Plandex项目在Docker环境下的常见问题及解决方案

问题背景

在使用Plandex项目的Docker环境时，开发者可能会遇到两类典型问题：一类是由于Windows和Linux系统换行符差异导致的脚本执行错误，另一类是数据库初始化过程中的语法错误。这些问题在首次运行docker-compose up命令时尤为常见。

换行符问题分析

在Windows Subsystem for Linux (WSL)环境中，如果项目是从Windows系统克隆而非直接在WSL中克隆，shell脚本文件可能会保留Windows风格的换行符(CRLF)。这会导致在Linux环境下执行时出现类似/usr/bin/env: 'bash\r': No such file or directory的错误。

解决方案是使用dos2unix工具转换相关脚本文件的换行符：

dos2unix 01-init.sh
dos2unix wait-for-it.sh
dos2unix start_local.sh

从项目维护角度，可以通过添加.gitattributes文件来预防此类问题：

*.sh text eol=lf

数据库初始化问题

另一个常见问题是PostgreSQL数据库初始化时出现的语法错误，表现为ERROR: syntax error at or near "WITH"。这通常是由于环境变量未正确设置导致的。

正确的初始化流程应该是：

1. 运行start_local.sh脚本自动创建.env文件
2. 或者手动将_env文件重命名为.env
3. 确保.env文件中包含所有必要的环境变量

最佳实践建议

1. 开发环境一致性：建议在WSL环境中直接克隆仓库，避免跨系统操作带来的换行符问题

2. 初始化流程：严格按照项目文档的初始化步骤操作，先运行start_local.sh脚本，再执行docker-compose up

3. 环境变量检查：确保.env文件包含以下关键配置：

   • 数据库密码
   • 数据库名称
   • 用户凭证
   • 数据存储路径
   • 运行环境标识

4. 容器清理：遇到问题时，可以尝试删除容器和卷后重新初始化：

docker-compose down -v

通过理解这些常见问题的根源和解决方案，开发者可以更顺利地搭建Plandex项目的开发环境，避免在初期配置阶段浪费时间。这些问题虽然看似简单，但对于项目初次使用者来说可能会造成较大困扰，因此掌握这些排查技巧十分必要。