从本地 Demo 到服务器上线：用 Docker 部署一个可运行的 AI Agent 实战指南

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

AI Agent Docker部署教程｜附源码

随着大模型应用的快速发展，越来越多团队开始从“单次问答式 ChatBot”转向“可调用工具、可执行任务、可持续运行”的 AI Agent。AI Agent 不只是回答问题，它还可以根据用户目标进行规划、调用工具、访问数据库、执行脚本、读取文件、对接业务系统，甚至完成自动化流程。

不过，很多人在本地跑通 Agent Demo 后，真正部署到服务器时就会遇到一系列问题：

Python 环境依赖冲突；
不同服务器环境不一致；
API Key 配置不安全；
服务重启后 Agent 无法自动恢复；
多个服务之间，例如 Redis、数据库、向量库、Agent 服务不好管理；
代码更新后部署流程繁琐。

因此，使用 Docker 来部署 AI Agent 是非常推荐的方式。本文将从零开始，完整演示如何构建一个简单可运行的 AI Agent 服务，并使用 Docker 与 Docker Compose 完成部署。

本文包含：

AI Agent 项目结构设计；
FastAPI 后端服务；
Agent 核心逻辑源码；
Dockerfile 编写；
docker-compose.yml 编写；
环境变量配置；
本地运行与服务器部署；
常见问题排查；
生产环境优化建议。

一、什么是 AI Agent？

AI Agent 可以简单理解为一个具备“自主决策能力”的 AI 程序。传统的大模型应用通常是：

用户输入问题 → 模型生成回答 → 返回结果

而 Agent 的工作方式更接近：

用户提出目标 → Agent 分析任务 → 制定步骤 → 调用工具 → 获取结果 → 继续推理 → 最终完成任务

例如用户输入：

帮我查询今天北京天气，并根据天气给我一份出门建议。

普通 ChatBot 可能只能根据已有知识猜测，而 AI Agent 可以调用天气 API，获取实时数据后再生成建议。

一个典型 AI Agent 通常包含以下组件：

组件	作用
LLM	大语言模型，负责理解、推理和生成
Tools	工具，例如搜索、天气、数据库、文件读写等
Memory	记忆模块，用于保存上下文或历史状态
Planner	规划模块，用于拆解任务
Executor	执行模块，用于调用工具完成任务
API Server	对外提供 HTTP 接口

本文为了便于理解，不引入过多复杂框架，而是使用 Python + FastAPI + OpenAI兼容接口 + Docker 实现一个轻量级 AI Agent。

二、项目最终效果

我们最终会部署一个 HTTP 服务，用户可以通过接口向 Agent 发送任务，例如：

curl -X POST http://localhost:8000/agent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "请帮我计算 12 * 8，然后给出一句学习建议"}'

服务返回：

{
  "reply": "12 * 8 = 96。学习建议：每天保持稳定输入和复盘，比短时间突击更有效。"
}

这个 Agent 具备以下能力：

接收用户输入；
判断是否需要调用工具；
支持计算器工具；
调用大模型生成最终回答；
通过 Docker 容器化部署；
通过 Docker Compose 管理服务。

三、项目目录结构

建议创建如下项目结构：

ai-agent-docker-demo/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── agent.py
│   ├── tools.py
│   └── config.py
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md

各文件作用如下：

文件	说明
`app/main.py`	FastAPI 服务入口
`app/agent.py`	Agent 核心逻辑
`app/tools.py`	工具函数，例如计算器
`app/config.py`	环境变量配置
`requirements.txt`	Python 依赖
`Dockerfile`	构建 Docker 镜像
`docker-compose.yml`	编排运行服务
`.env.example`	环境变量示例
`README.md`	项目说明文档

四、核心源码实现

下面开始编写代码。

1. 安装依赖文件 requirements.txt

在项目根目录创建 requirements.txt：

fastapi==0.115.0
uvicorn[standard]==0.30.6
pydantic==2.8.2
python-dotenv==1.0.1
openai==1.43.0

这里我们使用 OpenAI Python SDK。需要说明的是，现在很多大模型服务商都提供 OpenAI 兼容接口，例如：

OpenAI；
Azure OpenAI；
通义千问兼容接口；
DeepSeek；
智谱；
Moonshot；
本地 Ollama 的 OpenAI 兼容接口；
vLLM 部署的本地模型服务。

因此，只要接口兼容，修改 OPENAI_BASE_URL 和 OPENAI_API_KEY 即可。

2. 配置文件 app/config.py

import os
from dotenv import load_dotenv

load_dotenv()


