安装故障排查¶

本指南用于排查首次 Docker 与 Compose 安装问题。请在包含 docker-compose.yml 的仓库根目录执行命令。

先做这组检查¶

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 postgres migration backend

请优先查看第一个失败的依赖服务，而不是只看最后出现的 backend 错误。正常启动顺序是 PostgreSQL 与 Redis、migration、API 和各 Worker。

镜像拉取失败¶

常见错误包含 registry-1.docker.io、failed to resolve reference、连接超时，或 Docker Desktop 没有 HTTPS 代理。

确认宿主机代理端口正在监听。
在 Docker Desktop 打开 Settings → Resources → Proxies。
为 HTTP 与 HTTPS 填写实际可用的 HTTP 代理地址。
保存后彻底退出并重启 Docker Desktop。
使用 docker info 确认代理生效，再执行 docker compose pull。

Windows 可用下面的命令检查：

curl.exe -x http://127.0.0.1:10808 https://registry-1.docker.io/v2/
docker info | findstr /i proxy

/v2/ 返回 UNAUTHORIZED 表示 Registry 已经可达，只是该接口需要 Docker 的认证流程；超时或连接失败才表示网络仍未打通。

PostgreSQL 升级后不健康¶

如果日志提示数据目录由另一个 PostgreSQL 大版本初始化，不要反复重启容器。 PostgreSQL 数据目录不能跨大版本直接复用。

仅当本地数据可以全部丢弃时：

docker compose down -v
docker compose up -d

down -v 会永久删除 Compose volumes，包括本地数据库。需要保留数据时严禁使用。

需要保留数据时，应先用原 PostgreSQL 大版本启动，再通过 pg_dump/pg_restore 或 pg_upgrade 迁移。更换镜像或数据卷前必须先备份。

数据库迁移没有完成¶

docker compose ps migration
docker compose logs --tail=200 migration
docker compose logs --tail=100 postgres

不要从多个 API Worker 并发执行结构变更。数据库升级由 Compose 中的 migration 服务统一负责，其他服务会等待它成功结束。

后端退出或健康检查失败¶

docker compose logs --tail=200 backend
docker compose exec backend curl -f http://localhost:5000/api/health

优先核对：

源码部署是否同时存在 .env 与 backend_api_python/.env；
GHCR 部署是否引用安装程序生成的 backend.env；
POSTGRES_PASSWORD、SECRET_KEY 与 CREDENTIAL_ENCRYPTION_KEY 是否为空或占位值；
各服务使用的 PostgreSQL 与 Redis 密码是否一致；
migration 服务是否已成功完成。

管理员登录或系统设置保存问题请阅读管理员凭据与系统设置排错。

安全的恢复命令¶

# 查看状态与近期日志
docker compose ps
docker compose logs --tail=100 backend trading-worker scheduler-worker

# 保留数据卷并重建容器
docker compose up -d --force-recreate

# 保留数据卷并停止容器
docker compose down