byy/qiming
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
913c6da8f396635419bba755b73dd4eeda32e047
qiming/qiming-rcoder/.qoder/repowiki/zh/content/故障排除/安全考虑.md
Codex 4b1a580132 添加qiming-rcoder模块
2026-06-01 13:54:52 +08:00

329 lines
16 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.
# 安全考虑
<cite>
**本文引用的文件**
- [docker/Dockerfile](file://docker/Dockerfile)
- [scripts/setup-network-isolation.sh](file://scripts/setup-network-isolation.sh)
- [docker/docker-compose.yml](file://docker/docker-compose.yml)
- [config.yml](file://config.yml)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs)
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs)
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs)
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs)
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs)
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs)
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs)
- [crates/rcoder/src/middleware/tracing_middleware.rs](file://crates/rcoder/src/middleware/tracing_middleware.rs)
- [crates/agent_runner/src/middleware/tracing_middleware.rs](file://crates/agent_runner/src/middleware/tracing_middleware.rs)
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs)
- [crates/shared_types/src/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)
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs)
- [crates/agent_runner/src/utils/system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs)
</cite>
## 目录
1. [简介](#简介)
2. [项目结构与安全边界](#项目结构与安全边界)
3. [核心安全组件](#核心安全组件)
4. [架构总览](#架构总览)
5. [详细组件安全分析](#详细组件安全分析)
6. [依赖关系与耦合分析](#依赖关系与耦合分析)
7. [性能与安全权衡](#性能与安全权衡)
8. [故障排查与安全审计](#故障排查与安全审计)
9. [结论](#结论)
## 简介
本章节系统阐述 RCoder 在部署与运行中的安全实践，围绕容器隔离、挂载权限控制、镜像来源验证、API 访问控制、输入验证与防滥用、敏感信息管理、网络隔离脚本、日志与审计、漏洞扫描与最小权限原则等方面展开。文档旨在帮助运维与开发人员在保障功能完备的同时，提升系统的安全性与可审计性。
## 项目结构与安全边界
- 容器运行时：通过 Docker Compose 启动主服务与代理服务，主服务暴露端口并可选启用反向代理；Agent Runner 作为容器内服务参与聊天处理。
- 网络隔离：提供宿主机侧网络隔离脚本，基于 iptables 限制容器对内网地址段的访问。
- 配置管理：支持命令行参数、环境变量与配置文件的多级覆盖；敏感信息建议通过环境变量注入，避免明文写入配置文件。
- 日志与可观测性：内置 OpenTelemetry 与结构化日志，支持按天滚动与 trace_id 传播，便于审计与定位问题。
```mermaid
graph TB
subgraph "宿主机"
DC["Docker Compose<br/>rcoder 服务"]
NI["网络隔离脚本<br/>iptables 规则"]
LOG["日志目录<br/>logs/"]
end
subgraph "容器内"
RC["rcoder 主服务"]
AR["agent_runner 服务"]
PM["Pingora 反向代理"]
DM["Docker 管理器"]
end
DC --> RC
RC --> PM
RC --> DM
RC --> AR
NI -.-> DC
LOG -.-> RC
```
图表来源
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L210-L272)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L120-L178)
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)
章节来源
- [docker/docker-compose.yml](file://docker/docker-compose.yml#L1-L37)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L210-L272)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L120-L178)
## 核心安全组件
- 容器隔离与能力控制：容器启动时丢弃网络相关能力，禁用特权模式，降低逃逸风险。
- 网络隔离脚本：在宿主机 iptables 上为 rcoder- 前缀网络添加规则，阻止访问常见内网地址段。
- 配置与环境变量：支持环境变量覆盖端口、工作目录、网络模式、自动清理、容器 TTL 等，敏感信息建议通过环境变量注入。
- 日志与追踪：结构化 JSON 日志按天滚动，trace_id 传播，便于审计与关联分析。
- 反向代理与健康检查：Pingora 代理提供后端健康检查与统计接口，便于监控与故障定位。
章节来源
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L147-L165)
- [scripts/setup-network-isolation.sh](file://scripts/setup-network-isolation.sh#L1-L112)
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L212-L239)
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L134-L171)
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L274-L321)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L181-L232)
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)
## 架构总览
下图展示 RCoder 主服务、Agent Runner、Pingora 代理与 Docker 管理器之间的交互，以及网络隔离脚本对宿主机网络的影响。
```mermaid
sequenceDiagram
participant Client as "客户端"
participant RC as "rcoder 主服务"
participant PM as "Pingora 代理"
participant AR as "agent_runner 服务"
participant DM as "Docker 管理器"
participant NI as "网络隔离脚本"
Client->>RC : "POST /chat"
RC->>DM : "获取/创建容器"
DM-->>RC : "返回容器信息"
RC->>AR : "转发请求到容器内 /chat"
AR-->>RC : "返回处理结果"
RC-->>Client : "返回响应"
Note over NI,PM : "宿主机 iptables 限制容器访问内网"
```
图表来源
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L323-L431)
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L174-L321)
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L105-L165)
- [scripts/setup-network-isolation.sh](file://scripts/setup-network-isolation.sh#L70-L95)
章节来源
- [crates/rcoder/src/router.rs](file://crates/rcoder/src/router.rs#L52-L84)
- [crates/agent_runner/src/router.rs](file://crates/agent_runner/src/router.rs#L40-L70)
## 详细组件安全分析
### 容器隔离与挂载权限控制
- 能力与特权控制
- 容器启动时丢弃网络原始与管理能力，禁用特权模式，降低容器逃逸与网络嗅探风险。
- 挂载策略
- 默认挂载类型为 bind，部分服务挂载路径允许只读或额外绑定，需谨慎评估挂载路径与权限。
- 网络隔离脚本
- 通过查找 rcoder- 前缀网络，为每个网络子网添加 DROP 规则，阻止访问常见内网地址段；规则在系统重启后会丢失，需持久化或开机重载。
```mermaid
flowchart TD
Start(["容器启动"]) --> DropCaps["丢弃网络相关能力<br/>禁用特权模式"]
DropCaps --> Mounts["绑定挂载配置<br/>只读/额外挂载"]
Mounts --> NetIsolate["宿主机 iptables 规则<br/>阻止访问内网地址段"]
NetIsolate --> Run(["容器运行"])
```
图表来源
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L147-L165)
- [scripts/setup-network-isolation.sh](file://scripts/setup-network-isolation.sh#L70-L95)
章节来源
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L105-L165)
- [scripts/setup-network-isolation.sh](file://scripts/setup-network-isolation.sh#L1-L112)
### 镜像来源验证与多镜像配置
- 多镜像配置
- 支持按服务类型选择镜像，包含全局默认与架构特定镜像，策略为仅使用服务特定配置。
- 缓存与选择
- 提供镜像缓存配置，支持 TTL 与最大条目数；镜像选择策略为 ServiceOnly。
- 建议
- 通过 registry 前缀与服务特定镜像保证来源可控；结合镜像签名与拉取策略，进一步强化来源可信度。
```mermaid
classDiagram
class MultiImageConfig {
+services
+global_defaults
+selection_strategy
+cache_config
+validate()
+hash_key()
}
class ServiceConfig {
+service_type
+image/arm64/amd64
+mounts
+environment
+resource_limits
+get_image_for_platform(platform)
+validate()
}
MultiImageConfig --> ServiceConfig : "包含"
```
图表来源
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L43-L110)
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L361-L406)
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L153-L188)
章节来源
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L43-L110)
- [crates/shared_types/src/multi_image_config.rs](file://crates/shared_types/src/multi_image_config.rs#L361-L406)
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs#L153-L188)
### API 端点访问控制、输入验证与防滥用
- 访问控制
- 当前未实现显式的鉴权/授权中间件；建议在反向代理层或网关处增加认证与授权策略。
- 输入验证
- 主服务与 Agent Runner 均对请求进行基本校验（如 prompt 非空），并在业务层进行并发控制与会话清理。
- 防滥用
- 通过并发请求限制与会话缓存清理，避免同一项目下的并发冲突；建议引入速率限制中间件或上游限流策略。
```mermaid
sequenceDiagram
participant Client as "客户端"
participant RC as "rcoder 主服务"
participant AR as "agent_runner 服务"
Client->>RC : "POST /chat"
RC->>RC : "校验请求参数"
RC->>AR : "转发请求"
AR->>AR : "并发检查/会话清理"
AR-->>RC : "返回结果"
RC-->>Client : "返回响应"
```
图表来源
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L108-L170)
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L174-L238)
章节来源
- [crates/rcoder/src/handler/chat_handler.rs](file://crates/rcoder/src/handler/chat_handler.rs#L108-L170)
- [crates/agent_runner/src/handler/chat_handler.rs](file://crates/agent_runner/src/handler/chat_handler.rs#L174-L238)
### 配置文件与敏感信息管理
- 配置优先级
- 命令行参数 > 环境变量 > 配置文件 > 默认配置；Docker 配置支持环境变量覆盖。
- 敏感信息建议
- 将密钥、令牌等敏感信息通过环境变量注入，避免写入 config.yml；必要时使用密钥管理服务或容器编排平台的机密存储。
- 配置文件生成
- 首次启动会生成默认配置文件，建议在部署时以只读方式挂载或通过环境变量覆盖。
章节来源
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
- [crates/agent_runner/src/config.rs](file://crates/agent_runner/src/config.rs#L110-L191)
- [config.yml](file://config.yml#L1-L161)
### 网络隔离脚本实施与影响
- 规则生效范围
- 为 rcoder- 前缀网络添加 DROP 规则，阻止访问常见内网地址段；规则在系统重启后会丢失，需持久化。
- 实施建议
- 将脚本加入系统启动项或 systemd 服务；定期检查规则有效性；结合防火墙策略与网络命名空间进一步加固。
章节来源
- [scripts/setup-network-isolation.sh](file://scripts/setup-network-isolation.sh#L1-L112)
### 日志与追踪、健康检查与可观测性
- 日志
- 结构化 JSON 日志按天滚动，支持 trace_id 传播，便于审计与跨服务关联。
- 追踪
- 中间件生成并传播 trace_id，便于端到端链路追踪。
- 健康检查
- Pingora 代理提供健康检查循环与统计接口，便于监控后端健康状态。
```mermaid
sequenceDiagram
participant RC as "rcoder 主服务"
participant PM as "Pingora 代理"
participant HC as "健康检查循环"
RC->>PM : "启动代理服务"
PM->>HC : "启动健康检查循环"
HC->>HC : "周期性检查后端连通性"
PM-->>RC : "健康状态快照/统计"
```
图表来源
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L168-L209)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L80-L121)
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)
章节来源
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L274-L321)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L181-L232)
- [crates/pingora-proxy/src/service.rs](file://crates/pingora-proxy/src/service.rs#L556-L596)
### 最小权限原则与系统提示词约束
- 最小权限
- 容器禁用特权模式并丢弃网络相关能力，减少潜在攻击面。
- 系统提示词约束
- Agent Runner 的系统提示词包含多项安全禁令，禁止内网探测、反向 Shell、框架转换等行为，有助于降低风险。
章节来源
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L147-L165)
- [crates/agent_runner/src/utils/system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs#L96-L115)
## 依赖关系与耦合分析
- 组件耦合
- rcoder 主服务依赖 Docker 管理器进行容器生命周期管理；与 Pingora 代理耦合用于后端发现与健康检查；与 Agent Runner 通过容器内通信协作。
- 外部依赖
- Docker API、iptables、Pingora 代理、OpenTelemetry/Tracing。
- 潜在风险
- Docker socket 挂载与权限配置不当可能导致容器逃逸；网络隔离规则缺失可能使容器访问内网。
```mermaid
graph LR
RC["rcoder 主服务"] --> DM["Docker 管理器"]
RC --> PM["Pingora 代理"]
RC --> AR["agent_runner 服务"]
NI["网络隔离脚本"] -.-> RC
```
图表来源
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L111-L158)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L120-L178)
- [scripts/setup-network-isolation.sh](file://scripts/setup-network-isolation.sh#L52-L95)
章节来源
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L111-L158)
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs#L120-L178)
## 性能与安全权衡
- 性能
- 容器能力限制与网络隔离会带来一定开销，但显著降低逃逸与横向移动风险。
- 安全
- 建议在生产环境启用严格的镜像来源验证、最小权限与网络隔离；结合速率限制与上游防护，平衡吞吐与安全。
[本节为通用指导，无需引用具体文件]
## 故障排查与安全审计
- 日志审计
- 检查 logs 目录下的 JSON 日志，结合 trace_id 进行关联分析；关注健康检查失败与代理统计异常。
- 网络隔离验证
- 使用脚本列出当前规则，确认 rcoder- 网络的 DROP 规则已生效；必要时重新加载规则。
- 配置核验
- 确认环境变量覆盖生效，敏感信息未出现在配置文件中；检查 Docker 配置与挂载路径。
- 漏洞扫描
- 建议对镜像进行静态扫描，识别高危漏洞；对运行时容器进行定期扫描与基线核查。
章节来源
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L274-L321)
- [scripts/setup-network-isolation.sh](file://scripts/setup-network-isolation.sh#L97-L112)
- [crates/rcoder/src/config.rs](file://crates/rcoder/src/config.rs#L253-L332)
## 结论
RCoder 在容器隔离、网络隔离、日志与追踪方面具备良好基础。建议在生产环境中补充鉴权/授权、速率限制、镜像来源验证与漏洞扫描机制，严格使用环境变量管理敏感信息，并完善网络隔离规则的持久化与监控，以实现更全面的安全保障与可审计性。
Reference in New Issue View Git Blame Copy Permalink