byy/qiming
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
91f68576dd8c8ce7632a22dedbcf33ccacc3d4c8
qiming/qiming-rcoder/.qoder/repowiki/zh/content/容器化管理/容器生命周期管理.md
Codex 4b1a580132 添加qiming-rcoder模块
2026-06-01 13:54:52 +08:00

21 KiB
Raw Blame History

容器生命周期管理

**本文引用的文件** - [manager.rs](file://crates/docker_manager/src/manager.rs) - [container_stop.rs](file://crates/docker_manager/src/container_stop.rs) - [container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs) - [types.rs](file://crates/docker_manager/src/types.rs) - [lib.rs](file://crates/docker_manager/src/lib.rs) - [docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs) - [container_manager.rs](file://crates/rcoder/src/service/container_manager.rs) - [cleanup_task.rs](file://crates/rcoder/src/proxy_agent/cleanup_task.rs) - [agent_model.rs](file://crates/shared_types/src/model/agent_model.rs)

目录

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

引言

本文件围绕容器的完整生命周期管理展开，涵盖创建、启动、运行时监控、优雅停止与清理。重点基于 docker_manager 中的 create_container/start_container 流程，解析容器配置参数（资源限制、挂载卷、环境变量、网络与端口等）的设置逻辑；结合 container_stop 中的终止策略（超时与强制清理）、container_self_inspector 的容器内自检能力，以及 rcoder 层面的会话与容器映射关系，给出从 API 请求到容器终止的完整调用链路，并讨论异常终止场景下的恢复与资源泄漏防范策略。

项目结构

该仓库采用多 crate 的模块化组织，其中与容器生命周期直接相关的关键模块如下：

  • docker_manager：容器生命周期与资源编排的核心实现
  • rcoder：业务层容器管理与会话映射
  • shared_types：跨模块共享的数据模型与生命周期抽象
graph TB
subgraph "容器管理核心"
DM["DockerManager<br/>manager.rs"]
CS["容器停止策略<br/>container_stop.rs"]
CSI["容器自检器<br/>container_self_inspector.rs"]
DT["类型与配置<br/>types.rs"]
DL["错误与导出<br/>lib.rs"]
end
subgraph "业务集成"
RCA["容器代理服务<br/>docker_container_agent.rs"]
CM["容器服务封装<br/>container_manager.rs"]
CT["清理任务<br/>cleanup_task.rs"]
AM["Agent生命周期模型<br/>agent_model.rs"]
end
DM --> CS
DM --> CSI
DM --> DT
DM --> DL
RCA --> DM
CM --> DM
CT --> DM
CT --> CS
CT --> AM

图表来源

章节来源

核心组件

  • DockerManager：负责容器创建、启动、状态更新、日志获取、重启与网络信息查询；提供统一的容器停止接口（支持超时与强制清理）。
  • 容器停止策略：提供启动时清理与运行时清理两类策略，分别针对遗留容器与即时回收资源。
  • 容器自检器：在容器内部通过 Docker API 检测挂载信息，解析容器内路径到宿主机路径。
  • 类型与配置：集中定义容器配置、状态、清理结果等数据结构。
  • 业务容器代理：将服务类型映射为镜像与配置，构造 DockerContainerConfig 并驱动 DockerManager 创建容器。
  • 容器服务封装：对外暴露容器信息查询与服务 URL 生成，屏蔽底层网络细节。
  • 清理任务：周期性扫描孤立容器并统一清理，结合运行时停止策略与 RAII 资源回收。
  • Agent 生命周期模型：提供优雅停止与强制清理的 RAII 抽象，确保资源释放。

章节来源

架构总览

下图展示从 API 请求到容器终止的完整调用链路，强调会话 ID 与容器的映射关系。

sequenceDiagram
participant Client as "客户端"
participant Handler as "rcoder处理器"
participant CM as "容器服务封装<br/>container_manager.rs"
participant RCA as "容器代理服务<br/>docker_container_agent.rs"
participant DM as "DockerManager<br/>manager.rs"
participant CS as "停止策略<br/>container_stop.rs"
participant CT as "清理任务<br/>cleanup_task.rs"
Client->>Handler : "发起请求"
Handler->>CM : "get_or_create_container(project_id, service_type)"
CM->>DM : "get_container_info / create_container"
DM-->>CM : "返回容器信息"
CM-->>Handler : "返回服务URL"
Handler-->>Client : "响应服务URL"
Note over Handler,CT : "异常或闲置清理时"
Handler->>CT : "触发清理任务"
CT->>DM : "find_container_by_identifier / list_containers_with_pattern"
DM-->>CT : "容器信息"
CT->>CS : "runtime_cleanup_container / startup_cleanup_containers"
CS->>DM : "stop_container_by_id_with_timeout(force=true)"
DM-->>CS : "清理完成"
CS-->>CT : "清理结果"

图表来源

详细组件分析

DockerManager：创建与启动流程

  • 容器创建与启动
    • 生成容器名称并检查是否已有同项目容器，若存在则先停止并删除。
    • 拉取镜像（本地不存在时）。
    • 构造挂载点（绑定宿主机路径到容器路径，支持只读与额外挂载）。
    • 设置环境变量、端口映射、资源限制（内存、CPU、Swap）。
    • 主动连接到动态检测的主网络，或使用 host 网络模式。
    • 设置容器主机名、域名为便于识别。
    • 设置启动命令与入口点。
    • 调用 create_container 并立即 start_container。
    • 等待短暂时间后检查容器健康状态，再写入容器映射。
  • 停止与清理
    • 提供 stop_container_by_id_with_timeout（支持超时与强制清理）。
    • 提供 stop_container（按 project_id 停止并移除映射）。
    • 提供 find_container_by_identifier（支持 project_id、容器名称与 Docker API 查询）。
    • 提供 update_container_status、get_container_network_info、get_container_logs 等辅助能力。
  • 资源限制与网络
    • 资源限制通过 HostConfig 的 memory、memory_swap、nano_cpus 设置。
    • 网络通过 NetworkingConfig 连接到动态主网络，支持 aliases 与 host 模式。
flowchart TD
Start(["开始创建容器"]) --> GenName["生成容器名称"]
GenName --> CheckExisting{"是否已存在同项目容器？"}
CheckExisting --> |是| StopOld["停止并删除旧容器"]
CheckExisting --> |否| PullImage["拉取镜像"]
StopOld --> PullImage
PullImage --> BuildMounts["构建挂载点"]
BuildMounts --> BuildEnv["构建环境变量"]
BuildEnv --> BuildPorts["构建端口映射"]
BuildPorts --> ApplyLimits["应用资源限制"]
ApplyLimits --> NetMode{"网络模式 host？"}
NetMode --> |否| ConnectNet["连接到动态主网络"]
NetMode --> |是| UseHost["使用 host 网络"]
ConnectNet --> BuildCfg["组装 ContainerCreateBody"]
UseHost --> BuildCfg
BuildCfg --> Create["create_container"]
Create --> Start["start_container"]
Start --> Health["检查容器健康状态"]
Health --> SaveMap["写入容器映射"]
SaveMap --> End(["完成"])

图表来源

章节来源

容器停止策略：优雅停止与强制清理

  • 启动时清理（startup_cleanup）
    • 使用 5 秒超时，支持并发停止多个容器。
    • 过滤 409 冲突错误（容器已在删除中），避免阻塞服务启动。
  • 运行时清理（runtime_cleanup）
    • 使用 3 秒优雅停止超时，超时后强制停止，快速释放资源。
    • 支持单个与批量清理，返回详细清理统计。
  • 统一停止接口
    • stop_container_by_id_with_timeout 内部使用 force=true 的 remove_container，避免“removal already in progress”竞态。
sequenceDiagram
participant Caller as "调用方"
participant CS as "container_stop.rs"
participant DM as "DockerManager"
Caller->>CS : "runtime_cleanup_container(container_id)"
CS->>DM : "stop_container_by_id_with_timeout(container_id, 3s)"
DM->>DM : "remove_container(..., force=true)"
DM-->>CS : "清理完成"
CS-->>Caller : "OK"

图表来源

章节来源

容器自检器：容器内状态探测与路径解析

  • 在容器内部通过 Docker API 检测自身挂载信息，解析容器内路径到宿主机路径。
  • 支持列出所有挂载点、验证 Docker socket 连接、从 /proc/self/cgroup 解析容器 ID 等能力。
  • 为容器内路径解析提供同步与异步两种接口，便于不同上下文使用。
flowchart TD
Enter(["进入容器内自检"]) --> Ping["连接 Docker socket 并 ping"]
Ping --> GetCID["解析容器ID/proc/self/cgroup"]
GetCID --> Inspect["inspect_container 获取挂载信息"]
Inspect --> MatchPath{"目标路径匹配？"}
MatchPath --> |是| ReturnHost["返回宿主机路径"]
MatchPath --> |否| ListMounts["列出所有挂载点并告警"]
ListMounts --> Error["返回错误"]
ReturnHost --> Exit(["完成"])
Error --> Exit

图表来源

章节来源

业务集成：从 API 到容器终止的调用链

  • 会话与容器映射
    • rcoder 层通过 ProjectAndContainerInfo 维护 project_id 与 session_id 的映射关系。
    • 容器服务封装 ContainerManager 提供 get_or_create_container/get_container_info，内部通过 DockerManager 获取网络信息并生成服务 URL。
  • 容器代理服务
    • docker_container_agent 根据服务类型选择镜像与配置，构造 DockerContainerConfig 并调用 DockerManager.create_container。
    • 等待容器内 agent_runner 就绪后返回服务 URL。
  • 清理与异常恢复
    • cleanup_task 周期性扫描孤立容器，使用 runtime_cleanup_container 统一清理。
    • 采用 RAII 的 AgentLifecycleGuard，当容器或 Agent 被移除时自动清理子进程与任务，避免资源泄漏。
sequenceDiagram
participant API as "API请求"
participant CM as "ContainerManager"
participant RCA as "docker_container_agent"
participant DM as "DockerManager"
participant CT as "cleanup_task"
participant AG as "AgentLifecycleGuard"
API->>CM : "get_or_create_container(project_id, service_type)"
CM->>RCA : "start_docker_container_agent_service"
RCA->>DM : "create_container(config)"
DM-->>RCA : "返回容器信息"
RCA-->>CM : "返回服务URL"
CM-->>API : "返回服务URL"
Note over CT,AG : "异常或闲置清理"
CT->>DM : "find_container_by_identifier / list_containers_with_pattern"
DM-->>CT : "容器信息"
CT->>DM : "runtime_cleanup_container"
DM-->>CT : "清理完成"
AG-->>CT : "Drop时清理资源"

图表来源

章节来源

容器配置参数设置逻辑（资源限制、挂载卷、环境变量）

  • 资源限制
    • 通过 HostConfig.nano_cpus 设置 CPU 限制（1 CPU = 1e9 nano CPUs）。
    • 通过 memory/memory_swap 设置内存与 Swap 限制。
  • 挂载卷
    • 默认绑定项目工作目录到容器内路径，支持只读。
    • 支持额外挂载点，逐项转换为 Mount。
  • 环境变量
    • 将 HashMap 转换为 "KEY=VALUE" 形式的字符串列表注入。
  • 端口映射
    • 通过端口绑定映射，host_ip 固定为 0.0.0.0，host_port 由映射提供。
  • 网络与主机名
    • 通过 NetworkingConfig 连接到动态主网络，设置 aliases。
    • 设置 hostname/domainname 便于识别。

章节来源

终止策略：信号发送、超时处理与强制杀灭

  • 优雅停止
    • 运行时清理使用 3 秒超时，超时后强制停止。
    • 启动时清理使用 5 秒超时，过滤 409 冲突错误。
  • 强制杀灭
    • stop_container_by_id_with_timeout 内部使用 force=true 的 remove_container，避免“removal already in progress”竞态。
  • 统一清理统计
    • 返回 total_found、successfully_removed、failed_removals、removed_container_ids、failed_removals_details、duration_ms 等指标。

章节来源

容器内状态探测与自检流程

  • 通过 Docker API 获取容器挂载信息，匹配目标容器内路径并返回宿主机绝对路径。
  • 支持列出所有挂载点用于调试，支持从 /proc/self/cgroup 解析容器 ID。
  • 提供 verify_docker_connection 与 get_all_mounts 辅助诊断。

章节来源

依赖分析

  • 组件耦合
    • DockerManager 与 container_stop：停止策略依赖 DockerManager 的 remove_container 接口。
    • docker_container_agent 与 DockerManager：代理服务通过 DockerManager 创建容器。
    • cleanup_task 与 DockerManager/container_stop：清理任务统一调用停止策略。
    • rcoder 的会话与容器映射：ProjectAndContainerInfo 与 cleanup_task 的映射关系。
  • 外部依赖
    • bollard：Docker API 客户端。
    • tokio/dashmap/tracing：异步运行时、并发容器与日志。
  • 循环依赖
    • 未见循环导入；各模块职责清晰，通过公共类型与接口解耦。
graph LR
RCA["docker_container_agent.rs"] --> DM["manager.rs"]
CM["container_manager.rs"] --> DM
CT["cleanup_task.rs"] --> DM
CT --> CS["container_stop.rs"]
DM --> CS
DM --> DT["types.rs"]
DM --> DL["lib.rs"]
CT --> AM["agent_model.rs"]

图表来源

章节来源

性能考虑

  • 并发清理：container_stop 支持并发停止多个容器，显著提升启动时遗留容器清理效率。
  • 超时控制：运行时清理使用短超时（3 秒），避免阻塞；启动时清理使用更短超时（5 秒），保证服务启动不被拖慢。
  • 端口映射优化：业务侧采用内部网络通信，避免端口分配与释放带来的开销。
  • 资源限制：合理设置 CPU 与内存限制，避免容器争抢影响整体稳定性。
  • 日志与健康检查：通过 get_container_logs 与健康检查减少无效重试与等待。

[本节为通用指导，不直接分析具体文件]

故障排查指南

  • 容器启动后立即退出
    • 检查 DockerManager.check_container_health 的错误输出，定位退出码与错误信息。
  • 容器不存在或已在删除中
    • stop_container_by_id_with_timeout 对 No such container 与 removal already in progress 做了特殊处理，可忽略相关警告。
  • 网络连接问题
    • 使用 get_container_network_info 获取容器网络信息，确认容器已连接到动态主网络。
  • 清理统计异常
    • 通过 CleanupResult 的字段（如 failed_removals_details）定位失败容器与错误原因。
  • 会话与容器映射丢失
    • 使用 cleanup_task 的孤立容器检查与清理，结合 RAII 的 AgentLifecycleGuard 自动清理资源。

章节来源

结论

本系统通过 DockerManager 提供统一的容器生命周期管理能力，配合 container_stop 的优雅停止与强制清理策略、container_self_inspector 的容器内自检能力，以及 rcoder 层的会话与容器映射、清理任务与 RAII 资源回收，实现了从 API 请求到容器终止的闭环管理。在异常终止场景下，通过统一的停止接口与清理统计，能够快速定位问题并防止资源泄漏。建议在生产环境中合理设置资源限制与网络策略，并持续监控清理任务的执行效果。

[本节为总结性内容，不直接分析具体文件]

附录

Reference in New Issue View Git Blame Copy Permalink