浅念
601451f22b
Overlay ~150 upstream items onto our V8.12 base, preserving trade-pro
theme, registry tests, and design docs. Re-applied our patch set
(discovery/env_for/blocks.css/type-mapping/theme_color/frontend entries,
test_theme_pro_v3 mods) — all anchors survived upstream evolution.
New platform enhancement (fixes upgrade-introduced regression):
multilingual.site_locale now honors settings_json.locale, plus
PUT /api/i18n/sites/{id}/locale — standalone English sites get
<html lang='en'> under the V8.15 locale-rewrite pipeline.
compose: adopt V8.21.3 (image 8.21.3-dev.1, /api/ready probes, MySQL/S3
env) with project name pinned to siteforge-v8-10 (data volumes).
Tests: 356 passed / 11 failed — all 11 confirmed pre-existing in
pristine V8.21.3 on this host (10 upstream Windows env + our build test
now green after locale fix). Patch registry updated in plan doc.
Co-Authored-By: Claude Code <noreply@anthropic.com>
65 lines
5.5 KiB
Markdown
65 lines
5.5 KiB
Markdown
# 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：
|
||
|
||
```nginx
|
||
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` 更安全。
|