cms-website/cms现状与SiteForge差距分析_V1.0.md

# cms 代码库现状 vs SiteForge V3.0 差距分析与改造清单

> ⚠️ **本文档已作废（2026-10-20）**：被 `cms现状与SiteForge差距分析_V2.0.md` 取代。V2.0 修正了本文多处评级（隔离残留、非原子发布、SVG/媒体安全、迁移自动发布等，均以代码证据为准）。本文仅作历史参考，请勿据此决策。

> 版本：V1.0｜日期：2026-10-20
> 方法：SiteForge V3.0 §2.1 的 17 项必须交付能力为标尺，逐条对照 `D:\project\cms` 的**实际代码**（非文档声称），证据来自代码探索 + 迁移台账 + 契约文档。
> 结论用途：走「C 路线」——以 cms 为基座继续演进，把 V3.0 当架构检查清单逐项吸收。

---

## 1. 总评

**17 项能力：已有 4 项、部分 9 项、缺失 4 项。**

cms 已经用真实数据（两站：hesupipe.com ✅ 完成、magicbridgeauto.com ⏸ 暂停）验证了最难的「迁移 → 静态构建 → 门禁 → 回滚」主干链路，这与 V3.0 的核心路径完全同构。缺口集中在：**部署上线（阻塞）、主题系统（平台化核心）、迁移质量增强（差量/冲突/URL 注册表）、账号与运维硬化**。

一句话：**V3.0 里"值钱的架构思想"cms 已吸收了一半（不可变修订、版本化产物、门禁、幂等），另一半（输入快照、URL 注册表、主题协议、部署器）就是改造清单的主线。**

---

## 2. 十七项能力逐条对照

图例：✅ 已有（实战验证）｜🟡 部分（能跑但有明显缺口）｜❌ 缺失

| # | V3.0 必须交付 | 评级 | cms 实际现状（代码证据） | 关键差距 |
|---|---|---|---|---|
| 1 | 多站点与环境管理 | 🟡 | sites/域名/设置齐全；站点隔离已修复并有 e2e（`isolation.e2e.test.ts`，文档里的"X-Site-Id 未生效"是过时信息） | 无 staging/production 环境抽象；构建历史存内存（重启即丢） |
| 2 | 单一超级管理员（MFA/恢复/会话撤销） | 🟡 | 登录 + bcrypt + 审计日志可用；单账号种子 | 自研 HMAC token **无过期、无撤销**；无 MFA/恢复码/登录限流；**登录页预填了默认账号密码** |
| 3 | WordPress REST/WXR/SQL/uploads 导入 | ✅ | REST + WXR 双通道 + zip 媒体 sourceUrl 预入库 + externalRef 幂等 + WAF 退避；两站实战（33MB WXR 也解析了） | 缺 SQL 直连通道（第三通道）；ACF 字段发现未做 |
| 4 | Sitemap/HTML/Playwright 扫描 | ❌ | 仅拉取老站 sitemap.xml（1 级 index 递归） | 无 HTML 链接发现爬虫、无 Playwright；V3.0 的十来源 URL 全集完全没有 |
| 5 | 原始快照与差量同步 | 🟡 | WXR 原件留档 storage/wxr；重跑幂等更新 | **无冲突队列、无人工编辑保护**（重跑无条件整条覆盖 data）、无新增/更新/删除/冲突的差量分类报告 |
| 6 | 统一内容与内容修订 | ✅ | content_revisions 不可变（插入式）、公开端点只读 published 修订、5 种内容类型带 Schema | 缺乐观锁（last-write-wins，多标签页会互相覆盖）；archived 状态无入口 |
| 7 | URL 注册表与路由编译 | 🟡 | 301 存 site_settings.redirects（JSONB）；三格式产物（_redirects/nginx conf/csv）；三色报告 🔴missing=0 实战达标 | 无独立路由注册表（normalized key/route_kind/indexable）；无 410/查询参数路由；无部署能力预检 |
| 8 | SEO 快照与差异报告 | 🟡 | 出站 SEO 全套（title/desc/canonical/hreflang/og/twitter/noindex）+ Yoast 随迁 + 门禁查 title/H1/canonical + sitemap 一致性 | 无"旧站真实 HTML vs 新站"三套数据对比；无 P0–P3 分级差异报告 |
| 9 | 媒体迁移与旧路径保持 | ✅ | 全量转存 + sourceUrl 幂等去重 + alt + 多尺寸；两站 5494 张实战、替换零残留 | 老站已被外链引用的媒体旧 URL 是否 301 未处理（对齐 V3.0"旧路径保持"） |
| 10 | 主题/模板/板块协议 | ❌ | templates 表存在但**空表无种子**；主题 Tab 能编辑 token 但**运行时没人消费（死线）**；后台表单全部硬编码；建站只有 1 个硬编码模板选项 | **最大缺口**（平台化文档自己标注）。ERD 里的 block_instances/template_slots/component_versions 设计未落地 |
| 11 | 组件化公共包 | 🟡 | astro runtime 内共享数据源 + base 组件 + 183 个设计 token（契约测试保护）；domain-contracts 类型包 | 无四层复用分层、无多主题目录结构（themes/）、无跨主题复用验证 |
| 12 | Astro 全量静态构建 | ✅ | 版本化产物（.artifacts/，KEEP=10）+ 4 阶段原子发布 + 门禁 + 回滚（可再滚回） | **缺构建输入快照**：构建时实时拉 API，失败时**静默回落 seed 演示数据**（高危！） |
| 13 | 预览、验收、发布、回滚 | 🟡 | 验收（gate.mjs）/发布/回滚完整且实战 | **草稿预览缺失**（只能发布后看）；无生产冒烟 |
| 14 | Nginx/SSH 发布 | ❌ | 产物只落本地目录；全库 grep 无 rsync/sftp/ssh/部署代码 | **两站上线都阻塞在这**（台账："部署阿里云（等凭据）"——凭据之外还缺整个部署器） |
| 15 | S3/OSS + CDN 发布（与 14 二选一） | ❌ | MinIO 容器起了但无任何代码使用 | 同上 |
| 16 | 表单基础服务 | 🟡 | leads 提交 + zod 校验 + 状态流转 + 审计 | 无垃圾防护/验证码/限流；**邮件通知是 TODO 注释**（设置里有"接收邮箱"字段但不发）；无 CRM 转发 |
| 17 | 备份、监控和操作日志 | 🟡 | audit_logs 覆盖全部变更端点（actor/before/after/requestId） | **无任何备份脚本**（94MB PG + 1.3GB 媒体全在开发机一块盘上）；无监控告警；Fastify logger 关闭；ClickHouse/Redis/MinIO 容器闲置 |

