byy/qiming
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
751ce4561984555cd711cfa2752e7d9f0ddf8e9d
qiming/qiming-rcoder/.qoder/repowiki/zh/content/部署指南/Docker部署.md
Codex 4b1a580132 添加qiming-rcoder模块
2026-06-01 13:54:52 +08:00

320 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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部署方案设计精良，采用了多阶段构建策略，确保了生产环境的安全性和效率。调试镜像包含了丰富的诊断工具，为生产环境的问题排查提供了强大支持。构建和部署脚本自动化了整个流程，降低了人为错误的风险。通过合理的配置管理和卷挂载策略，实现了配置与代码的分离，提高了部署的灵活性。整体方案既适合初学者快速上手，也为高级用户提供了深入优化和调试的可能性。
Reference in New Issue View Git Blame Copy Permalink