AIclinicalresearch/docs/03-业务模块/Redcap/04-参考资料/03-REDCap本地Docker开发环境部署方案_旧版.md

REDCap Docker部署方案（开发/生产一致性架构）

文档版本： v2.0
创建日期： 2026-01-01
最后更新： 2026-01-01（根据ECS决议报告修订）
文档目的： 指导IIT Manager Agent项目的REDCap Docker环境搭建（开发/生产架构一致）
阅读时间： 25分钟
重要性： ⭐⭐⭐⭐⭐ Day 2开发前必读
预计部署时间： 1.5小时
架构决策依据： REDCap生产环境部署：ECS vs SAE深度决议报告

---

📋 文档说明

核心理念：本地开发即生产环境 🎯

本文档基于IIT Manager Agent项目的混合架构决策，采用Docker容器化部署REDCap，实现：

• ✅ 开发环境 = 测试环境 = 生产环境（无环境漂移）
• ✅ Docker配置可直接用于阿里云ECS生产部署
• ✅ Docker配置可直接用于医院内网私有化部署
• ✅ 2人团队可维护的简单架构

架构定位

数据平面 (Data Layer) - REDCap部署策略：
├─ 本地开发：Docker Compose (Windows/Mac)
├─ 阿里云测试/生产：ECS + Docker + RDS MySQL
└─ 医院私有化：服务器 + Docker + 本地MySQL

控制平面 (AI Agent Layer) - 部署策略：
├─ Node.js后端：阿里云SAE (Serverless)
├─ Python微服务：阿里云SAE
└─ React前端：阿里云SAE

为什么REDCap用ECS而不是SAE？
❌ REDCap有三个"致命特性"不适合Serverless：
   1. Cron依赖（心跳任务）
   2. Session粘滞（本地会话）
   3. POSIX文件系统依赖（本地存储）

详见：REDCap生产环境部署：ECS vs SAE深度决议报告.md

适用场景

本地开发环境：

• ✅ REDCap API Adapter开发与测试
• ✅ External Module开发与调试
• ✅ IIT试验项目原型验证
• ✅ API Token测试和数据格式验证

生产环境（相同Docker配置 + 额外配置）：

• ✅ 阿里云ECS生产部署（+ RDS + OSS + SLB）
• ✅ 医院内网私有化部署（+ SSL + 备份）
• ✅ 多院区标准化交付

---

🎯 一、核心架构设计

1.1 容器架构（开发/生产一致）

生产级核心容器（必需）

REDCap Docker环境（开发/生产通用）
├─ 容器1: MySQL 8.0 数据库         【redcap-db】
│   ├─ 本地开发：Docker容器
│   └─ 生产环境：阿里云RDS MySQL（推荐）或Docker容器
│
└─ 容器2: Apache + PHP 8.1 + REDCap  【redcap-web】
    ├─ 包含Cron定时任务
    ├─ 包含External Modules
    └─ 本地存储（edocs/、modules/、temp/）

网络：redcap-network（bridge模式）
存储：Docker命名卷（持久化数据）

开发辅助容器（仅开发环境，生产禁用）

⚠️ 以下容器仅用于本地开发调试，生产环境出于安全考虑应禁用：

容器3: phpMyAdmin（可选）       【phpmyadmin】
├─ 用途：数据库可视化管理、调试
├─ 端口：8081
└─ 生产环境：❌ 不部署（安全风险）

说明：
生产环境数据库管理应通过：
✅ 阿里云RDS控制台
✅ MySQL命令行（SSH连接）
✅ 受限的DMS数据管理服务

1.2 架构优势

✅ 开发/生产环境一致（消除"在我机器上能跑"问题）
✅ MySQL在Docker内，无需本机安装（开发环境）
✅ 可无缝切换到RDS MySQL（生产环境）
✅ 所有依赖隔离，不污染主机环境
✅ 一键启动/停止，2人团队可维护
✅ 环境可重复构建（容器化标准交付）
✅ 易于销毁重建（测试友好）
✅ 数据持久化（Docker卷 或 RDS）
✅ 支持多版本并存（不同端口）
✅ 直接可用于医院内网部署（离线交付）

1.3 端口分配

服务	容器端口	主机端口	访问地址	生产环境
REDCap Web	80	8080	http://localhost:8080	✅ 部署（端口80）
MySQL	3306	3306	localhost:3306	⚠️ 或使用RDS
phpMyAdmin	80	8081	http://localhost:8081	❌ 禁用

生产环境端口调整：

• REDCap Web：使用标准80/443端口（通过SLB）
• MySQL：如使用RDS，无需暴露端口（内网连接）
• phpMyAdmin：不部署

---

🗂️ 二、文件结构规划

2.1 项目目录结构

AIclinicalresearch/
├─ redcap15.8.0/                    # ✅ 已有REDCap源码
│   └─ redcap/                      # REDCap核心文件
│
├─ redcap-docker-dev/               # 🆕 Docker部署目录（需创建）
│   ├─ docker-compose.yml           # Docker编排配置（核心）
│   ├─ Dockerfile.redcap            # REDCap容器镜像定义
│   ├─ .env                         # 环境变量（数据库密码等）
│   │
│   ├─ config/                      # 配置文件目录
│   │   ├─ apache/
│   │   │   └─ redcap.conf          # Apache虚拟主机配置
│   │   ├─ php/
│   │   │   └─ php.ini              # PHP配置
│   │   └─ database.php             # REDCap数据库连接配置
│   │
│   ├─ scripts/                     # 自动化脚本
│   │   ├─ setup-redcap.ps1         # 🔧 一键部署脚本（PowerShell）
│   │   ├─ start-redcap.ps1         # 🚀 启动脚本
│   │   ├─ stop-redcap.ps1          # ⏹️ 停止脚本
│   │   ├─ logs-redcap.ps1          # 📝 查看日志
│   │   └─ clean-redcap.ps1         # 🗑️ 清理环境
│   │
│   └─ README.md                    # 部署文档

2.2 目录说明

