[Question]: Errors for `docker compose -f docker/docker-compose.yml up -d`

快速结论：在 RAGFlow 使用 docker compose -f docker/docker-compose.yml up -d 启动时，阿里云/华为云服务器上常见的报错是拉取镜像时出现 TLS 证书校验失败。优先排查 Docker 镜像源（Registry Mirror）配置，必要时更换网络环境或配置代理。

适用环境：阿里云 ECS、华为云 ECS；Docker Compose 方式部署 RAGFlow；镜像仓库默认指向 registry-1.docker.io 与 auth.docker.io。

最快修复方案：暂无确认的一步修复方案。Issue 中用户最终通过更换 VPN 网络环境成功完成部署；另一条有效路径是修改 Docker 的镜像源配置，将 Registry Mirror 指向可访问的镜像加速器。两种方式均已在 Issue 讨论中被提及，但未给出官方标准配置值，可优先尝试配置镜像加速器。

注意事项：镜像源加速器在不同云厂商、不同地域、不同时间可用性不稳定，且配置后需重启 Docker 服务并清空失败缓存。VPN 方案在部分网络环境下才能生效，且可能涉及合规风险。此外，如果后续遇到 Additional property extra_hosts is not allowed 的报错，可能与 docker-compose 版本过旧有关，需要升级 docker-compose 插件。

问题场景

用户分别在阿里云和华为云的 Linux 服务器上，尝试使用 docker compose -f docker/docker-compose.yml up -d 启动 RAGFlow（infiniflow/ragflow），在执行拉取镜像阶段出现 TLS 证书校验错误，导致部署失败。

报错原文

Error response from daemon: Head "https://registry-1.docker.io/v2/valkey/valkey/manifests/8": Get "https://auth.docker.io/token?scope=repository%3Avalkey%2Fvalkey%3Apull&service=registry.docker.io": tls: failed to verify certificate: x509: certificate is valid for *.twitter.com, twitter.com, *.x.com, x.com, not auth.docker.io

随后在评论区还出现了第二个报错：

validating /root/ragflow-main/docker/docker-compose-base.yml: networks.ragflow Additional property extra_hosts is not allowed

原因分析

主报错的最可能原因是网络出口被劫持或污染。错误信息明确显示 docker daemon 访问 auth.docker.io 时，收到的 TLS 证书竟然是 twitter.com 和 x.com 的证书，说明 HTTPS 流量被中间设备（可能是云厂商网络策略、运营商或代理）拦截并重定向。这不是 RAGFlow 自身配置问题，而是 Docker 客户端无法正常连接 Docker Hub 认证服务。

第二个报错 Additional property extra_hosts is not allowed，可能原因是 docker-compose 版本过低，导致 Compose 文件中的 extra_hosts 配置项不被当前版本识别。

环境排查

确认 Docker 版本：docker --version，评论区出现 Docker 26.1.3 仍报错的情况。
确认 docker-compose 插件版本：docker compose version，过旧版本无法解析 extra_hosts。
确认当前网络环境下能否正常访问 Docker Hub：curl -I https://registry-1.docker.io/v2/，观察返回的证书域名。
检查 /etc/docker/daemon.json 中是否已配置 registry-mirrors。
确认服务器所在云厂商地域与 Docker Hub 的连通性。

解决步骤

先确认 DNS 解析是否异常：执行 nslookup auth.docker.io，检查返回 IP 是否为 Docker 官方地址。如果解析结果异常，先修改 DNS 为 223.5.5.5 或 114.114.114.114 后重试。
配置 Docker 镜像加速器（可优先尝试）：编辑 /etc/docker/daemon.json，添加 {"registry-mirrors": ["https://docker.m.daocloud.io"]}（此处替换为实际可用的镜像加速地址），保存后执行 systemctl daemon-reload && systemctl restart docker，然后重新执行 docker compose -f docker/docker-compose.yml up -d。
若镜像加速无效，尝试更换网络环境：Issue 作者最终通过启用 VPN 成功完成部署。在云服务器上使用代理时，需要在 Docker systemd 服务中配置 HTTP_PROXY / HTTPS_PROXY 环境变量，然后 systemctl restart docker。
针对 extra_hosts is not allowed 报错：更新 docker-compose 插件，执行 sudo apt update && sudo apt install docker-compose-plugin 或 sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64" -o /usr/local/bin/docker-compose 升级后重试（本 Issue 未给出明确升级命令，仅指出可能是 docker 版本问题）。
重试部署：确认上述配置生效后，重新执行 docker compose -f docker/docker-compose.yml up -d，注意观察拉取日志，个别镜像可能仍然下载失败，需要重试或单独 pull。

验证方法

重新执行部署命令后，观察镜像拉取阶段不再出现 tls: failed to verify certificate 报错；所有 RAGFlow 容器状态均为 Up（使用 docker ps 查看），此时说明网络问题已解决。若针对 extra_hosts 报错进行修复，重新运行 docker compose config 可正常解析配置文件，即表示 compose 文件已通过校验。