Apache APISIX配置本地上游服务出现502错误求助

一、先确认本地服务基础可用性 #

直接访问本地服务的目标路径，验证服务本身是否正常：

curl http://127.0.0.1:3001/anything/test

如果能返回Hello World，说明服务本身无问题；如果无响应或报错，先排查Node服务的启动状态。

二、分步调试定位问题 #

1. 查看APISIX错误日志 #

日志会直接给出502的具体原因，比如连接拒绝、无法找到主机等：

• 源码部署：

  tail -f logs/error.log
  

• Docker部署：

  docker exec -it <apisix容器ID> tail -f /usr/local/apisix/logs/error.log
  

2. 测试APISIX到本地服务的连通性 #

如果APISIX用Docker部署，容器内的127.0.0.1指向容器自身，而非宿主机，需在容器内测试连通性：

# 替换<宿主机局域网IP>为实际IP，比如192.168.1.100
docker exec -it <apisix容器ID> curl http://<宿主机局域网IP>:3001/anything/test

如果不通，说明容器与宿主机网络存在隔离，这是最常见的触发502的原因。

3. 确认路由匹配条件 #

你的路由配置指定了host: example.com，请求时必须携带该Host头，否则APISIX无法匹配到路由：

curl http://127.0.0.1:9080/anything/test -H "Host: example.com"

三、针对性解决方法 #

场景1：APISIX以Docker部署，本地服务在宿主机 #

这是最普遍的问题，解决方式三选一：

• 修改上游地址为宿主机局域网IP
  把路由配置中的127.0.0.1:3001替换成宿主机的实际局域网IP（如192.168.1.100）：

  {
      "methods": ["GET"],
      "host": "example.com",
      "uri": "/anything/*",
      "upstream": {
          "type": "roundrobin",
          "nodes": {
              "192.168.1.100:3001": 1
          }
      }
  }
  

• 用Host网络模式启动APISIX
  启动容器时添加--network host参数，让容器直接复用宿主机网络：

  docker run -d --network host apache/apisix:latest
  

• 使用host.docker.internal（仅Docker Desktop）
  把上游地址改为host.docker.internal:3001，该域名是Docker Desktop专为宿主机访问提供的映射。

场景2：本地服务监听范围限制 #

如果Node服务仅监听127.0.0.1，则外部（包括Docker容器）无法访问，修改监听地址为0.0.0.0：

server.listen(port, '0.0.0.0', () => {
  console.log(`Server running at http://${hostname}:${port}/`)
})

修改后重启Node服务，即可允许所有网卡访问。

场景3：防火墙/安全组拦截 #

检查宿主机防火墙规则，确保3001端口允许APISIX所在网络访问：

• Linux：开放端口

  sudo ufw allow 3001/tcp
  

• Windows：在防火墙高级设置中添加允许3001端口入站的规则。

四、验证修复结果 #

修改配置后，用带Host头的请求测试：

curl http://127.0.0.1:9080/anything/test -H "Host: example.com"

返回Hello World即说明问题解决。

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