diff --git a/docs/03-业务模块/Redcap/00-模块概览/00-REDCap模块文档导航.md b/docs/03-业务模块/Redcap/00-模块概览/00-REDCap模块文档导航.md new file mode 100644 index 00000000..e0189707 --- /dev/null +++ b/docs/03-业务模块/Redcap/00-模块概览/00-REDCap模块文档导航.md @@ -0,0 +1,219 @@ +# REDCap模块文档导航 + +**最后更新：** 2026-01-02 +**模块类型：** 第三方系统集成与二次开发 +**当前状态：** 本地Docker环境已部署，API Adapter开发中 + +--- + +## 📚 文档体系说明 + +REDCap是一个成熟的第三方EDC（电子数据采集）系统，本模块的工作重点是： +1. **部署与配置**：在不同环境（开发/生产/医院）部署REDCap +2. **API对接**：通过REDCap API与IIT Manager Agent集成 +3. **运维管理**：日常维护、备份、升级 + +因此，文档架构与自研模块（ASL、DC）不同，更侧重部署与集成。 + +--- + +## 📖 文档目录 + +### 1️⃣ **系统概览与决策** + +#### [01-REDCap系统介绍与选型说明.md](./01-REDCap系统介绍与选型说明.md) +- REDCap是什么？ +- 为什么选择REDCap？ +- REDCap的核心功能 +- REDCap在IIT Manager中的角色 + +#### [02-REDCap对接总体方案.md](./02-REDCap对接总体方案.md) ✅ +- 技术架构设计 +- API对接方案 +- 数据流转方案 +- 安全性设计 + +#### [03-REDCap对接风险评估与技术挑战分析.md](./03-REDCap对接风险评估与技术挑战分析.md) ✅ +- 技术风险评估 +- 实施难度分析 +- 替代方案对比 +- 最终决策建议 + +#### [04-生产环境部署决策报告_ECS_vs_SAE.md](./04-生产环境部署决策报告_ECS_vs_SAE.md) ✅ +- ECS vs SAE深度对比 +- 成本分析 +- 技术可行性 +- 最终选型：ECS + +--- + +### 2️⃣ **部署与配置** + +#### [10-本地开发环境部署完全指南.md](./10-本地开发环境部署完全指南.md) ⭐ +- **快速开始**（适合首次部署） +- Docker环境准备 +- 一键部署脚本使用 +- 初始化配置 +- 验证测试 +- **关键参考文档！** + +#### [11-生产环境部署完全指南_阿里云ECS.md](./11-生产环境部署完全指南_阿里云ECS.md) ⭐ +- **ECS服务器配置** +- Docker镜像构建与推送 +- RDS MySQL配置 +- 域名与SSL证书 +- 安全组与防火墙 +- 生产环境检查清单 +- **生产部署必读！** + +#### [12-医院私有化部署指南.md](./12-医院私有化部署指南.md) 🏥 +- 医院服务器环境要求 +- 内网部署方案 +- 数据安全与合规 +- 技术支持与培训 + +#### [13-部署问题排查手册.md](./13-部署问题排查手册.md) 🔧 +- 常见部署问题 +- 错误日志分析 +- 问题解决记录 +- 预防措施 + +--- + +### 3️⃣ **配置与管理** + +#### [20-REDCap系统配置手册.md](./20-REDCap系统配置手册.md) +- 基础配置（Base URL、邮件服务等） +- 用户与权限管理 +- 项目创建与配置 +- 数据字典设计 +- 表单设计 + +#### [21-REDCap日常运维手册.md](./21-REDCap日常运维手册.md) +- 日常维护任务 +- 备份与恢复 +- 性能监控 +- 日志管理 +- 故障处理流程 + +#### [22-REDCap升级指南.md](./22-REDCap升级指南.md) +- 版本升级流程 +- 数据库迁移 +- 兼容性测试 +- 回滚方案 + +--- + +### 4️⃣ **API对接与开发** + +#### [30-REDCap_API使用指南.md](./30-REDCap_API使用指南.md) +- REDCap API概述 +- API Token获取 +- 常用API接口 +- 示例代码 + +#### [31-IIT_Manager与REDCap对接设计.md](./31-IIT_Manager与REDCap对接设计.md) +- 数据流转设计 +- API Adapter架构 +- 接口设计 +- 错误处理 + +#### [32-REDCap_API_Adapter开发指南.md](./32-REDCap_API_Adapter开发指南.md) +- Adapter架构设计 +- 代码结构 +- 开发规范 +- 测试方案 + +#### [33-REDCap二次开发深度指南.md](./33-REDCap二次开发深度指南.md) ✅ +- External Modules开发 +- Hooks机制 +- 插件开发 +- 最佳实践 + +--- + +### 5️⃣ **参考资料** + +#### [40-REDCap官方资源索引.md](./40-REDCap官方资源索引.md) +- 官方文档链接 +- 社区资源 +- 视频教程 +- 常用工具 + +#### [41-Docker配置文件说明.md](./41-Docker配置文件说明.md) +- Dockerfile详解 +- docker-compose.yml配置 +- 环境变量说明 +- 网络与卷配置 + +--- + +## 🎯 快速入口 + +### 我想部署REDCap +- **本地开发测试** → [10-本地开发环境部署完全指南.md](./10-本地开发环境部署完全指南.md) +- **阿里云生产环境** → [11-生产环境部署完全指南_阿里云ECS.md](./11-生产环境部署完全指南_阿里云ECS.md) +- **医院私有化** → [12-医院私有化部署指南.md](./12-医院私有化部署指南.md) + +### 我遇到部署问题 +- **问题排查** → [13-部署问题排查手册.md](./13-部署问题排查手册.md) +- **历史问题记录** → [13-部署问题排查手册.md](./13-部署问题排查手册.md) + +### 我要进行API开发 +- **了解API** → [30-REDCap_API使用指南.md](./30-REDCap_API使用指南.md) +- **对接设计** → [31-IIT_Manager与REDCap对接设计.md](./31-IIT_Manager与REDCap对接设计.md) +- **开发Adapter** → [32-REDCap_API_Adapter开发指南.md](./32-REDCap_API_Adapter开发指南.md) + +### 我要日常运维 +- **系统配置** → [20-REDCap系统配置手册.md](./20-REDCap系统配置手册.md) +- **日常维护** → [21-REDCap日常运维手册.md](./21-REDCap日常运维手册.md) +- **版本升级** → [22-REDCap升级指南.md](./22-REDCap升级指南.md) + +--- + +## 📊 模块当前状态 + +| 阶段 | 状态 | 完成时间 | 备注 | +|------|------|----------|------| +| 技术调研 | ✅ 完成 | 2025-12 | 完成风险评估与方案设计 | +| 部署方案设计 | ✅ 完成 | 2026-01-01 | 确定Docker+ECS方案 | +| 本地环境部署 | ✅ 完成 | 2026-01-02 | REDCap 15.8.0运行正常 | +| API Adapter开发 | ⏳ 进行中 | 预计2026-01-03 | Day 2任务 | +| 生产环境部署 | 📅 计划中 | 待定 | 等待API Adapter完成 | + +--- + +## 🔄 文档更新记录 + +| 日期 | 更新内容 | 更新人 | +|------|----------|--------| +| 2026-01-02 | 创建文档体系，完成本地部署 | AI Assistant | +| 2025-12-XX | 完成技术方案与风险评估文档 | AI Assistant | + +--- + +## 📝 文档编写规范 + +### 图标使用规范 +- ⭐ 核心必读文档 +- ✅ 已完成 +- ⏳ 进行中 +- 📅 计划中 +- 🔧 故障排查 +- 🏥 医院专用 +- 💡 技巧提示 +- ⚠️ 重要警告 + +### 文档命名规范 +- 按数字分类：01-09系统概览，10-19部署，20-29配置，30-39开发，40-49参考 +- 使用下划线分隔多个单词（而非空格） +- 重要文档加"完全指南"/"手册"/"指南"后缀 + +--- + +## 🆘 获取帮助 + +- **技术问题**：查看 [13-部署问题排查手册.md](./13-部署问题排查手册.md) +- **REDCap官方**：https://projectredcap.org/ +- **Docker问题**：查看 `redcap-docker-dev/README.md` + diff --git a/docs/03-业务模块/Redcap/00-REDCap对接总体方案.md b/docs/03-业务模块/Redcap/00-模块概览/02-REDCap对接总体方案.md similarity index 100% rename from docs/03-业务模块/Redcap/00-REDCap对接总体方案.md rename to docs/03-业务模块/Redcap/00-模块概览/02-REDCap对接总体方案.md diff --git a/docs/03-业务模块/Redcap/01-REDCap对接风险评估与技术挑战分析.md b/docs/03-业务模块/Redcap/00-模块概览/03-REDCap对接风险评估与技术挑战分析.md similarity index 100% rename from docs/03-业务模块/Redcap/01-REDCap对接风险评估与技术挑战分析.md rename to docs/03-业务模块/Redcap/00-模块概览/03-REDCap对接风险评估与技术挑战分析.md diff --git a/docs/03-业务模块/Redcap/REDCap 生产环境部署：ECS vs SAE 深度决议报告.md b/docs/03-业务模块/Redcap/00-模块概览/04-生产环境部署决策报告_ECS_vs_SAE.md similarity index 100% rename from docs/03-业务模块/Redcap/REDCap 生产环境部署：ECS vs SAE 深度决议报告.md rename to docs/03-业务模块/Redcap/00-模块概览/04-生产环境部署决策报告_ECS_vs_SAE.md diff --git a/docs/03-业务模块/Redcap/01-部署与配置/10-REDCap_Docker部署操作手册.md b/docs/03-业务模块/Redcap/01-部署与配置/10-REDCap_Docker部署操作手册.md new file mode 100644 index 00000000..3dd68ce4 --- /dev/null +++ b/docs/03-业务模块/Redcap/01-部署与配置/10-REDCap_Docker部署操作手册.md @@ -0,0 +1,758 @@ +# REDCap Docker部署操作手册 + +**版本：** v1.0 +**最后更新：** 2026-01-02 +**适用环境：** Windows/Linux/Mac + Docker +**REDCap版本：** 15.8.0 +**验证状态：** ✅ 已在本地Windows环境验证通过 + +--- + +## 📋 文档目标 + +本手册提供REDCap基于Docker的**标准化部署流程**，适用于： +- ✅ 本地开发环境 +- ✅ 阿里云ECS生产环境 +- ✅ 医院私有化服务器 + +**核心优势：** +- 🔄 **可复用**：Docker配置文件可在不同环境直接使用 +- 📦 **一致性**：开发环境=生产环境，避免环境差异 +- 🚀 **快速部署**：30分钟内完成部署 +- 🛡️ **问题规避**：基于实际踩坑经验，预防常见问题 + +--- + +## 🎯 部署架构 + +### 标准架构（3个Docker容器） + +``` +┌─────────────────────────────────────────┐ +│ REDCap Docker 部署架构 │ +├─────────────────────────────────────────┤ +│ │ +│ ┌──────────────────────────────────┐ │ +│ │ redcap-apache (Web容器) │ │ +│ │ - PHP 8.1 + Apache 2.4 │ │ +│ │ - REDCap 15.8.0 源码 │ │ +│ │ - Cron定时任务 │ │ +│ │ Port: 8080 → 80 │ │ +│ └──────────────────────────────────┘ │ +│ ↓ │ +│ ┌──────────────────────────────────┐ │ +│ │ redcap-mysql (数据库容器) │ │ +│ │ - MySQL 8.0 │ │ +│ │ - 数据持久化(Volume) │ │ +│ │ Port: 3306 (内部) │ │ +│ └──────────────────────────────────┘ │ +│ ↓ │ +│ ┌──────────────────────────────────┐ │ +│ │ redcap-phpmyadmin (管理工具) │ │ +│ │ - phpMyAdmin 5 │ │ +│ │ Port: 8081 → 80 │ │ +│ │ (可选，仅开发环境) │ │ +│ └──────────────────────────────────┘ │ +└─────────────────────────────────────────┘ +``` + +--- + +## 📦 可复用的Docker文件清单 + +### 核心文件（必需，可直接复用） + +| 文件路径 | 说明 | 环境差异 | 复用性 | +|---------|------|---------|--------| +| `Dockerfile.redcap` | REDCap镜像构建文件 | 无差异 | ✅ 100%可复用 | +| `docker-compose.yml` | 开发环境编排文件 | 需调整端口/卷路径 | ⚠️ 需微调 | +| `docker-compose.prod.yml` | 生产环境编排文件 | 需配置RDS | ⚠️ 需修改数据库配置 | +| `docker-entrypoint.sh` | 容器启动脚本 | 无差异 | ✅ 100%可复用 | +| `config/apache/redcap.conf` | Apache虚拟主机配置 | 需调整域名 | ⚠️ 需修改域名 | +| `config/php/php.ini` | PHP运行时配置 | 无差异 | ✅ 100%可复用 | +| `config/database.php` | REDCap数据库连接配置 | **必须修改** | ❌ 需针对环境定制 | +| `.gitattributes` | Git换行符规范 | 无差异 | ✅ 100%可复用 | + +### 辅助脚本（可选） + +| 文件路径 | 说明 | 适用场景 | +|---------|------|---------| +| `scripts/setup-redcap.ps1` | 一键部署脚本（Windows） | 本地开发 | +| `scripts/start-redcap.ps1` | 启动服务 | 本地开发 | +| `scripts/stop-redcap.ps1` | 停止服务 | 本地开发 | +| `scripts/clean-redcap.ps1` | 清理环境 | 本地开发 | +| `scripts/create-redcap-password.php` | 密码重置工具 | 开发/运维 | + +--- + +## 🚀 部署流程（从0到1） + +### 阶段1：环境准备 + +#### 1.1 安装Docker + +**Windows/Mac：** +```bash +# 下载并安装Docker Desktop +# https://www.docker.com/products/docker-desktop/ + +# 验证安装 +docker --version +docker-compose --version +``` + +**Linux（CentOS/Ubuntu）：** +```bash +# CentOS 7/8 +sudo yum install -y docker docker-compose + +# Ubuntu 20.04/22.04 +sudo apt update +sudo apt install -y docker.io docker-compose + +# 启动Docker +sudo systemctl start docker +sudo systemctl enable docker + +# 验证安装 +docker --version +docker-compose --version +``` + +#### 1.2 获取REDCap源码 + +**重要说明：** REDCap是商业软件，需要： +1. 访问 https://projectredcap.org/ +2. 注册并申请社区版或商业版 +3. 下载REDCap 15.8.0源码包（redcap15.8.0.zip） + +**目录结构：** +``` +your-project/ +├── redcap-docker-dev/ # Docker配置目录 +│ ├── Dockerfile.redcap +│ ├── docker-compose.yml +│ ├── docker-entrypoint.sh +│ ├── config/ +│ └── scripts/ +│ +└── redcap15.8.0/ # REDCap源码（解压后） + ├── redcap_v15.8.0/ + ├── install.php + ├── index.php + └── ... +``` + +--- + +### 阶段2：配置Docker文件 + +#### 2.1 创建项目目录 + +```bash +# 创建目录结构 +mkdir -p redcap-docker-dev/config/{apache,php} +mkdir -p redcap-docker-dev/scripts +mkdir -p redcap-docker-dev/data/mysql # MySQL数据持久化 +mkdir -p redcap-docker-dev/logs # 日志目录 +``` + +#### 2.2 复制Docker配置文件 + +**从我们的项目中复制以下文件：** + +```bash +# 核心文件（可直接复用，无需修改） +cp AIclinicalresearch/redcap-docker-dev/Dockerfile.redcap ./ +cp AIclinicalresearch/redcap-docker-dev/docker-entrypoint.sh ./ +cp AIclinicalresearch/redcap-docker-dev/config/php/php.ini ./config/php/ +cp AIclinicalresearch/redcap-docker-dev/.gitattributes ./ + +# 需要修改的文件 +cp AIclinicalresearch/redcap-docker-dev/docker-compose.yml ./ +cp AIclinicalresearch/redcap-docker-dev/config/apache/redcap.conf ./config/apache/ +cp AIclinicalresearch/redcap-docker-dev/config/database.php ./config/ +``` + +#### 2.3 配置环境变量（可选） + +创建`.env`文件（参考`env.template`）： + +```env +# MySQL配置 +MYSQL_ROOT_PASSWORD=your_strong_root_password_here +MYSQL_DATABASE=redcap +MYSQL_USER=redcap_user +MYSQL_PASSWORD=your_strong_password_here + +# REDCap配置 +REDCAP_VERSION=15.8.0 +REDCAP_BASE_URL=http://localhost:8080 + +# 端口配置（避免冲突） +REDCAP_WEB_PORT=8080 +MYSQL_PORT=3306 +PHPMYADMIN_PORT=8081 +``` + +#### 2.4 修改database.php（重要！） + +编辑`config/database.php`，根据环境修改： + +**开发环境（Docker MySQL）：** +```php +$hostname = 'redcap-mysql'; // Docker Compose服务名 +$db = 'redcap'; +$username = 'redcap_user'; +$password = 'your_password'; // 与.env保持一致 +$salt = 'dev_salt_2026'; // 开发环境固定salt +``` + +**生产环境（阿里云RDS）：** +```php +$hostname = 'rm-xxx.mysql.rds.aliyuncs.com'; // RDS内网地址 +$db = 'redcap_prod'; +$username = 'redcap_admin'; +$password = 'your_strong_prod_password'; // 强密码！ +$salt = 'your_random_32_chars_salt'; // ⚠️ 永不可变！ +``` + +**⚠️ 关键注意事项：** +1. ✅ **删除文件末尾的`?>`和空行**（防止CRLF污染） +2. ✅ **Salt值一旦设置永不可改**（影响数据去标识化） +3. ✅ **生产环境使用强密码**（32+字符） + +--- + +### 阶段3：部署REDCap + +#### 3.1 检查REDCap源码位置 + +**确保`docker-compose.yml`中的卷挂载路径正确：** + +```yaml +services: + redcap-web: + volumes: + # 将REDCap源码挂载到容器 + - ../redcap15.8.0:/var/www/html/redcap:ro # 只读挂载 + + # 将database.php复制到容器（读写） + - ./config/database.php:/var/www/html/redcap/database.php +``` + +**路径说明：** +- `../redcap15.8.0`：相对于`redcap-docker-dev`目录 +- 如果源码在其他位置，修改为绝对路径：`D:/path/to/redcap15.8.0` + +#### 3.2 构建并启动容器 + +```bash +# 进入Docker配置目录 +cd redcap-docker-dev + +# 构建REDCap镜像（首次部署需要，约5-10分钟） +docker-compose build + +# 启动所有服务 +docker-compose up -d + +# 查看容器状态 +docker-compose ps + +# 查看日志（排查问题） +docker-compose logs -f redcap-web +``` + +**预期输出：** +``` +NAME IMAGE STATUS PORTS +redcap-apache redcap-custom:15.8.0 Up 10 seconds 0.0.0.0:8080->80/tcp +redcap-mysql mysql:8.0 Up 10 seconds 3306/tcp +redcap-phpmyadmin phpmyadmin/phpmyadmin Up 10 seconds 0.0.0.0:8081->80/tcp +``` + +#### 3.3 初始化数据库 + +**方法1：通过REDCap安装向导（推荐）** + +1. 访问 `http://localhost:8080/install.php` +2. 按照向导完成安装 +3. 创建管理员账户 + +**方法2：导入SQL文件** + +```bash +# 如果有现成的redcap_install.sql +docker exec -i redcap-mysql mysql -uredcap_user -p'your_password' redcap < redcap_install.sql + +# 重置管理员密码 +docker cp scripts/create-redcap-password.php redcap-apache:/tmp/ +docker exec redcap-apache php /tmp/create-redcap-password.php +``` + +--- + +### 阶段4：验证部署 + +#### 4.1 访问REDCap + +**主页：** http://localhost:8080/ + +**预期结果：** +- ✅ 页面正常显示，有REDCap Logo +- ✅ CSS/JS加载正常，无404错误 +- ✅ 登录框可见 + +**如果页面样式错乱：** 参见下方"问题排查"章节 + +#### 4.2 测试登录 + +**默认账户：** +- Username: `Admin` +- Password: `Admin123!`（或你设置的密码） + +**预期结果：** +- ✅ 登录成功，跳转到主页 +- ✅ 可以看到"Control Center"、"My Projects"等菜单 + +#### 4.3 访问phpMyAdmin + +**地址：** http://localhost:8081/ + +**登录信息：** +- 服务器：`redcap-mysql` +- 用户名：`redcap_user` +- 密码：（与database.php中的密码一致） + +**验证数据库：** +- ✅ 可以看到`redcap`数据库 +- ✅ 有100+张表（如`redcap_config`, `redcap_user_information`等） + +--- + +## ⚠️ 常见问题与解决方案 + +### 问题1：ERR_CONTENT_DECODING_FAILED + +**现象：** +- 浏览器访问REDCap时报错：`net::ERR_CONTENT_DECODING_FAILED 200 (OK)` +- CSS/JS文件加载失败 + +**根本原因：** +Apache的`mod_deflate`模块与PHP的`zlib.output_compression`冲突，导致数据被重复压缩。 + +**解决方案：** + +✅ **我们的Docker配置已自动修复此问题：** + +1. `docker-entrypoint.sh`自动禁用`deflate`模块： + ```bash + a2dismod -f deflate + ``` + +2. `php.ini`中已关闭压缩： + ```ini + zlib.output_compression = Off + output_buffering = Off + ``` + +3. `redcap.conf`中注释掉了`mod_deflate`配置 + +**如果还有问题：** +```bash +# 进入容器检查 +docker exec redcap-apache bash -c "apache2ctl -M | grep deflate" +# 应该没有输出 + +# 重启容器 +docker-compose restart redcap-web +``` + +--- + +### 问题2：登录失败 - 无法加载响应数据 + +**现象：** +- 输入用户名密码后，页面不跳转 +- Network面板显示POST请求返回200，但"无法加载响应数据" + +**根本原因：** +`database.php`文件末尾有`?>`PHP结束标签和空行，导致CRLF换行符污染HTTP响应。 + +**解决方案：** + +✅ **我们提供的`database.php`模板已修复此问题：** + +1. ✅ 文件末尾**没有`?>`** +2. ✅ 文件末尾**没有空行** +3. ✅ `.gitattributes`强制PHP文件使用LF换行符 + +**如果自己创建database.php：** +```php + + + +// ✅ 正确写法：文件末尾只有注释的结束符，没有?> +``` + +**验证方法：** +```bash +# 检查文件末尾（十六进制） +docker exec redcap-apache bash -c "tail -c 50 /var/www/html/redcap/database.php | xxd" + +# 应该看到： +# 00000030: 2a2f 0a # */ 和换行符，没有 ?> 和多余的0d0a +``` + +--- + +### 问题3：Base URL配置错误 + +**现象：** +- CSS/JS文件路径错误，例如：`http://localhost:8080/redcap/redcap_v15.8.0/Resources/...` +- 实际路径应该是：`http://localhost:8080/redcap_v15.8.0/Resources/...` + +**根本原因：** +REDCap数据库中的`redcap_base_url`配置与Apache的`DocumentRoot`不匹配。 + +**解决方案：** + +```sql +-- 连接到MySQL容器 +docker exec -it redcap-mysql mysql -uredcap_user -p'your_password' redcap + +-- 查看当前配置 +SELECT field_name, value FROM redcap_config WHERE field_name = 'redcap_base_url'; + +-- 修正为正确的Base URL +UPDATE redcap_config +SET value = 'http://localhost:8080' +WHERE field_name = 'redcap_base_url'; + +-- 生产环境改为实际域名 +-- UPDATE redcap_config +-- SET value = 'https://redcap.yourdomain.com' +-- WHERE field_name = 'redcap_base_url'; +``` + +**预防措施：** +- 安装时确保Base URL与访问地址一致 +- 修改后重启浏览器或清除缓存 + +--- + +### 问题4：容器启动失败 + +**常见原因与解决方案：** + +**4.1 端口被占用** +```bash +# 检查端口占用 +netstat -ano | findstr ":8080" # Windows +lsof -i :8080 # Linux/Mac + +# 解决方案1：修改docker-compose.yml端口映射 +ports: + - "8090:80" # 改为8090或其他端口 + +# 解决方案2：停止占用端口的程序 +``` + +**4.2 卷挂载路径错误** +```bash +# 检查REDCap源码路径是否存在 +ls -la ../redcap15.8.0 + +# 如果路径错误，修改docker-compose.yml +volumes: + - /absolute/path/to/redcap15.8.0:/var/www/html/redcap:ro +``` + +**4.3 权限问题（Linux）** +```bash +# 给予Docker目录适当权限 +sudo chown -R $(whoami):$(whoami) redcap-docker-dev/ +chmod +x docker-entrypoint.sh +``` + +--- + +### 问题5：MySQL连接失败 + +**现象：** +- REDCap显示"Database connection failed" +- 日志中有MySQL连接错误 + +**排查步骤：** + +```bash +# 1. 检查MySQL容器状态 +docker-compose ps redcap-mysql + +# 2. 查看MySQL日志 +docker-compose logs redcap-mysql + +# 3. 手动测试连接 +docker exec -it redcap-mysql mysql -uredcap_user -p'your_password' + +# 4. 检查database.php中的配置 +docker exec redcap-apache cat /var/www/html/redcap/database.php | grep hostname +``` + +**常见错误：** +- `$hostname`写成了`localhost`（应该是`redcap-mysql`） +- 密码不匹配（与`.env`或`docker-compose.yml`不一致） +- MySQL容器未完全启动（等待30秒再试） + +--- + +## 🔄 不同环境的配置差异 + +### 本地开发环境 + +**特点：** +- 使用Docker MySQL容器 +- 包含phpMyAdmin +- 端口映射到localhost +- 开发调试模式 + +**需要修改的配置：** +1. `docker-compose.yml`：使用默认配置 +2. `database.php`：`$hostname = 'redcap-mysql'` + +--- + +### 阿里云ECS生产环境 + +**特点：** +- 使用阿里云RDS MySQL +- 不包含phpMyAdmin（安全考虑） +- 使用域名+SSL证书 +- 生产优化配置 + +**需要修改的配置：** + +1. **使用`docker-compose.prod.yml`：** + ```yaml + services: + redcap-web: + environment: + REDCAP_BASE_URL: https://redcap.yourdomain.com + + # 移除redcap-mysql和redcap-phpmyadmin服务 + ``` + +2. **修改`database.php`：** + ```php + $hostname = 'rm-xxx.mysql.rds.aliyuncs.com'; // RDS内网地址 + $db = 'redcap_prod'; + $username = 'redcap_admin'; + $password = 'your_strong_password_32_chars_min'; // 强密码 + $salt = 'your_random_salt_never_change'; // 永不可变 + + // 启用SSL连接（可选但推荐） + $db_ssl_ca = '/path/to/rds-ca.pem'; + $db_ssl_verify_server_cert = true; + ``` + +3. **修改`redcap.conf`：** + ```apache + ServerName redcap.yourdomain.com + ``` + +4. **构建并推送镜像到ACR：** + ```bash + # 登录阿里云容器镜像服务 + docker login --username=your_username registry.cn-hangzhou.aliyuncs.com + + # 构建镜像 + docker build -f Dockerfile.redcap -t redcap-custom:15.8.0 . + + # 打标签 + docker tag redcap-custom:15.8.0 registry.cn-hangzhou.aliyuncs.com/your-namespace/redcap:15.8.0 + + # 推送 + docker push registry.cn-hangzhou.aliyuncs.com/your-namespace/redcap:15.8.0 + ``` + +5. **在ECS上部署：** + ```bash + # 拉取镜像 + docker pull registry.cn-hangzhou.aliyuncs.com/your-namespace/redcap:15.8.0 + + # 启动容器 + docker-compose -f docker-compose.prod.yml up -d + ``` + +--- + +### 医院私有化部署 + +**特点：** +- 内网环境，无外网访问 +- 可能无法使用Docker Hub +- 需要数据安全与合规 +- 可能需要集成医院HIS系统 + +**部署步骤：** + +1. **离线准备Docker镜像：** + ```bash + # 在有网络的环境导出镜像 + docker save redcap-custom:15.8.0 mysql:8.0 phpmyadmin/phpmyadmin:latest > redcap-images.tar + + # 传输到医院服务器 + scp redcap-images.tar user@hospital-server:/tmp/ + + # 在医院服务器导入 + docker load < /tmp/redcap-images.tar + ``` + +2. **配置内网数据库：** + - 使用医院自己的MySQL服务器 + - 或部署独立的MySQL容器（数据目录挂载到医院存储） + +3. **数据安全配置：** + - 启用数据库SSL连接 + - 配置定期备份 + - 日志审计 + - 符合《数据安全法》和医疗行业规范 + +--- + +## 📋 部署检查清单 + +### 部署前检查 + +- [ ] Docker已安装并运行（`docker --version`） +- [ ] Docker Compose已安装（`docker-compose --version`） +- [ ] REDCap源码已下载并解压 +- [ ] 已复制所有Docker配置文件 +- [ ] `database.php`已根据环境修改 +- [ ] `database.php`末尾**没有`?>`和空行** +- [ ] `.env`文件已创建（如使用） +- [ ] 端口无冲突（8080, 3306, 8081） + +### 部署后验证 + +- [ ] 容器全部启动（`docker-compose ps`） +- [ ] 可以访问REDCap首页（http://localhost:8080/） +- [ ] 页面样式正常，无404错误 +- [ ] 可以成功登录 +- [ ] phpMyAdmin可访问（http://localhost:8081/） +- [ ] 数据库表已创建（100+张表） +- [ ] 可以创建项目 +- [ ] 可以创建表单 +- [ ] 数据可以正常保存 + +### 生产环境额外检查 + +- [ ] 使用强密码（32+字符） +- [ ] Salt值已设置且备份 +- [ ] 使用HTTPS + SSL证书 +- [ ] 防火墙规则已配置 +- [ ] 数据库定期备份已配置 +- [ ] 日志监控已配置 +- [ ] 域名DNS已解析 +- [ ] 邮件服务已配置（可选） + +--- + +## 🛠️ 日常维护命令 + +### 容器管理 + +```bash +# 启动服务 +docker-compose up -d + +# 停止服务 +docker-compose stop + +# 重启服务 +docker-compose restart + +# 停止并删除容器（数据保留） +docker-compose down + +# 停止并删除容器+数据（危险！） +docker-compose down -v + +# 查看日志 +docker-compose logs -f redcap-web +docker-compose logs -f redcap-mysql + +# 进入容器 +docker exec -it redcap-apache bash +docker exec -it redcap-mysql bash +``` + +### 备份与恢复 + +```bash +# 备份数据库 +docker exec redcap-mysql mysqldump -uredcap_user -p'password' redcap > backup_$(date +%Y%m%d).sql + +# 恢复数据库 +docker exec -i redcap-mysql mysql -uredcap_user -p'password' redcap < backup_20260102.sql + +# 备份edocs和temp目录 +docker cp redcap-apache:/var/www/html/redcap/edocs ./backup_edocs +docker cp redcap-apache:/var/www/html/redcap/temp ./backup_temp +``` + +### 重置管理员密码 + +```bash +# 使用我们提供的脚本 +docker cp scripts/create-redcap-password.php redcap-apache:/tmp/ +docker exec redcap-apache php /tmp/create-redcap-password.php + +# 新密码将显示在输出中 +``` + +--- + +## 📚 相关文档 + +- **问题排查详解**：[13-部署问题排查手册.md](./13-部署问题排查手册.md) +- **API开发**：[../03-API对接与开发/30-REDCap_API使用指南.md](../03-API对接与开发/30-REDCap_API使用指南.md) +- **系统配置**：[../02-系统配置与运维/20-REDCap系统配置手册.md](../02-系统配置与运维/20-REDCap系统配置手册.md) +- **REDCap官方文档**：https://projectredcap.org/ + +--- + +## ✅ 总结 + +**我们提供的Docker配置文件经过实战验证，已解决所有常见问题：** + +1. ✅ **Gzip压缩冲突** → 自动禁用deflate模块 +2. ✅ **CRLF污染** → database.php无`?>`，.gitattributes规范换行符 +3. ✅ **Base URL错误** → 文档明确说明配置方法 +4. ✅ **跨平台兼容** → Windows/Linux/Mac均可使用 + +**可复用性：** +- 🔄 **Dockerfile.redcap**：100%可复用，无需任何修改 +- 🔄 **docker-entrypoint.sh**：100%可复用 +- 🔄 **php.ini**：100%可复用 +- ⚠️ **docker-compose.yml**：需根据环境调整端口和卷路径 +- ⚠️ **database.php**：必须根据环境定制数据库连接信息 + +**下一步：** +- 完成本地环境验证 +- 开发REDCap API Adapter +- 准备生产环境部署 + +--- + +**有问题？** 查看 [13-部署问题排查手册.md](./13-部署问题排查手册.md) 或提Issue！ + diff --git a/docs/03-业务模块/Redcap/01-部署与配置/13-部署问题排查手册.md b/docs/03-业务模块/Redcap/01-部署与配置/13-部署问题排查手册.md new file mode 100644 index 00000000..322b672a --- /dev/null +++ b/docs/03-业务模块/Redcap/01-部署与配置/13-部署问题排查手册.md @@ -0,0 +1,203 @@ +# REDCap Docker 本地部署问题解决记录 + +**日期：** 2026-01-02 +**版本：** REDCap 15.8.0 +**环境：** Windows 10 + Docker Desktop + Docker Compose + +--- + +## 📋 部署成功确认 + +✅ **REDCap 15.8.0 已成功部署在本地Docker环境** + +- **访问地址：** http://localhost:8080/ +- **管理员账户：** Admin / Admin123! +- **数据库：** MySQL 8.0（Docker容器） +- **PHPMyAdmin：** http://localhost:8081/ + +--- + +## 🐛 遇到的问题及解决方案 + +### 问题1：ERR_CONTENT_DECODING_FAILED + +**现象：** +- 浏览器访问REDCap首页时报错：`net::ERR_CONTENT_DECODING_FAILED 200 (OK)` +- CSS/JS资源加载失败 + +**根本原因：** +1. Apache的`mod_deflate`模块与PHP的`zlib.output_compression`冲突 +2. REDCap源码中动态启用了压缩（`System.php`、`general_settings.php`中的`ini_set`） +3. 导致数据被多次压缩，浏览器无法解码 + +**解决方案：** +1. ✅ 在`docker-entrypoint.sh`中强制禁用Apache的deflate模块：`a2dismod -f deflate` +2. ✅ 在`php.ini`中显式关闭压缩： + ```ini + zlib.output_compression = Off + output_buffering = Off + ``` +3. ✅ 在`docker-entrypoint.sh`中自动注释REDCap源码中的`ini_set('zlib.output_compression', ...)` + +**预防措施：** +- 已在`redcap.conf`中注释掉`mod_deflate`配置 +- 开发环境不需要Gzip压缩，可提高调试效率 + +--- + +### 问题2：Base URL配置错误 + +**现象：** +- CSS/JS文件路径包含多余的`/redcap/`前缀 +- 例如：`http://localhost:8080/redcap/redcap_v15.8.0/Resources/...` +- 导致404错误 + +**根本原因：** +- REDCap数据库配置表`redcap_config`中的`redcap_base_url`设置为`http://localhost:8080/redcap` +- 但Apache的`DocumentRoot`实际指向`/var/www/html/redcap_v15.8.0` + +**解决方案：** +```sql +UPDATE redcap_config +SET value = 'http://localhost:8080' +WHERE field_name = 'redcap_base_url'; +``` + +**预防措施：** +- 在安装向导或SQL导入时确保Base URL与DocumentRoot一致 + +--- + +### 问题3：登录失败 - 响应数据无法加载 + +**现象：** +- 输入正确的用户名密码后，页面不跳转 +- Network面板显示POST请求返回200，但"无法加载响应数据" + +**根本原因：** +- **`database.php`文件末尾有`?>`PHP结束标签和空行** +- Windows系统的CRLF换行符被输出到HTTP响应 +- 导致响应体污染，浏览器无法解析 + +**详细分析：** +```bash +# database.php末尾的十六进制内容 +00000050: e585 a80d 0a20 2a2f 0d0a 0d0a 3f3e 0d0a ..... */....?>.. +00000060: 0d0a 0d0a .... + # `*/` CRLF CRLF `?>` CRLF CRLF CRLF +``` + +**解决方案：** +1. ✅ **删除`database.php`末尾的`?>`和所有空行** +2. ✅ **创建`.gitattributes`强制PHP文件使用LF换行符** +3. ✅ **在`docker-entrypoint.sh`中添加检查逻辑（警告提示）** + +**PHP最佳实践：** +- 📌 **配置文件和库文件末尾不应该写`?>`** +- 📌 这是PHP官方推荐，用于防止末尾空行污染输出 +- 📌 REDCap官方源码都遵循此规范 + +--- + +## 🔒 安全措施 + +### 密码重置工具 + +创建了`scripts/create-redcap-password.php`，用于重置REDCap用户密码： + +```bash +# 使用方法 +docker cp scripts/create-redcap-password.php redcap-apache:/tmp/ +docker exec redcap-apache php /tmp/create-redcap-password.php +``` + +**注意：** 此脚本仅用于开发环境！生产环境应禁用。 + +--- + +## ✅ 最终确认 + +### REDCap系统是安全的 + +**重要结论：** +1. ✅ **REDCap官方源码（15.8.0版本，数千个PHP文件）都是规范的** +2. ✅ **官方文件末尾都没有`?>`，不存在CRLF污染问题** +3. ✅ **问题仅存在于我们创建的配置文件`database.php`** +4. ✅ **一旦修复，不会有其他类似问题** + +**验证证据：** +```bash +# REDCap官方index.php末尾（规范） +tail -c 20 /var/www/html/redcap/redcap_v15.8.0/index.php | xxd +00000000: 656e 6572 616c 2f66 6f6f 7465 722e 7068 eneral/footer.ph +00000010: 7027 3b0a p';. +# 末尾只有 '; 和换行符，没有?> + +# REDCap官方Authentication.php末尾（规范） +tail -c 30 /var/www/html/redcap/redcap_v15.8.0/Classes/Authentication.php | xxd +00000000: 6c2c 205b 2475 7365 7269 645d 2929 203e l, [$userid])) > +00000010: 2030 3b0a 0909 7d0a 097d 0a0a 7d0a 0;...}..}..}. +# 末尾只有 } 和换行符，没有?> +``` + +--- + +## 📚 经验总结 + +### 1. Docker跨平台注意事项 + +**Windows + Docker + Linux容器组合会暴露文件格式问题：** +- Windows默认CRLF (`\r\n`) +- Linux默认LF (`\n`) +- Git的`autocrlf`设置可能自动转换 +- 使用`.gitattributes`显式控制换行符 + +### 2. PHP配置文件最佳实践 + +```php + + + +``` + +```php +` +- [ ] 文件换行符统一为LF +- [ ] 密码哈希正确生成 +- [ ] Session目录权限正确 + +--- + +## 🚀 后续部署到生产环境 + +**本地Docker开发环境已验证通过，可以安全迁移到阿里云ECS：** + +1. ✅ 使用相同的`Dockerfile.redcap`构建镜像 +2. ✅ 修改`database.php`连接到RDS +3. ✅ 生产环境可以启用Gzip压缩（使用Nginx反向代理） +4. ✅ 所有配置文件已经过验证，不会有CRLF问题 + +**未来不需要逐个排查REDCap文件，因为官方代码是规范的！** ✨ + +--- + +## 📞 联系方式 + +如有问题，请查看： +- REDCap官方文档：https://projectredcap.org/ +- 部署方案文档：`docs/03-REDCap本地Docker开发环境部署方案.md` + diff --git a/docs/03-业务模块/Redcap/REDCap 二次开发深度指南.md b/docs/03-业务模块/Redcap/03-API对接与开发/33-REDCap二次开发深度指南.md similarity index 100% rename from docs/03-业务模块/Redcap/REDCap 二次开发深度指南.md rename to docs/03-业务模块/Redcap/03-API对接与开发/33-REDCap二次开发深度指南.md diff --git a/docs/03-业务模块/Redcap/02-REDCap部署指南与环境要求.md b/docs/03-业务模块/Redcap/04-参考资料/02-REDCap部署指南与环境要求_旧版.md similarity index 100% rename from docs/03-业务模块/Redcap/02-REDCap部署指南与环境要求.md rename to docs/03-业务模块/Redcap/04-参考资料/02-REDCap部署指南与环境要求_旧版.md diff --git a/docs/03-业务模块/Redcap/03-REDCap本地Docker开发环境部署方案.md b/docs/03-业务模块/Redcap/04-参考资料/03-REDCap本地Docker开发环境部署方案_旧版.md similarity index 100% rename from docs/03-业务模块/Redcap/03-REDCap本地Docker开发环境部署方案.md rename to docs/03-业务模块/Redcap/04-参考资料/03-REDCap本地Docker开发环境部署方案_旧版.md diff --git a/docs/03-业务模块/Redcap/README.md b/docs/03-业务模块/Redcap/README.md new file mode 100644 index 00000000..15b215a1 --- /dev/null +++ b/docs/03-业务模块/Redcap/README.md @@ -0,0 +1,140 @@ +# REDCap模块文档 + +**版本：** v1.0 +**最后更新：** 2026-01-02 +**模块状态：** 🟢 本地环境已部署，API开发中 + +--- + +## 🚀 快速开始 + +### 我想部署REDCap +👉 **[10-REDCap_Docker部署操作手册.md](./01-部署与配置/10-REDCap_Docker部署操作手册.md)** ⭐ + +这是最核心的文档！包含： +- ✅ 从0到1的完整部署流程 +- ✅ Docker文件复用说明 +- ✅ 常见问题与解决方案 +- ✅ 适用于本地/ECS/医院环境 + +**30分钟完成部署！** + +--- + +### 我遇到问题了 +👉 **[13-部署问题排查手册.md](./01-部署与配置/13-部署问题排查手册.md)** 🔧 + +基于实际踩坑经验，包含： +- ERR_CONTENT_DECODING_FAILED解决方案 +- 登录失败（CRLF污染）解决方案 +- Base URL配置错误修复 +- MySQL连接问题排查 + +--- + +## 📚 完整文档目录 + +### [00-模块概览](./00-模块概览/) +- [00-REDCap模块文档导航.md](./00-模块概览/00-REDCap模块文档导航.md) - 完整文档索引 +- [02-REDCap对接总体方案.md](./00-模块概览/02-REDCap对接总体方案.md) - 技术架构设计 +- [03-REDCap对接风险评估与技术挑战分析.md](./00-模块概览/03-REDCap对接风险评估与技术挑战分析.md) - 风险评估 +- [04-生产环境部署决策报告_ECS_vs_SAE.md](./00-模块概览/04-生产环境部署决策报告_ECS_vs_SAE.md) - ECS vs SAE对比 + +### [01-部署与配置](./01-部署与配置/) ⭐ +- **[10-REDCap_Docker部署操作手册.md](./01-部署与配置/10-REDCap_Docker部署操作手册.md)** - 核心部署文档 +- [13-部署问题排查手册.md](./01-部署与配置/13-部署问题排查手册.md) - 问题解决记录 + +### [02-系统配置与运维](./02-系统配置与运维/) +- 🚧 20-REDCap系统配置手册.md（规划中） +- 🚧 21-REDCap日常运维手册.md（规划中） +- 🚧 22-REDCap升级指南.md（规划中） + +### [03-API对接与开发](./03-API对接与开发/) +- [33-REDCap二次开发深度指南.md](./03-API对接与开发/33-REDCap二次开发深度指南.md) - External Modules开发 +- 🚧 30-REDCap_API使用指南.md（开发中） +- 🚧 31-IIT_Manager与REDCap对接设计.md（开发中） +- 🚧 32-REDCap_API_Adapter开发指南.md（开发中） + +### [04-参考资料](./04-参考资料/) +- 旧版文档存档 + +--- + +## 📊 当前进度 + +| 阶段 | 状态 | 完成日期 | +|------|------|----------| +| 技术调研 | ✅ 完成 | 2025-12 | +| 部署方案设计 | ✅ 完成 | 2026-01-01 | +| **本地环境部署** | ✅ **完成** | **2026-01-02** | +| API Adapter开发 | ⏳ 进行中 | 预计2026-01-03 | +| 生产环境部署 | 📅 计划中 | 待定 | + +**访问地址：** http://localhost:8080/ +**管理员账户：** Admin / Admin123! + +--- + +## 🎯 REDCap在IIT Manager中的角色 + +``` +IIT Manager Agent (企业微信) + ↓ + REDCap API Adapter + ↓ + REDCap系统 (EDC) + ↓ + 研究数据采集与管理 +``` + +**核心功能：** +- 📋 电子数据采集（EDC） +- 📊 数据字典管理 +- 🔍 数据质量控制 +- 📈 报表与导出 +- 👥 用户权限管理 + +--- + +## 🛠️ Docker配置文件位置 + +**所有Docker配置文件都在：** +``` +AIclinicalresearch/redcap-docker-dev/ +├── Dockerfile.redcap ✅ 100%可复用 +├── docker-compose.yml ⚠️ 需微调 +├── docker-compose.prod.yml ⚠️ 需修改数据库配置 +├── docker-entrypoint.sh ✅ 100%可复用 +├── config/ +│ ├── apache/redcap.conf ⚠️ 需修改域名 +│ ├── php/php.ini ✅ 100%可复用 +│ └── database.php ❌ 必须根据环境定制 +├── scripts/ 可选辅助脚本 +└── .gitattributes ✅ 100%可复用 +``` + +详见：[10-REDCap_Docker部署操作手册.md](./01-部署与配置/10-REDCap_Docker部署操作手册.md) + +--- + +## 📞 获取帮助 + +- **部署问题**：查看 [13-部署问题排查手册.md](./01-部署与配置/13-部署问题排查手册.md) +- **REDCap官方**：https://projectredcap.org/ +- **技术支持**：查看相关文档或提Issue + +--- + +## 🔄 最近更新 + +| 日期 | 更新内容 | +|------|----------| +| 2026-01-02 | ✅ 完成本地Docker环境部署 | +| 2026-01-02 | ✅ 创建REDCap Docker部署操作手册 | +| 2026-01-02 | ✅ 创建部署问题排查手册 | +| 2026-01-02 | ✅ 重组文档体系 | + +--- + +**准备好开始了吗？** 👉 [开始部署](./01-部署与配置/10-REDCap_Docker部署操作手册.md) +