添加qiming-rcoder模块

2026-06-01 13:54:52 +08:00
parent 8092c4b1f8
commit 4b1a580132
539 changed files with 151650 additions and 0 deletions
--- a/qiming-rcoder/.qoder/repowiki/zh/content/部署指南/部署指南.md
+++ b/qiming-rcoder/.qoder/repowiki/zh/content/部署指南/部署指南.md
@@ -0,0 +1,347 @@
+# 部署指南
+
+<cite>
+**本文档中引用的文件**  
+- [Dockerfile](file://docker/Dockerfile)
+- [docker-compose.yml](file://docker/docker-compose.yml)
+- [rcoder-service.sh](file://rcoder-service.sh)
+- [start-rcoder.sh](file://docker/start-rcoder.sh)
+- [build.sh](file://docker/scripts/build.sh)
+- [deploy.sh](file://docker/scripts/deploy.sh)
+- [config.yml](file://config.yml)
+- [main.rs](file://crates/rcoder/src/main.rs)
+- [config.rs](file://crates/rcoder/src/config.rs)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [Docker部署](#docker部署)
+3. [Docker Compose配置](#docker-compose配置)
+4. [生产环境配置](#生产环境配置)
+5. [systemd服务实现](#systemd服务实现)
+6. [常见问题及解决方案](#常见问题及解决方案)
+7. [总结](#总结)
+
+## 简介
+本部署指南详细介绍了RCoder项目的部署流程，包括Docker部署、Docker Compose配置、生产环境配置和systemd服务实现。文档提供了具体的配置选项、参数说明和返回值解释，并阐述了各组件之间的关系。通过本指南，初学者可以快速上手部署，而经验丰富的开发人员可以获得足够的技术深度。
+
+## Docker部署
+RCoder项目提供了完整的Docker部署方案，包括多阶段构建、调试工具集成和生产环境优化。
+
+### Dockerfile分析
+Dockerfile采用多阶段构建策略，分为编译阶段和运行阶段。编译阶段使用`rust:1.90-bookworm`镜像进行编译，运行阶段则基于相同的镜像但包含完整的调试工具。
+
+```mermaid
+graph TD
+A[Dockerfile] --> B[多阶段构建]
+B --> C[编译阶段]
+B --> D[运行阶段]
+C --> E[安装编译依赖]
+C --> F[编译release版本]
+D --> G[安装运行时依赖]
+D --> H[安装调试工具]
+D --> I[复制二进制文件]
+```
+
+**Diagram sources**
+- [Dockerfile](file://docker/Dockerfile#L12-L115)
+
+**Section sources**
+- [Dockerfile](file://docker/Dockerfile#L1-L305)
+
+### 构建脚本
+项目提供了`build.sh`脚本用于构建Docker镜像，该脚本会检查必要的文件并执行构建命令。
+
+```mermaid
+flowchart TD
+Start([开始构建]) --> CheckFiles["检查必要文件"]
+CheckFiles --> BuildImage["执行docker build命令"]
+BuildImage --> Success["构建成功"]
+BuildImage --> Failure["构建失败"]
+Success --> End([结束])
+Failure --> End
+```
+
+**Diagram sources**
+- [build.sh](file://docker/scripts/build.sh#L1-L21)
+
+**Section sources**
+- [build.sh](file://docker/scripts/build.sh#L1-L21)
+
+## Docker Compose配置
+Docker Compose配置文件定义了RCoder服务的运行环境，包括端口映射、环境变量和卷挂载。
+
+### docker-compose.yml分析
+docker-compose.yml文件配置了RCoder服务的关键参数，包括镜像名称、端口映射、环境变量和卷挂载。
+
+```mermaid
+graph TD
+A[docker-compose.yml] --> B[服务定义]
+B --> C[镜像配置]
+B --> D[端口映射]
+B --> E[环境变量]
+B --> F[卷挂载]
+B --> G[健康检查]
+B --> H[重启策略]
+C --> I[使用RCODER_IMAGE环境变量]
+D --> J[映射RCODER_PORT端口]
+E --> K[设置时区和日志级别]
+F --> L[挂载Docker socket]
+F --> M[挂载项目工作目录]
+F --> N[挂载日志目录]
+F --> O[挂载启动脚本]
+```
+
+**Diagram sources**
+- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
+
+**Section sources**
+- [docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
+
+### 部署脚本
+`deploy.sh`脚本自动化了部署流程，包括检查必要文件、构建镜像和启动服务。
+
+```mermaid
+flowchart TD
+Start([开始部署]) --> CheckFiles["检查必要文件"]
+CheckFiles --> CheckImage["检查镜像是否存在"]
+CheckImage --> Build["构建镜像"]
+CheckImage --> Start["启动服务"]
+Build --> Start
+Start --> Success["部署成功"]
+Start --> Failure["部署失败"]
+Success --> End([结束])
+Failure --> End
+```
+
+**Diagram sources**
+- [deploy.sh](file://docker/scripts/deploy.sh#L1-L42)
+
+**Section sources**
+- [deploy.sh](file://docker/scripts/deploy.sh#L1-L42)
+
+## 生产环境配置
+生产环境配置涉及多个方面，包括配置文件、环境变量和安全设置。
+
+### 配置文件
+`config.yml`文件包含了RCoder服务的主要配置选项，包括默认代理类型、项目工作目录、端口设置和Docker配置。
+
+```mermaid
+graph TD
+A[config.yml] --> B[基本配置]
+A --> C[代理配置]
+A --> D[Docker配置]
+B --> E[default_agent]
+B --> F[projects_dir]
+B --> G[port]
+C --> H[listen_port]
+C --> I[default_backend_port]
+C --> J[backend_host]
+C --> K[port_param]
+D --> L[multi_image_config]
+D --> M[network_mode]
+D --> N[work_dir]
+D --> O[auto_cleanup]
+D --> P[container_ttl_seconds]
+```
+
+**Diagram sources**
+- [config.yml](file://config.yml#L1-L161)
+
+**Section sources**
+- [config.yml](file://config.yml#L1-L161)
+
+### 环境变量
+RCoder服务支持通过环境变量覆盖配置文件中的设置，提供了灵活的配置方式。
+
+```mermaid
+flowchart TD
+A[环境变量] --> B[RUST_LOG]
+A --> C[PORT]
+A --> D[DOCKER_SOCKET_PATH]
+A --> E[RCODER_WORKSPACE]
+A --> F[RCODER_LOGS]
+A --> G[RCODER_NETWORK_MODE]
+A --> H[RCODER_WORK_DIR]
+A --> I[RCODER_AUTO_CLEANUP]
+A --> J[RCODER_CONTAINER_TTL]
+B --> K[设置日志级别]
+C --> L[设置服务端口]
+D --> M[设置Docker socket路径]
+E --> N[设置工作目录]
+F --> O[设置日志目录]
+G --> P[设置网络模式]
+H --> Q[设置工作目录]
+I --> R[设置自动清理]
+J --> S[设置容器存活时间]
+```
+
+**Section sources**
+- [main.rs](file://crates/rcoder/src/main.rs#L49-L53)
+- [config.rs](file://crates/rcoder/src/config.rs#L214-L236)
+
+### 启动脚本
+`start-rcoder.sh`脚本负责启动RCoder服务，设置了必要的环境变量并创建了所需的目录。
+
+```mermaid
+flowchart TD
+Start([开始启动]) --> SetEnv["设置环境变量"]
+SetEnv --> CreateDir["创建必要目录"]
+CreateDir --> PrintConfig["打印环境配置"]
+PrintConfig --> StartService["启动rcoder服务"]
+StartService --> End([结束])
+```
+
+**Diagram sources**
+- [start-rcoder.sh](file://docker/start-rcoder.sh#L1-L23)
+
+**Section sources**
+- [start-rcoder.sh](file://docker/start-rcoder.sh#L1-L23)
+
+## systemd服务实现
+systemd服务实现通过`rcoder-service.sh`脚本提供，支持启动、停止、重启和状态查询等操作。
+
+### 服务管理脚本
+`rcoder-service.sh`脚本提供了完整的服务管理功能，包括依赖检查、PID管理、日志记录和信号处理。
+
+```mermaid
+graph TD
+A[rcoder-service.sh] --> B[配置区域]
+A --> C[工具函数]
+A --> D[服务控制函数]
+A --> E[主函数]
+B --> F[端口设置]
+B --> G[可执行文件路径]
+B --> H[工作目录]
+B --> I[日志文件]
+B --> J[PID文件]
+B --> K[PATH设置]
+B --> L[日志级别]
+C --> M[info函数]
+C --> N[warn函数]
+C --> O[error函数]
+C --> P[status_msg函数]
+C --> Q[check_dependencies函数]
+C --> R[get_pid函数]
+C --> S[is_running函数]
+D --> T[start函数]
+D --> U[stop函数]
+D --> V[restart函数]
+D --> W[status函数]
+E --> X[main函数]
+```
+
+**Diagram sources**
+- [rcoder-service.sh](file://rcoder-service.sh#L1-L328)
+
+**Section sources**
+- [rcoder-service.sh](file://rcoder-service.sh#L1-L328)
+
+### 服务控制流程
+服务控制流程包括启动、停止、重启和状态查询四个主要操作，每个操作都有详细的错误处理和日志记录。
+
+```mermaid
+flowchart TD
+A[主函数] --> B[解析命令行参数]
+B --> C{命令}
+C --> D[start]
+C --> E[stop]
+C --> F[restart]
+C --> G[status]
+D --> H[检查依赖]
+H --> I[启动服务]
+I --> J[保存PID]
+E --> K[检查是否运行]
+K --> L[停止服务]
+L --> M[清理PID文件]
+F --> N[调用stop]
+N --> O[调用start]
+G --> P[检查运行状态]
+P --> Q[显示状态信息]
+```
+
+**Section sources**
+- [rcoder-service.sh](file://rcoder-service.sh#L289-L327)
+
+## 常见问题及解决方案
+本节列出了部署过程中可能遇到的常见问题及其解决方案。
+
+### Docker socket权限问题
+当容器无法访问Docker socket时，会出现权限错误。
+
+**问题表现**：
+- 服务启动失败
+- 日志中出现"Permission denied"错误
+- 无法创建或管理容器
+
+**解决方案**：
+1. 确保Docker服务正在运行
+2. 检查Docker socket文件是否存在
+3. 确保用户在docker组中
+4. 在docker-compose.yml中正确挂载Docker socket
+
+```mermaid
+flowchart TD
+A[权限问题] --> B[检查Docker服务]
+B --> C[检查socket文件]
+C --> D[检查用户组]
+D --> E[正确挂载socket]
+E --> F[解决问题]
+```
+
+**Section sources**
+- [main.rs](file://crates/rcoder/src/main.rs#L49-L53)
+- [docker-compose.yml](file://docker/docker-compose.yml#L11-L15)
+
+### 配置文件加载问题
+当配置文件不存在或格式错误时，服务可能无法正常启动。
+
+**问题表现**：
+- 服务启动失败
+- 日志中出现"Failed to load config"错误
+- 使用默认配置而非自定义配置
+
+**解决方案**：
+1. 检查配置文件是否存在
+2. 验证YAML格式是否正确
+3. 确保配置文件路径正确
+4. 检查文件权限
+
+```mermaid
+flowchart TD
+A[配置问题] --> B[检查文件存在]
+B --> C[验证YAML格式]
+C --> D[检查路径正确]
+D --> E[检查文件权限]
+E --> F[解决问题]
+```
+
+**Section sources**
+- [config.rs](file://crates/rcoder/src/config.rs#L255-L272)
+
+### 网络隔离配置
+`setup-network-isolation.sh`脚本用于配置Docker容器的网络隔离规则，防止容器访问内网地址。
+
+```mermaid
+flowchart TD
+Start([开始配置]) --> CheckRoot["检查root权限"]
+CheckRoot --> CheckIptables["检查iptables安装"]
+CheckIptables --> FindNetworks["查找rcoder-网络"]
+FindNetworks --> Loop["遍历每个网络"]
+Loop --> GetSubnet["获取子网"]
+GetSubnet --> CheckRules["检查规则存在"]
+CheckRules --> AddRules["添加DROP规则"]
+AddRules --> Next["下一个网络"]
+Next --> Loop
+Loop --> PrintRules["打印当前规则"]
+PrintRules --> End([结束])
+```
+
+**Diagram sources**
+- [setup-network-isolation.sh](file://scripts/setup-network-isolation.sh#L1-L112)
+
+**Section sources**
+- [setup-network-isolation.sh](file://scripts/setup-network-isolation.sh#L1-L112)
+
+## 总结
+本部署指南详细介绍了RCoder项目的部署流程，涵盖了Docker部署、Docker Compose配置、生产环境配置和systemd服务实现。通过本指南，用户可以全面了解RCoder的部署架构和配置选项，解决常见问题，并根据实际需求进行定制化部署。文档提供了足够的技术深度，既适合初学者快速上手，也为经验丰富的开发人员提供了详细的参考。