标题：Docker 升级坑点汇总，非 Bug 反馈
例行检查
你的版本
Docker Compose 部署
升级路径：
v4.14.x → v4.14.22 → v4.15.0-beta1 → v4.15.0-beta2
相关组件版本：
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，导致：
curl: Recv failure: Connection reset by peer
502 Bad Gateway
需要在 FastGPT 主服务中明确配置：
environment:
- HOSTNAME=0.0.0.0
如果 FastGPT Pro 也存在相同监听问题，可以给 Pro 同样配置。
2. beta 版本加强了环境变量校验
升级后，如果必填变量缺失或格式不符合要求，服务会持续提示：
Invalid environment variables
System initialization failed
FastGPT 与 FastGPT Pro 需要重点检查：
environment:
- TOKEN_KEY=<自定义安全值>
- AES256_SECRET_KEY=<自定义安全值>
- FILE_TOKEN_KEY=<自定义安全值>
注意事项：
- FastGPT 和 FastGPT Pro 中的相关密钥需要保持一致。
- 不要直接复制示例中的默认值到生产环境。
- 不要使用过短或过于简单的值。
- 升级前检查同一服务中是否重复配置了同名环境变量。
- Compose 列表中出现重复变量时，后面的值可能覆盖前面的值，但会增加排查难度。
3. SYNC_INDEX 参数格式变化
新版本中应使用布尔字符串：
或：
不建议继续使用：
- SYNC_INDEX=1
- SYNC_INDEX=0
如果 MongoDB 中已经存在重复数据，启用索引同步可能出现：
E11000 duplicate key error
index: appId_1_chatId_1
此错误在本次环境中没有阻止系统完成初始化，但会导致唯一索引创建失败。建议先清理重复数据，再开启自动索引同步。
4. AIProxy PostgreSQL 共享内存不足
升级 AIProxy 后，执行日志清理或 VACUUM ANALYZE 时出现：
could not resize shared memory segment
No space left on device
该错误不一定是宿主机磁盘不足，而可能是 PostgreSQL 容器默认 /dev/shm 只有 64MiB。
可以在 aiproxy_pg 服务中增加：
aiproxy_pg:
shm_size: "256mb"
修改后需要重建 aiproxy_pg 容器。
5. Pro 后台文件上传接口路由
在 Pro 管理后台上传头像或文件时，请求路径可能是：
如果 Pro 域名的 Nginx 将全部请求都代理到 FastGPT Pro，这个上传接口可能返回 404。
需要将该路径单独转发到 FastGPT 主服务，例如：
location ^~ /api/system/file/upload/ {
proxy_pass http://<FASTGPT_MAIN_SERVICE>;
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_MAIN_SERVICE> 替换为实际的 FastGPT 主服务地址。
6. 容器重建后 Nginx 可能缓存旧容器地址
使用 Docker Compose 重建 FastGPT 或 FastGPT Pro 后，容器 IP 可能变化。
如果 Nginx 使用服务名代理，但没有及时重新解析，外部访问可能暂时出现：
此时可以重启 Nginx 容器，让其重新解析上游服务地址。
7. beta2 沙盒组件需要配套升级
升级到 beta2 时，除了 FastGPT 和 FastGPT Pro，还需要同步调整：
fastgpt-agent-sandbox:v0.2.0
fastgpt-agent-volume-manager:v0.2.0
FastGPT 环境变量中的沙盒镜像 tag 也需要同步更新：
- AGENT_SANDBOX_OPENSANDBOX_IMAGE_TAG=v0.2.0
只升级 FastGPT 主服务，而未更新配套沙盒组件，可能导致功能不兼容。
8. OpenSandbox API Key 两端必须一致
如果仅部署了 OpenSandbox 服务，但没有配置 API Key，FastGPT 可能识别不到虚拟机配置，前端提示：
OpenSandbox 配置示例：
[server]
host = "0.0.0.0"
port = 8090
api_key = "<自定义安全值>"
FastGPT 环境变量：
- AGENT_SANDBOX_PROVIDER=opensandbox
- AGENT_SANDBOX_OPENSANDBOX_BASEURL=http://opensandbox-server:8090
- AGENT_SANDBOX_OPENSANDBOX_API_KEY=<与服务端一致的值>
注意：
- API Key 不要使用文档示例值。
- 不要在 issue、日志截图或配置文件中公开实际值。
- OpenSandbox 服务端和 FastGPT 客户端的值必须一致。
9. OpenSandbox 实际监听端口不要只看镜像声明
容器镜像可能显示暴露了某个端口，但实际服务监听端口由配置文件决定。
本次环境中：
因此 FastGPT 应连接：
- AGENT_SANDBOX_OPENSANDBOX_BASEURL=http://opensandbox-server:8090
建议通过容器内实际访问确认，不要只根据 docker ps 中的 EXPOSE 信息判断。
10. OpenSandbox 自定义网络与 networkPolicy 冲突
虚拟机功能已经显示，但创建 Sandbox 时出现：
FastGPT 日志中的实际原因是：
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 中配置：
[docker]
network_mode = "bridge"
注意：
- 这里修改的是 OpenSandbox 创建出来的运行时沙盒容器网络模式。
- 不代表需要删除
opensandbox-server 自身在 Docker Compose 中加入的业务网络。
- 修改后只需重建 OpenSandbox Server，再重新创建 Sandbox。
11. Agent Volume Manager 正常不代表 Sandbox 一定能创建
本次排查中，Volume Manager 日志已经显示卷创建成功：
POST /v1/volumes/ensure
created=true
status=201
但 OpenSandbox 创建运行时容器仍然返回 400。
因此，排查 Failed to create sandbox 时需要分别查看：
FastGPT 日志
OpenSandbox Server 日志
Agent Volume Manager 日志
Docker 新建容器状态
不能仅根据 Volume Manager 成功判断整个 Sandbox 链路正常。
12. 启动瞬间的连接失败不一定是升级失败
重建 FastGPT 或 FastGPT Pro 后，前几次访问可能出现：
Connection reset by peer
Operation timed out
HTTP 000
等待初始化完成后可能恢复为 HTTP 200。
建议使用循环健康检查，而不是在容器刚启动时根据第一次请求直接回滚。
13. Redis 启动阶段可能出现短暂重连日志
FastGPT 初始化完成后，可能短时间出现：
如果 Redis 容器状态为 healthy，FastGPT 后续运行正常，并且日志不持续增长，可以先观察，不一定代表 Redis 故障。
14. Docker Compose 的 version 字段警告
新版 Docker Compose 会提示：
the attribute `version` is obsolete
该警告不会阻止服务启动，但可以在后续维护时移除 Compose 文件顶层的 version 字段，避免干扰排查。
复现步骤
-
使用较旧版本的 Docker Compose 配置部署 FastGPT。
-
仅修改 FastGPT、FastGPT Pro、Plugin、AIProxy 等镜像 tag。
-
未同步更新环境变量校验要求、沙盒组件版本和 OpenSandbox 配置。
-
依次测试：
- FastGPT 主站
- FastGPT Pro 管理后台
- 文件上传
- AIProxy
- Agent Skill
- OpenSandbox 虚拟机
-
可能出现：
- 主服务连接重置
- Nginx 502
- 环境变量校验失败
- 文件上传 404
- PostgreSQL 共享内存不足
- 虚拟机功能不显示
Failed to create sandbox- OpenSandbox 创建接口返回 400
预期结果
希望升级文档可以增加一份 Docker Compose 升级检查清单，至少提示以下内容：
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，希望可以作为文档补充或其他私有部署用户的参考。
标题：Docker 升级坑点汇总，非 Bug 反馈
例行检查
你的版本
相关组件版本：
问题描述、日志截图、配置文件等
本次在测试环境使用 Docker Compose 逐步升级，过程中遇到了一些配置兼容和部署注意事项。大部分不是程序 Bug，但如果仅修改镜像 tag，比较容易出现服务启动失败、502、文件上传失败或虚拟机不可用等问题。
整理如下，供其他私有部署用户参考。
1. FastGPT 主服务监听地址
升级后，Next.js 可能只监听容器内部某个 IP，导致：
需要在 FastGPT 主服务中明确配置：
如果 FastGPT Pro 也存在相同监听问题，可以给 Pro 同样配置。
2. beta 版本加强了环境变量校验
升级后，如果必填变量缺失或格式不符合要求，服务会持续提示：
FastGPT 与 FastGPT Pro 需要重点检查：
注意事项：
3.
SYNC_INDEX参数格式变化新版本中应使用布尔字符串：
- SYNC_INDEX=true或：
- SYNC_INDEX=false不建议继续使用：
如果 MongoDB 中已经存在重复数据，启用索引同步可能出现：
此错误在本次环境中没有阻止系统完成初始化，但会导致唯一索引创建失败。建议先清理重复数据，再开启自动索引同步。
4. AIProxy PostgreSQL 共享内存不足
升级 AIProxy 后，执行日志清理或
VACUUM ANALYZE时出现：该错误不一定是宿主机磁盘不足，而可能是 PostgreSQL 容器默认
/dev/shm只有 64MiB。可以在
aiproxy_pg服务中增加：修改后需要重建
aiproxy_pg容器。5. Pro 后台文件上传接口路由
在 Pro 管理后台上传头像或文件时，请求路径可能是：
如果 Pro 域名的 Nginx 将全部请求都代理到 FastGPT Pro，这个上传接口可能返回 404。
需要将该路径单独转发到 FastGPT 主服务，例如：
其中
<FASTGPT_MAIN_SERVICE>替换为实际的 FastGPT 主服务地址。6. 容器重建后 Nginx 可能缓存旧容器地址
使用 Docker Compose 重建 FastGPT 或 FastGPT Pro 后，容器 IP 可能变化。
如果 Nginx 使用服务名代理，但没有及时重新解析，外部访问可能暂时出现：
此时可以重启 Nginx 容器，让其重新解析上游服务地址。
7. beta2 沙盒组件需要配套升级
升级到 beta2 时，除了 FastGPT 和 FastGPT Pro，还需要同步调整：
FastGPT 环境变量中的沙盒镜像 tag 也需要同步更新：
- AGENT_SANDBOX_OPENSANDBOX_IMAGE_TAG=v0.2.0只升级 FastGPT 主服务，而未更新配套沙盒组件，可能导致功能不兼容。
8. OpenSandbox API Key 两端必须一致
如果仅部署了 OpenSandbox 服务，但没有配置 API Key，FastGPT 可能识别不到虚拟机配置，前端提示：
OpenSandbox 配置示例：
FastGPT 环境变量：
注意：
9. OpenSandbox 实际监听端口不要只看镜像声明
容器镜像可能显示暴露了某个端口，但实际服务监听端口由配置文件决定。
本次环境中：
因此 FastGPT 应连接：
- AGENT_SANDBOX_OPENSANDBOX_BASEURL=http://opensandbox-server:8090建议通过容器内实际访问确认，不要只根据
docker ps中的EXPOSE信息判断。10. OpenSandbox 自定义网络与
networkPolicy冲突虚拟机功能已经显示，但创建 Sandbox 时出现：
FastGPT 日志中的实际原因是：
OpenSandbox 创建沙盒时，如果请求中包含
networkPolicy，Docker runtime 不能使用自定义网络名称。需要在
opensandbox-config.toml中配置：注意：
opensandbox-server自身在 Docker Compose 中加入的业务网络。11. Agent Volume Manager 正常不代表 Sandbox 一定能创建
本次排查中，Volume Manager 日志已经显示卷创建成功：
但 OpenSandbox 创建运行时容器仍然返回 400。
因此，排查
Failed to create sandbox时需要分别查看：不能仅根据 Volume Manager 成功判断整个 Sandbox 链路正常。
12. 启动瞬间的连接失败不一定是升级失败
重建 FastGPT 或 FastGPT Pro 后，前几次访问可能出现：
等待初始化完成后可能恢复为 HTTP 200。
建议使用循环健康检查，而不是在容器刚启动时根据第一次请求直接回滚。
13. Redis 启动阶段可能出现短暂重连日志
FastGPT 初始化完成后，可能短时间出现：
如果 Redis 容器状态为 healthy，FastGPT 后续运行正常，并且日志不持续增长，可以先观察，不一定代表 Redis 故障。
14. Docker Compose 的
version字段警告新版 Docker Compose 会提示：
该警告不会阻止服务启动，但可以在后续维护时移除 Compose 文件顶层的
version字段，避免干扰排查。复现步骤
使用较旧版本的 Docker Compose 配置部署 FastGPT。
仅修改 FastGPT、FastGPT Pro、Plugin、AIProxy 等镜像 tag。
未同步更新环境变量校验要求、沙盒组件版本和 OpenSandbox 配置。
依次测试：
可能出现：
Failed to create sandbox预期结果
希望升级文档可以增加一份 Docker Compose 升级检查清单，至少提示以下内容：
以上内容主要是升级和部署经验汇总，不一定属于产品 Bug，希望可以作为文档补充或其他私有部署用户的参考。