# 升级

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

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

## [开始之前](https://pentagi.com/zh-cn/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-cn/docs/glossary/#flow)。仍在运行的 [sandbox](https://pentagi.com/zh-cn/docs/glossary/#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-cn/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` 镜像标签跟随主分支。要停留在一个发布版本上，请在 `.env` 中设置 `PENTAGI_IMAGE=vxcontrol/pentagi:<version>`。

## [安装程序](https://pentagi.com/zh-cn/docs/deployment/upgrade/#installer)

1. 从 [快速入门](https://pentagi.com/zh-cn/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-cn/docs/deployment/upgrade/#from-210-to-220)

### [文件](https://pentagi.com/zh-cn/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-cn/docs/glossary/#knowledge-graph)，请将存储库中的 `examples/neo4j` 放在 `./neo4j` — Graphiti 需要其 APOC plugin — 并查看 [记忆与知识](https://pentagi.com/zh-cn/docs/concepts/memory/#knowledge-graph-optional) 了解模型预设。`GRAPHITI_MODEL_NAME` 不再被读取。
* 首次启动时会运行八个数据库迁移。`docker compose logs pentagi` 会在完成后显示“Database schema updated successfully”。

### [登录和访问](https://pentagi.com/zh-cn/docs/deployment/upgrade/#sign-in-and-access)

* 所有人都需要重新登录：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** 下将 `admin@pentagi.com` 移动到您控制的地址，然后重新启用登录。安装程序的 **Reset Admin Password** 仅通过 `admin@pentagi.com` 查找管理员。
* 在反向代理后面，设置 `TRUSTED_PROXIES`，否则所有用户共享代理的地址，一次失败的登录突发会将所有人锁定 15 分钟 — 参见 [网络暴露](https://pentagi.com/zh-cn/docs/configuration/security/#network-exposure)。

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

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

### [模型和提示词](https://pentagi.com/zh-cn/docs/deployment/upgrade/#models-and-prompts)

* 自定义 [provider](https://pentagi.com/zh-cn/docs/glossary/#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](https://pentagi.com/zh-cn/docs/glossary/#tool) 进行搜索。带有 `{{.GoogleToolName}}` 和其他每个引擎变量的自定义提示词将被忽略，并在日志中发出警告，直到它们使用 `{{.WebSearchToolName}}`；基于新的默认值重新制定自定义 searcher 和 pentester 提示词。

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

* 在启动后两分钟内以及之后每三小时，PentAGI 会向 `update.pentagi.com` 报告其版本和安装摘要；[更新检查](https://pentagi.com/zh-cn/docs/configuration/security/#update-check) 列出了它发送的内容，`UPDATE_CHECK_INTERVAL=0` 将其关闭。
* 除非设置了 `PPROF_ADDR`，否则 profiler 不再监听端口 7777。
* 新的可选设置包括带有 `LLM_FALLBACK_PROVIDER` 的 [provider 故障转移](https://pentagi.com/zh-cn/docs/configuration/llm-providers/#failover)、用于 [多个实例](https://pentagi.com/zh-cn/docs/deployment/production/#several-instances-tenant_id) 的 `DOCKER_PORTS_BASE`、`DOCKER_IMAGE_SELECTION_MODE` 和 `DOCKER_ALLOWED_IMAGES`、内部 [search engine](https://pentagi.com/zh-cn/docs/glossary/#search-engine) `WEB_SEARCH_INTERNAL_ENABLED`，以及 Mistral、xAI、MiniMax 和 Firecrawl 密钥。

## [备份和回滚](https://pentagi.com/zh-cn/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 镜像已无法拉取。