# Docker Pod 信息接口设计文档

> **文档版本**: v1.0.1  
> **创建日期**: 2024-12-16  
> **更新日期**: 2024-12-16  
> **状态**: 草案  
> **相关模块**: `crates/rcoder/src/router.rs`, `crates/docker_manager`, `crates/shared_types`

---

## 1. 需求概述

### 1.1 背景

RCoder 系统采用动态容器管理模式，可以根据 `user_id` 和 `project_id` 创建和管理 Docker 容器（特别是 `ComputerAgentRunner` 类型的容器）。为了便于系统监控和前端用户使用 noVNC 远程虚拟桌面，需要新增三个接口：

1. **获取当前容器数量接口** - 用于监控系统中已创建的容器总数
2. **启动容器接口** - 根据 `user_id` 和 `project_id` 启动（或获取已存在的）容器，**仅启动容器本身，不启动 Agent 服务**，以便用户可以通过 noVNC 访问远程虚拟桌面
3. **容器保活接口** - 刷新容器的最后活动时间，防止容器被定时清理任务销毁

> [!IMPORTANT]
> 所有接口响应统一使用 `shared_types::HttpResult<T>` 结构进行包装，保持与系统其他 API 的一致性。

### 1.2 目标

| 目标 | 描述 |
|------|------|
| **监控能力** | 提供容器数量统计，便于系统运维监控 |
| **用户体验** | 简化容器启动流程，自动化处理容器存在性检查 |
| **简洁响应** | 响应只包含容器基本信息，VNC 访问通过独立接口获取 |
| **轻量启动** | 仅启动容器，不启动 Agent 服务，减少资源占用 |
| **容器保活** | 支持刷新容器活动时间，防止被自动清理 |

---

## 2. HttpResult 响应包装

### 2.1 HttpResult 结构 (来自 `shared_types`)

所有接口响应均使用 `HttpResult<T>` 包装：

```rust
// 来自 crates/shared_types/src/model/http_result.rs

#[derive(Debug, Deserialize, ToSchema)]
pub struct HttpResult<T> {
    /// 响应码: "0000" 表示成功
    pub code: String,
    
    /// 响应消息
    pub message: String,
    
    /// 响应数据 (成功时有值)
    pub data: Option<T>,
    
    /// OpenTelemetry Trace ID (用于链路追踪)
    pub tid: Option<String>,
    
    /// 是否成功 (code == "0000")
    #[serde(skip)]
    pub success: bool,
}

impl<T> HttpResult<T> {
    /// 创建成功响应
    pub fn success(data: T) -> Self;
    
    /// 创建错误响应
    pub fn error(code: &str, message: &str) -> Self;
    
    /// 创建内部错误响应 (code: "5000")
    pub fn internal_error(message: &str) -> Self;
}
```

### 2.2 响应格式示例

**成功响应:**

```json
{
  "code": "0000",
  "message": "成功",
  "data": { ... },
  "tid": "abc123def456...",
  "success": true
}
```

**错误响应:**

```json
{
  "code": "5000",
  "message": "获取 DockerManager 失败",
  "data": null,
  "tid": "abc123def456...",
  "success": false
}
```

---

## 3. 接口设计

### 3.1 接口一：获取当前容器数量

#### 3.1.1 接口规格

| 属性 | 值 |
|------|-----|
| **路径** | `GET /computer/pod/count` |
| **方法** | GET |
| **入参** | 无 |
| **响应类型** | `HttpResult<PodCountResponse>` |
| **标签** | `pod` (Pod 容器管理接口) |

#### 3.1.2 请求示例

```bash
curl -X GET http://localhost:8087/computer/pod/count
```

#### 3.1.3 响应数据结构 (data 字段)

