添加qiming-rcoder模块

qiming-rcoder/.qoder/repowiki/zh/content/部署指南/systemd服务管理.md

@@ -0,0 +1,296 @@
+# systemd服务管理
+
+<cite>
+**本文引用的文件**
+- [rcoder-service.sh](file://rcoder-service.sh)
+- [README.md](file://README.md)
+- [docker/scripts/start-rcoder.sh](file://docker/scripts/start-rcoder.sh)
+- [docker/Dockerfile](file://docker/Dockerfile)
+- [docker/docker-compose.yml](file://docker/docker-compose.yml)
+- [Cargo.toml](file://Cargo.toml)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考虑](#性能考虑)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本文件面向运维与开发团队，系统性阐述如何将 rcoder 服务通过 systemd 进行开机自启、自动重启与状态监控，并结合仓库内的脚本与配置，给出完整的集成方案与最佳实践。重点覆盖：
+- rcoder-service.sh 与 systemd 的集成方式与差异
+- systemd 服务单元文件的编写要点（[Service]、[Install]、[Timer]）
+- start-rcoder.sh 在 systemd 上下文中的执行流程与环境准备
+- 日志查看、状态查询与故障排查的标准操作
+- 权限管理、资源限制与安全沙箱的配置建议
+- 常见问题（启动失败、权限不足、依赖未就绪）的定位与解决
+
+## 项目结构
+围绕 systemd 集成的关键文件与位置如下：
+- systemd 服务单元示例位于 README.md 中，提供标准的 [Unit]/[Service]/[Install] 配置模板
+- rcoder-service.sh 是传统“手动服务管理脚本”，用于本地或非 systemd 场景
+- docker/scripts/start-rcoder.sh 是容器场景下的启动脚本，展示环境变量与工作目录准备
+- docker/Dockerfile 与 docker/docker-compose.yml 展示了容器内健康检查与重启策略
+- Cargo.toml 描述了项目依赖与运行时特性，有助于理解 systemd 下的运行环境
+
+```mermaid
+graph TB
+A["系统服务管理<br/>systemd"] --> B["rcoder 服务单元<br/>rcoder.service"]
+B --> C["可执行文件<br/>/opt/rcoder/target/release/rcoder"]
+B --> D["工作目录<br/>/opt/rcoder"]
+B --> E["环境变量<br/>RUST_LOG, RCODER_PORT 等"]
+F["rcoder-service.sh<br/>本地脚本管理"] -.-> C
+G["docker/scripts/start-rcoder.sh<br/>容器启动脚本"] -.-> C
+H["docker/Dockerfile<br/>健康检查/暴露端口"] --> I["健康检查<br/>/health"]
+J["docker/docker-compose.yml<br/>重启策略/restart: always"] --> B
+```
+
+图表来源
+- [README.md](file://README.md#L560-L583)
+- [rcoder-service.sh](file://rcoder-service.sh#L134-L191)
+- [docker/scripts/start-rcoder.sh](file://docker/scripts/start-rcoder.sh#L1-L23)
+- [docker/Dockerfile](file://docker/Dockerfile#L293-L304)
+- [docker/docker-compose.yml](file://docker/docker-compose.yml#L30-L33)
+
+章节来源
+- [README.md](file://README.md#L560-L583)
+- [rcoder-service.sh](file://rcoder-service.sh#L1-L328)
+- [docker/scripts/start-rcoder.sh](file://docker/scripts/start-rcoder.sh#L1-L23)
+- [docker/Dockerfile](file://docker/Dockerfile#L293-L304)
+- [docker/docker-compose.yml](file://docker/docker-compose.yml#L30-L33)
+
+## 核心组件
+- systemd 服务单元：定义服务行为、用户、工作目录、环境变量、重启策略与安装目标
+- rcoder-service.sh：提供 start/stop/restart/status 的本地脚本化管理，适合非 systemd 场景
+- start-rcoder.sh：容器内启动脚本，负责环境变量注入、目录创建与执行 rcoder
+- 健康检查与重启策略：Dockerfile 的 HEALTHCHECK 与 docker-compose.yml 的 restart: always 体现容器层面的自愈能力
+
+章节来源
+- [README.md](file://README.md#L560-L583)
+- [rcoder-service.sh](file://rcoder-service.sh#L134-L284)
+- [docker/scripts/start-rcoder.sh](file://docker/scripts/start-rcoder.sh#L1-L23)
+- [docker/Dockerfile](file://docker/Dockerfile#L293-L304)
+- [docker/docker-compose.yml](file://docker/docker-compose.yml#L30-L33)
+
+## 架构总览
+下图展示了 systemd 与 rcoder 的典型交互：systemd 启动 rcoder，rcoder 通过健康检查对外提供服务；容器场景下，start-rcoder.sh 负责环境准备与进程启动。
+
+```mermaid
+sequenceDiagram
+participant OS as "操作系统"
+participant SD as "systemd"
+participant SVC as "rcoder.service"
+participant BIN as "rcoder 可执行文件"
+participant LOG as "日志文件"
+participant NET as "网络端口"
+OS->>SD : "enable/start"
+SD->>SVC : "加载单元并初始化"
+SVC->>BIN : "ExecStart 启动进程"
+BIN->>LOG : "写入日志"
+BIN->>NET : "监听端口"
+SVC-->>SD : "健康检查通过/失败"
+SD-->>OS : "自动重启/通知"
+```
+
+图表来源
+- [README.md](file://README.md#L560-L583)
+- [docker/Dockerfile](file://docker/Dockerfile#L293-L304)
+
+## 详细组件分析
+
+### systemd 服务单元文件编写指南
+- [Unit]：描述服务元信息与依赖时机
+  - Description：服务描述
+  - After：在网络就绪后再启动
+- [Service]：核心执行与生命周期控制
+  - Type：simple（systemd 直接管理 ExecStart 进程）
+  - User：指定运行用户（建议独立非 root 用户）
+  - WorkingDirectory：工作目录（存放配置、日志、PID 文件）
+  - ExecStart：启动命令（建议使用绝对路径）
+  - Restart：always（异常退出后自动重启）
+  - RestartSec：重启间隔（避免频繁抖动）
+  - Environment：注入日志级别、端口等环境变量
+- [Install]：安装目标
+  - WantedBy：multi-user.target（多用户运行级别）
+
+章节来源
+- [README.md](file://README.md#L560-L583)
+
+### rcoder-service.sh 与 systemd 的差异与迁移建议
+- rcoder-service.sh 的职责
+  - 依赖检查（可执行文件、Bun/NPM 等）
+  - PID 文件管理与进程状态判断
+  - 日志输出与错误提示
+  - 启停与状态查询
+- 与 systemd 的差异
+  - rcoder-service.sh 为“前台”脚本，systemd 期望“后台”守护进程
+  - rcoder-service.sh 自带 nohup 与日志重定向，systemd 通过 StandardOutput/StandardError 管理日志
+  - rcoder-service.sh 依赖本地 PATH 与工作目录，systemd 通过 WorkingDirectory 与 Environment 管理
+- 迁移建议
+  - 若仍使用 rcoder-service.sh，建议将其作为 ExecStart 的入口脚本，但需确保其按 systemd 期望的“后台”方式运行
+  - 更推荐直接使用 ExecStart 指向 rcoder 可执行文件，并通过 Environment 注入所需变量
+
+章节来源
+- [rcoder-service.sh](file://rcoder-service.sh#L68-L103)
+- [rcoder-service.sh](file://rcoder-service.sh#L134-L191)
+- [rcoder-service.sh](file://rcoder-service.sh#L193-L236)
+- [rcoder-service.sh](file://rcoder-service.sh#L246-L284)
+
+### start-rcoder.sh 在 systemd 上下文中的执行流程与环境准备
+- 环境变量准备
+  - RUST_LOG：日志级别
+  - PORT：服务端口
+  - DOCKER_SOCKET_PATH：Docker 套接字路径
+  - RCODER_WORKSPACE：工作区目录
+- 目录创建
+  - logs 与 workspace 目录确保存在
+- 启动 rcoder
+  - 使用 exec 方式启动，使 systemd 能正确接管进程
+  - 通过 -- 参数传递端口给 rcoder
+
+章节来源
+- [docker/scripts/start-rcoder.sh](file://docker/scripts/start-rcoder.sh#L1-L23)
+
+### systemd 与容器场景的协同
+- docker/Dockerfile
+  - EXPOSE 暴露端口（含 tokio-console 端口）
+  - HEALTHCHECK 对 /health 进行健康检查
+- docker/docker-compose.yml
+  - restart: always 提供容器层面的自愈
+  - 健康检查与端口映射配合 systemd 的外部可用性
+
+章节来源
+- [docker/Dockerfile](file://docker/Dockerfile#L293-L304)
+- [docker/docker-compose.yml](file://docker/docker-compose.yml#L30-L33)
+
+## 依赖关系分析
+- rcoder 服务对运行时环境的依赖
+  - Rust 运行时与日志库（tracing、tracing-subscriber）
+  - HTTP 与异步运行时（tokio、axum、tower）
+  - OpenTelemetry 与 Tokio Console（可选）
+- systemd 对服务的依赖
+  - 可执行文件路径与权限
+  - 工作目录与日志目录的可写权限
+  - 环境变量（端口、日志级别、Docker 套接字等）
+
+```mermaid
+graph LR
+A["rcoder 可执行文件"] --> B["HTTP 服务<br/>端口监听"]
+A --> C["日志系统<br/>tracing/tracing-subscriber"]
+A --> D["异步运行时<br/>tokio/axum/tower"]
+A --> E["可观测性<br/>OpenTelemetry/Tokio Console"]
+F["systemd"] --> A
+F --> G["工作目录/日志目录"]
+F --> H["环境变量"]
+```
+
+图表来源
+- [Cargo.toml](file://Cargo.toml#L54-L102)
+- [Cargo.toml](file://Cargo.toml#L92-L102)
+- [Cargo.toml](file://Cargo.toml#L199-L205)
+
+章节来源
+- [Cargo.toml](file://Cargo.toml#L54-L102)
+- [Cargo.toml](file://Cargo.toml#L92-L102)
+- [Cargo.toml](file://Cargo.toml#L199-L205)
+
+## 性能考虑
+- 日志级别与性能
+  - RUST_LOG=info 适合生产；debug 会增加 IO 与 CPU 开销
+- 端口与网络
+  - 确保端口未被占用；合理规划防火墙规则
+- 健康检查与重启
+  - HEALTHCHECK 与 restart: always 可提升可用性，但需避免过度重启导致抖动
+- 资源限制
+  - systemd 可通过 LimitNOFILE、LimitMEM/CPU 等进行资源约束（建议在单元文件中配置）
+
+[本节为通用指导，不直接分析具体文件]
+
+## 故障排查指南
+- 启动失败
+  - 检查 ExecStart 路径与权限
+  - 查看日志：journalctl -u rcoder -f
+  - 验证环境变量是否正确注入
+- 权限不足
+  - 确认 User 拥有工作目录与日志目录的读写权限
+  - 端口是否需要 root 权限（建议使用非特权端口）
+- 依赖服务未就绪
+  - 使用 After=network.target 等依赖时机
+  - 在容器场景下，确认 Docker 套接字挂载与权限
+- 日志查看与状态查询
+  - 日志：journalctl -u rcoder -n 100
+  - 状态：systemctl status rcoder
+  - 启停：systemctl start/stop/restart rcoder
+- 常见问题定位
+  - 端口占用：调整 RCODER_PORT 或停止占用进程
+  - 端口被占用：参考 README 中的端口调整示例
+
+章节来源
+- [README.md](file://README.md#L560-L583)
+- [rcoder-service.sh](file://rcoder-service.sh#L134-L191)
+- [rcoder-service.sh](file://rcoder-service.sh#L193-L236)
+- [rcoder-service.sh](file://rcoder-service.sh#L246-L284)
+
+## 结论
+- systemd 集成 rcoder 的关键在于：明确的单元文件、正确的 ExecStart、合理的环境变量与工作目录、以及可靠的健康检查与重启策略
+- 若采用容器部署，start-rcoder.sh 提供了清晰的环境准备与启动流程，可作为 systemd ExecStart 的入口脚本
+- 生产环境中建议结合日志级别控制、资源限制与健康检查，确保服务稳定与可观测
+
+[本节为总结性内容，不直接分析具体文件]
+
+## 附录
+
+### systemd 服务单元文件编写示例（基于仓库内容）
+- [Unit]
+  - Description：RCoder AI Development Platform
+  - After：network.target
+- [Service]
+  - Type：simple
+  - User：rcoder
+  - WorkingDirectory：/opt/rcoder
+  - ExecStart：/opt/rcoder/target/release/rcoder --port 3000
+  - Restart：always
+  - RestartSec：5
+  - Environment：RUST_LOG=info；RCODER_PORT=3000
+- [Install]
+  - WantedBy：multi-user.target
+
+章节来源
+- [README.md](file://README.md#L560-L583)
+
+### start-rcoder.sh 在 systemd 上下文中的执行流程
+```mermaid
+flowchart TD
+Start(["进入 systemd"]) --> Prep["准备环境变量<br/>RUST_LOG/PORT/DOCKER_SOCKET_PATH/RCODER_WORKSPACE"]
+Prep --> Mkdir["创建日志与工作目录"]
+Mkdir --> Exec["exec 启动 rcoder<br/>传递端口参数"]
+Exec --> Done(["进程由 systemd 管理"])
+```
+
+图表来源
+- [docker/scripts/start-rcoder.sh](file://docker/scripts/start-rcoder.sh#L1-L23)
+
+### 日志查看、状态查询与故障排查标准操作
+- 日志查看
+  - journalctl -u rcoder -f
+  - journalctl -u rcoder -n 100
+- 状态查询
+  - systemctl status rcoder
+- 启停控制
+  - systemctl start/stop/restart rcoder
+- 常见问题
+  - 端口被占用：调整端口或释放占用进程
+  - 权限不足：修正用户与目录权限
+  - 依赖未就绪：检查 After 与 Docker 套接字挂载
+
+章节来源
+- [README.md](file://README.md#L560-L583)
+- [rcoder-service.sh](file://rcoder-service.sh#L134-L191)
+- [rcoder-service.sh](file://rcoder-service.sh#L193-L236)
+- [rcoder-service.sh](file://rcoder-service.sh#L246-L284)