AI Agent Docker部署教程｜附配置文件

随着大模型能力的快速发展，越来越多团队开始将 AI Agent（智能体） 引入到业务系统中，用于自动问答、知识库检索、任务规划、数据分析、代码生成、流程自动化等场景。相比普通的聊天机器人，AI Agent 通常具备更强的工具调用能力、记忆能力、任务拆解能力以及多轮执行能力，因此在实际生产环境中，稳定部署和可维护运维就显得尤为重要。

本文将以一个通用的 AI Agent 服务为例，讲解如何使用 Docker + Docker Compose 完成部署，并提供完整的配置文件示例。你可以根据自己的项目框架进行适配，例如 LangChain、LlamaIndex、AutoGen、CrewAI、自研 Agent 服务，或基于 FastAPI / Flask / Node.js 构建的 AI Agent 后端。

一、为什么推荐使用 Docker 部署 AI Agent？

AI Agent 项目通常依赖较多组件，例如：

• Python / Node.js 运行环境
• 大模型 API Key
• 向量数据库
• Redis 缓存
• PostgreSQL / MySQL 数据库
• Embedding 模型
• 任务队列
• 文件存储
• 日志系统
• Web 后端服务
• 前端管理页面

如果直接在服务器裸机上安装依赖，往往会遇到以下问题：

1. 环境不一致
   本地可以运行，服务器无法运行，常见原因包括 Python 版本不同、依赖库冲突、系统包缺失等。

2. 部署复杂
   每次上线都需要手动安装依赖、修改配置、重启服务，容易出错。

3. 迁移困难
   从一台服务器迁移到另一台服务器时，需要重新配置环境。

4. 不利于扩展
   后续如果要增加 Redis、数据库、向量库等服务，维护成本会越来越高。

使用 Docker 后，可以将 AI Agent 应用及其运行环境打包成镜像，通过配置文件统一管理，做到：

• 一键启动
• 环境隔离
• 快速迁移
• 易于扩容
• 便于回滚
• 方便接入 CI/CD

二、部署架构说明

本文示例采用如下架构：

用户浏览器 / 第三方系统
        │
        ▼
    Nginx 反向代理
        │
        ▼
 AI Agent API 服务
        │
 ┌──────┼────────┐
 ▼      ▼        ▼
Redis  PostgreSQL 向量数据库

各组件作用如下：

本文为了便于演示，向量数据库使用 Qdrant。如果你使用 Milvus、Weaviate、Chroma，也可以按照类似方式替换。

三、服务器环境准备

1. 推荐服务器配置

如果你的 AI Agent 主要通过 OpenAI、Claude、通义千问、智谱、DeepSeek 等云端模型 API 运行，不在本地部署大模型，那么服务器配置要求并不高。

推荐配置：

如果你要本地部署大模型，例如 Qwen、Llama、DeepSeek-R1 Distill 等，则需要 GPU 服务器，配置取决于模型大小。

2. 安装 Docker

以 Ubuntu 为例：

sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release

添加 Docker 官方 GPG Key：

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

添加 Docker 软件源：

echo \
  "deb [arch=$(dpkg --print-architecture) \
  signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" \
  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

安装 Docker：

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

检查版本：

docker version
docker compose version

如果希望当前用户不用每次执行 sudo，可以执行：

sudo usermod -aG docker $USER

然后重新登录服务器。

四、项目目录结构

建议在服务器上创建如下目录：

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

项目结构如下：

/opt/ai-agent
├── docker-compose.yml
├── Dockerfile
├── .env
├── requirements.txt
├── app
│   ├── main.py
│   ├── agent.py
│   ├── config.py
│   └── tools
│       └── search_tool.py
├── nginx
│   └── default.conf
└── data
    ├── postgres
    ├── redis
    └── qdrant

说明：

五、编写 AI Agent 示例服务

下面提供一个简化版的 AI Agent 后端服务示例，基于 FastAPI 构建。真实业务中，你可以将这里的 Agent 逻辑替换为 LangChain、LlamaIndex、AutoGen、CrewAI 或自研 Agent 框架。

