cms-SiteForge/README.md

# SiteForge Enterprise V8.21.3 — 四套内置主题手机端统一优化

> **状态：开发集成版**。从 V8.21.2 完整源码升级；原站点与数据未覆盖。四套内置主题统一支持抽屉菜单，可选的 1–5 项手机底栏 Tabs 默认关闭。正式生产的域名部署、Apple/Android 真机与 Art Design Pro 官方构建仍需独立验收。

## 本轮重点

- `automotive` / `industrial` / `corporate` / `minimal` 手机端导航统一为右侧抽屉，菜单可包含二三级链接。
- 全站设计新增 `mobile_tabs`：默认 `enabled=false`；开启后新增、删除、排序、图标、站内/HTTPS/电话/邮箱链接均通过可视化表单配置。
- 支持底部 `菜单` Tab 打开抽屉；适配安全区域与小屏宽度。
- 保留现有网站内容、URL/SEO、设计草稿与构建/发布流程；旧配置无需迁移，默认不显示底栏。
- 手机端 4 套主题 × 首页/产品列表/产品详情/文章详情 × 375/390/430px 离线 Chromium 回归通过。

## 快速使用和测试

- **直观预览**：`examples/mobile-showcase/index.html`（离线主题样例，可切换四主题和四类页面）。
- **后台配置**：网站 → 可视化编辑器 → 全站页眉与页脚 → 手机底部快捷导航 Tabs。
- **专项测试**：`python -m pytest tests/test_mobile_tabs_v8213.py -q`。
- **Chromium 测试**：`python scripts/browser_mobile_v8213.py`（需要 Playwright 和 Chromium）；结果写入 `reports/mobile-v8213-browser.json`。
- **HTTP 端到端**：`python scripts/http_end_to_end.py`。
- **完整技术说明**：`docs/V8_21_3_MOBILE_THEMES.md`。

---

# SiteForge Enterprise V8.21.2 — 简洁可视化编辑器（开发集成版）

本轮优化聚焦**降低学习成本**，而不是增加技术菜单。新增三步操作指引、显眼的草稿保存和设计发布、左侧一键添加区块、右侧内容/样式/设备编辑，复杂模板与动态数据设置默认收起；中间预览可以直接点击区块选中。FAQ、轮播、画廊、优势、数字统计等条目使用逐项普通表单，**不再要求普通用户填写 JSON**。

- 编辑器：原 `/editor/{site_id}/{entry_id}` 路径，无数据库结构变更。
- 离线可交互预览：[`examples/Studio_V8_21_2_新手友好版交互预览.html`](examples/Studio_V8_21_2_新手友好版交互预览.html)。演示中的保存/发布不连接生产 API。
- 变更与验收：[`docs/V8_21_2_EASY_STUDIO.md`](docs/V8_21_2_EASY_STUDIO.md)。
- 仍保持原有 CSRF、权限、草稿乐观锁、审核及静态构建流程；**发布设计不等于自动部署上线**。
- 官方 Art Design Pro 工程、真实 Chromium E2E 和生产环境验收仍需独立完成；不要据此宣布正式投产。

---

# SiteForge Enterprise V8.21.1 — Studio 可视化编辑器体验增强

> 基于 V8.21.0-dev.1 完整源码迭代；当前版本 `8.21.1-dev.1`，属于兼容性开发集成版，未覆盖生产网站。
>
> **本次直接改进**：区块搜索和快捷排序、属性分类、PC/平板/手机预览、保存与预览异步竞态保护、移动端侧栏、Ctrl+S、测试工具和离线交互示例。
>
> 交付说明：[可视化编辑器优化实施与验证](docs/V8_21_1_STUDIO_UX.md) | [无需服务器的离线交互演示](examples/Studio_V8_21_1_交互预览.html) | [原始测试数据](reports/studio-ux/editor-ux-validation.json)
>
> **准确验收边界**：39 个测试模块拆分运行累计 328 项通过，HTTP+Worker 构建通过；一键回归在第七批出现停滞，真实 Chromium 因环境策略被拒绝。尚未完成正式 Art Design Pro 全工程编译或真实企业部署验收。

---

# SiteForge Enterprise V8.21.0-dev.1 — 高级编辑历史与安全数据装配

