故障排查

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

首先检查

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/tasks: 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
synaps3 admin settings get cache.eviction_policy
synaps3 admin settings get cache.lru_high_watermark_percent
synaps3 admin settings get cache.lru_low_watermark_percent

恢复方式：

• 先确认主机仍有可用磁盘空间，再按容量增大 cache.max_size_gb。
• 恢复存储提供方连接和后台任务进度，让排队上传完成并触发缓存淘汰。
• 默认的 lru 适合按容量自动清理。降低高水位可以为新写入保留更多余量，并始终满足 0 <= low < high <= 100。
• 只有希望版本达到存储桶要求的最低耐久副本数后异步删除对应版本时，才使用 after_upload。
• 需要完全禁用自动清理时使用 none。

LRU 无法清理 multipart 暂存数据、未达到存储桶最低耐久副本数的版本，或没有可读已提交远端副本的版本。写入不会同步触发清理，因此在后台清理追赶完成或出现安全候选前，仍可能继续返回 507 Insufficient Storage。

LRU 删除失败后，任务仍会作为 failed 工作保留。先修复任务中报告的文件系统或数据库问题；任务标记为可重试时，可运行 synaps3 admin task retry <id>。

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

Failed 任务

列出 failed 任务：

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

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

synaps3 admin task retry 42

API 会标明每个失败任务是否可使用 Retry。存储提供方替换从 Details → Storage → Data Sets 恢复。只有尚未发出广播的钱包操作可以从 Tasks 恢复；广播结果不确定时仍不可重试。Store 结果不确定时会提供 Check again，它只观察存储提供方，不会再次上传。远端副本删除超过 24 小时仍无法确认时，Recover 会先检查链上状态；若副本仍存在且未排队删除，可能再次提交付费请求，而先前的请求仍可能成功。若数据集在链上不再活跃，链上无法据此确认这份副本已删除，任务会继续核查，不会将其记为已删除。只有在核对失败结果后才使用 Dismiss 或 synaps3 admin task acknowledge <id>；确认后的任务会继续保留配置的时长，再由后台清理。失败任务积压时，任务页的 Dismiss all 会处理当前操作类型筛选下的失败任务，命令行对应 synaps3 admin task acknowledge --type <操作> --yes；在你确认之后才记录的失败仍会留在列表里。

存储提供方或 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、waiting 还是 failed。