AIclinicalresearch/docs/03-业务模块/Redcap/01-部署与配置/13-部署问题排查手册.md

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中显式关闭压缩：

   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

解决方案：

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

解决方案：

1. ✅ 删除database.php末尾的?>和所有空行
2. ✅ 创建.gitattributes强制PHP文件使用LF换行符
3. ✅ 在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系统是安全的

重要结论：

1. ✅ REDCap官方源码（15.8.0版本，数千个PHP文件）都是规范的
2. ✅ 官方文件末尾都没有?>，不存在CRLF污染问题
3. ✅ 问题仅存在于我们创建的配置文件database.php
4. ✅ 一旦修复，不会有其他类似问题

验证证据：

# 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：

1. ✅ 使用相同的Dockerfile.redcap构建镜像
2. ✅ 修改database.php连接到RDS
3. ✅ 生产环境可以启用Gzip压缩（使用Nginx反向代理）
4. ✅ 所有配置文件已经过验证，不会有CRLF问题

未来不需要逐个排查REDCap文件，因为官方代码是规范的！ ✨

---

📞 联系方式

如有问题，请查看：

• REDCap官方文档：https://projectredcap.org/
• 部署方案文档：docs/03-REDCap本地Docker开发环境部署方案.md