在Backstage中配置新代理后出现Proxy URI 404未找到问题

问题场景 #

尝试配置Backstage代理指向本地8083端口的GraphQL服务，当前app-config.yaml配置如下：

proxy:
   endpoints:
    /graphql:
       target: 'http://localhost:8083/graphql'
       method: ['GET', 'POST']
       port: 3000

Backstage日志显示代理已创建：

[1] 2025-03-31T10:02:14.960Z proxy info [HPM] Proxy created: /graphql  -> http://localhost:8083/graphql type=plugin
[1] 2025-03-31T10:02:14.961Z proxy info [HPM] Proxy rewrite rule created: "^/api/proxy/graphql/?" ~> "/" type=plugin
[1] 2025-03-31T10:02:14.962Z search info Added DefaultCatalogCollatorFactory collator factory for type software-catalog type=plugin
[1] 2025-03-31T10:02:14.962Z search info Added DefaultTechDocsCollatorFactory collator factory for type techdocs type=plugin
[1] 2025-03-31T10:02:14.962Z search info Starting all scheduled search tasks. type=plugin

但访问http://localhost:3000/api/proxy/graphql时返回404错误，手动访问也无法正常响应。

问题原因 #

1. 多余的port配置项：Backstage代理默认运行在Backstage自身的服务端口（即3000），proxy.endpoints下不存在port配置项，该配置会干扰代理规则的正确解析。
2. 默认路径重写导致目标路径截断：从日志可以看到，默认重写规则会将^/api/proxy/graphql/?替换为/，这意味着实际转发的请求是http://localhost:8083/，而非预期的http://localhost:8083/graphql，目标服务的根路径不存在对应接口，因此返回404。

修复方案 #

方案一：关闭路径重写 #

保留target的完整路径，关闭默认的路径重写规则：

proxy:
   endpoints:
    /graphql:
       target: 'http://localhost:8083/graphql'
       method: ['GET', 'POST']
       pathRewrite: false

方案二：调整target与路径重写规则 #

将target设为服务根地址，通过pathRewrite将代理路径映射到目标服务的GraphQL端点：

proxy:
   endpoints:
    /graphql:
       target: 'http://localhost:8083'
       method: ['GET', 'POST']
       pathRewrite:
         '^/api/proxy/graphql': '/graphql'

验证 #

修改配置后重启Backstage，日志中会显示正确的重写规则，此时访问http://localhost:3000/api/proxy/graphql即可正常转发到本地8083端口的GraphQL服务。

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