From 0f7b99c6872ea1cfe4577e3d18c8b2bcd6d9dad6 Mon Sep 17 00:00:00 2001
From: nav <nav@mgr.hangman-lab.top>
Date: Tue, 12 May 2026 12:44:08 +0000
Subject: [PATCH] docs(ops): add backup and restore runbook

---
 docs/TODO-backend-center-guild.md  |  2 +-
 docs/backup-and-restore-runbook.md | 83 ++++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+), 1 deletion(-)
 create mode 100644 docs/backup-and-restore-runbook.md

diff --git a/docs/TODO-backend-center-guild.md b/docs/TODO-backend-center-guild.md
index 75ebe08..00ed413 100644
--- a/docs/TODO-backend-center-guild.md
+++ b/docs/TODO-backend-center-guild.md
@@ -97,7 +97,7 @@
 - [x] DB migration 机制（TypeORM migration）
 - [x] 结构化日志 + request id
 - [x] 基础监控指标（QPS、延迟、错误率）
-- [ ] 备份与恢复流程文档
+- [x] 备份与恢复流程文档
 
 ---
 
diff --git a/docs/backup-and-restore-runbook.md b/docs/backup-and-restore-runbook.md
new file mode 100644
index 0000000..6f5d94d
--- /dev/null
+++ b/docs/backup-and-restore-runbook.md
@@ -0,0 +1,83 @@
+# Fabric 备份与恢复 Runbook（v1）
+
+## 1. 范围
+- MySQL Center：`fabric_center`
+- MySQL Guild：`fabric_guild`
+- 可选：持久卷级别备份（`mysql_center_data` / `mysql_guild_data`）
+
+---
+
+## 2. 备份策略（建议）
+- 频率：每天 1 次全量（低峰期）
+- 保留：最近 7~14 天
+- 方式：`mysqldump`（逻辑备份）+ 异地对象存储
+- 校验：每周至少一次恢复演练
+
+---
+
+## 3. 手动备份命令
+> 在 `Fabric/` 目录执行
+
+### 3.1 备份 Center
+```bash
+docker exec fabric-mysql-center sh -lc \
+  'mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" --single-transaction --quick --routines --events fabric_center' \
+  > backup-center-$(date +%F-%H%M%S).sql
+```
+
+### 3.2 备份 Guild
+```bash
+docker exec fabric-mysql-guild sh -lc \
+  'mysqldump -uroot -p"$MYSQL_ROOT_PASSWORD" --single-transaction --quick --routines --events fabric_guild' \
+  > backup-guild-$(date +%F-%H%M%S).sql
+```
+
+### 3.3 压缩
+```bash
+gzip backup-center-*.sql
+gzip backup-guild-*.sql
+```
+
+---
+
+## 4. 恢复流程
+
+### 4.1 停写（建议）
+- 先停 `backend-center` / `backend-guild`，避免恢复时写入冲突。
+
+### 4.2 恢复 Center
+```bash
+gunzip -c backup-center-YYYY-MM-DD-HHMMSS.sql.gz | \
+  docker exec -i fabric-mysql-center sh -lc 'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" fabric_center'
+```
+
+### 4.3 恢复 Guild
+```bash
+gunzip -c backup-guild-YYYY-MM-DD-HHMMSS.sql.gz | \
+  docker exec -i fabric-mysql-guild sh -lc 'mysql -uroot -p"$MYSQL_ROOT_PASSWORD" fabric_guild'
+```
+
+### 4.4 恢复后检查
+- 启动后端服务
+- 调用：
+  - `GET /api/healthz`
+  - `GET /api/metrics`
+- 随机抽查：
+  - 用户登录
+  - 节点注册列表
+  - 消息拉取/回补
+
+---
+
+## 5. 演练清单
+- [ ] 恢复耗时记录
+- [ ] 数据一致性抽样
+- [ ] 回滚预案验证
+- [ ] 文档更新（命令/版本/风险）
+
+---
+
+## 6. 风险与注意事项
+- 恢复前先确认目标库环境（避免误写生产）
+- 密钥与密码不要写入仓库，统一走环境变量
+- `DB_SYNC` 在生产保持 `false`，结构变更走 migration