docs(iit): REDCap对接技术方案完成与模块状态更新
- 新增《REDCap对接技术方案与实施指南》(1070行) - 确定DET+REST API技术方案(不使用External Module) - 完整RedcapAdapter/WebhookController/SyncManager代码设计 - Day 2详细实施步骤与验收标准 - 更新《IIT Manager Agent模块当前状态与开发指南》 - 记录REDCap本地环境部署完成(15.8.0) - 记录对接方案确定过程与技术决策 - 更新Day 2工作计划(6个阶段详细清单) - 整体进度18%(Day 1完成+REDCap环境就绪) - REDCap环境准备完成 - 测试项目test0102(PID 16)创建成功 - DET功能源码验证通过 - 本地Docker环境稳定运行 技术方案: - 实时触发: Data Entry Trigger (0秒延迟) - 数据拉取: REST API exportRecords (增量同步) - 轮询补充: pg-boss定时任务 (每30分钟) - 可靠性: Webhook幂等性 + 轮询补充机制
This commit is contained in:
@@ -1,203 +0,0 @@
|
||||
# REDCap Docker 本地部署问题解决记录
|
||||
|
||||
**日期：** 2026-01-02
|
||||
**版本：** REDCap 15.8.0
|
||||
**环境：** Windows 10 + Docker Desktop + Docker Compose
|
||||
|
||||
---
|
||||
|
||||
## 📋 部署成功确认
|
||||
|
||||
✅ **REDCap 15.8.0 已成功部署在本地Docker环境**
|
||||
|
||||
- **访问地址：** http://localhost:8080/
|
||||
- **管理员账户：** Admin / Admin123!
|
||||
- **数据库：** MySQL 8.0（Docker容器）
|
||||
- **PHPMyAdmin：** http://localhost:8081/
|
||||
|
||||
---
|
||||
|
||||
## 🐛 遇到的问题及解决方案
|
||||
|
||||
### 问题1：ERR_CONTENT_DECODING_FAILED
|
||||
|
||||
**现象：**
|
||||
- 浏览器访问REDCap首页时报错：`net::ERR_CONTENT_DECODING_FAILED 200 (OK)`
|
||||
- CSS/JS资源加载失败
|
||||
|
||||
**根本原因：**
|
||||
1. Apache的`mod_deflate`模块与PHP的`zlib.output_compression`冲突
|
||||
2. REDCap源码中动态启用了压缩（`System.php`、`general_settings.php`中的`ini_set`）
|
||||
3. 导致数据被多次压缩，浏览器无法解码
|
||||
|
||||
**解决方案：**
|
||||
1. ✅ 在`docker-entrypoint.sh`中强制禁用Apache的deflate模块：`a2dismod -f deflate`
|
||||
2. ✅ 在`php.ini`中显式关闭压缩：
|
||||
```ini
|
||||
zlib.output_compression = Off
|
||||
output_buffering = Off
|
||||
```
|
||||
3. ✅ 在`docker-entrypoint.sh`中自动注释REDCap源码中的`ini_set('zlib.output_compression', ...)`
|
||||
|
||||
**预防措施：**
|
||||
- 已在`redcap.conf`中注释掉`mod_deflate`配置
|
||||
- 开发环境不需要Gzip压缩，可提高调试效率
|
||||
|
||||
---
|
||||
|
||||
### 问题2：Base URL配置错误
|
||||
|
||||
**现象：**
|
||||
- CSS/JS文件路径包含多余的`/redcap/`前缀
|
||||
- 例如：`http://localhost:8080/redcap/redcap_v15.8.0/Resources/...`
|
||||
- 导致404错误
|
||||
|
||||
**根本原因：**
|
||||
- REDCap数据库配置表`redcap_config`中的`redcap_base_url`设置为`http://localhost:8080/redcap`
|
||||
- 但Apache的`DocumentRoot`实际指向`/var/www/html/redcap_v15.8.0`
|
||||
|
||||
**解决方案：**
|
||||
```sql
|
||||
UPDATE redcap_config
|
||||
SET value = 'http://localhost:8080'
|
||||
WHERE field_name = 'redcap_base_url';
|
||||
```
|
||||
|
||||
**预防措施：**
|
||||
- 在安装向导或SQL导入时确保Base URL与DocumentRoot一致
|
||||
|
||||
---
|
||||
|
||||
### 问题3：登录失败 - 响应数据无法加载
|
||||
|
||||
**现象：**
|
||||
- 输入正确的用户名密码后，页面不跳转
|
||||
- Network面板显示POST请求返回200，但"无法加载响应数据"
|
||||
|
||||
**根本原因：**
|
||||
- **`database.php`文件末尾有`?>`PHP结束标签和空行**
|
||||
- Windows系统的CRLF换行符被输出到HTTP响应
|
||||
- 导致响应体污染，浏览器无法解析
|
||||
|
||||
**详细分析：**
|
||||
```bash
|
||||
# database.php末尾的十六进制内容
|
||||
00000050: e585 a80d 0a20 2a2f 0d0a 0d0a 3f3e 0d0a ..... */....?>..
|
||||
00000060: 0d0a 0d0a ....
|
||||
# `*/` CRLF CRLF `?>` CRLF CRLF CRLF
|
||||
```
|
||||
|
||||
**解决方案：**
|
||||
1. ✅ **删除`database.php`末尾的`?>`和所有空行**
|
||||
2. ✅ **创建`.gitattributes`强制PHP文件使用LF换行符**
|
||||
3. ✅ **在`docker-entrypoint.sh`中添加检查逻辑（警告提示）**
|
||||
|
||||
**PHP最佳实践：**
|
||||
- 📌 **配置文件和库文件末尾不应该写`?>`**
|
||||
- 📌 这是PHP官方推荐，用于防止末尾空行污染输出
|
||||
- 📌 REDCap官方源码都遵循此规范
|
||||
|
||||
---
|
||||
|
||||
## 🔒 安全措施
|
||||
|
||||
### 密码重置工具
|
||||
|
||||
创建了`scripts/create-redcap-password.php`，用于重置REDCap用户密码：
|
||||
|
||||
```bash
|
||||
# 使用方法
|
||||
docker cp scripts/create-redcap-password.php redcap-apache:/tmp/
|
||||
docker exec redcap-apache php /tmp/create-redcap-password.php
|
||||
```
|
||||
|
||||
**注意：** 此脚本仅用于开发环境！生产环境应禁用。
|
||||
|
||||
---
|
||||
|
||||
## ✅ 最终确认
|
||||
|
||||
### REDCap系统是安全的
|
||||
|
||||
**重要结论：**
|
||||
1. ✅ **REDCap官方源码（15.8.0版本，数千个PHP文件）都是规范的**
|
||||
2. ✅ **官方文件末尾都没有`?>`，不存在CRLF污染问题**
|
||||
3. ✅ **问题仅存在于我们创建的配置文件`database.php`**
|
||||
4. ✅ **一旦修复，不会有其他类似问题**
|
||||
|
||||
**验证证据：**
|
||||
```bash
|
||||
# REDCap官方index.php末尾（规范）
|
||||
tail -c 20 /var/www/html/redcap/redcap_v15.8.0/index.php | xxd
|
||||
00000000: 656e 6572 616c 2f66 6f6f 7465 722e 7068 eneral/footer.ph
|
||||
00000010: 7027 3b0a p';.
|
||||
# 末尾只有 '; 和换行符，没有?>
|
||||
|
||||
# REDCap官方Authentication.php末尾（规范）
|
||||
tail -c 30 /var/www/html/redcap/redcap_v15.8.0/Classes/Authentication.php | xxd
|
||||
00000000: 6c2c 205b 2475 7365 7269 645d 2929 203e l, [$userid])) >
|
||||
00000010: 2030 3b0a 0909 7d0a 097d 0a0a 7d0a 0;...}..}..}.
|
||||
# 末尾只有 } 和换行符，没有?>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 经验总结
|
||||
|
||||
### 1. Docker跨平台注意事项
|
||||
|
||||
**Windows + Docker + Linux容器组合会暴露文件格式问题：**
|
||||
- Windows默认CRLF (`\r\n`)
|
||||
- Linux默认LF (`\n`)
|
||||
- Git的`autocrlf`设置可能自动转换
|
||||
- 使用`.gitattributes`显式控制换行符
|
||||
|
||||
### 2. PHP配置文件最佳实践
|
||||
|
||||
```php
|
||||
<?php
|
||||
// 配置代码...
|
||||
|
||||
// ❌ 错误：有结束标签和空行
|
||||
?>
|
||||
|
||||
|
||||
```
|
||||
|
||||
```php
|
||||
<?php
|
||||
// 配置代码...
|
||||
|
||||
// ✅ 正确：没有结束标签
|
||||
```
|
||||
|
||||
### 3. REDCap部署检查清单
|
||||
|
||||
- [ ] Apache DocumentRoot与Base URL一致
|
||||
- [ ] 禁用压缩模块（开发环境）
|
||||
- [ ] `database.php`末尾无`?>`
|
||||
- [ ] 文件换行符统一为LF
|
||||
- [ ] 密码哈希正确生成
|
||||
- [ ] Session目录权限正确
|
||||
|
||||
---
|
||||
|
||||
## 🚀 后续部署到生产环境
|
||||
|
||||
**本地Docker开发环境已验证通过，可以安全迁移到阿里云ECS：**
|
||||
|
||||
1. ✅ 使用相同的`Dockerfile.redcap`构建镜像
|
||||
2. ✅ 修改`database.php`连接到RDS
|
||||
3. ✅ 生产环境可以启用Gzip压缩（使用Nginx反向代理）
|
||||
4. ✅ 所有配置文件已经过验证，不会有CRLF问题
|
||||
|
||||
**未来不需要逐个排查REDCap文件，因为官方代码是规范的！** ✨
|
||||
|
||||
---
|
||||
|
||||
## 📞 联系方式
|
||||
|
||||
如有问题，请查看：
|
||||
- REDCap官方文档：https://projectredcap.org/
|
||||
- 部署方案文档：`docs/03-REDCap本地Docker开发环境部署方案.md`
|
||||
|
||||
Reference in New Issue
Block a user