Label Studio部署实战：Nginx反向代理配置与502排错全指南

正经做标注平台，没人愿意每天都敲 http://192.168.1.10:8080 这种地址去访问。Label Studio 装好只是第一步，能让团队稳定、安全、顺滑地访问才是真正考验运维功底的地方。我自己在服务器上折腾过几轮，踩了不少坑，把 Nginx 反向代理这套配置彻底梳理通了，这篇就把完整过程拆开讲清楚，包括为什么要做反代、配置里每个关键参数是干什么的、502 错误怎么一步步排查、子路径发布有哪些坑、以及最后怎么把 HTTPS 加上。

适合看这篇的人很明确：一是自己搭了 Label Studio，想发布给同事用；二是已经在用，但经常遇到 502、刷新 404、上传大文件 413 这类问题的；三是准备把标注平台正式上生产，想做正规域名 + HTTPS 访问的。下面这些内容都是我实际跑过的配置，直接照着做基本能成。

1. 为什么放着现成的8080端口不用，非要加一层Nginx

1.1 直接暴露IP加端口访问，问题比想象中多

很多人在服务器上跑起 Label Studio 后，第一反应就是把端口开出来给同事访问。这种方式在只有你自己一个人用的时候没问题，但凡超过两三个人，问题就开始冒头。

第一个问题是不好记。http://172.16.3.21:8080 这个地址你得反复提醒别人，而且很多公司内网的 IP 是 DHCP 分配的，重启一次服务器 IP 变了，所有人手上的地址全部失效。第二个问题是浏览器对非标准端口的体验很差，Chrome 和 Edge 会在地址栏明确提示这个连接不是私密连接，部分浏览器插件甚至默认拦截非 443 端口的访问，说明成本很高。第三个问题才是真正要命的——端口直接暴露意味着没有任何一层访问控制，任何人拿到这个 IP 都能访问你的标注系统，而标注数据往往是涉及隐私的核心资产。

这些问题不是 Label Studio 特有的，任何 web 服务直接裸奔都这样。解决办法就是在外面套一层 Nginx，把 80/443 作为统一入口，后面具体是哪个服务、哪个端口，都由 Nginx 来分发和屏蔽。

1.2 Nginx反向代理在这套架构里到底干了什么

网上解释反向代理的文章很多，讲得玄乎的也不少。其实用大白话说，Nginx 在中间扮演的是一个“前台接待”的角色。访客不需要知道 Label Studio 实际运行在哪个端口，只需要访问你给的前台地址（比如 http://label.example.com），前台根据规则找到对应的后端同事（8080 端口上跑着的 Label Studio 进程），把请求转过去，再把响应带回来。

这里要注意区分“正向代理”和“反向代理”。正向代理是替客户端去访问它自己访问不到的资源，服务的对象是“你”；反向代理是替后端服务器接收请求、转发消息，服务的对象是“后端服务”。我们这里用的是反向代理，客户端只认 Nginx 这一个入口，背后有几台服务器、跑在什么端口，对用户完全透明。

Nginx 在这个架构里还能顺手做很多事：终止 HTTPS 加密连接、统一的访问日志和错误日志、请求体大小限制、超时控制、WebSocket 升级支持、甚至可以在 Nginx 这一层做 IP 白名单和 Basic Auth 认证。这些都是 Label Studio 本身不擅长的事。

1.3 Label Studio 的自身特点决定了 Nginx 要特殊关照哪些点

Label Studio 不是那种简单的静态页面，它由前端 SPA 应用 + Python 后端 API 组成，默认监听 8080 端口。它有三个特点直接决定了 Nginx 的配置重点：

第一，前后端分离架构，前端需要加载大量 JS/CSS 静态资源，Nginx 代理时不能把静态资源的路径搞错，否则页面样式全丢。第二，它用 WebSocket 做实时通信，比如多人在线协作标注、任务状态推送、导入进度更新都依赖长连接，Nginx 默认的 HTTP 代理协议不会自动升级 WebSocket，需要显式配置。第三，标注工具必然涉及大量数据上传，一张标注图片几十 MB，一个 JSON 数据集动辄上百 MB，Nginx 默认的 1MB 请求体限制必须调大。

理解了这几个特点，后面的配置就有的放矢了——不是机械地抄配置，而是知道每一行在解决什么问题。

2. 环境准备：把Nginx和Label Studio先跑起来

2.1 安装Nginx，不同发行版两条命令的事

先安装 Nginx。Ubuntu/Debian 系用 apt：

bash复制sudo apt update
sudo apt install nginx -y
sudo systemctl enable --now nginx

CentOS/RHEL 系用 dnf（新版本）或者 yum（老版本）：

bash复制sudo dnf install nginx -y
sudo systemctl enable --now nginx

安装完成后用 systemctl status nginx 确认状态是 active (running)，然后本机 curl 一下：

bash复制curl http://127.0.0.1/

如果返回的是 Nginx 默认欢迎页的 HTML，说明基础服务已经跑起来了。这一步卡住的情况通常是 80 端口被其他进程占用，用 ss -lntp | grep :80 看一下端口状态就知道是谁占了。

2.2 把Label Studio跑起来，注意监听地址的选择

Label Studio 的启动方式有两种主流做法。一种是用 pip 直接安装后启动：

bash复制pip install label-studio
label-studio start label-studio --host 127.0.0.1 --port 8080

另一种是用 Docker：

bash复制docker run -it -p 8080:8080 -v $(pwd)/label-studio-data:/label-studio/data heartexlabs/label-studio:latest

这里有一个关键点建议从一开始就养成习惯：在准备用 Nginx 反代的情况下，Label Studio 启动时监听 127.0.0.1 就够了。因为 Nginx 和 Label Studio 在同一台机器上，Nginx