HaHafeng
38d9bf99d6
核心成果: - REDCap 15.8.0成功部署在Docker环境 - 登录功能正常，管理员账户: Admin/Admin123! - MySQL 8.0 + PHP 8.1 + Apache 2.4环境验证通过 问题解决: 1. 修复ERR_CONTENT_DECODING_FAILED错误 - 强制禁用Apache deflate模块 - PHP配置关闭zlib.output_compression - 自动注释REDCap源码中的压缩设置 2. 修复Base URL配置错误 - 更新redcap_config表中的redcap_base_url - 统一DocumentRoot与访问路径 3. 修复登录失败问题(CRLF污染) - 删除database.php末尾的PHP结束标签 - 创建.gitattributes规范换行符 - 验证REDCap官方源码无此问题 技术改进: - 添加密码重置工具脚本 - 完善docker-entrypoint.sh启动脚本 - 创建详细的部署问题解决记录 - 建立PHP配置文件最佳实践 部署文档: - REDCap本地Docker开发环境部署方案 - REDCap生产环境部署决策报告(ECS vs SAE) - 部署问题解决记录(含根因分析) 下一步: - Day 2: 开发REDCap API Adapter - 实现与IIT Manager Agent的数据对接
5.6 KiB
5.6 KiB
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资源加载失败
根本原因：
- Apache的
mod_deflate模块与PHP的zlib.output_compression冲突 - REDCap源码中动态启用了压缩（
System.php、general_settings.php中的ini_set） - 导致数据被多次压缩，浏览器无法解码
解决方案：
- ✅ 在
docker-entrypoint.sh中强制禁用Apache的deflate模块：a2dismod -f deflate - ✅ 在
php.ini中显式关闭压缩：zlib.output_compression = Off output_buffering = Off - ✅ 在
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
解决方案：
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响应
- 导致响应体污染，浏览器无法解析
详细分析：
# database.php末尾的十六进制内容
00000050: e585 a80d 0a20 2a2f 0d0a 0d0a 3f3e 0d0a ..... */....?>..
00000060: 0d0a 0d0a ....
# `*/` CRLF CRLF `?>` CRLF CRLF CRLF
解决方案：
- ✅ 删除
database.php末尾的?>和所有空行 - ✅ 创建
.gitattributes强制PHP文件使用LF换行符 - ✅ 在
docker-entrypoint.sh中添加检查逻辑（警告提示）
PHP最佳实践：
- 📌 配置文件和库文件末尾不应该写
?> - 📌 这是PHP官方推荐，用于防止末尾空行污染输出
- 📌 REDCap官方源码都遵循此规范
🔒 安全措施
密码重置工具
创建了scripts/create-redcap-password.php，用于重置REDCap用户密码：
# 使用方法
docker cp scripts/create-redcap-password.php redcap-apache:/tmp/
docker exec redcap-apache php /tmp/create-redcap-password.php
注意： 此脚本仅用于开发环境！生产环境应禁用。
✅ 最终确认
REDCap系统是安全的
重要结论：
- ✅ REDCap官方源码（15.8.0版本，数千个PHP文件）都是规范的
- ✅ 官方文件末尾都没有
?>，不存在CRLF污染问题 - ✅ 问题仅存在于我们创建的配置文件
database.php - ✅ 一旦修复，不会有其他类似问题
验证证据：
# 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
// 配置代码...
// ✅ 正确：没有结束标签
3. REDCap部署检查清单
- Apache DocumentRoot与Base URL一致
- 禁用压缩模块（开发环境）
database.php末尾无?>- 文件换行符统一为LF
- 密码哈希正确生成
- Session目录权限正确
🚀 后续部署到生产环境
本地Docker开发环境已验证通过，可以安全迁移到阿里云ECS：
- ✅ 使用相同的
Dockerfile.redcap构建镜像 - ✅ 修改
database.php连接到RDS - ✅ 生产环境可以启用Gzip压缩（使用Nginx反向代理）
- ✅ 所有配置文件已经过验证，不会有CRLF问题
未来不需要逐个排查REDCap文件，因为官方代码是规范的！ ✨
📞 联系方式
如有问题，请查看：
- REDCap官方文档：https://projectredcap.org/
- 部署方案文档：
docs/03-REDCap本地Docker开发环境部署方案.md