基于Docker部署Label Studio私有标注平台

发表于 2026-03-14

Label Studio是一款开源、多模态的数据标注工具，支持图像、文本、视频、音频等多种数据类型的标注任务，广泛应用于机器学习数据预处理场景。本文基于Docker容器化技术，详细讲解Label Studio的私有部署流程，整合Nginx反向代理、外部Redis缓存、外部PostgreSQL数据库配置，实现安全、高效、可协作的私有标注平台搭建，适配企业内网多人协作、敏感数据私有化存储的核心需求。

一、部署背景与核心需求

在实际企业应用中，数据标注往往涉及敏感信息（如隐私图片、内部文档），因此私有化部署是必然选择。本次部署需满足以下核心需求：

私有化部署：所有标注数据、配置信息存储在内网，杜绝数据外流；
多人协作：支持多角色用户（管理员、标注员、审核员）权限管理，实现数据集隔离；
安全访问：隐藏Label Studio核心服务端口，通过Nginx反向代理对外暴露访问入口；
稳定可靠：复用宿主机外部Redis（缓存）和PostgreSQL（数据库），提升服务稳定性和可维护性；
易用性：简化访问方式，用户无需记忆复杂端口，通过固定端口即可访问。

二、前置条件准备

部署前需确保服务器满足以下环境要求，避免因依赖缺失导致部署失败：

2.1 环境版本要求

环境/工具	版本要求	检查与安装命令
操作系统	Linux（Ubuntu 20.04+/CentOS 7+）	无（推荐Ubuntu，兼容性更好）
Docker	20.10+	检查：`docker -v`；安装：`curl -fsSL https://get.docker.com \| sh`
Docker Compose	V2+	检查：`docker compose version`；安装：`apt install docker-compose-plugin`（Ubuntu）
Nginx	1.18+	检查：`nginx -v`；安装：`apt install nginx`（Ubuntu）/ `yum install nginx`（CentOS）
PostgreSQL	13+/14+	部署在宿主机，检查：`systemctl status postgresql`
Redis	6+/7+	部署在宿主机，检查：`systemctl status redis`
端口	8081（Nginx对外）、9000（Label Studio本机）、5432（PG）、6379（Redis）	检查端口占用：`netstat -tulpn \| grep 端口号`

2.2 核心前置配置（关键！）

本次部署使用宿主机已有的Redis和PostgreSQL（无自定义Docker Network），需提前配置两者允许容器访问，否则会出现连接失败问题。

2.2.1 宿主机PostgreSQL配置

登录PostgreSQL，创建Label Studio专属数据库和用户（用于容器连接）： -- 创建数据库 CREATE DATABASE label_studio; -- 创建用户（替换your_pg_pass为自定义密码） CREATE USER label_studio WITH PASSWORD 'your_pg_pass'; -- 赋予用户数据库全权限 GRANT ALL PRIVILEGES ON DATABASE label_studio TO label_studio;
修改PostgreSQL配置文件，允许容器访问：
1. 编辑postgresql.conf（路径通常为/etc/postgresql/版本/main/postgresql.conf）： listen_addresses = '*' # 允许所有IP访问（内网环境安全）
2. 编辑pg_hba.conf（同上述路径），添加容器网段和宿主机授权： # 允许Docker容器网段（默认172.17.0.0/16）访问 host label_studio label_studio 172.17.0.0/16 md5 # 允许宿主机本地访问 host label_studio label_studio 127.0.0.1/32 md5
重启PostgreSQL服务：systemctl restart postgresql

2.2.2 宿主机Redis配置

编辑Redis配置文件redis.conf（路径通常为/etc/redis/redis.conf）： bind 0.0.0.0 # 允许所有IP访问（内网环境） protected-mode no # 关闭保护模式，允许容器访问 requirepass your_redis_pass # 配置密码（可选，推荐，替换为自定义密码）
重启Redis服务：systemctl restart redis

三、分步部署Label Studio（Docker+Nginx）

本次部署采用Docker Compose管理容器，整合Label Studio和Nginx两个核心服务，Label Studio仅绑定本机端口，通过Nginx反向代理对外暴露8081端口，确保服务安全。

3.1 创建部署目录（统一管理文件）

为避免配置文件混乱，创建统一的部署目录，所有数据、配置文件均存储在此目录下：

# 创建核心部署目录
mkdir -p /opt/label-studio/{data,conf,nginx}
# 进入部署目录
cd /opt/label-studio

目录说明：

data：存储Label Studio标注数据、日志等（持久化）；
conf：存储Label Studio配置文件；
nginx：存储Nginx反向代理配置文件和缓存文件。

3.2 编写Docker Compose配置文件

