# REDCap Docker部署操作手册

**版本�?* v1.0  
**最后更新：** 2026-01-02  
**适用环境�?* Windows/Linux/Mac + Docker  
**REDCap版本�?* 15.8.0  
**验证状态：** �?已在本地Windows环境验证通过

---

## 📋 文档目标

本手册提供REDCap基于Docker�?*标准化部署流�?*，适用于：
- �?本地开发环�?
- �?阿里云ECS生产环境
- �?医院私有化服务器

**核心优势�?*
- 🔄 **可复�?*：Docker配置文件可在不同环境直接使用
- 📦 **一致�?*：开发环�?生产环境，避免环境差�?
- 🚀 **快速部�?*�?0分钟内完成部�?
- 🛡�?**问题规避**：基于实际踩坑经验，预防常见问题

---

## 🎯 部署架构

### 标准架构�?个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 安装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. �?**生产环境使用强密�?*�?2+字符�?

---

### 阶段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镜像（首次部署需要，�?-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`数据�?
- �?�?00+张表（如`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**�?00%可复用，无需任何修改
- 🔄 **docker-entrypoint.sh**�?00%可复�?
- 🔄 **php.ini**�?00%可复�?
- ⚠️ **docker-compose.yml**：需根据环境调整端口和卷路径
- ⚠️ **database.php**：必须根据环境定制数据库连接信息

**下一步：**
- 完成本地环境验证
- 开发REDCap API Adapter
- 准备生产环境部署

---

**有问题？** 查看 [13-部署问题排查手册.md](./13-部署问题排查手册.md) 或提Issue�?