42 lines
2.2 KiB
Markdown
42 lines
2.2 KiB
Markdown
# 迁移至 XControl CMS 的实施指南
|
||
|
||
本文梳理了从旧版静态页面体系迁移到全新 CMS 架构的步骤，并提供回滚方案以保障发布安全。
|
||
|
||
## 迁移准备
|
||
|
||
1. **梳理现有页面**：整理旧系统的路由、模板和数据源，并标注关键依赖（例如第三方 API、Webhook）。
|
||
2. **建立对照表**：在项目 wiki 中维护“旧页面 → 新模板”的映射，明确所需内容源与扩展。
|
||
3. **同步配置**：将上述映射写入 [`config/cms.json`](../../config/cms.json)，并针对每个模板准备默认内容样例。
|
||
|
||
## 实施步骤
|
||
|
||
1. **搭建预览环境**：
|
||
- 创建 `feature/cms-migration` 分支；
|
||
- 部署独立的 CMS 预览环境，指向 `cms.json` 中定义的内容源；
|
||
- 确保团队成员可登录并在预览中校对页面。
|
||
2. **内容迁移**：
|
||
- 使用 `scripts/content-migrator`（TODO）或手动脚本，将旧 Markdown/HTML 转换为 CMS 支持的内容块；
|
||
- 对照对照表验证每个页面的链接、组件与扩展生效情况；
|
||
- 在预览环境执行冒烟测试，覆盖核心业务流（注册、下单、反馈表单等）。
|
||
3. **灰度发布**：
|
||
- 在 CDN/网关上新增 `cms-beta` 域名，对应新的渲染服务；
|
||
- 内部用户和部分真实流量切换到新域，收集性能及错误日志；
|
||
- 若未出现阻塞问题，逐步放大流量并更新主域名解析。
|
||
|
||
## 回滚方案
|
||
|
||
1. **保留旧环境**：迁移期间保留旧渲染服务与静态资源，避免同名覆盖；
|
||
2. **可控切换**：所有流量切换通过网关开关或流量调度平台完成，开关命名为 `enable_new_cms`；
|
||
3. **回滚流程**：
|
||
- 若监控中断或错误率超出阈值，立即关闭 `enable_new_cms` 将流量打回旧系统；
|
||
- 执行 `make revert-cms-release`（脚本需在部署仓库中实现）撤销最新配置发布；
|
||
- 将问题归档在 incident 工单，收集 `cms.json` 与扩展日志，确认修复后重新灰度。
|
||
|
||
## 里程碑检查
|
||
|
||
- ✅ 完成 `cms.json` 配置与 Schema 校验；
|
||
- ✅ 预览环境可完整渲染所有页面；
|
||
- ✅ 灰度发布通过性能、监控、无障碍检查；
|
||
- ✅ 回滚演练至少一次，确保运维手册可执行。
|
||
|