**交付性质：完整源码的开发集成版。** 基于 V8.20 继续开发，保留原有 WordPress 迁移、主题建站、P5 发布、多语言和企业运维代码。

本轮新增：

- **持久化设计版本历史**：每次页面草稿保存与发布自动创建完整快照，按网站和页面隔离，SHA-256 完整性校验，编辑权限控制；可从历史记录恢复成**新草稿**（不直接覆写线上页面）。前端编辑器新增“版本历史”操作。
- **更安全的数据装配**：字段映射支持受限的 trim、默认值、英文大小写转换、前后缀；预览生成确定性 `plan_hash`，确认导入时可携带该指纹防止过期预览；新增严格冲突拒绝模式 `abort`，现有 `skip`、`replace` 仍兼容。内容导入 UI 新增转换选择、冲突策略和预检确认。
- **质量与版本管理**：更新镜像标签、版本常量和检查入口；专项测试覆盖历史恢复、站点隔离、快照篡改阻断、过期预检及字段处理。

验收：本地按 **10 个独立分组**执行原项目全部 **38 个测试模块、325 项测试通过**；Python 编译、Node.js 语法、静态发布检查和 HTTP+Worker E2E 通过。长流程一键检查在本环境**曾偶发停滞**，因此不能把它记为完全稳定。真实 Docker、PostgreSQL/Redis、正式 Art Design Pro 工程编译及客户迁移仍未通过验收。

文档：[V8.21 实现与验收](docs/V8_21_EDITOR_AND_MAPPING.md) · [HTML 验收报告](reports/V8_21_集成验收.html) · [10 批原始日志](reports/v821_manual_verified/)

验证命令：

```bash
python -m pytest -q tests/test_v821_editor_history_and_mapping.py
python scripts/http_end_to_end.py
bash scripts/check.sh
```

---

# SiteForge Enterprise V8.20.0-dev.1 — 复杂 WordPress 迁移预检与兼容性增强

基于 V8.19 完整源码。本轮新增 WXR 离线兼容预检 API + 后台入口、ACF 简单 Repeater 元数据提取、CSS 背景图本地化、危险 URL 在直接导入及暂存前阻断，以及带构建路径对账的 JSON/HTML CLI 报告。

- 阅读：[`docs/V8_20_COMPLEX_WORDPRESS.md`](docs/V8_20_COMPLEX_WORDPRESS.md)
- 演示：`python scripts/wp_v820_preflight.py fixtures/v820/wordPress-complex-sample.xml --output reports/v820-demo.json`（演示数据包含故意设置的阻断项，返回码为 1）
- 回归：`bash scripts/check.sh` 或 `python scripts/regression_v820.py --batch-size 4 --report reports/v820-regression`
- HTTP 集成：`python scripts/http_end_to_end.py`
- 安全：所有离线预检不写数据库、不联网、不执行 PHP/JS 或反序列化未知 PHP 对象。

**交付状态：开发集成版。** 尚未实现 WordPress/Elementor/ACF/WooCommerce 完整 1:1 视觉或动态业务迁移；Art Design Pro 官方工程真实编译与生产 PostgreSQL/Redis/远程发布仍需现场验收。

---

# SiteForge Enterprise V8.19.0-dev.1 — 统一后台集成版

V8.19 基于 V8.18 的完整项目继续开发。新增 **后端授权菜单 `/api/console/bootstrap`**、Art Design Pro **单一导航树安装器**、Vue 工作台与内容管理、共享会话/CSRF/站点选择、官方工程安装校验，以及 HTTPS 同源反向代理示例。正式功能与限制详见 [`docs/V8_19_ART_UNIFIED_BACKEND.md`](docs/V8_19_ART_UNIFIED_BACKEND.md)。

**交付性质：开发集成版。** 本仓库含完整 SiteForge 后端和 Art 对接业务模块，**不含官方 Art Design Pro 整套前端工程**；真实官方 `pnpm build`、PC/移动端浏览器及 HTTPS 正式发布尚未验收。不得把安装器 fixture 测试等同于官方完整前端编译。历史的 PostgreSQL/Redis/多 Worker 生产门禁仍未关闭。

建议执行：

