故障排查

先记录现象、请求状态、发生时间和部署版本，再按下列分支缩小范围。日志只保留必要错误与脱敏摘要，不发送密码、Cookie、MCP Key、完整数据库连接串或私密 RPC 地址。

安装页重复出现或进入维护页

只读检查 GET /api/install/status 的状态与脱敏摘要，并确认当前进程实际使用的应用目录和挂载卷。

主密钥必须与 config/database.enc 匹配。检查原 ENCRYPTION_KEY 是否仍由安全配置提供，或原 config/master.key 是否保留；只确认存在与权限，不输出文件内容。不要删除配置、改安装标记、清空数据库或生成新密钥来掩盖故障。

数据库连接或空库检查失败

• MySQL/PostgreSQL：确认目标库已存在且没有用户表，账号具备初始化权限，网络、端口和 TLS 设置与部署一致。
• Compose：确认数据库健康后应用才启动，已有加密配置与引导参数一致。非空目标库或参数冲突不会自动覆盖。
• SQLite：确认数据库位于本地可写磁盘且只有一个实例使用；不将数据库文件放到网络共享目录。
• 升级：查看启动迁移的具体错误。2.6.10 期望数据库修订 17，不手工修改版本标记跳过失败迁移。

部署默认路径未被调整时，可在目标服务器查看服务状态和最近日志：

sudo docker compose -f /data/slothvault/compose.yml ps
sudo docker compose -f /data/slothvault/compose.yml logs --tail=100 slothvault

这些命令是只读诊断；共享日志前脱敏。若部署目录曾修改，使用实际生成的 Compose 路径。

草稿或正文不可见

先判断访问的是管理员预览还是公开阅读。项目只有未发布版本时，不应因笔记启用而进入公开列表；参与发布的分类、笔记与主正文需启用且未删除，笔记只能有一份有效主正文。

权限拒绝通常区分 401（需要登录）、403（会员不匹配或下载被关闭）、404（隐藏或不存在）。拥有下载名单会员仍必须同时通过阅读条件。文章会员名单与项目权限分别管理，管理员可预览不代表访客可读。

附件另检查业务引用和访问模式：新上传而未绑定的文件只允许管理员访问；正文图片展示与显式下载不是同一权限。不要把文件复制到公开目录作为修复。

MCP 连接失败或写入冲突

连接失败时先检查原生宿主的连接启用状态和工具发现。401 时由管理员在 Key 页面检查 Key 是否启用、到期、删除或账号角色变化；不把网页登录 Cookie 当作 MCP 凭据，也不要求在聊天中发送明文 Key。

VERSION_FROZEN 表示目标已经发布，正文或标签变更应转到复制出的草稿。VERSION_WRITE_CONFLICT 表示修订号过期，先重新读取 outline；DOCUMENTATION_SYNC_INCOMPLETE 表示计划文档尚未全部完成；DOCUMENTATION_CHANGELOG_REQUIRED 表示缺少唯一、包含准确目标版本的集中更新日志。

超时并不证明写入失败。先读回版本、修订号、pending 和已完成键，再判断是否重试；不要重复创建项目、版本、笔记或上传附件。

上传、备份及恢复失败

普通文件上限为 10 MiB、头像为 2 MiB；完整备份的上传使用独立 8 MiB 分片。若分片请求在到达应用前返回 413，检查反向代理单次请求体限制，而不是把整个备份总大小设为限制。

BACKUP_UNSUPPORTED_FORMAT 时核对完整包格式及业务数据版本：当前是格式 2、数据 2.16.0，注册转换版本为 2.13.0、2.14.0、2.15.0。不改 ZIP 内版本字段强行导入；保留原包并查看校验结果。

恢复会覆盖业务数据，必须经过恢复预检和恢复前保护备份。保护备份失败应停止；磁盘不足、附件损坏或摘要不符时先修复对应问题，不绕过校验。事务默认一小时，压缩、上传和预检不计入这项事务超时。

钱包或存证状态异常

Devnet 项目版本及委托签名仅允许当前选中的 Phantom 适配器；使用其他钱包时，不应自动切换为 Mainnet。当前签名与登录协议仅支持 Solana。

业务记录冻结、待签名、广播中和已上链是不同状态。网络中断或响应丢失时，先对账已保存的原签名或重播相同交易字节；不要未经核对就再次签名。明确的交易执行错误按返回 reason 定位，钱包取消不撤销已提交业务记录。只有实际匹配的 finalized 交易才能确认上链。