常见问题

应用容器反复重启

先查看应用和依赖状态：

docker compose ps
docker compose logs --tail=200 sub2api
docker compose logs --tail=100 postgres
docker compose logs --tail=100 redis

常见原因：

• POSTGRES_PASSWORD 未设置或与已有数据库不一致。
• PostgreSQL 数据目录权限错误。
• Redis 密码不一致。
• 数据库迁移失败。
• .env 中存在无法解析的特殊字符。

修改 Compose 前可以先检查最终配置：

docker compose config

找不到管理员密码

未设置 ADMIN_PASSWORD 时，首次启动会生成密码并输出到日志：

docker compose logs sub2api | grep "admin password"

日志已经轮转或丢失时，不要反复删除数据库重新初始化，应使用受支持的管理员恢复流程。

如果数据库已经有管理员，后来修改 ADMIN_PASSWORD 不会重置密码。登录校验读取 PostgreSQL 的 users.password_hash；先按启动、配置与事实来源确认实际状态，再通过后台或受控恢复流程修改密码。

页面能打开，但 API 请求失败

依次检查：

curl -i http://127.0.0.1:8080/health
curl -i https://api.example.com/health

• 第一条失败：检查应用、PostgreSQL、Redis和本机防火墙。
• 第一条成功、第二条失败：检查 DNS、证书和反向代理。
• 页面成功、模型 API 失败：检查 API Key、分组、账号和上游网络。

流式响应最后一次性返回

反向代理启用了响应缓冲。Nginx 需要：

proxy_buffering off;
proxy_cache off;

同时确认 CDN 没有对 API 路径做缓冲或缓存。

流式请求中途断开

检查反向代理和 CDN 的读取超时：

proxy_read_timeout 3600s;
proxy_send_timeout 3600s;

还需要检查上游响应头超时、客户端自己的请求超时，以及代理出口是否重置空闲连接。

粘性会话没有生效

• 确认 Redis 正常。
• 确认请求携带稳定的会话 metadata。
• Nginx 必须启用 underscores_in_headers on，否则可能丢弃 session_id。
• 账号不可用或限流时，系统会主动切换账号，这是正常行为。

返回 413 Request Entity Too Large

请求可能同时受到 CDN、反向代理、全局服务和网关四层限制。应按实际需求同时检查：

• CDN 上传限制。
• Nginx client_max_body_size 或 Caddy request_body。
• SERVER_MAX_REQUEST_BODY_SIZE。
• GATEWAY_MAX_BODY_SIZE。

不要为了绕过单个请求直接把所有限制设为无限。

升级后无法启动

1. 保留现场，不要删除 PostgreSQL 数据目录。
2. 查看迁移错误和第一个 fatal 日志。
3. 对照版本说明确认数据库版本要求。
4. 如果只能回退，先判断新迁移是否兼容旧二进制。
5. 必要时在新数据库实例恢复升级前备份，再切换应用。

OAuth 回调地址错误

第三方平台登记的回调地址必须与用户实际访问域名和协议完全一致。确认：

• 外部地址是 https://。
• 反向代理传递 X-Forwarded-Proto 和 X-Forwarded-Host。
• 配置中的前端地址、API 地址和平台后台登记地址一致。
• 不要把容器内部地址或 localhost 登记为公网回调。

数据统计日期不一致

检查应用、PostgreSQL、容器和管理员预期时区是否一致。Docker 部署通常设置：

TZ=Asia/Shanghai

修改时区可能改变“今日”、订阅到期和聚合报表的边界，正式环境应在上线前确定。