```bash
bash scripts/check.sh
python scripts/http_end_to_end.py
python scripts/install_into_art_design_pro.py /path/to/official/art-design-pro
python scripts/install_into_art_design_pro.py /path/to/official/art-design-pro --apply
python scripts/verify_art_design_pro_v819.py /path/to/official/art-design-pro
```

---

# SiteForge Enterprise V8.18.0-dev.1 — 企业底座与数据迁移安全

V8.18 基于 V8.17 完整源码继续开发。新增 PostgreSQL 专用灾备、SQLite→PG 数据迁移校验、外部发布不确定状态的安全处置、CI 集成验证。详见 [`README_V8_18.md`](README_V8_18.md) 和 [`docs/V8_18_ENTERPRISE_HARDENING.md`](docs/V8_18_ENTERPRISE_HARDENING.md)。**本版本尚未完成真实生产环境验收。**

---

# SiteForge Enterprise V8.17.0-dev.1 — 集成回归与生产验收整合版

> **状态：开发集成版；不代表生产环境验收通过。** 基于 V8.16 完整源码升级，合入 V8.17 只读审计和 WordPress URL 迁移基线工具，并改造官方回归执行器。原 ZIP 不受影响。

## V8.17 本轮已整合

- **统一回归执行器**：`scripts/regression_v817.py` 逐批运行测试（每批最多 10 个文件），每批超时默认 90 秒；超时将结束整个子进程组、留存日志，随后逐个模块隔离定位。任何超时、失败或重试后才通过，都不能算本次验收通过。
- **Windows + Linux 一致性**：`scripts/check.sh` 和 `scripts/check.ps1` 均调用该执行器。JSON、Markdown、HTML 及每批 verbose 日志保存在 `reports/`。
- **可重复 CI**：Linux CI 两轮重复测试并上传报告；新增隔离浏览器 smoke 作业，原有 PostgreSQL、Docker 质量门禁保留。CI 定义存在并不表示已经在 GitHub Actions 实际执行。
- **Chromium 测试修复**：移动端新页面复用桌面端登录上下文；默认使用 Playwright 安装的 Chromium，`SITEFORGE_CHROMIUM` 可显式指定浏览器。
- **生产验收只读工具**：`scripts/siteforge_v817_audit.py` 支持仓库、存活/就绪探针、Compose、PG SELECT 1、Redis PING、静态构建/SEO、人工发布证据校验；不会执行部署或数据库变更。
- **WordPress 路径核对**：`scripts/export_wordpress_url_baseline.py` 从授权站点导出的 WXR/Sitemap 等本地文件建立旧路径基线，再用构建目录对比。缺失路径阻断验收而不是静默改 URL。
- 本轮产品版本更新为 `8.17.0-dev.1`；Compose 镜像及已有版本断言相应升级。不存在自动升级现有部署卷的操作。

### 一键回归（隔离本地目录）

```bash
bash scripts/check.sh
python scripts/http_end_to_end.py
python scripts/siteforge_v817_audit.py --repo . --output reports/v817-audit
```

Windows PowerShell：`./scripts/check.ps1`。

若需重复运行和定位卡点：

```bash
python scripts/regression_v817.py --repeat 3 --timeout 90 --module-timeout 50 --report reports/repeated
```

### 上线门禁

正式上线之前必须在独立测试环境完成 GitHub CI 的 Docker / PG / Redis / Chromium、真实远程发布与回滚、备份恢复、业务页面与 301/canonical/hreflang 审核。**没有实测证据时这些条目均视为未验收。** `Art Design Pro` 官方完整工程并未随此源码提供，本版本没有声称已编译或安装该后台。

参阅：`docs/V8_17_ACCEPTANCE_RUNBOOK.md` 和 `docs/V8_17_INTEGRATION_RELEASE_NOTES.md`。

---

# SiteForge Enterprise V8.16.0-dev.1 — 企业部署基础与可重复验收

> **交付状态：开发集成版。** 该版本继续沿用 V8.15 全部建站、编辑、WordPress 迁移、P5 发布和 P6 多语言功能。本轮重点是修复 PostgreSQL 兼容隐患、健康探针、Worker 实例隔离和实测建站链路。**Art Design Pro 官方完整工程没有随项目提供，不能声称已集成或完成编译；真实 PostgreSQL/Redis、Docker 和公网上线仍须实机验收。**