---

## 3. cms 超出 V3.0 预期的地方（不要在改造中丢掉）

1. **WXR 正则解析器**（universal-row.ts）：无 XML 库依赖，处理了 `_thumbnail_id`、`_product_image_gallery`、`wppop_sections` PHP 反序列化、Yoast 主分类——这些实战细节 V3.0 只写了方向。
2. **WAF/验证码对抗**：REST 通道 202 挑战页快速失败 + 指数退避（30/90/180s）+ 全局节流——SiteGround 拦截是真实踩坑沉淀。
3. **三色报告闭环**：externalRef ∪ sitemap 双源对照，🔴missing=0 作为发布关卡已在两站达标。
4. **契约测试纪律**：18 事件目录冻结、183 token 全量校验、组件零颜色字面量、WP 文本清洗规则——V3.0 §24 要求的契约测试已有雏形。
5. **多语言位**（entry_locales + hreflang 渲染）：V3.0 把多语言放到 V1.1，cms 已有编辑位和渲染。

---

## 4. 上线前必须处理的五个高危问题（按危险程度排序）

| # | 问题 | 危险场景 | 修法（对应 V3.0 条目） |
|---|---|---|---|
| 1 | **构建 seed 兜底**：API 拉取失败时静默用演示数据构建 | control-api 抖动 → 演示内容被构建、过门禁、发布上线 → 线上变成假站 | 构建改为**先冻结输入快照**（拉全量数据 → 落盘 → 校验 → 再构建）；失败即中止（V3.0 §13.1） |
| 2 | **零备份**：数据库、媒体、产物全在开发机 D 盘 | 磁盘坏 = 两站迁移成果 + 平台数据全灭 | pg_dump 定时 + storage/ 与 .artifacts/ 同步到第二存储；先手动后自动（V3.0 §20） |
| 3 | **认证弱**：token 无过期无撤销 + 登录页预填默认凭据 + 无限流 | 部署到公网后管理后台即刻成为攻击面 | token 加过期+撤销表；删除预填凭据并改密；登录限流；MFA 可后置（V3.0 §19.1） |
| 4 | **无部署器**：产物出不去本地 | 两站永远"差最后一步"上线 | 实现 rsync/SSH 部署器（先）+ OSS/CDN（后）；附带上线检查表（V3.0 附录 A） |
| 5 | **重跑覆盖人工编辑**：迁移重跑无条件覆盖 data | 旧站同步时把后台手工修好的内容冲掉 | override 标记 + 冲突队列（V3.0 §8.4） |

---

## 5. 改造路线图（C 路线：四梯队）

### 第一梯队 · 解锁上线与数据安全（立即，1–2 周）
1. **部署器 v1**：rsync/SSH 到阿里云 ECS + nginx conf 应用 + 部署记录 + 产物哈希校验 → 把 hesupipe 真正发上线（对齐 V3.0 #14）
2. **备份**：每日 pg_dump + storage 增量同步 + 恢复演练一次（对齐 V3.0 #17、§20）
3. **构建输入冻结**：移除 seed 兜底；构建前物化站点数据快照；快照哈希进产物元数据（对齐 V3.0 #12、§13.1）
4. **认证加固**：token 过期/撤销、清默认凭据、登录限流（对齐 V3.0 #2）

