AIclinicalresearch/docs/03-业务模块/Redcap/01-部署与配置/10-REDCap_Docker部署操作手册.md

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：

# 下载并安装Docker Desktop
# https://www.docker.com/products/docker-desktop/

# 验证安装
docker --version
docker-compose --version

Linux（CentOS/Ubuntu）：

# 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 创建项目目录

# 创建目录结构
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配置文件

从我们的项目中复制以下文件：

# 核心文件（可直接复用，无需修改）
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）：

# 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）：

$hostname   = 'redcap-mysql';     // Docker Compose服务名
$db         = 'redcap';
$username   = 'redcap_user';
$password   = 'your_password';    // 与.env保持一致
$salt       = 'dev_salt_2026';    // 开发环境固定salt

生产环境（阿里云RDS）：

$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中的卷挂载路径正确：

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 构建并启动容器

# 进入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文件

# 如果有现成的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模块：

   a2dismod -f deflate
   

2. php.ini中已关闭压缩：

   zlib.output_compression = Off
   output_buffering = Off
   

3. redcap.conf中注释掉了mod_deflate配置

如果还有问题：

# 进入容器检查
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
// 数据库配置...

$hostname = 'redcap-mysql';
$db = 'redcap';
// ...

// ❌ 错误写法：
?>


// ✅ 正确写法：文件末尾只有注释的结束符，没有?>

验证方法：

# 检查文件末尾（十六进制）
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不匹配。

解决方案：

-- 连接到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 端口被占用

# 检查端口占用
netstat -ano | findstr ":8080"    # Windows
lsof -i :8080                     # Linux/Mac

# 解决方案1：修改docker-compose.yml端口映射
ports:
  - "8090:80"    # 改为8090或其他端口

# 解决方案2：停止占用端口的程序

4.2 卷挂载路径错误

# 检查REDCap源码路径是否存在
ls -la ../redcap15.8.0

# 如果路径错误，修改docker-compose.yml
volumes:
  - /absolute/path/to/redcap15.8.0:/var/www/html/redcap:ro

4.3 权限问题（Linux）

# 给予Docker目录适当权限
sudo chown -R $(whoami):$(whoami) redcap-docker-dev/
chmod +x docker-entrypoint.sh

---

问题5：MySQL连接失败

现象：

• REDCap显示"Database connection failed"
• 日志中有MySQL连接错误

排查步骤：

# 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：

   services:
     redcap-web:
       environment:
         REDCAP_BASE_URL: https://redcap.yourdomain.com
   
   # 移除redcap-mysql和redcap-phpmyadmin服务
   

2. 修改database.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：

   ServerName redcap.yourdomain.com
   

4. 构建并推送镜像到ACR：

   # 登录阿里云容器镜像服务
   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上部署：

   # 拉取镜像
   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镜像：

   # 在有网络的环境导出镜像
   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已解析
• 邮件服务已配置（可选）

---

🛠️ 日常维护命令

容器管理

# 启动服务
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

备份与恢复

# 备份数据库
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

重置管理员密码

# 使用我们提供的脚本
docker cp scripts/create-redcap-password.php redcap-apache:/tmp/
docker exec redcap-apache php /tmp/create-redcap-password.php

# 新密码将显示在输出中

---

📚 相关文档

• 问题排查详解：13-部署问题排查手册.md
• API开发：../03-API对接与开发/30-REDCap_API使用指南.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 或提Issue！