排障

按从外到内顺序诊断：进程、监听、站点匹配、路由、WAF、上游。每次只改变一层，并保留失败请求 ID。

最初五分钟

tiyi doctor
systemctl status tiyi --no-pager
journalctl -u tiyi -n 200 --no-pager
ss -ltnp
tiyi system health

Agent 检查 tiyi-agent unit；开发环境前台运行时检查终端与命令行路径。

无法打开控制台

• 确认配置的 server.addr 与主机防火墙。
• 80/443 服务代理流量；控制台默认监听 8080。
• 运行 tiyi doctor 检查端口冲突与配置错误。
• 若报告服务状态目录所有权，先核对路径，再运行 sudo tiyi doctor --fix-state-ownership。

丢失首次管理员密码

sudo tiyi user list
sudo tiyi user reset-password <user-id> --password '<new-strong-password>'

请求没有匹配站点或错误上游响应

curl -v -H 'Host: app.example.com' http://127.0.0.1/
tiyi site list
tiyi upstream list

检查 Host 规范化、监听、站点启用状态、最长前缀路由、上游 scheme/端口与健康探针。浏览器直接访问 IP 而不带配置 Host，不是有效站点测试。

预期攻击没有被拦截

• 确认请求进入预期站点且 WAF 已启用。
• 检查有效策略、engine state、偏执级别、阈值、bypass、IP 列表优先级与路径覆盖。
• 按请求 ID 与规则 ID 查询 Finding/Security 证据。
• 使用不受信任来源测试；global/site allow 或 bypass 可能决定结果。
• 修改前预览编译后策略。

TLS 或 ACME 失败

检查 DNS、公网可达性、HTTP-01 所需的 80 端口、证书绑定、时钟与 ACME order 详情。DNS-01 要求受支持 provider 与正确范围凭据。不要在 issue 或支持材料中包含 provider 密钥。

Agent 离线或不能应用

• 对比 Server URL、注册有效期、时钟、DNS 与网络路径。
• 读取同一时间点的 Server 与 Agent journal。
• 区分离线、身份/协议拒绝、签名失败与 apply 失败。
• 重连后确认 applied revision/hash，不能只看 online。

v3.2 拒绝旧状态

Observation v2 会按设计拒绝 pre-v3.2 数据库、Agent 身份标记与缓存 bundle。项目目前没有需要兼容的正式用户升级群体：保留源清单和必要密钥，把旧开发/测试状态移走，以干净状态启动 v3.2，再重新注册 Agent。不要把旧数据库复制回来。

有计数但证据或 SIEM 延迟

打开监控 → 日志管道，检查队列深度、丢弃、重试与 panic 计数。精确计数、保留证据、明细/SIEM 投递彼此独立。从太一主机测试目标并修复消费者；除非诊断明确要求，不要重启健康的数据面。

收集安全的支持材料

包含版本、模式、脱敏配置、unit、health/doctor 输出、相关 journal、站点/上游 ID、时间与时区、请求 ID。删除 JWT、密码、注册 token、私钥、DNS 凭据、cookie 与敏感请求体。