Backstage启用HTTPS后后端启动失败：localhost证书验证错误

已按照官方文档配置Backstage启用HTTPS（自签名证书），但后端启动后搜索插件无法完成索引任务，报错显示内部请求转向localhost，与证书绑定的真实主机名不匹配，导致证书验证失败。直接使用真实主机名调用API可正常运行。

错误日志 #

Duration":"PT15M"} type=taskManager task=search_index_techdocs
2023-10-10T16:03:26.777Z search info Collating documents for software-catalog via DefaultCatalogCollatorFactory type=plugin documentType=software-catalog
2023-10-10T16:03:26.787Z search info Collating documents for techdocs via DefaultTechDocsCollatorFactory type=plugin documentType=techdocs
2023-10-10T16:03:26.796Z search warn Index for software-catalog was not created: an error was encountered type=plugin documentType=software-catalog
2023-10-10T16:03:26.796Z search error Collating documents for software-catalog failed: FetchError: request to https://localhost:7777/api/catalog/entities?offset=0&limit=500 failed, reason: unable to verify the first certificate type=plugin documentType=software-catalog
2023-10-10T16:03:26.797Z backstage error request to https://localhost:7777/api/catalog/entities?offset=0&limit=500 failed, reason: unable to verify the first certificate type=system task=search_index_software_catalog errno=UNABLE_TO_VERIFY_LEAF_SIGNATURE code=UNABLE_TO_VERIFY_LEAF_SIGNATURE stack=FetchError: request to https://localhost:7777/api/catalog/entities?offset=0&limit=500 failed, reason: unable to verify the first certificate
    at ClientRequest.<anonymous> (/data/test_backstage/backstage1/backstage/node_modules/node-fetch/lib/index.js:1501:11)
    at ClientRequest.emit (node:events:514:28)
    at TLSSocket.socketErrorListener (node:_http_client:501:9)
    at TLSSocket.emit (node:events:514:28)
    at emitErrorNT (node:internal/streams/destroy:151:8)
    at emitErrorCloseNT (node:internal/streams/destroy:116:3)
    at process.processTicksAndRejections (node:internal/process/task_queues:82:21)
2023-10-10T16:03:26.799Z search warn Index for techdocs was not created: an error was encountered type=plugin documentType=techdocs

排查与解决步骤 #

1. 修正后端baseUrl配置 #

Backstage内部服务间调用依赖baseUrl定位目标地址，需确保app-config.yaml（或对应环境变量）使用证书绑定的真实主机名：

backend:
  baseUrl: https://your-real-hostname:7777
  listen:
    port: 7777
    ssl:
      certificate: ./path/to/your-cert.pem
      key: ./path/to/your-key.pem

• 确认baseUrl未设置为localhost
• 若用环境变量，检查BACKEND_BASE_URL是否配置正确

2. 检查搜索插件请求配置 #

搜索插件索引时调用Catalog API，需排查：

• app-config.yaml中search模块是否存在硬编码localhost的配置
• 自定义插件或扩展代码中，是否有强制指定localhost的请求逻辑

3. 确认服务绑定与路由配置 #

• 后端listen.address默认是0.0.0.0（允许所有地址访问），但baseUrl必须设置为外部可访问的真实主机名
• 若部署在反向代理或容器后，确保X-Forwarded-Host等头信息配置正确，Backstage能识别真实访问地址

4. 调试阶段临时信任自签名证书（生产环境禁用） #

若配置无误仍报错，可临时关闭Node.js证书验证排查：

NODE_TLS_REJECT_UNAUTHORIZED=0 yarn start-backend

若问题消失，需将自签名证书添加到系统信任列表：

• Linux/macOS：

  sudo cp your-cert.pem /usr/local/share/ca-certificates/
  sudo update-ca-certificates
  

• Windows：

  certutil -addstore -f "ROOT" your-cert.pem
  

内容的提问来源于stack exchange，提问作者anish anil