1. requirements.txt

fastapi==0.115.6
uvicorn[standard]==0.34.0
pydantic==2.10.4
pydantic-settings==2.7.1
openai==1.58.1
redis==5.2.1
psycopg2-binary==2.9.10
qdrant-client==1.12.1
python-dotenv==1.0.1

2. app/config.py

from pydantic_settings import BaseSettings


class Settings(BaseSettings):
    app_name: str = "AI Agent Service"
    app_env: str = "production"
    api_key: str

    openai_api_key: str
    openai_base_url: str = "https://api.openai.com/v1"
    model_name: str = "gpt-4o-mini"

    redis_host: str = "redis"
    redis_port: int = 6379
    redis_password: str | None = None

    postgres_host: str = "postgres"
    postgres_port: int = 5432
    postgres_db: str = "ai_agent"
    postgres_user: str = "ai_agent"
    postgres_password: str = "change_me"

    qdrant_host: str = "qdrant"
    qdrant_port: int = 6333

    class Config:
        env_file = ".env"


settings = Settings()

3. app/agent.py

from openai import OpenAI
from app.config import settings


class SimpleAgent:
    def __init__(self):
        self.client = OpenAI(
            api_key=settings.openai_api_key,
            base_url=settings.openai_base_url,
        )

    def run(self, user_input: str) -> str:
        system_prompt = """
你是一个企业级AI Agent助手。
你需要准确理解用户需求，并给出结构化、可执行的回答。
如果用户问题涉及步骤、方案或排查，请优先使用列表形式。
"""

        response = self.client.chat.completions.create(
            model=settings.model_name,
            messages=[
                {"role": "system", "content": system_prompt},
                {"role": "user", "content": user_input},
            ],
            temperature=0.3,
        )

        return response.choices[0].message.content

4. app/main.py

from fastapi import FastAPI, Header, HTTPException
from pydantic import BaseModel
from app.agent import SimpleAgent
from app.config import settings


app = FastAPI(title=settings.app_name)

agent = SimpleAgent()


class ChatRequest(BaseModel):
    message: str


class ChatResponse(BaseModel):
    reply: str


@app.get("/health")
def health_check():
    return {
        "status": "ok",
        "service": settings.app_name,
        "env": settings.app_env,
    }


@app.post("/api/chat", response_model=ChatResponse)
def chat(request: ChatRequest, x_api_key: str = Header(default="")):
    if x_api_key != settings.api_key:
        raise HTTPException(status_code=401, detail="Invalid API Key")

    reply = agent.run(request.message)

    return ChatResponse(reply=reply)

六、编写 Dockerfile

在项目根目录创建 Dockerfile：

FROM python:3.11-slim

WORKDIR /app

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

