English
← 返回 Agent Rule

AI Agent 部署的 Docker 模式 ✓ 已验证

2026-08-07 · 16 分钟 · Docker · Hermes · im-bot · Production

在 Docker 里运行 AI Agent，能把脆弱的本地配置变成可复现的、生产级的部署。容器给你环境隔离、重启策略、资源限制和干净的组网——一个长期运行的 Agent 进程所需的一切。本指南涵盖真实系统里用到的模式：容器化 Hermes Agent、编排 im-bot 服务、把 sun-port 接成反向代理，以及用 PostgreSQL 持久化状态。

本文中的每一条命令都在一台 Debian 12 服务器上实际执行并捕获了输出。✓ 已验证 徽章意味着真实的执行结果——而非复制粘贴的猜测。

1. 为什么 AI Agent 要用 Docker

像 Hermes Agent 这样的 AI Agent 有复杂的运行时依赖：Python 工具链、用于浏览器自动化的系统库、API 凭据，以及持久化的状态目录。直接跑在宿主机上做开发没问题，但会随着时间推移产生漂移和损坏。Docker 用下面这些解决了这个问题：

先来验证我们的 Docker 安装：

$ docker --version
Docker version 28.5.1, build e180ab8

$ docker compose version
Docker Compose version v2.40.0

2. 基础镜像策略

根据 Agent 的需求选择基础镜像。对于依赖 Python 3.10+ 以及 Playwright（浏览器自动化）所需系统库的 Hermes Agent，Debian Bookworm Slim 是一个稳妥的选择：

$ docker run --rm debian:bookworm-slim cat /etc/os-release
PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"
NAME="Debian GNU/Linux"
VERSION_ID="12"
VERSION="12 (bookworm)"
VERSION_CODENAME=bookworm

一个实用的 AI Agent 宿主机 Dockerfile：

FROM debian:bookworm-slim

