升级 — PentAGI

将安装更新到新版本，以及从 2.1.0 迁移到 2.2.0 时需要更改的内容。

更新会替换 PentAGI 镜像，如果发布版本更改了 compose 文件，也会替换它们。您的 .env 和数据卷保持不变，数据库迁移会在 PentAGI 启动时运行。

开始之前

阅读您运行版本之后的每个版本的发布说明；自 2.1.0 起，它们包含升级说明。
备份数据库。安装程序和 PentAGI 都不会执行此操作，且回滚迁移会导致数据丢失。使用默认的 PENTAGI_POSTGRES_USER 和 PENTAGI_POSTGRES_DB：
```
docker exec pgvector pg_dump -U postgres -Fc pentagidb > pentagi-backup.dump
```
同时保留 .env 和 compose 文件的副本：安装程序会在没有备份的情况下替换 compose 文件。
完成您不再需要的 flow。仍在运行的 sandbox 会按其创建时的状态重用，并使用创建它的发布版本的设置。
如果从 2.1.0 升级，请在新版本启动之前，按照从 2.1.0 到 2.2.0中的说明对 .env 及其旁边的文件进行更改。如果启用了 Google 或 GitHub 登录，请立即清空 OAUTH_GOOGLE_CLIENT_ID 和 OAUTH_GITHUB_CLIENT_ID；该部分解释了原因。

Docker Compose

在您的 .env 旁边下载新发布版本的 compose 文件：docker-compose.yml 以及您运行的每个可选堆栈的文件。PentAGI 容器仅接收其 compose 文件中列出的变量，因此 .env 中的新设置在较旧的文件后面不会生效。

cd ~/pentagi
curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/main/docker-compose.yml
# and the file of each optional stack you run, for example:
curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/main/docker-compose-langfuse.yml

拉取镜像并重启，使用您启动堆栈时使用的相同 -f 文件。如果没有 pull，up -d 会保留主机上已有的镜像。
```
docker compose pull && docker compose up -d
```
刷新运行 flow 的 Docker 主机上的 sandbox 镜像，docker compose pull 不会执行此操作。之后创建的 flow 将使用它。
```
docker pull vxcontrol/kali-linux
```

latest 镜像标签跟随主分支。要停留在一个发布版本上，请在 .env 中设置 PENTAGI_IMAGE=vxcontrol/pentagi:<version>。

安装程序

从快速入门下载新发布版本的安装程序，并使用您的 .env 运行它。2.1.0 安装程序无法自我更新。
要替换 compose 文件，请更改一个设置以使菜单中出现 Apply Changes，选择它，并在安装程序列出过时的文件时回答 y。
在维护菜单中，运行 Update PentAGI 以拉取新镜像，并在提供时运行 Update Worker Image。单独运行 Update PentAGI 会保留旧的 compose 文件。

从 2.1.0 到 2.2.0

文件

compose 文件在其旁边挂载 example.bedrock.provider.yml。安装程序会创建它；在手动安装时，请自行创建它，空文件即可：touch example.bedrock.provider.yml。
如果您运行 Langfuse，请替换 docker-compose-langfuse.yml：2.1.0 文件命名了 minio/minio 镜像，该镜像已不再发布，因此 docker compose pull 会与之一起失败。如果您的 .env 设置了 MINIO_IMAGE=minio/minio:…，请删除该行。
对于 knowledge graph，请将存储库中的 examples/neo4j 放在 ./neo4j — Graphiti 需要其 APOC plugin — 并查看记忆与知识了解模型预设。GRAPHITI_MODEL_NAME 不再被读取。
首次启动时会运行八个数据库迁移。docker compose logs pentagi 会在完成后显示“Database schema updated successfully”。

所有人都需要重新登录：2.1.0 的会话将被拒绝。API 令牌继续有效，脚本使用 POST /api/v1/auth/logout 注销。
API 令牌在 REST /users、/roles 和 /tokens 路由上会收到 403 错误：请从已登录的浏览器会话管理账户、角色和令牌。
Google 和 GitHub 登录现在会将提供商验证的电子邮件登录到具有该地址的现有账户（包括本地账户），并具有该账户的角色。2.1.0 无法更改账户的电子邮件，因此如果启用了登录，请使用空的 OAUTH_GOOGLE_CLIENT_ID 和 OAUTH_GITHUB_CLIENT_ID 进行升级，在 Settings → Account 下将 [email protected] 移动到您控制的地址，然后重新启用登录。安装程序的 Reset Admin Password 仅通过 [email protected] 查找管理员。
在反向代理后面，设置 TRUSTED_PROXIES，否则所有用户共享代理的地址，一次失败的登录突发会将所有人锁定 15 分钟 — 参见网络暴露。

