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：**
```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
<?php
// 数据库配置...

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

// ❌ 错误写法：
?>


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

**验证方法：**
```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！