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

20 KiB
Raw Blame History

容器化管理

**本文引用的文件** - [crates/docker_manager/src/lib.rs](file://crates/docker_manager/src/lib.rs) - [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs) - [crates/docker_manager/src/types.rs](file://crates/docker_manager/src/types.rs) - [crates/docker_manager/src/utils.rs](file://crates/docker_manager/src/utils.rs) - [crates/docker_manager/src/image_selector.rs](file://crates/docker_manager/src/image_selector.rs) - [crates/docker_manager/src/container_self_inspector.rs](file://crates/docker_manager/src/container_self_inspector.rs) - [crates/docker_manager/src/container_stop.rs](file://crates/docker_manager/src/container_stop.rs) - [crates/rcoder/src/proxy_agent/docker_container_agent.rs](file://crates/rcoder/src/proxy_agent/docker_container_agent.rs) - [crates/rcoder/src/service/container_manager.rs](file://crates/rcoder/src/service/container_manager.rs) - [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs) - [crates/rcoder/src/rcoder_default.yml](file://crates/rcoder/src/rcoder_default.yml) - [crates/shared_types/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs) - [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs) - [docker/Dockerfile](file://docker/Dockerfile) - [docker/docker-compose.yml](file://docker/docker-compose.yml)

目录

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

引言

本文件系统性阐述本项目的容器化管理能力，涵盖 Docker 集成、容器生命周期、资源隔离与镜像管理的实现细节。文档基于实际代码库，提供面向初学者的循序讲解与面向资深工程师的技术深度，包括配置选项、参数与返回值说明、组件间关系、常见问题与解决方案，并辅以可视化图示帮助理解。

项目结构

围绕容器化管理的关键模块分布如下：

  • docker_manager：Docker 客户端封装、容器生命周期管理、镜像选择、网络与资源限制、容器自检测与停止策略
  • rcoder 服务层：容器编排入口、容器信息查询与服务 URL 生成、与 docker_manager 的交互
  • shared_types：多镜像配置模型、服务镜像配置、服务类型枚举等
  • docker 目录：Dockerfile 与 docker-compose.yml，定义运行时镜像与编排网络
graph TB
subgraph "rcoder 服务层"
RC["rcoder 服务<br/>容器管理器"]
DCA["Docker 容器 Agent"]
end
subgraph "docker_manager"
DM["DockerManager"]
IS["镜像选择器"]
UT["工具集"]
CSI["容器自检测"]
CS["停止策略"]
end
subgraph "shared_types"
MIC["多镜像配置"]
SIC["服务镜像配置"]
end
subgraph "运行时"
DC["Docker 守护进程"]
NET["Docker 网络"]
end
RC --> DM
DCA --> DM
DM --> DC
DM --> NET
DM --> IS
DM --> UT
DM --> CSI
DM --> CS
IS --> MIC
IS --> SIC

图表来源

章节来源

核心组件

  • DockerManager：统一的 Docker 客户端封装，负责容器创建、启动、停止、删除、状态查询、日志获取、网络信息查询、镜像存在性检查与拉取等
  • 镜像选择器：基于服务类型与多镜像配置选择镜像，支持架构特定镜像与全局默认镜像
  • 工具集：平台检测、镜像兼容性判断、容器命名、配置加载（环境变量/配置文件）、路径规范化
  • 容器自检测：在容器内部通过 Docker API 获取自身挂载信息，解析容器内路径到宿主机路径
  • 停止策略：提供启动时清理与运行时清理两种策略，支持并发停止、超时控制与错误过滤
  • rcoder 服务层：容器编排入口，负责按项目维度创建/复用容器，生成服务 URL，查询网络信息

章节来源

架构总览

容器化管理采用“服务层 + docker_manager + Docker 守护进程”的分层设计。rcoder 服务层通过 DockerManager 与 Docker 守护进程交互，镜像选择器根据服务类型与多镜像配置决定镜像，工具集负责平台检测与配置加载，容器自检测与停止策略分别用于容器内部路径解析与资源回收。

sequenceDiagram
participant Client as "客户端"
participant RC as "rcoder 服务层"
participant DCA as "Docker 容器 Agent"
participant DM as "DockerManager"
participant DC as "Docker 守护进程"
Client->>RC : 请求项目容器
RC->>DM : 获取/创建容器
DM->>DC : 列出/检查镜像
DC-->>DM : 镜像存在/不存在
DM->>DC : 创建容器(挂载/网络/资源限制)
DC-->>DM : 返回容器ID
DM->>DC : 启动容器
DC-->>DM : 容器状态
DM-->>RC : 返回容器信息
RC->>DCA : 启动容器内 agent_runner
DCA-->>RC : 返回服务URL
RC-->>Client : 返回服务URL

图表来源

详细组件分析

DockerManager：容器生命周期与资源隔离

  • 连接与初始化：支持通过环境变量或本地默认连接 Docker 守护进程；初始化时检测主网络名称并确保 RCoder 网络存在
  • 容器创建：生成容器名称、检查同项目容器、拉取镜像、绑定挂载点、设置环境变量与端口映射、应用资源限制（内存、CPU、交换）、连接到动态检测的网络
  • 容器停止：提供按项目与按容器 ID 的停止接口，支持超时与强制删除；并发清理提升效率
  • 状态与日志：查询容器状态、健康状态、获取容器日志
  • 网络信息：通过 Docker API 获取容器网络 IP，支持基于网络名称的通信
  • 错误处理：统一的 DockerError 错误类型，区分连接、创建、启动、停止、删除、拉取、配置、IO、序列化、Bollard 错误
classDiagram
class DockerManager {
+new(config) DockerManager
+create_container(config) DockerContainerInfo
+stop_container(project_id) void
+stop_container_by_id(id, timeout) void
+get_container_info(project_id) DockerContainerInfo
+list_containers() Vec~DockerContainerInfo~
+update_container_status(project_id) ContainerStatus
+get_container_logs(project_id, lines) String
+restart_container(project_id) void
+get_container_network_info(id) HashMap~String,String~
+get_docker_client() Docker
+get_service_config(type) ServiceImageConfig
+select_image(type, overrides) String
}

图表来源

章节来源

镜像选择器：多镜像配置与架构适配

  • 多镜像配置：支持全局默认镜像、服务特定镜像（通用/ARM64/AMD64/默认回退）、镜像选择策略（当前为 ServiceOnly）、缓存配置
  • 服务镜像配置：包含服务类型、镜像、环境变量、挂载点、命令、入口点、资源限制、工作目录、网络模式、容器路径模板等
  • 选择逻辑：优先使用服务通用镜像，否则按平台选择架构特定镜像，最后回退到默认镜像；支持项目级镜像覆盖与环境变量合并
flowchart TD
Start(["开始"]) --> CheckService["检查服务是否启用"]
CheckService --> |否| Err["返回配置错误"]
CheckService --> |是| Priority["优先使用服务通用镜像"]
Priority --> |存在| UseGeneric["使用通用镜像"]
Priority --> |不存在| Platform["按平台选择架构镜像"]
Platform --> UseArm64["使用 ARM64 镜像"]
Platform --> UseAmd64["使用 AMD64 镜像"]
UseArm64 --> Fallback["使用默认镜像"]
UseAmd64 --> Fallback
Fallback --> Done(["结束"])
UseGeneric --> Done
Err --> Done

图表来源

章节来源

工具集：平台检测、镜像兼容性与配置加载

  • 平台检测：自动检测系统架构并返回 Docker 平台字符串，支持环境变量覆盖
  • 镜像兼容性：根据镜像标签判断与当前平台的兼容性
  • 配置加载：从环境变量与 rcoder 配置加载 DockerManagerConfig，支持网络模式、工作目录、自动清理、容器 TTL、默认镜像等
  • 容器命名：使用 project_id 生成稳定容器名称，便于管理与调试
flowchart TD
A["获取环境变量"] --> B["检测平台"]
B --> C{"平台是否来自环境变量?"}
C --> |是| D["使用环境变量平台"]
C --> |否| E["自动检测平台"]
D --> F["加载 DockerManagerConfig"]
E --> F
F --> G["应用 rcoder 配置覆盖"]
G --> H["生成默认镜像(按架构)"]

图表来源

章节来源

容器自检测：容器内路径解析

  • 在容器内部通过 Docker API 获取自身挂载信息，解析容器内路径到宿主机路径
  • 提供容器路径到宿主机路径的解析器，支持已知路径的硬编码映射与通用路径解析
sequenceDiagram
participant INS as "容器自检测器"
participant DC as "Docker 守护进程"
INS->>DC : inspect 当前容器
DC-->>INS : 返回挂载信息
INS->>INS : 解析目标容器路径
INS-->>INS : 返回宿主机绝对路径

图表来源

章节来源

停止策略：启动时清理与运行时清理

  • 启动时清理：并发停止匹配模式的容器，使用较短超时，过滤 409 冲突错误，快速清理遗留容器
  • 运行时清理：单个或批量容器停止，使用较短超时，超时后强制停止，快速释放资源
flowchart TD
Start(["开始"]) --> Mode{"清理模式"}
Mode --> |启动时| Startup["并发停止匹配容器"]
Mode --> |运行时| Runtime["单个/批量停止"]
Startup --> Timeout["短超时(5s)"]
Runtime --> ShortTimeout["短超时(3s)"]
Timeout --> Force["超时后强制停止"]
ShortTimeout --> Force
Force --> Stats["统计成功/失败/耗时"]
Stats --> End(["结束"])

图表来源

章节来源

rcoder 服务层：容器编排与服务 URL 生成

  • 容器编排：按项目维度检查/创建容器，动态获取网络名称，生成服务 URL
  • 服务 URL：通过 Docker API 获取容器在动态网络中的 IP，拼接服务端口生成 URL
  • 与 docker_manager 的交互：调用 DockerManager 的容器创建、网络信息查询、服务配置获取等
sequenceDiagram
participant RC as "ContainerManager"
participant DM as "DockerManager"
participant DC as "Docker 守护进程"
RC->>DM : 获取动态网络名称
DM-->>RC : 返回网络名称
RC->>DM : 获取容器网络信息
DM->>DC : inspect 容器
DC-->>DM : 返回网络IP
DM-->>RC : 返回网络IP映射
RC-->>RC : 生成服务URL

图表来源

章节来源

依赖关系分析

  • docker_manager 依赖 bollard 与 DashMap，提供 Docker 客户端、并发容器映射与错误类型
  • rcoder 服务层依赖 docker_manager 的全局实例与容器信息结构
  • shared_types 提供多镜像配置与服务镜像配置模型，被 docker_manager 与 rcoder 共同使用
  • docker 目录提供运行时镜像与编排网络，与 rcoder 服务层配合实现容器化部署
graph LR
RC["rcoder 服务层"] --> DM["docker_manager"]
DM --> ST["shared_types"]
DM --> BOL["bollard"]
DM --> DMAP["DashMap"]
RC --> DM
ST --> MIC["MultiImageConfig"]
ST --> SIC["ServiceImageConfig"]

图表来源

章节来源

性能考虑

  • 并发停止：启动时清理与运行时批量清理均采用并发任务，显著缩短清理时间
  • 超时控制：启动时使用较短超时（5s），运行时使用更短超时（3s），在保证稳定性的同时快速回收资源
  • 网络连接：容器创建时直接连接到动态检测的网络，避免跨网络通信开销
  • 资源限制：通过 HostConfig 的内存、CPU、交换限制实现资源隔离，避免资源争用
  • 镜像拉取：仅在本地不存在时拉取镜像，减少重复下载

章节来源

故障排查指南

  • Docker 连接失败
    • 现象：初始化 DockerManager 报错
    • 排查：确认 DOCKER_HOST 环境变量、Docker 守护进程状态、socket 权限
    • 参考：DockerError::ConnectionError
  • 容器创建失败
    • 现象：创建容器报错
    • 排查：检查镜像是否存在、挂载路径、网络名称、资源限制参数
    • 参考：DockerError::ContainerCreationError
  • 容器启动失败
    • 现象：容器创建后立即退出
    • 排查：查看容器日志、健康检查状态、入口点与命令、环境变量
    • 参考：DockerError::ContainerStartError、get_container_logs
  • 容器停止失败
    • 现象：删除容器报错
    • 排查：忽略 409 冲突错误（已在启动清理中处理）；检查容器是否已删除或正在删除
    • 参考：DockerError::ContainerStopError、DockerError::ContainerRemoveError
  • 镜像拉取失败
    • 现象：ensure_image_exists 失败
    • 排查：检查镜像仓库可达性、认证配置、网络策略
    • 参考：DockerError::ImagePullError
  • 网络不存在
    • 现象：ensure_rcoder_network 失败
    • 排查：确认 docker-compose 网络已创建、主容器处于预期网络
    • 参考：DockerError::ConnectionError
  • 容器自检测失败
    • 现象：无法解析容器内路径到宿主机路径
    • 排查：确认 Docker socket 挂载与权限、/proc 文件系统可读
    • 参考：ContainerSelfInspector::detect_host_path_for_container_dir

章节来源

结论

本项目通过 docker_manager 提供了完善的容器化管理能力：统一的 Docker 客户端封装、灵活的多镜像配置与架构适配、稳定的容器生命周期管理、资源隔离与网络连接、以及容器内部路径解析与高效停止策略。rcoder 服务层在此基础上实现了按项目维度的容器编排与服务 URL 生成，整体架构清晰、扩展性强，既满足初学者快速上手，也为高级用户提供深入定制的空间。

附录

配置选项与参数说明

  • DockerManagerConfig
    • docker_host：Docker 守护进程地址（可选）
    • default_image：默认镜像
    • default_platform：默认平台（如 linux/amd64）
    • default_network_mode：默认网络模式（如 bridge）
    • default_work_dir：默认工作目录
    • auto_cleanup：是否启用自动清理
    • container_ttl_seconds：容器存活时间（秒）
    • multi_image_config：多镜像配置（来自 rcoder 配置）
  • DockerContainerConfig
    • project_id：项目标识
    • image：镜像名称
    • name_prefix：容器名称前缀
    • host_path：宿主机路径
    • container_path：容器内路径
    • work_dir：工作目录
    • env_vars：环境变量
    • port_bindings：端口映射
    • network_mode：网络模式
    • auto_remove：容器停止后自动删除
    • resource_limits：资源限制（内存、CPU、交换）
    • extra_mounts：额外挂载点
    • command：启动命令
    • entrypoint：入口点
    • network_name：网络名称（可选）
  • DockerConfig（rcoder 配置）
    • multi_image_config：多镜像配置
    • network_mode：网络模式
    • work_dir：工作目录
    • auto_cleanup：自动清理
    • container_ttl_seconds：容器存活时间（秒）

章节来源

运行时镜像与编排

  • Dockerfile：包含调试工具与健康检查，暴露端口，设置环境变量
  • docker-compose.yml：定义 rcoder 服务、端口映射、环境变量、卷挂载、健康检查、网络

章节来源

Reference in New Issue View Git Blame Copy Permalink