feat(redcap): REDCap 15.8.0 Docker本地开发环境部署完成
核心成果: - 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的数据对接
This commit is contained in:
203
redcap-docker-dev/docs/部署问题解决记录.md
Normal file
203
redcap-docker-dev/docs/部署问题解决记录.md
Normal file
@@ -0,0 +1,203 @@
|
||||
# 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