自部署故障排查

下面每个英文标题都是稳定链接锚点。涉及 Compose 的命令均在 deploy/selfhost 执行；日志可能含初始化码，分享前先脱敏。

app-connection

APP 无法连接时，先确认服务器已启动，再原样复制部署向导给出的地址并点击“测试连接”。只有本机回环地址允许 HTTP，其他地址需要 HTTPS。检查下方的证书、Host 与实例身份条目；不要通过关闭证书校验解决连接问题。

cert-untrusted

现象： APP 提示证书不受信任。

原因： 自签名证书、证书链不完整或签发根不在系统信任库。

解决： 检查网关提供的完整证书链，使用系统信任的证书；企业 CA 由管理员按组织要求安装到客户端系统信任库。APP 没有跳过校验按钮。本机试用可改用 local 预设的回环地址。

cert-expired

现象： 提示证书已过期。

原因： 网关证书过期、续期失败，或客户端时间错误。

解决： 先校准时间，检查网关续期、DNS 与 80/443 可达性，更新证书后重测。保留 Caddy 状态卷；不要通过反复重装申请证书。

cert-name-mismatch

现象： 提示域名不匹配。

原因： APP 输入的主机名不在证书覆盖范围，或网关返回了其他站点证书。

解决： 使用证书对应的域名，检查 DNS、虚拟主机与证书绑定；不要把 HTTPS 域名替换为裸地址。

port-in-use

现象： 安装提示 80/443 或本机服务端口已被占用。

原因： 已有 Web 服务或另一套容器监听相同端口。

解决： 用 ss 或 netstat 确认占用者，再决定调整；已有网关时优先使用 proxy 预设，不直接停止不明服务。

aaaa-record

现象： 安装 DNS 检查失败，或部分设备打不开服务。

原因： AAAA 指向旧地址，服务器没有对应 IPv6，或 A/AAAA 与当前出口不一致。

解决： 在 DNS 控制台校正记录，没有可用 IPv6 时移除错误 AAAA，等待缓存更新后重试。CDN、多出口或特殊 NAT 改用 proxy 方案。

setup-code-expired

现象： 初始化码过期、失效或连续输错后不能创建管理员。

原因： 超过 30 分钟、Server 已重启或累计输错 5 次。

解决： docker compose restart server 后在私人终端运行 docker compose logs --since 1m server 获取新码。若已初始化，直接登录；不要重启 Caddy。

startup-warnings

现象： 首次创建管理员前可能周期性出现 Instance initialization unavailable; retrying in background，也可能看到一条 Fastify 弃用警告。

原因： 前者表示某项启动任务失败后正在后台重试，例如官方风格库暂时不可达。查看同条日志的 task：avatar-styles 是风格库，另外还可能是 server-settings、instance-identity 或 setup-code；并非所有重试都无影响。Fastify 弃用警告提示依赖接口将来需调整，本身不是进程退出或健康失败。

解决： 若健康检查成功、初始化码正常输出且 APP 可连接，风格库暂不可达的重试和单独的弃用警告是可出现的非致命日志，可继续创建管理员，不必反复重装。若没有初始化码、身份检查失败或健康检查不通过，检查对应任务与数据库/网络；持续失败不能当作正常。初始化码失效按 取新码步骤 处理。后台重试也可能发生在管理员创建之后。

database-migration-failed

现象： Server 输出迁移错误并反复重启，健康检查不通过。

原因： 数据库连接、权限或 migration 状态异常。

解决： 先 docker compose logs server 查看原因，再 docker compose stop server 停止循环；保留数据与备份，修复数据库或迁移状态后用 docker compose up -d --wait --wait-timeout 180 恢复。不能跳过迁移，迁移后不能只回退镜像。

restore-existing-env

现象： 恢复提示已有 .env。

原因： 当前环境不是空环境，可能先执行了安装向导。

解决： 保留原环境，换全新主机和源码目录，不先运行安装脚本；不要为绕过保护删除现有配置。

restore-existing-volumes

现象： 恢复提示已有项目数据卷。

原因： 固定 Compose 项目名下已有数据；换源码目录也不等于换数据卷。

解决： 使用全新 Docker 主机。不要执行 down -v 清空原数据来强行恢复。

restore-materials

现象： 口令错误、恢复文件损坏、摘要不符、分片缺失或不完整。

原因： 口令不正确、两份材料不配套、传输损坏，或使用了 .partial 输出。

解决： 核对原始完整数据目录和对应 .skr，重新传输并运行 verify；口令无法找回时不能解密，不编辑 manifest 绕过校验。

restore-version

现象： 恢复拒绝当前代码或缺少备份 migration。

原因： 当前代码比备份旧，或源码不完整。

解决： 使用不低于备份时版本的完整源码；不要手工删除迁移记录以通过检查。

restore-postgres

现象： Postgres 主版本不匹配。

原因： 恢复工具环境与备份的数据库大版本不同。

解决： 使用匹配的大版本恢复，跨大版本升级单独处理，不能直接换镜像大版本挂旧卷。

restore-verification

现象： 数据写入后恢复仍失败，或身份、密文、媒体、卡片验证不通过。

原因： 身份/加密材料不一致、引用文件缺失、对象服务无法访问或健康检查失败。

解决： 保留失败现场与工具输出的详细日志路径，不宣布恢复成功。检查配套材料、权限、对象服务及配置；另建空环境重试。正常删除的媒体墓碑不算缺失；外部 S3 需有独立备份。

s3-namespace-unavailable

现象： 读取图片或卡片返回 503，恢复统计中 unavailable 非零。

原因： 旧记录的 namespace 与当前 endpoint/bucket/prefix 不匹配。

解决： 恢复旧配置及服务可达性，先复制校验并改指到 filesystem，再更换 S3 配置。不要把 503 当作对象丢失，也不要直接覆盖数据库中的归属。

s3-access

现象： 对象读取 503，恢复出现 failed 或 missing。

原因： failed 可能是认证或网络错误；missing 是确认缺失。缺 s3:ListBucket 时，缺失对象可能返回 403。

解决： 检查 bucket、region、endpoint、凭据与对象权限，补足 s3:ListBucket；确认真正缺失后从对象存储备份恢复。配置方法见 S3 与 OSS。

host-mismatch

现象： 健康检查通过，但登录等请求返回 421 HOST_MISMATCH。

原因： 网关未保留外部 Host，或外部地址没有列入实例配置。

解决： 核对 PUBLIC_BASE_URL、附加地址与网关 Host。健康接口通过不能证明业务 Host 配置正确。

instance-changed

现象： 相同地址提示实例身份变化，无法连接。

原因： 数据库重建或身份密钥更换，使它不再是先前信任的实例。

解决： 确认是否恢复了完整配置与数据库；真正的新实例使用新基址。不要删除本机身份记录来复用旧空间授权。