# 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官方源码�?5.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`