PentAGI Docker Compose 部署指南

目标：在一台 Ubuntu 22.04 服务器上以官方 Docker Compose 方式从零部署 PentAGI v2.2.0（AI 驱动自动化渗透测试系统），覆盖镜像选型、.env 最小配置、启动验证、数据持久化、升级与卸载，以及部署过程中的真实排障实录。全部命令与回显在 Ubuntu 22.04（x86_64）实测采集，LLM 接入采用 OpenAI 兼容自定义端点（无真实 API key 场景的最小化验证路径）。

一、环境信息

• 操作系统：Ubuntu 22.04（x86_64）
• 软件版本：PentAGI v2.2.0（官方最新稳定版，2026-10-05 发布；Docker Hub vxcontrol/pentagi:2.2.0，查询日期 2026-10-23）
• 编排工具：Docker Engine 28.x + Docker Compose v2（docker compose 子命令）
• 硬件要求（官方 System Requirements）：≥2 vCPU、≥4GB 内存、≥20GB 磁盘
• 服务端口规划（本篇实测值，生产可按需调整）：

⚠️ 注意：Flow 运行期每个 Flow 会在宿主 DOCKER_PORTS_BASE（默认 28000）起的 2000 端口窗口内动态发布 2 个带外回连端口（绑定 DOCKER_PUBLIC_IP，默认 0.0.0.0），防火墙需按需管控。

二、镜像选型说明

官方 docker-compose.yml（v2.2.0）定义 4 个固定服务，镜像如下：

关键差异与选型：pentagi 主镜像必须固定到发布版本号（如 2.2.0），避免 latest 漂移导致升级不可追溯；pgvector 与 scraper 官方只发布 latest，升级时以 docker compose pull 的时间点为准。三个可选附加栈（Langfuse/Graphiti/observability）各有独立 compose 文件，首部部署不需要。

三、前置条件

1. 已安装 Docker Engine 与 Compose 插件，当前用户可操作 Docker：

docker version --format '{{.Server.Version}}'

实测输出：

28.5.2

2. 服务器可访问外网（拉取镜像与后续 LLM/搜索 API 调用；纯内网环境需自建镜像源并使用 Ollama/vLLM 本地模型）。
3. 准备至少一个 LLM 供应商凭据：真实场景使用 OpenAI/Anthropic/Gemini/DeepSeek/GLM/Kimi/Qwen 等任一 API key，或自建 Ollama/vLLM；本文实测使用 OpenAI 兼容自定义端点（LLM_SERVER_* 变量），在不持有真实 key 的环境下完成部署与配置加载验证。
4. 端口确认：宿主 8443（或自定义发布端口）未被占用。

四、部署步骤

4.1 建立部署目录

mkdir -p /opt/pentagi && cd /opt/pentagi

4.2 下载官方编排文件与示例配置

curl -o .env https://raw.githubusercontent.com/vxcontrol/pentagi/master/.env.example
curl -o docker-compose.yml https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose.yml
curl -o example.custom.provider.yml https://raw.githubusercontent.com/vxcontrol/pentagi/master/examples/configs/custom-openai.provider.yml
curl -o example.ollama.provider.yml https://raw.githubusercontent.com/vxcontrol/pentagi/master/examples/configs/ollama-llama318b.provider.yml
curl -o example.bedrock.provider.yml https://raw.githubusercontent.com/vxcontrol/pentagi/master/examples/configs/bedrock.provider.yml

💡 说明：三个 provider 示例文件必须真实存在（空文件也可），docker-compose.yml 会把它们挂载进容器；挂载源不存在时 Docker 会创建同名目录，反而导致启动异常。生产建议固定到 v2.2.0 标签下载：把 URL 中 master 换成 v2.2.0。

4.3 修改 .env 关键配置

.env.example（约 620 行）按区块组织：Core runtime / LLM Providers / Embedding / Summarizer / 搜索引擎 / Docker / PostgreSQL / 可选栈。最小部署需改以下各项（实测取值）：

# 固定主服务版本
PENTAGI_IMAGE=vxcontrol/pentagi:2.2.0
# 宿主发布端口（默认 8443，按需修改；127.0.0.1 表示仅本机访问，对外服务改为 0.0.0.0 或具体网卡 IP）
PENTAGI_LISTEN_PORT=8150
PENTAGI_LISTEN_IP=0.0.0.0
# 宿主 5432 通常已有 PostgreSQL，改开发布端口避免冲突
PGVECTOR_LISTEN_PORT=15432
POSTGRES_EXPORTER_LISTEN_PORT=19187
SCRAPER_LISTEN_PORT=19443
# 安全项（默认值 salt/postgres 必须修改，否则无法创建 API Token）
COOKIE_SIGNING_SALT=quzuo-s8-pentagi-salt
PENTAGI_POSTGRES_PASSWORD=q1w2e3r4
# 对外访问地址（含端口，保持与 PENTAGI_LISTEN_PORT 一致）
PUBLIC_URL=https://127.0.0.1:8150
CORS_ORIGINS=https://127.0.0.1:8150