在/opt/label-studio目录下创建docker-compose.yml文件，核心配置如下（已整合所有需求，可直接复制使用，需替换自定义密码和宿主机IP）：

version: '3.8'

services:
  # Label Studio 核心服务（仅本机可访问，绑定9000端口）
  label-studio:
    image: heartexlabs/label-studio:latest
    container_name: label-studio
    restart: always
    environment:
      # 连接宿主机PostgreSQL配置
      - LABEL_STUDIO_DB=postgres
      - LABEL_STUDIO_DB_HOST=192.168.1.100  # 替换为宿主机内网IP
      - LABEL_STUDIO_DB_PORT=5432
      - LABEL_STUDIO_DB_USER=label_studio
      - LABEL_STUDIO_DB_PASSWORD=your_pg_pass  # 替换为之前创建的PG密码
      - LABEL_STUDIO_DB_NAME=label_studio
      # 连接宿主机Redis配置
      - REDIS_HOST=192.168.1.100  # 替换为宿主机内网IP
      - REDIS_PORT=6379
      - REDIS_PASSWORD=your_redis_pass  # 替换为Redis密码，无则删除该行
      - REDIS_DB=0
      # 基础配置
      - ALLOWED_HOSTS=*
      - LABEL_STUDIO_DATA_DIR=/label-studio/data
    volumes:
      - ./data:/label-studio/data
      - ./conf:/label-studio/conf
    # 核心：仅绑定本机127.0.0.1:9000，外部无法直接访问
    ports:
      - 127.0.0.1:9000:8080
    # Linux系统兼容host.docker.internal（可选，用于容器访问宿主机）
    extra_hosts:
      - "host.docker.internal:host-gateway"
    networks:
      - label-studio-net

  # Nginx 反向代理服务（对外暴露8081端口）
  nginx:
    image: nginx:1.23-alpine
    container_name: label-studio-nginx
    restart: always
    ports:
      - "8081:80"  # 宿主机8081端口映射到容器80端口（对外访问入口）
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ./nginx/cache:/var/cache/nginx
    depends_on:
      - label-studio  # 确保Label Studio启动后再启动Nginx
    extra_hosts:
      - "host.docker.internal:host-gateway"
    networks:
      - label-studio-net

# 容器内部网络（仅用于Label Studio和Nginx通信）
networks:
  label-studio-net:
    driver: bridge

3.3 编写Nginx反向代理配置

在/opt/label-studio/nginx目录下创建nginx.conf文件，核心作用是将外部8081端口的请求，代理到本机9000端口的Label Studio服务，同时优化访问性能和大文件上传体验：

server {
    listen 80;  # 容器内部监听80端口，与Docker映射对应
    server_name _;  # 匹配所有IP，无需配置域名

    # 支持大文件上传（标注视频/图片常用，可根据需求调整大小）
    client_max_body_size 10G;

    # 传递真实访问IP和请求信息，便于日志排查
    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;

    # 超时配置，避免大文件上传超时
    proxy_connect_timeout 300s;
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;

    # 核心反向代理逻辑：将请求转发到本机9000端口（Label Studio）
    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_redirect off;
    }

    # 静态文件缓存（CSS/JS/图片等），提升访问速度
    location /static/ {
        proxy_pass http://127.0.0.1:9000/static/;
        expires 30d;  # 缓存30天
        add_header Cache-Control "public, max-age=2592000";
    }
}

3.4 启动服务并验证

启动容器服务（后台运行）： docker compose up -d
检查服务运行状态（确保所有容器均为Up状态）： docker compose ps若出现Exited状态，可通过日志排查问题：docker compose logs -f label-studio
访问验证：
1. 本机测试：curl http://127.0.0.1:9000，应返回Label Studio登录页面HTML内容；
2. 外部/内网测试：浏览器打开http://宿主机IP:8081（如http://192.168.1.100:8081），进入Label Studio登录页面，说明部署成功；
3. 安全验证：外部机器访问http://宿主机IP:9000，应无法访问（符合预期，确保Label Studio不对外暴露）。
首次登录配置：首次访问http://宿主机IP:8081，会引导创建超级管理员账号（用户名、密码、邮箱），记住该账号，用于后续用户管理和项目配置。

四、关键配置说明与优化

4.1 端口安全设计（核心亮点）

本次部署采用“Label Studio本机隐藏+Nginx反向代理”的安全架构，核心设计如下：

Label Studio端口映射为127.0.0.1:9000:8080，仅宿主机本机可直接访问，外部无法直接发起请求，避免核心服务被恶意攻击；
Nginx对外仅暴露8081端口，所有用户通过该端口访问，由Nginx统一转发请求，相当于给Label Studio加了一层“防护屏障”；
防火墙仅需放行8081端口，无需放行9000、5432、6379端口，进一步提升内网安全性。

