qinglong/docs/adr/ADR-0231-in-process-worker-ingress-runtime-capability-port.md

ADR-0231：Worker ingress 复用 control 进程并注入 runtime capability port

• 状态：Accepted
• 日期：2026-07-30
• 关联 RFC：QL-RFC-0001 D-02、D-57、D-104、D-118、D-214、D-215
• 关联 ADR：ADR-0058、ADR-0059、ADR-0108—0110、ADR-0119、ADR-0230

背景

Worker transport、mTLS listener、认证、Session、attestation、offer、activation、 Secret delivery、Artifact、completion 和 lease-control contract 已分别存在，但正式 cluster-control process 只启动用户 API listener。Worker ingress 只能从测试或外部 caller 手工组合，因此 Remote Worker 无法通过 production deployment 接入。

直接让 ql3_worker_ingress Pool 构造 completion/lease adapter 虽会在数据库 ACL 处失败关闭，却模糊了能力所有权；另起 sidecar 与内部 HTTP/Unix RPC 又会增加进程 RSS、socket、认证、shutdown 和部署故障域。对可能运行在小型设备上的统一产品， Edge/Standalone 也不能因为 Cluster 功能而加载 S3 SDK 或读取 Worker Secret。

决策

1. 使用同进程 capability port，不建立内部 RPC

bootstrapClusterControlRuntime 在 runtime Pool readiness 之后构造冻结的 ClusterWorkerRuntimePort。它只公开：

• offer claim；
• starting/running/start-failure ACK；
• 可选 Secret delivery；
• Artifact upload；
• completion；
• lease renew/stop。

port 不公开 Pool、SQL client 或 repository。production composition 把该对象注入 Worker admission pipeline；HTTPS transport 不 import runtime PostgreSQL adapter。

runtime Pool 继续拥有所有 Run/Attempt/Lease mutation。Worker ingress 的独立 Pool 只拥有 credential resolve、Session、attestation 与 write-only security audit。 @qinglong/cluster-postgres/worker-ingress 不再导出 completion 和 lease-control mutation adapter。

2. 一个 control 进程、两个 listener、两个最小权限 Pool

既有 ql3-cluster-control binary 同时拥有：

• 5800：control API/probe listener；
• 5801：TLS 1.3 + mandatory client certificate 的 Worker listener。

不新增 workspace package、sidecar、内部 listener、timer、watcher、queue 或 IPC。 Worker ingress 默认最多 4 个 PostgreSQL 连接，control runtime Pool 继续使用原上限。 Worker listener 的启动属于 application lifecycle：readiness/recovery 完成后启动， 失败时 production activation 失败关闭；停止时先撤 admission，再关闭 Worker Pool 与 listener。

3. Artifact provider 只在启用 Worker ingress 后加载

Worker completion 必须先有 immutable、digest-authenticated Artifact evidence。 启用 Worker ingress 时配置必须提供受限 S3 bucket 与 region，可选 private endpoint、 path style、expected owner 和 KMS。S3 client/binding 由 process 动态 import，默认 control、Edge、Standalone 和 disabled Worker ingress 不加载 AWS SDK，也不读取其 配置。

S3 adapter 仍只有 s3ArtifactStore.ts 一个第三方 provider importer。process 关闭时 无论启动或 emit 是否失败，都会停止已启动 application 并销毁 S3 client；清理失败 不能覆盖更早的根错误。

Secret provider 保持可选注入。没有 provider 时 /secrets 稳定返回不可用，不会 回退到环境变量、数据库明文或空值；不含 Secret reference 的执行仍可使用其余完整 链路。

4. 部署显式分离 Secret 与端口

Kustomize base 增加 worker-mtls 5801 Service/container port，以及独立 ql3-cluster-worker-ingress Secret：

• Worker credential pepper；
• server key/certificate 与 Worker client CA；
• Worker ingress PostgreSQL URL/CA；
• Artifact bucket/provider 配置。

CloudNativePG overlay 删除通用 Worker DSN，改用 ql3-postgres-worker-ingress-auth 与 ql3-postgres-ca。control Pod 不取得 migration/admin/package authority，Worker listener 不取得 runtime password。

不采用的方案

独立 Worker ingress sidecar

拒绝作为当前默认。它需要定义并保护第二套内部 wire protocol，增加每 Pod 的 Node 进程、RSS、socket、健康检查和 shutdown 顺序，而当前 modular-monolith 权限边界可由 对象 capability 与独立数据库角色完整表达。未来只有在独立扩缩容或强进程隔离有 实测收益时才重新评审。

给 ql3_worker_ingress 增加 Run mutation GRANT

拒绝。外部 Worker transport 被攻破时会直接获得控制面写权限，也绕过 runtime recovery/fencing owner。数据库 ACL 与代码 entrypoint 都必须拒绝这条捷径。

为 Worker ingress 新拆 workspace package

拒绝。它与现有 cluster-control 共享部署、版本、依赖与生命周期；拆出单用途薄包会 回到 D-207 已拒绝的碎片化。当前仍为 20 个 workspace package。

在所有 Profile 启动时加载 S3

拒绝。Artifact provider 只属于启用的 Cluster Worker ingress。路由设备上的 Edge/Standalone 不应承担其模块、配置、credential chain 或空闲连接成本。

当前验证

1. cluster-control 全量 150 项为 148 pass、2 条外部服务条件 skip、0 fail；新增 bootstrap/production/process/config 测试证明 capability port 不暴露 Pool、Worker lifecycle 幂等启停、缺 runtime port 失败关闭、Artifact binding 惰性创建与销毁；
2. cluster-postgres 全量 238 项为 237 pass、1 条真库条件 skip、0 fail； entrypoint 测试证明 Worker ingress 无 Secret/completion/lease mutation adapter；
3. deployment audit 无 findings，base/CloudNativePG 分离 runtime 与 Worker credential、CA、mTLS material，并只暴露 5800/5801 两个命名端口；
4. Linux arm64 Node 24.18.0 在 512 MiB、2 CPU、256 PID、零 swap、非 root、只读 root/workspace 下通过：memory.peak=41431040 bytes、模块加载 RSS 增量 24195072 bytes、零 OOM/oom_kill；
5. QL3_HA_SKIP_IMAGE_PULL=true 的 PostgreSQL 18.4 arm64 HA 门再次通过 physical streaming、remote_apply、timeline 1→2、旧主 fencing、 pg_rewind 只读同步重入、两个 fresh control replica 与全部领域 gate，总 passed=true；
6. workspace 保持 20 包，没有新增 migration、表、生产依赖、timer、watcher、 queue、sidecar 或内部 RPC。

尚未关闭

1. Cluster Secret material 的正式 provider 与 rotation/retention 产品入口；当前 Secret-bearing Remote Worker task 继续失败关闭；
2. Remote Worker expiry/lost/retry 的 production lifecycle、部署启动装配与容量 telemetry；
3. 真实 Kubernetes 多 Pod Worker Session replacement、网络分区、operator/proxy、 STONITH、S3 outage/backpressure 与独立扩缩容证据。