cms-SiteForge/deploy/native-release/README.md

V8.14 原生发布目标（SFTP / S3）运行配置

本文件包含可以部署的代码与操作步骤。真实服务器、证书、IAM、DNS 和缓存策略必须由部署人员配置并验证。

运行方式

默认仍采用原 V8.13 HTTPS 发布 Agent，不修改已有目标配置即可继续使用。每个目标分别设定 SITEFORGE_DEPLOY_{STAGING|PRODUCTION}_TYPE 为 agent、sftp 或 s3。

可选适配器及依赖版本已纳入 requirements.lock 和 Docker 镜像；如果镜像构建不能联网获取依赖，不会自动降级成无校验发布。

SFTP

1. 创建专用无 shell/受限权限的发布账号，仅允许访问专属发布根目录；安装并配置支持 OpenSSH posix-rename@openssh.com 扩展的 SFTP 服务器。Worker 不执行任意远程 shell 命令。
2. 在管理服务器上由管理员手动核对目标主机 SSH 公钥指纹，保存 secrets/publish_known_hosts。不可使用 AutoAddPolicy 或 StrictHostKeyChecking=no。
3. 为 Worker 安装只读私钥文件 secrets/publish_key；强烈建议独立测试/生产密钥及不同账号，挂载到 /run/secrets/siteforge_publish_key。
4. 设置目标 HOST、PORT、USERNAME、REMOTE_ROOT、KNOWN_HOSTS_FILE、SSH_KEY_FILE、PUBLIC_URL；PUBLIC_URL 必须是真实 HTTPS 站点首页地址（如 https://staging.example.com/），必须映射到该站点 current 目录。
5. 执行 docker compose -f compose.yaml -f compose.publish-targets.example.yaml up -d --build。示例同时演示 Staging SFTP、Production S3，实际部署时应依安全需求拆分环境和变量。
6. 执行两次不同版本的审批发布、模拟校验失败与回滚；确认当前站点始终是已经完整验证的版本。

SFTP 文件布局：REMOTE_ROOT/{site}/releases/{sha256[:20]}/...，current -> releases/{sha256[:20]}。生成临时符号链接后使用原子 posix_rename 切换；若目标服务器不支持该扩展，则拒绝部署，不会使用有中间空窗的 fallback。

当前原生 SFTP 使用不带口令交互的 SSH 私钥文件。如果组织要求硬件密钥、交互式证书或私钥密码，需要在运维方案中对接安全代理，不要把口令写入前端或数据库。

S3 / S3-compatible

1. 创建独立存储桶或隔离前缀，赋予发布 Worker 最小必要的对象读写权限；站点网关使用不同的、只读 IAM 身份（建议使用实例角色/工作负载身份，不要硬编码 Access Key）。
2. 设置 SITEFORGE_DEPLOY_PRODUCTION_TYPE=s3、BUCKET、REGION、PREFIX、POINTER_AWARE=1、PUBLIC_URL。可选 ENDPOINT_URL 必须是 HTTPS 根地址。
3. 发布会上传不可变 sites/{site}/releases/{digest}/ 对象，对每个文件进行 SHA256 复核；最后条件更新 sites/{site}/current.json。并发指针修改会被 S3 ETag/If-Match 限制阻断。
4. 必须部署指针感知网站网关 app.s3_gateway:app（示例 compose.s3-gateway.example.yaml），让 https://web.example.com/{site}/ 根据 current.json 读取正确版本。不能直接把裸 S3 Static Website Hosting 端点当作已经实现原子切换。
5. 网关示例为读路径提供 no-cache 和安全路径验证。对 CDN 的改写规则、主站根目录映射、缓存失效与回滚速度，必须在真实域名上验收。S3-compatible 需要支持条件写入；不支持的供应商不得声明原子发布。

发布安全门禁

• 构建状态必须是 complete，ZIP 路径必须处于系统归档根目录，静态质量和迁移审计满足要求。
• 由独立审批人批准的版本才能部署；网页只提交异步任务，发布由 Worker 执行。
• 上传/完整性校验失败不得改变当前发布指针；上线后首页内容哈希不匹配会尝试切换回旧版本。
• 当前系统仍不保证 Worker 被强制杀死、网络分区发生在指针切换瞬间时具有跨进程数据库+远程站点的严格分布式事务；应当增加带审计的 reconciliation 机制后才能视为生产最终验收通过。

测试和运维验收

本地测试：python -m pytest -q tests/test_release_native_v814.py tests/test_release_v813.py。

生产验收必须测试：凭据错误、SSH 主机密钥变化、上传中断、哈希错误、审批撤销、重复任务、目标网关故障、回滚、旧版本路径、500/超时、CDN 缓存以及 API 日志中无凭据泄漏。

S3 网站独立域名的反向代理（必做）

本项目生成的静态网站可能使用 /products/、/about/ 等根路径链接。示例网关的内部路由是 /{site}/products/。正式域名必须在反向代理层把根路径映射到正确的站点前缀，不能直接将网关根目录暴露为某个企业网站。

以下仅是 Nginx 的 HTTP 内网转发结构示例，真实外网必须先配置受信 HTTPS 证书和正确的 DNS：

server {
    listen 127.0.0.1:8088;
    server_name www.example.com;
    location / {
        proxy_set_header Host $host;
        proxy_pass http://127.0.0.1:8791/my_site_id/;
    }
}

这样 https://www.example.com/products/ 才会被反代为网关的 /my_site_id/products/。公网 443/TLS、缓存层和域名验证需由实际反向代理负责，不要原样复制演示域名到生产环境。

针对每个独立网站设置不同的 server_name、站点 ID 和相应的 PUBLIC_URL。使用 CDN 时，对根路径 HTML、current.json 的旧版本缓存必须进行专项验证；无明确缓存失效机制前使用 no-cache 更安全。