open-source/qinglong
1
0
Fork 0
mirror of https://github.com/whyour/qinglong.git synced 2026-09-20 16:07:11 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
ffa4b4e7cb65ceaebe847e2c5eac18d1c624502b
qinglong/docs/adr/ADR-0121-production-worker-headless-execution-composition.md
T

7.4 KiB
Raw Blame History

ADR-0121：Production Worker Headless Execution Composition

  • 状态：Accepted（执行平面具体装配已实现；Session heartbeat、证书/credential 产品流程、部署入口与 retention 仍为发布 Gate）
  • 日期：2026-07-23
  • 关联 RFC：QL-RFC-0001 D-05、D-06、D-14、D-85、D-108、D-111、D-114、D-115、D-116、D-120
  • 关联 ADR：ADR-0061、ADR-0087、ADR-0110–ADR-0120

ADR-0122 当前增量：@qinglong/worker-runtime/product 已在不新增 package 的前提下接入 exact Session wire、共享 Agent、journal-derived capacity 与单 cadence shutdown；本 ADR 下方 98/98、294 sources 是 D-120 接受时快照。当前累计证据为 Worker 122/122、runtime-core 159/159、Cluster Control 129 pass/2 external skip、23 importer/303 TypeScript sources。credential material provider 已由 ADR-0123 实现， 远端 recovery 和设备证据仍未完成。

背景

ADR-0110 至 ADR-0118 已分别完成 Offer、单一 inbox、Activation、Secret、日志、POSIX Executor、 Artifact/completion 与 Lease control，但都只提供默认关闭的原语。继续由最终部署入口逐个手工实例化会 产生多个 HTTPS Agent、不同 storage root、遗漏 completion-first supervision 或错误 shutdown 顺序。

原 WorkerRemoteExecutionHeadlessLifecycle.stop() 还会直接 Abort Pull 并释放 journal owner。如果 Pull 已经取得 Offer，或本地进程仍在运行，部署进程可能在没有 durable drain 证明时退出；这不是可接受的 production shutdown。

决策

1. 不新增 package，只开放显式 production subpath

具体执行平面放在 @qinglong/worker-runtime/production。默认 package 根入口继续只暴露证书 store 与 续期原语，不加载 runtime-core remote execution、proper-lockfile、HTTPS client 或 POSIX Executor。

enabled=false 在读取 Profile、路径、credential、Session 或创建对象前返回。启用只接受 worker Profile，并要求三个互不相同、互不嵌套、非文件系统根的绝对 storage authority：

  • Offer/inbox journal；
  • 本地日志 spool；
  • completion receipt。

Edge 默认 4 条 startup/supervision page、64 条 journal、2 秒 cadence、4 MiB Attempt/32 MiB reserve； Node 默认 16/32 条 page、256 条 journal、500 ms cadence、64 MiB Attempt/256 MiB reserve。所有值仍受 1–64 page、1024 journal、100 ms–60 s cadence 等硬上限约束，不能由部署无限放大。

2. 一个 stack 装配全部现有具体能力

production factory 只使用现有 package 和 public subpath，装配：

  1. 单 owner WorkerRemoteOfferFileJournal；
  2. 单一 WorkerIngressHttpsClient 与 keep-alive Agent；
  3. Offer、Activation、Secret、Artifact upload、Completion 与 Lease-control adapters；
  4. Secret-before-Artifact materializer 与 Edge/Node 文件日志 policy；
  5. reviewed launcher 的 POSIX Executor、同一 receipt root 和 LocalProcessController；
  6. completion-first control coordinator、Processor 与 headless lifecycle。

stack 不导入 cluster-control、PostgreSQL 或 legacy root，也不创建第二个 Agent、数据库连接、per-Run timer 或新 schema。credential provider 与 Session lifecycle 由更外层注入，因为证书签发、ql3w credential 恢复和 heartbeat 是独立部署 authority。

3. 返回 active 前必须完成有界 startup reconciliation