4.2 外部Redis/PG连接说明

本次部署未使用Docker内置的Redis和PostgreSQL，而是复用宿主机已有的实例，优势如下：

统一管理：企业内网通常已有数据库/缓存集群，复用现有实例可减少资源浪费，便于统一运维和数据备份；
数据安全：数据库和缓存数据存储在宿主机，而非Docker容器，避免容器删除导致数据丢失；
灵活扩展：后续可根据需求，将Redis/PG替换为集群架构，无需修改Label Studio配置。

注意：配置中LABEL_STUDIO_DB_HOST和REDIS_HOST必须填写宿主机内网IP，不可使用localhost（容器内localhost指向自身，而非宿主机）。

4.3 性能优化配置

大文件上传：Nginx配置client_max_body_size 10G，支持GB级视频、图片上传，避免上传超时；
静态文件缓存：Nginx对Label Studio的静态资源（CSS/JS/图片）进行30天缓存，减少重复请求，提升页面加载速度；
超时配置：延长代理超时时间至300s，适配标注过程中长时间连接的场景。

五、多人权限管理与数据集导入

5.1 多角色用户管理

登录超级管理员账号后，可创建多角色用户，实现多人协作和数据集隔离：

点击顶部导航栏「Settings」→「Users」；
点击「Create User」，填写用户名、密码，选择角色：
1. Annotator（标注员）：仅能标注分配的任务，无审核和管理权限；
2. Reviewer（审核员）：可标注并审核标注结果，确保标注质量；
3. Admin（管理员）：全权限，可管理用户、项目和配置（谨慎分配）。
为用户分配项目权限：进入目标项目→「Settings」→「Access」，添加用户并分配View（仅查看）、Edit（可标注）、Owner（项目所有者）权限。

5.2 数据集导入（私有化存储）

Label Studio支持多种数据集导入方式，适配不同规模的标注需求，所有数据均存储在宿主机/opt/label-studio/data目录，确保私有化：

小数据集：进入项目→「Import」→「Upload Files」，批量上传本地文件（图片、文本、视频等）；
大数据集（推荐）：将内网数据集文件夹挂载到容器，避免直接上传耗时： # 1. 创建内网数据集目录 mkdir -p /data/label-dataset # 2. 修改docker-compose.yml，添加卷挂载（在volumes下新增） volumes: - ./data:/label-studio/data - ./conf:/label-studio/conf - /data/label-dataset:/label-studio/dataset # 3. 重启服务 docker compose down && docker compose up -d导入时选择「Local Storage」，找到/label-studio/dataset目录即可批量导入。

六、常用运维命令与故障排查

6.1 常用运维命令

操作需求	命令
启动服务	`docker compose up -d`
停止服务	`docker compose down`
重启服务	`docker compose restart`
查看Label Studio日志	`docker compose logs -f label-studio`
查看Nginx日志	`docker compose logs -f nginx`
备份数据（核心）	`cp -r /opt/label-studio/data /backup/label-studio-$(date +%Y%m%d)`
重置管理员密码	`docker exec -it label-studio python manage.py changepassword 用户名`

6.2 常见故障排查

问题1：Label Studio启动失败，日志提示“could not connect to postgres/redis” 排查：① 确认宿主机Redis/PG服务正在运行；② 检查配置文件中IP、端口、密码是否正确；③ 确认宿主机防火墙放行5432、6379端口；④ 检查PG/Redis配置是否允许外部访问。
问题2：访问http://宿主机IP:8081无法打开页面排查：① 检查Nginx和Label Studio容器是否正常运行；② 确认宿主机防火墙放行8081端口；③ 查看Nginx日志，确认反向代理配置是否正确。
问题3：大文件上传失败，提示超时排查：修改Nginx配置中的client_max_body_size、proxy_read_timeout参数，增大数值后重启Nginx。

七、总结

本文基于Docker容器化技术，完成了Label Studio私有标注平台的完整部署，整合了Nginx反向代理、外部Redis缓存、外部PostgreSQL数据库，实现了以下核心目标：

私有化安全：所有数据存储在内网，Label Studio仅本机可访问，通过Nginx反向代理对外暴露，杜绝数据外流和恶意攻击；
多人协作：支持多角色用户管理和数据集隔离，适配企业团队标注场景；
稳定高效：复用宿主机现有Redis/PG，优化大文件上传和页面加载性能，适合长期使用；
易用易维护：通过Docker Compose统一管理容器，运维命令简洁，故障排查便捷。

本部署方案适用于企业内网、敏感数据标注场景，可根据实际需求扩展功能（如配置HTTPS加密、集成MinIO私有存储、批量导入/导出标注数据），进一步提升平台的安全性和实用性。