Label Studio 数据存储配置指南：SQLite、PostgreSQL 与 MinIO 的选型与实践-酒店常州论坛

Label Studio 数据存储配置指南：SQLite、PostgreSQL 与 MinIO 的选型与实践

【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio

Label Studio 使用数据库来存储项目数据与配置信息。本文以存储配置官方指南为骨架，系统梳理其内置的 SQLite、PostgreSQL 与 MinIO 三种存储方案的适用场景、配置参数与数据持久化方案，并深入对应源码，讲解环境变量如何驱动 Django 数据库后端切换、-db参数如何解析、Docker Compose 组合文件如何拉起 PostgreSQL/MinIO 等底层机制。读完本文，你可以为小规模原型、百万级标注任务或 S3 兼容对象存储等不同场景，快速选择并落地一套正确的数据存储方案。

概览：Label Studio 的数据存储架构

Label Studio 的元数据（项目、任务、标注结果、用户与权限等）统一由一个数据库承载。在核心设置模块中，Django 的DATABASES_ALL字典预置了三种后端，并通过DJANGO_DB环境变量选择其一：

sqlite：默认的 SQLite 单文件数据库，无需任何配置即可运行；
postgresql：生产环境推荐的 PostgreSQL，适合大规模任务与高并发场景；
mysql：可选支持的 MySQL 后端（当前文档未展开，但源码同样内置了配置入口）。

此外，大体积的标注数据（图片、音频、视频等原始文件）并不直接塞进关系型数据库，而是通过外部对象存储（如 S3、GCS、Azure Blob 或本地 MinIO）管理。MinIO 作为 S3 兼容的对象存储，可以与本仓库自带的docker-compose.minio.yml组合文件一键拉起，用于贴近生产环境的本地联调。

标注性能与数据库选型

SQLite 的适用边界

SQLite 是 Label Studio 的默认数据库，适合数万级标注任务的项目，前提是你不会在数据管理器中频繁使用复杂过滤条件，也不会有复杂的多用户协作流水线。从源码可以印证，SQLite 的能力边界是显式存在的：

在 projects/models.py、tasks/serializers.py、data_manager/managers.py 等多处，代码都会先判断settings.DJANGO_DB == settings.DJANGO_DB_SQLITE再决定是否启用某些高级查询能力；
部分异步迁移（如 0055_task_proj_octlen_idx_async.py、0056_task_prediction_result_proj_gin_idx_async.py）也会先检测是否为 SQLite，再决定是否创建高性能索引，说明 SQLite 下部分索引与查询优化会被跳过。

何时必须换用 PostgreSQL

如果出现以下情况，请升级到 PostgreSQL：

需要标注数百万条任务；
预期有大量并发用户同时操作；
希望运行真实规模的项目（而非演示原型）；
频繁导入新标注任务。

文档给出了一组可参考的量化指标：如果在标注进行的同时导入数据，任务加载与标注提交的耗时可能超过10 秒；当任务量超过100,000条且并发用户达到5 个以上时，就应考虑 PostgreSQL 或其他更健壮的数据库。也建议先阅读安装与升级指南，其中包含 PostgreSQL 数据库的完整安装配置说明。

使用 SQLite 数据库（默认方案）

Label Studio 默认使用 SQLite，无需任何配置。所有数据都会写入一个单一文件，存放在管理员用户目录下的应用数据目录中；启动 Label Studio 后，终端会打印出实际使用的目录路径，例如：

=> Database and media directory: /root/.local/share/label-studio

从源码看，这个目录由 get_data_dir() 根据操作系统用户数据目录规范（user_data_dir(appname=_DIR_APP_NAME)）计算并自动创建；SQLite 数据库文件的默认名称为label_studio.sqlite3（见 base.py）。你也可以通过命令行-db参数或DATABASE_NAME环境变量显式指定数据库文件路径：

label-studio start my_project -db /path/to/custom.sqlite3

在 server.py 中，-db参数会被解析为绝对路径并写入DATABASE_NAME环境变量，进而被 Django 设置读取并用于打开 SQLite 文件。相关参数定义见 argparser.py。

连接 PostgreSQL 数据库

将任务与标注结果存储在 PostgreSQL 中，是处理数十万乃至上百万级任务量时的推荐方案，尤其适合需要频繁导入新任务的使用场景。

方式一：启动时初始化连接

使用以下命令启动 Label Studio，配置 PostgreSQL 连接，扫描已有任务并载入指定项目进行标注：

label-studio start my_project --init -db postgresql