class Settings:
    OPENAI_API_KEY: str = os.getenv("OPENAI_API_KEY", "")
    OPENAI_BASE_URL: str = os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
    OPENAI_MODEL: str = os.getenv("OPENAI_MODEL", "gpt-4o-mini")

    APP_HOST: str = os.getenv("APP_HOST", "0.0.0.0")
    APP_PORT: int = int(os.getenv("APP_PORT", "8000"))

    AGENT_SYSTEM_PROMPT: str = os.getenv(
        "AGENT_SYSTEM_PROMPT",
        "你是一个严谨、可靠的AI Agent。你可以根据用户问题进行分析，并在需要时使用工具。"
    )


settings = Settings()

这个文件用于集中读取环境变量，避免在代码里硬编码密钥。

生产环境中，API Key 一定不要直接写在代码里，也不要提交到 Git 仓库。

3. 工具模块 app/tools.py

为了演示 Agent 调用工具，我们先实现一个简单计算器工具。

import ast
import operator


class SafeCalculator:
    """
    一个简单的安全计算器，只允许基本数学运算。
    避免直接使用 eval 带来的安全风险。
    """

    operators = {
        ast.Add: operator.add,
        ast.Sub: operator.sub,
        ast.Mult: operator.mul,
        ast.Div: operator.truediv,
        ast.Pow: operator.pow,
        ast.USub: operator.neg,
    }

    def calculate(self, expression: str):
        try:
            node = ast.parse(expression, mode="eval").body
            return self._eval(node)
        except Exception as e:
            raise ValueError(f"计算表达式不合法: {expression}") from e

    def _eval(self, node):
        if isinstance(node, ast.Constant):
            if isinstance(node.value, (int, float)):
                return node.value
            raise ValueError("只支持数字")

        if isinstance(node, ast.BinOp):
            left = self._eval(node.left)
            right = self._eval(node.right)
            op_type = type(node.op)

            if op_type not in self.operators:
                raise ValueError("不支持该运算符")

            return self.operators[op_type](left, right)

        if isinstance(node, ast.UnaryOp):
            operand = self._eval(node.operand)
            op_type = type(node.op)

            if op_type not in self.operators:
                raise ValueError("不支持该一元运算符")

            return self.operators[op_type](operand)

        raise ValueError("表达式包含不允许的内容")


calculator = SafeCalculator()


def run_tool(tool_name: str, tool_input: str):
    """
    根据工具名称执行对应工具。
    后续可以在这里扩展更多工具，例如天气、搜索、数据库查询等。
    """
    if tool_name == "calculator":
        return calculator.calculate(tool_input)

    raise ValueError(f"未知工具: {tool_name}")

这里没有使用 Python 的 eval，而是通过 ast 语法树解析表达式，只允许基本数学运算。这样可以避免用户输入恶意代码。

例如，下面这种危险输入不会被执行：

__import__("os").system("rm -rf /")

4. Agent 核心逻辑 app/agent.py

接下来实现 Agent。为了让逻辑清晰，我们将 Agent 分成三步：

判断用户请求是否需要工具；
如果需要工具，则提取工具名称和工具参数；
将工具结果和用户问题一起交给大模型生成最终回答。

import json
from openai import OpenAI

from app.config import settings
from app.tools import run_tool


class SimpleAgent:
    def __init__(self):
        if not settings.OPENAI_API_KEY:
            raise RuntimeError("缺少 OPENAI_API_KEY，请检查环境变量配置")

        self.client = OpenAI(
            api_key=settings.OPENAI_API_KEY,
            base_url=settings.OPENAI_BASE_URL,
        )

    def chat(self, message: str) -> str:
        """
        Agent主入口。
        """
        tool_plan = self._plan_tool(message)

        if tool_plan.get("use_tool") is True:
            tool_name = tool_plan.get("tool_name")
            tool_input = tool_plan.get("tool_input")

            try:
                tool_result = run_tool(tool_name, tool_input)
            except Exception as e:
                tool_result = f"工具执行失败: {str(e)}"

            return self._final_answer(
                user_message=message,
                tool_name=tool_name,
                tool_input=tool_input,
                tool_result=str(tool_result),
            )

        return self._llm_answer(message)

    def _plan_tool(self, message: str) -> dict:
        """
        判断是否需要调用工具。
        这里使用大模型做工具规划。
        """
        prompt = f"""
你是一个AI Agent的工具规划器。

当前可用工具：
1. calculator
   - 用途：执行数学计算
   - 输入：数学表达式，例如 "12*8+3"

请判断用户问题是否需要调用工具。
如果需要，请返回严格JSON格式：
{{
  "use_tool": true,
  "tool_name": "calculator",
  "tool_input": "表达式"
}}

如果不需要，请返回严格JSON格式：
{{
  "use_tool": false
}}

用户问题：
{message}
"""

        response = self.client.chat.completions.create(
            model=settings.OPENAI_MODEL,
            messages=[
                {"role": "system", "content": "你只返回JSON，不要输出多余内容。"},
                {"role": "user", "content": prompt},
            ],
            temperature=0,
        )

        content = response.choices[0].message.content.strip()

        try:
            return json.loads(content)
        except Exception:
            return {"use_tool": False}

    def _final_answer(
        self,
        user_message: str,
        tool_name: str,
        tool_input: str,
        tool_result: str,
    ) -> str:
        """
        基于工具结果生成最终回答。
        """
        prompt = f"""
用户问题：
{user_message}

你已经调用了工具：
工具名称：{tool_name}
工具输入：{tool_input}
工具结果：{tool_result}

请结合工具结果，给用户一个自然、准确、简洁的回答。
"""

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

        return response.choices[0].message.content

    def _llm_answer(self, message: str) -> str:
        """
        不需要工具时，直接调用大模型回答。
        """
        response = self.client.chat.completions.create(
            model=settings.OPENAI_MODEL,
            messages=[
                {"role": "system", "content": settings.AGENT_SYSTEM_PROMPT},
                {"role": "user", "content": message},
            ],
            temperature=0.7,
        )

        return response.choices[0].message.content

