故障排查

上传、下载、登录或后台存储失败时，从这里开始。先检查健康状态，再按钱包、缓存、后台任务或存储提供方信号缩小范围。

首先检查

curl http://127.0.0.1:9090/healthz
synaps3 admin status
synaps3 admin task stats

健康基线：

{"status":"ok"}

如果健康状态不是 ok，优先按返回的错误文本继续排查。

setup 状态

/healthz 可能返回：

{"status":"setup"}

这表示 SynapS3 缺少必要配置。修改设置前，先查看配置校验返回的详细信息。

检查报告的字段：

synaps3 admin status
synaps3 admin settings get

如果缺少钱包私钥，先生成钱包：

synaps3 wallet generate

如果缺少钱包私钥，将生成的私钥写入 SYNAPS3_FILECOIN_PRIVATE_KEY，或写入配置文件中的 filecoin.private_key。然后重启 SynapS3，检查 /healthz 并验证实际生效设置。

预期结果：重启后健康状态从 setup 变为 ok。

后台任务不健康

示例：

{"status":"unhealthy","errors":["worker/uploader: not responding"]}

检查任务状态：

synaps3 admin task stats
synaps3 admin task list --status running --limit 20

重启后，未完成的后台任务会重新进入可继续处理的状态。如果后台任务处理持续不健康，先记录当前任务状态并查看日志，然后重启服务。

钱包充值或 deposit 失败

检查钱包状态：

synaps3 admin status

在 Calibration 上重新为地址领取测试资产：

synaps3 wallet fund-testnet 0x...

然后重试 deposit 和 FWSS approval：

synaps3 wallet deposit 2 # 2 USDFC
synaps3 wallet approve

如果 faucet 失败，使用 ChainSafe 或 Plumbline 手动领取，然后重新运行 synaps3 admin status。

Faucet 领取成功后会输出 CalibnetUSDFC: <hash> 和 CalibnetFIL: <hash>。deposit 或 approval 确认后会输出 Transaction: <hash> 和 Status: confirmed；已经完成 approval 时会输出 FWSS approval: already approved。如果没有出现这些结果，先检查 RPC 连接、钱包余额和命令返回的错误，再重试。

缓存已满

缓存容量耗尽时上传端点可能失败。检查使用量：

synaps3 admin status
synaps3 admin settings get cache.max_size_gb

恢复方式：

• 先确认主机仍有可用磁盘空间，再按容量增大 cache.max_size_gb。
• 恢复存储提供方连接和后台任务进度，让排队上传完成并触发缓存淘汰。
• 如果希望远端存储成功后自动排队清理本地缓存，保持 cache.eviction_policy = "lru"。

修改缓存设置后，重启 SynapS3，检查 /healthz，再运行 synaps3 admin settings get cache.max_size_gb 验证实际生效值。

Exhausted 任务

列出 exhausted 任务：

synaps3 admin task list --status exhausted --limit 100

确认 RPC 连接、存储提供方可用性、钱包余额、FWSS approval 和缓存磁盘容量都已就绪后，再重试。

synaps3 admin task retry 42

存储提供方或 RPC 问题

在仪表盘查看存储提供方健康状态和 Filecoin readiness，或检查 Admin API：

curl -u admin http://127.0.0.1:9090/api/v1/filecoin/readiness
curl -u admin http://127.0.0.1:9090/api/v1/observability/providers

在 curl 的无回显提示中输入 Admin 密码。

恢复方式：

• 恢复配置中的 filecoin.rpc_url。
• 确认 SynapS3 主机能访问存储提供方 URL。
• 除非明确需要并信任私有存储提供方 URL，否则保持 filecoin.allow_private_networks = false。

S3 客户端无法上传

按顺序检查：

1. S3 客户端使用 path-style addressing。
2. Access key 和 secret key 来自 synaps3 admin s3-user create。
3. 本地评估使用 http://localhost:8080，生产环境使用正确的 HTTPS S3 地址。
4. 对象大小在 127 到 1,065,353,216 字节之间，并且对象键符合 S3 兼容性限制。
5. 仪表盘任务页显示 Filecoin 存储处于 queued、running 还是 exhausted。