```rust
/// 容器数量响应结构
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
pub struct PodCountResponse {
    /// 当前运行的容器总数
    #[schema(example = 5)]
    pub total_count: u32,
    
    /// 按服务类型分类的容器数量
    pub by_service_type: PodCountByServiceType,
    
    /// 统计时间戳 (Unix 毫秒)
    #[schema(example = 1702700000000)]
    pub timestamp: u64,
}

/// 按服务类型分类的容器数量
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
pub struct PodCountByServiceType {
    /// RCoder 类型容器数量
    #[schema(example = 2)]
    pub rcoder: u32,
    
    /// ComputerAgentRunner 类型容器数量
    #[schema(example = 3)]
    pub computer_agent_runner: u32,
}
```

#### 3.1.4 完整响应示例

```json
{
  "code": "0000",
  "message": "成功",
  "data": {
    "total_count": 5,
    "by_service_type": {
      "rcoder": 2,
      "computer_agent_runner": 3
    },
    "timestamp": 1702700000000
  },
  "tid": "4bf92f3577b34da6a3ce929d0e0e4736",
  "success": true
}
```

---

### 3.2 接口二：启动容器 (Ensure Container)

#### 3.2.1 接口规格

| 属性 | 值 |
|------|-----|
| **路径** | `POST /computer/pod/ensure` |
| **方法** | POST |
| **入参** | `user_id` (必填), `project_id` (必填) |
| **响应类型** | `HttpResult<EnsurePodResponse>` |
| **标签** | `pod` (Pod 容器管理接口) |

> [!NOTE]
> 此接口采用 **幂等设计**：如果对应的容器已经存在且处于运行状态，则直接返回现有容器信息，不会创建新容器。

> [!IMPORTANT]
> **此接口仅启动容器，不启动 Agent 服务。** 容器启动后，用户可直接通过 noVNC 访问虚拟桌面，无需等待 Agent 服务初始化。如需使用 AI Agent 功能，请调用 `/computer/chat` 接口。

#### 3.2.2 请求结构

```rust
/// 启动容器请求结构
#[derive(Debug, Clone, Deserialize, ToSchema)]
pub struct EnsurePodRequest {
    /// 用户唯一标识符
    #[schema(example = "user_123")]
    pub user_id: String,
    
    /// 项目唯一标识符
    #[schema(example = "proj_456")]
    pub project_id: String,
    
    /// 可选的资源限制配置
    #[serde(skip_serializing_if = "Option::is_none")]
    pub resource_limits: Option<PodResourceLimits>,
}

/// Pod 资源限制配置
#[derive(Debug, Clone, Deserialize, Serialize, ToSchema)]
pub struct PodResourceLimits {
    /// 内存限制 (bytes), 例如 4GB = 4294967296
    #[schema(example = 4294967296)]
    pub memory: Option<u64>,
    
    /// CPU 份额 (1024 = 1 核)
    #[schema(example = 2048)]
    pub cpu_shares: Option<u64>,
}
```

#### 3.2.3 请求示例

```bash
curl -X POST http://localhost:8087/computer/pod/ensure \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "project_id": "proj_456"
  }'
```

#### 3.2.4 响应数据结构 (data 字段)

```rust
/// 启动容器响应结构
#[derive(Debug, Clone, Serialize, ToSchema)]
pub struct EnsurePodResponse {
    /// 容器是否为新创建 (false 表示已存在)
    pub created: bool,

    /// 容器基本信息
    pub container_info: PodContainerInfo,

    /// 提示消息
    #[schema(example = "容器已就绪")]
    pub message: String,
}

/// 容器基本信息
#[derive(Debug, Clone, Serialize, ToSchema)]
pub struct PodContainerInfo {
    /// 容器 ID
    #[schema(example = "abc123def456")]
    pub container_id: String,

    /// 容器名称
    #[schema(example = "computer-agent-runner-user_123")]
    pub container_name: String,

    /// 容器 IP 地址 (内部网络)
    #[schema(example = "172.17.0.5")]
    pub container_ip: String,

    /// 服务 URL
    #[schema(example = "http://172.17.0.5:8086")]
    pub service_url: String,

    /// 容器状态
    #[schema(example = "running")]
    pub status: String,
}
```

#### 3.2.5 完整响应示例

**成功响应（新创建容器）:**