这个 Agent 还比较简单，但已经具备了 Agent 的基本形态：

可以理解用户意图；
可以判断是否需要工具；
可以调用外部工具；
可以根据工具结果生成回答。

如果你后续想扩展，可以加入更多工具，例如：

天气查询；
Web 搜索；
SQL 查询；
文件总结；
知识库检索；
邮件发送；
自动创建工单；
调用企业内部接口。

5. FastAPI 服务入口 app/main.py

下面我们写 HTTP 接口：

from fastapi import FastAPI
from pydantic import BaseModel

from app.agent import SimpleAgent


app = FastAPI(
    title="AI Agent Docker Demo",
    description="一个使用 FastAPI 和 Docker 部署的简单 AI Agent 示例",
    version="1.0.0",
)


class ChatRequest(BaseModel):
    message: str


class ChatResponse(BaseModel):
    reply: str


agent = SimpleAgent()


@app.get("/")
def root():
    return {
        "message": "AI Agent service is running",
        "docs": "/docs"
    }


@app.get("/health")
def health():
    return {
        "status": "ok"
    }


@app.post("/agent/chat", response_model=ChatResponse)
def chat(request: ChatRequest):
    reply = agent.chat(request.message)
    return ChatResponse(reply=reply)

启动后可以访问：

http://localhost:8000/docs

FastAPI 会自动生成 Swagger 文档，方便调试接口。

五、环境变量配置

在项目根目录创建 .env.example：

OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini

APP_HOST=0.0.0.0
APP_PORT=8000

AGENT_SYSTEM_PROMPT=你是一个严谨、可靠、擅长使用工具的AI Agent。

实际使用时复制一份：

cp .env.example .env

然后编辑 .env：

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

如果你使用的是 DeepSeek 等 OpenAI 兼容服务，可以类似这样配置：

OPENAI_API_KEY=你的DeepSeek_API_Key
OPENAI_BASE_URL=https://api.deepseek.com
OPENAI_MODEL=deepseek-chat

如果你使用本地 Ollama 的 OpenAI 兼容接口，可以配置为：

OPENAI_API_KEY=ollama
OPENAI_BASE_URL=http://host.docker.internal:11434/v1
OPENAI_MODEL=qwen2.5:7b

需要注意：在 Linux 服务器中，host.docker.internal 不一定默认可用，如果 Agent 容器要访问宿主机上的 Ollama 服务，可能需要额外配置网络，后文会讲。

六、编写 Dockerfile

在项目根目录创建 Dockerfile：

FROM python:3.11-slim

WORKDIR /app

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

COPY requirements.txt .

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

COPY . .

EXPOSE 8000

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

解释一下关键配置：

配置	说明
`python:3.11-slim`	使用轻量版 Python 镜像
`WORKDIR /app`	设置容器工作目录
`PYTHONDONTWRITEBYTECODE=1`	不生成 `.pyc` 文件
`PYTHONUNBUFFERED=1`	日志实时输出
`COPY requirements.txt .`	先复制依赖文件
`pip install`	安装 Python 依赖
`COPY . .`	复制项目代码
`EXPOSE 8000`	声明服务端口
`CMD`	容器启动命令

为什么先复制 requirements.txt 再复制全部代码？

