故障排查

按问题类型快速定位解决方案，多数问题可在日志中找到线索

通用排查思路

遇到问题时，先查看 ~/.ginkgo-backup/logs/ 下的详细日志，再调用 GET /api/v1/oversight/health 检查系统健康状态。本页按问题类型整理了常见症状与解决方案。

查看日志

日志位于 ~/.ginkgo-backup/logs/ 目录，按日期分文件。也可通过 API 查看：

Shell

# 获取最近日志 curl http://127.0.0.1:9275/api/v1/logs \ -H "Authorization: Bearer $TOKEN" # 系统健康检查 curl http://127.0.0.1:9275/api/v1/oversight/health \ -H "Authorization: Bearer $TOKEN"

问题分类

服务器问题

服务器无法启动

  • 检查端口 9275 是否被占用：netstat -an | grep 9275
  • 指定其他端口启动：./ginkgo-server --port 8080
  • 检查数据目录权限：~/.ginkgo-backup/
  • 查看 ~/.ginkgo-backup/logs/ 下的启动日志

SQLITE_BUSY / database is locked 错误

  • Ginkgo 已内置并发优化，通常会自动处理
  • 若持续出现，检查是否有外部进程访问 ginkgo.db
  • 服务器运行时切勿用外部 SQLite 工具打开数据库文件

认证 Token 丢失

  • 查看 ~/.ginkgo-backup/config.json 中的自动生成 Token
  • 若已丢失，删除 ~/.ginkgo-backup/config.json 并重启服务器，会生成新 Token

备份问题

备份似乎卡住不动

  • 检查源目录是否包含超大文件（可能在哈希计算阶段）
  • 查看备份进度：GET /api/v1/backup/progress
  • 取消并重试：POST /api/v1/backup/cancel

备份占用内存过高

  • 管道有基于系统内存的内置限制
  • 降低源设置中的 chunk_concurrency
  • 检查是否有超大文件被整体读入内存

文件未被备份

  • 检查排除模式：GET /api/v1/sources/{id}
  • 检查源目录下的 .ginkgo-backupignore 文件
  • 查看备份日志：GET /api/v1/logs?source_id={id}

恢复问题

恢复失败，提示解密错误

  • 确认选择了正确的仓库
  • 若密钥已更换，导入旧密钥：POST /api/v1/keys/import
  • 使用恢复码：POST /api/v1/recovery-code/import

恢复后的文件时间戳不正确

  • 部分文件系统不支持精确时间戳，这是预期行为
  • 可在 manifest 中查看原始 mtime：GET /api/v1/snapshots/{id}

云同步问题

云同步失败

  • 测试云连接：POST /api/v1/cloud/test
  • 检查 OAuth2 Token 是否过期（通常自动刷新，但被撤销时会失败）
  • 检查到云端的网络连通性
  • 查看日志中的具体错误信息

OneDrive/Dropbox 上传报 404

  • 父目录必须先存在——Ginkgo 会自动创建
  • 若问题持续，删除并重新创建云后端
  • 确认 OAuth2 应用未被撤销

Google Drive 出现重复文件夹

  • 确认使用 drive scope（而非 drive.file）
  • drive.file scope 无法列出现有文件夹，导致重复创建
  • 删除重复文件夹并使用正确 scope 重新授权

GC 问题

GC 删除了过多数据

  • 检查 GC 安全级别是否过于激进
  • 生产环境使用 Normal 或 Paranoid 级别
  • 始终先用 dry_run 预览：POST /api/v1/retention/gc?dry_run=true
  • 检查回收站目录：<repo>/.ginkgo-backup/trash/

GC 未按预期运行

  • GC 有最小间隔（默认 4 小时）
  • 查看上次 GC 时间：GET /api/v1/oversight/cleanup-logs
  • 使用 force: true 跳过间隔检查

挂载问题

Linux 上挂载失败

  • 确认已安装 WinFSP（Windows）或 FUSE（Linux/macOS）
  • 构建时使用 CGO_ENABLED=0 以包含 FUSE 支持
  • 检查挂载点权限

WebDAV 挂载断开

  • WebDAV 会话 30 分钟后自动过期
  • 重新挂载：POST /api/v1/mount/{source_id}
  • 确认服务器仍在运行

TLS 与证书

浏览器提示证书无效或不受信任

  • 运行 ginkgo-server --tls-trust 将本地 CA 安装到系统信任库（需要管理员权限）
  • 安装前会自动清理同名旧 CA，避免冲突
  • 确保 CA 证书的 PermittedIPRanges 包含你访问的公网 IP SAN
  • CLI 端使用 --tls 或 GINKGO_TLS=1 启用 HTTPS 连接

Headless 模式下无法访问 API

  • Headless 模式默认监听 0.0.0.0 并自动开启 TLS
  • 确认防火墙允许 9275 端口（或自定义端口）
  • 使用 https://<IP>:9275/api/v1/health 验证（注意 https）
  • 如需公网访问，建议在前端反向代理（Caddy/Nginx）启用公开 CA 证书

公网 IP 变化后证书失效

  • EnsureLocalCert 会检查现有 CA 的 PermittedIPRanges 是否覆盖新公网 IP SAN
  • 在「设置」中更新公网 IP SAN 后重启服务，会自动重新生成 CA 和证书

WebUI 密码与 TOTP

忘记 WebUI 访问密码

  • 在服务器本机运行：ginkgo-server --set-password <新密码>
  • 或直接编辑 ~/.ginkgo-backup/config.json 重置密码字段后重启服务
  • 重置密码不会影响 Token 认证和已建立的 API 客户端

TOTP 2FA 手机丢失无法登录

  • 使用启用 2FA 时保存的备用恢复码
  • 若无恢复码，可在服务器本机直接调用 POST /api/v1/auth/totp/disable 禁用 2FA
  • 禁用后建议重新启用 2FA 并保存新的恢复码

CLI 报「证书验证失败」

  • 确认已运行 --tls-trust 安装本地 CA
  • 或使用 GINKGO_TLS=1 让 CLI 走 HTTPS
  • 若使用自签证书且未安装 CA，CLI 会拒绝连接以保证安全

许可证与激活

首次启动要求输入激活码

  • 所有用户首次启动都需要输入激活码以绑定发行商并加载品牌配置
  • 激活码由你的发行商提供，分为主激活码（无限次激活）和付费许可（100/60 个）
  • 一旦绑定到某个发行商，无法切换到其他发行商
  • 免费版激活码可永久使用，保护最多 5 个项目

激活码无效或已用完

  • 联系你的发行商确认激活码状态
  • 付费许可激活码有次数限制（每包 100 或 60 个）
  • 经销商通过 Creem 平台支付 $1000 购买经销商包并自动开通账户
  • 许可证使用 ed25519 本地签名验证，公司停业时进入 Sunset Mode 仍可正常使用

Mesh Backup 节点数受限

  • 免费版 Mesh Backup 限制 1 个对等节点（你的电脑 + 1 台其他设备）
  • 购买终身版或家庭版可解除节点限制
  • 许可证通过本地 ed25519 签名验证，无需联网

获取帮助

若以上方案无法解决问题：

GitHub Issues

https://github.com/ginkgo-backup/ginkgo/issues

邮箱支持

[email protected]

日志位置

~/.ginkgo-backup/logs/

健康检查

GET /api/v1/oversight/health

相关文档

CLI 命令参考API 参考配置详解