## V8.16 本轮变更

1. **PostgreSQL 查询行适配**：`PGRow` 同时提供字典字段访问和数字索引（如 `fetchone()[0]`），修复了原队列容量检查与其他遗留语句在 PG 下类型不匹配的问题。占位符转换现在保护 SQL 注释和转义引号；DDL 分句避免破坏字符串里的分号。
2. **数据库初始化迁移**：原先仅 SQLite 执行的 `schema_registry` 迁移账本现在也在 PostgreSQL 创建和校验；重复运行可验证迁移 checksum。团队账号唯一性冲突也支持 PG 错误码 `23505`。
3. **探针分层**：`GET /api/health` 为轻量存活；新增公开 `GET /api/ready` 检查数据库查询和 `/data` 可写性，失败只返回 `503 {"status":"unavailable"}`，不会泄露数据库/文件路径。Compose 的 Web 探针改用 `/api/ready`，Worker 探针附加数据库和存储检查。
4. **Worker 心跳隔离**：支持 `SITEFORGE_WORKER_INSTANCE`，企业 PostgreSQL 模式下默认以容器主机名隔离心跳，防止两个 Worker 相互掩盖健康问题；构建队列依然以数据库锁/租约为准。
5. **集成验证**：新增 `scripts/http_end_to_end.py`，可在隔离 SQLite 中实际启动 HTTP 服务，创建网站和页面、提交任务、启动 Worker 子进程、检查 ZIP 和预览。`scripts/browser_smoke.py` 为真实 Chromium 脚本（需要浏览器允许本地 HTTP）；扩展 `scripts/verify_pg_bootstrap.py` 对所有模块初始化和队列 claim/complete/cancel 的真实 PostgreSQL 验证。
6. **CI**：回归按模块分进程运行，减少历史测试共享状态造成的超时；Web 真实 HTTP 集成测试纳入测试 Job，PG 连接测试继续由 CI `postgres-smoke` Job 执行。

## 快速检查

```bash
bash scripts/check.sh
python scripts/http_end_to_end.py
# 仅在隔离的 PostgreSQL 数据库中：
SITEFORGE_DATABASE_URL='postgresql://siteforge:***@postgres:5432/siteforge_test' python scripts/verify_pg_bootstrap.py
# 可选：安装 Playwright + Chromium 后，且允许访问 localhost：
python scripts/browser_smoke.py
```

完整验收说明和未完成门禁见 [`docs/V8_16_PRODUCTION_ACCEPTANCE.md`](docs/V8_16_PRODUCTION_ACCEPTANCE.md)。**不要在生产数据库上运行 PG smoke**，不要直接把 SQLite 数据文件重定向为 PostgreSQL，也不要在没有备份/恢复演练时升级正式卷。

---

# SiteForge Enterprise V8.15.0-dev.1 — P6 多语言网站与国际 SEO

> 历史版本说明：V8.14 在 V8.13 基础上新增原生 SFTP、S3 发布适配器及 S3 发布指针读取服务，保留 P5 发布任务、不可变版本校验与历史回滚；保留四套主题、内容管理、WordPress 迁移、数据连接器、编辑器和 Worker。**SFTP/S3 已有代码及本地仿真测试，但未完成真实 Docker、远程服务器和生产域名验收，不可直接宣布生产级完成。**


## V8.15 新增：P6 多语言网站管理（开发集成版）

**请先读此段**：V8.15 在 V8.14 完整源码上新增语言组/翻译组、审核状态、前台语言切换、HTML `lang`、双向 `hreflang` 与 Sitemap `xhtml:link`。所有业务内容由用户自己翻译、审核；不会自动翻译产品规格、公司地址或 SEO 事实。