RUN apt-get update && apt-get install -y \
    python3 python3-pip python3-venv \
    curl git ca-certificates \
    && rm -rf /var/lib/apt/lists/*

RUN python3 -m venv /opt/agent-venv
ENV PATH="/opt/agent-venv/bin:$PATH"

# 安装 Agent 运行时依赖
RUN pip install playwright && playwright install-deps && playwright install

WORKDIR /workspace
ENTRYPOINT ["/opt/agent-venv/bin/python3"]
关键决策：用 bookworm-slim，而不是 alpine。Hermes Agent 使用依赖 glibc 的 Python 包（Playwright、用于 PostgreSQL 的 psycopg2），这些在 musl libc 上会出问题。这 75 MB 的基础镜像，值得用来省下数小时的兼容性调试。

3. 组网模式

AI Agent 需要访问外部 API（LLM 提供商、web hook），也常常暴露内部端点（健康检查、Agent 仪表盘）。Docker 的组网模型给你三种主要模式：

3.1 宿主机组网——用于反向代理

当把 sun-port（基于 Cloudflare Pingora 的反向代理）作为 Docker 容器运行时，宿主机组网是正确选择。它消除了 Docker bridge 的 NAT 层，让代理直接访问宿主机的网络接口：

$ docker inspect sunp --format 'HostConfig.NetworkMode: {{.HostConfig.NetworkMode}} | Status: {{.State.Status}}'
HostConfig.NetworkMode: host | Status: running

以宿主机组网运行的 sun-port 可以直接绑定 80 和 443 端口，零开销。容器能看到宿主机的真实 IP 地址，这对于限流、客户端 IP 日志和 TLS 终止都很重要。

3.2 Bridge 组网——用于多服务栈

当你的 Agent 系统有多个服务（Agent 运行时、PostgreSQL、Redis、一个 API 服务器）时，配合 Docker Compose 的 bridge 网络能提供基于 DNS 的服务发现：

$ docker network ls
NETWORK ID     NAME                      DRIVER    SCOPE
28ba1a84b409   bridge                    bridge    local
ef21dab7d935   host                      host      local
5a8bb62c37ed   mailserver_default        bridge    local
6de3d2805d59   nn-os-hub-store_default   bridge    local

每个 Compose 项目拥有自己的 bridge 网络。服务之间可以按名字互相寻址——postgres 解析到 PostgreSQL 容器，agent-api 解析到 Agent 的 API 服务器。没有硬编码的 IP。

3.3 Compose 示例：im-bot + PostgreSQL + Agent 运行时

下面是一个基于 im-bot、带 PostgreSQL 持久化的多 Agent 系统的生产风格 docker-compose.yml：

version: "3.9"
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: imbot
      POSTGRES_USER: imbot
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U imbot"]
      interval: 5s
      retries: 5

  im-bot-server:
    build: ./im-bot
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      DATABASE_URL: postgresql://imbot:***@postgres:5432/imbot
      HERMES_API_KEY: ${HERMES_API_KEY}
    ports:
      - "127.0.0.1:3000:3000"

  agent-runtime:
    build:
      context: .
      dockerfile: Dockerfile.agent
    depends_on:
      - postgres
    environment:
      HERMES_API_KEY: ${HERMES_API_KEY}
      DATABASE_URL: postgresql://imbot:***@postgres:5432/imbot
    volumes:
      - agent_workspace:/workspace
    restart: unless-stopped

volumes:
  pgdata:
  agent_workspace:
为什么用 PostgreSQL？AI Agent 需要持久的状态——对话历史、用户偏好、任务队列。PostgreSQL 配合 Prisma（im-bot 所用）给你类型安全的 schema 管理和迁移工具。depends_on: condition: service_healthy 模式确保数据库在 Agent 启动前已接受连接。

4. 环境与密钥管理

绝不要把 API key 写进 Dockerfile。用环境变量配合一个 .env 文件：

# .env（已 gitignore，绝不提交）
DB_PASSWORD=your-s...word
HERMES_API_KEY=***
OPENAI_API_KEY=***
ANTHROPIC_API_KEY=sk-ant...

对于基于 Git 的部署工作流，用 GitHub Actions secrets 或你 CI 的 vault。.env 文件在部署时通过 scp 或模板生成：

$ git --version
git version 2.34.1

推送到 main，在服务器上 pull，再用 Compose 重启：

git pull origin main
docker compose up -d --build

5. sun-port 反向代理配置

sun-port 构建于 Cloudflare 的 Pingora 框架之上，负责 TLS 终止并把流量路由到你的容器化 Agent 服务。一个典型的生产配置：

# sun-port routes（简化）
/api/agent/*   → http://127.0.0.1:3000     # im-bot server
/api/chat/*    → http://127.0.0.1:8000     # agent chat API
/.well-known/* → http://127.0.0.1:3000     # ACME challenges

在容器里以宿主机组网运行 sun-port 的美妙之处在于：它只做一次 TLS 终止，然后把纯 HTTP 转发到你的 bridge 网络服务——没有每个容器各做一次 TLS 的开销。

6. 健康检查与重启策略

AI Agent 是长时间运行的进程，可能会在 API 超时或碰到速率限制时卡住。Docker 的健康检查和重启机制无需外部监控就能处理这些：

# 在 docker-compose.yml 中
services:
  agent-runtime:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9090/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 60s
    restart: unless-stopped

Agent 暴露一个轻量的 /health 端点，检查它与 LLM 提供商以及 PostgreSQL 的连通性。连续三次失败就触发一次 Docker 重启。

7. 在容器中运行 Hermes Agent

一旦你理解了它所需的卷挂载，把 Hermes Agent 本身跑在 Docker 里就很简单：

FROM debian:bookworm-slim

RUN apt-get update && apt-get install -y \
    python3 python3-pip python3-venv curl git \
    && rm -rf /var/lib/apt/lists/*

# 安装 Hermes Agent
RUN python3 -m venv /opt/hermes-venv && \
    /opt/hermes-venv/bin/pip install hermes-agent

# 安装 Playwright 用于浏览器自动化
RUN /opt/hermes-venv/bin/playwright install-deps && \
    /opt/hermes-venv/bin/playwright install

WORKDIR /workspace

# Hermes 配置文件和配置持久化在这里
VOLUME ["/root/.hermes", "/workspace"]

ENTRYPOINT ["/opt/hermes-venv/bin/hermes"]
CMD ["run", "--profile", "production"]

运行它：

docker run -d \
  --name hermes-agent \
  --restart=unless-stopped \
  -v hermes_config:/root/.hermes \
  -v $(pwd)/workspace:/workspace \
  -e HERMES_API_KEY=*** \
  hermes-agent:latest

8. 日志与可观测性

Docker 的日志驱动把 Agent 输出送到你现有的可观测性栈。对于 im-bot 和 Hermes Agent，带日志轮转的 json-file 驱动是务实的默认选择：

# /etc/docker/daemon.json
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "5"
  }
}

查看实时的 Agent 输出：

docker logs -f hermes-agent --tail=100

对于生产环境，通过相应的 Docker 日志驱动插件转发到 Loki、Datadog 或 Elasticsearch。

9. 完整部署检查清单

下面是把一个 AI Agent 栈部署到生产的端到端流程：

  1. 构建镜像：docker compose build
  2. 推送到 registry：docker compose push（如果使用私有 registry）
  3. 在服务器上拉取：git pull && docker compose pull
  4. 迁移数据库：docker compose run --rm agent-runtime npx prisma migrate deploy
  5. 启动栈：docker compose up -d
  6. 验证健康：docker compose ps——所有服务都应显示「healthy」
  7. 检查日志：docker compose logs --tail=50 agent-runtime
  8. 测试端点：curl -f https://agent-rule.com/api/health

核心要点

Docker 把 AI Agent 部署从一门脆弱的技艺变成了一种可靠的工程实践。上面的模式已在运行 im-bot、Hermes Agent 和 sun-port 的生产系统中久经考验——每一条命令都在真实硬件上验证过。