LLM 接入二选一（实测采用方式 B）：

# 方式 A：真实供应商，例如 OpenAI
# OPEN_AI_KEY=sk-xxx

# 方式 B：OpenAI 兼容自定义端点（vLLM/LiteLLM/网关均可）
LLM_SERVER_URL=http://mock-openai:9000/v1
LLM_SERVER_KEY=sk-mock-0000
LLM_SERVER_MODEL=mock-llm
LLM_SERVER_PROVIDER=custom
# 向量嵌入指向同一兼容端点，消除启动日志的 embedder 报错（见 10.1）
EMBEDDING_URL=http://mock-openai:9000/v1
EMBEDDING_KEY=sk-mock-0000
EMBEDDING_MODEL=mock-embed
EMBEDDING_PROVIDER=openai

⚠️ 注意：LLM_SERVER_URL 指向 compose 网络内可达的地址。本实测在 compose 附加服务里提供了一个 OpenAI 兼容 mock（/v1/models、/v1/chat/completions、/v1/embeddings），容器名 mock-openai 由 compose DNS 解析。若端点在宿主机，写 http://<宿主IP>:<端口>/v1，不要写 localhost（那指向 pentagi 容器自身）。

4.4 启动

docker compose up -d

实测输出（首启需拉取镜像，约 2-5 分钟）：

 Container pentagi Created
 Container pgvector Starting
 Container scraper Starting
 Container pentagi-2.2.0-mock-openai Starting
 Container pgvector Started
 Container pgvector Waiting
 Container scraper Started
 Container pentagi-2.2.0-mock-openai Started
 Container pgvector Waiting
 Container pgvector Healthy
 Container pgexporter Starting
 Container pgexporter Started
 Container pgvector Healthy
 Container pentagi Starting
 Container pentagi Started

4.5 验证启动与版本

docker compose ps

实测输出：

NAME                       STATUS                    PORTS
pentagi                    Up 23 seconds             0.0.0.0:8150->8443/tcp
pentagi-2.2.0-mock-openai  Up 28 seconds
pgexporter                 Up 23 seconds             0.0.0.0:19187->9187/tcp
pgvector                   Up 28 seconds (healthy)   0.0.0.0:15432->5432/tcp
scraper                    Up 28 seconds             0.0.0.0:19443->443/tcp

docker logs pentagi 2>&1 | grep -E 'Starting PentAGI|migrated|listening|TLS'

实测输出：

time="2026-10-22T21:21:13Z" level=info msg="Starting PentAGI 2.2.0-ce"
2026/10/22 21:21:13 goose: successfully migrated database to version: 20260722
time="2026-10-22T21:21:13Z" level=info msg="API server listening on 0.0.0.0:8443"
time="2026-10-22T21:21:13Z" level=info msg="Starting server with TLS enabled"

关键验证点：Starting PentAGI 2.2.0-ce 确认版本；goose: successfully migrated database to version: 20260722 确认 26 张业务表迁移完成；listening on 0.0.0.0:8443 确认监听地址可被端口映射转发（若显示 127.0.0.1:8443 见 10.2 排障）；Starting server with TLS enabled 确认自签证书已生成。

服务端点验证（自签证书需 -k）：

curl -sk -o /dev/null -w 'HTTP %{http_code}\n' https://127.0.0.1:8150/
curl -sk -X POST https://127.0.0.1:8150/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"mail":"admin@pentagi.com","password":"admin"}'

实测输出：

HTTP 200
{"data":{},"status":"success"}

⚠️ 注意：登录请求体字段是 mail 而非 username/email，用错字段返回 Auth.InvalidLoginRequest。首次登录后立即改密：平台强密码策略要求 ≥16 位，或 ≥8 位且同时含大写字母、小写字母、数字与特殊字符（特殊字符限 !@#$&*），q1w2e3r4 这类弱口令会被 stpass 校验拒绝（实测返回 Users.ChangePasswordCurrentUser.InvalidPassword）。改密 API 为 PUT /api/v1/user/password，请求体 {"current_password":"admin","password":"新密码","confirm_password":"新密码"}。

