# SiteForge V8.17 — 生产交付门禁执行手册

> 状态：独立增量验收工具；不包含 V8.16 原项目源码、Art Design Pro 官方完整工程或真实测试环境。本文的项目结构以所获 V8.16 README 为依据。生产演练与授权审批必须由真实环境执行并存档。

## 一、目标与范围

- V8.16 具备 HTTP `/api/health`、`/api/ready`，PG 兼容层、Worker 实例标识与 HTTP/PG 浏览器测试脚本。
- V8.17 增量提供不侵入应用数据的统一检查入口，报告 JSON + Markdown + 离线可视化 HTML。
- **不替代** `scripts/check.sh`、`scripts/http_end_to_end.py`、`scripts/browser_smoke.py`、`scripts/verify_pg_bootstrap.py`；这些是应用级端到端验证。
- **不会执行** Docker up/down/build、数据库迁移、写入、发布/回滚、备份/恢复、人工审批。

## 二、集成路径

1. 解压原 V8.16 完整工程到**隔离测试目录**，不要覆盖正式数据卷。
2. 将本补充包 `scripts/siteforge_v817_audit.py` 和 `tests/test_siteforge_v817_audit.py` 分别复制到原项目同名目录中；不会替换已有模块。
3. 按需复制 `docs/V8_17_ACCEPTANCE_RUNBOOK.md` 和 `examples/`。
4. 运行 `python -m unittest discover -s tests -p 'test_siteforge_v817_audit.py' -v`，再执行以下命令。

## 三、执行命令

最小安全检查（无网络、无需 Docker）：

```bash
python scripts/siteforge_v817_audit.py --repo . --output reports/siteforge-v817
```

隔离 Docker 企业 Compose 已启动后：

```bash
python scripts/siteforge_v817_audit.py \
  --repo . --docker --url http://127.0.0.1:8787 \
  --output reports/enterprise-staging
```

使用已有隔离数据库配置；**PG 仅执行 SELECT 1（事务只读），Redis 仅执行 PING**：

```bash
# 以下环境变量需由运维通过私密渠道事先配置，切勿提交 .env 或 DSN 到仓库。
python scripts/siteforge_v817_audit.py \
  --postgres --redis --output reports/datastores
```

静态构建产物 URL 校验（old_urls.txt 需人工从旧站导出，不自动抓取）：

```bash
python scripts/siteforge_v817_audit.py \
  --build-dir /path/to/generated/site \
  --url-baseline old_urls.txt \
  --output reports/static-seo
```

验收报告：`reports/*.html` 离线打开、`reports/*.json` 可机器读取、`reports/*.md` 可归档。返回码 2 代表存在 FAIL；WARN/SKIP 仅表示需要进一步处理，不视为生产通过。

## 四、关键门禁和接受标准

| 门禁 | 自动审计可做 | 仍需人工与真实环境执行 |
|---|---|---|
| 代码与 Compose | 文件完整性、Python AST、Compose 配置、容器状态 | 应用全测试集、供应链审计、CI 与镜像签名 |
| Web 与 Worker | HTTP readiness、容器运行/health、Worker 服务发现 | 真实异步任务、租约竞争、断网恢复、容量压测 |
| PostgreSQL | 真正连通后的 `SELECT 1` | **隔离测试库**运行原项目 PG bootstrap、迁移校验、恢复演练 |
| Redis | PING | 队列可靠性、幂等、故障切换、持久化和告警演练 |
| URL / SEO | html lang、canonical 规则、内部链接、旧路径覆盖、sitemap | 迁移映射审定、301/404、robots、实际源站比对、GSC 验收 |
| 多语言 | hreflang 格式与语言标签 | 关联双方对称、翻译审核、独立域名 HTTPS |
| 发布与回滚 | 读取人工证据表 | 真实 staging 激活、不可变版本、校验 SHA、回滚演练、审批隔离 |
| Art Design Pro | 检查当前 `workspace` 静态入口 | **获得官方工程并构建**，完成组件/路由/权限/API 接入和验收 |

## 五、证据记录规范

以 `examples/evidence.template.json` 为模板记录 10 个阶段。每阶段保留 `status`、`operator`、`date`、`evidence`，例如证据可以是带日期的运行日志路径或测试报告 URL。工具只验证字段存在，**不核验证据内容真实性**。`pending` 永远不等同 `passed`。

**回滚演练**：先备份隔离测试环境，生成构建 A，部署到 staging，生成 B，再回滚至 A；比对前后首页和关键 URL 的 SHA/状态码，确认旧版恢复。测试的真实日志由人工归档。不得自动在生产环境执行此脚本包的任何写入动作。

**SSRF 风险**：HTTP 模式默认仅 localhost。远端只允许在操作者明确指定 `--allow-remote` 且获得目标授权时检查；URL 不得包含用户名、密码、查询或 fragment。代理/CDN 的响应和 TLS 配置需人工复核。

## 六、管理后台 UX 接入约定（下一层）

- 导航继续沿用“工作台 / 我的网站 / 内容页面 / 外观设计 / 导入迁移 / 构建交付 / 网站设置”；技术工具统一收纳高级工具。
- 验收中心可在**构建交付 > 验收报告**展示 JSON：优先级为 FAIL、WARN、SKIP、PASS，附修复建议，保留站点上下文。
- 不在编辑页弹出多层确认；破坏性/正式发布才要求明确确认或审批。
- 未获得 Art Design Pro 官方完整源码前，该交付**不能称为官方集成**；正式集成需基于实际 Vue 项目文件、授权版本、组件结构和构建配置开展。

## 七、Known limitations

- 文件可用性为当前 V8.16 README 描述，不保证用户本地工程文件路径完全相同，缺项会被标注 WARN。
- 报告 **不是渗透测试、上线证明、真实发布演练或真实数据备份报告**。
- 单站静态链接检查不能证明跨语言站的双向 hreflang；多语言配对需单独验证。
- 对于在 CDN 或独立路径进行的预览，构建本地链接存在不代表预览 rewrite 逻辑完全正确，需要另行浏览器检查。
- 使用 JSON 证据表并不代表完成任何业务审批或合规认证。

## 八、隔离 CI

提供 `.github/workflows/siteforge-v817-acceptance.yml` 作为**人工触发**的独立验收工作流：一组运行只读源码检查/测试，一组在临时 PostgreSQL 16 和 Redis 7 容器中执行最小存活检查，并上传脱敏报告。该 CI **不能替代**在实际 SiteForge 企业 Compose 下的完整业务链路和故障注入。