SaaS Boilerplate 项目本地部署时数据库迁移失败的解决方案

问题背景

在使用 SaaS Boilerplate 项目进行本地开发时，开发者在执行 pnpm saas deploy 命令部署本地环境时，会遇到数据库迁移任务失败的问题。这个问题主要源于环境变量配置的冲突，导致系统无法正确连接到 LocalStack 服务。

问题根源分析

该问题的核心原因在于环境变量配置的冗余。在项目的 packages/backend/.env.shared 文件中，保留了 AWS_ENDPOINT_URL=http://localstack:4566 的配置项，而这个配置现在已经被迁移到了 docker-compose.local.yml 文件中通过环境变量传递。

这种配置冗余导致了以下问题：

1. 当后端服务尝试执行数据库迁移时，会优先读取 .env 文件中的配置
2. 由于 .env 文件中保留了旧的 LocalStack 配置，服务会尝试直接连接 localstack 主机名
3. 在本地开发环境中，这个主机名无法解析，导致连接失败

解决方案

要解决这个问题，需要执行以下步骤：

1. 从 packages/backend/.env.shared 文件中移除 AWS_ENDPOINT_URL=http://localstack:4566 这一行配置
2. 确保 docker-compose.local.yml 文件中包含了正确的 LocalStack 端点配置
3. 重新构建并部署项目

技术细节

环境变量加载顺序

理解这个问题的关键在于了解环境变量的加载顺序。在 Docker 环境中，环境变量的加载通常遵循以下优先级：

1. 容器内直接设置的环境变量（最高优先级）
2. docker-compose.yml 或 docker-compose.local.yml 中定义的环境变量
3. .env 文件中的环境变量
4. 系统环境变量（最低优先级）

配置迁移的历史背景

这个问题的出现反映了项目配置方式的演进过程。早期版本可能直接在 .env 文件中配置所有环境变量，但随着项目复杂度的增加，配置被合理地拆分到了不同的文件中：

• 基础配置保留在 .env.shared 中
• 本地开发特定配置移到了 docker-compose.local.yml 中
• 生产环境配置通过 CI/CD 流程注入

最佳实践建议

为了避免类似问题，建议遵循以下配置管理原则：

1. 单一来源原则：每个配置项应该只有一个权威来源
2. 环境隔离：不同环境（开发、测试、生产）的配置应该明确分离
3. 文档同步：当配置方式变更时，及时更新相关文档
4. 版本控制：重要的环境配置变更应该通过版本控制系统管理

验证方法

修改配置后，可以通过以下方式验证问题是否解决：

1. 执行 pnpm saas build 重新构建项目
2. 运行 pnpm saas deploy 部署本地环境
3. 观察数据库迁移任务是否正常执行
4. 检查后端服务日志，确认没有与 LocalStack 连接相关的错误

总结

这个案例展示了微服务架构中配置管理的重要性。通过合理组织环境变量和配置文件，可以避免部署时的各种连接问题。SaaS Boilerplate 项目的这一改进，使得本地开发环境的搭建更加可靠和一致。