这是为了利用 Docker 构建缓存。只要依赖文件没变，下次构建镜像时就不会重复安装依赖，可以加快构建速度。

七、编写 docker-compose.yml

虽然可以直接使用 docker run，但更推荐使用 Docker Compose。它可以统一管理服务、环境变量、端口映射和重启策略。

创建 docker-compose.yml：

services:
  ai-agent:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: ai-agent-demo
    ports:
      - "8000:8000"
    env_file:
      - .env
    restart: unless-stopped

这个配置非常简单：

build.context 表示从当前目录构建镜像；
container_name 指定容器名称；
ports 将宿主机 8000 端口映射到容器 8000 端口；
env_file 加载 .env；
restart: unless-stopped 表示容器异常退出会自动重启，除非手动停止。

八、本地 Docker 部署

确保已经安装 Docker 和 Docker Compose。

检查 Docker 版本：

docker version

检查 Compose 版本：

docker compose version

然后在项目根目录执行：

docker compose up -d --build

查看容器状态：

docker ps

查看日志：

docker logs -f ai-agent-demo

如果看到类似输出：

Uvicorn running on http://0.0.0.0:8000

说明服务已经启动成功。

测试健康检查接口：

curl http://localhost:8000/health

{"status":"ok"}

测试 Agent 接口：

curl -X POST http://localhost:8000/agent/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "请计算 12 * 8 + 6，并用一句话解释结果"}'

返回示例：

{
  "reply": "12 * 8 + 6 的计算结果是 102，因为 12 乘以 8 得到 96，再加上 6 等于 102。"
}

九、使用 docker run 部署

如果你不想使用 Compose，也可以使用 docker run。

构建镜像：

docker build -t ai-agent-demo:1.0 .

运行容器：

docker run -d \
  --name ai-agent-demo \
  --env-file .env \
  -p 8000:8000 \
  --restart unless-stopped \
  ai-agent-demo:1.0

查看日志：

docker logs -f ai-agent-demo

停止容器：

docker stop ai-agent-demo

删除容器：

docker rm ai-agent-demo

十、部署到 Linux 服务器

假设你的服务器是 Ubuntu 22.04。

1. 安装 Docker

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

启动 Docker：

systemctl enable docker
systemctl start docker

检查状态：

systemctl status docker

2. 上传项目代码

你可以使用 Git：

git clone https://github.com/yourname/ai-agent-docker-demo.git
cd ai-agent-docker-demo

也可以使用 scp 上传：

scp -r ai-agent-docker-demo root@your_server_ip:/opt/

进入目录：

cd /opt/ai-agent-docker-demo

3. 配置环境变量

cp .env.example .env
vim .env

填写你的 API Key。

4. 启动服务

docker compose up -d --build

5. 开放安全组端口

如果你使用云服务器，例如阿里云、腾讯云、华为云、AWS，需要在安全组中放行端口：

TCP 8000

然后访问：

http://服务器IP:8000/docs

如果你希望使用域名和 HTTPS，建议使用 Nginx 反向代理。

十一、Nginx 反向代理配置

生产环境不建议直接暴露 8000 端口，可以通过 Nginx 代理到内部服务。

安装 Nginx：

apt update
apt install -y nginx

创建配置：

vim /etc/nginx/sites-available/ai-agent.conf

写入：

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

    location / {
        proxy_pass http://127.0.0.1:8000;
        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_read_timeout 300;
        proxy_connect_timeout 300;
        proxy_send_timeout 300;
    }
}

启用配置：

ln -s /etc/nginx/sites-available/ai-agent.conf /etc/nginx/sites-enabled/
nginx -t
systemctl reload nginx

如果需要 HTTPS，可以使用 Certbot：

apt install -y certbot python3-certbot-nginx
certbot --nginx -d agent.example.com

之后就可以通过：

https://agent.example.com

访问你的 AI Agent 服务。

十二、如果要连接本地 Ollama 怎么办？

很多开发者会在服务器宿主机上运行 Ollama，然后 Docker 容器里的 Agent 访问宿主机 Ollama。

首先确保 Ollama 监听地址不是只绑定 127.0.0.1。可以配置：

export OLLAMA_HOST=0.0.0.0:11434
ollama serve

在 Linux Docker 中，可以在 docker-compose.yml 增加：

services:
  ai-agent:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: ai-agent-demo
    ports:
      - "8000:8000"
    env_file:
      - .env
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: unless-stopped

然后 .env 配置：

OPENAI_API_KEY=ollama
OPENAI_BASE_URL=http://host.docker.internal:11434/v1
OPENAI_MODEL=qwen2.5:7b