```json
{
  "code": "0000",
  "message": "成功",
  "data": {
    "created": true,
    "container_info": {
      "container_id": "abc123def456...",
      "container_name": "computer-agent-runner-user_123",
      "container_ip": "172.17.0.5",
      "service_url": "http://172.17.0.5:8086",
      "status": "running"
    },
    "message": "容器创建成功（Agent 服务未启动）"
  },
  "tid": "4bf92f3577b34da6a3ce929d0e0e4736",
  "success": true
}
```

**成功响应（容器已存在）:**

```json
{
  "code": "0000",
  "message": "成功",
  "data": {
    "created": false,
    "container_info": {
      "container_id": "abc123def456...",
      "container_name": "computer-agent-runner-user_123",
      "container_ip": "172.17.0.5",
      "service_url": "http://172.17.0.5:8086",
      "status": "running"
    },
    "message": "容器已存在"
  },
  "tid": "4bf92f3577b34da6a3ce929d0e0e4736",
  "success": true
}
```

**错误响应:**

```json
{
  "code": "5000",
  "message": "启动容器失败: Docker 连接超时",
  "data": null,
  "tid": "4bf92f3577b34da6a3ce929d0e0e4736",
  "success": false
}
```

---

### 3.3 接口三：容器保活 (Keepalive)

#### 3.3.1 接口规格

| 属性 | 值 |
|------|-----|
| **路径** | `POST /computer/pod/keepalive` |
| **方法** | POST |
| **入参** | `user_id` (必填), `project_id` (必填) |
| **响应类型** | `HttpResult<KeepalivePodResponse>` |
| **标签** | `pod` (Pod 容器管理接口) |

> [!NOTE]
> 此接口用于防止容器被定时清理任务销毁。系统会定期（默认每 5 分钟）检查容器的最后活动时间，闲置超过 30 分钟的容器将被自动清理。

> [!TIP]
> **使用场景**：前端在用户使用 noVNC 远程桌面时，应定期调用此接口（建议每 5-10 分钟一次）来保持容器活跃状态。

#### 3.3.2 请求结构

```rust
/// 容器保活请求结构
#[derive(Debug, Clone, Deserialize, ToSchema)]
pub struct KeepalivePodRequest {
    /// 用户唯一标识符
    #[schema(example = "user_123")]
    pub user_id: String,
    
    /// 项目唯一标识符
    #[schema(example = "proj_456")]
    pub project_id: String,
}
```

#### 3.3.3 请求示例

```bash
curl -X POST http://localhost:8087/computer/pod/keepalive \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "project_id": "proj_456"
  }'
```

#### 3.3.4 响应数据结构 (data 字段)

```rust
/// 容器保活响应结构
#[derive(Debug, Clone, Serialize, ToSchema)]
pub struct KeepalivePodResponse {
    /// 容器是否存在 (true=已存在, false=新创建)
    pub existed: bool,
    
    /// 容器是否为新创建 (当 existed=false 时为 true)
    pub created: bool,
    
    /// 容器基本信息
    pub container_info: PodContainerInfo,
    
    /// 上次活动时间 (Unix 毫秒时间戳, 更新前)
    #[schema(example = 1702700000000)]
    pub previous_activity_time: u64,
    
    /// 当前活动时间 (Unix 毫秒时间戳, 更新后)
    #[schema(example = 1702700600000)]
    pub current_activity_time: u64,
    
    /// 距离下次清理的剩余时间 (秒)
    /// 基于默认 30 分钟闲置超时计算
    #[schema(example = 1800)]
    pub time_until_cleanup: u64,
    
    /// 提示消息
    #[schema(example = "容器活动时间已刷新")]
    pub message: String,
}
```

#### 3.3.5 完整响应示例

**成功响应（容器已存在，刷新活动时间）:**

