合并远端并行的 worker unit 渲染实现

远端 798098e06 与本地 299544719 并行修复了同一问题（deploy 原文安装
unit 覆盖自定义路径）。合并采纳远端实现为准：python3 字面量渲染（含
模板占位路径存在性校验）、install_worker_systemd_units 参数化、Jenkins
双流水线暴露并透传 CONTROLLER/BGFILTER env 参数、guardrails 门禁——
其中流水线透传补上了本地版本刻意未覆盖的传输层缺口。保留本地独有的
readyz 派生修复、connect 重连与冷启动宽限、契约文档收口；删除本地
sed 渲染实现与合并产生的重复参数定义；decision-log 双条目并存。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/project-memory/shared-memory/decision-log.md

@@ -4426,3 +4426,10 @@
 - 平台差异（Windows 开发环境）：连接已关闭的 loopback 端口不回 RST 而是挂到 connect timeout，错误呈现为 `deadline_exceeded` 且 `is_connect` 为真；重连判定只看 connect 分类，不看错误码。生产 Linux 即时拒绝，呈现 `internal_error`。
 - 安全不变量测试：除配额 / 跨窗 / deadline 地板路径外，专项覆盖「TCP 已 accept、未回任何 HTTP 字节即断开 → 不得发起第二次连接」，以 mock listener 的 accept 计数证明父侧未重连。
 - 影响范围：`server-rs/crates/api-server/src/bgfilter_worker.rs`、`state.rs`、`editor_project.rs`、调度方案 §5.1/§7/§9.3/§11、数据契约 247-248 行、运维文档及各编辑器专题文档的旧禁令措辞统一改为「不重试已被 worker 接收的内部 RPC」。
+
+## 2026-07-23 生产 API 发布按实际路径渲染 worker systemd unit
+
+- 背景：Server-Provision 支持自定义 current link、API env 和角色 env，并在首次安装时渲染三个 worker unit；API deploy 为下发随 release 更新的 unit 又原样覆盖目标机配置，导致自定义路径在下一次发布时退回模板默认值。
+- 决策：`production-api-deploy.sh` 继续随 release 安装默认命名的 BgFilter、external-generation worker 和 controller unit，但安装前必须用本次部署参数渲染临时文件；新增 `--controller-env-file` 补齐 controller 专属 env 输入。release 内模板保持默认路径，供 provision 和 deploy 共同作为单一模板来源；自定义服务名仍由目标机自行管理，不强制覆盖。
+- 影响范围：`scripts/deploy/production-api-deploy.sh`、`scripts/check-production-api-deploy.mjs`、`jenkins/Jenkinsfile.production-api-deploy`、`jenkins/Jenkinsfile.production-full-build-and-deploy`、`scripts/check-production-ops-guardrails.mjs`、生产运维文档和 worker systemd 发布契约。
+- 验证方式：`bash -n scripts/deploy/production-api-deploy.sh`、`node --check scripts/check-production-api-deploy.mjs`、`npm run check:production-api-deploy`、`npm run check:production-ops`、`npm run check:encoding`、`git diff --check`。

docs/project-memory/shared-memory/pitfalls.md

@@ -3312,3 +3312,11 @@
 - 验证与回滚：重启后先跑真实 PR 的四个 job，再清理旧镜像。失败时先把 workflow `runs-on` 改回 `ubuntu-latest`，再恢复 runner config 备份并重启；不在 Git、共享文档或日志中记录 config 备份路径、注册信息或 token。
 - 重启边界：`docker restart --timeout 660` 只设置容器停止宽限，不能替代 Runner drain。rootless DinD supervisor 可能与 runner 同时停止内层 dockerd，使仍在收尾的 job 因连接关闭被标记失败；切换前必须同时确认 Gitea 没有 `in_progress` run 且内层 `docker ps` 为空。误触发时只重跑受影响的失败 job，不重跑已成功项。
 - 关联：`deploy/container/README.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`docs/project-memory/shared-memory/development-workflow.md`。
+
+## 生产 API 发布重装 worker unit 不能丢失自定义路径（2026-07-23）
+
+- 现象：Server-Provision 已按自定义 current link 和 env 路径安装 worker systemd unit，但下一次 API 发布后，worker 可能重新读取 `/opt/genarrative/current` 与 `/etc/genarrative/*.env`；默认路径仍有旧 release 时，服务 active 和部署成功都不能证明新二进制已运行。
+- 原因：发布包中的 BgFilter、external-generation worker 和 controller unit 是带默认路径的模板；deploy 若直接 `install` 原文件，会覆盖 provision 已渲染的目标机 unit。external-generation 专属 env 还是可选加载，错误路径可能不会阻止服务进入 active。
+- 处理：API deploy 安装三个 unit 前必须按本次 current、API env 和各角色 env 参数渲染临时文件，安装后保留 release 内原始模板不变；controller 自定义 env 由 `--controller-env-file` 显式传入。API Deploy 与 Full Job 必须同步暴露并透传 controller/BgFilter env，不能让流水线回退默认路径。自定义服务名表示沿用目标机自管 unit，不进入默认 unit 安装分支。
+- 验证：部署 guard 使用临时自定义绝对路径，直接读取实际安装目录中的三个 unit，核对 `WorkingDirectory`、`ExecStart`、共享 API env 与角色 env，不能只用 fake `systemctl is-active` 判绿。
+- 关联：`scripts/deploy/production-api-deploy.sh`、`scripts/check-production-api-deploy.mjs`、`scripts/jenkins-server-provision.sh`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。