这样容器内就可以访问宿主机服务。

十三、生产环境优化建议

上面的示例适合入门和小规模测试。如果要用于生产环境，建议进一步优化。

1. 增加鉴权

现在接口是公开的，任何人都可以调用。建议增加 API Token。

例如在 config.py 中增加：

API_TOKEN: str = os.getenv("API_TOKEN", "")

在接口中校验 Header：

from fastapi import Header, HTTPException
from app.config import settings


def verify_token(x_api_token: str = Header(default="")):
    if settings.API_TOKEN and x_api_token != settings.API_TOKEN:
        raise HTTPException(status_code=401, detail="Invalid API token")

然后在接口中使用依赖注入。

2. 增加日志

生产服务需要记录：

请求时间；
用户输入；
模型调用耗时；
工具调用耗时；
错误信息；
Token 消耗。

可以使用 Python 的 logging，也可以接入 ELK、Loki、Prometheus 等系统。

3. 增加超时控制

大模型接口可能因为网络或服务商问题而超时。建议设置请求超时时间，并做好异常处理。

4. 增加限流

如果接口暴露在公网，需要避免被恶意刷爆。可以在 Nginx 或应用层增加限流。

Nginx 示例：

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

server {
    location / {
        limit_req zone=agent_limit burst=10 nodelay;
        proxy_pass http://127.0.0.1:8000;
    }
}

5. 使用多进程

Uvicorn 单进程适合演示。如果请求量较大，可以使用 Gunicorn 管理多个 Worker。

修改启动命令：

CMD ["gunicorn", "app.main:app", "-k", "uvicorn.workers.UvicornWorker", "-w", "4", "-b", "0.0.0.0:8000"]

同时在 requirements.txt 中增加：

gunicorn==23.0.0

6. 使用向量数据库

如果要让 Agent 支持知识库问答，可以接入：

Milvus；
Qdrant；
Weaviate；
Chroma；
pgvector。

Docker Compose 可以同时编排向量库和 Agent 服务。

7. 使用 Redis 保存会话

如果 Agent 需要多轮对话记忆，可以把上下文保存到 Redis。这样容器重启后也不会丢失会话状态。

十四、扩展示例：加入 Redis 服务

如果希望后续支持会话记忆，可以在 Compose 中加入 Redis。

services:
  ai-agent:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: ai-agent-demo
    ports:
      - "8000:8000"
    env_file:
      - .env
    depends_on:
      - redis
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    container_name: ai-agent-redis
    ports:
      - "6379:6379"
    restart: unless-stopped

然后在 .env 中增加：

REDIS_URL=redis://redis:6379/0

注意，在 Docker Compose 网络中，服务之间可以通过服务名访问。这里 Agent 访问 Redis 时，主机名不是 localhost，而是 redis。

十五、常见问题排查

1. 容器启动后马上退出

查看日志：

docker logs ai-agent-demo

常见原因：

.env 文件不存在；
OPENAI_API_KEY 没配置；
Python 依赖安装失败；
代码导入路径错误。

2. 接口访问不了

检查容器是否运行：

docker ps

检查端口映射：

docker port ai-agent-demo

检查防火墙：

ufw status

云服务器还要检查安全组。

3. 大模型接口调用失败

可能原因：

API Key 错误；
Base URL 配置错误；
模型名称错误；
网络无法访问模型服务；
账户余额不足；
服务商限流。

可以进入容器内部测试：

docker exec -it ai-agent-demo bash

查看环境变量：

env | grep OPENAI

4. Docker 构建很慢

可以考虑：

使用国内镜像源；
精简依赖；
利用 Docker 缓存；
使用更小的基础镜像；
构建阶段和运行阶段分离。

5. 修改代码后不生效

重新构建并启动：

docker compose up -d --build

如果仍然不生效，可以清理旧镜像：

docker compose down
docker image prune -f
docker compose up -d --build

十六、完整源码汇总

为了方便复制，下面给出核心文件汇总。

requirements.txt

fastapi==0.115.0
uvicorn[standard]==0.30.6
pydantic==2.8.2
python-dotenv==1.0.1
openai==1.43.0

Dockerfile

FROM python:3.11-slim

WORKDIR /app

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

COPY requirements.txt .

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

COPY . .

EXPOSE 8000

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

docker-compose.yml

services:
  ai-agent:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: ai-agent-demo
    ports:
      - "8000:8000"
    env_file:
      - .env
    restart: unless-stopped

.env.example

OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini

APP_HOST=0.0.0.0
APP_PORT=8000

AGENT_SYSTEM_PROMPT=你是一个严谨、可靠、擅长使用工具的AI Agent。