从零上线 AI Agent：Docker Compose 一键部署实战指南

发布人：慈云数据-客服中心发布时间：22小时前阅读量：4

AI Agent 部署完整教程｜一键部署

随着大模型能力的快速提升，AI Agent 已经从“聊天机器人”逐渐演变为可以执行任务、调用工具、检索知识库、自动规划流程的智能应用。无论是企业内部知识助手、客服机器人、自动化办公助手，还是数据分析、代码生成、运维告警处理，AI Agent 都能在实际业务中发挥重要作用。

本文将以“快速上线一个可用的 AI Agent 服务”为目标，提供一套完整的部署教程。你可以通过 Docker Compose 实现一键部署，快速搭建一个包含 Web 服务、数据库、向量数据库、环境变量配置和反向代理的 AI Agent 运行环境。

说明：本文偏向通用型部署方案，适用于大多数 AI Agent 项目，例如基于 LangChain、LlamaIndex、Dify、FastAPI Agent、自研 Agent 框架等。如果你使用的是特定开源项目，也可以参考本文的部署思路进行调整。

一、AI Agent 是什么？

AI Agent 可以简单理解为“具备自主执行能力的 AI 应用”。传统的大模型聊天应用通常只负责回答用户问题，而 AI Agent 不仅能回答，还可以根据目标进行任务拆解、工具调用和结果反馈。

一个典型的 AI Agent 通常包含以下几个核心能力：

理解用户意图
能够识别用户输入的目标、约束条件和上下文信息。
任务规划
将复杂任务拆解为多个可执行步骤，例如搜索资料、读取文档、调用接口、生成报告等。
工具调用
可以调用搜索引擎、数据库、API、代码解释器、知识库、邮件系统等外部工具。
记忆能力
支持短期会话记忆和长期知识存储，提升连续对话体验。
结果反馈与迭代
根据执行结果继续调整策略，直到完成用户目标。

因此，部署 AI Agent 不只是部署一个聊天页面，还需要考虑模型服务、后端接口、数据库、向量检索、任务队列、安全认证、日志监控等多个部分。

二、部署前准备

在开始部署之前，需要准备一台服务器。推荐配置如下：

项目	推荐配置
操作系统	Ubuntu 20.04 / 22.04 / Debian 11+
CPU	2 核及以上
内存	4GB 起步，推荐 8GB+
磁盘	30GB 起步，推荐 50GB+
网络	可访问外网
部署方式	Docker + Docker Compose

如果你只是部署一个调用云端大模型 API 的 Agent，服务器配置不需要太高；如果你计划本地部署大模型，例如 Qwen、Llama、DeepSeek、Yi 等，则需要更高的 GPU 配置。

本文默认使用云端模型 API，例如 OpenAI、DeepSeek、通义千问、智谱、Claude 等。

三、整体部署架构

本文的部署架构如下：

用户浏览器
   │
   ▼
Nginx 反向代理
   │
   ▼
AI Agent Web/API 服务
   │
   ├── PostgreSQL 数据库
   ├── Redis 缓存/任务队列
   ├── 向量数据库 Milvus / Chroma / Qdrant
   └── 大模型 API

各模块作用如下：

Nginx：提供域名访问、HTTPS、反向代理。
AI Agent 后端服务：处理用户请求、调用大模型、执行 Agent 逻辑。
PostgreSQL：存储用户、会话、任务、配置等结构化数据。
Redis：用于缓存、异步任务队列、临时会话状态。
向量数据库：存储知识库文档向量，用于 RAG 检索增强。
大模型 API：作为 Agent 的核心推理能力来源。

四、安装 Docker 和 Docker Compose

如果你的服务器还没有安装 Docker，可以使用以下命令一键安装。

curl -fsSL https://get.docker.com | bash

安装完成后，启动 Docker：

systemctl enable docker
systemctl start docker

检查 Docker 是否安装成功：

docker -v

安装 Docker Compose：

sudo apt update
sudo apt install docker-compose-plugin -y

检查版本：

docker compose version

如果能够正常输出版本号，说明环境准备完成。

五、创建项目目录

在服务器中创建一个部署目录：

mkdir -p /opt/ai-agent
cd /opt/ai-agent

建议目录结构如下：

/opt/ai-agent
├── docker-compose.yml
├── .env
├── nginx
│   └── default.conf
├── data
│   ├── postgres
│   ├── redis
│   └── qdrant
└── logs

创建目录：

mkdir -p nginx data/postgres data/redis data/qdrant logs

六、编写环境变量配置

创建 .env 文件：

vim .env

写入以下内容：