```json
{
  "code": "0000",
  "message": "成功",
  "data": {
    "existed": true,
    "created": false,
    "container_info": {
      "container_id": "abc123def456...",
      "container_name": "computer-agent-runner-user_123",
      "container_ip": "172.17.0.5",
      "service_url": "http://172.17.0.5:8086",
      "status": "running"
    },
    "previous_activity_time": 1702700000000,
    "current_activity_time": 1702700600000,
    "time_until_cleanup": 1800,
    "message": "容器活动时间已刷新，距离自动清理还有 30 分钟"
  },
  "tid": "4bf92f3577b34da6a3ce929d0e0e4736",
  "success": true
}
```

**成功响应（容器不存在，自动创建）:**

```json
{
  "code": "0000",
  "message": "成功",
  "data": {
    "existed": false,
    "created": true,
    "container_info": {
      "container_id": "xyz789...",
      "container_name": "computer-agent-runner-user_123",
      "container_ip": "172.17.0.6",
      "service_url": "http://172.17.0.6:8086",
      "status": "running"
    },
    "previous_activity_time": 0,
    "current_activity_time": 1702700600000,
    "time_until_cleanup": 1800,
    "message": "容器已自动创建，距离自动清理还有 30 分钟"
  },
  "tid": "4bf92f3577b34da6a3ce929d0e0e4736",
  "success": true
}
```

**错误响应:**

```json
{
  "code": "5000",
  "message": "刷新活动时间失败: 容器状态异常",
  "data": null,
  "tid": "4bf92f3577b34da6a3ce929d0e0e4736",
  "success": false
}
```

---

## 4. 架构设计

### 4.1 整体架构

```
┌─────────────────────────────────────────────────────────────────┐
│                         外部客户端                                │
└────────────────────────────┬────────────────────────────────────┘
                             │ HTTP
                             ▼
┌─────────────────────────────────────────────────────────────────┐
│                      rcoder (主服务)                              │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    router.rs                              │   │
│  │  /computer/pod/count    ─────▶ pod_count_handler          │   │
│  │  /computer/pod/ensure   ─────▶ pod_ensure_handler         │   │
│  │  /computer/pod/keepalive─────▶ pod_keepalive_handler      │   │
│  └───────────────────────────┬─────────────────────────────┘   │
│                              │                                   │
│  ┌───────────────────────────▼─────────────────────────────┐   │
│  │               service/pod_service.rs                      │   │
│  │  ┌─────────────────┐   ┌──────────────────────────────┐ │   │
│  │  │ PodService      │   │ PodServiceTrait (trait)      │ │   │
│  │  │ - get_count()   │   │ - get_pod_count()            │ │   │
│  │  │ - ensure_pod()  │   │ - ensure_pod()               │ │   │
│  │  └─────────────────┘   └──────────────────────────────┘ │   │
│  └───────────────────────────┬─────────────────────────────┘   │
│                              │                                   │
│  ┌───────────────────────────▼─────────────────────────────┐   │
│  │             docker_manager (crate)                        │   │
│  │  DockerManager                                            │   │
│  │  - list_containers()                                      │   │
│  │  - get_agent_info()                                       │   │
│  │  - start_agent_container()                                │   │
│  └───────────────────────────┬─────────────────────────────┘   │
└──────────────────────────────┼──────────────────────────────────┘
                               │ Docker API
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Docker Daemon                                  │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐    │
│  │ container-1    │  │ container-2    │  │ container-3    │    │
│  │ (user_123)     │  │ (user_456)     │  │ (project_xyz)  │    │
│  └────────────────┘  └────────────────┘  └────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
```

### 4.2 模块职责

| 模块 | 职责 |
|------|------|
| `handler/pod_handler.rs` | 处理 HTTP 请求，参数解析与验证 |
| `service/pod_service.rs` | 核心业务逻辑，调用 DockerManager |
| `docker_manager` | Docker API 交互，容器生命周期管理 |

---

## 5. Trait 与结构体定义

### 5.1 Service Trait

