部署

用 Docker 容器化部署你的 Agent 后端

2026.07.23· 6 个步骤 · 约 15 分钟阅读· 🐳 Docker

你的 Agent 在笔记本上跑得好好的，一到服务器就「缺依赖、端口冲突、环境不一样」。Docker 把应用和依赖打包成一个镜像，到哪都能一模一样地跑。本教程把 Agent 后端容器化，并用 docker-compose 把「Agent + Redis + 数据库」一起编排起来。

🐳 本教程适合：想把本地 Agent 服务稳定部署到服务器/云的开发者和 DevOps。需要一台 Linux 服务器。

Step 1：写 Dockerfile

1 写 Dockerfile

从官方轻量镜像起，复制代码、装依赖、声明启动命令。

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Step 2：多阶段构建瘦身

2 多阶段构建瘦身

用多阶段构建，把编译产物和运行时分开，镜像更小、更安全。

FROM python:3.11 AS build
# ... 装依赖到 /install
FROM python:3.11-slim
COPY --from=build /install /usr/local
COPY . /app

Step 3：用 compose 编排多服务

3 用 compose 编排多服务

Agent 常要 Redis（缓存/队列）和数据库。用 docker-compose.yml 一次起好。

services:
  agent:
    build: .
    ports: ["8000:8000"]
    env_file: .env
    depends_on: [redis, db]
  redis:
    image: redis:7-alpine
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: ${{POSTGRES_PWD}}

Step 4：管理密钥（.env 不入库）

4 管理密钥（.env 不入库）

API key、数据库密码放 .env，并把它写进 .gitignore，绝不上传仓库。

泄露高危：曾有多起「把 .env 传 GitHub 导致 key 被盗刷」的事故。务必 .gitignore + 用密钥管理服务。

Step 5：构建镜像

5 构建镜像

本地先构建并跑通，再考虑推到镜像仓库。

docker compose build
docker compose up -d
curl localhost:8000/health

Step 6：运行与监控

6 运行与监控

加 healthcheck 让编排器知道服务活着；用 docker logs 看输出，用 restart: unless-stopped 自动拉起。

# 看日志
docker compose logs -f agent
# 挂掉自动重启（写在 compose 的 agent 下）
# restart: unless-stopped

常见问题速查

你遇到的现象	大概率原因 & 解决
本地能跑服务器挂	依赖没装全 / 端口未暴露，用同镜像消除差异
key 泄露	.env 入库了，立刻轮换 key 并加 gitignore
服务假死	加 healthcheck，配 restart 策略
镜像太大	多阶段构建 + 用 -slim/alpine 基础镜像

📚 更多教程 📰 智能体资讯 📖 Agent百科