灾难恢复运行手册

恢复目标

• RPO（恢复点目标）：已推送到权威Git仓库的代码和内容为零数据丢失；尚未推送的本地修改不在保证范围内。
• RTO（恢复时间目标）：在代码托管、包注册表和静态托管平台可用的前提下，4小时内恢复可访问站点。

权威数据源

• 私有Git仓库是文章、动画、配置、自动化脚本和运行手册的权威来源。
• package-lock.json固定依赖解析结果。
• docs/.vitepress/dist/、node_modules/和本地缓存均为可重新生成内容，不是备份。
• 当前项目没有生产数据库和用户上传文件，因此没有Git之外的业务数据备份对象。

前置条件

• 一台干净的构建机；
• Git；
• Node.js 22 LTS及npm；
• 权威Git仓库的只读或读写权限；
• 静态托管平台的项目管理权限；
• DNS服务商的管理权限；
• 部署所需凭据能够从批准的密钥管理系统恢复或重新签发。

密钥清单

仓库内不得保存令牌、私钥、Cookie或生产凭据。

密钥或权限	保存位置	恢复方式
Git仓库访问权限	代码托管平台	由组织管理员重新授权
静态托管部署权限	托管平台或CI内置令牌	重新连接项目或重新签发
DNS管理权限	DNS服务商	由账户管理员恢复

本地开发不需要生产密钥。若未来增加外部API，必须先在本表登记其用途、保管位置、轮换方式和失效处理。

从干净机器恢复

git clone <private-repository-url> energy-handbook-site
cd energy-handbook-site
git fetch --tags --prune
git checkout <approved-branch-or-tag>
npm ci
npm run check

构建成功后，静态站点位于：

docs/.vitepress/dist/

验证本地预览：

npm run docs:preview

至少检查：

1. 首页可访问；
2. 侧边栏和本地搜索可用；
3. 关键知识文章可打开；
4. docs/public/demos/中的动画可以播放和单步执行；
5. 浏览器控制台没有阻断页面使用的错误；
6. 当前页面版本能够追溯到明确的Git提交SHA。

恢复部署

1. 在静态托管平台创建或恢复项目。
2. 将项目连接到权威Git仓库和批准的发布分支。
3. 使用仓库中的CI工作流构建和发布，不上传本地缓存或手工修改后的构建目录。
4. 记录部署对应的提交SHA和构建日志。
5. 使用平台分配的临时域名完成健康检查。

DNS与TLS恢复

1. 从DNS服务商的变更记录或外部配置备份恢复所需记录。
2. 将文档中的占位域名替换为实际生产配置；实际域名不写入示例或测试夹具。
3. 指向新部署前先降低TTL，并保留上一部署作为回滚目标。
4. 使用托管平台重新签发TLS证书。
5. 验证HTTPS、证书链、主机名、重定向和站点地图。

回滚

优先回滚到最近一个已验证的Git提交或发布标签：

git checkout <last-known-good-tag-or-sha>
npm ci
npm run check

通过正常CI流程发布该版本。不要在生产服务器上直接修改生成文件。回滚完成后记录故障提交、恢复提交、影响范围和后续修复计划。

恢复演练记录

• 2026-07-20：在排除.git、node_modules、构建目录和缓存的隔离副本中执行npm ci与完整npm run check；20项自动化测试和VitePress生产构建全部通过。
• DNS切换、TLS重新签发和托管平台项目重建尚未进行破坏性演练，需要在不影响生产站点的临时域名上完成。