目录/文件	用途	开发环境	生产环境
docker-compose.yml	定义多容器应用	✅ 必需	✅ 必需（需调整）
Dockerfile.redcap	自定义REDCap镜像	✅ 必需	✅ 必需
.env	敏感信息（密码）	✅ 必需	✅ 必需（强密码）
config/apache/	Web服务器配置	✅ 必需	✅ 必需（+SSL）
config/php/	PHP运行时配置	✅ 必需	✅ 必需
config/database.php	REDCap数据库连接	✅ 必需	✅ 必需（RDS连接）
scripts/	运维脚本	⭐ 推荐	✅ 必需

生产环境额外需要：

• SSL证书文件（Let's Encrypt或商业证书）
• 备份脚本（数据库 + 文件）
• 监控配置（CloudMonitor Agent）
• 日志轮转配置

---

🔧 三、关键配置说明

3.1 MySQL配置（容器内）

3.1.1 基本配置

# docker-compose.yml - MySQL服务
services:
  redcap-db:
    image: mysql:8.0
    container_name: redcap-mysql
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${MYSQL_USER}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
    volumes:
      - redcap-db-data:/var/lib/mysql    # 数据持久化
    ports:
      - "3306:3306"
    networks:
      - redcap-network
    command: --default-authentication-plugin=mysql_native_password

3.1.2 环境变量（.env文件）

# 数据库配置（开发环境）
MYSQL_ROOT_PASSWORD=redcap_root_123
MYSQL_DATABASE=redcap
MYSQL_USER=redcap_user
MYSQL_PASSWORD=redcap_pass_456

# ⚠️ 警告：这些是开发环境密码！
# 生产环境必须使用强密码！

3.1.3 认证插件说明

# 为什么使用 mysql_native_password？
# REDCap 15.8.0兼容性要求
# 如果使用MySQL 8.0默认的caching_sha2_password会导致连接失败

---

3.2 PHP + Apache配置

3.2.1 PHP配置（php.ini）

# config/php/php.ini

# ========== 文件上传（REDCap必需）==========
upload_max_filesize = 32M         # REDCap文件上传限制
post_max_size = 32M               # 表单提交大小
max_file_uploads = 20             # 同时上传文件数

# ========== 执行时间（数据导出需要）==========
max_execution_time = 300          # 5分钟（大数据导出）
max_input_time = 300              # 输入解析时间

# ========== 内存（REDCap最低要求）==========
memory_limit = 256M               # REDCap推荐256MB

# ========== 时区（重要！）==========
date.timezone = Asia/Shanghai     # 北京时间

# ========== 错误报告（开发环境）==========
display_errors = On               # 开发环境显示错误
error_reporting = E_ALL           # 报告所有错误

# ========== Session配置 ==========
session.gc_maxlifetime = 3600     # Session过期时间（1小时）
session.cookie_lifetime = 0       # Cookie浏览器关闭时过期

3.2.2 PHP扩展（必需）

# Dockerfile.redcap 中安装扩展

# 核心扩展（REDCap必需）
RUN docker-php-ext-install \
    mysqli              # MySQL连接（必需）
    pdo_mysql           # PDO支持（必需）
    gd                  # 图片处理（验证码、图表）
    zip                 # 数据导出压缩
    mbstring            # 多字节字符串（UTF-8）
    curl                # API调用
    soap                # Web Service集成（可选）
    ldap                # LDAP认证（可选）

# Apache模块
RUN a2enmod rewrite ssl headers

3.2.3 Apache配置（redcap.conf）

# config/apache/redcap.conf

<VirtualHost *:80>
    ServerName localhost
    DocumentRoot /var/www/html/redcap
    
    <Directory /var/www/html/redcap>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
        
        # 防止目录遍历
        Options -Indexes
        
        # 允许.htaccess
        AllowOverride All
    </Directory>
    
    # 日志配置
    ErrorLog ${APACHE_LOG_DIR}/redcap-error.log
    CustomLog ${APACHE_LOG_DIR}/redcap-access.log combined
    
    # 安全头（开发环境可选）
    # Header always set X-Frame-Options "SAMEORIGIN"
    # Header always set X-Content-Type-Options "nosniff"
</VirtualHost>

---

3.3 REDCap database.php配置

3.3.1 数据库连接配置

<?php
// config/database.php

/**
 * REDCap数据库连接配置（Docker环境）
 * 此文件需要复制到REDCap源码的redcap/目录下
 */

global $log_all_errors;
$log_all_errors = TRUE;  // 开发环境开启详细日志

// ========== MYSQL DATABASE CONNECTION ==========
// Docker容器内连接配置
$hostname   = 'redcap-db';        # 容器服务名（不是localhost！）
$db         = 'redcap';           # 数据库名
$username   = 'redcap_user';      # 用户名
$password   = 'redcap_pass_456';  # 密码

// ========== SALT VARIABLE（重要！）==========
// 用于数据去标识化哈希
// ⚠️ 一旦设置，永远不可更改！
$salt = 'iit_dev_salt_2026_redcap_v15';  // 至少8个字符

// ========== SSL连接（开发环境不需要）==========
$db_ssl_key  = '';
$db_ssl_cert = '';
$db_ssl_ca   = '';
$db_ssl_capath = NULL;
$db_ssl_cipher = NULL;
$db_ssl_verify_server_cert = false;

?>

3.3.2 Salt值说明

什么是Salt？
- 用于REDCap数据导出时的去标识化
- 影响哈希数据的生成
- 一旦设置后不可更改（会导致历史数据无法解密）

开发环境建议：
- 使用固定的Salt值（便于多次重建环境）
- 包含项目标识（如'iit_dev_salt_2026'）
- 至少8个字符，建议20+字符

生产环境要求：
- 使用强随机Salt（32+字符）
- 包含大小写字母、数字、特殊字符
- 妥善备份（丢失会导致数据无法解密）

---

📧 四、邮件服务配置策略

4.1 三种配置方案对比

方案	复杂度	功能	推荐场景
方案A：跳过配置	⭐ 最简单	无邮件功能	✅ Day 2-8 API开发
方案B：MailHog	⭐⭐ 简单	本地邮件拦截	Day 9-10 邮件测试
方案C：真实SMTP	⭐⭐⭐ 复杂	真实邮件发送	后期集成测试

4.2 方案A：跳过配置（推荐用于Day 2-8）

优势：
✅ 配置最简单
✅ 启动最快
✅ 不影响API开发
✅ REDCap可正常运行

限制：
❌ 无法发送调查邀请
❌ 无法发送密码重置邮件
❌ 无法发送系统通知