- 入口：后台首页 → 选择网站 → **多语言管理**。
- 一个 SiteForge 站点代表一个语言版本，每个语言站拥有独立的企业内容和 URL。已实现**独立域名或子域名**方案，组成员必须配置自己的 HTTPS 域名；尚不支持多个语言共用域名下的 `/en/` 子路径方案。
- 管理员创建语言组，选择默认语言；拥有两个语言站 Owner 权限的操作者可以把站点加入同一语言组。
- 按语义创建翻译内容组（如 `product:rox01`），把中文 `/products/rox/` 与英文 `/vehicle/rox/` 的**实际内容 ID** 关联。两端需要 `published` 和 `approved` 且允许索引才会输出相互指向的语言链接。
- `pending` 只允许关联内容草稿。如果后来绕过编辑器直接将 pending 内容改为 published，**构建会拒绝执行**。
- 默认语言确实有已审核对应页面时才输出 `x-default`；`noindex`、缺失、草稿或不一致 canonical 的页面不参与。
- 生成的 `sitemap.xml` 使用正确的 XHTML 命名空间和双方对称的 alternate URL；每个独立网站的 canonical 仍指向自己的正式 URL。
- UI 有可点击的语言切换条，未关联的页面不显示不存在的翻译页面入口。
- 旧站无需设置语言组，可继续按原构建方式工作；数据库迁移只新增表格。
- 本轮**没有**实现机器翻译、批量翻译工作流、子路径多语言站点、主题各栏目默认文案的完全国际化。四套现有商业主题的预设导航和空栏目提示部分仍是中文，正式英文站上线前需配置企业自己的导航和文案。

操作示例：

1. 在“我的网站”分别新建中文站和英文站，设置 `https://zh.example.com`、`https://en.example.com`。
2. 选择中文站 → 多语言管理 → 建立语言组，默认语言可选 `en`，并将当前站点登记为 `zh-CN`（若建组时，分别填写“默认语言”和“当前网站实际语言”，两者可以不同）。
3. 将英文站加入该语言组，设置 `en`；在两个站各自建立真实对应页面。
4. 创建翻译组 `about-company`，分别选中两语言的页面，状态设为“已确认”。
5. 在两个站分别执行 Worker 静态构建，检查 HTML `<html lang=...>`、`rel=alternate` 和 `sitemap.xml`；正式发布仍需要独立审批。

本轮核心代码：`app/multilingual.py`、`app/builder.py`、`app/templates/workspace.html`、`app/static/workspace.js`，专项测试 `tests/test_multilingual_v815.py`。


## V8.15 新增：P6 多语言网站管理（开发集成版）

**请先读此段**：V8.15 在 V8.14 完整源码上新增语言组/翻译组、审核状态、前台语言切换、HTML `lang`、双向 `hreflang` 与 Sitemap `xhtml:link`。所有业务内容由用户自己翻译、审核；不会自动翻译产品规格、公司地址或 SEO 事实。

- 入口：后台首页 → 选择网站 → **多语言管理**。
- 一个 SiteForge 站点代表一个语言版本，每个语言站拥有独立的企业内容和 URL。已实现**独立域名或子域名**方案，组成员必须配置自己的 HTTPS 域名；尚不支持多个语言共用域名下的 `/en/` 子路径方案。
- 管理员创建语言组，选择默认语言；拥有两个语言站 Owner 权限的操作者可以把站点加入同一语言组。
- 按语义创建翻译内容组（如 `product:rox01`），把中文 `/products/rox/` 与英文 `/vehicle/rox/` 的**实际内容 ID** 关联。两端需要 `published` 和 `approved` 且允许索引才会输出相互指向的语言链接。
- `pending` 只允许关联内容草稿。如果后来绕过编辑器直接将 pending 内容改为 published，**构建会拒绝执行**。
- 默认语言确实有已审核对应页面时才输出 `x-default`；`noindex`、缺失、草稿或不一致 canonical 的页面不参与。
- 生成的 `sitemap.xml` 使用正确的 XHTML 命名空间和双方对称的 alternate URL；每个独立网站的 canonical 仍指向自己的正式 URL。
- UI 有可点击的语言切换条，未关联的页面不显示不存在的翻译页面入口。
- 旧站无需设置语言组，可继续按原构建方式工作；数据库迁移只新增表格。
- 本轮**没有**实现机器翻译、批量翻译工作流、子路径多语言站点、主题各栏目默认文案的完全国际化。四套现有商业主题的预设导航和空栏目提示部分仍是中文，正式英文站上线前需配置企业自己的导航和文案。

操作示例：