```rust
// crates/rcoder/src/service/pod_service.rs

use async_trait::async_trait;
use crate::AppError;

/// Pod 服务 Trait
/// 
/// 定义 Pod 容器管理的核心能力接口
#[async_trait]
pub trait PodServiceTrait: Send + Sync {
    /// 获取当前容器数量统计
    /// 
    /// # 返回
    /// 容器数量统计信息
    async fn get_pod_count(&self) -> Result<PodCountResponse, AppError>;
    
    /// 确保容器存在（幂等操作）
    /// 
    /// 如果容器已存在则返回现有容器信息，否则创建新容器
    /// 仅启动容器，不启动 Agent 服务
    /// 
    /// # 参数
    /// - `request`: 启动容器请求
    /// 
    /// # 返回
    /// 容器信息和 VNC 访问信息
    async fn ensure_pod(&self, request: EnsurePodRequest) -> Result<EnsurePodResponse, AppError>;
    
    /// 容器保活（刷新活动时间）
    /// 
    /// 如果容器已存在则刷新其最后活动时间，防止被清理任务销毁
    /// 如果容器不存在则自动创建
    /// 
    /// # 参数
    /// - `request`: 保活请求（包含 user_id 和 project_id）
    /// 
    /// # 返回
    /// 保活结果，包含活动时间信息和距离清理的剩余时间
    async fn keepalive_pod(&self, request: KeepalivePodRequest) -> Result<KeepalivePodResponse, AppError>;
}
```

### 5.2 请求/响应结构体

```rust
// crates/rcoder/src/handler/pod_handler.rs

use serde::{Deserialize, Serialize};
use utoipa::ToSchema;

// ============================================================================
// 接口一：获取容器数量
// ============================================================================

/// 容器数量响应
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
pub struct PodCountResponse {
    /// 当前运行的容器总数
    pub total_count: u32,
    
    /// 按服务类型分类的容器数量
    pub by_service_type: PodCountByServiceType,
    
    /// 统计时间戳 (Unix 毫秒)
    pub timestamp: u64,
}

/// 按服务类型分类的容器数量
#[derive(Debug, Clone, Serialize, Deserialize, ToSchema)]
pub struct PodCountByServiceType {
    /// RCoder 类型容器数量
    pub rcoder: u32,
    
    /// ComputerAgentRunner 类型容器数量
    pub computer_agent_runner: u32,
}

// ============================================================================
// 接口二：启动容器
// ============================================================================

/// 启动容器请求
#[derive(Debug, Clone, Deserialize, ToSchema)]
pub struct EnsurePodRequest {
    /// 用户唯一标识符 (必填)
    #[schema(example = "user_123")]
    pub user_id: String,
    
    /// 项目唯一标识符 (必填)
    #[schema(example = "proj_456")]
    pub project_id: String,
    
    /// 可选的资源限制配置
    #[serde(skip_serializing_if = "Option::is_none")]
    pub resource_limits: Option<PodResourceLimits>,
}

/// Pod 资源限制配置
#[derive(Debug, Clone, Deserialize, Serialize, ToSchema)]
pub struct PodResourceLimits {
    /// 内存限制 (bytes)
    pub memory: Option<u64>,
    
    /// CPU 份额
    pub cpu_shares: Option<u64>,
}

/// 启动容器响应
///
/// 注意: 此结构体作为 HttpResult<EnsurePodResponse> 的 data 字段返回
/// 成功状态由外层 HttpResult 的 code 字段表示
#[derive(Debug, Clone, Serialize, ToSchema)]
pub struct EnsurePodResponse {
    /// 容器是否为新创建 (false 表示已存在)
    pub created: bool,

    /// 容器基本信息
    pub container_info: PodContainerInfo,

    /// 提示消息
    pub message: String,
}

/// 容器基本信息
#[derive(Debug, Clone, Serialize, ToSchema)]
pub struct PodContainerInfo {
    /// 容器 ID
    pub container_id: String,

    /// 容器名称
    pub container_name: String,

    /// 容器 IP 地址
    pub container_ip: String,

    /// 服务 URL
    pub service_url: String,

    /// 容器状态
    pub status: String,
}

// ============================================================================
// 接口三：容器保活
// ============================================================================

/// 容器保活请求
#[derive(Debug, Clone, Deserialize, ToSchema)]
pub struct KeepalivePodRequest {
    /// 用户唯一标识符
    #[schema(example = "user_123")]
    pub user_id: String,
    
    /// 项目唯一标识符
    #[schema(example = "proj_456")]
    pub project_id: String,
}

/// 容器保活响应
/// 
/// 注意: 此结构体作为 HttpResult<KeepalivePodResponse> 的 data 字段返回
#[derive(Debug, Clone, Serialize, ToSchema)]
pub struct KeepalivePodResponse {
    /// 容器是否已存在
    pub existed: bool,
    
    /// 容器是否为新创建 (当 existed=false 时为 true)
    pub created: bool,
    
    /// 容器基本信息
    pub container_info: PodContainerInfo,
    
    /// 上次活动时间 (Unix 毫秒时间戳, 更新前)
    pub previous_activity_time: u64,
    
    /// 当前活动时间 (Unix 毫秒时间戳, 更新后)
    pub current_activity_time: u64,
    
    /// 距离下次清理的剩余时间 (秒)
    pub time_until_cleanup: u64,
    
    /// 提示消息
    pub message: String,
}
```

