# SiteForge 多站点静态迁移与内容发布平台 > 完整项目计划方案 V3.0 > 编制日期：2026-10-20 > 文档状态：立项、研发与试点执行基线 > 适用范围：WordPress 为主，兼容 HTML、PHP/MySQL、自研 CMS、API 与标准数据文件 > 设计原则：单一超级管理员、组件化复用、每站独立设计、纯静态生产、URL/SEO 优先、可审计发布与回滚 --- ## 0. 执行摘要 SiteForge 是一套面向多网站运营的迁移与发布控制平台。它负责扫描旧站、导入内容、保留 URL 和 SEO、重新设计主题、生成静态网站，并在后续持续管理产品、新闻、页面和媒体。 平台不是另一个 WordPress，也不是通用拖拽建站器。它的核心价值是把多次网站迁移中重复发生的工作标准化： ```text 旧站盘点 → 全量导入 → 数据标准化 → URL/SEO 冻结 → 独立主题实现 → 差量同步 → 静态构建 → 自动验收 → 发布确认 → 原子切换 → 监测与回滚 ``` 生产网站输出独立的 HTML、CSS、JavaScript 和媒体文件，不实时依赖 SiteForge 数据库。表单、搜索等必须动态运行的能力通过独立 API 或服务提供。 V1 采用以下核心技术方向： - Art Design Pro 管理后台底座（Vue 3 + TypeScript + Element Plus）。 - NestJS 模块化单体 API。 - PostgreSQL 数据库。 - Redis + BullMQ 任务队列。 - TypeScript 抓取与 Playwright 渲染兜底。 - Astro 静态构建。 - S3 兼容对象存储。 - Docker Compose 部署控制面。 - Nginx/SSH 和对象存储/CDN 两类发布适配器。 V1 只设置一种系统角色 `super_admin`，默认由一个超级管理员账号管理全部功能，不建设 RBAC、成员和复杂审批系统。高风险操作通过二次确认、MFA、不可变日志和可回滚发布降低风险。 --- ## 1. 建设背景与目标 ### 1.1 当前问题 - 多个网站主要使用 WordPress，也存在其他 CMS、PHP、自研系统或纯 HTML 网站。 - 每次迁移都需要重新处理内容、URL、SEO、图片、服务器规则和发布流程。 - 网站之间设计差异大，无法直接使用同一套页面模板。 - 旧站积累了历史路径、外链和搜索流量，不能随意改变 URL。 - 新站希望保持纯静态，同时仍需要持续新增产品、新闻和页面。 - 现有迁移通常依赖人工脚本，缺少可重复、可审计和可回滚的标准流程。 ### 1.2 建设目标 1. 一个后台集中管理多个网站。 2. 优先深度支持 WordPress，通过适配器兼容其他来源。 3. 精确保留旧 URL、状态码、跳转和 SEO 行为。 4. 每个站点可使用完全独立的主题和页面设计。 5. 使用组件化、板块化机制提高开发复用率。 6. 后台可以长期维护产品、新闻、页面、菜单和媒体。 7. 生产站以纯静态方式部署，控制面故障不影响线上访问。 8. 每次构建、验收、发布和回滚都有完整记录。 9. 完成两个差异化试点后，新站主要投入集中在来源映射、异常处理和主题设计。 ### 1.3 成功标准 | 维度 | V1 成功标准 | |---|---| | URL | 基线 URL 100% 有明确处置结果或批准例外 | | SEO | 关键 SEO 属性有来源快照、目标值和差异报告 | | 内容 | 核心页面、产品、文章、分类、媒体通过业务抽检 | | 设计 | 至少两套视觉差异明显的独立主题运行在同一平台 | | 发布 | 构建可追溯、发布原子化、回滚经过实际演练 | | 稳定性 | SiteForge 短时离线不影响已经发布的生产站点 | | 运营 | 超级管理员可无代码新增产品、新闻和普通页面 | | 复用 | 第二个站点复用迁移、URL、SEO、构建和发布链路 | ### 1.4 不做承诺 - 仅凭公开 URL 自动发现后台未公开内容和私有字段。 - 任意复杂页面构建器内容零人工转换成理想的新设计。 - 电商交易、支付、订单和会员系统完全静态化。 - 网站迁移后搜索排名绝对不波动。 - V1 支持所有 CMS、任意主题切换和通用低代码设计。 --- ## 2. 产品范围与版本边界 ### 2.1 V1 必须交付 | 能力 | 是否阻塞试点 | 验收方式 | |---|---:|---| | 多站点与环境管理 | 是 | 至少两个站点隔离运行 | | 单一超级管理员 | 是 | 登录、MFA、恢复、会话撤销可用 | | WordPress REST/WXR/SQL/uploads 导入 | 是 | 真实试点数据导入通过 | | Sitemap/HTML/Playwright 扫描 | 是 | 输出可审计 URL 与页面清单 | | 原始快照与差量同步 | 是 | 重跑不重复，切站前完成最终增量 | | 统一内容与内容修订 | 是 | 产品、新闻、页面可编辑和回滚 | | URL 注册表与路由编译 | 是 | 目标部署环境真实 HTTP 验证 | | SEO 快照与差异报告 | 是 | P0/P1 门禁有效 | | 媒体迁移与旧路径保持 | 是 | 关键媒体无未处理 404 | | 主题/模板/板块协议 | 是 | 两个差异化主题使用同一协议 | | 组件化公共包 | 是 | 两个主题复用数据、SEO、媒体和交互逻辑 | | Astro 全量静态构建 | 是 | 产物可独立部署 | | 预览、验收、发布、回滚 | 是 | 完成一次上线及回滚演练 | | Nginx/SSH 发布 | 是 | 试点目标发布通过 | | S3/OSS + CDN 发布 | 二选一 | 如作为试点目标则验收 | | 表单基础服务 | 按站点 | 提交、重试、隐私和反垃圾通过 | | 备份、监控和操作日志 | 是 | 完成恢复演练与告警测试 | ### 2.2 V1.1 建议能力 - 多语言内容和 hreflang 完整工作流。 - 定时发布和批量发布。 - 简单站内搜索或独立搜索服务接入。 - 图片 WebP/AVIF 衍生和更精细的媒体优化。 - PHP/MySQL、Drupal、Joomla 等第二批深度适配器。 - 页面依赖图驱动的选择性重建。 - WebHook 和外部业务系统联动。 ### 2.3 暂不建设 - 自由画布式低代码编辑器。 - 无限层级嵌套板块。 - 复杂商城、订单、支付和会员中心。 - 多角色、成员、细粒度 RBAC 和站内审批流。 - 跨组织 SaaS 计费和主题市场。 - 自动发布未经人工确认的 AI 生成或迁移结果。 - Kubernetes、多区域主动容灾和复杂微服务拆分。 --- ## 3. 总体架构 ```mermaid flowchart TB subgraph Sources[旧站与数据来源] WP[WordPress] WEB[HTML / JS 网站] DB[PHP / MySQL / 自研 CMS] FILE[WXR / CSV / JSON / XML / ZIP] LOG[访问日志 / GSC / GA4] end subgraph Control[SiteForge 控制面] ADMIN[超级管理员后台] API[模块化 API] JOB[任务调度与 Worker] RAW[原始快照] CDM[统一内容库] ROUTE[URL / SEO 引擎] THEME[主题 / 板块 / 组件] BUILD[隔离静态构建] QA[自动验收门禁] RELEASE[Release 与部署] end subgraph Production[独立生产面] NGINX[Nginx 静态站] CDN[对象存储 / CDN] DYNAMIC[表单 / 搜索等独立 API] end Sources --> JOB ADMIN --> API API --> JOB JOB --> RAW RAW --> CDM CDM --> ROUTE ROUTE --> THEME THEME --> BUILD BUILD --> QA QA --> RELEASE RELEASE --> NGINX RELEASE --> CDN NGINX -.按需调用.-> DYNAMIC CDN -.按需调用.-> DYNAMIC ``` ### 3.1 控制面与生产面 控制面包含后台、API、数据库、队列、采集、内容、构建和发布。生产面只包含不可变静态文件、部署规则和明确的动态服务。 生产网页不得在请求时读取 SiteForge 数据库，也不得依赖 WordPress/PHP 运行时。 ### 3.2 模块化单体 V1 使用模块化单体 API 与独立 Worker，不拆分大量微服务： ```text API：认证、站点、内容、URL、SEO、主题、任务、发布 Worker：扫描、导入、媒体、构建、验证、部署 共享契约：Schema、DTO、事件、状态机 ``` ### 3.3 四个发布输入 ```text Release = ContentSnapshot + RouteSeoSnapshot + ThemeBuildSnapshot + SiteEnvironmentSnapshot ``` 发布后的 release 必须能准确回答：用了哪些内容、路由、SEO、媒体、主题代码、依赖、环境配置和构建镜像。 --- ## 4. 超级管理员与操作流程 ### 4.1 唯一系统角色 V1 只定义 `super_admin` 一种角色，管理： - 全部网站和环境。 - 数据源、扫描、导入和字段映射。 - 产品、新闻、页面、分类、菜单和媒体。 - URL、SEO、Sitemap 和跳转。 - 主题、模板、板块和组件版本。 - 预览、构建、发布、回滚和备份。 - 系统配置、密钥引用和操作日志。 默认只启用一个日常超级管理员账号，不建设团队成员和权限分配。系统需提供： - 强密码策略。 - MFA。 - 一次性恢复码。 - 登录失败限流。 - 会话列表和远程撤销。 - 登录异常提醒。 - 高风险操作重新输入密码/MFA。 - 操作日志记录账号、会话、IP、时间、对象和结果。 ### 4.2 简化内容状态 不建设复杂审批流： ```text draft → ready_to_publish → publishing → published → archived ``` 外部内容、SEO或设计人员的确认结果可以作为备注和附件保存，由超级管理员执行最终发布确认。 ### 4.3 高风险操作 以下操作必须二次确认： - 生产发布。 - 生产回滚。 - 删除发布中的内容或 URL。 - 清空导入批次。 - 删除媒体原件。 - 更换生产域名或部署目标。 - 修改密钥、备份和安全配置。 --- ## 5. 端到端迁移与切站流程 ### 5.1 完整流程 ```mermaid flowchart TD A[创建站点与授权确认] --> B[连接数据源] B --> C[URL/SEO/功能全量盘点] C --> D[第一次全量导入] D --> E[标准化与字段映射] E --> F[主题和板块实现] F --> G[预览与多轮修复] G --> H[迁移期间差量同步] H --> I[上线前内容冻结] I --> J[最终差量导入与全站重扫] J --> K[锁定发布快照] K --> L[静态构建与自动验收] L -->|失败| E L -->|通过| M[超级管理员发布确认] M --> N[原子发布与缓存刷新] N --> O[上线监测与保护期] O -->|严重异常| P[回滚] O -->|稳定| Q[关闭旧站写入并归档] ``` ### 5.2 差量同步 差量判断综合使用： - 来源稳定 ID。 - WordPress `modified_gmt` 等更新时间。 - 内容和元数据 checksum。 - 媒体哈希。 - 页面最终 HTML/SEO checksum。 - 删除、隐藏和状态变化标记。 每次同步输出：新增、更新、删除、无变化、冲突和失败。人工修改过的目标内容不得被来源更新静默覆盖，必须进入冲突队列。 ### 5.3 切站时间线建议 ```text T-7天：完整彩排，验证发布和回滚 T-3天：缩短 DNS TTL，确认旧站备份 T-1天：执行倒数第二次差量同步 T-2小时：冻结旧站内容写入 T-90分钟：最终差量导入和 URL/SEO 重扫 T-45分钟：锁定快照、构建、门禁检查 T-15分钟：发布确认和临时入口冒烟 T时刻：切换生产并刷新缓存 T+2小时：高频关键 URL、表单和日志监测 T+7天/约定期：确认稳定后归档旧环境 ``` 实际时间按网站规模调整。 ### 5.4 回滚触发条件 - 关键 URL 大量 404/500。 - Canonical/Robots 全站错误。 - 核心页面内容或媒体系统性缺失。 - 表单等关键业务无法使用。 - 发布规则与静态文件版本不一致。 - 性能或可用性达到站点约定的严重阈值。 --- ## 6. URL 全集与扫描系统 ### 6.1 URL 发现来源 不能只依赖 Sitemap 和站内爬虫。基线合并以下来源： 1. Sitemap 和 Sitemap Index。 2. 首页、导航、分类、分页和全部站内链接。 3. WordPress数据库中的公开内容、附件和历史 permalink。 4. REST API/WXR/其他结构化导出。 5. Nginx/Apache/CDN访问日志中的落地 URL。 6. Search Console 页面数据。 7. GA4/其他分析工具的历史着陆页。 8. 现有 Nginx、Apache、CDN 重定向规则。 9. 业务提供的广告、邮件、二维码和重要外链。 10. 已知媒体、PDF和站点验证文件。 ### 6.2 URL 基线状态 每条 URL 标记： ```text discovered verified_active verified_redirect verified_not_found requires_auth unknown excluded_with_reason ``` 报告必须区分“确认遗漏”和“无法证明是否存在”。所谓 100% URL 处置率，是指已确认的 URL 基线全部有明确处理，而不是声称发现了互联网上所有历史地址。 ### 6.3 扫描策略 - 明确允许的域名、子域名、协议和端口。 - HTTP 抓取优先，JS 页面进入 Playwright 队列。 - 每站设置并发、速率、深度、最大页面数和文件大小。 - 保留原始 URL，同时生成规范化辅助键。 - 不粗暴合并大小写、尾斜杠、查询参数和编码形式。 - 任务支持断点续跑、重试、取消和恢复。 - 保存响应头、状态码、跳转链、原始 HTML、渲染 DOM 和 checksum。 ### 6.4 URL 注册表 ```text host original_path normalized_lookup_key query_policy source_status target_status route_kind target_content_id target_file redirect_location indexable priority source_snapshot_id verification_status ``` `route_kind`：`html`、`redirect`、`asset`、`gone`、`dynamic`。 ### 6.5 路径兼容 必须区分： - `/about`、`/about/`、`/about.html` - `/Article/`、`/article/` - Unicode 原文与不同百分号编码 - `/news/page/2/`、标签和归档页 - `?p=123`、`?page_id=123` - `.php` 历史入口 - 媒体、PDF、字体和验证文件 系统内部路径采用 UTF-8，并定义唯一的编码/解码规则。发布前检查 Windows 与 Linux 文件系统的大小写、保留名称和 Unicode 规范化冲突。 --- ## 7. 部署能力矩阵与路由编译 ### 7.1 部署适配器契约 每种部署目标声明能力： ```ts interface DeploymentCapabilities { exactStatusCodes: boolean; redirects: boolean; queryRouting: boolean; caseSensitivePaths: boolean; customHeaders: boolean; custom404: boolean; gone410: boolean; atomicSwitch: boolean; rollback: boolean; cachePurge: boolean; edgeLogic: boolean; } ``` ### 7.2 路由编译 统一 `route-manifest` 根据目标平台编译成： - Nginx location/rewrite/map 规则。 - Apache规则（后续按需）。 - 对象存储静态文件结构。 - CDN Redirect/Rewrite/Edge 规则。 - 自定义错误页和响应头配置。 若部署目标无法实现某个关键 URL 的状态码或查询路由，预检必须阻止发布，并给出替代建议。 ### 7.3 基础输出方式 - `/about-us/` → `about-us/index.html` - `/news/a.html` → `news/a.html` - `.php` 页面 → 服务器规则映射到静态文件 - 查询参数语义路由 → Edge规则或独立服务 - 历史媒体路径 → 原样文件或精确映射 ### 7.4 部署能力验收 不能只检查文件是否存在，必须在与生产一致的 Web Server/CDN 预览环境中逐 URL 发起 HTTP 请求，验证状态码、Location、Content-Type、缓存头和页面内容。 --- ## 8. 来源适配器与数据导入 ### 8.1 可信度顺序 ```text 数据库/平台 API > 标准导出文件 > 页面 HTML/渲染 DOM ``` HTML 同时用于验证最终对外页面，因此即使拥有数据库也应抓取旧站 HTML Head 和正文摘要进行交叉核对。 ### 8.2 适配器接口 ```ts export interface SourceAdapter { readonly id: string; detect(ctx: ScanContext): Promise; probe(ctx: ImportContext): Promise; discover(ctx: ImportContext): AsyncIterable; extract(ref: SourceResourceRef, ctx: ImportContext): Promise; normalize(record: SourceRecord, ctx: MappingContext): Promise; collectAssets?(ctx: ImportContext): AsyncIterable; extractSiteSettings?(ctx: ImportContext): Promise; diff?(from: SnapshotRef, to: SnapshotRef): Promise; verify?(ctx: ImportContext): Promise; } ``` 统一错误码： ```text AUTH_REQUIRED RATE_LIMITED PRIVATE_CONTENT UNSUPPORTED_FIELD UNSUPPORTED_DYNAMIC_FEATURE MISSING_ASSET PARSE_FAILURE SOURCE_CHANGED SECURITY_REJECTED ``` ### 8.3 WordPress 首版范围 - `wp_posts`、`wp_postmeta`。 - 分类、标签及关联。 - 页面、文章、公开 CPT。 - 菜单、附件、特色图片。 - WXR 内容和 postmeta。 - REST API 公开内容。 - `wp-content/uploads`。 - Yoast SEO、Rank Math 常见字段，并与最终 HTML Head 比对。 - Gutenberg 基础块。 - ACF 原始字段保留和人工映射。 - WooCommerce 商品基础信息、属性、变体和图库按试点评估。 专项适配：Elementor、WPBakery、多语言插件、自定义表、复杂短代码、主题私有字段。 ### 8.4 导入幂等与冲突 源记录唯一键： ```text site_id + source_connection_id + source_type + source_id + locale ``` 使用 checksum 区分新增、变化和未变化。人工编辑过的字段保存 `override` 标记；再次导入时保留来源新值和人工值，产生冲突，不自动覆盖。 ### 8.5 原始快照 保存： - 原始文件或响应位置。 - 来源连接与适配器版本。 - 提取时间和时区。 - 源 ID、URL 和状态。 - checksum。 - 导入批次。 - 清洗、映射和异常日志。 --- ## 9. 统一数据模型 ### 9.1 模型原则 - PostgreSQL 保存关系和业务状态。 - JSONB 保存扩展字段，但核心关系使用独立表。 - 对象存储保存原始快照、媒体、报告和 release。 - 所有业务实体包含 `site_id`。 - 发布内容采用不可变 revision。 - 跨实体引用可追踪，删除有影响分析。 ### 9.2 核心实体 | 领域 | 实体 | |---|---| | 管理员 | admin_user、admin_session、recovery_code | | 站点 | site、domain、environment、site_setting | | 来源 | source_connection、import_job、source_snapshot、source_record | | 内容 | content_entry、content_revision、page_block | | 引用 | content_reference、global_fragment_usage | | 分类 | taxonomy、term、content_term | | 媒体 | media_asset、media_variant、media_usage | | 导航 | menu、menu_item | | 路由 | route_registry、redirect_rule、route_snapshot | | SEO | seo_record、seo_snapshot、seo_change_note | | 主题 | theme、theme_version、template_binding、block_schema | | 构建 | build_job、build_input_snapshot、build_artifact | | 验收 | validation_run、validation_issue、exception_note | | 发布 | release、deployment_target、deployment、rollback_event | | 运维 | job_lease、dead_letter_job、audit_log、credential_reference | ### 9.3 核心内容类型 - `page` - `post` - `product` - `product_category` - `brand` - `taxonomy_term` - `menu` - `global_fragment` - `media_asset` ### 9.4 内容引用关系 板块引用的产品、文章、媒体和路由写入 `content_reference`： ```text site_id source_revision_id source_block_id reference_type target_content_id target_media_id target_route_id ``` 用途： - 删除前影响分析。 - 防止悬空引用。 - 计算需要重建的页面。 - 媒体垃圾回收。 - 生成相关推荐和反向引用报告。 ### 9.5 删除与下线 已发布内容不能直接物理删除。操作步骤： 1. 显示引用页面和媒体影响。 2. 选择保留页面、301/308、410或取消发布。 3. 验证站内链接和 Sitemap。 4. 创建新的内容和路由快照。 5. 构建并发布。 6. 达到保留期限后再清理无引用媒体。 ### 9.6 并发编辑 所有草稿更新包含 revision/version。后台使用 ETag 或版本号进行乐观锁；即使只有一个账号，也要防止多标签页或重复请求覆盖较新的修改。 --- ## 10. 内容、主题、板块与组件化 ### 10.1 基本关系 ```text 内容数据 → 板块实例 → 页面模板 → 主题渲染 → 静态页面 ``` - 内容保存业务数据。 - 板块保存结构化展示数据。 - 模板约束页面区域和允许的板块。 - 主题决定最终 HTML、CSS、动画和响应式效果。 ### 10.2 板块类型 全局板块：Header、Footer、顶部通知、全局 CTA、联系方式。 页面板块：Hero、富文本、图文、图库、Feature、数据指标、产品列表、文章列表、参数表、下载、FAQ、CTA。 模板系统板块：面包屑、产品主信息、产品参数、文章正文、列表分页、SEO Head。 站点专属板块：360 展示、工厂流程、经销商地图等。 Legacy HTML：只用于未完成结构化的历史页面，必须清洗、隔离并标记。 ### 10.3 板块实例 ```ts interface BlockInstance> { id: string; type: string; schemaVersion: number; slotKey: string; position: number; variant?: string; data: T; settings?: { anchorId?: string; themeMode?: 'default' | 'light' | 'dark'; spacing?: 'none' | 'small' | 'medium' | 'large'; }; visibility: { enabled: boolean; locales?: string[] }; } ``` `slotKey` 支持 `main`、`sidebar`、`before_content`、`after_content` 等有限区域，不提供自由坐标布局。 ### 10.4 Schema 驱动后台 每个板块提供： - JSON Schema：字段、类型、长度、必填和枚举。 - UI Schema：后台控件、标签、媒体选择和内部链接选择。 - Schema Version：板块升级和数据迁移。 前端表单和后端保存均执行校验。生产构建遇到未知或不兼容板块时必须失败。 ### 10.5 四层组件复用 ```text 第一层：数据契约与工具 第二层：无样式基础组件 第三层：Headless 业务逻辑 第四层：主题展示组件 ``` 前三层公共复用，第四层由主题独立实现。 公共包： ```text content-contracts block-contracts theme-runtime ui-primitives headless-components content-resolvers media-components seo-components form-runtime design-tokens ``` 复用边界： | 能力 | 公共复用 | 主题独立 | |---|---:|---:| | 数据类型、Schema、迁移 | 是 | 否 | | URL、SEO和媒体解析 | 是 | 可配置 | | 菜单树、分页、表单状态 | 是 | 展示独立 | | 产品和文章查询 | 是 | 卡片独立 | | Hero内容协议 | 是 | 渲染独立 | | Header/Footer | 逻辑可复用 | 结构与视觉独立 | | 页面模板、动画、品牌样式 | 否 | 是 | 主题之间禁止直接引用对方内部组件。两个主题重复出现的非视觉逻辑提取到公共包，纯视觉实现留在主题。 ### 10.6 主题清单 主题 manifest 声明： - 主题 ID、版本和构建引擎。 - 兼容的 runtime 和公共包版本。 - 模板及入口文件。 - 每个模板允许、必需和最大数量的板块。 - 板块 renderer、schema 和 variant。 - 站点配置 schema。 - 可编辑区域。 ### 10.7 主题版本 - 公共包遵循语义化版本。 - 破坏性变更提供迁移函数或兼容层。 - Release 锁定主题、公共包和构建镜像版本。 - 两套示范主题自动执行契约和截图回归。 - 主题切换前生成兼容报告，缺少 renderer 时禁止生产构建。 详细实现可参考 `SiteForge_主题与板块设计方案_V1.0.md`，V3 中与该文档冲突时以本方案为准。 --- ## 11. SEO 迁移 ### 11.1 三套数据 ```text source_raw → source_rendered → target_build ``` - `source_raw`：数据库、插件、API中的数据。 - `source_rendered`：旧站最终 HTML 和响应头。 - `target_build`：新站预览环境真实 HTTP 结果。 最终对外行为以 `source_rendered` 作为重要基线，插件字段用于补充来源和解释差异。 ### 11.2 对比字段 - Title、Description。 - Canonical。 - Robots Meta与响应头。 - H1/H2和正文摘要。 - Hreflang。 - Open Graph和Twitter Card。 - JSON-LD。 - Sitemap收录。 - 图片alt。 - 内部链接。 - 发布和更新时间。 - 面包屑。 ### 11.3 严重级别 | 级别 | 示例 | 处理 | |---|---|---| | P0 | 关键 URL 缺失、全站 noindex、Canonical 错域、重定向循环 | 阻止发布 | | P1 | 核心正文缺失、关键 Title 未批准改变、大量资源 404 | 修复或记录例外后确认 | | P2 | 次要 OG、ALT、非核心结构化数据差异 | 可带记录发布 | | P3 | 性能、语义和图片优化建议 | 进入优化清单 | 原站存在 SEO 错误时，迁移和优化分开记录；只有超级管理员明确确认后才在迁移中修复。 --- ## 12. 媒体与静态资源 ### 12.1 媒体数据 - 来源 URL和旧路径。 - MIME、扩展名、尺寸和大小。 - SHA-256。 - 原件位置和衍生资源。 - alt、caption和语言。 - 引用内容和板块。 - 迁移、验证和安全状态。 ### 12.2 处理策略 - 保存原始二进制，不只保存远程地址。 - 已索引或被外链引用的旧路径优先保持。 - WebP/AVIF和缩略图作为衍生资源。 - 处理 `src`、`srcset`、懒加载、CSS URL、PDF、SVG、字体和视频封面。 - 不通过全局字符串替换修改 HTML 引用。 - 清理无引用媒体前执行引用和 URL 影响分析。 ### 12.3 安全 - 限制类型、大小、文件数量和解压总量。 - 防 ZIP/TAR目录穿越和压缩炸弹。 - SVG/HTML净化。 - 禁止可执行文件进入公开产物。 - 对上传附件执行恶意文件和敏感信息扫描。 --- ## 13. 构建系统 ### 13.1 构建输入快照 构建开始时创建不可变 `build_input_snapshot`： ```text site_id environment_id content_snapshot_id route_snapshot_id seo_snapshot_id asset_manifest_id theme_version_id site_config_version dependency_lock_hash source_commit runtime_version container_image_digest locale timezone build_timestamp ``` 构建过程中发生的新编辑不进入本次 build。 ### 13.2 可复现构建 - 使用锁定依赖和固定运行时。 - 构建镜像按 digest 固定。 - 外部资源必须下载并固定哈希，或明确列入允许的远程依赖。 - 时间、时区、随机数和排序规则固定。 - 输出 manifest 和 checksums。 - 历史 release 回滚直接恢复产物，不重新构建。 ### 13.3 隔离执行 构建和第三方适配器运行在隔离容器/沙箱中： - 只读代码和输入快照。 - 独立可写临时目录。 - CPU、内存、磁盘和执行时长限制。 - 默认禁止任意网络访问，按任务白名单开放。 - 不挂载控制面密钥和主数据库凭据。 - 构建完成后销毁临时环境。 ### 13.4 构建并发 - 同站点同环境只允许一个发布构建持有租约。 - 普通预览构建可以排队或按限额并行。 - 每个 Job 有唯一幂等键。 - 旧构建完成时如果输入版本已经落后，不得自动发布。 - 取消只在定义好的安全点生效。 - Worker 通过心跳续租，失联后任务可安全恢复。 ### 13.5 构建产物 ```text releases// dist/ build-input.json build-manifest.json route-manifest.json asset-manifest.json validation-summary.json migration-report.html checksums.txt ``` ### 13.6 全量与增量 V1 使用按站全量构建。全局板块、主题或路由变化均全量构建。V1.1 根据 `content_reference` 建立依赖图，再实现选择性重建。 --- ## 14. 发布、原子切换与回滚 ### 14.1 发布状态机 ```text created → snapshot_locked → building → validating → ready_to_publish → publishing → verifying → published ``` 异常状态：`failed`、`cancelled`、`rolled_back`、`partially_deployed`。 ### 14.2 发布锁 生产发布获取 `environment_publish_lock`。切换时使用当前 `active_release_id` 做比较并交换：只有当前线上版本与启动发布时一致，才能切换到新 release，避免旧任务覆盖新版本。 ### 14.3 发布步骤 1. 锁定构建输入。 2. 在隔离环境生成 release。 3. 执行本地校验。 4. 上传不可变版本目录。 5. 校验文件数量、大小和哈希。 6. 使用临时入口执行真实 HTTP 验收。 7. 获取发布锁并再次检查当前版本。 8. 原子切换静态目录和路由规则。 9. 刷新必要 CDN 缓存。 10. 立即执行生产冒烟。 11. 标记 `published` 或执行补偿/回滚。 ### 14.4 对象存储注意事项 对象存储根目录直接同步不一定原子。优先使用版本前缀加入口指针/部署版本切换；HTML和路由规则作为同一部署事务处理。静态指纹资源长期缓存，HTML、Sitemap和非指纹文件按变更策略刷新。 ### 14.5 回滚 回滚切换到上一个已验证 release，包括： - 静态文件。 - 路由规则。 - 响应头配置。 - 必要的动态服务配置版本。 - CDN缓存策略。 首个试点正式上线前必须完成一次生产等价环境回滚演练。 --- ## 15. 动态能力 ### 15.1 处置原则 每个旧站动态功能必须选择： ```text 保留原服务 / 新 API 承接 / 第三方替换 / 静态降级 / 正式下线 ``` 没有结论的动态功能不能视为迁移完成。 ### 15.2 功能方案 | 功能 | 推荐实现 | |---|---| | 联系/询价 | 独立 Form API + 邮件/CRM | | 小站搜索 | 构建时生成客户端索引 | | 大站搜索 | 独立搜索服务 | | 分析统计 | 站点配置化接入 | | 下载统计 | CDN/边缘日志或下载 API | | 多语言 | V1.1 locale内容 + hreflang + 路由规则 | | 定时发布 | V1.1调度构建与部署 | | 会员/订单/支付 | 独立业务系统 | | 复杂筛选 | 客户端索引或搜索 API | ### 15.3 Form API 要求 - 站点和来源域名白名单。 - CSRF/Origin检查。 - 验证码、IP/指纹限流和反垃圾。 - 请求幂等键，防止重复询盘。 - 字段 schema 和长度限制。 - 隐私同意及政策版本记录。 - 敏感字段加密和日志脱敏。 - 数据保留、导出和删除策略。 - 邮件/CRM WebHook重试与死信队列。 - 附件类型、大小和恶意文件检查。 - 提交已接收、转发成功和转发失败分开记录。 --- ## 16. 管理后台 ### 16.1 前端技术选型 管理后台确定采用 **Art Design Pro** 作为工程底座，其底层技术为 **Vue 3 + TypeScript + Element Plus**。三者不是二选一关系： - Art Design Pro：后台布局、菜单、标签页、登录页面、基础工程规范和通用页面框架。 - Vue 3 + TypeScript：业务页面、状态管理、组合式逻辑和类型约束。 - Element Plus：表单、表格、弹窗、分页、上传、树形控件等基础 UI。 V1 只有超级管理员，不启用 Art Design Pro 中复杂的角色、按钮和动态权限配置。路由和菜单由系统模块固定声明，登录后拥有全部功能。 后台建议沿用底座已有的 Vue Router、Pinia、请求封装、国际化和构建工具；具体依赖版本在项目初始化时锁定。业务 API 类型由共享契约或 OpenAPI 生成，避免前后端各自维护重复接口类型。 管理后台主题只影响 SiteForge 控制台，不得与生产网站的 Astro 主题系统混用。 ### 16.2 信息架构 | 菜单 | 主要能力 | |---|---| | 工作台 | 站点状态、迁移进度、失败任务、线上告警 | | 网站 | 域名、环境、语言、主题、部署目标 | | 数据源 | 连接、凭据引用、导出文件、能力探测 | | 扫描与导入 | URL 来源、任务、差量、冲突和失败 | | 数据映射 | 源字段、标准字段、转换、未识别字段 | | 内容 | 页面、产品、新闻、分类、品牌、菜单 | | 页面板块 | 模板、板块、顺序、区域、预览 | | 媒体 | 原件、衍生、引用、旧路径和安全状态 | | URL | 路径、状态、跳转、冲突、部署兼容 | | SEO | 元信息、Sitemap、结构化数据、差异 | | 主题 | 主题版本、模板、组件兼容、预览 | | 构建 | 输入快照、任务、日志、产物 | | 测试 | URL、SEO、内容、资源、视觉报告 | | 发布 | Release、发布确认、部署、回滚 | | 系统 | 超管账号、会话、密钥、备份、日志、通知 | 页面编辑器仅提供板块新增、复制、排序、隐藏、删除、字段编辑、媒体/内容引用和静态预览，不提供自由画布和任意 CSS/JavaScript。 --- ## 17. 任务队列与可观测性 ### 17.1 队列类型 - Probe - Crawl - Import - Normalize - Asset - Build - Validate - Deploy - Cache Purge - Form Delivery ### 17.2 任务规则 - Job ID和幂等键。 - 最大重试次数。 - 指数退避和随机抖动。 - 可重试错误与永久错误分类。 - Worker心跳和租约。 - 超时和失联任务回收。 - 死信队列与人工重放。 - 每站点并发、抓取速率和资源配额。 - 取消和恢复检查点。 - 外部副作用记录，避免重复发送或重复部署。 ### 17.3 关键指标 - 队列长度、等待时间和失败率。 - 扫描页面数、成功率和每分钟请求。 - 导入新增/更新/冲突/失败数量。 - 构建时长、页面数、产物大小。 - 验收问题分布。 - 发布成功率和回滚次数。 - 生产 4xx/5xx、关键 URL 可用性。 - 表单接收与转发成功率。 - 存储、数据库和备份状态。 ### 17.4 告警 - 关键任务连续失败。 - 队列长时间无消费者。 - 构建或发布超时。 - 关键 URL不可访问。 - 生产出现全站 noindex/Canonical错误。 - 表单转发积压。 - 备份失败或恢复验证失败。 - 存储容量接近阈值。 --- ## 18. 自动验收与发布门禁 ### 18.1 测试矩阵 | 维度 | 自动检查 | 通过条件 | |---|---|---| | URL来源 | 多来源合并与去重 | 未处理 URL 为0或有明确例外 | | HTTP行为 | 状态、跳转、Header、Content-Type | 与路由注册表一致 | | SEO | Title、Canonical、Robots、Hreflang、JSON-LD | P0为0，P1修复或记录例外 | | 内容 | 标题、正文摘要、产品核心字段 | 满足站点验收清单 | | 引用 | 内容、媒体、路由反向关系 | 无悬空关键引用 | | 媒体 | 文件、MIME、哈希、尺寸 | 无未处理关键缺失 | | 内链 | href/src/srcset/CSS URL | 无未处理内部死链 | | 主题契约 | 模板、板块、schema、renderer | 全部兼容 | | 视觉 | 典型页面桌面/移动截图 | 新设计基线审核通过 | | 可访问性 | 语义、键盘、焦点、对比度 | 达到项目基线 | | 动态功能 | 表单、搜索和外部服务冒烟 | 每项成功用例通过 | | 性能 | Lighthouse/Web Vitals | 达到各站约定目标 | | 安全 | 敏感文件、依赖、CSP、恶意内容 | 无高危问题 | | 部署 | 目标能力和路由预检 | 无关键不兼容 | | 回滚 | 完整 release 恢复 | 演练通过 | ### 18.2 强制阻止发布 - 最终差量同步未完成。 - 关键 URL 未映射或意外 404/500。 - 重定向循环或关键查询路由无法实现。 - 生产页面存在错误 noindex、Canonical或预览域名。 - 大量核心内容、媒体或引用缺失。 - 主题缺少板块渲染器或 schema 不兼容。 - 部署目标不支持关键路由行为。 - 构建输入快照不完整或版本已过期。 - 当前环境存在其他发布任务。 - Release 无法回滚。 - 未通过超级管理员发布确认。 ### 18.3 报告 ```text inventory.csv route-diff.csv seo-diff.csv content-diff.csv reference-diff.csv assets-diff.csv broken-links.csv deployment-capability.json issues.json screenshots/ summary.html ``` --- ## 19. 安全设计 ### 19.1 认证与会话 - 超级管理员强密码和MFA。 - 密码使用成熟算法加盐哈希。 - 短期会话、HttpOnly/Secure/SameSite Cookie。 - CSRF防护。 - 登录限流和异常提醒。 - 恢复码离线保存。 - 高风险操作重新验证。 ### 19.2 凭据 - 数据源和部署凭据进入密钥管理。 - 数据库只保存引用，不保存可见明文。 - 优先只读凭据。 - 日志自动脱敏。 - 密钥支持轮换和撤销。 ### 19.3 SSRF与采集 - 域名、协议和端口白名单。 - DNS解析后检查IP。 - 每次重定向重新校验。 - 拒绝内网、回环、链路本地和云元数据地址。 - 受限网络出口和请求速率。 ### 19.4 供应链与构建 - 锁定依赖和运行时。 - 依赖漏洞和许可证扫描。 - 生成软件物料清单。 - 主题/适配器来源和版本可追溯。 - 构建沙箱默认无控制面密钥。 - 发布产物执行敏感信息扫描。 ### 19.5 Web安全 - CSP及必要安全响应头。 - Legacy HTML和SVG净化。 - 外部脚本、iframe和域名白名单。 - 预览站访问控制和禁止索引。 - 表单输入校验、限流和隐私保护。 --- ## 20. 备份、恢复与数据保留 ### 20.1 备份对象 - PostgreSQL。 - 对象存储中的原始快照和媒体。 - 构建 release 和报告。 - 路由与部署规则。 - 加密密钥配置和恢复材料。 - 系统配置及审计日志。 ### 20.2 建议目标 首版建议基线，可按实际业务调整： - PostgreSQL RPO：24小时以内；关键迁移/发布窗口前额外备份。 - 控制面 RTO：8小时以内。 - 已发布静态站 RTO：1小时以内，通过现有 release 恢复。 - 至少保留最近30天数据库备份。 - 生产 release 至少保留最近10个和所有人工标记版本。 - 原始迁移快照保留至站点迁移验收完成后的约定期限。 ### 20.3 一致性与演练 数据库备份记录对应的对象存储清单和密钥版本。恢复时按同一备份点恢复数据库、对象和配置。首个试点上线前完成一次恢复演练，此后至少每季度验证一次。 ### 20.4 数据删除 制定原始 SQL、个人数据、表单数据、日志和媒体的保留期限。清理任务先生成预览清单，超级管理员确认后执行，并保留删除审计。 --- ## 21. 非功能要求 ### 21.1 性能 - 管理后台常用查询应分页。 - 大型导入和构建全部异步执行。 - 静态页面按站点设定性能目标。 - 图片包含尺寸并生成适配资源。 - 客户端 JavaScript 按需加载。 ### 21.2 可访问性 建议以 WCAG 2.1 AA 为基础目标：语义结构、键盘操作、焦点状态、颜色对比、表单标签、替代文本和减少动画偏好。 ### 21.3 浏览器 项目启动时确定支持矩阵，默认支持主流浏览器最近两个稳定版本及当前主流移动浏览器。特殊旧浏览器按站点单独评估。 ### 21.4 配额 每站配置： - 最大 URL 数。 - 最大抓取深度和并发。 - 最大媒体和单文件大小。 - 最大构建时长和产物大小。 - 预览版本和 release 保留数量。 超出配额时停止任务并给出明确原因，不自动无限消耗资源。 --- ## 22. 技术栈与仓库结构 ### 22.1 技术栈 | 层级 | 技术 | |---|---| | 后台 | Art Design Pro（Vue 3 + TypeScript + Element Plus） | | API | NestJS + TypeScript | | 数据库 | PostgreSQL | | ORM | 预研阶段在 Prisma与团队既有方案中确定，并记录ADR | | 队列 | Redis + BullMQ | | 抓取 | Crawlee/Undici + Cheerio | | JS渲染 | Playwright | | 静态构建 | Astro + TypeScript | | Schema | JSON Schema + Ajv | | 媒体 | Sharp | | 对象存储 | S3兼容存储/MinIO | | 运行 | Docker Compose | | 测试 | 单元、契约、集成、Playwright E2E、HTTP验收 | ### 22.2 仓库 ```text siteforge/ apps/ admin/ api/ worker/ builder/ form-api/ packages/ contracts/ content-contracts/ block-contracts/ adapter-sdk/ adapter-wordpress/ adapter-generic-web/ route-engine/ seo-engine/ asset-engine/ validation-engine/ deployment-engine/ theme-runtime/ ui-primitives/ headless-components/ content-resolvers/ media-components/ seo-components/ form-runtime/ design-tokens/ themes/ pilot-wordpress/ pilot-secondary/ infra/ docker/ nginx/ database/ monitoring/ docs/ adr/ api/ runbooks/ migrations/ tests/ fixtures/ contract/ integration/ e2e/ ``` ### 22.3 ADR 决策记录 以下决策必须形成 ADR： - ORM选择。 - 对象存储与生产部署目标。 - URL 编码和文件映射规则。 - 主题/公共包版本策略。 - 富文本与 HTML 净化方案。 - 构建沙箱实现。 - Form API 数据保留和邮件/CRM策略。 --- ## 23. API 范围 ```text POST /api/v1/auth/login POST /api/v1/auth/mfa/verify POST /api/v1/auth/logout GET /api/v1/auth/sessions DELETE /api/v1/auth/sessions/:id POST /api/v1/sites GET /api/v1/sites/:siteId POST /api/v1/sites/:siteId/connections POST /api/v1/sites/:siteId/scans POST /api/v1/sites/:siteId/imports POST /api/v1/sites/:siteId/imports/:id/diff GET /api/v1/sites/:siteId/content PATCH /api/v1/sites/:siteId/content/:contentId GET /api/v1/sites/:siteId/content/:contentId/references GET /api/v1/sites/:siteId/routes POST /api/v1/sites/:siteId/routes/validate GET /api/v1/sites/:siteId/seo/diff GET /api/v1/themes GET /api/v1/themes/:themeId/manifest PUT /api/v1/sites/:siteId/theme POST /api/v1/sites/:siteId/builds GET /api/v1/sites/:siteId/builds/:buildId POST /api/v1/sites/:siteId/validations POST /api/v1/sites/:siteId/releases/:releaseId/publish POST /api/v1/sites/:siteId/deployments/:deploymentId/rollback GET /api/v1/sites/:siteId/reports/:type ``` 所有站点 API 在服务端验证登录状态、`site_id`、对象归属、版本号和并发条件。 --- ## 24. 测试策略 ### 24.1 单元测试 - URL规范化辅助键。 - 重定向循环检测。 - SEO差异分类。 - Schema验证和板块迁移。 - 内容引用和删除影响。 - checksum和差量判断。 - 部署能力匹配。 ### 24.2 契约测试 - 每个来源适配器使用相同 fixture 契约。 - 每个部署适配器满足 capability 接口。 - 每个主题 manifest、模板、板块和 renderer 完整。 - API DTO与事件版本兼容。 ### 24.3 集成测试 - WordPress导入到内容修订。 - 内容到Astro静态输出。 - Route Manifest到Nginx/CDN规则。 - 构建、校验、发布和回滚。 - Form API到邮件/CRM和死信重放。 ### 24.4 测试夹具 至少覆盖： - WordPress默认固定链接。 - `.html`和`.php`路径。 - 中文/Unicode路径。 - 大小写冲突。 - 尾斜杠混用。 - 查询参数入口。 - 多级分类和分页。 - Yoast/Rank Math。 - ACF/Gutenberg。 - 重定向链和媒体重定向。 - JS渲染页面。 - 不支持板块和板块版本升级。 ### 24.5 视觉测试 新旧站只比较内容和关键结构，不做像素一致要求。新主题建立自己的视觉基线，后续主题升级与该基线做截图回归。 --- ## 25. 项目阶段与排期 以下按约5人核心团队估算：1名项目/产品负责人、2名前后端工程师、1名迁移/数据工程师、1名测试/运维，设计师阶段性参与。 ### 阶段0：真实数据盘点与技术预研（第1–2周） 任务： - 选择WordPress试点和第二来源试点。 - 获取数据库、WXR、uploads、日志、Sitemap和服务器规则。 - 建立URL/SEO/功能初始基线。 - 验证重点插件、页面构建器和路径类型。 - 确定ORM、存储、部署和构建沙箱ADR。 交付：试点评估报告、来源能力报告、风险清单、字段样本、最终V1范围与校准排期。 ### 阶段1：平台骨架与安全基础（第3–5周） 任务： - Monorepo、环境、CI。 - 超管登录、MFA、会话和日志。 - PostgreSQL、Redis、对象存储。 - 站点、环境、快照、任务和密钥引用。 - Worker租约、重试和死信框架。 交付：可登录、创建站点、运行并观察后台任务。 ### 阶段2：扫描、导入与URL/SEO基线（第6–9周） 任务： - Sitemap/HTML/Playwright扫描。 - WordPress REST/WXR/SQL/uploads导入。 - 多来源URL合并。 - 原始快照、差量同步和冲突处理。 - 内容、媒体、URL和SEO核心模型。 交付：首站真实数据可重复导入，生成URL/SEO/内容清单。 ### 阶段3：主题、板块和静态构建（第10–13周） 任务： - Block Schema、模板和主题manifest。 - 公共组件包。 - 后台板块编辑。 - 首套试点主题。 - 隔离可复现构建。 - 内容引用和删除影响分析。 交付：首站能从后台内容生成完整静态预览。 ### 阶段4：第二主题、第二来源与动态功能（第14–16周） 任务： - 第二套明显不同的主题。 - 通用网页/第二来源适配。 - 公共组件复用验证。 - 表单或试点必需动态服务。 - 目标部署适配器和能力预检。 交付：两个站点、两种来源、两套主题在同一平台运行。 ### 阶段5：门禁、发布与生产化（第17–20周） 任务： - URL/SEO/内容/媒体/视觉验收。 - 发布锁、原子切换和CDN策略。 - 回滚、监控、告警和备份恢复。 - 最终差量同步和切站Runbook。 - 上线彩排、正式切换和保护期。 交付：至少一个试点正式上线，两个试点均完成完整迁移与回滚闭环。 ### 25.1 计划区间 建议按20–24周预留项目周期，目标20周，额外4周用于复杂插件、历史路径、内容清理和试点反馈。若团队少于4人，应减少第二来源范围或顺延工期。 --- ## 26. 团队职责 这里是项目职责，不是系统角色： | 职能 | 责任 | |---|---| | 项目/产品 | 范围、优先级、试点协调和业务结论 | | 架构/后端 | 数据、API、任务、构建、发布和安全 | | 前端/主题 | 管理后台、组件包、主题和响应式页面 | | 迁移/数据 | 扫描、适配器、字段映射、URL/SEO基线 | | 测试/运维 | 自动验收、部署、监控、备份和回滚 | | 设计 | 品牌规范、模板设计和视觉验收 | | SEO/内容业务 | 提供线下确认，由超管记录结论 | 系统内所有操作仍由超级管理员完成。 --- ## 27. 试点资料清单 ### 27.1 WordPress试点 - 域名、授权和主机信息。 - WXR、SQL、网站目录和uploads。 - 插件/主题列表及版本。 - SEO插件、ACF/CPT和页面构建器信息。 - Sitemap和服务器重写规则。 - 访问日志、GSC、GA4落地页。 - 重要页面和高流量页面。 - 表单、搜索、多语言、会员、交易和第三方脚本。 - DNS、CDN、证书和生产发布权限。 ### 27.2 第二试点 - 非WordPress或只能从HTML/API/数据库迁移。 - 页面结构与第一站明显不同。 - 可验证独立主题和通用适配器。 - 能提供足够数据和业务确认人。 ### 27.3 设计资料 - Logo、字体、颜色和品牌规范。 - 桌面/移动设计稿。 - 页面类型和组件清单。 - 内容优先级和典型页面。 - 目标浏览器和性能要求。 --- ## 28. 风险管理 | 风险 | 影响 | 应对 | |---|---|---| | 数据来源不完整 | 页面或字段遗漏 | 多来源URL全集、明确未知范围 | | 迁移期间旧站继续更新 | 切站时丢内容 | 差量同步、冻结窗口、最终重扫 | | 页面构建器复杂 | 无法自动结构化 | 原始数据保留、映射、Legacy兜底 | | URL规则混合 | 404或错误跳转 | 注册表、部署能力预检、真实HTTP测试 | | 部署目标能力不足 | 无法保持状态码和查询规则 | 路由编译器、Edge或更换目标 | | 构建并发 | 旧版本覆盖新版本 | 输入快照、租约、CAS发布锁 | | 主题过度通用 | 所有网站设计雷同 | 复用数据与逻辑，视觉独立 | | 公共组件耦合 | 升级影响全部主题 | 语义版本、契约测试、截图回归 | | 动态功能遗漏 | 表单/搜索失效 | 功能处置表和上线冒烟 | | 构建代码不可信 | 泄密或破坏环境 | 隔离容器、限额、默认断网 | | 超管账号丢失 | 无法管理系统 | MFA恢复码、离线备份、恢复Runbook | | 备份不可恢复 | 故障时数据永久丢失 | RPO/RTO、关联清单、季度演练 | | 范围扩张 | V1延期 | 版本矩阵和变更评审 | | SEO波动 | 搜索流量下降 | 基线、门禁、监测和快速回滚 | --- ## 29. 最终交付物 ### 29.1 软件 - SiteForge管理后台。 - API、数据库迁移和Worker。 - 超管认证、MFA、会话和操作日志。 - WordPress与通用网页适配器。 - URL、SEO、内容、媒体和引用引擎。 - 主题SDK、组件公共包和两套主题。 - Astro隔离构建系统。 - 路由编译和部署适配器。 - 验收报告、发布锁、回滚和监控。 - Form API或试点动态能力。 - Docker、Nginx、备份和运维配置。 ### 29.2 文档 - 产品功能与后台说明。 - 系统架构和ADR。 - 数据库字典和ER图。 - API、队列和状态机协议。 - 适配器SDK。 - 主题、板块和组件开发规范。 - URL/SEO迁移规范。 - 安全和数据保留规范。 - 部署、监控、备份和恢复手册。 - 切站与回滚Runbook。 - 自动测试和验收模板。 - 两个试点迁移报告。 ### 29.3 最终验收流程 两个试点能够完成： ```text 多来源盘点 → 全量导入 → 标准化与映射 → 独立主题 → 差量同步 → URL/SEO冻结 → 静态构建 → 自动门禁 → 目标环境预检 → 发布确认 → 原子发布 → 生产验证 → 回滚演练 ``` 所有未支持内容和功能必须进入异常清单，不能静默遗漏。 --- ## 30. 立项前需要确认 1. 首个WordPress试点站。 2. 第二个不同来源试点站。 3. 两个站点的页面数、媒体量、语言和动态功能。 4. 是否能提供SQL、uploads、访问日志、GSC和服务器规则。 5. 生产主要部署到Nginx还是对象存储/CDN。 6. 表单提交到邮箱、CRM还是两者。 7. V1是否只做单语言和手动发布。 8. 目标RPO、RTO和旧站保留期。 9. 品牌设计稿和页面类型是否已经确定。 10. 超级管理员账号和恢复材料由谁保管。 --- ## 31. 立即执行计划 1. 收集两个试点资料并建立只读备份。 2. 从Sitemap、数据库、日志、GSC和业务清单合并URL初始全集。 3. 建立10–20个真实页面的最小纵向PoC。 4. 验证：导入 → 标准化 → URL/SEO → 主题渲染 → 静态发布。 5. 确定ORM、部署目标、构建沙箱和Form API ADR。 6. 冻结V1范围矩阵和验收清单。 7. 再进入20周左右的正式开发与试点实施。 --- ## 32. 最终结论 本方案将SiteForge定位为“多站点迁移与静态发布控制平台”。系统统一的是数据、URL、SEO、组件协议、构建和发布，不强制统一每个网站的设计。 项目成功的关键不只是采集页面，而是： - 从多来源建立可信URL全集。 - 迁移期间持续差量同步，切站时不丢数据。 - 使用可追溯的内容和路由快照。 - 用公共数据/逻辑组件提高复用，同时保留主题视觉独立。 - 在目标部署环境验证真实HTTP行为。 - 通过构建锁、发布锁和不可变release避免版本错乱。 - 通过门禁、监控、备份和回滚控制上线风险。 按本方案完成两个差异化试点后，后续网站可以复用迁移、内容、URL、SEO、构建、测试和发布能力，把新增站点的主要工作收敛到数据映射、异常处理和独立主题设计。 --- ## 附录A：发布前检查表 | 检查项 | 结果 | 备注 | |---|---|---| | 旧站写入已冻结 | | | | 最终差量同步完成 | | | | URL多来源基线完成 | | | | 关键URL状态与跳转通过 | | | | SEO P0/P1处理完成 | | | | 内容和媒体抽检通过 | | | | 主题/板块契约通过 | | | | 表单/搜索等动态功能通过 | | | | 部署能力预检通过 | | | | 构建输入快照锁定 | | | | 生产冒烟脚本准备 | | | | 回滚版本和脚本确认 | | | | 数据库/对象存储备份完成 | | | | 超级管理员完成发布确认 | | | ## 附录B：核心状态机 内容： ```text draft → ready_to_publish → published → archived ``` 迁移记录： ```text raw → normalized → needs_review → verified ``` 构建发布： ```text created → snapshot_locked → building → validating → ready_to_publish → publishing → verifying → published ``` 任务异常： ```text failed / cancelled / dead_lettered / partially_deployed / rolled_back ``` ## 附录C：官方实现参考 - WordPress REST API： - WordPress WXR： - WP-CLI export： - Astro路由： - Google不变URL的站点迁移： - Google URL变更迁移： - OWASP SSRF防护： > 框架版本、插件兼容性、部署供应商能力、项目周期和RPO/RTO，应在阶段0完成真实试点盘点后最终确认。 > 对应的详细Sprint、任务分解、依赖、验收门槛和上线时间线，见 `SiteForge_项目实施计划_V1.0.md`。