AIclinicalresearch/redcap-docker-dev/README.md

# REDCap Docker部署环境

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

---

## 📋 目录

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

---

## 🚀 快速开始

### 一键部署（推荐）

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

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

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

### 手动部署

```powershell
# 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：准备环境变量

```powershell
# 复制模板
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镜像

```powershell
docker-compose build
```

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

### 步骤3：启动容器

```powershell
docker-compose up -d
```

**启动的服务**：
- `redcap-mysql`：MySQL 8.0数据库
- `redcap-apache`：REDCap Web服务
- `redcap-phpmyadmin`：数据库管理工具（可选）

### 步骤4：等待服务就绪

```powershell
# 等待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"（开发环境不需要邮件）

---

## 🔧 常用命令

### 启动/停止

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

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

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

### 查看日志

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

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

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

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

### 容器管理

```powershell
# 查看容器状态
docker-compose ps

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

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

# 查看资源使用
docker stats
```

### 数据库管理

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

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

### 清理环境

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

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

---

## 🔍 故障排查

### 问题1：容器无法启动

```powershell
# 检查Docker状态
docker info

# 查看容器日志
docker-compose logs

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

### 问题2：无法访问REDCap

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

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

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

### 问题3：数据库连接失败

```powershell
# 检查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：端口冲突

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

---

## 🏗️ 生产环境部署

### 使用生产配置

```powershell
# 使用生产环境配置文件
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开发环境部署方案](../../docs/03-业务模块/Redcap/03-REDCap本地Docker开发环境部署方案.md)
- [REDCap生产环境部署：ECS vs SAE深度决议报告](../../docs/03-业务模块/Redcap/REDCap%20生产环境部署：ECS%20vs%20SAE%20深度决议报告.md)
- [REDCap二次开发深度指南](../../docs/03-业务模块/Redcap/REDCap%20二次开发深度指南.md)
- [IIT Manager Agent MVP开发任务清单](../../docs/03-业务模块/IIT%20Manager%20Agent/04-开发计划/MVP开发任务清单.md)

---

## 📞 技术支持

**需要帮助？**

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开发任务清单](../../docs/03-业务模块/IIT%20Manager%20Agent/04-开发计划/MVP开发任务清单.md)

---

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