581 lines
14 KiB
Markdown
581 lines
14 KiB
Markdown
# R 统计引擎架构与部署指南
|
||
|
||
> **版本：** v1.0
|
||
> **创建日期：** 2026-02-19
|
||
> **维护者：** SSA-Pro 开发团队
|
||
> **状态：** ✅ 生产就绪
|
||
|
||
---
|
||
|
||
## 📋 目录
|
||
|
||
1. [概述](#1-概述)
|
||
2. [架构设计](#2-架构设计)
|
||
3. [Docker 镜像构建](#3-docker-镜像构建)
|
||
4. [部署指南](#4-部署指南)
|
||
5. [API 参考](#5-api-参考)
|
||
6. [开发指南](#6-开发指南)
|
||
7. [运维指南](#7-运维指南)
|
||
8. [常见问题](#8-常见问题)
|
||
|
||
---
|
||
|
||
## 1. 概述
|
||
|
||
### 1.1 什么是 R 统计引擎
|
||
|
||
R 统计引擎是平台的**专用统计计算服务**，基于 Docker 容器化部署，提供：
|
||
|
||
- 🧮 **严谨的统计分析能力**（T 检验、方差分析、回归等）
|
||
- 🛡️ **统计护栏**（正态性检验、方差齐性检验等）
|
||
- 📊 **可视化输出**（Base64 编码的图表）
|
||
- 📝 **可复现代码生成**（APA 格式的 R 脚本）
|
||
|
||
### 1.2 定位
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 业务模块层 │
|
||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
||
│ │ SSA-Pro │ │ 其他 │ │ 其他 │ │
|
||
│ │ 智能统计 │ │ 模块 │ │ 模块 │ │
|
||
│ └────┬────┘ └─────────┘ └─────────┘ │
|
||
├───────┼─────────────────────────────────────────────────────┤
|
||
│ ▼ 通用能力层 │
|
||
│ ┌─────────────────────────────────────────────────────┐ │
|
||
│ │ R 统计引擎 (Docker) │ │
|
||
│ │ • /health 健康检查 │ │
|
||
│ │ • /api/v1/tools 工具列表 │ │
|
||
│ │ • /api/v1/skills 技能执行 │ │
|
||
│ └─────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 1.3 技术栈
|
||
|
||
| 组件 | 版本 | 说明 |
|
||
|------|------|------|
|
||
| R | 4.3.3 | 统计计算核心 |
|
||
| plumber | 1.2.1 | REST API 框架 |
|
||
| ggplot2 | 最新 | 数据可视化 |
|
||
| car | 3.1-2 | 高级统计检验 |
|
||
| dplyr/tidyr | 最新 | 数据处理 |
|
||
| Docker | 24+ | 容器化部署 |
|
||
|
||
---
|
||
|
||
## 2. 架构设计
|
||
|
||
### 2.1 Brain-Hand 模型
|
||
|
||
R 统计引擎采用 **Brain-Hand 分离架构**：
|
||
|
||
```
|
||
┌──────────────────┐ ┌──────────────────┐
|
||
│ Node.js │ │ R Docker │
|
||
│ (Brain) │ │ (Hand) │
|
||
├──────────────────┤ ├──────────────────┤
|
||
│ • 业务逻辑 │ HTTP │ • 统计计算 │
|
||
│ • 认证鉴权 │ ───────> │ • 数据处理 │
|
||
│ • OSS 签名 │ │ • 图表生成 │
|
||
│ • 结果解释 │ <─────── │ • 代码生成 │
|
||
└──────────────────┘ JSON └──────────────────┘
|
||
```
|
||
|
||
### 2.2 数据传输协议
|
||
|
||
支持两种数据传输方式：
|
||
|
||
| 方式 | 条件 | 字段 |
|
||
|------|------|------|
|
||
| **inline** | 数据 < 2MB | `data_source.data` (JSON) |
|
||
| **oss** | 数据 >= 2MB | `data_source.oss_url` (预签名 URL) |
|
||
|
||
```json
|
||
// 方式 1: inline
|
||
{
|
||
"data_source": {
|
||
"type": "inline",
|
||
"data": [{"group": "A", "value": 10}, ...]
|
||
}
|
||
}
|
||
|
||
// 方式 2: oss (预签名 URL)
|
||
{
|
||
"data_source": {
|
||
"type": "oss",
|
||
"oss_url": "https://bucket.oss.com/data.csv?signature=xxx"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.3 安全设计
|
||
|
||
| 安全措施 | 实现方式 |
|
||
|----------|----------|
|
||
| 非特权用户 | `USER appuser` |
|
||
| 路径遍历防护 | `tool_code` 正则白名单 `^[A-Z][A-Z0-9_]*$` |
|
||
| OSS 密钥隔离 | Node.js 生成预签名 URL，R 无需持有密钥 |
|
||
| 健康检查 | Docker HEALTHCHECK |
|
||
|
||
---
|
||
|
||
## 3. Docker 镜像构建
|
||
|
||
### 3.1 完整 Dockerfile
|
||
|
||
```dockerfile
|
||
FROM rocker/r-ver:4.3
|
||
|
||
LABEL maintainer="dev-team@aiclinicalresearch.com"
|
||
LABEL version="1.0.1"
|
||
LABEL description="SSA-Pro R Statistics Service"
|
||
|
||
# 安装系统依赖（包括 R 包编译所需的库）
|
||
RUN apt-get update && apt-get install -y \
|
||
libcurl4-openssl-dev \
|
||
libssl-dev \
|
||
libxml2-dev \
|
||
libsodium-dev \
|
||
zlib1g-dev \
|
||
libnlopt-dev \
|
||
liblapack-dev \
|
||
libblas-dev \
|
||
gfortran \
|
||
pkg-config \
|
||
cmake \
|
||
curl \
|
||
&& rm -rf /var/lib/apt/lists/*
|
||
|
||
# 直接安装 R 包
|
||
RUN R -e "install.packages(c( \
|
||
'plumber', \
|
||
'jsonlite', \
|
||
'ggplot2', \
|
||
'glue', \
|
||
'dplyr', \
|
||
'tidyr', \
|
||
'base64enc', \
|
||
'yaml', \
|
||
'car', \
|
||
'httr' \
|
||
), repos='https://cloud.r-project.org/', Ncpus=2)"
|
||
|
||
# 安全加固：创建非特权用户
|
||
RUN useradd -m -s /bin/bash appuser
|
||
|
||
WORKDIR /app
|
||
|
||
# 复制应用代码
|
||
COPY plumber.R plumber.R
|
||
COPY utils/ utils/
|
||
COPY tools/ tools/
|
||
COPY tests/ tests/
|
||
|
||
# 设置目录权限
|
||
RUN chown -R appuser:appuser /app
|
||
|
||
# 切换到非特权用户
|
||
USER appuser
|
||
|
||
EXPOSE 8080
|
||
|
||
# 环境变量
|
||
ENV DEV_MODE="false"
|
||
|
||
# 健康检查
|
||
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
|
||
CMD curl -f http://localhost:8080/health || exit 1
|
||
|
||
# 启动服务
|
||
CMD ["R", "-e", "plumber::plumb('plumber.R')$run(host='0.0.0.0', port=8080)"]
|
||
```
|
||
|
||
### 3.2 系统依赖说明
|
||
|
||
| 依赖包 | 用途 |
|
||
|--------|------|
|
||
| `libcurl4-openssl-dev` | httr 包（HTTP 请求） |
|
||
| `libssl-dev` | openssl 包（加密） |
|
||
| `libxml2-dev` | xml2 包（XML 解析） |
|
||
| `libsodium-dev` | sodium 包（加密） |
|
||
| `zlib1g-dev` | httpuv 包（Web 服务器） |
|
||
| `libnlopt-dev` | nloptr 包（优化算法） |
|
||
| `liblapack-dev` | 线性代数计算 |
|
||
| `libblas-dev` | 基础线性代数 |
|
||
| `gfortran` | Fortran 编译器（部分 R 包需要） |
|
||
| `cmake` | nloptr 包构建 |
|
||
| `curl` | 健康检查 |
|
||
|
||
### 3.3 构建命令
|
||
|
||
```bash
|
||
# 本地构建
|
||
cd r-statistics-service
|
||
docker build -t ssa-r-statistics:1.0.1 .
|
||
|
||
# 查看镜像
|
||
docker images ssa-r-statistics
|
||
|
||
# 预期输出
|
||
REPOSITORY TAG IMAGE ID CREATED SIZE
|
||
ssa-r-statistics 1.0.1 xxxxxxxxxxxx x minutes ago 1.81GB
|
||
```
|
||
|
||
### 3.4 构建时间参考
|
||
|
||
| 阶段 | 耗时 |
|
||
|------|------|
|
||
| 基础镜像下载 | ~2 分钟（首次） |
|
||
| 系统依赖安装 | ~1 分钟 |
|
||
| R 包安装 | ~6 分钟 |
|
||
| **总计** | **~9 分钟** |
|
||
|
||
---
|
||
|
||
## 4. 部署指南
|
||
|
||
### 4.1 开发环境
|
||
|
||
使用 docker-compose：
|
||
|
||
```yaml
|
||
# r-statistics-service/docker-compose.yml
|
||
version: '3.8'
|
||
|
||
services:
|
||
ssa-r-service:
|
||
build: .
|
||
container_name: ssa-r-statistics
|
||
ports:
|
||
- "8082:8080" # 主机8082 → 容器8080（REDCap占用8080/8081）
|
||
environment:
|
||
- DEV_MODE=true
|
||
volumes:
|
||
# 开发环境挂载：支持热重载
|
||
- ./tools:/app/tools
|
||
- ./utils:/app/utils
|
||
- ./tests:/app/tests
|
||
restart: unless-stopped
|
||
healthcheck:
|
||
test: ["CMD", "curl", "-f", "http://localhost:8080/health"] # 容器内部仍是8080
|
||
interval: 30s
|
||
timeout: 10s
|
||
retries: 3
|
||
start_period: 10s
|
||
```
|
||
|
||
启动命令：
|
||
```bash
|
||
cd r-statistics-service
|
||
docker-compose up -d
|
||
```
|
||
|
||
### 4.2 生产环境 (SAE)
|
||
|
||
```yaml
|
||
# SAE 配置
|
||
容器镜像: registry.cn-beijing.aliyuncs.com/aiclinical/ssa-r-statistics:1.0.1
|
||
实例规格: 2 vCPU, 4 GB
|
||
最小实例: 1
|
||
最大实例: 5
|
||
端口: 8080
|
||
|
||
环境变量:
|
||
DEV_MODE: "false"
|
||
```
|
||
|
||
### 4.3 环境变量
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `DEV_MODE` | `false` | 开发模式（启用热重载，每次请求重新加载工具脚本） |
|
||
|
||
> **说明**：开发环境和生产环境都使用真实 OSS，无需 Mock 数据。
|
||
> - 开发环境：`ai-clinical-data-dev` bucket
|
||
> - 生产环境：`ai-clinical-data` bucket
|
||
|
||
### 4.4 端口配置
|
||
|
||
| 环境 | 主机端口 | 容器端口 | 说明 |
|
||
|------|----------|----------|------|
|
||
| **开发环境** | 8082 | 8080 | 避免与 REDCap 8080/8081 冲突 |
|
||
| **生产环境 (SAE)** | 8080 | 8080 | 云端无端口冲突 |
|
||
|
||
> **注意**：Node.js 后端通过 `R_SERVICE_URL` 环境变量配置 R 服务地址，默认值为 `http://localhost:8082`。
|
||
|
||
---
|
||
|
||
## 5. API 参考
|
||
|
||
### 5.1 健康检查
|
||
|
||
```http
|
||
GET /health
|
||
```
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"timestamp": "2026-02-19 08:00:00",
|
||
"version": "1.0.1",
|
||
"dev_mode": true,
|
||
"tools_loaded": 1
|
||
}
|
||
```
|
||
|
||
### 5.2 工具列表
|
||
|
||
```http
|
||
GET /api/v1/tools
|
||
```
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"tools": ["t_test_ind", "anova_oneway"],
|
||
"count": 2
|
||
}
|
||
```
|
||
|
||
### 5.3 执行技能
|
||
|
||
```http
|
||
POST /api/v1/skills/{tool_code}
|
||
Content-Type: application/json
|
||
```
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"data_source": {
|
||
"type": "inline",
|
||
"data": [...]
|
||
},
|
||
"params": {
|
||
"group_var": "group",
|
||
"value_var": "value"
|
||
},
|
||
"guardrails": {
|
||
"check_normality": true
|
||
}
|
||
}
|
||
```
|
||
|
||
**成功响应：**
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"message": "分析完成",
|
||
"warnings": null,
|
||
"results": {
|
||
"method": "Welch Two Sample t-test",
|
||
"statistic": -5.196,
|
||
"df": 5.98,
|
||
"p_value": 0.002,
|
||
"p_value_fmt": "p = .002"
|
||
},
|
||
"plots": ["data:image/png;base64,..."],
|
||
"trace_log": [...],
|
||
"reproducible_code": "..."
|
||
}
|
||
```
|
||
|
||
**错误响应：**
|
||
```json
|
||
{
|
||
"status": "error",
|
||
"error_code": "E001",
|
||
"error_type": "business",
|
||
"message": "列名 'xxx' 在数据中不存在",
|
||
"user_hint": "请检查变量名是否拼写正确"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 开发指南
|
||
|
||
### 6.1 添加新工具
|
||
|
||
1. 在 `tools/` 目录创建 R 脚本：
|
||
|
||
```r
|
||
# tools/my_analysis.R
|
||
|
||
#' @tool_code ST_MY_ANALYSIS
|
||
#' @name 我的分析工具
|
||
#' @version 1.0.0
|
||
|
||
# 统一入口函数
|
||
run_analysis <- function(input) {
|
||
# 加载数据
|
||
df <- load_input_data(input)
|
||
|
||
# 参数
|
||
p <- input$params
|
||
|
||
# 护栏检查
|
||
# ...
|
||
|
||
# 核心计算
|
||
# ...
|
||
|
||
# 返回结果
|
||
return(list(
|
||
status = "success",
|
||
message = "分析完成",
|
||
results = list(...)
|
||
))
|
||
}
|
||
```
|
||
|
||
2. 重启服务（开发模式无需重启）
|
||
|
||
3. 测试：
|
||
```bash
|
||
curl -X POST http://localhost:8082/api/v1/skills/ST_MY_ANALYSIS \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"data_source": {...}, "params": {...}}'
|
||
```
|
||
|
||
### 6.2 工具命名规范
|
||
|
||
| 项目 | 规范 |
|
||
|------|------|
|
||
| 文件名 | 小写下划线：`t_test_ind.R` |
|
||
| tool_code | 大写下划线：`ST_T_TEST_IND` |
|
||
| 入口函数 | 固定名称：`run_analysis` |
|
||
|
||
### 6.3 结果格式规范
|
||
|
||
```r
|
||
return(list(
|
||
status = "success" | "error" | "blocked",
|
||
message = "...",
|
||
warnings = c("...") | NULL,
|
||
results = list(
|
||
# 统计结果
|
||
),
|
||
plots = list(
|
||
"data:image/png;base64,..."
|
||
),
|
||
trace_log = c("..."),
|
||
reproducible_code = "..."
|
||
))
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 运维指南
|
||
|
||
### 7.1 日志查看
|
||
|
||
```bash
|
||
# 实时日志
|
||
docker logs -f ssa-r-statistics
|
||
|
||
# 最近 100 行
|
||
docker logs --tail 100 ssa-r-statistics
|
||
```
|
||
|
||
### 7.2 性能监控
|
||
|
||
```bash
|
||
# 容器资源使用
|
||
docker stats ssa-r-statistics
|
||
```
|
||
|
||
### 7.3 重启服务
|
||
|
||
```bash
|
||
# 开发环境
|
||
docker-compose restart
|
||
|
||
# 生产环境 (SAE)
|
||
通过 SAE 控制台重启实例
|
||
```
|
||
|
||
### 7.4 镜像更新
|
||
|
||
```bash
|
||
# 1. 构建新镜像
|
||
docker build -t ssa-r-statistics:1.0.2 .
|
||
|
||
# 2. 推送到镜像仓库
|
||
docker tag ssa-r-statistics:1.0.2 registry.cn-beijing.aliyuncs.com/aiclinical/ssa-r-statistics:1.0.2
|
||
docker push registry.cn-beijing.aliyuncs.com/aiclinical/ssa-r-statistics:1.0.2
|
||
|
||
# 3. 更新 SAE 部署
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 常见问题
|
||
|
||
### Q1: 构建时 httpuv 安装失败
|
||
|
||
**错误：** `fatal error: zlib.h: No such file or directory`
|
||
|
||
**解决：** 添加 `zlib1g-dev` 到系统依赖
|
||
|
||
### Q2: 构建时 nloptr 安装失败
|
||
|
||
**错误：** `CMAKE NOT FOUND`
|
||
|
||
**解决：** 添加 `cmake` 到系统依赖
|
||
|
||
### Q3: /tmp 权限问题
|
||
|
||
**错误：** `cannot open file '/tmp/Rtmpxxx': No such file or directory`
|
||
|
||
**解决：** 不要在启动命令中清理 /tmp
|
||
|
||
### Q4: DEV_MODE 热重载不生效
|
||
|
||
**原因：** 没有挂载 volumes
|
||
|
||
**解决：**
|
||
```yaml
|
||
volumes:
|
||
- ./tools:/app/tools
|
||
```
|
||
|
||
### Q5: 容器启动后无法访问
|
||
|
||
**检查：**
|
||
1. 端口映射是否正确
|
||
2. 健康检查是否通过
|
||
3. 查看容器日志
|
||
|
||
---
|
||
|
||
## 附录：文件结构
|
||
|
||
```
|
||
r-statistics-service/
|
||
├── Dockerfile # 生产镜像定义
|
||
├── docker-compose.yml # 开发环境编排
|
||
├── renv.lock # R 包版本锁定（备用）
|
||
├── .Rprofile # R 启动配置（备用）
|
||
├── plumber.R # API 入口
|
||
├── utils/
|
||
│ ├── data_loader.R # 数据加载（预签名 URL）
|
||
│ ├── guardrails.R # 统计护栏
|
||
│ ├── error_codes.R # 错误映射
|
||
│ └── result_formatter.R # 结果格式化
|
||
├── tools/
|
||
│ └── t_test_ind.R # 独立样本 T 检验
|
||
├── tests/
|
||
│ └── fixtures/
|
||
│ └── normal_data.csv # 测试数据
|
||
├── metadata/ # 工具元数据（预留）
|
||
└── templates/ # 解释模板（预留）
|
||
```
|
||
|
||
---
|
||
|
||
**文档结束**
|