### 5.3 Service 实现结构

```rust
// crates/rcoder/src/service/pod_service.rs

use std::sync::Arc;

/// Pod 服务实现
/// 
/// 封装 Docker 容器管理的业务逻辑
pub struct PodService {
    /// Docker 管理器
    docker_manager: Arc<docker_manager::DockerManager>,
}

impl PodService {
    /// 创建 PodService 实例
    pub fn new(docker_manager: Arc<docker_manager::DockerManager>) -> Self {
        Self { docker_manager }
    }
}

#[async_trait]
impl PodServiceTrait for PodService {
    async fn get_pod_count(&self) -> Result<PodCountResponse, AppError> {
        // 具体实现...
        todo!()
    }
    
    async fn ensure_pod(&self, request: EnsurePodRequest) -> Result<EnsurePodResponse, AppError> {
        // 具体实现...
        todo!()
    }
    
    async fn keepalive_pod(&self, request: KeepalivePodRequest) -> Result<KeepalivePodResponse, AppError> {
        // 具体实现...
        // 1. 查询容器是否存在
        // 2. 不存在则创建容器
        // 3. 存在则刷新 last_activity 时间
        // 4. 计算距离清理的剩余时间
        todo!()
    }
}
```

---

## 6. 路由配置

### 6.1 新增路由

在 `crates/rcoder/src/router.rs` 中添加以下路由：

```rust
// 在 create_router 函数中添加

// Pod 容器管理路由 (统一使用 /computer 前缀)
.route("/computer/pod/count", get(handler::pod_count))
.route("/computer/pod/ensure", post(handler::pod_ensure))
.route("/computer/pod/keepalive", post(handler::pod_keepalive))
```

### 6.2 OpenAPI 配置更新

```rust
// 在 ApiDoc 结构体中添加

#[openapi(
    paths(
        // ... 现有路径
        handler::pod_count,
        handler::pod_ensure,
        handler::pod_keepalive,
    ),
    components(
        schemas(
            // ... 现有 schemas
            handler::PodCountResponse,
            handler::PodCountByServiceType,
            handler::EnsurePodRequest,
            handler::PodResourceLimits,
            handler::EnsurePodResponse,
            handler::PodContainerInfo,
            handler::KeepalivePodRequest,
            handler::KeepalivePodResponse,
        )
    ),
    tags(
        // ... 现有 tags
        (name = "pod", description = "Pod 容器管理接口，支持容器监控和启动"),
    ),
)]
```

---

## 7. 错误处理

### 7.1 错误类型

| 错误码 | HTTP 状态码 | 描述 |
|--------|-------------|------|
| `DOCKER_MANAGER_ERROR` | 500 | Docker Manager 获取失败 |
| `CONTAINER_CREATE_FAILED` | 500 | 容器创建失败 |
| `CONTAINER_NOT_FOUND` | 404 | 容器未找到（仅查询场景） |
| `INVALID_REQUEST` | 400 | 请求参数无效 |

### 7.2 错误响应结构（HttpResult 统一格式）