实施方法：
1. REDCap安装时跳过SMTP配置步骤
2. 控制中心 → Email & Notification → 留空
3. 直接进行API开发

适用于：
✅ REDCap API Adapter开发
✅ External Module开发（不涉及邮件）
✅ 数据导入导出测试

4.3 方案B：MailHog（本地邮件测试）

# docker-compose.yml 添加MailHog服务
services:
  mailhog:
    image: mailhog/mailhog
    container_name: redcap-mailhog
    ports:
      - "1025:1025"   # SMTP端口
      - "8025:8025"   # Web UI端口
    networks:
      - redcap-network

# REDCap SMTP配置
SMTP Host: mailhog
SMTP Port: 1025
SMTP Auth: 无需认证

# 访问Web界面查看邮件
http://localhost:8025

使用场景：测试调查邀请、密码重置等邮件功能

4.4 方案C：真实SMTP（Gmail/Outlook）

# REDCap控制中心配置

# Gmail示例
SMTP Host: smtp.gmail.com
SMTP Port: 587
SMTP Auth: TLS
Username: your-email@gmail.com
Password: app-specific-password  # 不是Gmail密码！

# 限制
- Gmail：每天100封（免费账户）
- Outlook：每天300封
- 需要开启"不够安全的应用访问"或使用应用专用密码

推荐策略：

• Day 2-8：使用方案A（跳过）
• Day 9-10：如需测试邮件，临时切换到方案B
• 生产环境：使用企业SMTP或云服务（SendGrid、阿里云DirectMail）

---

🌐 五、本地 vs 云端部署

5.1 Docker镜像可移植性分析

本地Docker → 阿里云ECS：是否可以？

答案：可以，但不推荐直接迁移！

可以这样做：
1. 导出Docker镜像
   docker save redcap-local:1.0 -o redcap.tar
2. 上传到ECS
   scp redcap.tar user@ecs-ip:/tmp/
3. 在ECS导入
   docker load -i /tmp/redcap.tar
4. 运行容器
   docker run -d -p 80:80 redcap-local:1.0

但为什么不推荐？
❌ 性能：Docker多一层虚拟化，损失10-20%性能
❌ 稳定性：容器层增加复杂度和故障点
❌ 运维：医疗系统需要最大可控性
❌ 备份：容器数据备份更复杂
❌ 监控：直接部署更易于监控和调试

5.2 推荐的云端部署策略

本地开发（Docker）→ 云端生产（标准部署）

阶段1：本地Docker开发（当前）
- 目的：API Adapter开发、External Module开发
- 环境：Windows + Docker Desktop
- 数据：测试数据（可随时销毁）

阶段2：ECS标准部署（未来）
- 目的：生产环境、真实医疗数据
- 环境：Ubuntu 22.04 + LAMP
- 数据：RDS MySQL（高可用）+ OSS存储

迁移路径：
1. 在本地Docker完成External Module开发
2. 验证API Adapter功能
3. 在ECS上标准安装REDCap（LAMP）
4. 复制External Module代码到ECS
5. 配置生产级数据库和SMTP
6. 配置SSL证书和域名

5.3 环境对比表

对比项	本地Docker	阿里云ECS（标准部署）
部署方式	Docker Compose	LAMP手动安装
访问地址	localhost:8080	https://redcap.domain.com
数据库	Docker容器	RDS MySQL（推荐）或本地
存储	Docker卷	OSS或本地磁盘
邮件	跳过或MailHog	阿里云DirectMail/SendGrid
SSL	不需要	Let's Encrypt证书
性能	⭐⭐⭐	⭐⭐⭐⭐⭐
稳定性	⭐⭐⭐	⭐⭐⭐⭐⭐
成本	$0	$50-200/月
适用场景	开发测试	生产环境

---

🔑 六、关键注意事项

6.1 坑点1：文件权限问题 ⚠️

症状

安装时提示：
"Unable to write to /var/www/html/edocs directory"
"Unable to write to /var/www/html/temp directory"

原因

Apache运行用户（www-data）对目录无写权限
Docker容器内文件权限与主机不同步

解决方案

# 方法1：启动后手动修复（推荐）
docker exec -it redcap-web chown -R www-data:www-data /var/www/html/edocs
docker exec -it redcap-web chown -R www-data:www-data /var/www/html/temp
docker exec -it redcap-web chown -R www-data:www-data /var/www/html/modules

# 方法2：在Dockerfile中预先配置
RUN mkdir -p /var/www/html/edocs /var/www/html/temp /var/www/html/modules && \
    chown -R www-data:www-data /var/www/html

预防措施

# 检查权限
docker exec -it redcap-web ls -la /var/www/html/

# 应该看到：
drwxr-xr-x  www-data www-data  edocs
drwxr-xr-x  www-data www-data  temp
drwxr-xr-x  www-data www-data  modules

---

6.2 坑点2：数据库连接失败 ⚠️

症状

安装页面提示：
"Cannot connect to database"
"Access denied for user 'redcap_user'@'redcap-web.redcap-network'"

原因

原因1: MySQL容器未完全启动
原因2: database.php配置错误（hostname）
原因3: 认证插件不兼容（caching_sha2_password）

解决方案

问题1：MySQL未就绪

# 查看MySQL日志，等待"ready for connections"
docker-compose logs redcap-db | grep "ready for connections"

# 输出示例：
# 2026-01-01 10:00:00 [Server] /usr/sbin/mysqld: ready for connections.

# 建议等待30秒后再访问install.php

问题2：hostname配置错误

// ❌ 错误配置
$hostname = 'localhost';      // 容器内localhost不是MySQL
$hostname = '127.0.0.1';      // 同上
$hostname = 'redcap-mysql';   // 容器名，但应使用服务名

// ✅ 正确配置
$hostname = 'redcap-db';      // Docker Compose服务名

问题3：认证插件

# 确保docker-compose.yml中包含：
command: --default-authentication-plugin=mysql_native_password

# 或在MySQL容器内手动修改用户
docker exec -it redcap-mysql mysql -uroot -p
ALTER USER 'redcap_user'@'%' IDENTIFIED WITH mysql_native_password BY 'redcap_pass_456';
FLUSH PRIVILEGES;

---

