QuantDingerQuantDingerv5.0.1 Docs 文档中心
GitHub
查看 Markdown 源文件

Installation Troubleshooting / 安装排错指南

This guide collects common first-time Docker installation issues for QuantDinger, especially on Windows with Docker Desktop and a local proxy.

本文整理 QuantDinger 首次 Docker 安装时常见的问题，尤其适用于 Windows、Docker Desktop、本地代理环境。

Quick Checks / 快速检查

Run these commands from the QuantDinger repository root, next to docker-compose.yml.

请在 QuantDinger 仓库根目录执行，也就是 docker-compose.yml 所在目录。

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

Docker Hub Pull Fails / Docker Hub 镜像拉取失败

Symptom / 现象

You may see errors like:

可能会看到类似错误：

failed to resolve reference "docker.io/library/redis:8-alpine"
failed to do request: Head "https://registry-1.docker.io/v2/library/redis/manifests/7-alpine"
connecting to registry-1.docker.io:443: connectex: A connection attempt failed

or:

或者：

container via direct connection because Docker Desktop has no HTTPS proxy

Cause / 原因

Docker Desktop cannot reach Docker Hub from its own internal network. A browser or terminal may work, but Docker Desktop may still be using a different proxy path.

Docker Desktop 的内部网络无法访问 Docker Hub。浏览器或普通终端能访问，并不代表 Docker Desktop 拉镜像时也能走同一个代理。

Fix / 解决方法

First find the working local proxy port. Common ports are 7890, 7897, 10808, and 10809.

先确认本机真正可用的代理端口。常见端口有 7890、7897、10808、10809。

curl.exe -x http://127.0.0.1:10808 https://registry-1.docker.io/v2/

If the proxy works, Docker Hub should return UNAUTHORIZED. That is expected because this Registry API endpoint requires Docker authentication.

如果代理可用，Docker Hub 通常会返回 UNAUTHORIZED。这是正常的，因为这个 Registry API 地址需要 Docker 自己的认证 token。

{"errors":[{"code":"UNAUTHORIZED","message":"authentication required"}]}

Then configure Docker Desktop:

然后配置 Docker Desktop：

  1. Open Docker Desktop.
  2. Go to Settings -> Resources -> Proxies.
  3. Select Manual configuration.

  4. Set both proxy fields to the working port, for example:

  5. 打开 Docker Desktop。

  6. 进入 Settings -> Resources -> Proxies。
  7. 选择 Manual configuration。
  8. 两个代理地址都填可用端口，例如：
Web Server (HTTP):         http://127.0.0.1:10808
Secure Web Server (HTTPS): http://127.0.0.1:10808

If Docker still pulls directly, set Containers proxy to Same as host proxy, apply the change, then fully restart Docker Desktop from the system tray.

如果 Docker 仍然直连，把下面的 Containers proxy 改成 Same as host proxy，保存后从系统托盘完全退出并重启 Docker Desktop。

Verify Docker Desktop has picked up the proxy:

验证 Docker Desktop 是否已经读取代理配置：

docker info | findstr /i proxy

Typical output:

典型输出：

HTTP Proxy: http.docker.internal:3128
HTTPS Proxy: http.docker.internal:3128
No Proxy: hubproxy.docker.internal

http.docker.internal:3128 is normal. Docker Desktop maps your host proxy to an internal proxy address.

看到 http.docker.internal:3128 是正常的。Docker Desktop 会把宿主机代理映射成内部代理地址。

Retry:

重新执行：

docker compose pull
docker compose up -d

Browser Shows UNAUTHORIZED / 浏览器显示 UNAUTHORIZED

Opening this URL in a browser may show UNAUTHORIZED:

浏览器打开下面地址时可能显示 UNAUTHORIZED：

https://registry-1.docker.io/v2/library/redis/manifests/8-alpine

This is not an image problem. It means the Docker Registry endpoint is reachable, but the browser did not send Docker's authentication token.

这不是镜像有问题。它说明 Docker Registry 地址可以访问，只是浏览器没有携带 Docker 拉镜像所需的认证 token。

