xinyouhe/cms-website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
107642c1b3ef38f9a55ab8163a88c658443ac081
cms-website/cms现状与SiteForge差距分析_V1.0.md
T
浅念 d60123ba41 docs: SiteForge 规划文档基线 + 纵向切片设计规格 V1 
- V3.0 总体方案、主题与板块设计、实施计划
- cms 现状差距分析 V2.0（V1.0 已标注作废）与复用评估 V1.0
- 纵向切片设计规格（路线 C：全新架构 + 白名单资产移植）
- .gitignore 先行（storage/artifacts/env 永不入库）

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-10-20 16:10:34 +08:00

12 KiB
Raw Blame History

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 复工的前置）

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

第三梯队 · 迁移质量增强（按站需要，穿插进行）

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

第四梯队 · 运营与规模（上线后迭代）

  1. 表单强化：垃圾防护、邮件通知（消灭 TODO）、CRM 转发（V3.0 #16）
  2. 监控告警 + 结构化日志 + 构建历史持久化（V3.0 #17）
  3. WP SQL 第三通道、ACF 字段发现（V3.0 #3 补全）
  4. 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 稿/参考站）排上日程——第二梯队一完成它就能复工。
Reference in New Issue View Git Blame Copy Permalink