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