显式启动先取得 journal owner，再按配置 page 完整扫描历史 inbox。只有得到 reconciled 才创建一个 unref 全局 cadence；recovery_required 或超过由 journal hard cap 推导的最大 tick 数立即清理并拒绝 启动。启动扫描期间不 Pull 新任务。

定时 tick 继续使用 lifecycle 内部 coalescing；异常只进入低敏 diagnostic，不重叠创建另一轮。每轮先 completion/lease supervision，再在 Session available 时最多 Pull 并处理一个 Offer。

4. Draining 必须在释放 owner 前关闭 Pull 竞态

lifecycle 增加显式 beginDrain()：

  1. 原子标记本地 draining；
  2. Abort 在途 Pull 并等待其结束；
  3. 替换请求 AbortController，但继续持有 journal owner；
  4. 后续 tick 只做既有执行监督，永不 Pull。

production stop 随后要求外层 Session.beginDrain() 已耐久关闭新工作，并复验当前 Session 不再 available。它在固定 1 秒–10 分钟总预算内重复 completion-first supervision 和最多 64 条一页的 journal 检查。只有全部记录进入 start_failure_acknowledged|completion_acknowledged，才按 cadence → lifecycle/owner → Offer transport → shared Agent 顺序关闭。

drain timeout 返回 drain_timed_out，保留 owner 并继续 draining cadence，允许稍后重试；durable recovery_required 返回同名状态并保留 authority，禁止自动假装停止。Session drain 调用失败或不能 证明离开 available 也不得释放 owner。shutdown 等待 timer 保持 ref，防止进程在证明完成前自然退出； 只有常驻 cadence 使用 unref。

5. 本 ADR 不开放完整 Worker 发布

该入口完成的是 execution plane，而不是完整 Worker Profile。发布仍要求外层提供并验证：

  • Worker Session register/heartbeat/drain/offline lifecycle；
  • certificate enrollment/renewal 与 ql3w credential provision/recovery；
  • deployment config、私有路径创建、告警和进程 shutdown budget；
  • 本地 spool retention/delete 与对象存储 temporary lifecycle；
  • 固定 Edge/Node x64/arm64、休眠、断网、断电和磁盘压力证据。

缺少任一项时部署入口继续默认关闭，不能把注入式测试 provider 当作产品配置。

被否决的替代方案

  1. 新建 worker-application package：没有新依赖或发布责任，违反 D-85。
  2. 每个 client 自建 Agent：重复 TLS credential authority、socket 与关闭状态。
  3. stop 直接释放 journal：运行进程和丢响应 Offer 会失去唯一监督 owner。
  4. Session drain 后仍允许 Pull：控制面和本地状态存在竞态，可能在 shutdown 接收新任务。
  5. drain timeout 后强制 close：把“预算耗尽”伪造成“副作用已停止”。
  6. 嵌套 journal/log/receipt root：扩大扫描、清理和路径 capability 的误伤范围。
  7. production 子入口从 package 根导出：让证书-only steady state eager-load 网络与文件锁依赖。

验收证据

  1. lifecycle 测试证明 beginDrain Abort Pull、draining tick 不再 Pull、最终 stop 前 owner 不释放。
  2. production 测试证明 disabled 零 option access、错误 Profile/重叠路径在文件系统前拒绝、空 execution plane 真实取得并释放 owner、Session drain 失败保持可重试。
  3. 独立进程证明 package 根不加载 journal/proper-lockfile，只有 /production 加载执行图，且该入口 不加载任何 ql3-cluster-*。
  4. Worker Runtime 98/98 通过，包含显式 enabled factory gate 与两个真实 TLS 1.3 mTLS 回环集成； 严格类型检查通过。
  5. workspace 仍为 23 个 importer、294 个 TypeScript source file，dependency/source audit findings=[]，没有新增依赖、schema、migration、数据库连接或 per-Run timer。
  6. 23 package clean build 与全量测试通过；六种本机制品再次通过真实 pack/offline install/import， 最大仍为 2,457,770 bytes、409 files、72 loaded modules，当前抽样 RSS delta 最大 12,566,528 bytes，且均不安装 @aws-sdk/*。
Reference in New Issue View Git Blame Copy Permalink