注意：此处的-db postgresql在启动流程中会被解释为数据库文件的相对路径postgresql，真正决定数据库后端的仍是DJANGO_DB环境变量（详见下文“环境变量的优先级与解析顺序”）。因此执行上述命令前，必须先设置下列环境变量，Label Studio 才能连接到 PostgreSQL：

DJANGO_DB=default POSTGRE_NAME=postgres POSTGRE_USER=postgres POSTGRE_PASSWORD= POSTGRE_PORT=5432 POSTGRE_HOST=db

各环境变量的作用与默认值，可以从 base.py 中的 PostgreSQL 后端配置找到对应实现：

环境变量	含义	源码默认值	文档示例值
`DJANGO_DB`	选择数据库后端（`sqlite`/`postgresql`/`mysql`，或`default`指向 PostgreSQL）	`sqlite`（见 label_studio.py）	`default`
`POSTGRE_NAME`	数据库名称	`postgres`	`postgres`
`POSTGRE_USER`	数据库用户	`postgres`	`postgres`
`POSTGRE_PASSWORD`	数据库密码	`postgres`	（空）
`POSTGRE_PORT`	数据库端口	`5432`	`5432`
`POSTGRE_HOST`	数据库主机地址	`localhost`	`db`

提示：在 Docker Compose 环境中POSTGRE_HOST=db指向 compose 网络中名为db的服务（见下文）。在宿主机直连时，应改为实际数据库地址。

方式二：通过 Docker Compose 启动

仓库根目录的 docker-compose.yml 已经内置了一个完整的 PostgreSQL 栈：app（Label Studio 应用）、nginx（反向代理）与db（PostgreSQL 17）三个服务。直接执行：

docker-compose up -d

即可让 Label Studio 运行在 PostgreSQL 之上。该 compose 文件中的app服务已经预置了上述全部连接环境变量（docker-compose.yml），并挂载数据卷./mydata:/label-studio/data:rw（docker-compose.yml）以持久化应用数据。db服务使用pgautoupgrade/pgautoupgrade:17-alpine镜像，并将数据保存在./postgres-data目录（docker-compose.yml）。

环境变量的优先级与解析顺序

DJANGO_DB的取值会直接决定 Django 使用哪套DATABASES配置，这一机制在 label_studio.py 中完成：

DJANGO_DB = get_env('DJANGO_DB', DJANGO_DB_SQLITE) DATABASES = {'default': DATABASES_ALL[DJANGO_DB]}

而在基础设置 base.py 中，default这一别名被预先指向了 PostgreSQL 配置：

DATABASES_ALL['default'] = DATABASES_ALL[DJANGO_DB_POSTGRESQL] DATABASES = {'default': DATABASES_ALL.get(get_env('DJANGO_DB', 'default'))}

因此，文档示例中的DJANGO_DB=default实际等效于DJANGO_DB=postgresql——这一点在 docker-compose.yml 中也被使用。若想显式切换回 SQLite，设置DJANGO_DB=sqlite即可。仓库测试中也印证了这种切换逻辑，例如 api_tasks.tavern.yml 会根据DJANGO_DB是否包含default决定跳过或执行特定用例，而 test_experimental.py 则通过override_settings(DJANGO_DB='postgres')模拟 PostgreSQL 环境。

使用 MinIO 对象存储

MinIO 是兼容 Amazon S3 协议的对象存储服务，可用于存放需要标注的原始数据（任务文件），让本地开发环境更贴近基于 S3 的生产架构。

启动 MinIO 容器

仓库提供了专用的组合文件 docker-compose.minio.yml，除 MinIO 服务外还附带一个 Prometheus 监控实例。启动命令：

# Linux 下若不在 docker 组中，请在命令前加 sudo docker compose -f docker-compose.yml -f docker-compose.minio.yml up -d

启动后，MinIO 服务可通过 http://localhost:9000 访问（API 端口），Web 管理控制台位于 http://localhost:9009（见 docker-compose.minio.yml）。

如需配置 MinIO 参数，请在仓库根目录创建.env文件，并务必覆盖默认的管理员凭据：

MINIO_ROOT_USER=minio_admin_do_not_use_in_production MINIO_ROOT_PASSWORD=minio_admin_do_not_use_in_production # 自动选择正确的 compose 组合文件（二选一） # Windows COMPOSE_FILE=docker-compose.yml;docker-compose.minio.yml # Linux/Mac COMPOSE_FILE=docker-compose.yml:docker-compose.minio.yml # 指定 MinIO 版本（可选） # MINIO_VERSION=RELEASE.2025-04-22T22-12-26Z

