Troubleshooting

简体中文 | English

Center Does Not Start

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

Check port conflicts and the permissions and contents of ./data/config, ./data/history, and ./data/logs. The master.key must match the config.db used to create encrypted credentials. A corrupt database, missing master key, or failed migration stops the Center with an explicit error.

Development builds, release candidates, and v0.1.0 are not supported upgrade sources for v0.1.1. Use empty data directories when first moving from those versions. v0.1.1 is now the production-data compatibility baseline; do not troubleshoot an existing v0.1.1 deployment by deleting ./data/config, which also loses the account, node identities, and encrypted credentials.

Agent Does Not Come Online

# 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

Verify that the node can reach the Center's external origin, system time is correct, and the reverse proxy allows Agent APIs. Re-running the installer preserves a valid local identity. To obtain a new identity, run the installer with --uninstall --purge before enrolling again.

Collect Detailed Node Logs

In the node's Settings, temporarily change the default log level from info to debug. Wait for configuration synchronization before reproducing the issue. Use the node's Logs tab or the global Logs page to filter by time, node, level, component, task, public IP, proxy, or keyword. Display filters do not change the collection level. Restore info after troubleshooting.

Request failure details include the failure stage, HTTP status, rate-limit headers, and raw failure response body. Request authentication information is not logged. Third-party response bodies may contain sensitive information; review them before sharing. Logs default to seven days of retention, with capacity-based or permanent retention available. Offline Agent logs are bounded to 64 MiB and 10,000 entries, evicting the oldest entries when either limit is reached.

For missing ipapi data, correlate the task and public IP with rate-limit, quota, timeout, and retry records. Complete probes try third-party requests up to three times for retryable failures; live logs are still needed to determine the cause. For inconsistent public-IP or NAT displays, inspect discovery, configuration synchronization, and task logs together.

WebSocket Is Unavailable

Temporary synchronization uses WebSocket Upgrade under /api/v1/agent/sync/. Ensure the reverse proxy uses HTTP/1.1 and forwards Upgrade and Connection. A WebSocket failure does not immediately make the node offline; 30-second HTTP polling remains the source of status.

No Public IP Is Discovered

Under Settings > Network probes, configure at least two different discovery-service hosts for each address family. Multiple services must agree on one address for the same path. The page reports a check failure when only one service succeeds or results conflict.

For a proxy egress, open the node's Public IPs > Manage proxies, confirm the proxy is enabled and its credentials are correct, and inspect IPv4 and IPv6 check states separately. A dynamic proxy returning different addresses is not itself an error.

Complete Probe Fails or Has Empty Fields

• A node below 64 MiB automatically pauses complete probes; the administrator can override the pause.
• A third-party timeout or rejection affects only that provider's fields.
• Configure the optional ipapi API key under Settings > System when ipapi data is required.
• JSON null means no data and is not a format error.
• An incompatible type for a known field produces an empty value and a format diagnostic.

Inspect the execution error code, raw report, and format diagnostics first. A single IPv6 or proxy failure describes only that check attempt.