PentAGI v2.2.0 配置参数详解

目标：面向已完成 PentAGI Compose 部署的运维与安全工程师，逐类讲清 .env 配置文件中各参数的作用、默认值与生产建议。本文参数说明全部溯源自 PentAGI v2.2.0 源码（.env.example、backend/docs/config.md），关键行为均在本机 v2.2.0 实例上实测验证，溯源与实测日期为 2026-10-23。

一、环境信息

参数体量实测：v2.2.0 的 .env.example 共含 345 个变量赋值行，其中约 133 行属于可选的 Graphiti / Neo4j / Langfuse 可观测栈，PentAGI 主栈核心配置约 200 个。本文覆盖主栈全部功能类别，可选栈仅讲与主栈衔接的入口参数。

合规提示：PentAGI 是面向授权渗透测试场景的自动化工具。所有配置示例仅用于自有环境或已获书面授权的测试目标，文中参数不涉及任何攻击结果的编造。

二、前置条件

• 已按《PentAGI Docker Compose 部署指南》完成部署，实例可正常登录 Web 控制台；
• 部署目录下存在从源码复制的 .env 文件（由 docker-compose.yml 的 env_file 机制注入容器）；
• 具备查看容器日志的权限（docker compose logs），本文多处用启动日志验证配置生效。

三、参数查看与修改方式

3.1 配置加载机制（源码实查）

PentAGI 后端启动时按以下顺序装配配置（backend/pkg/config/config.go 的 NewConfig()）：

1. godotenv.Load() 读取工作目录下的 .env 文件，写入进程环境变量——不覆盖已存在的变量；
2. github.com/caarlos0/env/v10 按 struct tag 将环境变量解析进 Config 结构体，未设置且无默认值的字段保持零值；
3. 各 provider 注册时做凭据门槛检查（pkg/providers/registry.go 的 Enabled 函数）：某家 LLM 的 API Key 为空，该 provider 直接不注册，不会导致启动失败，只是控制台可用 provider 变少。

由此得出两条关键推论，均已实测验证：

• shell 环境变量优先于 .env 文件：godotenv 不覆盖已有变量，若执行 docker compose up 的 shell 里已导出同名变量（如 SERVER_HOST），它会压过 .env 中的值。实测曾因此导致容器监听在容器内 loopback 上、宿主机 curl 返回 000（排障过程见第七节与部署篇第六节）。
• .env 改完必须重建容器：配置在进程启动时一次性读取，修改 .env 后需 docker compose up -d 重建使配置生效，仅 restart 不会重新读文件。

3.2 修改与验证流程（实测命令）

$ vi .env                                          # 编辑参数
$ docker compose config | grep SERVER_HOST         # 渲染 compose 最终值，确认没有 shell 变量覆盖
    SERVER_HOST: 0.0.0.0
$ docker compose up -d                             # 重建生效
$ docker compose logs --tail 50 pentagi            # 观察启动日志确认监听地址与 provider 注册

3.3 Web 控制台可改项与环境变量的边界（源码 config.md 实查）

Web 控制台 Settings 页可管理：Provider 配置档案（每个代理角色用哪个模型）、Prompt 模板、PentAGI API Token。但以下类别仍以环境变量为唯一事实来源：LLM 凭据与端点、搜索引擎凭据、Langfuse/Graphiti 等第三方集成、MCP 服务管理。改这些必须走 .env + 重建。

四、参数总览

五、核心参数分类详解

5.1 核心运行时

TENANT_ID 生效时自动命名空间的范围：PostgreSQL 会创建同名 schema、沙箱容器名变为 <tenant>-pentagi-terminal-<flow>、Graphiti 分组变为 <tenant>-flow-<id>、Cookie/JWT 密钥加入租户因子（一个实例签发的会话在另一个实例上失效）。不自动命名空间的：DATA_DIR、DOCKER_NETWORK、各监听端口——多实例部署必须手工错开。

5.2 LLM Provider（13 家）

每家 provider 只需配置凭据即可启用，凭据为空则不注册（见 3.1 凭据门槛）。v2.2.0 支持的 13 家及默认端点（源码 .env.example 实查）：

Custom provider 补充说明：

• LLM_SERVER_PROVIDER：模型名前缀，接 LiteLLM 网关时按需设置（如 openai/gpt-4o 形态）；DeepSeek/GLM/Kimi/Qwen/MiniMax/Mistral/xAI 七家的 *_PROVIDER 变量同理；
• LLM_SERVER_API_TYPE 置 azure 或 azure_ad 可对接 Azure OpenAI 部署，此时 LLM_SERVER_API_VERSION（默认 2024-10-21）才生效；
• LLM_SERVER_PRESERVE_REASONING（默认 false）：开启后在多轮对话中回传 reasoning_content，部分推理模型（文档举例 Moonshot）缺它会在工具调用轮次报错；
• LLM_FALLBACK_PROVIDER：主 provider 调用失败时用哪一家重试，空为关闭。

