Feature Specification: Kubernetes Runtime Support

Feature Branch: dev-k8s
Created: 2026-04-16
Status: Draft
Input: User description: "修复 K8s 支持，问题是 global 模块未使用 RuntimeManager，K8s Runtime 中 user_id 未处理，使用 Pod IP 而非 Service DNS"

User Scenarios & Testing

Primary User Story

RCoder 在 Kubernetes 集群中运行时，需要动态为每个项目/用户创建和管理容器（Pod）。当前实现仅支持 Docker Socket 方式，不支持 K8s 环境。

Acceptance Scenarios

Given RCoder 运行在 K8s 环境（设置 CONTAINER_RUNTIME=kubernetes），When 用户调用 /chat 接口，Then 系统应在 K8s 中创建 Pod 并正常通信
Given RCoder 运行在 K8s 环境，When 用户调用 /computer/chat 接口，Then 系统应使用 user_id 作为 Pod 标识创建容器
Given K8s Pod 发生重启，When gRPC 通信发生，Then 系统应能通过稳定的 Service DNS 找到新 Pod

Edge Cases

Pod 重启后 IP 变化如何处理？
K8s API 访问失败时的降级策略？
容器清理逻辑在 K8s 中如何适配？

Requirements

Functional Requirements

FR-001: 系统必须根据 CONTAINER_RUNTIME 环境变量选择 Docker 或 Kubernetes 运行时
FR-002: Kubernetes Runtime 必须支持 /chat 接口（使用 project_id 作为 Pod 标识）
FR-003: Kubernetes Runtime 必须支持 /computer/chat 接口（使用 user_id 作为 Pod 标识）
FR-004: Kubernetes Runtime 必须使用稳定的 Service DNS 而非 Pod IP
FR-005: 系统必须实现 list_containers 接口以支持 pod list 管理接口
FR-006: Kubernetes Runtime 必须支持容器健康检查

Key Entities

ContainerRuntime: 容器运行时抽象接口
KubernetesRuntime: K8s 运行时实现
DockerRuntime: Docker 运行时实现（封装 DockerManager）
RuntimeManager: 运行时管理器，负责选择和初始化正确的运行时

Technical Context (for planning)

Problem Analysis

问题	严重程度	位置
global 模块未使用 RuntimeManager，K8s 路径从未触发	P0	docker_manager/src/lib.rs
user_id 在 K8s Runtime 中被忽略	P0	kubernetes_runtime.rs
使用 Pod IP 而非 Service DNS	P0	kubernetes_runtime.rs
list_containers 未实现	P1	kubernetes_runtime.rs
健康检查机制不兼容 K8s	P1	health/

Proposed Changes

修改 global 模块使用 RuntimeManager 选择运行时
K8s Runtime 支持 user_id 参数
K8s Runtime 使用 Service DNS（{service}-{id}.{namespace}.svc.cluster.local）
实现 list_containers 方法
添加 K8s 健康检查支持（ Readiness Probe 概念）

Review & Acceptance Checklist

User description parsed
Key concepts extracted
Ambiguities marked (Pod DNS 格式、K8s API 权限)
User scenarios defined
Requirements generated
Entities identified
Review checklist passed

3.0 KiB Raw Blame History Unescape Escape