添加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/部署指南/Docker部署.md
+++ b/qiming-rcoder/.qoder/repowiki/zh/content/部署指南/Docker部署.md
@@ -0,0 +1,320 @@
+# Docker部署
+
+<cite>
+**本文档引用的文件**
+- [Dockerfile](file://docker/Dockerfile)
+- [build-docker-image.sh](file://docker/scripts/build-docker-image.sh)
+- [docker-compose.yml](file://docker/docker-compose.yml)
+- [.dockerignore](file://.dockerignore)
+- [start-rcoder.sh](file://docker/start-rcoder.sh)
+- [deploy.sh](file://docker/scripts/deploy.sh)
+- [analyze-rcoder.sh](file://docker/scripts/analyze-rcoder.sh)
+- [generate-flamegraph.sh](file://docker/scripts/generate-flamegraph.sh)
+- [diagnose-blocking.sh](file://docker/scripts/diagnose-blocking.sh)
+- [rcoder-service.sh](file://rcoder-service.sh)
+- [config.yml](file://config.yml)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构概述](#架构概述)
+5. [详细组件分析](#详细组件分析)
+6. [依赖分析](#依赖分析)
+7. [性能考虑](#性能考虑)
+8. [故障排除指南](#故障排除指南)
+9. [结论](#结论)
+
+## 简介
+本文档详细介绍了Rcoder项目的Docker部署方案。文档深入解析了多阶段构建过程、基础镜像选择、依赖安装和二进制文件复制策略。通过实际代码库中的具体示例，展示了构建脚本`build-docker-image.sh`的使用方法和参数配置。文档还记录了环境变量、挂载卷和网络配置的最佳实践，解释了Docker部署与rcoder主服务的集成关系，并提供了常见构建失败、权限问题和容器启动错误的解决方案。为初学者提供逐步指导的同时，也为高级用户提供性能优化和安全加固建议。
+
+## 项目结构
+
+```mermaid
+graph TD
+Docker["Docker 部署"]
+Docker --> Scripts["docker/scripts/"]
+Docker --> Config["docker/"]
+Docker --> Root["项目根目录"]
+Scripts --> build_image["build-docker-image.sh"]
+Scripts --> deploy["deploy.sh"]
+Scripts --> start["start-rcoder.sh"]
+Scripts --> analyze["analyze-rcoder.sh"]
+Scripts --> diagnose["diagnose-blocking.sh"]
+Scripts --> flamegraph["generate-flamegraph.sh"]
+Config --> Dockerfile["Dockerfile"]
+Config --> compose["docker-compose.yml"]
+Config --> start_script["start-rcoder.sh"]
+Root --> dockerignore[".dockerignore"]
+Root --> service_script["rcoder-service.sh"]
+Root --> config["config.yml"]
+```
+
+**图源**
+- [docker/Dockerfile](file://docker/Dockerfile)
+- [docker/scripts/](file://docker/scripts/)
+- [docker-compose.yml](file://docker/docker-compose.yml)
+
+**本节来源**
+- [docker/Dockerfile](file://docker/Dockerfile)
+- [docker/scripts/](file://docker/scripts/)
+- [docker-compose.yml](file://docker/docker-compose.yml)
+
+## 核心组件
+
+本文档的核心组件包括Docker多阶段构建系统、调试工具集、部署脚本和配置管理。Dockerfile采用多阶段构建策略，分离编译和运行环境，确保生产镜像的轻量化和安全性。构建脚本`build-docker-image.sh`自动化了镜像构建流程，而`deploy.sh`脚本则提供了完整的部署解决方案。调试工具集包括`analyze-rcoder.sh`、`diagnose-blocking.sh`和`generate-flamegraph.sh`，为生产环境的问题诊断提供了强大支持。
+
+**本节来源**
+- [docker/Dockerfile](file://docker/Dockerfile)
+- [docker/scripts/build-docker-image.sh](file://docker/scripts/build-docker-image.sh)
+- [docker/scripts/deploy.sh](file://docker/scripts/deploy.sh)
+
+## 架构概述
+
+```mermaid
+graph TD
+Build["构建阶段"]
+Runtime["运行时阶段"]
+Deployment["部署阶段"]
+Debug["调试工具"]
+Build --> |"FROM rust:1.90-bookworm AS builder"| Builder["编译器镜像"]
+Builder --> |"cargo build --release"| Binary["rcoder 二进制"]
+Runtime --> |"FROM rust:1.90-bookworm"| RuntimeImage["运行时镜像"]
+RuntimeImage --> |"COPY --from=builder"| CopyBinary["复制二进制"]
+RuntimeImage --> |"安装调试工具"| DebugTools["调试工具集"]
+RuntimeImage --> |"创建用户和目录"| Setup["环境设置"]
+Deployment --> |"docker-compose up"| Container["容器实例"]
+Container --> |"挂载卷"| Volumes["卷挂载"]
+Container --> |"环境变量"| Env["环境配置"]
+Container --> |"网络配置"| Network["网络设置"]
+Debug --> |"analyze-rcoder"| Process["进程分析"]
+Debug --> |"diagnose-blocking"| Blocking["阻塞诊断"]
+Debug --> |"generate-flamegraph"| Performance["性能分析"]
+Build --> Runtime
+Runtime --> Deployment
+Deployment --> Debug
+```
+
+**图源**
+- [docker/Dockerfile](file://docker/Dockerfile)
+- [docker-compose.yml](file://docker/docker-compose.yml)
+- [docker/scripts/](file://docker/scripts/)
+
+## 详细组件分析
+
+### Docker多阶段构建分析
+
+```mermaid
+graph TD
+Stage1["构建阶段"]
+Stage2["运行时阶段"]
+subgraph Stage1
+A["基础镜像: rust:1.90-bookworm"]
+B["安装编译依赖"]
+C["复制源码"]
+D["编译release版本"]
+E["安装Rust调试工具"]
+A --> B --> C --> D --> E
+end
+subgraph Stage2
+F["基础镜像: rust:1.90-bookworm"]
+G["设置环境变量"]
+H["安装运行时和调试依赖"]
+I["创建应用用户和目录"]
+J["从构建阶段复制二进制"]
+K["复制启动脚本"]
+L["创建调试工具脚本"]
+M["设置工作目录和权限"]
+N["暴露端口"]
+O["健康检查"]
+P["启动命令"]
+F --> G --> H --> I --> J --> K --> L --> M --> N --> O --> P
+end
+E --> |"COPY --from=builder"| J
+```
+
+**图源**
+- [docker/Dockerfile](file://docker/Dockerfile#L12-L304)
+
+**本节来源**
+- [docker/Dockerfile](file://docker/Dockerfile#L12-L304)
+
+### 构建脚本分析
+
+```mermaid
+flowchart TD
+Start["开始构建"]
+Start --> Check["检查Dockerfile存在"]
+Check --> |"存在"| BuildBinary["构建rcoder二进制"]
+Check --> |"不存在"| Error1["报错退出"]
+BuildBinary --> |"成功"| BuildImage["构建Docker镜像"]
+BuildBinary --> |"失败"| Error2["报错退出"]
+BuildImage --> |"成功"| Success["构建成功"]
+BuildImage --> |"失败"| Error3["报错退出"]
+Success --> Info["显示使用方式"]
+Info --> End["结束"]
+Error1 --> End
+Error2 --> End
+Error3 --> End
+```
+
+**图源**
+- [docker/scripts/build-docker-image.sh](file://docker/scripts/build-docker-image.sh#L1-L38)
+
+**本节来源**
+- [docker/scripts/build-docker-image.sh](file://docker/scripts/build-docker-image.sh#L1-L38)
+
+### 部署脚本分析
+
+```mermaid
+flowchart TD
+Start["开始部署"]
+Start --> CheckFiles["检查必要文件"]
+CheckFiles --> |"存在"| CheckImage["检查镜像是否存在"]
+CheckFiles --> |"不存在"| Error1["报错退出"]
+CheckImage --> |"存在"| StartService["启动服务"]
+CheckImage --> |"不存在"| BuildImage["构建镜像"]
+BuildImage --> |"成功"| StartService
+BuildImage --> |"失败"| Error2["报错退出"]
+StartService --> |"成功"| Success["部署成功"]
+StartService --> |"失败"| Error3["报错退出"]
+Success --> Commands["显示管理命令"]
+Commands --> End["结束"]
+Error1 --> End
+Error2 --> End
+Error3 --> End
+```
+
+**图源**
+- [docker/scripts/deploy.sh](file://docker/scripts/deploy.sh#L1-L42)
+
+**本节来源**
+- [docker/scripts/deploy.sh](file://docker/scripts/deploy.sh#L1-L42)
+
+### 调试工具分析
+
+```mermaid
+graph TD
+DebugTools["调试工具集"]
+DebugTools --> Analyze["analyze-rcoder.sh"]
+DebugTools --> Diagnose["diagnose-blocking.sh"]
+DebugTools --> Flamegraph["generate-flamegraph.sh"]
+Analyze --> |"功能"| A1["进程基本信息"]
+Analyze --> |"功能"| A2["线程状态"]
+Analyze --> |"功能"| A3["网络连接"]
+Analyze --> |"功能"| A4["文件描述符"]
+Analyze --> |"功能"| A5["内存使用"]
+Diagnose --> |"功能"| D1["进程状态"]
+Diagnose --> |"功能"| D2["网络队列"]
+Diagnose --> |"功能"| D3["阻塞线程"]
+Diagnose --> |"功能"| D4["系统资源"]
+Diagnose --> |"功能"| D5["错误日志"]
+Diagnose --> |"功能"| D6["死锁检查"]
+Flamegraph --> |"功能"| F1["性能采样"]
+Flamegraph --> |"功能"| F2["火焰图生成"]
+Flamegraph --> |"功能"| F3["结果分析"]
+Flamegraph --> |"功能"| F4["问题定位"]
+```
+
+**图源**
+- [docker/scripts/analyze-rcoder.sh](file://docker/scripts/analyze-rcoder.sh)
+- [docker/scripts/diagnose-blocking.sh](file://docker/scripts/diagnose-blocking.sh)
+- [docker/scripts/generate-flamegraph.sh](file://docker/scripts/generate-flamegraph.sh)
+
+**本节来源**
+- [docker/scripts/analyze-rcoder.sh](file://docker/scripts/analyze-rcoder.sh)
+- [docker/scripts/diagnose-blocking.sh](file://docker/scripts/diagnose-blocking.sh)
+- [docker/scripts/generate-flamegraph.sh](file://docker/scripts/generate-flamegraph.sh)
+
+## 依赖分析
+
+```mermaid
+graph LR
+Dockerfile --> rust["rust:1.90-bookworm"]
+Dockerfile --> cargo["Cargo"]
+Dockerfile --> apt["apt-get"]
+build_script --> docker["Docker"]
+build_script --> cargo["Cargo"]
+deploy_script --> docker_compose["docker-compose"]
+deploy_script --> build_script["build.sh"]
+start_script --> rcoder["rcoder 二进制"]
+start_script --> bash["bash"]
+config --> yaml["YAML"]
+rust --> openssl["libssl-dev"]
+rust --> protobuf["protobuf-compiler"]
+rust --> build_essential["build-essential"]
+runtime --> curl["curl"]
+runtime --> jq["jq"]
+runtime --> gdb["gdb"]
+runtime --> strace["strace"]
+runtime --> htop["htop"]
+runtime --> tcpdump["tcpdump"]
+```
+
+**图源**
+- [docker/Dockerfile](file://docker/Dockerfile)
+- [docker/scripts/build-docker-image.sh](file://docker/scripts/build-docker-image.sh)
+- [docker/scripts/deploy.sh](file://docker/scripts/deploy.sh)
+
+**本节来源**
+- [docker/Dockerfile](file://docker/Dockerfile)
+- [docker/scripts/build-docker-image.sh](file://docker/scripts/build-docker-image.sh)
+- [docker/scripts/deploy.sh](file://docker/scripts/deploy.sh)
+
+## 性能考虑
+
+Rcoder的Docker部署在性能方面进行了多项优化。多阶段构建确保了运行时镜像的轻量化，减少了攻击面和启动时间。调试镜像包含了完整的性能分析工具集，包括`perf`、`flamegraph`和`strace`，可以进行深入的性能分析。`generate-flamegraph.sh`脚本自动化了火焰图的生成过程，帮助开发者快速定位性能瓶颈。`diagnose-blocking.sh`脚本专门用于诊断阻塞问题，通过分析线程状态和系统调用，快速发现潜在的性能问题。
+
+**本节来源**
+- [docker/Dockerfile](file://docker/Dockerfile)
+- [docker/scripts/generate-flamegraph.sh](file://docker/scripts/generate-flamegraph.sh)
+- [docker/scripts/diagnose-blocking.sh](file://docker/scripts/diagnose-blocking.sh)
+
+## 故障排除指南
+
+### 常见构建失败解决方案
+
+```mermaid
+flowchart TD
+BuildFail["构建失败"]
+BuildFail --> CheckDockerfile["检查Dockerfile存在"]
+CheckDockerfile --> |"不存在"| CreateDockerfile["创建Dockerfile"]
+CheckDockerfile --> |"存在"| CheckNetwork["检查网络连接"]
+CheckNetwork --> |"连接失败"| FixNetwork["修复网络"]
+CheckNetwork --> |"连接正常"| CheckDependencies["检查依赖"]
+CheckDependencies --> |"依赖缺失"| InstallDependencies["安装依赖"]
+CheckDependencies --> |"依赖完整"| CheckSource["检查源码"]
+CheckSource --> |"源码损坏"| RestoreSource["恢复源码"]
+CheckSource --> |"源码正常"| CheckDisk["检查磁盘空间"]
+CheckDisk --> |"空间不足"| FreeSpace["清理空间"]
+CheckDisk --> |"空间充足"| CheckPermissions["检查权限"]
+CheckPermissions --> |"权限不足"| FixPermissions["修复权限"]
+CheckPermissions --> |"权限正常"| CheckConfig["检查配置"]
+CheckConfig --> |"配置错误"| FixConfig["修复配置"]
+CheckConfig --> |"配置正确"| SeekHelp["寻求帮助"]
+```
+
+**本节来源**
+- [docker/scripts/build-docker-image.sh](file://docker/scripts/build-docker-image.sh)
+- [docker/Dockerfile](file://docker/Dockerfile)
+
+### 权限问题解决方案
+
+当遇到权限问题时，首先检查Docker守护进程是否正在运行，并确保当前用户有权限访问Docker socket。如果使用`sudo`运行Docker命令，考虑将用户添加到`docker`组以避免权限问题。对于容器内部的权限问题，检查Dockerfile中是否正确创建了应用用户，并确保挂载卷的权限设置正确。
+
+**本节来源**
+- [docker/Dockerfile](file://docker/Dockerfile)
+- [docker/docker-compose.yml](file://docker/docker-compose.yml)
+
+### 容器启动错误解决方案
+
+容器启动错误可能由多种原因引起。首先检查`docker-compose.yml`文件中的配置是否正确，特别是端口映射和卷挂载。使用`docker logs`命令查看容器日志，定位具体的错误信息。如果遇到依赖缺失问题，确保所有必要的依赖都已正确安装。对于网络问题，检查容器的网络配置和防火墙设置。
+
+**本节来源**
+- [docker/docker-compose.yml](file://docker/docker-compose.yml)
+- [docker/scripts/deploy.sh](file://docker/scripts/deploy.sh)
+
+## 结论
+
+Rcoder项目的Docker部署方案设计精良，采用了多阶段构建策略，确保了生产环境的安全性和效率。调试镜像包含了丰富的诊断工具，为生产环境的问题排查提供了强大支持。构建和部署脚本自动化了整个流程，降低了人为错误的风险。通过合理的配置管理和卷挂载策略，实现了配置与代码的分离，提高了部署的灵活性。整体方案既适合初学者快速上手，也为高级用户提供了深入优化和调试的可能性。