### 第二梯队 · 平台化核心（3–6 周，magicbridge 复工的前置）
5. **主题系统落地**（V3.0 #10/#11，对应 cms 平台化 P2–P4）：
   - templates 表种子 + corporate-pro 主题物化（把现在写死的布局抽成第一套主题）
   - **打通 token 死线**：让主题 Tab 的编辑真正影响构建产物
   - Schema 驱动表单（字段类型注册表 → 动态渲染），下线硬编码表单
   - themes/ 多主题目录 + 按 templateKey 构建（为 magicbridge 汽车站主题做准备）
6. **草稿预览**：预览构建目录 + 访问控制 + noindex（V3.0 #13）

### 第三梯队 · 迁移质量增强（按站需要，穿插进行）
7. **差量同步 + 冲突保护**：override 标记、差量分类报告（新增/更新/删除/冲突）、人工修改不被静默覆盖（V3.0 #5）——旧站仍在更新时必需
8. **URL 注册表**：redirects 从 settings JSONB 升级为独立表（ERD 本来就这么设计的），补 route_kind/410/查询参数（V3.0 #7）
9. **SEO 差异报告**：老站 HTML Head 抓取 vs 新站预览对比，P0–P3 分级接入门禁（V3.0 #8）
10. **HTML 爬虫**：链接发现补全 URL 全集（sitemap+WXR+爬虫三源）；Playwright 仅按需（V3.0 #4）

### 第四梯队 · 运营与规模（上线后迭代）
11. 表单强化：垃圾防护、邮件通知（消灭 TODO）、CRM 转发（V3.0 #16）
12. 监控告警 + 结构化日志 + 构建历史持久化（V3.0 #17）
13. WP SQL 第三通道、ACF 字段发现（V3.0 #3 补全）
14. event-gateway/ClickHouse 分析栈：**单独决策**——它与建站平台正交，要么砍掉容器要么立项，别挂着

---

## 6. 明确不照搬 V3.0 的部分（单人 + AI 模式的取舍）

| V3.0 设计 | 取舍 | 理由 |
|---|---|---|
| MFA + 恢复码完整体系 | 后置 | 单运营者；先用强密码 + token 过期 + 限流 + IP 白名单顶住，公网暴露后再上 |
| 构建沙箱容器化（断网/限额/无密钥） | 暂缓 | 单人开发无第三方适配器代码风险；**先移除 seed 兜底**（真实风险排序相反） |
| CAS 发布锁 / 环境锁 / 租约心跳 | 暂缓 | 单运营者无并发发布冲突；构建单站串行已足够 |
| 十来源 URL 全集 | 渐进 | sitemap + WXR + 日志三源已覆盖大半；GSC/GA4 等按站补 |
| NestJS + BullMQ 任务队列全家桶 | 观察 | 现状"control-api spawn pnpm"土但能跑；队列在任务变多（定时备份/批量迁移）后再上 |
| 5 人团队 20 周排期 | 不适用 | 1 人 + AI 串行；按梯队推进，每梯队以"真实站点闭环"为验收 |

---

## 7. 文档与现实偏差清单（建议顺手修正）

1. `平台化总体设计与实施计划.md` §3："X-Site-Id 未生效（已知缺陷）"——**已过时**，代码已修复且有 e2e 测试。
2. ERD-V1（45 张表、ClickHouse 4 表）是**设计蓝图不是实现**：实际 ORM 是 Drizzle（非 Prisma），redirects 是 settings JSONB（非独立表），site_snapshots/publish_manifests/artifacts/releases 等 ERD 表均未建。
3. `services/build-worker`、`services/event-gateway` 是 README 空壳；真实构建在 control-api + astro runtime 脚本里。
4. 登录页（admin-web）预填了 `admin@hesupipe.com / hesu-admin-2026`——上线前必须清除。
5. docker-compose 的 ClickHouse/Redis/MinIO 无代码消费——要么用起来要么先摘掉，避免"看起来有"的假象。

---

## 8. 下一步建议（本周可做）

1. 部署器 v1 动工前，先向用户/托管方确认：目标形态是阿里云 ECS（nginx）还是 OSS+CDN——决定先写 rsync 还是 OSS 上传。
2. 手动做一次全量备份（pg_dump + storage 拷贝到第二块盘/网盘），不等脚本。
3. 删除构建 seed 兜底（一行开关级改动，风险最高、成本最低）。
4. 把 magicbridge 的主题设计输入（HTML 稿/参考站）排上日程——第二梯队一完成它就能复工。