实测记录（LLM 接入方式）：实验环境无真实 LLM API Key，本批次用 LLM_SERVER_PROVIDER=custom 接入自建的 OpenAI 兼容 mock 端点完成全链路验证——LLM_SERVER_URL=http://mock-openai:9000/v1、LLM_SERVER_KEY=sk-mock-0000、LLM_SERVER_MODEL=mock-llm。启动后 provider 正常注册，创建 flow 时 PentAGI 先向端点发一次探测调用采样 tool call ID 模板（mock 返回带 tool_calls 的响应后探测通过），随后成功创建沙箱容器。mock 不支持的部分（真实模型对话质量）不在本文讨论范围。

5.3 Embedding（向量嵌入）

实测记录：LLM_SERVER_* 指向 mock 端点、未配 EMBEDDING_* 时，启动日志出现 embedder 初始化报错；将 EMBEDDING_URL/KEY 指向同一 mock 端点（/v1/embeddings 路径）、EMBEDDING_MODEL=mock-embed、EMBEDDING_PROVIDER=openai 后报错消失（日志 grep 不再命中）。结论：custom LLM provider 场景必须显式配齐 EMBEDDING 四件套，不能指望回退逻辑（回退目标是 OpenAI 官方端点与密钥，custom 场景均为空）。

5.4 搜索引擎（9 类）

SearXNG 其余参数：SEARXNG_CATEGORIES（默认 general）、SEARXNG_LANGUAGE、SEARXNG_SAFESEARCH（默认 0，0/1/2 三档）、SEARXNG_TIME_RANGE、SEARXNG_TIMEOUT。注意：SEARXNG_URL 只填地址，SearXNG 实例本身需另行部署（官方 Compose 栈不含它）。

实测记录：实验环境关闭了外网搜索（DUCKDUCKGO_ENABLED=false），Sploitus 保持默认，flow 创建与沙箱运行不受影响——搜索引擎只在代理执行检索类工具时才会被调用。

5.5 Docker 沙箱（安全关键项）

安全警告（源码 .env.example 原文，对应官方 issue #337）：DOCKER_INSIDE=true 会把宿主 Docker socket 挂进每个沙箱，沙箱内进程获得不受限的 Docker API——可被提示注入利用逃逸到宿主。确需 DinD 时，官方建议用 DOCKER_INSIDE_HOST 指向独立的低权限 daemon（如 docker-socket-proxy），而非直挂裸 socket。

5.6 服务监听与安全

Compose 层监听变量（决定宿主机端口映射）：

容器内服务器变量（SERVER_*，.env.example 显式置 SERVER_PORT=8443、SERVER_HOST=0.0.0.0、SERVER_USE_SSL=true）：

实测记录：PUBLIC_URL=https://127.0.0.1:8150、CORS_ORIGINS=https://127.0.0.1:8150、COOKIE_SIGNING_SALT 换为自定义随机串后，本机 HTTPS 登录、GraphQL 请求均正常。COOKIE_SIGNING_SALT 同时参与 Bearer JWT 密钥派生——改盐后所有旧会话与 API Token 全部失效，需重新登录。

5.7 数据库（pgvector）

实测记录：PENTAGI_POSTGRES_PASSWORD 改为强密码后栈正常起库，26 张业务表自动迁移完成。密码注意强密码策略（见 7.3）。

5.8 Web Scraper

两个 URL 职责不同：后端→scraper 走 SCRAPER_PRIVATE_URL（容器网络名直连），最终返回给用户点击的链接用 SCRAPER_PUBLIC_URL（需浏览器可达）。公网部署时后者要配成对外域名。

5.9 网络代理与超时

实测提醒：PROXY_URL 的注释明确写了"local endpoints included"——设置后连容器网络内的本地端点也会被代理。本批次 mock 端点实测时保持 PROXY_URL 为空；生产环境若同时用代理和内网 LLM 网关，需确认代理对内网地址直连放行。

5.10 Agent 监督与执行上限

5.11 Summarizer 与 Assistant（长对话压缩）

5.12 可观测集成入口

六、生产配置模板

以下为无真实 OpenAI Key、用自定义 OpenAI 兼容网关（如 LiteLLM/自建推理网关）时的最小可用模板，实测基于本批次 v2.2.0 部署：

