备份、升级和恢复哪吒 Dashboard
建立哪吒 Dashboard 的一致性备份、升级前检查、恢复和迁移验证流程。
备份、升级和恢复哪吒 Dashboard
[!info] related notes
目标与恢复点
备份必须能恢复 Dashboard 配置、SQLite 数据、用户与服务器记录，并让现有 Agent 使用原 UUID 重新上线。仅备份二进制文件没有价值。
备份对象
独立部署通常需要：
/opt/nezha/dashboard/data/：配置和 SQLite。- systemd unit：确认启动用户、WorkingDirectory 和环境变量。
- Caddy/Nginx 配置和证书获取方式。
- 自定义前端模板、通知配置和额外资源。
- 当前 Dashboard 与 Agent 版本清单。
不要把密钥明文放进公开仓库。备份应限制访问并验证可恢复性；若归档没有客户端加密，应明确记录这个安全边界。
Oracle2 当前备份模型
2026-09-08 起，哪吒有两层备份：
层 1：本机变更前回滚快照
仍保留：
/opt/nezha/dashboard/data/config.yaml.bak-*：重大配置/UI 变更前保存的配置快照。/opt/nezha/dashboard/data/sqlite.db.bak-*：删除服务器、增加监控、UI 调整等操作前保存的 SQLite 快照。/opt/nezha/dashboard/theme-backups/20260908T042214Z/：切回 Dashboard 内置 Nazhua 前，对旧本地主题覆盖目录和配置做的归档。
它们解决的是“刚改坏了怎么快速回滚”。
层 2：Oracle2 共用 OneDrive 周备份
哪吒不单独创建自己的 timer，而是接入 Oracle2 统一的：
oracle2-agent-backup.timer
↓
personal-infrastructure/etc/server/oracle2/backup-to-onedrive.sh
↓
myonedrive:/ServerBackups/Oracle2当前归档格式：
schema=oracle2-runtime-backup-v3
components=hermes,cpa,nezha-dashboard,sub-store哪吒 payload 包含：
nezha/
├── config.yaml
├── sqlite.db
├── nezha-dashboard.service
└── dashboard-version.txt其中 sqlite.db 不是在运行时直接 cp，而是使用 SQLite online backup：
sqlite3 /opt/nezha/dashboard/data/sqlite.db \
".backup '<staging>/nezha/sqlite.db'"随后对副本执行：
PRAGMA integrity_check;只有结果为 ok 才继续打包和上传。Caddy 配置同时由 Oracle2 的 CPA payload 保存，因此灾难恢复时哪吒 Web/gRPC 反向代理也有同一批次的异地副本。
[!important] 当前安全边界 Oracle2 周归档目前是普通
tar.gz，MANIFEST标记为protection=onedrive-access-control-only。config.yaml含 secret，所以 OneDrive 账号访问控制、MFA 和 OAuth 应用安全属于备份安全边界；当前并非客户端加密备份。
2026-09-08 验收
新周备份已经真实上传并通过 restore-drill.sh：
oracle2-agent-20260908T044352Z.tar.gz验证包含：外层 SHA-256、内层 SHA256SUMS、SQLite integrity_check = ok、恢复 payload 结构，以及备份结束后 nezha-dashboard.service = active。
实现位于 personal-infrastructure 提交：
d832727 feat(backup): include Nezha and Sub-Store in Oracle2 weekly backups当前主题恢复边界
生产已回归 Dashboard 内置 Nazhua：
user_template: nazhua-dist并且生产目录不再保留 /opt/nezha/dashboard/nazhua-dist/ 本地覆盖。旧主题二改只作为历史回滚材料保存在 theme-backups，不再属于长期生产恢复的必要对象。正常灾难恢复优先恢复 data/、systemd、Caddy 和版本信息，然后直接使用内置 Nazhua。
SQLite 一致性备份
短暂停机最简单可靠：
sudo systemctl stop nezha-dashboard
sudo tar -C /opt -czf /var/backups/nezha-$(date +%F).tar.gz nezha
sudo systemctl start nezha-dashboard在线生产备份则优先使用 SQLite 自身备份命令，而不是在高写入时直接复制文件：
sudo sqlite3 /opt/nezha/dashboard/data/sqlite.db \
'.backup /var/backups/nezha-sqlite.db'
sudo sqlite3 /var/backups/nezha-sqlite.db 'PRAGMA integrity_check;'期望输出为 ok。Oracle2 周备份已经采用这一方案。
推荐的两层备份模型
层 1：本机变更前快照
用于几十秒内回滚最近一次错误操作：
/opt/nezha/dashboard/data/config.yaml.bak-<reason>-<timestamp>
/opt/nezha/dashboard/data/sqlite.db.bak-<reason>-<timestamp>
/opt/nezha/dashboard/theme-backups/<timestamp>/命名应包含“为什么备份”，而不只是日期，例如 bak-add-network-monitors、bak-ui。
层 2：异地灾备
当前已由 Oracle2 周备份自动完成，包含：
config.yaml- SQLite 一致性副本
nezha-dashboard.service- Dashboard 版本信息
- 同一归档中的 Caddy/CPA 状态
- SHA-256 校验与恢复演练
应用二进制本身仍视为可重建对象：在全新主机恢复时，应先安装与备份记录匹配的 Dashboard 版本，再应用持久状态。旧本地 Nazhua fork 不属于当前生产恢复依赖。
升级前检查
- 记录当前版本与安装方式。
- 阅读目标版本发布说明。
- 确认最近一组 Oracle2 周备份和恢复演练成功；重大升级前可以额外触发一次手动 quick backup。
- 验证备份完整性和剩余远端空间。
- 确认 Caddy、Cloudflare gRPC 与 Agent 版本兼容路径没有变化。
[!warning] V0 与 V1 数据结构 官方文档说明 V0 与 V1 数据库结构不兼容，不能把普通目录复制当作跨大版本迁移方案。
恢复流程
全新主机上的推荐顺序：
- 安装与备份版本匹配的 Nezha Dashboard 二进制和
nezha运行用户。 - 配置 Oracle2 恢复环境与 OneDrive rclone remote。
- 先运行
restore-from-onedrive.sh不带--apply，验证 archive、SHA、SQLite 和 manifest。 - 检查
MANIFEST.txt，确认schema=oracle2-runtime-backup-v3且含nezha-dashboard。 - 明确批准后运行
restore-from-onedrive.sh --apply，脚本恢复config.yaml、SQLite 和 systemd unit，并修正可用的文件所有权。 - 启动 Dashboard 并检查日志。
- 验证用户登录、服务器记录、服务监控和 Agent 重连。
sudo systemctl daemon-reload
sudo systemctl restart nezha-dashboard
sudo systemctl status nezha-dashboard --no-pager
sudo journalctl -u nezha-dashboard -e --no-pager当前使用内置 Nazhua 时，不应为了恢复而重新创建旧的 /opt/nezha/dashboard/nazhua-dist/，除非是在明确执行历史回滚。
恢复验证
-
PRAGMA integrity_check返回ok。 - 外层
.sha256与内层SHA256SUMS都通过。 - Dashboard 版本和数据库迁移成功。
- Caddy gRPC 探测返回
application/grpc。 - 原服务器 UUID 复用，没有批量生成新记录。
- 通知、服务监控和权限边界符合预期。
- 首页使用内置 Nazhua，核心 JS/CSS 返回正确 MIME。
- 旧主机关闭后，新主机仍能独立工作。
Digital Biome