Backstage Heroku部署时数据库连接被拒报错如何解决

报错核心信息 #

Backend failed to start up, Error: Failed to connect to the database to make sure that 'backstage_plugin_catalog' exists, Error: connect ECONNREFUSED 127.0.0.1:5432

根因 #

Backstage后端默认数据库配置指向本地PostgreSQL服务的5432端口，但Heroku部署环境不会在应用实例本地运行PostgreSQL，配置未适配生产环境时就会触发连接拒绝。

排查修复步骤 #

• 检查Heroku Postgres插件绑定状态
  进入Heroku对应应用的Resources页面，确认已成功开通Heroku Postgres服务。服务绑定成功后Heroku会自动向应用运行时注入DATABASE_URL环境变量，Backstage生产模式默认优先读取该变量建立数据库连接。
• 修正生产环境数据库配置
  检查项目下app-config.production.yaml配置文件，确认数据库配置段没有硬编码本地127.0.0.1地址、5432端口，同时补充Heroku Postgres要求的SSL配置，参考配置如下：

  database:
    client: pg
    connection:
      connectionString: ${DATABASE_URL}
      ssl:
        rejectUnauthorized: false
  

  同时检查packages/backend/src/plugins/目录下各插件（catalog、auth、scaffolder等）的数据库初始化代码，确认没有覆盖默认的环境变量读取逻辑、硬编码本地连接参数。
• 调整数据库迁移执行阶段
  不要把数据库迁移命令（yarn backstage-cli backend:migrate）写在package.json的postinstall脚本里——Heroku的构建阶段无法读取运行时注入的DATABASE_URL变量，执行迁移时会默认连接本地5432触发报错。需要在项目根目录创建/修改Procfile，把迁移命令放到release阶段执行：

  release: yarn backstage-cli backend:migrate
  web: yarn start:backend
  

• 验证环境变量生效
  本地安装Heroku CLI后，执行命令heroku run env -a <你的Heroku应用名>，确认输出内容中存在DATABASE_URL变量，且变量值为Heroku分配的Postgres连接地址（非127.0.0.1开头）。

内容的提问来源于stack exchange，提问作者Remya R Praveen