HaHafeng
dbca1615b5
核心成果: 创建REDCap模块文档体系（4个分类目录） 完成《REDCap Docker部署操作手册》- 最核心文档 梳理从0到1的完整部署流程 明确Docker文件的可复用性 文档体系: - 00-模块概览/ 系统介绍、方案设计、决策报告 - 01-部署与配置/ 部署手册、问题排查（核心） - 02-系统配置与运维/ 日常管理（规划中） - 03-API对接与开发/ API开发、二次开发 - 04-参考资料/ 旧版文档存档 核心文档: 10-REDCap_Docker部署操作手册.md（最重要） - 完整的从0到1部署流程 - Docker文件复用说明和可复用性分析 - 3种环境差异配置（本地/ECS/医院） - 5大常见问题与解决方案 - 部署检查清单 - 日常维护命令 13-部署问题排查手册.md - 基于实际踩坑经验 - ERR_CONTENT_DECODING_FAILED - CRLF污染问题 - Base URL配置错误 - MySQL连接问题 Docker文件可复用性: 100%可复用（无需修改）: - Dockerfile.redcap - docker-entrypoint.sh - config/php/php.ini - .gitattributes 需根据环境调整: - docker-compose.yml（端口、卷路径） - config/apache/redcap.conf（域名） - config/database.php（数据库连接） 文档重组: - 移动文档到对应分类目录 - 重命名为标准格式（数字前缀） - 旧版文档归档到参考资料 - 创建README快速入口 下一步: - Day 2: 开发REDCap API Adapter - 创建API使用指南 - 创建对接设计文档
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