# --- 镜像（锁定版本，勿用 latest）---
PENTAGI_IMAGE=vxcontrol/pentagi:2.2.0

# --- LLM：自定义 OpenAI 兼容端点 ---
LLM_SERVER_URL=http://litellm:4000/v1
LLM_SERVER_KEY=sk-your-gateway-key
LLM_SERVER_MODEL=gpt-4o
LLM_SERVER_PROVIDER=custom
# custom 场景必须显式配置 embedding（回退目标是 OpenAI 官方，网关场景无效）
EMBEDDING_PROVIDER=openai
EMBEDDING_URL=http://litellm:4000/v1
EMBEDDING_KEY=sk-your-gateway-key
EMBEDDING_MODEL=text-embedding-3-small

# --- 搜索：全部免 Key 或关闭 ---
DUCKDUCKGO_ENABLED=true
SEARXNG_URL=http://searxng:8080        # 可选：自建元搜索

# --- 安全：三处必改 ---
PENTAGI_POSTGRES_PASSWORD=<强密码，见 7.3 策略>
COOKIE_SIGNING_SALT=<openssl rand -hex 24 生成>
LOCAL_SCRAPER_PASSWORD=<强密码>

# --- 地址 ---
PUBLIC_URL=https://pentagi.example.com
CORS_ORIGINS=https://pentagi.example.com
PENTAGI_LISTEN_IP=0.0.0.0               # 需要非本机访问时
TRUSTED_PROXIES=10.0.0.0/8              # 有反代时填代理网段

# --- 明确不启用的能力 ---
DOCKER_INSIDE=false                     # 无 DinD 需求保持关闭
PROXY_URL=                              # 出网可控环境留空

七、常见问题（含本批次实测排障）

7.1 改了 .env 不生效 / 容器监听在错误地址

实测根因：执行 docker compose up 的 shell 中残留全局环境变量 SERVER_HOST=127.0.0.1，按 3.1 的加载机制压过了 .env 的 SERVER_HOST=0.0.0.0，容器内进程只监听容器 loopback，宿主机 curl 返回 000。定位：docker compose config | grep SERVER_HOST 看渲染后的最终值；解决：清理 shell 变量或显式 SERVER_HOST=0.0.0.0 docker compose up -d，日志随后出现 listening on 0.0.0.0:8443。

7.2 custom LLM provider 启动报 embedder 错误

见 5.3 实测记录：LLM_SERVER_* 配好但 EMBEDDING_* 留空时，启动日志出现 embedder 初始化报错；将 EMBEDDING_URL/KEY/MODEL/PROVIDER 显式指向同一 OpenAI 兼容端点后消失。

7.3 数据库/登录密码被拒

PentAGI 有内置密码策略（源码 backend/pkg/password/policy.go）：至少 16 字符，或至少 8 字符且同时含大写、小写、数字、特殊字符（限 !@#$&*）。实测 q1w2e3r4 被拒（InvalidPassword），q1W2e3R4! 通过。该策略作用于 Web 首次注册改密；数据库口令同样建议达标。

7.4 找不到 termi_db 参数

v2.2.0 的 .env.example 中不存在 termi_db 参数（全文 grep 实证，仅 TERMINAL_TOOL_TIMEOUT 含相近词根）。若在旧资料中见到该名称，对应能力在 v2.2.0 中由 PENTAGI_POSTGRES_* 三件套与 DATABASE_URL 承担。

7.5 部署后外网访问不了

两层检查：宿主映射层 PENTAGI_LISTEN_IP（默认 127.0.0.1，只允许本机访问）与容器内监听层 SERVER_HOST（应为 0.0.0.0）。docker compose ps 看映射列：显示 127.0.0.1:8443->8443/tcp 即宿主侧只绑了回环。远程开放时建议配反代 + TRUSTED_PROXIES，避免直接暴露 8443。

7.6 配置代理后内网 LLM 网关也走代理

PROXY_URL 按官方注释作用于所有后端出站调用且不排除内网地址（见 5.9）。若代理不放行内网网段，需要在代理侧配置直连规则，或评估改为在容器层配置 HTTP_PROXY/NO_PROXY（注意两者作用面不同，PROXY_URL 只影响 PentAGI 后端进程）。

八、参考链接

• 官方仓库：vxcontrol/pentagi（v2.2.0 源码 .env.example、backend/docs/config.md）
• 官网：pentagi.com
• 本专栏系列：《PentAGI 介绍与选型指南》（组件定位与同类工具对比）、《PentAGI Docker Compose 部署指南》（部署步骤与挂载结构）、《PentAGI v2.2.0 API 使用详解》（REST/GraphQL 接口）