# 升級

> 將安裝更新至新版本，以及從 2.1.0 遷移至 2.2.0 時需要變更的事項。

更新會替換 PentAGI 映像檔，並在發行版本變更時替換 compose 檔案。您的 `.env` 和資料卷會保留，且資料庫遷移會在 PentAGI 啟動時執行。

## [開始之前](https://pentagi.com/zh-tw/docs/deployment/upgrade/#before-you-start)

* 閱讀您目前執行版本之後每個版本的[發行說明](https://pentagi.com/changelog/)；自 2.1.0 版起，其中包含升級注意事項。
* 備份資料庫。安裝程式和 PentAGI 都不會執行此操作，且無法在不遺失資料的情況下復原遷移。使用預設的 `PENTAGI_POSTGRES_USER` 和 `PENTAGI_POSTGRES_DB`：

  ```bash
  docker exec pgvector pg_dump -U postgres -Fc pentagidb > pentagi-backup.dump
  ```

  同時保留 `.env` 和 compose 檔案的副本：安裝程式會在沒有備份的情況下替換 compose 檔案。
* 完成您不再需要的 [flow](https://pentagi.com/zh-tw/docs/glossary/#flow)。仍在執行的 [sandbox](https://pentagi.com/zh-tw/docs/glossary/#sandbox) 會以其建立時的設定（即建立該 sandbox 的發行版本設定）被重複使用。
* 若從 2.1.0 升級，請在新版本啟動前，依照 [從 2.1.0 到 2.2.0](#from-210-to-220) 中的說明，對 `.env` 及其相鄰檔案進行變更。若已啟用 Google 或 GitHub 登入，請現在清空 `OAUTH_GOOGLE_CLIENT_ID` 和 `OAUTH_GITHUB_CLIENT_ID`；該章節說明了原因。

## [Docker Compose](https://pentagi.com/zh-tw/docs/deployment/upgrade/#docker-compose)

1. 在您的 `.env` 旁邊下載新發行版本的 compose 檔案：`docker-compose.yml` 以及您執行的每個可選堆疊的檔案。PentAGI 容器僅接收其 compose 檔案中列出的變數，因此 `.env` 中的新設定若透過較舊的檔案則不會生效。

   ```bash
   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
   ```

2. 拉取映像檔並重新啟動，使用您啟動堆疊時相同的 `-f` 檔案。若不使用 `pull`，`up -d` 會保留主機上已有的映像檔。

   ```bash
   docker compose pull && docker compose up -d
   ```

3. 在執行 flow 的 Docker 主機上刷新 sandbox 映像檔，`docker compose pull` 不會執行此操作。之後建立的 flow 將使用它。

   ```bash
   docker pull vxcontrol/kali-linux
   ```

`latest` 映像檔標籤會追蹤 main 分支。若要停留在單一發行版本，請在 `.env` 中設定 `PENTAGI_IMAGE=vxcontrol/pentagi:<version>`。

## [安裝程式](https://pentagi.com/zh-tw/docs/deployment/upgrade/#installer)

1. 從 [快速入門](https://pentagi.com/zh-tw/docs/getting-started/quickstart/) 下載新發行版本的安裝程式，並使用您的 `.env` 執行它。2.1.0 安裝程式無法更新自身。
2. 若要替換 compose 檔案，請變更設定以使選單中出現 **Apply Changes**，選擇它，並在安裝程式列出過期檔案時回答 `y`。
3. 在維護選單中，執行 **Update PentAGI** 以拉取新映像檔，並在提供時執行 **Update Worker Image**。單獨執行 **Update PentAGI** 會保留舊的 compose 檔案。

## [從 2.1.0 到 2.2.0](https://pentagi.com/zh-tw/docs/deployment/upgrade/#from-210-to-220)

### [檔案](https://pentagi.com/zh-tw/docs/deployment/upgrade/#files)

* 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](https://pentagi.com/zh-tw/docs/glossary/#knowledge-graph)，請將儲存庫中的 `examples/neo4j` 放置於 `./neo4j` — Graphiti 需要其 APOC plugin — 並參閱 [記憶體與知識](https://pentagi.com/zh-tw/docs/concepts/memory/#knowledge-graph-optional) 以了解 model presets。`GRAPHITI_MODEL_NAME` 不再被讀取。
* 首次啟動時會執行八個資料庫遷移。`docker compose logs pentagi` 會在完成時顯示 "Database schema updated successfully"。

### [登入與存取](https://pentagi.com/zh-tw/docs/deployment/upgrade/#sign-in-and-access)

* 所有人都必須重新登入：來自 2.1.0 的工作階段會被拒絕。API token 繼續有效，且腳本會使用 `POST /api/v1/auth/logout` 登出。
* API token 在 REST `/users`、`/roles` 和 `/tokens` 路徑上會收到 403 錯誤：請從已登入的瀏覽器工作階段管理帳戶、角色和 token。
* Google 和 GitHub 登入現在會將 [provider](https://pentagi.com/zh-tw/docs/glossary/#provider) 驗證過的電子郵件簽署進入具有該地址的現有帳戶（包括本機帳戶），並使用该帳戶的角色。2.1.0 無法變更帳戶的電子郵件，因此若啟用了登入功能，請使用空的 `OAUTH_GOOGLE_CLIENT_ID` 和 `OAUTH_GITHUB_CLIENT_ID` 進行升級，在 **Settings → Account** 下將 `admin@pentagi.com` 移至您控制的地址，然後重新開啟登入功能。安裝程式的 **Reset Admin Password** 僅透過 `admin@pentagi.com` 尋找管理員。
* 在反向代理後面，請設定 `TRUSTED_PROXIES`，否則所有使用者將共用代理的地址，且一次突發的登入失敗會讓所有人被鎖定 15 分鐘 — 請參閱 [網路暴露](https://pentagi.com/zh-tw/docs/configuration/security/#network-exposure)。

### [Sandboxes](https://pentagi.com/zh-tw/docs/deployment/upgrade/#sandboxes)

* 使用 `DOCKER_INSIDE=true` — 2.1.0 `.env` template 和安裝程式預設值 — 2.1.0 將主機 Docker socket 掛載到每個 sandbox 中。2.2.0 僅從 `DOCKER_INSIDE_HOST` 中設定的獨立 daemon set 為 [agent](https://pentagi.com/zh-tw/docs/glossary/#agent) 提供 Docker；若無此設定，他們將無法獲得任何 Docker，且日誌會顯示 `sandbox DISABLED`。使用 `DOCKER_INSIDE_HOST` 時，請將 `DOCKER_SOCKET=` 設為空，否則仍會掛載 template 的 `/var/run/docker.sock`。請參閱 [worker node](https://pentagi.com/zh-tw/docs/deployment/worker-node/)。
* 完成在 2.1.0 上啟動的 flow：他們的 sandbox 會保留舊的 socket 掛載和功能，直到 flow 完成為止。
* 將 `TENANT_ID` 留空：在現有安裝中，它會將 PentAGI 指向一個新的、空的 schema。

### [Models 和 prompts](https://pentagi.com/zh-tw/docs/deployment/upgrade/#models-and-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](https://pentagi.com/zh-tw/docs/glossary/#tool) 進行搜尋。帶有 `{{.GoogleToolName}}` 和其他每個引擎變數的自訂 prompts 會被忽略，並在日誌中發出警告，直到它們使用 `{{.WebSearchToolName}}`；基於新的預設值重新調整自訂 searcher 和 pentester prompts。

### [其他變更](https://pentagi.com/zh-tw/docs/deployment/upgrade/#other-changes)

* 在啟動後兩分鐘內，以及之後每三小時，PentAGI 會向 `update.pentagi.com` 報告其版本和安裝摘要；[更新檢查](https://pentagi.com/zh-tw/docs/configuration/security/#update-check) 列出了它發送的內容，而 `UPDATE_CHECK_INTERVAL=0` 會將其關閉。
* 除非設定了 `PPROF_ADDR`，否則 profiler 不再監聽埠 7777。
* 新的可選設定包括帶有 `LLM_FALLBACK_PROVIDER` 的 [provider failover](https://pentagi.com/zh-tw/docs/configuration/llm-providers/#failover)、用於 [多個實例](https://pentagi.com/zh-tw/docs/deployment/production/#several-instances-tenant_id) 的 `DOCKER_PORTS_BASE`、`DOCKER_IMAGE_SELECTION_MODE` 和 `DOCKER_ALLOWED_IMAGES`、內部 [search engine](https://pentagi.com/zh-tw/docs/glossary/#search-engine) `WEB_SEARCH_INTERNAL_ENABLED`，以及 Mistral、xAI、MiniMax 和 Firecrawl 金鑰。

## [備份與復原](https://pentagi.com/zh-tw/docs/deployment/upgrade/#back-up-and-roll-back)

PentAGI 永遠不會反向執行遷移，手動執行遷移會刪除資料，因此回到 2.1.0 的方法是備份。停止使用資料庫的服務，重新建立資料庫並還原匯出檔：

```bash
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 映像檔已無法再被拉取。