AIclinicalresearch/redcap-docker-dev

REDCap Docker部署环境

IIT Manager Agent项目 - REDCap开发/生产一致性环境
版本：v1.0 | 日期：2026-01-01

---

📋 目录

1. 快速开始
2. 项目结构
3. 环境要求
4. 详细部署步骤
5. 常用命令
6. 故障排查
7. 生产环境部署

---

🚀 快速开始

一键部署（推荐）

# 进入项目目录
cd redcap-docker-dev

# 运行一键部署脚本
.\scripts\setup-redcap.ps1

# 访问REDCap
# http://localhost:8080/install.php

手动部署

# 1. 复制环境变量模板
copy env.template .env

# 2. 构建并启动容器
docker-compose up -d

# 3. 查看容器状态
docker-compose ps

---

📁 项目结构

redcap-docker-dev/
├── docker-compose.yml          # Docker编排（开发环境）
├── docker-compose.prod.yml     # Docker编排（生产环境）
├── Dockerfile.redcap           # REDCap镜像定义
├── docker-entrypoint.sh        # 容器启动脚本
├── env.template                # 环境变量模板
├── .gitignore                  # Git忽略规则
│
├── config/                     # 配置文件目录
│   ├── apache/
│   │   └── redcap.conf         # Apache虚拟主机配置
│   ├── php/
│   │   └── php.ini             # PHP配置
│   └── database.php            # REDCap数据库配置
│
├── scripts/                    # 运维脚本
│   ├── setup-redcap.ps1        # 一键部署
│   ├── start-redcap.ps1        # 启动服务
│   ├── stop-redcap.ps1         # 停止服务
│   ├── logs-redcap.ps1         # 查看日志
│   └── clean-redcap.ps1        # 清理环境
│
└── README.md                   # 本文档

---

💻 环境要求

软件要求

• Docker Desktop：20.10+ （Windows/Mac）
• PowerShell：5.1+ 或 PowerShell Core 7+
• 内存：至少4GB可用
• 磁盘：至少10GB可用空间

REDCap源码

确保REDCap源码位于正确位置：

AIclinicalresearch/
├── redcap15.8.0/
│   └── redcap/
└── redcap-docker-dev/  # 当前目录

---

📖 详细部署步骤

步骤1：准备环境变量

# 复制模板
copy env.template .env

# （可选）编辑.env修改密码
notepad .env

默认配置（开发环境）：

• MySQL Root密码：redcap_root_dev_2026
• MySQL数据库：redcap
• MySQL用户：redcap_user
• MySQL密码：redcap_pass_dev_456

⚠️ 生产环境必须修改所有密码！

步骤2：构建Docker镜像

docker-compose build

预计时间：5-10分钟（首次）

步骤3：启动容器

docker-compose up -d

启动的服务：

• redcap-mysql：MySQL 8.0数据库
• redcap-apache：REDCap Web服务
• redcap-phpmyadmin：数据库管理工具（可选）

步骤4：等待服务就绪

# 等待30秒让MySQL完全启动
# 然后访问：http://localhost:8080/install.php

步骤5：安装REDCap

访问：http://localhost:8080/install.php

数据库配置：

• Hostname：redcap-db
• Database：redcap
• Username：redcap_user
• Password：redcap_pass_dev_456
• Salt：iit_dev_salt_2026_redcap_v15_do_not_change

管理员账户（示例）：

• Username：admin
• Password：Admin@123456（开发环境）
• Email：dev@example.com

SMTP配置：

• 选择"Skip SMTP Configuration"（开发环境不需要邮件）

---

🔧 常用命令

启动/停止

# 启动服务
.\scripts\start-redcap.ps1

# 停止服务（保留数据）
.\scripts\stop-redcap.ps1

# 重启服务
.\scripts\stop-redcap.ps1
.\scripts\start-redcap.ps1

查看日志

# 查看所有服务日志
.\scripts\logs-redcap.ps1

# 查看特定服务
.\scripts\logs-redcap.ps1 -Service redcap-web

# 实时跟踪日志
.\scripts\logs-redcap.ps1 -Follow

# 显示更多行
.\scripts\logs-redcap.ps1 -Tail 100

容器管理

# 查看容器状态
docker-compose ps

# 进入容器
docker exec -it redcap-apache bash

# 重启特定容器
docker-compose restart redcap-web

# 查看资源使用
docker stats

数据库管理

# 通过phpMyAdmin
# 访问：http://localhost:8081
# 用户：root
# 密码：redcap_root_dev_2026

# 或通过命令行
docker exec -it redcap-mysql mysql -uroot -predcap_root_dev_2026 redcap

清理环境

# 完全清理（删除所有数据）
.\scripts\clean-redcap.ps1

⚠️ 警告：此命令会删除所有数据，无法恢复！

---

🔍 故障排查

问题1：容器无法启动

# 检查Docker状态
docker info

# 查看容器日志
docker-compose logs

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

问题2：无法访问REDCap

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

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

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

问题3：数据库连接失败

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

# 等待MySQL完全启动（30秒）
Start-Sleep -Seconds 30

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

问题4：端口冲突

# 修改docker-compose.yml中的端口映射
# 例如将8080改为8888：
ports:
  - "8888:80"  # 主机端口:容器端口

---

🏗️ 生产环境部署

使用生产配置

# 使用生产环境配置文件
docker-compose -f docker-compose.prod.yml up -d

关键差异

配置项	开发环境	生产环境
phpMyAdmin	✅ 启用	❌ 禁用（安全）
MySQL	Docker容器	阿里云RDS（推荐）
密码	简单密码	强密码（32+字符）
SSL	不需要	必需（HTTPS）
日志	详细	精简
资源限制	无	配置限制

生产环境检查清单

• 修改所有默认密码
• 配置RDS MySQL连接
• 移除phpMyAdmin容器
• 启用HTTPS（SSL证书）
• 配置防火墙规则
• 配置自动备份
• 配置监控告警
• 限制SSH访问

详细生产部署文档

参考：docs/03-业务模块/Redcap/03-REDCap本地Docker开发环境部署方案.md

---

📚 相关文档

• REDCap本地Docker开发环境部署方案
• REDCap生产环境部署：ECS vs SAE深度决议报告
• REDCap二次开发深度指南
• IIT Manager Agent MVP开发任务清单

---

📞 技术支持

需要帮助？

1. 查看详细文档（上方链接）
2. 查看容器日志：.\scripts\logs-redcap.ps1
3. 参考REDCap官方文档：https://projectredcap.org/
4. 联系IIT Manager开发团队

---

🎯 下一步

部署成功后：

1. ✅ 完成REDCap安装（install.php）
2. ✅ 创建测试项目（IIT试验项目）
3. ✅ 生成API Token
4. ✅ 开始Day 2开发（REDCap API Adapter）

参考：MVP开发任务清单

---

文档维护：IIT Manager开发团队
最后更新：2026-01-01
版本：v1.0