故障排查

先定位故障层级，再修改配置。不要一遇到页面异常就重装、删库、清空 secrets 或重新生成所有 Agent 凭据。

最短排查顺序

/ready
  → Controller 容器状态和日志
  → 反向代理 / TLS / WebSocket
  → Public API
  → Admin 会话
  → Agent 服务和日志
  → 探测目标 / 通知渠道

基础命令：

cd /opt/zeno
docker compose ps
curl -fsS http://127.0.0.1:18980/health
curl -fsS http://127.0.0.1:18980/ready
docker compose logs --tail=200 zeno

日志粘贴到 Issue 前必须脱敏；不要包含 Token、完整安装命令、Authorization header、.env、数据库、备份内容或通知凭据。

网站打不开

本机 /ready 失败

检查容器状态和日志。重点看：

• SQLite 无法打开或检查失败；
• 数据/secrets 权限错误；
• 必需配置缺失；
• 端口占用；
• 容器健康检查失败。

不要用删除数据库或放宽 secrets 到 0777 的方式绕过错误。

本机正常，公网失败

检查：

1. DNS 是否指向正确主机；
2. HTTPS 证书是否有效；
3. 反向代理是否指向 127.0.0.1:18980；
4. Nginx 是否转发 WebSocket upgrade header；
5. ZENO_TRUSTED_PROXIES 是否只包含真实反代来源；
6. 防火墙是否开放 HTTPS，而不是直接开放 18980。

页面能开但一直加载

分别访问：

curl -fsS https://zeno.example.com/api/public/v1/settings
curl -fsS https://zeno.example.com/api/public/v1/summary

• settings 失败：检查 Controller 和反向代理；
• summary 失败：检查数据库、迁移和 Controller 日志；
• 两者成功但页面失败：检查浏览器控制台、静态资源缓存和代理是否改写路径。

后台无法登录

1. 确认访问 /dashboard；
2. 首次登录账号为 admin；
3. bootstrap 凭据来自当前安装目录；
4. 检查是否在另一个标签页修改过账号或密码；
5. 检查浏览器时间、Cookie/存储限制和 Controller 日志。

忘记密码时使用 官方离线恢复流程。不要手改 hash 或 session 表。

Agent 一直 no_data

在 Agent 主机检查：

curl -fsS https://zeno.example.com/ready
systemctl is-active zeno-agent.service
journalctl -u zeno-agent.service --since '15 minutes ago' --no-pager

常见原因：

• Agent 接入 URL 错误；
• TLS/DNS 不可达；
• enrollment 命令已失效或被重复使用；
• 目标主机时间不同步；
• 服务未启动；
• Controller/Agent 版本组合未验证。

修复后要看到一次新的真实上报，不能只以服务 active 判断完成。

节点显示 warning

warning 表示 Agent 仍在线，但资源规则或探测状态异常。检查：

• CPU、内存、磁盘规则及统计窗口；
• 目标是否持续不可达；
• 节点详情中的延迟和丢包；
• 是否有尚未恢复的活动 incident。

不要通过 CSS 隐藏 warning，也不要用 heartbeat 清除仍然存在的资源异常。

延迟没有数据

• 目标是否分配给该节点；
• tcping 是否填写端口；
• ping 是否被系统或网络禁止；
• http_get 是否返回 4xx/5xx；
• Agent 到目标的网络是否可达；
• Agent 日志是否有探测超时或权限错误。

没有数据时页面应显示 No data，而不是 0 ms。

Telegram 通知失败

先执行后台“测试通知”。检查：

• Bot Token 和 Chat ID；
• Bot 是否能向目标会话发消息；
• Controller 出站网络；
• 渠道是否启用；
• 通知类型是否已添加并启用；
• 作用范围是否包含目标服务器。

测试通知只证明渠道可发送；离线、阈值和恢复通知仍需真实事件验证。

外观或主题异常

1. 切回 default 外观预设；
2. 切回 classic 服务器卡片主题；
3. 清空有问题的自定义 CSS；
4. 关闭背景图；
5. 刷新并检查 Public Settings；
6. 在浅色、深色和手机视口重新验证。

设置值非法或缺失时应回退到安全默认值。详细说明见 外观设置。

升级后异常

官方安装器会在 readiness 失败时自动恢复。若服务已启动但业务异常：

1. 记录当前镜像 version、revision 和 digest；
2. 保留日志和失败现场；
3. 验证安装器备份 manifest；
4. 按 升级与回滚 恢复同一份 .env、Compose、data/ 和 secrets/；
5. 不要只切旧镜像而保留不兼容的新数据库。

报告问题

请提供脱敏后的：

• Zeno Controller 版本/镜像 digest；
• Agent 版本；
• OS 与架构；
• 部署方式；
• 故障时间范围；
• 预期和实际行为；
• 最小相关日志。

安全漏洞按 安全策略 私密报告；普通可复现问题使用 GitHub Issue Forms。