# 基础配置
APP_NAME=AI-Agent
APP_ENV=production
APP_PORT=8000

# 域名配置
DOMAIN=agent.example.com

# 数据库配置
POSTGRES_DB=ai_agent
POSTGRES_USER=ai_agent_user
POSTGRES_PASSWORD=请修改为强密码
POSTGRES_HOST=postgres
POSTGRES_PORT=5432

# Redis 配置
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=请修改为强密码

# 向量数据库配置
QDRANT_HOST=qdrant
QDRANT_PORT=6333

# 大模型 API 配置
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-请替换为你的密钥
OPENAI_BASE_URL=https://api.openai.com/v1
MODEL_NAME=gpt-4o-mini

# 应用安全配置
JWT_SECRET=请修改为随机长字符串
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=请修改管理员密码

注意事项：

POSTGRES_PASSWORD、REDIS_PASSWORD、JWT_SECRET、ADMIN_PASSWORD 必须修改。
如果使用 DeepSeek，可以将配置改为：

LLM_PROVIDER=deepseek
OPENAI_API_KEY=sk-你的DeepSeek密钥
OPENAI_BASE_URL=https://api.deepseek.com
MODEL_NAME=deepseek-chat

如果使用通义千问或其他兼容 OpenAI API 的模型服务，也可以通过修改 OPENAI_BASE_URL 和 MODEL_NAME 适配。

七、编写 Docker Compose 文件

创建 docker-compose.yml：

vim docker-compose.yml

写入以下内容：

services:
  ai-agent:
    image: your-ai-agent-image:latest
    container_name: ai-agent
    restart: always
    env_file:
      - .env
    ports:
      - "8000:8000"
    volumes:
      - ./logs:/app/logs
    depends_on:
      - postgres
      - redis
      - qdrant
    networks:
      - ai-agent-net

  postgres:
    image: postgres:15
    container_name: ai-agent-postgres
    restart: always
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    networks:
      - ai-agent-net

  redis:
    image: redis:7
    container_name: ai-agent-redis
    restart: always
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - ./data/redis:/data
    ports:
      - "6379:6379"
    networks:
      - ai-agent-net

  qdrant:
    image: qdrant/qdrant:latest
    container_name: ai-agent-qdrant
    restart: always
    volumes:
      - ./data/qdrant:/qdrant/storage
    ports:
      - "6333:6333"
      - "6334:6334"
    networks:
      - ai-agent-net

networks:
  ai-agent-net:
    driver: bridge

这里的 your-ai-agent-image:latest 需要替换成你的 Agent 项目镜像。

如果你是自研项目，可以在项目根目录构建镜像：

docker build -t your-ai-agent-image:latest .

如果你使用开源项目，请参考对应项目的镜像名称，例如：

image: ghcr.io/example/ai-agent:latest

八、一键部署脚本

为了实现真正的一键部署，我们可以创建一个 deploy.sh 脚本。

vim deploy.sh

写入以下内容：

#!/bin/bash

set -e

echo "========== AI Agent 一键部署开始 =========="

cd /opt/ai-agent

echo "1. 检查 Docker 是否安装..."
if ! command -v docker &> /dev/null; then
  echo "未检测到 Docker，开始安装..."
  curl -fsSL https://get.docker.com | bash
  systemctl enable docker
  systemctl start docker
else
  echo "Docker 已安装"
fi

echo "2. 检查 Docker Compose 是否可用..."
if ! docker compose version &> /dev/null; then
  echo "未检测到 Docker Compose，开始安装..."
  apt update
  apt install docker-compose-plugin -y
else
  echo "Docker Compose 已可用"
fi

echo "3. 拉取镜像..."
docker compose pull || true

echo "4. 启动服务..."
docker compose up -d

echo "5. 查看服务状态..."
docker compose ps

echo "========== 部署完成 =========="
echo "请访问：http://服务器IP:8000"

赋予执行权限：

chmod +x deploy.sh

执行部署：

./deploy.sh

等待容器启动完成后，查看运行状态：

docker compose ps

如果所有服务状态都是 Up，说明部署成功。

九、配置 Nginx 反向代理

如果你希望通过域名访问，而不是使用 服务器IP:8000，可以配置 Nginx。

安装 Nginx：

apt update
apt install nginx -y

创建配置文件：

vim /etc/nginx/conf.d/ai-agent.conf

写入：