RUN apt-get update \
    && apt-get install -y --no-install-recommends \
       gcc \
       libpq-dev \
       curl \
    && rm -rf /var/lib/apt/lists/*

COPY requirements.txt /app/requirements.txt

RUN pip install --no-cache-dir -r requirements.txt

COPY app /app/app

EXPOSE 8000

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

这个 Dockerfile 做了以下事情：

1. 使用 python:3.11-slim 作为基础镜像；
2. 设置工作目录 /app；
3. 安装 PostgreSQL 相关依赖；
4. 安装 Python 依赖；
5. 复制后端代码；
6. 暴露 8000 端口；
7. 使用 uvicorn 启动 FastAPI 服务。

七、编写环境变量配置文件

在项目根目录创建 .env 文件：

APP_NAME=AI Agent Service
APP_ENV=production

API_KEY=please_change_this_api_key

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_BASE_URL=https://api.openai.com/v1
MODEL_NAME=gpt-4o-mini

REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=redis_password_change_me

POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=ai_agent
POSTGRES_USER=ai_agent
POSTGRES_PASSWORD=postgres_password_change_me

QDRANT_HOST=qdrant
QDRANT_PORT=6333

需要注意：

• API_KEY 是你自己服务的访问密钥，用于保护 /api/chat 接口；
• OPENAI_API_KEY 是大模型服务商提供的密钥；
• 如果你使用的是国内大模型厂商，只需要替换 OPENAI_BASE_URL 和 MODEL_NAME；
• 生产环境不要把 .env 上传到公开代码仓库。

例如，如果使用兼容 OpenAI API 格式的模型服务，可以这样配置：

OPENAI_BASE_URL=https://api.example.com/v1
MODEL_NAME=deepseek-chat

八、编写 Docker Compose 配置文件

创建 docker-compose.yml：

services:
  ai-agent:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: ai-agent-api
    restart: always
    env_file:
      - .env
    depends_on:
      - redis
      - postgres
      - qdrant
    ports:
      - "8000:8000"
    networks:
      - ai-agent-net

  redis:
    image: redis:7.4-alpine
    container_name: ai-agent-redis
    restart: always
    command: >
      redis-server
      --requirepass ${REDIS_PASSWORD}
      --appendonly yes
    volumes:
      - ./data/redis:/data
    networks:
      - ai-agent-net

  postgres:
    image: postgres:16-alpine
    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
    networks:
      - ai-agent-net

  qdrant:
    image: qdrant/qdrant:v1.12.4
    container_name: ai-agent-qdrant
    restart: always
    volumes:
      - ./data/qdrant:/qdrant/storage
    networks:
      - ai-agent-net

  nginx:
    image: nginx:1.27-alpine
    container_name: ai-agent-nginx
    restart: always
    depends_on:
      - ai-agent
    ports:
      - "80:80"
    volumes:
      - ./nginx/default.conf:/etc/nginx/conf.d/default.conf
    networks:
      - ai-agent-net

networks:
  ai-agent-net:
    driver: bridge

该配置包含五个服务：

1. ai-agent：智能体后端 API；
2. redis：缓存服务；
3. postgres：关系型数据库；
4. qdrant：向量数据库；
5. nginx：反向代理服务。

九、编写 Nginx 配置文件

创建目录：

mkdir -p nginx

创建 nginx/default.conf：

server {
    listen 80;
    server_name your-domain.com;

    client_max_body_size 20M;

    location / {
        proxy_pass http://ai-agent: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_connect_timeout 60s;
        proxy_send_timeout 120s;
        proxy_read_timeout 120s;
    }
}

如果你暂时没有域名，可以把：

server_name your-domain.com;

改成：

server_name _;

然后通过服务器 IP 访问。

十、启动服务

在项目根目录执行：

docker compose up -d --build

查看容器状态：

docker compose ps

正常情况下，你会看到类似输出：

NAME                  STATUS
ai-agent-api          Up
ai-agent-redis        Up
ai-agent-postgres     Up
ai-agent-qdrant       Up
ai-agent-nginx        Up

查看日志：

docker compose logs -f ai-agent

如果启动成功，通常可以看到 Uvicorn 相关日志：

Uvicorn running on http://0.0.0.0:8000

十一、测试接口

1. 健康检查

curl http://服务器IP/health

返回示例：

{
  "status": "ok",
  "service": "AI Agent Service",
  "env": "production"
}

2. 测试聊天接口

curl -X POST http://服务器IP/api/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: please_change_this_api_key" \
  -d '{"message":"请帮我制定一个AI Agent项目部署方案"}'

返回示例：

{
  "reply": "下面是一个AI Agent项目部署方案：..."
}

如果返回 401 Unauthorized，说明请求头中的 X-API-Key 与 .env 中配置的 API_KEY 不一致。

十二、配置 HTTPS 证书

生产环境建议启用 HTTPS。你可以使用 Certbot 申请免费 Let’s Encrypt 证书，也可以使用云厂商证书。

如果使用宿主机 Certbot，可以先安装：

sudo apt install -y certbot

申请证书：

sudo certbot certonly --standalone -d your-domain.com

证书通常位于：

/etc/letsencrypt/live/your-domain.com/fullchain.pem
/etc/letsencrypt/live/your-domain.com/privkey.pem

然后修改 docker-compose.yml 中 Nginx 服务，挂载证书目录：

nginx:
  image: nginx:1.27-alpine
  container_name: ai-agent-nginx
  restart: always
  depends_on:
    - ai-agent
  ports:
    - "80:80"
    - "443:443"
  volumes:
    - ./nginx/default.conf:/etc/nginx/conf.d/default.conf
    - /etc/letsencrypt:/etc/letsencrypt:ro
  networks:
    - ai-agent-net

修改 nginx/default.conf：

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    client_max_body_size 20M;

    location / {
        proxy_pass http://ai-agent: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_connect_timeout 60s;
        proxy_send_timeout 120s;
        proxy_read_timeout 120s;
    }
}

重启 Nginx：

docker compose restart nginx

十三、接入知识库与向量数据库

AI Agent 的一个常见能力是 RAG，即检索增强生成。它通常包括：

1. 上传文档；
2. 文档切分；
3. 调用 Embedding 模型生成向量；
4. 写入向量数据库；
5. 用户提问时检索相关片段；
6. 将检索结果与用户问题一起发送给大模型；
7. 生成更准确的回答。

本文示例中已经部署了 Qdrant，你可以在代码中连接它：

from qdrant_client import QdrantClient
from app.config import settings


client = QdrantClient(
    host=settings.qdrant_host,
    port=settings.qdrant_port,
)

创建 collection 示例：

client.recreate_collection(
    collection_name="knowledge_base",
    vectors_config={
        "size": 1536,
        "distance": "Cosine"
    }
)

这里的 size 要与你使用的 Embedding 模型维度一致。例如：

如果维度配置错误，写入向量时会报错。

十四、常见运维命令

1. 启动服务

docker compose up -d

2. 停止服务

docker compose down

3. 重启服务

docker compose restart

4. 重建镜像并启动

docker compose up -d --build

5. 查看所有服务日志

docker compose logs -f

6. 查看某个服务日志

docker compose logs -f ai-agent

7. 进入容器

docker exec -it ai-agent-api sh

8. 查看资源占用

docker stats

9. 清理无用镜像

docker image prune -f

10. 清理未使用资源

docker system prune -f

注意：不要随意删除数据卷或持久化目录，否则可能造成数据库数据丢失。

十五、生产环境安全建议

AI Agent 服务往往会接触用户数据、业务数据甚至内部系统，因此安全配置非常重要。

1. 不要暴露内部服务端口

生产环境中，Redis、PostgreSQL、Qdrant 不建议映射到公网端口。本文的 docker-compose.yml 中，这些服务没有配置 ports，只在 Docker 内部网络中访问，这是比较安全的做法。

2. 使用强密码

.env 中的以下字段应使用强密码：

API_KEY=
REDIS_PASSWORD=
POSTGRES_PASSWORD=
OPENAI_API_KEY=

建议使用至少 24 位随机字符串。

3. 配置防火墙

只开放必要端口：

sudo ufw allow 22
sudo ufw allow 80
sudo ufw allow 443
sudo ufw enable

4. 限制接口访问频率

可以在 Nginx 层增加限流配置，防止恶意请求或成本失控：

limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;

server {
    listen 80;
    server_name your-domain.com;

    location / {
        limit_req zone=api_limit burst=20 nodelay;
        proxy_pass http://ai-agent:8000;
    }
}

5. 做好日志脱敏

不要在日志中直接打印：

• API Key
• 用户隐私数据
• 身份证、手机号、邮箱
• 内部数据库连接串
• 大模型完整请求上下文

6. 控制 Agent 工具权限

如果你的 AI Agent 可以调用工具，例如执行 SQL、访问内部 API、操作文件、运行脚本，那么一定要做好权限边界。不要让 Agent 直接拥有过高权限，否则可能带来安全风险。

十六、常见问题排查

1. 容器启动失败

查看日志：

docker compose logs -f ai-agent

常见原因包括：

• .env 配置缺失；
• Python 依赖安装失败；
• API Key 未配置；
• 端口被占用；
• Dockerfile 路径错误。

2. 请求接口无响应

排查步骤：

docker compose ps
curl http://127.0.0.1:8000/health
curl http://127.0.0.1/health

如果 8000 可以访问但 80 不能访问，通常是 Nginx 配置问题。

3. 大模型调用失败

常见错误：

• API Key 错误；
• Base URL 错误；
• 模型名称不存在；
• 账户余额不足；
• 网络无法访问模型服务商；
• 请求超时。

可以进入容器测试网络：

docker exec -it ai-agent-api sh
curl https://api.openai.com/v1/models

4. Redis 连接失败

检查 Redis 是否启动：

docker compose ps redis
docker compose logs -f redis

如果 Redis 设置了密码，代码连接时也必须传入密码。

5. PostgreSQL 数据丢失

请检查是否正确挂载了持久化目录：

volumes:
  - ./data/postgres:/var/lib/postgresql/data

如果使用 docker compose down -v，会删除匿名卷，可能导致数据丢失。生产环境慎用。

十七、如何更新 AI Agent 服务

当你修改了代码后，可以执行：

docker compose up -d --build ai-agent

如果只修改了 .env，可以执行：

docker compose up -d
docker compose restart ai-agent

如果修改了 Nginx 配置：

docker compose restart nginx

建议上线前先查看日志：

docker compose logs -f ai-agent

确认无异常后再对外提供服务。

十八、备份与恢复建议

1. 备份 PostgreSQL

docker exec -t ai-agent-postgres pg_dump \
  -U ai_agent \
  ai_agent > backup_ai_agent.sql

恢复：

cat backup_ai_agent.sql | docker exec -i ai-agent-postgres psql \
  -U ai_agent \
  ai_agent

2. 备份 Qdrant 数据

由于本文将 Qdrant 数据挂载到了：

./data/qdrant

可以直接备份该目录：

tar -czvf qdrant_backup.tar.gz ./data/qdrant

3. 备份配置文件

建议备份：

.env
docker-compose.yml
nginx/default.conf

其中 .env 包含敏感信息，备份时应加密保存。

十九、进一步优化方向

当 AI Agent 服务进入生产阶段后，可以继续优化以下方面：

1. 增加流式输出
   使用 SSE 或 WebSocket，让用户更快看到模型响应。

2. 增加任务队列
   对于长任务，可以使用 Celery、RQ、Dramatiq 等队列框架。

3. 增加监控系统
   使用 Prometheus、Grafana、Loki 监控服务状态和日志。

4. 增加多模型路由
   根据任务类型自动选择不同模型，例如简单任务用低成本模型，复杂任务用高能力模型。

5. 增加成本控制
   记录每次调用的 token 用量，按用户、部门或项目统计成本。

6. 增加权限系统
   对不同用户开放不同 Agent、工具和知识库权限。

7. 增加灰度发布
   新版本先给部分用户使用，确认稳定后再全量上线。

8. 增加高可用部署
   将数据库、Redis、应用服务拆分部署，结合负载均衡提升可用性。

二十、总结

本文完整介绍了如何使用 Docker 部署一个 AI Agent 服务，并提供了包括 Dockerfile、docker-compose.yml、.env、Nginx、FastAPI 示例代码在内的配置文件。通过 Docker Compose，我们可以把 AI Agent API、Redis、PostgreSQL、Qdrant、Nginx 等组件统一编排起来，实现快速部署和稳定运行。

对于中小型项目来说，本文这套方案已经可以满足大多数测试环境和初期生产环境需求。如果后续业务规模扩大，可以在此基础上进一步引入 HTTPS、监控、日志、任务队列、权限系统、CI/CD、高可用架构等能力。

最后需要强调的是，AI Agent 不只是一个普通接口服务，它可能会连接知识库、数据库、内部系统甚至自动化工具。因此在部署时除了关注“能不能跑起来”，更要关注安全、权限、日志、成本和稳定性。只有把这些基础设施做好，AI Agent 才能真正可靠地服务于实际业务。