升級 — 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 會以其建立時的設定（即建立該 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 映像檔標籤會追蹤 main 分支。若要停留在單一發行版本，請在 .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 — 並參閱記憶體與知識以了解 model presets。GRAPHITI_MODEL_NAME 不再被讀取。
首次啟動時會執行八個資料庫遷移。docker compose logs pentagi 會在完成時顯示 "Database schema updated successfully"。

所有人都必須重新登入：來自 2.1.0 的工作階段會被拒絕。API token 繼續有效，且腳本會使用 POST /api/v1/auth/logout 登出。
API token 在 REST /users、/roles 和 /tokens 路徑上會收到 403 錯誤：請從已登入的瀏覽器工作階段管理帳戶、角色和 token。
Google 和 GitHub 登入現在會將 provider 驗證過的電子郵件簽署進入具有該地址的現有帳戶（包括本機帳戶），並使用该帳戶的角色。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 template 和安裝程式預設值 — 2.1.0 將主機 Docker socket 掛載到每個 sandbox 中。2.2.0 僅從 DOCKER_INSIDE_HOST 中設定的獨立 daemon set 為 agent 提供 Docker；若無此設定，他們將無法獲得任何 Docker，且日誌會顯示 sandbox DISABLED。使用 DOCKER_INSIDE_HOST 時，請將 DOCKER_SOCKET= 設為空，否則仍會掛載 template 的 /var/run/docker.sock。請參閱 worker node。
完成在 2.1.0 上啟動的 flow：他們的 sandbox 會保留舊的 socket 掛載和功能，直到 flow 完成為止。
將 TENANT_ID 留空：在現有安裝中，它會將 PentAGI 指向一個新的、空的 schema。

Models 和 prompts

自訂 provider 需要 LLM_SERVER_KEY：若金鑰為空，則會被停用，因此對於沒有身份驗證的伺服器，請設定任何非空值。
LLM_SERVER_LEGACY_REASONING 已被移除。自訂 provider 會發送 reasoning_effort 並將 reasoning.max_tokens 預算轉換為努力等級；在 Kimi K2、5.2 之前的 GLM 和 MiniMax M models 上，預算現在會導致 call 失敗，因此請從這些 agent 中移除它。
在 provider 組態檔中，若 agent 條目將 max_tokens、temperature、top_p 或 n 留空，現在會取得 provider type 的預設值，而不是發送空值。
除 Bedrock 外，每個 provider 的內建預設 models 都已變更；儲存在 Settings → Providers 中的 providers 會保留其 models。映像檔中綁定的五個組態已變更 models — openrouter、deepinfra、ollama-cloud、moonshot 和 deepseek。若 LLM_SERVER_CONFIG_PATH 或 OLLAMA_SERVER_CONFIG_PATH 在 /opt/pentagi/conf/ 下指向其中一個，請在主機上保留 2.1.0 檔案，並將其作為 custom 或 Ollama 組態掛載。
在 OpenAI 以外的伺服器上使用 EMBEDDING_URL 時，請設定 EMBEDDING_KEY：OPEN_AI_KEY 不再發送到那裡。
Agents 透過一個 web_search tool 進行搜尋。帶有 {{.GoogleToolName}} 和其他每個引擎變數的自訂 prompts 會被忽略，並在日誌中發出警告，直到它們使用 {{.WebSearchToolName}}；基於新的預設值重新調整自訂 searcher 和 pentester prompts。

其他變更

在啟動後兩分鐘內，以及之後每三小時，PentAGI 會向 update.pentagi.com 報告其版本和安裝摘要；更新檢查列出了它發送的內容，而 UPDATE_CHECK_INTERVAL=0 會將其關閉。
除非設定了 PPROF_ADDR，否則 profiler 不再監聽埠 7777。
新的可選設定包括帶有 LLM_FALLBACK_PROVIDER 的 provider failover、用於多個實例的 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 映像檔已無法再被拉取。