qinglong/docs/adr/ADR-0418-explicit-cluster-copilot-mcp-host-deployment.md

# ADR-0418：显式 Cluster Copilot MCP Host 部署与资源边界

- 状态：Accepted
- 日期：2026-08-16
- 关联 RFC：QL-RFC-0001 D-326、Phase 2

## 背景

D-325 提供了独立 `ql3-copilot-mcp` stdio 进程，但只存在 binary 并不能证明用户可以安全部署它。若把 stdio server 直接包装成 Kubernetes Deployment/Service，Pod 没有拥有其 stdin/stdout 的 MCP host session，既不可达又长期携带 API credential；若让用户随意拼 `docker run`，则容易使用 mutable tag、默认网络、root、可写文件系统、无限资源或把 credential 写入环境。Cluster Admin 镜像的默认入口已经是统一产品 façade，但 OCI layout 审计仍错误期待旧 recovery binary，模拟证据不能约束真实镜像。

QingLong 的部署跨度还要求明确区分：Edge/Standalone 小设备不应安装 Cluster Admin/MCP 依赖；Cluster MCP host 本身也要支持资源受限的运维终端与较高并发的专用节点，而不能靠隐藏队列或无限容器配额吸收差异。

## 决策

1. `ql3-cluster-admin` 产品 façade 增加静态 `copilot-mcp` 命令，仍用当前 Node executable、same-image canonical target、`shell=false` 和 inherited stdio；不通过 shell、动态 package resolution 或 entrypoint override 启动 MCP。
2. `ql3-copilot-mcp --check --config ...` 在不启动 MCP transport 的情况下完整验证 owner-private MCP/client/credential/CA authority，并只发一个不带认证的 `GET /readyz`。成功结果仅包含 transport、ready、配置/credential 有效性、并发上限和固定请求语义；不返回 endpoint、DNS、路径、credential、Project 或 Cluster identity。not-ready 退出 69，异常仍只输出低敏失败事实。
3. CLI 接受可选 `--concurrency-ceiling=1..16`。配置的 `maxConcurrentRequests` 高于外部部署 ceiling 时在 listener、stdio server 和网络 probe 前失败关闭。该 ceiling 不改变 D-325 的即时 busy/no-queue 语义，只防止私有配置越过容器资源档位。
4. 提供唯一受审 host-side Docker stdio launcher。它只接受 `check|serve` 和四个非 secret 环境值：immutable Admin image digest、canonical private projection root、专用 Docker network 名和 `compact|standard|dense` resource class。credential value 不得进入 argv、environment、host adapter 或 image。
5. 三档固定为：compact `192 MiB/0.25 CPU/32 PID/concurrency 1`，standard `512 MiB/1 CPU/64 PID/concurrency 4`，dense `1 GiB/2 CPU/96 PID/concurrency 16`。launcher 固定 `--pull never --init --read-only --cap-drop ALL --security-opt no-new-privileges --user 10001:10001`，只读挂载一个私有目录，不挂载 Docker socket、Kubernetes token、数据库 credential 或可写目录。
6. launcher 拒绝 mutable/tag-only image、非 canonical/含分隔歧义的 private root、隐式或 `bridge|default|host|none` 网络和未知资源档。专用 Docker network 只提供命名隔离；生产 host firewall 仍必须把 egress 限制到 DNS 与 exact Cluster API destination。
7. stdio MCP 由外部 MCP host 父进程启动，不新增 Kubernetes Deployment、Service、Ingress、RBAC、ServiceAccount、sidecar、health timer 或 restart controller。Cluster AI component 继续只拥有 server-side Copilot composition；二者不能合并。
8. Admin image 继续独立发布；本 Gate 不再拆第 19 个 package 或复制 MCP runtime。镜像 metadata 改为同时描述 cluster operations 与 bounded stdio MCP，OCI layout 审计必须期待 Dockerfile 的真实 product façade entrypoint，而非历史 recovery binary。
9. Edge/Standalone、Local MCP、Cluster Control、Cluster AI 和 shared Kubernetes operations 均不得引用 host launcher。路由设备默认制品与依赖闭包保持不变；需要本机 MCP 时仍只使用独立 `@qinglong/local-mcp-server` Profile。

## 不选择

- **把 stdio MCP 作为独立 Kubernetes Deployment/Service**：没有父 host session，网络 Service 也不能把 MCP stdio 变成 HTTP；会留下不可达的长期 credential Pod。
- **在 Cluster Control/AI Pod 增加 MCP sidecar**：混淆 server-side Tool/Model authority 与 operator API credential，扩大常驻资源和故障域。
- **允许任意 Docker flags 或 mutable tag**：无法证明镜像、身份、挂载、网络和资源边界。
- **为 launcher 新建 workspace package**：部署 adapter 没有新的领域模型或 consumer closure，会重新制造过细包并突破 18-package hard cap。
- **把 resource class 只写进文档**：私有 config 可静默扩大并发，容器内存上限无法成为可执行契约。
- **在 MCP 进程增加轮询 health timer**：引入常驻网络负载和隐藏生命周期；一次性 check 与 host-owned restart 足够。

## 验收

1. 产品 catalog/help/delegation 覆盖八个 remote client 与 `copilot-mcp`，并证明 target 位于同一安装、stdio 原样继承、signal 可收敛。
2. TLS 1.3 preflight 覆盖 config/credential validation、无 Authorization 的 exact `/readyz`、ready/not-ready/transport failure、并发 ceiling 和低敏输出。
3. launcher 测试以假 Docker 捕获完整 argv，证明三档资源、immutable digest、named network、non-root/read-only/no-capability/no-new-privileges、只读 projection 和无 secret env；负例覆盖 tag、ambient network 与路径漂移。
4. Cluster deployment audit 必须拒绝 launcher contract 漂移以及任何 Kubernetes YAML 中的 `ql3-copilot-mcp` 常驻资源；package/Edge import/Local artifact 门不得放宽。
5. OCI layout fixture 与真实 Dockerfile 必须共同绑定 product façade entrypoint 和新 metadata；Admin image live gate 至少验证 `copilot`、`copilot-mcp` help 与全部既有命令。
6. Cluster Admin、18-package clean build/test、backend、SBOM/OCI/部署审计和 14 档 Local artifact 全部通过后才允许 D-326 阶段提交。本 Gate 无 schema、migration、SQL、role、Pool 或 HA 拓扑变化，不重复数据库物理 HA。