If the network were blocked, the browser would usually time out or fail to connect instead.

如果网络不通，浏览器通常会超时或连接失败，而不是返回 UNAUTHORIZED。

Proxy Port Does Not Work / 代理端口不可用

Symptom / 现象

curl through the proxy fails:

通过代理执行 curl 失败：

curl.exe -x http://127.0.0.1:10809 https://registry-1.docker.io/v2/

Failed to connect to registry-1.docker.io port 443 via 127.0.0.1
Could not connect to server

Cause / 原因

The configured proxy port is not listening, or it is not an HTTP proxy port.

当前填写的代理端口没有服务监听，或者它不是 HTTP 代理端口。

Fix / 解决方法

Check common local proxy ports:

检查常见本地代理端口：

netstat -ano | findstr 7890
netstat -ano | findstr 7897
netstat -ano | findstr 10808
netstat -ano | findstr 10809

Then test the port that is actually listening:

然后测试实际正在监听的端口：

curl.exe -x http://127.0.0.1:10808 https://registry-1.docker.io/v2/

If your proxy client supports it, enable Allow LAN or Allow connections from LAN. Docker Desktop sometimes needs access from its internal VM/network rather than only the Windows loopback path.

如果代理软件支持，请开启 Allow LAN / 允许来自局域网的连接。Docker Desktop 有时需要从内部虚拟机网络访问代理，而不只是 Windows 自己的 127.0.0.1。

Postgres Container Is Unhealthy / Postgres 容器不健康

Symptom / 现象

docker compose up -d fails with:

执行 docker compose up -d 失败：

dependency postgres failed to start
container quantdinger-db is unhealthy

Postgres logs show:

Postgres 日志显示：

FATAL: database files are incompatible with server
DETAIL: The data directory was initialized by PostgreSQL version 16, which is not compatible with this version 18.3.

Cause / 原因

The existing Docker volume or mounted data directory was initialized by PostgreSQL 16, but the current Compose stack is starting PostgreSQL 18. PostgreSQL data directories cannot be reused across major versions without a migration.

已有 Docker volume 或挂载的数据目录是 PostgreSQL 16 初始化的，但当前 Compose 启动的是 PostgreSQL 18。PostgreSQL 的数据目录不能跨大版本直接复用，必须迁移。

Fix if Local Data Is Disposable / 本地数据可以清空时

For a fresh development setup where local database data is not important:

如果只是开发环境，本地数据库数据不重要，可以直接清空 volume：

docker compose down -v
docker compose up -d

Warning: -v deletes Compose volumes, including the local Postgres data volume.

注意：-v 会删除 Compose volumes，包括本地 Postgres 数据。

Fix if Data Must Be Kept / 需要保留数据时

Do not delete the volume. Either:

不要删除 volume。可以选择：

  1. Start with the same PostgreSQL major version that created the data directory, for example postgres:16-alpine.
  2. Export and import data with pg_dump / pg_restore.

  3. Use a proper PostgreSQL major-version migration process such as pg_upgrade.

  4. 改回创建该数据目录时使用的 PostgreSQL 大版本，例如 postgres:16-alpine。

  5. 使用 pg_dump / pg_restore 导出并恢复数据。
  6. 使用正式的 PostgreSQL 大版本迁移流程，例如 pg_upgrade。

Useful Recovery Commands / 常用恢复命令

Check service status:

查看服务状态：

docker compose ps

Read service logs:

查看服务日志：

docker compose logs --tail=100 postgres
docker compose logs --tail=100 redis
docker compose logs --tail=100 backend

Pull images again:

重新拉取镜像：

docker compose pull

Recreate containers without deleting data:

重建容器但保留数据：

docker compose up -d --force-recreate

Stop and remove containers but keep volumes:

停止并删除容器，但保留 volume：

docker compose down

Stop and remove containers and volumes:

停止并删除容器和 volume：

docker compose down -v

Use down -v only when you are sure the local database data can be deleted.

只有确认本地数据库数据可以删除时，才使用 down -v。