加密与安全
零知识架构——你的密钥、你的数据、你做主
AES-256-GCM 端到端加密
所有备份数据在离开你的设备之前，就用 AES-256-GCM 加密。GCM 自带认证，无需额外的 HMAC。Ginkgo 只用这一种加密算法——只有一条路径需要审计，没有「选错算法」的风险。
| 项目 | 值 |
|---|---|
| 加密算法 | AES-256-GCM |
| 密钥长度 | 256 位 |
| 密码派生 | Argon2id（time=3, memory=64MB, threads=4） |
| 派生用途 | Argon2id 派生 KEK 包装主密钥；HKDF-SHA256 用于云 GC 读取路径派生 blob 密钥 |
| Nonce 长度 | 12 字节 |
密钥层级
采用多层密钥设计：用户密码派生密钥加密密钥（KEK）来包装主密钥，主密钥统一加密所有数据块与清单。云仓库使用各自独立的主密钥，与本机仓库互不影响。
| 层级 | 说明 |
|---|---|
User Password | 用户密码（可选输入，启用加密后必填） |
KEK (Argon2id) | 密钥加密密钥，由密码经 Argon2id 派生，仅用于在 repo.key 中包装主密钥 |
Master Key | 主密钥，随机 32 字节，统一加密所有 blob（GB1/GB2）与清单（GKM1） |
Cloud Repo Master Key | 云仓库主密钥，每个云后端独立生成，与本机主密钥互不影响 |
repo.key 文件 | 存储被 KEK 包装后的主密钥（GEK1 二进制或 JSON 格式） |
零知识设计
加密密钥只生成并存储在你的设备上，Ginkgo 服务器无法读取你的数据。即使云存储被入侵，没有密钥拿到的也只是无法识别的密文。
恢复码——忘记密码的救命稻草
零知识加密意味着：忘记密码 = 数据无法恢复。所以务必在开启加密后导出恢复码并妥善保存（比如打印出来或存到密码管理器）。
凭证加密存储
云存储凭证（S3 密钥、WebDAV 密码、OAuth Token）用仓库加密密钥加密后存入本地数据库，API 响应中永远不会返回解密后的凭证。
勒索软件防护
Ginkgo 的跨仓库保护能检测异常的文件批量变更。通过 WebDAV 同步到云端的备份与本机完全隔离，勒索软件无法触及。即使本机被感染，云端备份依然安全，可以回滚到中毒前的版本。
配置保险库
安全备份和恢复应用配置——设置、调度、仓库布局。重装系统后无需重新配置，一键恢复全部设置。
密钥导出与导入
通过 API 导出加密密钥用于灾难恢复，或导入到新机器以重新访问旧备份。
TLS 与本地 CA
当 API 服务监听 0.0.0.0 或在 headless 模式下运行时，Ginkgo Backup 会自动开启 TLS，使用 ECDSA P-256 算法生成本地 CA 和服务器证书。CA 证书包含 NameConstraints 与用户配置的公网 IP SANs（以 /32 或 /128 网段写入 PermittedIPRanges），避免与其他实例的 CA 冲突。
首次启用 TLS
运行 ginkgo-server --tls-auto 自动生成本地 CA 和服务器证书
运行 ginkgo-server --tls-trust（需要管理员权限）将 CA 安装到系统信任库；安装前会自动清理同名旧 CA
CLI 端使用 --tls 或导出 GINKGO_TLS=1 通过 HTTPS 连接
TOTP 双因素认证
为 WebUI 登录启用 TOTP（基于时间的一次性密码）双因素认证，防止密码泄露导致账号被接管。TOTP 端点位于 /api/v1/auth/totp/*。
POST /api/v1/auth/totp/setup 开始设置，返回二维码与密钥
在 Authenticator App（Google Authenticator、1Password 等）扫码绑定
POST /api/v1/auth/totp/confirm 提交验证码确认绑定
POST /api/v1/auth/totp/disable 可禁用 2FA（需要当前 TOTP 码）
WebUI 访问密码
当 API 服务监听 0.0.0.0 时，强烈建议设置 WebUI 访问密码，防止局域网内未授权访问。Token 与密码配合使用：Token 用于 API 客户端，密码用于浏览器登录 WebUI。
运行 ginkgo-server --set-password <密码> 设置密码后退出
或通过 API POST /api/v1/auth/password 修改密码
浏览器首次访问 WebUI 会要求输入密码，登录后建立会话