使用Backstage官方Helm Chart部署后加载实体类型失败求助

问题描述 #

• 通过官方Backstage Helm Chart部署，仅修改资源配额并启用内置PostgreSQL数据库，关联的backstage-secret可被Pod正常读取
• Guest身份登录时触发提示：Failed to sign in as a guest using the auth backend. Do you want to fallback to the legacy guest token?，接受回退后页面显示Failed to load entity kinds & Could not fetch catalog entities
• Pod日志存在两个警告：
  1. 搜索插件警告：

     {"level":"warn","message":"Postgres search engine is not supported, skipping registration of search-backend-module-pg","plugin":"search","service":"backstage"}
     

  2. Kubernetes插件警告：

     {"level":"warn","message":"Failed to initialize kubernetes backend: valid kubernetes config is missing","plugin":"kubernetes","service":"backstage"}
     

核心原因分析 #

• PostgreSQL搜索引擎警告：默认启用的search-backend-module-pg需要Backstage版本兼容PostgreSQL作为搜索存储，若当前Chart绑定的版本未支持或未完成关联配置，会触发该警告，但此警告不影响Catalog核心功能
• Kubernetes插件警告：默认启用的Kubernetes插件未配置集群访问权限，导致初始化失败，但同样不直接引发Catalog加载问题
• Catalog加载失败的关键：启用内置PostgreSQL后，Backstage后端未正确配置Catalog数据库连接，无法读取元数据；或Guest权限未配置，无法访问Catalog API

解决方案 #

1. 配置PostgreSQL与Catalog的连接参数 #

在Helm values中补充数据库连接配置，确保Backstage后端能正确访问内置PostgreSQL：

appConfig:
  backend:
    database:
      client: pg
      connection:
        host: postgresql
        port: 5432
        user: backstage-admin
        passwordFromSecret: backstage-secret/postgres-password
        database: backstage

注意：passwordFromSecret格式为[secret名称]/[存储密码的key]，需确认你的backstage-secret中密码对应的key（通常为postgres-password）

2. 禁用未使用插件（可选） #

若不需要Kubernetes和PostgreSQL搜索功能，可在values中禁用相关插件以消除警告：

plugins:
  kubernetes:
    enabled: false
  search-backend-module-pg:
    enabled: false

3. 配置Guest权限访问Catalog #

添加权限配置，允许Guest用户访问Catalog资源（测试环境适用，生产环境需按需调整）：

appConfig:
  permission:
    enabled: true
    policy:
      type: allow-all

4. 验证基础状态 #

• 检查Backstage Pod的数据库连接日志：

  kubectl logs <backstage-pod名称> backend | grep database
  

• 确认PostgreSQL Pod运行状态：

  kubectl get pods -l app=postgresql
  

• 进入PostgreSQL Pod验证数据库是否存在：

  kubectl exec -it <postgresql-pod名称> -- psql -U backstage-admin -d backstage
  

验证步骤 #

1. 应用修改后的配置：

   helm upgrade backstage backstage/backstage -f 你的values文件.yaml
   

2. 等待Pod重启完成后，以Guest身份登录，检查Catalog页面加载状态
3. 查看Pod日志，确认核心功能相关的错误已消除

内容的提问来源于stack exchange，提问作者BFG 9k