故障排查

简体中文 | English

Center 无法启动

docker compose ps
docker compose logs --tail=200 center

重点检查端口占用以及 ./data/config、./data/history、./data/logs 的权限和内容。 master.key 必须与创建加密凭据时使用的 config.db 匹配。损坏的数据库、缺失的 主密钥或失败的迁移会让 Center 明确停止启动。

开发版、候选版和 v0.1.0 不属于 v0.1.1 的受支持升级来源。从这些版本首次 部署时使用空数据目录。v0.1.1 已经是生产数据兼容基线；已有 v0.1.1 部署不得 通过删除 ./data/config 排障，否则会丢失账户、节点身份和加密凭据。

Agent 没有上线

# systemd
systemctl status ipchronicle-agent
journalctl -u ipchronicle-agent --no-pager -n 200

# OpenRC
rc-service ipchronicle-agent status
tail -n 200 /var/log/ipchronicle-agent.log

确认节点能访问 Center 的外部地址、系统时间正常，并且反向代理允许 Agent API。 重复运行安装命令会保留有效的本地身份。需要新身份时，先运行安装器 --uninstall --purge，再重新注册。

采集节点详细日志

在节点设置中将日志等级从默认的 info 临时改为 debug，等待配置同步完成， 再复现问题。在节点日志标签或全局日志页按时间、节点、等级、组件、任务、 公网 IP、代理或关键词筛选。页面筛选不改变采集等级；排查结束后恢复 info。

请求失败详情包含失败阶段、HTTP 状态、限流响应头及原始失败响应正文。请求认证 信息不记录；第三方响应正文可能包含敏感内容，分享前先检查。日志默认保留 7 天， 也可按容量或永久保留。Agent 离线日志最多 64 MiB、10,000 条，超限淘汰最旧日志。

排查 ipapi 缺失时，关联任务与公网 IP，查看限流、额度、超时和重试记录。第三方 完整探测请求对可重试失败最多尝试三次；仍需根据现场日志判断缺失原因。公网 IP 或 NAT 显示不一致时，同时检查发现、配置同步和任务日志。

WebSocket 不可用

临时同步模式依赖 /api/v1/agent/sync/ 的 WebSocket Upgrade。确认反向代理使用 HTTP/1.1 并转发 Upgrade 和 Connection。WebSocket 失败不会让节点立即离线， 30 秒 HTTP 轮询仍是状态依据。

没有发现公网 IP

检查 设置 > 网络探测 中每个地址族是否配置至少两个不同主机的发现服务。多个 服务必须对同一路径取得一致地址。只有一个服务成功或结果冲突时，页面会显示检测 失败。

对于代理出口，在节点 公网 IP > 管理代理 中检查代理是否启用、凭据是否正确， 并分别查看 IPv4 和 IPv6 检测状态。动态代理返回不同地址本身不是错误。

完整探测失败或字段为空

• 低于 64 MiB 内存的节点会自动暂停完整探测，管理员可以手动覆盖；
• 第三方服务超时或拒绝请求时，只影响对应字段；
• ipapi 字段需要时，可以在 设置 > 系统 配置可选 API Key；
• JSON null 表示没有数据，不属于格式错误；
• 已知字段的数据类型不兼容时显示空值，并在格式诊断中记录问题。

先查看该执行的错误码、原始报告和格式诊断。单次 IPv6 或代理检测失败只表示本次 检测失败。