Docker升级坑点汇总，非 Bug 反馈

标题：Docker 升级坑点汇总，非 Bug 反馈

**例行检查**

[//]: # "方框内填 x 表示打钩"

* [ ] 我已确认目前没有类似 issue
* [x] 我已完整查看过项目 README，以及[[项目文档](https://doc.fastgpt.io/introduction/)](https://doc.fastgpt.io/introduction/)
* [x] 我使用了自己的 key，并确认 key 可正常使用
* [x] 我理解并愿意跟进此 issue，协助测试和提供反馈
* [x] 我理解并认可上述内容，并理解项目维护者精力有限，**不遵循规则的 issue 可能会被无视或直接关闭**

**你的版本**

* [ ] 公有云版本
* [x] 私有部署版本，具体版本号：

```text
Docker Compose 部署
升级路径：
v4.14.x → v4.14.22 → v4.15.0-beta1 → v4.15.0-beta2
```

相关组件版本：

```text
FastGPT：v4.15.0-beta2
FastGPT Pro：v4.15.0-beta2
FastGPT Plugin：v0.6.2
AIProxy：v0.5.6
Agent Sandbox：v0.2.0
Agent Volume Manager：v0.2.0
```

**问题描述、日志截图、配置文件等**

本次在测试环境使用 Docker Compose 逐步升级，过程中遇到了一些配置兼容和部署注意事项。大部分不是程序 Bug，但如果仅修改镜像 tag，比较容易出现服务启动失败、502、文件上传失败或虚拟机不可用等问题。

整理如下，供其他私有部署用户参考。

### 1. FastGPT 主服务监听地址

升级后，Next.js 可能只监听容器内部某个 IP，导致：

```text
curl: Recv failure: Connection reset by peer
502 Bad Gateway
```

需要在 FastGPT 主服务中明确配置：

```yaml
environment:
- HOSTNAME=0.0.0.0
```

如果 FastGPT Pro 也存在相同监听问题，可以给 Pro 同样配置。

### 2. beta 版本加强了环境变量校验

升级后，如果必填变量缺失或格式不符合要求，服务会持续提示：

```text
Invalid environment variables
System initialization failed
```

FastGPT 与 FastGPT Pro 需要重点检查：

```yaml
environment:
- TOKEN_KEY=<自定义安全值>
- AES256_SECRET_KEY=<自定义安全值>
- FILE_TOKEN_KEY=<自定义安全值>
```

注意事项：

* FastGPT 和 FastGPT Pro 中的相关密钥需要保持一致。
* 不要直接复制示例中的默认值到生产环境。
* 不要使用过短或过于简单的值。
* 升级前检查同一服务中是否重复配置了同名环境变量。
* Compose 列表中出现重复变量时，后面的值可能覆盖前面的值，但会增加排查难度。

### 3. `SYNC_INDEX` 参数格式变化

新版本中应使用布尔字符串：

```yaml
- SYNC_INDEX=true
```

或：

```yaml
- SYNC_INDEX=false
```

不建议继续使用：

```yaml
- SYNC_INDEX=1
- SYNC_INDEX=0
```

如果 MongoDB 中已经存在重复数据，启用索引同步可能出现：

```text
E11000 duplicate key error
index: appId_1_chatId_1
```

此错误在本次环境中没有阻止系统完成初始化，但会导致唯一索引创建失败。建议先清理重复数据，再开启自动索引同步。

### 4. AIProxy PostgreSQL 共享内存不足

升级 AIProxy 后，执行日志清理或 `VACUUM ANALYZE` 时出现：

```text
could not resize shared memory segment
No space left on device
```

该错误不一定是宿主机磁盘不足，而可能是 PostgreSQL 容器默认 `/dev/shm` 只有 64MiB。

可以在 `aiproxy_pg` 服务中增加：

```yaml
aiproxy_pg:
shm_size: "256mb"
```

修改后需要重建 `aiproxy_pg` 容器。

### 5. Pro 后台文件上传接口路由

在 Pro 管理后台上传头像或文件时，请求路径可能是：

```text
/api/system/file/upload/
```

如果 Pro 域名的 Nginx 将全部请求都代理到 FastGPT Pro，这个上传接口可能返回 404。

需要将该路径单独转发到 FastGPT 主服务，例如：

```nginx
location ^~ /api/system/file/upload/ {
proxy_pass http://;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_buffering off;
}
```

其中 `` 替换为实际的 FastGPT 主服务地址。

### 6. 容器重建后 Nginx 可能缓存旧容器地址

使用 Docker Compose 重建 FastGPT 或 FastGPT Pro 后，容器 IP 可能变化。

如果 Nginx 使用服务名代理，但没有及时重新解析，外部访问可能暂时出现：

```text
502 Bad Gateway
```

此时可以重启 Nginx 容器，让其重新解析上游服务地址。

### 7. beta2 沙盒组件需要配套升级

升级到 beta2 时，除了 FastGPT 和 FastGPT Pro，还需要同步调整：

```text
fastgpt-agent-sandbox:v0.2.0
fastgpt-agent-volume-manager:v0.2.0
```

FastGPT 环境变量中的沙盒镜像 tag 也需要同步更新：

```yaml
- AGENT_SANDBOX_OPENSANDBOX_IMAGE_TAG=v0.2.0
```

只升级 FastGPT 主服务，而未更新配套沙盒组件，可能导致功能不兼容。

### 8. OpenSandbox API Key 两端必须一致

如果仅部署了 OpenSandbox 服务，但没有配置 API Key，FastGPT 可能识别不到虚拟机配置，前端提示：

```text
当前系统未配置虚拟机，暂时无法使用相关功能
```

OpenSandbox 配置示例：

```toml
[server]
host = "0.0.0.0"
port = 8090
api_key = "<自定义安全值>"
```

FastGPT 环境变量：

```yaml
- AGENT_SANDBOX_PROVIDER=opensandbox
- AGENT_SANDBOX_OPENSANDBOX_BASEURL=http://opensandbox-server:8090
- AGENT_SANDBOX_OPENSANDBOX_API_KEY=<与服务端一致的值>
```

注意：

* API Key 不要使用文档示例值。
* 不要在 issue、日志截图或配置文件中公开实际值。
* OpenSandbox 服务端和 FastGPT 客户端的值必须一致。

### 9. OpenSandbox 实际监听端口不要只看镜像声明

容器镜像可能显示暴露了某个端口，但实际服务监听端口由配置文件决定。

本次环境中：

```toml
[server]
port = 8090
```

因此 FastGPT 应连接：

```yaml
- AGENT_SANDBOX_OPENSANDBOX_BASEURL=http://opensandbox-server:8090
```

建议通过容器内实际访问确认，不要只根据 `docker ps` 中的 `EXPOSE` 信息判断。

### 10. OpenSandbox 自定义网络与 `networkPolicy` 冲突

虚拟机功能已经显示，但创建 Sandbox 时出现：

```text
Failed to create sandbox
```

FastGPT 日志中的实际原因是：

```text
networkPolicy is not supported when docker network_mode is a user-defined network.
Use network_mode='bridge' to enable network policy enforcement.
```

OpenSandbox 创建沙盒时，如果请求中包含 `networkPolicy`，Docker runtime 不能使用自定义网络名称。

需要在 `opensandbox-config.toml` 中配置：

```toml
[docker]
network_mode = "bridge"
```

注意：

* 这里修改的是 OpenSandbox 创建出来的运行时沙盒容器网络模式。
* 不代表需要删除 `opensandbox-server` 自身在 Docker Compose 中加入的业务网络。
* 修改后只需重建 OpenSandbox Server，再重新创建 Sandbox。

### 11. Agent Volume Manager 正常不代表 Sandbox 一定能创建

本次排查中，Volume Manager 日志已经显示卷创建成功：

```text
POST /v1/volumes/ensure
created=true
status=201
```

但 OpenSandbox 创建运行时容器仍然返回 400。

因此，排查 `Failed to create sandbox` 时需要分别查看：

```text
FastGPT 日志
OpenSandbox Server 日志
Agent Volume Manager 日志
Docker 新建容器状态
```

不能仅根据 Volume Manager 成功判断整个 Sandbox 链路正常。

### 12. 启动瞬间的连接失败不一定是升级失败

重建 FastGPT 或 FastGPT Pro 后，前几次访问可能出现：

```text
Connection reset by peer
Operation timed out
HTTP 000
```

等待初始化完成后可能恢复为 HTTP 200。

建议使用循环健康检查，而不是在容器刚启动时根据第一次请求直接回滚。

### 13. Redis 启动阶段可能出现短暂重连日志

FastGPT 初始化完成后，可能短时间出现：

```text
Redis reconnecting
```

如果 Redis 容器状态为 healthy，FastGPT 后续运行正常，并且日志不持续增长，可以先观察，不一定代表 Redis 故障。

### 14. Docker Compose 的 `version` 字段警告

新版 Docker Compose 会提示：

```text
the attribute `version` is obsolete
```

该警告不会阻止服务启动，但可以在后续维护时移除 Compose 文件顶层的 `version` 字段，避免干扰排查。

**复现步骤**

1. 使用较旧版本的 Docker Compose 配置部署 FastGPT。
2. 仅修改 FastGPT、FastGPT Pro、Plugin、AIProxy 等镜像 tag。
3. 未同步更新环境变量校验要求、沙盒组件版本和 OpenSandbox 配置。
4. 依次测试：

* FastGPT 主站
* FastGPT Pro 管理后台
* 文件上传
* AIProxy
* Agent Skill
* OpenSandbox 虚拟机
5. 可能出现：

* 主服务连接重置
* Nginx 502
* 环境变量校验失败
* 文件上传 404
* PostgreSQL 共享内存不足
* 虚拟机功能不显示
* `Failed to create sandbox`
* OpenSandbox 创建接口返回 400

**预期结果**

希望升级文档可以增加一份 Docker Compose 升级检查清单，至少提示以下内容：

```text
1. FastGPT 和 Pro 的 HOSTNAME 监听配置
2. TOKEN_KEY、AES256_SECRET_KEY、FILE_TOKEN_KEY 的必填和一致性
3. 环境变量重复项检查
4. SYNC_INDEX 新的布尔格式
5. MongoDB 重复数据对唯一索引的影响
6. AIProxy PostgreSQL 的 shm_size
7. beta2 沙盒组件需要配套升级
8. OpenSandbox API Key 两端一致
9. OpenSandbox 实际监听端口
10. networkPolicy 与 Docker network_mode 的限制
11. Pro 文件上传接口应代理到 FastGPT 主服务
12. Docker 容器重建后 Nginx 上游地址刷新
```

以上内容主要是升级和部署经验汇总，不一定属于产品 Bug，希望可以作为文档补充或其他私有部署用户的参考。