1. 在“我的网站”分别新建中文站和英文站，设置 `https://zh.example.com`、`https://en.example.com`。
2. 选择中文站 → 多语言管理 → 建立语言组，默认语言可选 `en`，并将当前站点登记为 `zh-CN`（若建组时默认语言不是当前站实际语言，请创建后在已建组界面使用对应语言站点；管理后台的建组快捷操作默认登记所选默认语言，操作前请校正）。
3. 将英文站加入该语言组，设置 `en`；在两个站各自建立真实对应页面。
4. 创建翻译组 `about-company`，分别选中两语言的页面，状态设为“已确认”。
5. 在两个站分别执行 Worker 静态构建，检查 HTML `<html lang=...>`、`rel=alternate` 和 `sitemap.xml`；正式发布仍需要独立审批。

本轮核心代码：`app/multilingual.py`、`app/builder.py`、`app/templates/workspace.html`、`app/static/workspace.js`，专项测试 `tests/test_multilingual_v815.py`。

## 一、系统入口

- 简洁管理后台：`http://localhost:8787/`
- 「构建与交付」：构建、预览、质量检查、提交审批、远程发布及回滚
- 「高级工具」→「任务与发布审批」：审核人对不同账号提交的申请进行审批，查看任务详情
- `http://localhost:8787/api/health`：核实运行版本与构建提交

### V8.14 新增实际功能（同时保留 V8.13 发布流程）

| 流程 | 位置 | 实际行为 |
|---|---|---|
| 发布前核对 | `GET /api/production/sites/{site}/preflight/{build}` | 必须构建 complete、有 ZIP、静态质量通过、迁移复核完成、另一账号审批通过 |
| 发起远程发布 | `POST /api/production/sites/{site}/deploy` | Owner 提交到共享 Worker 队列，返回 202 + 任务 ID；不在 Web 请求中传 ZIP |
| Worker 实际上传 | `app.job_runner` + `app.release_api.run_delivery` | 暂存 ZIP、比对 SHA256、校验远程文件清单、激活线上指针、再核对公开首页 |
| 历史版本回滚 | `POST /api/production/sites/{site}/rollback` | Owner 只能回滚本站指定目标的已记录版本，后台异步执行 |
| 发布进度/历史 | `GET /api/production/sites/{site}/delivery-status` | 返回任务、发布历史及目标是否配置；不暴露 URL 凭据 |
| 远程 Agent | `app.deploy_agent:app` | 新增 `staging` / `verify` / `activate` 事务式三阶段，不覆盖已发布目录 |

共享 Worker 的取消、重试、限额、幂等键及租约机制沿用 V8.12；**远程发布依赖在目标服务器部署新版本 Agent，旧版 Agent 不支持三阶段 API**。


## V8.14 原生 SFTP / S3 发布

- `SITEFORGE_DEPLOY_STAGING_TYPE` 和 `SITEFORGE_DEPLOY_PRODUCTION_TYPE` 支持 `agent`（兼容默认）、`sftp`、`s3`。
- 原生 SFTP：Worker 使用管理员挂载的私钥与严格 known_hosts；远程服务器需要支持原子 `posix_rename`；发布指针为 `current` 符号链接。
- 原生 S3：按版本前缀不可变保存文件，使用 S3 条件更新 `current.json`；必须搭配只读指针感知网关 `app.s3_gateway:app`，不能将 S3 裸网站端点视为原子上线。
- 目标 URL、SSH 主机、桶和密钥只能由服务器配置，不能由建站人员在浏览器随意填写；Worker 执行真实上传，Web 仅提交任务。
- 详见 [`deploy/native-release/README.md`](deploy/native-release/README.md)、`compose.publish-targets.example.yaml`、`compose.s3-gateway.example.yaml`。
- **约束**：本次对 SFTP 和 S3 的测试使用模拟文件系统与模拟 S3 兼容语义，尚未在实际远程服务器或 Docker 环境验收。

## 二、Docker 安装（Windows PowerShell）

```powershell
# 解压 V8.14 后进入项目根目录。请勿直接覆盖 V8.12 的数据卷。
docker run --rm -v "${PWD}:/project" -w /project python:3.12-slim python scripts/init_config.py
docker compose up -d --build
docker compose ps
```

推荐先用独立测试域名 / Docker volume。Web 默认只监听 `127.0.0.1:8787`。如果反向代理到外网，需要设置 HTTPS 和 `SITEFORGE_COOKIE_SECURE=true`，自行配置防火墙、TLS 与可信反向代理。

