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