故障排查

先用内置诊断：

downctl doctor          # 版本、Python、依赖、代理、插件数
downctl -v get <url>    # 详细模式（意外错误会打印堆栈）

下载

中断后会从头开始吗？ 不会。按分片位图续传，重跑同一命令只补缺失分片。（DOWNCTL_TRUST_PARTIAL=1 只影响“大小已达预期、但无法探测稀疏空洞”的本地文件是否判为完整，不是用来续传比预期更小的部分文件。）

重跑会全部重下吗？ 已完成的文件会被跳过（位图账本，或大小/校验和匹配）。

提示磁盘空间不足 每个文件下载前会做磁盘预检（保留 200MB 余量），只失败当前文件。清出空间后重跑即可续传。

传输像是卡住了 连续 --stall 秒无进展会触发看门狗断开重连。可调整 --stall，或检查代理/网络。

checksum failed N times 文件反复校验不通过。请核对预期哈希（或来源）——服务端内容被改动时将永不通过。

401/403/404 私有资源或匿名限流。提供令牌（HF_TOKEN/GITHUB_TOKEN 或插件 token），或使用 --mirror。

代理 / WSL 用 -p 或 https_proxy/HTTP_PROXY 环境变量。WSL 下自动探测 Windows 宿主代理；可用 WSL_HOST_IP 覆盖宿主地址。downctl doctor 会打印探测到的代理。

重定向到其他主机时令牌会跟着走吗？ 不会。令牌是按主机的（仅 HF/GitHub）；共享会话不带全局 Authorization，因此凭据不会发往无关主机。

"Host key is not trusted" 默认按 ~/.ssh/known_hosts 校验主机密钥。请把主机密钥加入，或用 [plugins.sftp] known_hosts = ""（也接受 none/false）关闭校验。

"SFTP support requires asyncssh" 安装可选依赖：pip install 'downctl[sftp]'。

预签名 URL 会过期（默认 1 小时）。超长传输可能超过有效期——调大 [plugins.s3] expires（最大 7 天）或重跑。

downctl status <目录>    # 未完成 + 失败
downctl clean <目录>     # 清理残留位图 / 失败清单 / 失效锁

clean 绝不删除无法确认属主已死的锁目录，也绝不触碰你的数据文件。