OpenZiti 入门（6）：Tunneler 访问失败时怎么排查

上一期我们让客户端通过 Tunneler 访问 http://hello.ziti。这篇以同一个示例为基础，按顺序检查本地 HTTP 服务、Tunneler、DNS、策略和 Router，定位请求在哪一层卡住。

官方建议先检查客户端拦截，再检查服务端绑定，最后检查 Controller 的路由与电路日志。服务故障排查指南也采用这个顺序。

先看症状

OpenZiti 要求客户端身份和服务至少有一台在线的 Edge Router 可共同使用；服务端也需要成功绑定到服务，才能创建 Terminator。官方 Policies 文档对此有说明。

1. 确认 HTTP 服务本身可用

在运行 HTTP 服务的 Ubuntu 主机上执行：

bash
curl -v http://127.0.0.1:8000/

上一期的示例应返回：

text
Hello from an existing HTTP service

如果这里无法访问，先确认 Python HTTP 服务仍在运行，并检查它是否监听在 127.0.0.1:8000。此时还没到 OpenZiti 网络排查这一步。

2. 检查 Tunneler 和 DNS

确认 Tunneler 服务正在运行：

bash
sudo systemctl status ziti-edge-tunnel.service --no-pager

检查系统是否能解析 Ziti 服务名：

bash
resolvectl status
resolvectl query hello.ziti

如果 hello.ziti 无法解析，依次检查：

• ziti-edge-tunnel.service 是否运行。
• 客户端身份 local-web-client 是否已注册并在线。
• intercept.v1 中的地址是否为 hello.ziti，端口是否包含 80。
• 系统 DNS 是否使用 Tunneler 提供的解析服务。若未启用 systemd-resolved，可能需要手动配置系统解析器。

Linux Tunneler 通常通过 systemd-resolved 配置 DNS；详细排查步骤见官方 Linux Tunneler 故障排查文档。

3. 检查身份、服务和策略

在 Quickstart 管理终端中恢复环境并登录：

bash
source "$HOME/.ziti/quickstart/$(hostname -s)/$(hostname -s).env"
zitiLogin
ZITI="${ZITI_BIN_DIR-}/ziti"

先查看客户端身份、服务和 Router 状态：

bash
"$ZITI" edge list identities
"$ZITI" edge list services 'name="local-web"'
"$ZITI" edge list edge-routers

使用 Policy Advisor 检查客户端能否访问服务：

bash
"$ZITI" edge policy-advisor identities -q local-web-client local-web

重点看输出中的 Dial 和 Common Routers。客户端应有 Dial: Y，并且至少有一台共同 Router。若 Dial 不通过，检查 Service Policy 是否关联了 @local-web-client 和 @local-web；若没有共同 Router，检查身份和服务各自的 Router 策略。

4. 检查服务端绑定和 Terminator

上一期使用 Quickstart Edge Router 作为服务端 Tunneler。把 HOST_ID 设置为该 Router 对应的身份名称，然后检查 Bind 授权和 Terminator：

bash
HOST_ID="替换为Router关联的Identity名称"

"$ZITI" edge policy-advisor identities -q "$HOST_ID" local-web
"$ZITI" edge list terminators 'service.name="local-web"'

服务端身份需要对 local-web 有 Bind 权限，服务本身也要获准使用相应的 Router。确认 local-web-host 配置中的地址和端口仍是服务实际监听的地址，例如：

json
{"protocol":"tcp","address":"127.0.0.1","port":8000}

如果客户端能解析 hello.ziti，但请求出现 no terminator、重置或超时，优先检查 Host 侧绑定、Service Edge Router Policy，以及服务端身份和 Router 的在线状态。官方服务排查文档也将缺少 host.v1、缺少 Service Router Policy 或服务端身份离线列为常见原因。

5. 查看日志

查看 Tunneler 最近的服务日志：

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

Controller 和 Router 的 Quickstart 日志路径会在 startController、startRouter 的启动输出中显示。请求仍失败时，查看对应日志中的 ERROR 或 WARN。

如果需要更详细的 Tunneler 日志，可临时打开 DEBUG 级别：

bash
sudo -u ziti ziti-edge-tunnel set_log_level --loglevel DEBUG

复现问题后查看日志，再恢复常用级别：

bash
sudo -u ziti ziti-edge-tunnel set_log_level --loglevel INFO

排查时先关注故障发生的时间段，并在分享日志前检查是否包含敏感信息。官方 Linux Tunneler 文档还提供了导出身份和 Router 状态的 ziti-edge-tunnel dump 命令。

排查时可以从请求两端向网络中间逐步推进：先确认 HTTP 服务正常，再确认 Tunneler 和 DNS 工作，然后用 Policy Advisor 检查授权，最后查看 Router、Terminator 和日志。

如果遇到 no terminator，重点检查服务端绑定；如果是名称解析失败，先检查拦截配置和 Tunneler DNS；如果策略诊断显示没有共同 Router，检查身份和服务的 Router 授权。相关错误码可参考官方 Circuit 创建错误说明。