server {
    listen 80;
    server_name agent.example.com;

    client_max_body_size 50M;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

将 agent.example.com 替换为你的真实域名。

测试配置：

nginx -t

重载 Nginx：

systemctl reload nginx

此时可以通过：

http://agent.example.com

访问你的 AI Agent 服务。

十、配置 HTTPS 证书

生产环境强烈建议开启 HTTPS。可以使用 Certbot 免费申请 Let’s Encrypt 证书。

安装 Certbot：

apt install certbot python3-certbot-nginx -y

申请证书：

certbot --nginx -d agent.example.com

根据提示输入邮箱并同意协议即可。

证书申请成功后，Certbot 会自动修改 Nginx 配置，并开启 HTTPS。

测试自动续期：

certbot renew --dry-run

如果没有报错，说明证书自动续期正常。

十一、初始化数据库

部分 AI Agent 项目首次启动后需要执行数据库迁移，例如：

docker exec -it ai-agent bash

进入容器后执行：

python manage.py migrate

或者：

alembic upgrade head

不同项目命令可能不同，常见命令包括：

npm run migrate
pnpm db:migrate
python -m app.migrate

如果项目支持自动初始化，启动容器后会自动完成表结构创建。

你可以通过查看日志确认：

docker logs -f ai-agent

当日志中出现类似内容时，说明后端服务已经成功运行：

Application startup complete
Server running on 0.0.0.0:8000

十二、配置知识库与 RAG 检索

AI Agent 的一个重要能力是基于知识库回答问题，也就是常见的 RAG。

RAG 的基本流程如下：

上传文档
  ↓
文档切分
  ↓
向量化
  ↓
存入向量数据库
  ↓
用户提问
  ↓
向量检索相关内容
  ↓
大模型结合上下文回答

常见支持上传的文档格式包括：

PDF
Word
Markdown
TXT
HTML
CSV
Excel

在部署完成后，你可以进入管理后台，创建知识库，并上传企业文档、产品手册、FAQ、接口文档等资料。

为了提升检索质量，建议：

文档内容尽量结构化
标题、段落、列表越清晰，切分效果越好。
避免上传重复文档
重复内容会影响检索结果质量。
合理设置切分长度
常见 chunk size 可以设置为 500～1000 tokens。
设置合适的 Top K
一般检索前 3～8 条相关内容即可。
使用质量较高的 Embedding 模型
中文场景建议选择支持中文效果较好的向量模型。

十三、Agent 工具调用配置

一个真正可用的 AI Agent 往往需要接入工具。常见工具包括：

工具类型	用途
搜索工具	联网搜索实时信息
数据库工具	查询业务数据
HTTP API	调用第三方接口
代码执行器	执行 Python 或数据分析
邮件工具	自动发送邮件
日历工具	创建日程
工单工具	创建客服或运维工单

例如你可以配置一个天气 API 工具：

{
  "name": "get_weather",
  "description": "查询指定城市的天气信息",
  "parameters": {
    "city": {
      "type": "string",
      "description": "城市名称，例如北京、上海、深圳"
    }
  },
  "endpoint": "https://api.example.com/weather"
}

在 Agent 执行过程中，大模型会根据用户意图判断是否需要调用工具。如果用户问“明天北京天气怎么样，并帮我安排出行建议”，Agent 可以先调用天气接口，再根据结果生成建议。

十四、常用运维命令

查看容器状态：

docker compose ps

查看日志：

docker logs -f ai-agent

重启服务：

docker compose restart

停止服务：

docker compose down

更新服务：

docker compose pull
docker compose up -d

进入容器：

docker exec -it ai-agent bash

查看资源占用：

docker stats

备份数据库：

docker exec ai-agent-postgres pg_dump -U ai_agent_user ai_agent > backup.sql

恢复数据库：

cat backup.sql | docker exec -i ai-agent-postgres psql -U ai_agent_user ai_agent

十五、安全配置建议

生产环境部署 AI Agent 时，安全非常重要，尤其是当 Agent 可以调用工具和访问数据库时。

建议至少完成以下配置：

修改默认密码
管理员密码、数据库密码、Redis 密码都必须使用强密码。
限制数据库端口暴露
如果 PostgreSQL 和 Redis 只在 Docker 内部访问，可以不要映射到公网端口。
开启 HTTPS
防止登录信息和 API Key 明文传输。
限制后台访问 IP
企业内部使用时，可以通过 Nginx 限制管理后台访问来源。
保护 API Key
不要将大模型 API Key 写入前端代码，也不要提交到 Git 仓库。
开启日志审计
记录用户请求、工具调用、异常错误，方便追踪问题。
设置工具调用权限
对高风险工具，例如发送邮件、执行代码、删除数据等，应加入人工确认机制。
限制文件上传类型和大小
防止恶意文件上传和资源耗尽。

十六、性能优化建议

如果访问量逐渐增加，可以从以下方向优化：

1. 增加后端实例

可以将 ai-agent 服务扩展为多个实例：

docker compose up -d --scale ai-agent=3

然后通过 Nginx 做负载均衡。

2. 使用异步任务队列

长耗时任务，例如文档向量化、批量总结、数据分析，应放入异步队列执行，避免阻塞主接口。

3. 优化知识库检索

可以调整向量数据库索引参数、Top K、相似度阈值，减少无效上下文。

4. 缓存高频问题

对于重复问题，可以使用 Redis 缓存结果，降低大模型调用成本。

5. 控制上下文长度

上下文越长，模型调用成本越高，响应速度越慢。应合理截断历史对话和知识库内容。

十七、常见问题排查

1. 页面无法访问

检查服务是否启动：

docker compose ps

检查端口是否监听：

ss -tunlp | grep 8000

检查防火墙是否放行：

ufw allow 8000
ufw allow 80
ufw allow 443

2. 大模型接口调用失败

检查 .env 中的配置：

OPENAI_API_KEY
OPENAI_BASE_URL
MODEL_NAME

同时查看日志：

docker logs -f ai-agent

常见原因包括 API Key 错误、模型名称不正确、接口地址不兼容、账户额度不足等。

3. 知识库上传失败

可能原因：

文件过大；
文件格式不支持；
向量数据库未启动；
Embedding 模型配置错误；
后端没有文件写入权限。

检查 Qdrant 状态：

docker logs -f ai-agent-qdrant

4. Redis 连接失败

检查 Redis 密码是否一致：

docker logs -f ai-agent-redis

如果后端报错 NOAUTH Authentication required，说明 Redis 需要密码但应用没有正确传入密码。

5. 数据库连接失败

检查 PostgreSQL 容器状态：

docker logs -f ai-agent-postgres

确认 .env 中数据库用户名、密码、库名与 docker-compose.yml 一致。

十八、推荐上线流程

为了保证部署稳定，建议按照以下流程上线：

本地或测试服务器先完成部署；
配置大模型 API Key；
创建管理员账号；
上传测试知识库；
测试多轮对话；
测试工具调用；
配置域名和 HTTPS；
开启日志和监控；
修改默认密码；
正式开放给用户使用。

十九、总结

本文介绍了 AI Agent 的完整部署流程，包括服务器准备、Docker 安装、环境变量配置、Docker Compose 编排、一键部署脚本、Nginx 反向代理、HTTPS 配置、数据库初始化、知识库 RAG、工具调用、安全加固和常见问题排查。

如果你只是想快速体验 AI Agent，可以直接使用 Docker Compose 启动服务；如果你计划在企业生产环境中使用，则需要重点关注权限控制、日志审计、数据安全、API Key 管理和服务稳定性。

AI Agent 的核心价值不只是“会聊天”，而是能够连接业务系统、理解任务目标并自动完成流程。部署只是第一步，真正决定效果的是后续的知识库建设、工具链设计、Prompt 优化和业务流程集成。

通过本文的方案，你已经可以快速搭建一个基础可用的 AI Agent 平台，并在此基础上继续扩展更多能力，例如企业知识问答、智能客服、自动数据分析、自动工单处理、代码助手和办公自动化助手等。

文章标签： AIAgent DockerCompose 一键部署 RAG检索

上一篇：从 Demo 到生产：2026 年 AI Agent 落地部署实战指南

下一篇：企业落地 AI Agent：从试点到上线的完整部署指南

更多栏目

新闻动态

文档中心

下载中心

目录结构

全文

产品与服务

新闻帮助

生态合作

了解我们

从零上线 AI Agent：Docker Compose 一键部署实战指南

AI Agent 部署完整教程｜一键部署

一、AI Agent 是什么？

二、部署前准备

三、整体部署架构

四、安装 Docker 和 Docker Compose

五、创建项目目录

六、编写环境变量配置

七、编写 Docker Compose 文件

八、一键部署脚本

九、配置 Nginx 反向代理

十、配置 HTTPS 证书

十一、初始化数据库

十二、配置知识库与 RAG 检索

十三、Agent 工具调用配置

十四、常用运维命令

十五、安全配置建议

十六、性能优化建议

1. 增加后端实例

2. 使用异步任务队列

3. 优化知识库检索

4. 缓存高频问题

5. 控制上下文长度

十七、常见问题排查

1. 页面无法访问

2. 大模型接口调用失败

3. 知识库上传失败

4. Redis 连接失败

5. 数据库连接失败

十八、推荐上线流程

十九、总结