浏览器访问 https://127.0.0.1:8150，用 admin@pentagi.com 与新密码登录 Web 控制台，即完成部署。API Token 在 Settings → PentAGI API 创建（或 POST /api/v1/tokens/），后续 REST/GraphQL 调用带 Authorization: Bearer <token>；API 使用细节见本专栏《PentAGI v2.2.0 API 使用详解》。

五、数据持久化说明

docker-compose.yml 声明 5 个命名卷（named volumes），由 Docker 管理，位于 /var/lib/docker/volumes/：

另外 4 个 bind mount 把宿主当前目录的文件挂进容器（见第八节）。持久化验证：重建容器后 Flow 历史与用户不丢失：

docker compose down && docker compose up -d

重启后用原密码登录、GET /api/v1/flows/ 列表不变即验证通过（实测 flow 记录保留）。如需把数据落到指定磁盘目录，用 PENTAGI_DATA_DIR=/data/pentagi 等变量覆盖卷名为宿主路径。

六、环境变量表（部署核心项）

全量变量见 .env.example 内注释与 backend/docs/config.md，逐项详解见本专栏《PentAGI v2.2.0 配置参数详解》。

七、配置参数说明（compose 层面）

docker-compose.yml 中 pentagi 服务的关键配置：

• user: root:root：因需访问挂载的 Docker Socket 创建沙箱；官方注明改用 TCP 连接 Docker 时可降权为默认 pentagi 用户；
• logging.options: max-size=50m, max-file=7：日志轮转上限 350MB/服务；
• depends_on: pgvector (service_healthy)：pgvector 健康检查 pg_isready 通过后才启动主服务；
• restart: unless-stopped：开机随 Docker 自启（Docker 服务启用 systemctl enable docker 的前提下）；
• 网络声明 pentagi-network + observability-network + langfuse-network：后两者供可选附加栈使用，主栈启动时会一并创建。

💡 技术拓展：Compose 环境变量解析遵循「shell 环境变量 > .env 文件」优先级。若登录 shell 已存在与 .env 同名的变量（如 SERVER_HOST），compose 会优先采用 shell 值，这是部署机上"改了 .env 却不生效"的常见根因，可用 docker compose config | grep KEY 核对最终注入值。

八、配置文件挂载

pentagi 容器的 bind mount（源路径相对 compose 目录）：

provider 配置文件为 YAML，按 simple/simple_json/primary_agent/assistant/generator/refiner/adviser/reflector/searcher/enricher/coder/installer/pentester 13 个角色分别指定 model/temperature/top_p/max_tokens/reasoning/price。修改后 docker compose restart pentagi 生效。

九、等价 docker run（单容器理解用）

生产仍以 compose 为准；以下命令用于理解 pentagi 主容器的最小运行参数（沙箱功能依赖挂载的 Docker Socket 与数据库，单独运行仅能启动 API）：

docker run -d --name pentagi \
  -p 8150:8443 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v pentagi-data:/opt/pentagi/data \
  -v pentagi-ssl:/opt/pentagi/ssl \
  -v pentagi-ollama:/root/.ollama \
  -e SERVER_HOST=0.0.0.0 -e SERVER_PORT=8443 -e SERVER_USE_SSL=true \
  -e OPEN_AI_KEY=${OPEN_AI_KEY} \
  vxcontrol/pentagi:2.2.0

数据库连接串通过 DATABASE_URL=postgres://<user>:<pass>@pgvector:5432/pentagidb?sslmode=disable 注入，单容器形态需自行提供可达的 PostgreSQL（含 pgvector 扩展），因此推荐始终使用 compose 全栈。

十、常用运维命令

# 状态与日志
docker compose ps                          # 各服务状态
docker logs -f pentagi                     # 主服务日志（错误会带 level=error）
docker compose logs --tail=100 pentagi     # 查看最近 100 行

# 生命周期
docker compose start / stop                # 原样启停（保留容器）
docker compose restart pentagi             # 重启主服务（改 provider 配置后用）
docker compose down                        # 停止并删除容器与网络（保留卷）
docker compose down -v                     # ⚠️ 连同数据卷一起删除（销毁全部 Flow 历史）

# 升级到新版本（以 2.3.0 为例）
sed -i 's|vxcontrol/pentagi:2.2.0|vxcontrol/pentagi:2.3.0|' .env
docker compose up -d                       # 拉新镜像并滚动重建，数据库自动迁移
docker logs pentagi 2>&1 | grep migrated   # 确认迁移执行

