mirror of
https://github.com/whyour/qinglong.git
synced 2026-09-20 16:07:11 +08:00
136 lines
6.6 KiB
Markdown
136 lines
6.6 KiB
Markdown
# 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 与独立扩缩容证据。
|