6.3 坑点3：PHP扩展缺失 ⚠️

症状

install.php检查页面提示：
"The GD extension is not loaded"
"The ZIP extension is not loaded"
"The MySQLi extension is not loaded"

原因

php:8.1-apache基础镜像只包含核心扩展
REDCap需要额外安装10+个扩展

解决方案

Dockerfile中预装（推荐）

FROM php:8.1-apache

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    libpng-dev \
    libjpeg-dev \
    libfreetype6-dev \
    libzip-dev \
    libldap2-dev \
    && rm -rf /var/lib/apt/lists/*

# 安装PHP扩展
RUN docker-php-ext-configure gd --with-freetype --with-jpeg && \
    docker-php-ext-install -j$(nproc) \
    mysqli \
    pdo_mysql \
    gd \
    zip \
    mbstring \
    curl \
    soap \
    ldap

# 启用Apache模块
RUN a2enmod rewrite ssl headers

验证安装

# 进入容器检查
docker exec -it redcap-web php -m | grep -E '(mysqli|gd|zip|mbstring)'

# 应该看到：
gd
mbstring
mysqli
zip

---

6.4 坑点4：Windows路径映射 ⚠️

症状

容器启动失败或无法访问文件
Error: "no such file or directory"

原因

Windows路径格式与Linux不兼容
反斜杠(\)与正斜杠(/)冲突
绝对路径在Docker Desktop中可能有问题

解决方案

使用相对路径（推荐）

# ✅ 正确：相对路径
volumes:
  - ../redcap15.8.0/redcap:/var/www/html/redcap
  - ./config/apache/redcap.conf:/etc/apache2/sites-available/000-default.conf

# ❌ 错误：Windows绝对路径
volumes:
  - D:\MyCursor\AIclinicalresearch\redcap15.8.0\redcap:/var/www/html/redcap

# 🟡 可能可以：WSL路径（如果使用WSL2后端）
volumes:
  - /mnt/d/MyCursor/AIclinicalresearch/redcap15.8.0/redcap:/var/www/html/redcap

PowerShell中转换路径

# 获取当前目录的相对路径
$currentDir = Get-Location
$redcapSource = Join-Path $currentDir.Parent.FullName "redcap15.8.0\redcap"
Write-Host "REDCap Source: $redcapSource"

---

6.5 坑点5：端口冲突 ⚠️

症状

docker-compose up -d 失败
Error: "Bind for 0.0.0.0:8080 failed: port is already allocated"

原因

本机已有服务占用相同端口
- 8080: 可能有其他Web服务
- 3306: 可能已安装本地MySQL
- 8081: 可能有其他管理工具

解决方案

检查端口占用（Windows）

# 检查8080端口
netstat -ano | findstr :8080

# 输出示例：
# TCP    0.0.0.0:8080    0.0.0.0:0    LISTENING    1234

# 查看占用进程
tasklist | findstr 1234

# 结束进程（谨慎！）
taskkill /F /PID 1234

修改端口映射

# 如果8080被占用，改用8888
services:
  redcap-web:
    ports:
      - "8888:80"  # 主机8888 → 容器80

# 如果3306被占用，改用3307
  redcap-db:
    ports:
      - "3307:3306"

最佳实践

# 预先检查所有端口
netstat -ano | findstr :8080
netstat -ano | findstr :3306
netstat -ano | findstr :8081

# 如果都空闲，使用默认端口
# 如果有冲突，提前修改docker-compose.yml

---

6.6 坑点6：数据持久化误区 ⚠️

症状

容器删除后，数据丢失
docker-compose down 后无法恢复项目

原因

误用了--volumes参数删除了数据卷
没有理解Docker命名卷的概念

正确理解

Docker数据卷类型

# 类型1：命名卷（推荐，开发环境）
volumes:
  - redcap-db-data:/var/lib/mysql
# 特点：Docker管理，跨容器持久化，删除容器不影响

# 类型2：绑定挂载（不推荐，Windows性能差）
volumes:
  - ./mysql-data:/var/lib/mysql
# 特点：主机目录，可见但性能差

# 类型3：tmpfs（临时，不持久化）
tmpfs:
  - /var/lib/mysql
# 特点：内存存储，容器停止即丢失

安全操作

# ✅ 停止容器（保留数据）
docker-compose stop

# ✅ 停止并删除容器（保留数据）
docker-compose down

# ⚠️ 删除容器和网络，但保留卷（安全）
docker-compose down --volumes=false

# ❌ 删除所有（包括数据卷，危险！）
docker-compose down --volumes
docker-compose down -v  # 同上

数据备份

# 备份MySQL数据卷
docker run --rm -v redcap-db-data:/data -v $(pwd):/backup \
  ubuntu tar czf /backup/redcap-db-backup.tar.gz /data

# 恢复数据卷
docker run --rm -v redcap-db-data:/data -v $(pwd):/backup \
  ubuntu tar xzf /backup/redcap-db-backup.tar.gz -C /

---

🚀 七、部署流程（详细步骤）

7.1 阶段1：准备配置文件（15分钟）

步骤1：创建项目目录

# 进入项目根目录
cd D:\MyCursor\AIclinicalresearch

# 创建Docker部署目录
New-Item -ItemType Directory -Path "redcap-docker-dev" -Force
cd redcap-docker-dev

# 创建子目录
New-Item -ItemType Directory -Path "config\apache" -Force
New-Item -ItemType Directory -Path "config\php" -Force
New-Item -ItemType Directory -Path "scripts" -Force

步骤2：生成配置文件

# 此步骤将由自动化脚本完成，生成：
# - docker-compose.yml
# - Dockerfile.redcap
# - .env
# - config/apache/redcap.conf
# - config/php/php.ini
# - config/database.php
# - scripts/*.ps1

步骤3：验证REDCap源码

# 确认源码存在
Test-Path ..\redcap15.8.0\redcap\install.php

# 输出：True（表示源码存在）

---

7.2 阶段2：启动容器（10分钟）

步骤1：构建镜像

# 构建自定义REDCap镜像
docker-compose build

# 输出示例：
# Building redcap-web...
# Step 1/10 : FROM php:8.1-apache
# ...
# Successfully built abc123def456
# Successfully tagged redcap-docker-dev_redcap-web:latest

步骤2：启动所有容器

# 后台启动
docker-compose up -d

# 输出示例：
# Creating network "redcap-docker-dev_redcap-network" ... done
# Creating volume "redcap-docker-dev_redcap-db-data" ... done
# Creating redcap-mysql ... done
# Creating redcap-web   ... done
# Creating redcap-phpmyadmin ... done

步骤3：等待MySQL就绪

# 查看MySQL日志
docker-compose logs redcap-db | Select-String "ready for connections"

# 等待看到：
# [Server] /usr/sbin/mysqld: ready for connections.

# 建议等待30秒
Start-Sleep -Seconds 30

步骤4：修复文件权限

# 自动修复权限脚本（已包含在setup-redcap.ps1中）
docker exec -it redcap-web chown -R www-data:www-data /var/www/html/edocs
docker exec -it redcap-web chown -R www-data:www-data /var/www/html/temp
docker exec -it redcap-web chown -R www-data:www-data /var/www/html/modules

步骤5：验证容器状态

# 检查所有容器运行状态
docker-compose ps

# 应该看到：
# Name               State    Ports
# redcap-mysql       Up       0.0.0.0:3306->3306/tcp
# redcap-web         Up       0.0.0.0:8080->80/tcp
# redcap-phpmyadmin  Up       0.0.0.0:8081->80/tcp

---

7.3 阶段3：REDCap安装（30分钟）

步骤1：访问安装向导

打开浏览器访问：
http://localhost:8080/install.php

步骤2：系统要求检查

REDCap会自动检查：
✅ PHP版本 8.1.x
✅ MySQL连接
✅ PHP扩展（mysqli, gd, zip, etc.）
✅ 文件权限（edocs, temp可写）

如果有红叉❌，根据提示修复

步骤3：数据库配置

MySQL Hostname: redcap-db
MySQL Database: redcap
MySQL Username: redcap_user
MySQL Password: redcap_pass_456
Table Prefix: (留空，使用默认)

Salt: iit_dev_salt_2026_redcap_v15

步骤4：管理员账户

Username: admin
Password: Admin@123456  # 开发环境密码
Email: dev@example.com
First Name: Admin
Last Name: User

步骤5：SMTP配置

选择：Skip SMTP Configuration（跳过）
原因：Day 2-8不需要邮件功能

步骤6：完成安装

点击 "Complete Installation"
等待数据库表创建（约2-3分钟）
看到 "Installation Complete!" 消息

步骤7：首次登录

访问：http://localhost:8080/
用户名：admin
密码：Admin@123456

✅ 登录成功，看到REDCap主页

---

7.4 阶段4：创建测试项目（30分钟）

步骤1：新建项目

1. 点击 "New Project"
2. 项目标题：IIT Test Project
3. 项目目的：Research
4. 模板：Empty Project（从头创建）
5. 点击 "Create Project"

步骤2：设计数据字典

创建表单1：患者信息（Demographics）

字段列表：
1. record_id (Record ID)
   - 类型：Text Box
   - 验证：Integer
   - 标识符：Yes

2. patient_name (患者姓名)
   - 类型：Text Box
   - 标识符：Yes

3. age (年龄)
   - 类型：Text Box
   - 验证：Integer
   - 范围：1-120

4. gender (性别)
   - 类型：Radio Buttons
   - 选项：1, 男 | 2, 女

5. enrollment_date (入组日期)
   - 类型：Text Box
   - 验证：Date (Y-M-D)

创建表单2：随访记录（Follow-up）

字段列表：
1. followup_date (随访日期)
   - 类型：Text Box
   - 验证：Date (Y-M-D)

2. followup_type (随访类型)
   - 类型：Dropdown
   - 选项：1, 门诊 | 2, 电话 | 3, 线上

3. adverse_event (不良事件)
   - 类型：Yes-No
   - 默认：No

4. notes (备注)
   - 类型：Notes Box (Paragraph Text)

步骤3：创建测试数据

添加5条测试受试者记录：

Record 1:
- patient_name: 张三
- age: 45
- gender: 男
- enrollment_date: 2025-12-01

Record 2:
- patient_name: 李四
- age: 52
- gender: 女
- enrollment_date: 2025-12-05

... (省略3条)

步骤4：启用API访问

1. 进入项目
2. 左侧菜单 → Applications → API
3. 点击 "Enable API Access"
4. 勾选 "Export"、"Import" 权限
5. 点击 "Request API Token"
6. 系统生成Token（自动批准，因为是管理员）
7. 复制Token保存：
   示例：A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6

步骤5：测试API调用

# PowerShell测试导出数据
$apiUrl = "http://localhost:8080/api/"
$token = "YOUR_API_TOKEN_HERE"

$body = @{
    token = $token
    content = 'record'
    format = 'json'
    type = 'flat'
}

Invoke-RestMethod -Uri $apiUrl -Method Post -Body $body

# 应该返回JSON数组，包含5条测试数据

---

7.5 阶段5：配置后端环境变量（15分钟）

步骤1：更新后端.env

# AIclinicalresearch/backend/.env

# ========== REDCap配置（新增）==========
REDCAP_API_URL=http://localhost:8080/api/
REDCAP_API_TOKEN=A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6
REDCAP_PROJECT_ID=1

# 注意：localhost在Docker容器内需要改为host.docker.internal
# 如果后端也在Docker内，应使用容器IP或服务名

步骤2：创建API测试脚本

// backend/src/modules/iit-manager/test-redcap-api.ts

import axios from 'axios';

const REDCAP_API_URL = process.env.REDCAP_API_URL || 'http://localhost:8080/api/';
const REDCAP_API_TOKEN = process.env.REDCAP_API_TOKEN || '';

async function testREDCapAPI() {
  console.log('🔍 Testing REDCap API Connection...');
  
  try {
    const response = await axios.post(REDCAP_API_URL, new URLSearchParams({
      token: REDCAP_API_TOKEN,
      content: 'record',
      format: 'json',
      type: 'flat'
    }));
    
    console.log('✅ API Connection Successful!');
    console.log(`📊 Retrieved ${response.data.length} records`);
    console.log('Sample Record:', response.data[0]);
  } catch (error: any) {
    console.error('❌ API Connection Failed:', error.message);
  }
}

testREDCapAPI();

步骤3：运行测试

cd D:\MyCursor\AIclinicalresearch\backend
npx ts-node src/modules/iit-manager/test-redcap-api.ts

# 预期输出：
# 🔍 Testing REDCap API Connection...
# ✅ API Connection Successful!
# 📊 Retrieved 5 records
# Sample Record: { record_id: '1', patient_name: '张三', ... }

---

7.6 部署完成验证清单

验证项                                    状态
─────────────────────────────────────────────────
✅ Docker容器全部运行                      [ ]
✅ MySQL数据库可连接                       [ ]
✅ REDCap安装成功                          [ ]
✅ 管理员账户可登录                        [ ]
✅ 测试项目已创建                          [ ]
✅ API Token已生成                         [ ]
✅ API调用测试通过                         [ ]
✅ 后端环境变量已配置                      [ ]
✅ phpMyAdmin可访问（可选）                [ ]

全部勾选✅，表示部署成功！

---

💡 八、运维管理脚本

8.1 启动脚本（start-redcap.ps1）

#!/usr/bin/env pwsh
# start-redcap.ps1 - 启动REDCap开发环境

Write-Host "🚀 Starting REDCap Development Environment..." -ForegroundColor Cyan

# 检查Docker是否运行
$dockerRunning = docker info 2>&1 | Select-String "Server Version"
if (-not $dockerRunning) {
    Write-Host "❌ Docker is not running. Please start Docker Desktop." -ForegroundColor Red
    exit 1
}

# 启动容器
docker-compose up -d

# 等待MySQL就绪
Write-Host "⏳ Waiting for MySQL to be ready..." -ForegroundColor Yellow
Start-Sleep -Seconds 10

docker-compose logs redcap-db | Select-String "ready for connections"

# 显示服务状态
Write-Host ""
Write-Host "✅ REDCap Environment Started!" -ForegroundColor Green
Write-Host ""
Write-Host "📋 Service URLs:" -ForegroundColor Cyan
Write-Host "  REDCap:      http://localhost:8080" -ForegroundColor White
Write-Host "  phpMyAdmin:  http://localhost:8081" -ForegroundColor White
Write-Host ""
Write-Host "📊 Container Status:" -ForegroundColor Cyan
docker-compose ps

8.2 停止脚本（stop-redcap.ps1）

#!/usr/bin/env pwsh
# stop-redcap.ps1 - 停止REDCap开发环境

Write-Host "⏹️  Stopping REDCap Development Environment..." -ForegroundColor Yellow

# 停止容器（保留数据）
docker-compose stop

Write-Host "✅ REDCap Environment Stopped!" -ForegroundColor Green
Write-Host ""
Write-Host "💡 Data volumes are preserved." -ForegroundColor Cyan
Write-Host "   Run 'start-redcap.ps1' to restart." -ForegroundColor Cyan

8.3 查看日志脚本（logs-redcap.ps1）

#!/usr/bin/env pwsh
# logs-redcap.ps1 - 查看REDCap日志

param(
    [string]$Service = "",
    [switch]$Follow
)

Write-Host "📝 REDCap Container Logs" -ForegroundColor Cyan
Write-Host ""

if ($Follow) {
    # 实时跟踪日志
    if ($Service) {
        docker-compose logs -f $Service
    } else {
        docker-compose logs -f
    }
} else {
    # 显示最近日志
    if ($Service) {
        docker-compose logs --tail=50 $Service
    } else {
        docker-compose logs --tail=50
    }
}

8.4 清理脚本（clean-redcap.ps1）

#!/usr/bin/env pwsh
# clean-redcap.ps1 - 清理REDCap环境（危险操作！）

Write-Host "🗑️  REDCap Environment Cleanup" -ForegroundColor Red
Write-Host ""
Write-Host "⚠️  WARNING: This will DELETE ALL DATA!" -ForegroundColor Red
Write-Host ""

$confirm = Read-Host "Type 'YES' to confirm deletion"

if ($confirm -ne "YES") {
    Write-Host "❌ Cleanup cancelled." -ForegroundColor Yellow
    exit 0
}

Write-Host ""
Write-Host "🗑️  Removing containers..." -ForegroundColor Yellow
docker-compose down

Write-Host "🗑️  Removing volumes (DATA LOSS!)..." -ForegroundColor Red
docker-compose down --volumes

Write-Host "🗑️  Removing images..." -ForegroundColor Yellow
docker rmi redcap-docker-dev_redcap-web

Write-Host ""
Write-Host "✅ Cleanup Complete!" -ForegroundColor Green
Write-Host "   Run 'setup-redcap.ps1' to redeploy." -ForegroundColor Cyan

---

🎯 九、决策清单

在实施部署前，请确认以下决策：

9.1 必需决策

决策项	选项	推荐	您的选择
部署位置	redcap-docker-dev/	✅ 推荐	[ ]
REDCap端口	8080 / 其他	8080	[ ]
MySQL端口	3306 / 其他	3306	[ ]
phpMyAdmin	需要 / 不需要	需要	[ ]
SMTP配置	跳过 / 配置	跳过	[ ]
数据持久化	命名卷 / 绑定挂载	命名卷	[ ]

9.2 环境变量

# 确认以下密码（开发环境）
MYSQL_ROOT_PASSWORD=redcap_root_123        # 同意 [ ]
MYSQL_DATABASE=redcap                      # 同意 [ ]
MYSQL_USER=redcap_user                     # 同意 [ ]
MYSQL_PASSWORD=redcap_pass_456             # 同意 [ ]

# Salt值（重要！一旦设置不可更改）
REDCAP_SALT=iit_dev_salt_2026_redcap_v15   # 同意 [ ]

9.3 端口冲突检查

# 请先运行以下命令检查端口
netstat -ano | findstr :8080   # REDCap
netstat -ano | findstr :3306   # MySQL
netstat -ano | findstr :8081   # phpMyAdmin

# 如果有冲突，记录需要修改的端口：
# REDCap端口改为：_______
# MySQL端口改为：_______
# phpMyAdmin端口改为：_______

---

📝 十、后续步骤

10.1 Day 2开发准备

部署完成后，立即可以开始：

✅ REDCap API Adapter开发
   - exportRecords() 实现
   - importRecords() 实现
   - exportMetadata() 实现

✅ 真实API测试
   - 使用实际API Token
   - 验证JSON响应格式
   - 测试错误处理

✅ SyncManager开发
   - 混合同步模式（Webhook + Polling）
   - 数据增量拉取
   - pg-boss任务调度

10.2 External Module开发（Day 8）

当需要开发External Module时：
1. 在 redcap15.8.0/redcap/modules/ 创建模块目录
2. 编写 config.json 和 Module.php
3. 容器会自动挂载（因为使用卷映射）
4. REDCap控制中心启用模块

10.3 迁移到生产环境（未来）

本地开发验证通过后：
1. 在阿里云ECS标准安装REDCap（LAMP）
2. 配置RDS MySQL（高可用）
3. 配置OSS存储（edocs目录）
4. 配置SSL证书（Let's Encrypt）
5. 配置SMTP（阿里云DirectMail）
6. 复制External Module到生产环境
7. 导入测试项目（或从头创建）

---

🔗 十一、相关文档

11.1 项目文档

• REDCap二次开发深度指南 - REDCap架构和EM开发
• REDCap部署指南与环境要求 - 生产环境部署
• IIT Manager Agent技术方案 V1.1 - REDCap集成方案
• MVP开发任务清单 - Day 2任务

11.2 官方文档

• REDCap官网：https://projectredcap.org/
• REDCap API文档：https://redcap.vanderbilt.edu/api/help/
• External Module文档：https://github.com/vanderbilt-redcap/external-module-framework-docs

11.3 Docker文档

• Docker Compose：https://docs.docker.com/compose/
• Docker PHP镜像：https://hub.docker.com/_/php
• Docker MySQL镜像：https://hub.docker.com/_/mysql

---

📞 十二、故障排查

12.1 容器无法启动

# 检查Docker状态
docker info

# 查看容器日志
docker-compose logs

# 检查端口占用
netstat -ano | findstr :8080
netstat -ano | findstr :3306

# 重建容器
docker-compose down
docker-compose up -d --force-recreate

12.2 无法访问REDCap

# 检查容器运行状态
docker-compose ps

# 检查Apache日志
docker-compose logs redcap-web

# 进入容器诊断
docker exec -it redcap-web bash
curl localhost

12.3 数据库连接失败

# 检查MySQL日志
docker-compose logs redcap-db

# 测试MySQL连接
docker exec -it redcap-mysql mysql -uredcap_user -predcap_pass_456 -e "SHOW DATABASES;"

# 检查database.php配置
docker exec -it redcap-web cat /var/www/html/redcap/database.php

12.4 API调用失败

# 验证API Token
# REDCap → Applications → API → 查看Token

# 测试API连接
curl -X POST http://localhost:8080/api/ `
  -d "token=YOUR_TOKEN" `
  -d "content=version"

# 应该返回REDCap版本号

---

✅ 十三、部署成功标志

当您看到以下所有指标时，表示部署成功：

✅ 核心容器状态（必需）
   - redcap-mysql: Up
   - redcap-web: Up

⭐ 辅助容器状态（可选，仅开发环境）
   - redcap-phpmyadmin: Up（可选，生产环境禁用）

✅ 服务可访问
   - http://localhost:8080 → REDCap登录页（核心）
   - http://localhost:8081 → phpMyAdmin界面（可选，调试用）

✅ 功能验证
   - 管理员登录成功
   - 测试项目已创建
   - API Token已生成
   - API调用返回数据

✅ 后端集成
   - .env配置完成
   - API测试脚本通过
   - Node.js可访问REDCap

说明：
- phpMyAdmin是可选的开发调试工具
- 生产环境出于安全考虑应禁用
- 不影响REDCap核心功能

---

🏗️ 十四、生产环境部署指南

14.1 本地开发 → 生产环境迁移路径

阶段1: 本地开发环境（当前）
├─ 目的：API开发、EM调试
├─ 环境：Windows/Mac + Docker Desktop
├─ 数据库：Docker MySQL容器
├─ 辅助工具：phpMyAdmin（调试）
└─ 成本：$0

阶段2: 阿里云测试环境
├─ 目的：集成测试、性能测试
├─ 服务器：阿里云ECS（2核4GB）
├─ 数据库：阿里云RDS MySQL基础版
├─ 存储：云盘（40GB ESSD）
├─ 域名：test-redcap.yourdomain.com
└─ 成本：¥500-700/月

阶段3: 阿里云生产环境
├─ 目的：正式生产运行
├─ 服务器：阿里云ECS（4核8GB）
├─ 数据库：阿里云RDS MySQL高可用版
├─ 存储：云盘（100GB ESSD） + OSS备份
├─ 负载均衡：阿里云SLB + SSL证书
├─ 监控：CloudMonitor + 日志服务
├─ 域名：redcap.yourdomain.com
└─ 成本：¥1500-2000/月

阶段4: 医院私有化部署
├─ 目的：医院内网运行
├─ 服务器：医院提供服务器
├─ 数据库：Docker MySQL 或 医院MySQL服务器
├─ 部署方式：Docker离线镜像包
├─ 交付物：一键部署脚本 + 培训手册
└─ 成本：一次性部署费用

14.2 生产环境Docker配置调整

调整1：移除phpMyAdmin

# docker-compose.yml 生产环境版本

services:
  redcap-db:
    # ... MySQL配置保持不变

  redcap-web:
    # ... REDCap配置保持不变

  # ❌ 移除phpMyAdmin（安全考虑）
  # phpmyadmin:
  #   ...

# 生产环境数据库管理方式：
# 1. 使用阿里云RDS控制台
# 2. SSH连接ECS后使用mysql命令行
# 3. 受限的DMS数据管理服务

调整2：使用RDS MySQL

# docker-compose.yml 生产环境版本

services:
  # ❌ 移除redcap-db容器（使用RDS）
  # redcap-db:
  #   ...

  redcap-web:
    image: redcap-web:v1.0
    environment:
      # 连接阿里云RDS
      REDCAP_DB_HOST: rm-xxxxxx.mysql.rds.aliyuncs.com
      REDCAP_DB_PORT: 3306
      REDCAP_DB_NAME: redcap_prod
      REDCAP_DB_USER: redcap_user
      REDCAP_DB_PASS: ${MYSQL_PASSWORD}  # 从环境变量读取
    # ... 其他配置

调整3：配置SSL证书

# docker-compose.yml 生产环境版本

services:
  redcap-web:
    volumes:
      # 挂载SSL证书
      - ./ssl/cert.pem:/etc/ssl/certs/redcap.crt:ro
      - ./ssl/key.pem:/etc/ssl/private/redcap.key:ro
    ports:
      - "80:80"
      - "443:443"  # HTTPS端口

调整4：资源限制

# docker-compose.yml 生产环境版本

services:
  redcap-web:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G
    restart: always  # 自动重启

调整5：日志管理

# docker-compose.yml 生产环境版本

services:
  redcap-web:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

14.3 生产环境安全加固

必做项：
├─ 修改所有默认密码（MySQL、REDCap admin）
├─ 启用HTTPS（强制）
├─ 配置防火墙规则（仅开放80/443端口）
├─ 禁用phpMyAdmin（移除容器）
├─ 配置定期自动备份（数据库 + 文件）
├─ 配置监控告警（CPU、内存、磁盘、服务状态）
├─ 限制SSH访问（密钥认证 + IP白名单）
└─ 定期更新安全补丁

推荐项：
├─ 使用阿里云SLB做负载均衡和SSL卸载
├─ 配置WAF（Web应用防火墙）
├─ 启用RDS自动备份（每日备份，保留7天）
├─ 配置OSS存储备份（异地容灾）
└─ 使用CloudMonitor实时监控

14.4 生产环境成本估算

阿里云生产环境配置：

计算资源：
├─ ECS 4核8GB：¥400/月
├─ 云盘 100GB ESSD：¥50/月
└─ 小计：¥450/月

数据库：
├─ RDS MySQL高可用版 2核4GB：¥600/月
├─ 存储 100GB：包含
└─ 小计：¥600/月

网络与安全：
├─ SLB负载均衡：¥60/月
├─ SSL证书：¥100/年（Let's Encrypt免费）
├─ 公网流量：¥0.8/GB（估算¥50/月）
└─ 小计：¥110/月

存储与备份：
├─ OSS存储 100GB：¥10/月
├─ OSS流量：¥10/月
└─ 小计：¥20/月

监控与日志：
├─ CloudMonitor：免费
├─ 日志服务 10GB：¥5/月
└─ 小计：¥5/月

总计：¥1185/月（约¥14,220/年）

优化方案（包年）：
├─ ECS 4核8GB（3年）：¥3600/年（¥300/月）
├─ RDS MySQL高可用版：¥600/月
├─ 其他：¥135/月
└─ 总计：¥1035/月（约¥12,420/年）

14.5 医院私有化部署交付清单

交付物清单：

1. Docker镜像包：
   ├─ redcap-web:v1.0.tar（导出的镜像文件）
   ├─ mysql:8.0.tar（如医院无数据库）
   └─ docker-compose.yml（配置文件）

2. 部署脚本：
   ├─ install-docker.sh（Docker安装脚本）
   ├─ setup-redcap.sh（一键部署脚本）
   ├─ start-redcap.sh（启动脚本）
   ├─ stop-redcap.sh（停止脚本）
   └─ backup-redcap.sh（备份脚本）

3. 文档：
   ├─ 部署指南.pdf（医院IT版）
   ├─ 运维手册.pdf（日常操作）
   ├─ 故障排查手册.pdf（问题诊断）
   └─ 安全加固指南.pdf（合规要求）

4. 配置模板：
   ├─ database.php.template（数据库配置）
   ├─ php.ini.template（PHP配置）
   ├─ apache.conf.template（Apache配置）
   └─ .env.template（环境变量）

5. 培训材料：
   ├─ 系统架构说明.pptx
   ├─ 日常运维培训.pptx
   └─ 操作演示视频.mp4

部署流程：
Step 1: 医院IT安装Docker（30分钟）
Step 2: 导入Docker镜像（10分钟）
Step 3: 配置环境变量（10分钟）
Step 4: 启动容器（5分钟）
Step 5: 初始化REDCap（30分钟）
Step 6: 验证功能（30分钟）
总计：约2小时

14.6 生产环境监控方案

监控指标：

系统层：
├─ CPU使用率（告警阈值：>80% 持续5分钟）
├─ 内存使用率（告警阈值：>85%）
├─ 磁盘使用率（告警阈值：>80%）
└─ 网络流量（异常流量告警）

应用层：
├─ REDCap可用性（HTTP健康检查，5分钟间隔）
├─ 响应时间（告警阈值：>3秒）
├─ 错误率（告警阈值：>1%）
└─ 并发用户数

数据库层：
├─ RDS连接数（告警阈值：>80%）
├─ 慢查询数（>1秒的查询）
├─ 磁盘IOPS使用率
└─ CPU使用率

容器层：
├─ 容器运行状态（自动重启监控）
├─ 容器资源使用（内存泄漏检测）
└─ 容器日志错误率

告警方式：
├─ 短信（紧急告警）
├─ 邮件（一般告警）
├─ 钉钉/企业微信（团队通知）
└─ CloudMonitor控制台

---

🎉 结语

本地开发环境部署完成 ✅

恭喜！您已掌握REDCap Docker部署方案。

这套Docker配置具有以下特点：

• ✅ 开发/生产架构一致：消除环境漂移
• ✅ 可直接用于生产：经过少量调整即可
• ✅ 支持离线交付：医院私有化部署
• ✅ 2人团队可维护：简单、透明、可控

下一步行动

立即开始：

• Day 2：开始REDCap API Adapter开发
• 参考：MVP开发任务清单

未来规划：

• Week 2-3：阿里云ECS测试环境部署
• Month 1-2：医院试点部署
• Month 3+：标准化交付流程

需要帮助？

• 查看本文档的"故障排查"章节
• 查看Docker容器日志：docker-compose logs
• 参考REDCap官方文档：https://projectredcap.org/
• 参考ECS决议报告：REDCap生产环境部署：ECS vs SAE深度决议报告

---

文档维护：本文档随IIT Manager Agent项目持续更新
版本历史：

• v1.0 (2026-01-01): 初始版本
• v2.0 (2026-01-01): 根据ECS决议报告修订，强调开发/生产一致性
  最后更新：2026-01-01
  下次审查：生产环境首次部署后