**PostgreSQL/Redis 测试配置**：`docker compose -f compose.enterprise.yaml up -d --build`。这只是配置与兼容层，不能视为分布式高可用验收通过。

## 三、远程发布如何配置？

1. 在**接收网站的独立服务器**上部署 `compose.release-agent.yaml`，把 Agent 的 `127.0.0.1:8790` 通过受控 HTTPS 反向代理转发为固定发布域名（如 `https://deploy.example.com`）。Agent 所在服务器必须保留持久化 `releases` 卷。
2. 在接收服务器设置 `SITEFORGE_DEPLOY_SECRET_REF=file:production_release`，把强随机密钥文件仅挂载到 Agent `/run/secrets/production_release`。可通过 `compose.agent-secrets.example.yaml` 作为私有 Compose 覆盖参考。
3. 在 SiteForge 管理服务器 `.env` 中设置 `SITEFORGE_DEPLOY_PRODUCTION_URL=https://deploy.example.com` 和 `SITEFORGE_DEPLOY_PRODUCTION_SECRET_REF=file:production_release`，将**同一生产密钥**只挂载到 Worker `/run/secrets/production_release`；通过 `compose.release-secrets.example.yaml` 添加私有只读挂载。不要把密钥写进网站数据库或前端 JavaScript。
4. Staging 使用**另一套服务器及独立密钥**，不要复用生产凭据。
5. 使用 Owner 账号选择已完成的构建，执行「检查发布条件」→「提交审批」，由**另一个具有审核权限的账号**批准后选择目标提交异步发布，回到任务列表等待确认。
6. 正式域名的 DNS/CDN、静态页面反向代理、询盘服务和 HTTPS 证书需单独配置并验证。**Agent 的 `/public/{site}/` 是自身提供的内容探针，不等于你公司的域名已经自动生效。**

生产系统不应在管理后台填入任意远程 URL：仅运维人员通过可信环境配置发布目标，且 `safe_http` 禁止访问回环、内网、云元数据与 DNS 重绑定目标。

### Agent 路由

- `POST /staging/{site}`：签名上传并生成不可变版本文件，不修改线上 current。
- `GET /sites/{site}/verify/{release}`：签名核对文件哈希、完整性、是否在线。
- `POST /sites/{site}/activate/{release}`：验证后原子切换 current 指针。
- `POST /sites/{site}/rollback/{release}`：校验、原子切换回旧版本。
- `GET /public/{site}/`：验证激活后网站首页实际可访问，Worker 会比对首页 SHA256。

## 四、运行回归

```bash
python -m pytest -q
python -m compileall -q app
bash scripts/check.sh
python scripts/verify_release.py
```

**现有环境验证**：本地 Python、JavaScript 与 HTTP 模拟发布 Agent 的测试。远端真实公网 HTTPS、断网后的最终一致性、Docker Engine、浏览器跨设备交互以及正式域名端到端发布都还需要运维实机验收。严禁把模拟 Agent 测试记录成外网部署通过。

## 五、限制及尚未实现

- 本轮新增 **原生 SFTP/S3 发布代码及只读 S3 指针网关**；真实 SSH/S3、CDN、DNS/HTTPS、原子切换在正式服务器上的验收仍未完成。
- Worker 取消发生在指针切换瞬间时可能形成“远程已经切换、任务记录尚未写入”的待复核状态；必须检查 Agent 的带签名版本清单并人工处理，不保证跨机器严格事务。
- 存在内容/SEO 警告时必须人工复核；系统不会自动保证真实站点 SEO 或询盘业务有效。
- Art Design Pro 官方完整工程尚未集成编译；企业级 PostgreSQL/Redis 高可用、SSO、容灾和完整生产安全审计待验收。
- P0–P4 尚存在复杂插件迁移、真实浏览器、生产 MySQL/TLS、独立设备设计深度等未关闭项。

参阅 [V8.14 原生发布配置](deploy/native-release/README.md)、[V8.14 验收报告](docs/V8_14_P5_ACCEPTANCE.md) 和 [V8.13 旧版发布验收](docs/V8_13_P5_ACCEPTANCE.md) 与 [V8.12 历史说明](docs/HISTORY_V8_12_README.md)。