故障排查

本页针对稳定版 v0.11.0。先用下面的最小检查定位问题出在哪一段，再按现象进入对应小节。

先收集事实

1. 确认服务与状态

   curl -fsS http://127.0.0.1:23333/ready
   docker exec depsilo /app/depsilo doctor --json

   /ready 检查 SQLite 与对象存储；/health 只是进程存活信号，两者不能互相替代。

2. 看请求到底走了哪里

   Admin 的 Access logs（/admin/logs）记录生态、包名、状态与命中结果；Portal 的“监控”页展示上游健康、探测延迟和命中率。

3. 生成可分享的诊断报告

   如果按快速开始使用 Docker，先在容器内生成报告，再复制到本机：

   docker exec depsilo /app/depsilo diagnose \
     --out /root/.depsilo/depsilo-diagnostic.json
   docker cp depsilo:/root/.depsilo/depsilo-diagnostic.json \
     ./depsilo-diagnostic.json

   如果直接安装了二进制文件，在本机运行 depsilo diagnose --out depsilo-diagnostic.json。报告以仅所有者可读的权限创建，不含配置内容、凭据、请求样本、包名和客户端地址。再次运行时换一个文件名；命令不会覆盖已有报告。分享前仍应检查内容。

请求没有经过 Depsilo

• localhost 陷阱：容器、CI Runner 或远程机器里的 localhost 指向它自己，不是宿主机。换成客户端实际可达的主机名或 IP。
• 配置没被读取：确认客户端真的在使用新地址，例如 npm config get registry、go env GOPROXY、mvn help:effective-settings、bundle config get mirror.https://rubygems.org。项目级配置可能覆盖你改的用户级文件。
• 修改后未重启客户端：Docker 需要重启 daemon；某些 IDE 与构建守护进程会缓存旧配置。
• 回退路径仍在生效：extra-index-url、|direct、Composer 的原始 dist URL 都可能让请求绕过 Depsilo。见连接包管理器中的强制边界说明。

出现 451

响应代码	含义	处理
QUARANTINED	版本早于最低发布年龄阈值	等待阈值过后重试，或由管理员批准该 (生态, 包, 版本)
MALICIOUS_BLOCKED	命中已知恶意包数据集	不要绕过；确认包名与版本是否正确，误报走有记录的临时覆盖
SNAPSHOT_BLOCKED	快照模式下请求了快照外的版本	使用快照内的版本，或调整快照

批准与覆盖都会进入审计；恶意包的临时覆盖最长 24 小时，且不能原地延期，继续使用必须重新作出有记录的决定。策略细节见供应链安全。

认证与管理面问题

• bootstrap token 只用于首次设置，不能当作包管理器或 MCP 的长期凭据；MCP 使用 Admin 中创建的普通只读 API token。
• 管理面没有默认账号；首位管理员由首次设置创建。忘记密码时按部署文档的恢复流程处理，不要尝试猜测默认值。
• 显式配置文件下，监听非 loopback 地址时 auth.jwt_secret = "change-me-in-production" 会导致启动失败；用秘密管理系统注入至少 32 字节的随机值。
• API token 只保存哈希，明文只在创建时显示一次；丢失后只能重新创建。

命中率低或反复 MISS

• 第一次请求通常是 MISS，第二次同请求才适合验证缓存。
• 元数据与制品有不同的 TTL：内置默认 cache.ttl_index 为 5m、cache.ttl_blob 为 72h；样例文件是显式覆盖，不等同于默认值。
• 缓存有容量上限（默认 cache.max_size_gb = 20），LRU 淘汰后需要重新回源。
• 带上游凭据的响应不会进入共享缓存，按设计每次都回源。
• 策略在缓存查找之前执行，因此缓存中存在但被策略拒绝的版本仍会返回 451。

上游异常

• /ready 故意不检查上游：上游中断时 Depsilo 仍可能提供已有缓存，这是预期行为。
• 上游选择使用最高优先级的健康源；健康检查或一次请求结果把当前源标为不健康后，后续请求才会选择备用源，当前失败的请求不会自动重试。
• 在 Admin 的 Monitor 页查看镜像健康与探测延迟；持续失败时检查上游地址、网络出口与凭据。
• 删除某个生态的最后一个上游源会返回 409 LAST_UPSTREAM；先添加替代源再删除。

磁盘、状态与备份

• 配置与 SQLite 始终是本地状态；S3 只保存对象缓存，不会把实例变成多实例或高可用部署。
• depsilo backup 的归档包含 config.toml 与一致的 SQLite 快照，不包含本地或 S3 缓存对象。
• 使用主机目录时，目录必须是镜像固定身份 10001:10001 且挂载到 /root/.depsilo；命名卷与主机目录之间切换等于换了一份状态。
• 恢复前必须停止持有目标数据库的服务，先隔离演练再覆盖生产状态。

升级与版本问题

• 生产环境固定 X.Y.Z 标签或摘要，不要使用 latest；升级前阅读目标版本的发布说明。
• 二进制守护进程跨版本升级时，先确认记录的进程已经结束；v0.9.1 起不再接受 v0.9.0 的旧 PID 记录，必要时按发布说明手工清理。
• 升级后重新执行 /ready、doctor 与一次真实客户端拉取，不要只以“容器已启动”作为成功标准。

仍然无法解决

准备好 depsilo diagnose 报告、doctor --json 输出、相关 Access log 时间点与客户端配置片段（去掉凭据）后再寻求帮助。不要把 bootstrap token、API token、JWT secret 或完整配置文件粘贴到公开渠道。