OpenZiti 入门（20）：Docker 部署后服务访问失败，如何排查？

第 19 篇中，我们用 ziti-host 承载了 Docker 应用。本篇以该示例为对象，排查下面这个请求为什么失败：

bash
curl --noproxy '*' --connect-timeout 10 http://docker-app.ziti/

示例中的关键名称如下：

text
客户端身份：docker-web-client
OpenZiti 服务：docker-app
服务端身份：docker-app-host
承载容器：demo-ziti-host
应用容器：demo-app:8000

排查顺序是：容器状态 → 客户端解析 → 策略和 Router → 服务端到应用的连接。

1. 先看容器状态和日志

在 Docker 宿主机进入项目目录，使用第 19 篇的两个 Compose 文件：

bash
cd ~/openziti-docker-lab

docker compose -f compose.yaml -f compose.app.yaml ps -a

确认 ziti-controller、ziti-edge-router、demo-ziti-host 和 demo-app 正在运行。Quickstart 的初始化容器执行完成后，以退出码 0 结束是正常的。

查看相关日志：

bash
docker compose -f compose.yaml -f compose.app.yaml \
  logs --tail=100 ziti-controller ziti-edge-router demo-ziti-host demo-app

如果出现端口占用、镜像拉取失败或容器反复退出，先处理这些问题。Controller 显示健康只说明它的健康检查通过，应用仍需要单独验证。

2. 检查客户端 Tunneler 和域名解析

在作为客户端的 Ubuntu 宿主机上执行：

bash
systemctl status ziti-edge-tunnel.service --no-pager
getent ahostsv4 docker-app.ziti

如果域名没有返回地址，检查：

• docker-web-client 是否已注册到第 17 篇的 Docker 网络；
• docker-app-dial 是否授权了该身份；
• 客户端的 Tunneler 是否运行，以及拦截配置是否包含 docker-app.ziti:80；
• 本机 DNS 是否使用了 Tunneler 配置的解析器。

使用 systemd-resolved 时，可以继续查看：

bash
resolvectl dns
resolvectl domain
sudo journalctl -u ziti-edge-tunnel.service -n 100 --no-pager

更多 DNS 检查方法见官方 Linux Tunneler 排查指南。

3. 检查 Dial、Bind 和 Router

进入 Controller 容器：

bash
docker compose -f compose.yaml -f compose.app.yaml \
  exec ziti-controller bash

在容器内执行：

bash
zitiLogin
ziti edge list edge-routers

ziti edge policy-advisor services docker-app docker-web-client -q
ziti edge policy-advisor services docker-app docker-app-host -q

重点查看：

• 客户端身份是否有 Dial 权限；
• 服务端身份是否有 Bind 权限；
• 身份与服务是否有共同的在线 Router。

Policy Advisor 检查策略关系；即使结果显示允许，也还要确认承载容器和后端应用实际可用。OpenZiti 策略文档介绍了共同 Router 的要求。

完成检查后输入 exit 返回宿主机。

4. 检查 ziti-host 到应用的连接

第 19 篇的 host.v1 目标应为：

text
demo-app:8000

可以从同处 zitiblue 网络的 Router 容器检查应用：

bash
docker compose -f compose.yaml -f compose.app.yaml \
  exec ziti-private-blue curl -fsS http://demo-app:8000

如果这里也失败，先检查 demo-app 是否运行、端口是否正确，以及容器是否加入了预期网络。该命令检查的是 Docker 网络连通性；还要确认 demo-ziti-host 也连接到了同一网络。

常见配置错误是把 host.v1 地址写成 127.0.0.1。在第 19 篇的两个独立容器中，这个地址指向 ziti-host 容器自身；应使用它能够解析和访问的应用地址 demo-app。

5. 理解常见错误

错误代码的详细定义见官方 Circuit Create Error Codes。

6. 别忽略本地地址和数据卷

第 17 篇将 ZITI_INTERFACE 设置为 127.0.0.1，所以发布端口默认只能从 Docker 宿主机访问。远程客户端需要正确的可达地址、DNS 和证书配置；单独修改端口映射不一定足够。

第 19 篇的 demo-ziti-host-identity 卷保存了已注册身份。如果卷被删除，原来的一次性 JWT 也不能再次使用。排障时先检查卷挂载和日志，避免为了重试而直接执行 docker compose down -v。

向论坛求助时，可以提供相关容器状态、错误代码和脱敏日志；请先移除 JWT、身份文件、密码及其他凭据。