⚠️ 注意：数据库迁移由 goose 自动执行（只升不降）。跨大版本升级前先用 docker compose down -v 之外的正规手段备份：pg_dump -U postgres pentagidb > backup.sql。回滚版本前先确认目标版本的迁移兼容性。

十一、常见问题（排障实录）

11.1 启动日志出现 embedder 报错

现象（实测）：

time="2026-10-22T21:11:18Z" level=error msg="failed to create embedder 'openai'" error="missing the OpenAI API key, set it in the OPENAI_API_KEY environment variable"

定位：向量嵌入器复用 OpenAI 凭据，未配置任何 embedding 端点时该报错必然出现；属非致命错误（服务继续启动），但向量记忆功能不可用。解决方案：在 .env 配置 EMBEDDING_URL/EMBEDDING_KEY/EMBEDDING_MODEL（OpenAI 兼容 /v1/embeddings 端点），重建后报错消失（实测 grep -c 'failed to create embedder' 为 0）。

11.2 端口映射后浏览器无法访问（TLS unexpected eof）

现象（实测）：docker compose ps 显示端口映射正常，curl -k https://127.0.0.1:8150 报 error:0A000126:SSL routines::unexpected eof while reading，同时日志显示：

time="..." level=info msg="API server listening on 127.0.0.1:8443"

定位：服务绑定了容器内回环地址，Docker 端口转发（从容器 eth0 进流量）无法送达。根因是容器内 SERVER_HOST=127.0.0.1——本机部署时登录 shell 已存在同名变量 SERVER_HOST=127.0.0.1，compose 解析 SERVER_HOST=${SERVER_HOST:-0.0.0.0} 时 shell 变量优先于 .env。解决方案：docker compose config | grep SERVER_HOST 核对实际注入值；用 SERVER_HOST=0.0.0.0 docker compose up -d 显式覆盖或清理 shell 中的同名变量。重建后日志变为 API server listening on 0.0.0.0:8443，访问恢复。

11.3 登录/改密接口报错

• {"code":"Auth.InvalidLoginRequest"}：请求体字段错误，登录用 {"mail":"...","password":"..."}；
• {"code":"Users.ChangePasswordCurrentUser.InvalidPassword"}：新密码未达强度策略（见 4.5 注意）；
• 登录连续失败 10 次（同账号+IP）触发 15 分钟锁定（429）。

11.4 无法创建 API Token（token creation is disabled）

现象（实测）：POST /api/v1/tokens/ 返回 token creation is disabled with default salt。定位：COOKIE_SIGNING_SALT 保持默认值 salt 时 Token 功能被安全禁用（服务端启动也会记录）。解决方案：修改该变量后 docker compose up -d 重建，再创建即返回含 JWT 的 {"data":{...,"token":"eyJ..."}}。

11.5 创建 Flow 报 "no tool call ID samples collected"

现象（实测，LLM 为纯文本 OpenAI 兼容端点）：

level=warning msg="docker image chosen by the model was rejected, falling back" answer="mock reply: ..." fallback=vxcontrol/kali-linux flow_id=1
level=error msg="failed to get flow provider" error="failed to determine tool call ID template: no tool call ID samples collected" flow_id=1

定位：PentAGI 启动 Flow 时会向 LLM 发探测调用，从响应的 tool_calls 中采样并确定 tool call ID 模板（如 OpenAI 的 call_{r:24:x}）。端点不支持 function calling（响应无 tool_calls）时采样失败，Flow 进入 failed。解决方案：换用支持工具调用的模型端点（Ollama 的 tool-capable 模型、vLLM --enable-auto-tool-choice、或任意商业 API）。端点修复后实测 Flow 创建成功，日志出现 running container ... image=vxcontrol/kali-linux name=pentagi-terminal-2 type=primary，且 Flow 详情中 tool_call_id_template 被实测探测为端点实际返回的 ID 形态。

11.6 首启镜像拉取慢或超时

国内网络环境为 Docker Daemon 配置 HTTP 代理（/etc/docker/daemon.json 的 proxies.http-proxy）或使用镜像加速器后重试 docker compose pull。

十二、参考链接

• 官方 Quick Start：https://github.com/vxcontrol/pentagi#quick-start
• v2.2.0 Release Notes：https://github.com/vxcontrol/pentagi/releases/tag/v2.2.0
• Worker 节点隔离（生产双机架构）：https://github.com/vxcontrol/pentagi/blob/master/examples/guides/worker_node.md
• 本专栏相关：《PentAGI 介绍与选型指南》、《PentAGI v2.2.0 配置参数详解》、《PentAGI v2.2.0 API 使用详解》