错误响应统一使用 `HttpResult<T>` 格式，`data` 字段为 `null`：

```json
{
  "code": "5000",
  "message": "启动容器失败: Docker 连接超时",
  "data": null,
  "tid": "4bf92f3577b34da6a3ce929d0e0e4736",
  "success": false
}
```

---

## 8. 与现有功能的关系

### 8.1 复用现有组件

| 组件 | 复用方式 |
|------|----------|
| `docker_manager::global::get_global_docker_manager()` | 获取全局 Docker 管理器实例 |
| `ComputerContainerManager` | 复用用户容器创建逻辑 |
| `ContainerBasicInfo` | 复用容器信息结构 |

### 8.2 与 noVNC 集成

VNC 访问信息通过独立接口获取：

- **VNC 桌面访问接口**: `GET /computer/desktop/{user_id}/{project_id}`

Pingora 已配置路由规则 `/computer/vnc/{user_id}/{project_id}/{*path}`，会自动代理到对应容器的 6080 端口。

---

## 9. 实现清单

### 9.1 新增文件

| 文件路径 | 描述 |
|----------|------|
| `crates/rcoder/src/handler/pod_handler.rs` | Pod 相关 HTTP 处理器 |
| `crates/rcoder/src/service/pod_service.rs` | Pod 服务业务逻辑 |

### 9.2 修改文件

| 文件路径 | 修改内容 |
|----------|----------|
| `crates/rcoder/src/router.rs` | 添加 `/computer/pod/*` 路由 |
| `crates/rcoder/src/handler/mod.rs` | 导出 `pod_handler` 模块 |
| `crates/rcoder/src/service/mod.rs` | 导出 `pod_service` 模块 |

---

## 10. 验证计划

### 10.1 自动化测试

```bash
# 1. 编译检查
cargo build --workspace

# 2. 单元测试
cargo test --workspace

# 3. Clippy 检查
cargo clippy --workspace --all-targets
```

### 10.2 手动验证

```bash
# 1. 启动服务
make dev-restart

# 2. 测试获取容器数量
curl -X GET http://localhost:8087/computer/pod/count | jq

# 3. 测试启动容器
curl -X POST http://localhost:8087/computer/pod/ensure \
  -H "Content-Type: application/json" \
  -d '{"user_id": "test_user", "project_id": "test_project"}' | jq

# 4. 验证 VNC 访问
# 使用返回的 proxy_vnc_url 在浏览器中访问
```

### 10.3 OpenAPI 文档验证

启动服务后访问 Swagger UI：`http://localhost:8087/swagger-ui/` 确认新接口已正确注册。

---

## 11. 附录

### 11.1 参考文件

- [computer_container_manager.rs](file:///Volumes/soddygo/git_work/rcoder/crates/rcoder/src/service/computer_container_manager.rs) - 用户容器管理逻辑
- [computer_desktop_handler.rs](file:///Volumes/soddygo/git_work/rcoder/crates/rcoder/src/handler/computer_desktop_handler.rs) - VNC 桌面处理器
- [docker_manager/manager.rs](file:///Volumes/soddygo/git_work/rcoder/crates/docker_manager/src/manager.rs) - Docker 容器管理核心

### 11.2 相关接口

| 接口 | 描述 |
|------|------|
| `GET /computer/desktop/{user_id}/{project_id}` | 获取 VNC 桌面访问信息 |
| `POST /computer/chat` | Computer Agent 聊天接口 |
| `/computer/vnc/{user_id}/{project_id}/*` | Pingora VNC 代理路由 |

---

## 12. 变更记录

| 日期 | 版本 | 变更内容 | 作者 |
|------|------|----------|------|
| 2024-12-16 | v1.0.0 | 初始版本 | AI Assistant |
| 2024-12-16 | v1.0.1 | 使用 HttpResult 包装响应；明确不启动 Agent 服务 | AI Assistant |
| 2024-12-16 | v1.1.0 | 新增容器保活接口 (keepalive)，支持刷新容器活动时间防止被自动清理 | AI Assistant |