这些变量与 docker-compose.minio.yml、docker-compose.minio.yml 中的MINIO_VERSION、MINIO_ROOT_USER、MINIO_ROOT_PASSWORD插值一一对应，且均有安全的默认回退值。.env中的COMPOSE_FILE变量可以让docker compose up -d自动加载两个文件，无需每次手写-f参数。

将 Label Studio 连接到本地 MinIO

如果你没有静态 IP 地址，需要在 hosts 文件中添加一条记录，让 Label Studio 容器与浏览器都能以同一主机名访问 MinIO：

127.0.0.1 minio

各系统的 hosts 文件位置：

Windows：C:\Windows\System32\drivers\etc\hosts
Linux：/etc/hosts
macOS：/private/etc/hosts

修改 hosts 文件后，即可在浏览器中通过 http://minio:9000 访问 MinIO 服务器。之后可在 Label Studio 的存储设置中添加 S3 兼容存储源，填入 MinIO 的访问密钥与端点即可对接。

清除 MinIO 数据

以下命令会删除 MinIO 容器及其关联数据卷，属于破坏性操作，会清空 MinIO 中存储的全部数据：

docker-compose -f docker-compose.minio.yml down --volumes

数据持久化

如果你使用 Docker 容器、Heroku 或其他云平台部署，在关闭 Label Studio 后可能希望数据仍然保留。虽然可以通过数据导出导出标注任务与标注结果，但要完整保留 Label Studio 的运行状态以及上传的标注素材等资产，仍需配置数据持久化。

使用 Docker 挂载卷持久化

将 Docker 卷挂载到宿主机，即可在容器销毁后保留内部的 SQLite 数据库与上传的素材文件。

命令行启动方式下，用自定义卷替换原命令中的卷参数即可：

docker run -it -p 8080:8080 -v <yourvolume>:/label-studio/data heartexlabs/label-studio:latest

!!! attention "重要" 由于镜像是非 root 用户容器，挂载的文件与目录必须具备UID 1001可读写的权限。

若使用仓库自带的 docker-compose.yml，其中已经通过卷声明实现了持久化——nginx与app两个服务都挂载了./mydata:/label-studio/data:rw（docker-compose.yml、docker-compose.yml）。等效的手写 compose 配置如下：

version: "3.3" services: label_studio: image: heartexlabs/label-studio:latest container_name: label_studio ports: - 8080:8080 volumes: - ./mydata:/label-studio/data volumes: mydata:

此处使用绑定挂载（./mydata）或命名卷（mydata）均可，命名卷的更多用法参见 Docker Compose 文件规范中的 volumes 章节。

使用云服务商持久化

如果部署在 Heroku、AWS、Google Cloud 或 Microsoft Azure 等云平台，可以自建并托管一个 PostgreSQL 实例，然后为 Label Studio 设置上文介绍的 PostgreSQL 环境变量（DJANGO_DB、POSTGRE_NAME、POSTGRE_USER、POSTGRE_PASSWORD、POSTGRE_PORT、POSTGRE_HOST），即可实现数据持久化。云厂商提供的托管数据库服务通常自带备份、高可用等能力，适合作为生产环境的数据层。

生产实践建议与排查思路

数据库选型优先级：演示原型、万级以内任务用默认 SQLite 零成本起步；正式项目、十万级以上任务或多用户并发，优先切换到 PostgreSQL；需要对象存储时用 MinIO（S3 兼容）承接原始文件。
环境变量检查清单：切换到 PostgreSQL 失败时，重点核对DJANGO_DB是否被显式设为postgresql（或default）、POSTGRE_HOST是否可解析、POSTGRE_PASSWORD是否与实例实际密码一致。源码层面，Django 的DATABASES完全由这些变量驱动（base.py），变量缺失时会回退到默认值。
容器权限：非 root 容器要求挂载目录对UID 1001可写，若容器无法启动或写入失败，先检查挂载目录的所有权与权限位。
MinIO 凭据安全：.env中的默认凭据仅用于本地开发，任何暴露到公网的环境都必须替换为强密码。

小结

Label Studio 的数据存储体系由“关系型数据库 + 外部对象存储”两部分构成：SQLite 负责开箱即用的轻量起步，PostgreSQL 承担大规模、高并发场景，MinIO（或任意 S3 兼容服务）则托管标注素材。本文结合存储配置指南、核心数据库设置、CLI 参数解析、启动入口以及 docker-compose.yml、docker-compose.minio.yml 等仓库文件，完整覆盖了从数据库选型、环境变量配置、容器编排到数据持久化的全链路实践，可作为你搭建生产级 Label Studio 的数据存储参考手册。

【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析