qinglong/docs/adr/ADR-0194-replay-safe-local-deployment-preparation.md

# ADR-0194：可重放的本机部署准备与 Supervisor 描述符

- 状态：Accepted（systemd、OpenRC、Compose 部署准备器与真实 fresh setup
  已实现）
- 日期：2026-07-29
- 关联 RFC：QL-RFC-0001 D-05、D-06、D-40、D-62、D-175、D-183、
  D-184
- 关联 ADR：ADR-0063、ADR-0066、ADR-0086、ADR-0088、ADR-0185、
  ADR-0193

## 背景

ADR-0193 已关闭 fresh 数据库与常驻 application 的语义缺口，但操作员仍需手工创建
八个私有目录、复制两份 JSON、选择资源上限并自行拼接 supervisor 命令。手工步骤
容易产生宽权限目录、host/container 路径混用、可变镜像 tag、错误的停止信号或把
初始化命令误当成常驻进程。

直接在 CLI 中调用 `systemctl enable`、`rc-update` 或 `docker compose up` 又会引入
宿主机全局副作用。服务管理器调用没有与 SQLite mutation 相同的事务和精确重放
语义，也会迫使测试以 root 权限修改真实系统状态。

## 决策

### 1. 部署准备仍属于现有短生命周期 Owner CLI

`@qinglong/local-owner-cli/local-deployment` 与 `ql3-local-deploy` 负责部署文件
准备，不新增 workspace package。入口只接受：

```text
ql3-local-deploy prepare --command-file /absolute/private-command.json
```

command file 继续复用 `@qinglong/local-command-file` 的 canonical、当前 UID、
`0600`、no-follow 协议。命令必须是 exact
`local.deployment.prepare`，固定 Profile、instance、deployment root、D-183
mutation identity 和三种 service 之一。

实现保留在同一个 package 中，并按 contract validation、文件发布事务、
descriptor rendering 与薄 orchestration 四个内部模块组织。内部模块不是独立
发布或依赖边界，避免为了文件数量继续拆 workspace package，也避免部署协议、
文件事务和 supervisor 模板重新堆积为单个巨型源文件。

### 2. 文件事务无覆盖且可恢复

准备器以当前 POSIX UID/GID 创建并复核固定的 `0700` deployment、pepper、
backup、receipt、Artifact、Plugin staging/activation 与 service 目录。随后：

1. 复用 D-183 `executeLocalSetup` 收敛 migration 与 key authority；
2. 生成 exact `qinglong/local-application-process@v2` fresh 配置；
3. 生成 systemd、OpenRC 或 Compose 中唯一一种描述符；
4. 使用同目录 deterministic stage、完整写入、`fsync`、hard-link no-replace、
   directory `fsync` 和 stage cleanup 发布；
5. 已有目标只能在 owner、mode、link count、size 和完整字节全部一致时返回
   `existing`，否则失败关闭。

在执行 setup 前先检查已有 config/descriptor 与遗留 stage；已存在内容漂移不会先
改变数据库或密钥。崩溃发生在 stage、link 或 cleanup 窗口时，同一命令可以继续
收敛；不得生成新 mutation ID 来重试。

### 3. 三种描述符是显式 Profile contract

systemd/OpenRC 只接受 canonical regular Node executable 与 application entrypoint；
文件必须由 root 或当前 UID 拥有且不能 group/world writable。描述符固定
`SIGTERM`、30 秒停止预算、`0077` umask 和前台监督：

- Edge：128 MiB、64 PID、1024 fd；
- Standalone：256 MiB、256 PID、4096 fd。

Compose 只接受完整 `@sha256` image reference，并固定：

- numeric current UID:GID；
- read-only root filesystem；
- bind mount 唯一 deployment root；
- `network_mode: none`（fresh 默认 AI excluded）；
- drop all capabilities 与 `no-new-privileges`；
- 16 MiB noexec tmpfs、30 秒停止预算及同一 Profile memory/PID 上限。

container application config 使用 `/var/lib/qinglong3` 内部路径；host setup 仍对
bind source 执行。两套路径不能混写。

若当前 UID 为 0，命令必须显式写
`allowRootService: true`；非 root 必须为 `false`。这只是明确风险，不把 root
执行宣传为推荐配置。

### 4. 准备不等于系统启用

准备器不执行以下行为：

- 不复制文件到 `/etc`；
- 不调用 service manager 或 Docker daemon；
- 不拉取或构建镜像；
- 不签发、claim 或恢复 Owner；
- 不启用 AI、网络、Plugin online fetch；
- 不修改已存在的不同配置。

operator 必须检查 bundle，再显式安装和启动。发布镜像、系统包、签名、升级回滚与
真机 supervisor evidence 具有独立供应链和权限责任。

## 验收

- systemd fresh deployment 首次 `prepared`、原命令 `existing`；
- 八个目录均为当前 UID `0700`，application/unit 为 `0600`；
- 真实 SQLite `integrity_check=ok`；
- OpenRC 使用 `supervise-daemon`、TERM/KILL 有界停止和 `0077`；
- Compose 使用 digest image、read-only、network none、cap-drop、no-new-
  privileges 与 Profile 上限；
- command widening、mutable tag、root 未确认、权限或内容漂移均拒绝；
- CLI stdout/stderr 不包含路径、image、digest、material、token 或 secret；
- `local-owner-cli` package test 全量通过。

## 未包含

- 正式可发布的本机 OCI image 与 SBOM/provenance/signature；
- deb/rpm/apk/opkg 等系统包；
- `systemctl`、OpenRC、Compose 的真实安装/升级/回滚控制器；
- systemd/OpenRC 多发行版、rootless container 与 Linux x64/arm64 live matrix；
- 路由器断电、ENOSPC、只读文件系统与闪存写放大报告。