sow publish

sow publish 将某个 Repository 的当前 Built Generation 交付到 sow.yml 的 targets: 中指定的 目标。目标已经绑定 Repository 与 Provider，因此命令不接受 --repo 或 --dist。

语法

sow publish TARGET [--abort | --rebind] [-C|--workdir DIR] [-T|--timeout DUR | -N|--no-wait] [--json]

TARGET 必须是已配置的 filesystem 或 r2 发布目标。--abort 与 --rebind 互斥。

发布协议

交付前，SOW 要求存在已完成的 Built Generation，并验证公开树与冻结 Generation Manifest 精确 一致；然后按以下顺序规划并写入对象：

1. 不可变包体；
2. 校验和寻址元数据；
3. 可变协议指针；
4. 验证并持久化 Checkpoint。

精确对象集合、Receipt、阶段与 commit intent 都会落盘，确保中断后可以对账恢复。目标已经位于 当前 Generation 时，重复发布是幂等空操作。

sow publish local
published demo generation=00000000000000000005 to local (filesystem): phase=grace objects=14
sow publish local
publication demo generation=00000000000000000005 to local is already current (noop)

重绑定可变目标配置

首次成功 publish 会持久绑定 Repository、存储命名空间与 Target Identity。之后配置发生漂移时， SOW 会拒绝静默接受。只有诊断信息明确提示 --rebind，并且你已经复核变更后，才执行：

sow publish prod --rebind

如果改的是 targets: Map Key，请使用新目标名。Rebind 保留 active attempt 与 checkpoint identity， 并追加不可变、由操作者确认的 binding revision。

Rebind 与发布使用同一组 Workspace/Repository 锁，并在数据库事务内重新核对不可变字段；它可以 继续前滚 active commit-intent attempt。Target Maintenance 未完成时禁止改变 TTL；filesystem 正在进行 conditional-delete 维护时禁止改变 public_endpoint。首次绑定必须运行普通 publish， 不能使用 --rebind。

Abort 与恢复

--abort 只允许在持久 commit intent 之前使用。SOW 会对账已经创建的对象，保留后续安全判断所需 证据，并在不继续复制或删除远端对象的前提下放弃本次尝试。

写入 commit intent 后只能前向恢复：重新运行 sow publish TARGET，不能使用 --abort。

公共可见性校验

Provider 存储写入成功还不够：写入 Checkpoint 之前，发布流程还要校验 canonical public_endpoint。HTTP(S) 目标以普通 GET 为最终权威；no-cache Probe 只能促进 Revalidation， 必须由之后的普通 GET 才能通过。陈旧内容与缺失对象按 max_cache_ttl 重试；408、425、429 与 5xx 使用较短的有界重试窗口。等待 Header 与 Body 空闲进度分别计时；响应超长时失败关闭。

Filesystem 可使用 file:// 或 HTTP(S) 公共端点。执行条件删除时，file:// 需要精确文件身份 缺失，HTTP(S) 则需要 canonical 404/410。R2 必须使用 HTTP(S) 公共端点；R2 Target GC 仍然 只报告候选，不执行远端删除。

安全边界

• SOW 只发布到配置目标，不接受任意目标路径。
• 尚未构建的 Desired 变化不会进入发布。dirty Repository 因而可以发布上一个完整 Built Generation；如果目标必须反映当前 Desired 状态，应先运行 build。
• 布局迁移与相互矛盾的恢复证据会阻止发布；可裁决的未完成 Dist 操作会在选择源 Generation 之前恢复。
• 对象顺序保证包管理器指针不会引用尚不存在的内容。
• 发布命令不负责外部 Web Server、Bucket Policy、DNS 路由或缓存配置。

退出行为

参见

• sow status 与 sow check —— 判断当前 Built Generation 是否正是准备交付的版本
• sow gc —— 保守的目标维护
• sow.yml 发布目标 —— Provider 配置
• 发布模型 —— 阶段、Receipt、恢复与 Cache Grace