Docker环境下Nginx反向代理Umami至4000端口出现502错误排查

以下是几个最可能的原因及对应解决方式：

1. Docker容器间网络通信的目标地址错误 #

你在Nginx配置里如果写的是proxy_pass http://localhost:4000，这是错误的——Nginx容器内的localhost指向容器自身，而非宿主机。因为所有服务通过docker-compose部署，容器默认处于同一自定义网络，应该直接用Umami的服务名（对应docker-compose.yml里Umami服务的service字段，比如umami）加容器内部端口3000作为转发地址：

proxy_pass http://umami:3000;

同时确认docker-compose.yml里所有服务（Nginx、Umami、PostgreSQL）都在同一网络下（默认docker-compose会自动创建并加入默认网络，无需额外配置，除非你手动指定了多个网络）。

2. 子路径转发的配置遗漏 #

你要通过/umami路径访问Umami，需要同时处理两个关键点：

• Nginx的路径重写：确保转发时路径正确拼接，建议在location和proxy_pass末尾都加上斜杠：

  location /umami/ {
      proxy_pass http://umami:3000/;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
  }
  

• Umami的子路径配置：需要给Umami容器设置BASE_PATH环境变量，让它识别子路径请求。在docker-compose.yml的Umami服务里添加：

  environment:
    BASE_PATH: /umami
  

3. 混淆了宿主机端口与容器内部端口 #

宿主机的4000:3000映射是给外部访问用的，容器间通信不需要走这个映射端口。Nginx容器访问Umami时，必须用Umami容器内部监听的3000端口，而非宿主机的4000端口——这是常见的端口混淆错误。

4. 容器端口连通性验证 #

如果以上配置都没问题，可进入Nginx容器测试连通性：

# 进入Nginx容器（替换成你的Nginx容器名或ID）
docker exec -it <nginx-container-name> /bin/sh
# 测试访问Umami容器
curl http://umami:3000

如果curl返回连接拒绝，说明Umami容器的3000端口未正常监听，或者网络存在隔离，需要检查Umami容器的启动日志，确认服务是否正常启动。

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