Sandboxes

使用 DOCKER_INSIDE=true — 2.1.0 .env 模板和安装程序默认值 — 2.1.0 将主机 Docker socket 挂载到每个 sandbox 中。2.2.0 仅从 DOCKER_INSIDE_HOST 中的单独守护进程集为 agent 提供 Docker；如果没有它，他们什么也得不到，日志会说sandbox DISABLED。使用 DOCKER_INSIDE_HOST 时，将 DOCKER_SOCKET= 设置为空，否则仍会挂载模板的 /var/run/docker.sock。参见 Worker node。
完成在 2.1.0 上启动的 flow：它们的 sandbox 会保留旧的 socket 挂载和功能，直到 flow 完成。
将 TENANT_ID 留空：在现有安装上，它将 PentAGI 指向一个新的空模式。

模型和提示词

自定义 provider 需要 LLM_SERVER_KEY：使用空密钥会被禁用，因此对于没有身份验证的服务器，设置任何非空值。
LLM_SERVER_LEGACY_REASONING 已被移除。自定义 provider 发送 reasoning_effort 并将 reasoning.max_tokens 预算转换为努力级别；在 Kimi K2、5.2 之前的 GLM 和 MiniMax M 模型上，预算现在会导致调用失败，因此请从这些 agent 中移除它。
在 provider 配置文件中，留下 max_tokens、temperature、top_p 或 n 为空的 agent 条目现在会获取 provider 类型的默认值，而不是发送空值。
除 Bedrock 外，每个 provider 的内置默认模型都已更改；保存在 Settings → Providers 中的 provider 保留其模型。镜像中捆绑的五个配置文件更改了模型 — openrouter、deepinfra、ollama-cloud、moonshot 和 deepseek。如果 LLM_SERVER_CONFIG_PATH 或 OLLAMA_SERVER_CONFIG_PATH 在 /opt/pentagi/conf/ 下指向其中之一，请在主机上保留 2.1.0 文件，并将其作为自定义或 Ollama 配置挂载。
在 OpenAI 以外的服务器上使用 EMBEDDING_URL 时，设置 EMBEDDING_KEY：OPEN_AI_KEY 不再发送到那里。
Agent 通过一个 web_search tool 进行搜索。带有 {{.GoogleToolName}} 和其他每个引擎变量的自定义提示词将被忽略，并在日志中发出警告，直到它们使用 {{.WebSearchToolName}}；基于新的默认值重新制定自定义 searcher 和 pentester 提示词。

其他更改

在启动后两分钟内以及之后每三小时，PentAGI 会向 update.pentagi.com 报告其版本和安装摘要；更新检查列出了它发送的内容，UPDATE_CHECK_INTERVAL=0 将其关闭。
除非设置了 PPROF_ADDR，否则 profiler 不再监听端口 7777。
新的可选设置包括带有 LLM_FALLBACK_PROVIDER 的 provider 故障转移、用于多个实例的 DOCKER_PORTS_BASE、DOCKER_IMAGE_SELECTION_MODE 和 DOCKER_ALLOWED_IMAGES、内部 search engine WEB_SEARCH_INTERNAL_ENABLED，以及 Mistral、xAI、MiniMax 和 Firecrawl 密钥。

备份和回滚

PentAGI 永远不会反向运行迁移，手动运行它们会删除数据，因此回到 2.1.0 的方法是使用备份。停止使用数据库的服务，重新创建它并恢复转储：

docker compose stop pentagi pgexporter
docker exec pgvector dropdb -U postgres pentagidb
docker exec pgvector createdb -U postgres pentagidb
docker exec -i pgvector pg_restore -U postgres -d pentagidb < pentagi-backup.dump

然后恢复保存的 .env 和 compose 文件，设置 PENTAGI_IMAGE=vxcontrol/pentagi:2.1.0 并启动栈。保留新的 docker-compose-langfuse.yml：2.1.0 文件中的 MinIO 镜像已无法拉取。