全站统一备份与灾备方案 (AI Workspace)

本文档基于 install.svc.plus (或 root@install.svc.plus) 线上环境的实际部署情况，为你规划和整理了全局的灾备（DR）标准操作流程。除了核心的 PostgreSQL 数据库外，本方案覆盖了 AI Workspace 运行所需的所有核心状态组件（含应用附件、私有镜像、VPN 配置等）。

1. 核心状态组件与目录清单

在进行跨机房/跨区整机迁移时，必须确保以下数据的完整迁移。

1.1 数据库资产

实例用途	运行模式	监听端口/地址	包含的业务系统库
AI 核心服务库	Docker (`postgresql-svc-plus`)	`127.0.0.1:15432`	Account, Vault Storage, Artifact, LiteLLM, OpenClaw, QMD, RAG, Notification, Scheduler, Audit
Zitadel 认证库	Docker (`zitadel-db-1`)	容器内部网	Zitadel IAM 数据
Gitea 代码库	Native Systemd (PG 16)	`127.0.0.1:5434`	Gitea 元数据

1.2 关键文件与持久化挂载卷 (Stateful Volumes)

Important

以下目录是系统恢复后的“血肉”，如果不迁移，即使数据库还原，也会出现图片 404、模型拉取失败、组网断开等致命故障。

Gitea 仓库与对象数据: /var/lib/gitea/data 存储所有的 Git 裸仓库、LFS 大文件、用户头像及附件。
应用私有镜像库 (Harbor / Registry): /data/registry 或挂载的 /data/harbor 私有容器镜像。如果不迁移，新机在重启并执行 docker-compose pull 时将找不到未开源的基础环境镜像。
OpenClaw (AI 网关) 工作目录: openclaw workdir (对应部署时的物理挂载点) 包含 AI Gateway 的本地缓存档、向量化临时数据或加载的模型资产。
分布式组网与 VPN 配置: /etc/wireguard 包含本地节点的 WireGuard Private Key 与 Peers 路由表。若丢失此目录，新主机启动后将无法重新融入原有的 Xworkmate VPN 星型网络，所有跨云微服务通信将中断。
对象存储 (MinIO/S3): /data/minio (若开启) 现代云原生组件（如 Wiki、RAG）的大文件存储底座。
环境密钥文件: 各组件部署目录下的 .env (如 /opt/ai-workspace/)。

Note

例外清单： /etc/caddy/data 或 acme.json（Let's Encrypt 证书）。 处理策略： 灾备演练或真实迁移时无需同步。只需在新主机上线时，提前将 DNS A 记录解析至新 IP，再启动 Caddy 即可实现全自动在线续签。（需注意 Let's Encrypt 每周 5 次的重复签发限频，演练时建议使用 Staging 证书）。

2. 统一备份与同步策略 (Backup & Sync)

2.1 数据库逻辑备份 (PostgreSQL)

建议在宿主机的 /opt/backup/ 目录下创建统一备份脚本 pg_backup.sh 并加入 Cron 定时任务：

#!/bin/bash
BACKUP_DIR="/var/backups/postgresql"
DATE=$(date +"%Y%m%d_%H%M%S")
mkdir -p $BACKUP_DIR

echo "[INFO] 备份 AI 核心服务库 (15432 端口)..."
DB_URL_BASE="postgres://svcplus_vps:<YOUR_PASSWORD>@127.0.0.1:15432"
for DB in account litellm openclaw qmd rag notification scheduler audit artifact vault_storage; do
    pg_dump "$DB_URL_BASE/$DB?sslmode=disable" | gzip > "$BACKUP_DIR/${DB}_$DATE.sql.gz"
done

echo "[INFO] 备份 Zitadel 认证库 (zitadel-db-1)..."
docker exec zitadel-db-1 pg_dumpall -U postgres | gzip > "$BACKUP_DIR/zitadel_$DATE.sql.gz"

echo "[INFO] 备份 Gitea 代码库 (Native PG 16)..."
sudo -u postgres pg_dumpall -p 5434 | gzip > "$BACKUP_DIR/gitea_$DATE.sql.gz"

# 清理 7 天前的旧备份
find $BACKUP_DIR -type f -name "*.sql.gz" -mtime +7 -delete

2.2 文件状态同步 (Rsync 增量同步)

针对文件资源，建议使用 rsync 结合 Ansible 剧本向灾备节点推送，或定时同步到集中式对象存储。关键的 rsync 路径示例：

rsync -avz --delete /var/lib/gitea/data/ backup-server:/backup/gitea/
rsync -avz --delete /etc/wireguard/ backup-server:/backup/wireguard/
rsync -avz --delete /data/registry/ backup-server:/backup/registry/

3. 灾难恢复与还原操作 (Restore)

当发生整机崩溃或机房断网需要启用灾备节点时，严格按以下层级恢复：

阶段 1: 恢复 VPN 与网络层 在安装任何服务前，首先将 /etc/wireguard 目录还原，并启动 wg-quick up wg0，确保灾备节点重新获取原集群内网 IP。

阶段 2: 恢复对象与文件持久层 将备份好的 Gitea、OpenClaw workdir、应用镜像目录等还原至宿主机的绝对路径中，并修复属主权限（如 chown -R 1000:1000 /var/lib/gitea）。

阶段 3: 恢复 PostgreSQL 数据库层 确保仅启动数据库容器（停掉应用层容器）。

# 1. 还原 AI 核心库
gunzip -c /var/backups/postgresql/account_YYYYMMDD.sql.gz | psql "postgres://...:15432/account"

# 2. 还原 Zitadel 库
gunzip -c /var/backups/postgresql/zitadel_YYYYMMDD.sql.gz | docker exec -i zitadel-db-1 psql -U postgres

# 3. 还原 Gitea 库
gunzip -c /var/backups/postgresql/gitea_YYYYMMDD.sql.gz | sudo -u postgres psql -p 5434

阶段 4: 启动接入层与业务应用

确认全网 DNS 已切换至当前灾备节点公网 IP。
启动 Caddy 服务，系统会自动发起 HTTP-01 质询申请全新证书。
全面上线 docker-compose up -d 拉起各业务线应用。

5.3 KiB Raw Blame History Unescape Escape