Label Studio 故障排查全指南：安装、标注、云存储与 ML 后端常见问题定位与修复
【免费下载链接】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 社区版官方故障排查文档为核心，系统梳理从安装启动、项目加载、标注性能、云存储（S3/GCS/Azure/本地文件）同步，到预标注与 ML 机器学习后端接入过程中的高频故障场景，并逐一给出可复现的定位步骤与修复方案。阅读本文后，你将掌握如何通过浏览器控制台、服务端日志、/django-rq管理页、curl健康检查等工具快速定位问题，并能够正确处理 CORS、403 权限、任务同步、预测结果不可见、ML 超时与 Docker 部署等典型难题。
适用范围说明：本文面向 Label Studio 社区版（Community Edition）的常见用户侧问题。Label Studio Enterprise 的专属问题请参考官方支持中心的文章（见仓库 docs/source/guide/troubleshooting.md 页首说明）。
安装阶段问题排查
安装类问题请直接参考专门的安装排障指南 docs/source/guide/install_troubleshoot.md，其中覆盖了依赖冲突、数据库初始化失败、端口占用等安装与启动过程中的常见报错。本文后续章节聚焦启动成功之后、日常使用中出现的各类问题。
项目页面加载异常
打开项目时出现空白页
Label Studio 启动并打开项目后页面空白，可能由多种原因导致，最常见的是启动时指定的 host 缺少协议前缀。
如果在启动 Label Studio 时指定的 host 没有携带http://或https://协议头，Label Studio 可能无法正确定位加载项目页面所需的静态资源文件，从而渲染出空白页。
修复方式：更新启动参数或环境变量中指定的 host，确保其包含完整协议前缀。具体启动方式参见 docs/source/guide/start.md。例如：
# 错误示例：缺少协议前缀 label-studio start --host 192.168.1.10 --port 8080 # 正确示例：在浏览器访问时需以 http:// 或 https:// 开头 # label-studio start --host 0.0.0.0 --port 8080标注过程常见问题
标注速度明显变慢
标注缓慢通常与数据库负载和标注配置规模相关，可按以下顺序排查：
SQLite 数据库负载过高：如果服务使用默认的 SQLite 数据库，且其他用户正在导入大批量数据，数据库的读写压力会导致同一台服务器上所有标注用户的操作变慢。SQLite 不擅长并发写，这是由其架构决定的。
错峰导入大批量数据：如需上传成千上万条数据，建议选择无人标注的时段执行，或者改用 PostgreSQL、Redis 等更适合并发场景的数据库后端。可以直接在 Label Studio 仓库根目录使用 Docker Compose 一键切换 PostgreSQL：
docker-compose up -d仓库内的 docker-compose.yml 定义了完整的服务编排。此外，也可以不经过数据库直接同步云存储或数据库存储中的数据，参见 docs/source/guide/storage.md。
标签规模过大：如果标注配置中定义了成千上万个标签，界面渲染与交互会显著变慢，建议改用外部分类体系（Taxonomy）标签来承载大规模层级标签，而不是平铺几千个
<Label>。
图片/音频/资源加载失败（CORS 问题）
标注时图片、音频等资源加载不出来，最常见的原因是CORS（跨域资源共享）问题：当你尝试从外部托管拉取图片时，浏览器会出于安全策略拦截跨域请求。
定位方法：打开浏览器开发者工具（F12）的控制台（Console）面板，查看具体的报错信息。如果确认是 CORS 拦截，通常需要在资源所在的外部主机侧放行跨域访问：
能管理托管服务器：在 Web 服务器配置中为对应 location 开放 CORS 响应头。例如在 nginx 的
/etc/nginx/nginx.conf中，往location段加入如下配置：location <YOUR_LOCATION> { if ($request_method = 'OPTIONS') { add_header 'Access-Control-Allow-Origin' '*'; add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS'; # # Custom headers and headers various browsers *should* be OK with but aren't # add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range'; # # Tell client that this pre-flight info is valid for 20 days # add_header 'Access-Control-Max-Age' 1728000; add_header 'Content-Type' 'text/plain; charset=utf-8'; add_header 'Content-Length' 0; return 204; } if ($request_method = 'POST') { add_header 'Access-Control-Allow-Origin' '*'; add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS'; add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range'; add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range'; } if ($request_method = 'GET') { add_header 'Access-Control-Allow-Origin' '*'; add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS'; add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range'; add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range'; } }这段配置覆盖了浏览器的 OPTIONS 预检请求以及实际的 GET/POST 请求，
Access-Control-Max-Age 1728000让预检结果在 20 天内免于重复发送。使用云对象存储：Amazon S3、Google Cloud Storage（GCS）、Microsoft Azure Storage 各自都有独立的 CORS 配置入口，请分别在其控制台或 API 中为你的存储桶（bucket）配置 CORS 规则（S3 参考其用户指南中的 CORS 章节，GCS 参考其配置 CORS 文档，Azure 参考其 CORS 支持文档）。
使用本地静态文件服务器：如果通过
python -m http.server 8081 -d这类简易服务器托管数据，它默认不携带 CORS 头。可以改用支持 CORS 的http-server：npm install http-server -g http-server -p 3000 --cors
不是所有主机都支持 CORS 配置，但如果托管方提供了管理后台，可以尝试在其中查找并开启 CORS 相关设置。
音频波形与标注不一致
标注完音频数据后发现界面上显示的波形与时间戳、实际声音不匹配，常见原因是音频编码格式兼容性问题。例如标注的是 mp3 文件时，其帧结构与浏览器波形渲染可能存在偏差，建议转换为 wav 格式后再标注：
ffmpeg -y -i audio.mp3 -ar 8k -ac 1 audio.wav上面的命令将音频重采样为 8kHz 单声道 wav，兼顾了文件体积与波形渲染的准确性。
标注者看不到预测结果
如果标注者无法看到预标注（Pre-annotations）结果，请跳转至下文「预标注问题」章节。
云存储与本地存储问题
使用外部云存储连接（S3、GCS、Azure）时，需要先理解 Label Studio 的同步机制：
- Source 存储（数据源）：
- 选择Files导入方式时，Label Studio不会把桶内数据真正导入，而是创建指向对象的引用。因此你可以在桶侧完全控制哪些数据被同步、哪些展示在标注界面。
- 选择Tasks导入方式时，桶内文件被假定为不可变；要将更新后的文件状态推送到 Label Studio，唯一方式是换一个新文件名上传到存储，或者删除与该文件关联的所有任务后重新同步。
- 同步是单向的：要么由桶内对象创建任务（Source 存储），要么把标注结果推送到输出桶（Target 存储）。在桶侧修改内容并不能保证结果的一致性。
- 推荐实践：为每个 Label Studio 项目使用独立的桶目录（bucket folder），避免多个项目互相污染。
云存储数据无法预览（CORS 未配置）
如果没有正确配置 CORS，Label Studio 中无法预览云存储数据。典型症状是：界面上只显示数据的链接而不是数据预览，或浏览器控制台出现 CORS 错误。
- Amazon S3、GCS、Azure Storage 请分别在其官方文档中配置存储桶 CORS 规则。
- 配置 CORS 的同时，注意以下两点：
为服务账号（Service Account）授予正确的角色与权限。例如为服务账号授予
roles/iam.serviceAccountTokenCreator角色（GCS 场景）。如果 DEBUG 日志中出现了
labelstudio这个服务账号名相关的错误，可以通过在label-studio start命令中追加--log-level DEBUG标志开启调试日志：label-studio start --log-level DEBUG
浏览器控制台出现 403 错误
403 错误通常意味着凭据（credentials）配置不正确。
GCS（Google Cloud Storage）凭据检查清单：
- 按照 Google Cloud 官方「设置认证」与「Cloud Storage 的 IAM 权限」文档配置认证；
- 账号必须同时具备Service Account Token Creator（服务账号令牌创建者）角色、Storage Object Viewer（存储对象查看者）角色，以及storage.buckets.get访问权限；
- 如果使用服务账号授权访问 GCP，务必先激活该服务账号，例如通过
gcloud auth activate-service-account命令。
Amazon S3 凭据检查清单：
按 AWS CLI 官方「配置与凭据文件设置」文档配置凭据，并确认在 aws 客户端中凭据可用；
检查区域（region）是否正确：创建桶时指定的区域必须与源/目标存储设置或
.aws/config文件中的区域一致，否则访问桶对象会出问题。例如修改~/.aws/config：[default] region=us-east-2 # change to the region of your bucket检查凭据是否仍然有效：如果浏览器控制台出现 403，且桶权限已正确配置，可能需要更新 Access Key ID、Secret Access Key 与 Session ID。参见 AWS IAM 官方文档中关于「请求临时安全凭据」的说明。
点击 Sync 后数据没有更新
同步并非即时触发：Label Studio 的同步过程基于内部任务调度器（job scheduler），因此点击 Sync 后可能不会立刻看到效果。如果等待一段时间后仍无变化，按以下顺序排查：
- 确认凭据配置正确（见上文 403 部分）。
- 进入云存储设置页，点击连接旁的Edit，检查：
- File Filter Regex（文件过滤正则）是否正确。注意：当未指定过滤规则时，所有找到的对象都会被跳过。过滤条件必须是合法正则表达式而非通配符，例如
.*是合法的，*.不合法。 - Import method（导入方式）：处理图片、音频、文本等二进制内容时，简单场景应设置为
Files。该模式会让 Label Studio 自动以 URI 链接（如s3://bucket/1.jpg）形式创建任务，并在打开标注界面时解析为带签名的httpsURL 加载预览。如果桶中存放的是 Label Studio 格式的 JSON/JSONL 任务文件或 Parquet 文件，则应设为Tasks。
- File Filter Regex（文件过滤正则）是否正确。注意：当未指定过滤规则时，所有找到的对象都会被跳过。过滤条件必须是合法正则表达式而非通配符，例如
- 检查 rq worker 是否故障。一个快速验证方式是执行一次导出操作：在 Data Manager 中点击Export，创建一个新快照并下载 JSON 文件。如果导出报错，大概率是 rq worker 出了问题。另一个方法是：以超级用户（superuser）身份登录后访问
/django-rq页面，查看workers列，如果值为0或列为空，则说明 worker 异常。
云存储中的 JSON 文件未同步且 Data Manager 为空
按以下步骤排查：
- 编辑存储设置；如果在 Data Manager 中能看到任务，则问题已解决，跳到第 2 步。
- 将Import method设置为
Tasks。 - 如果 Data Manager 中依然看不到任务，说明你的桶只有 LIST 权限而没有 GET 权限。
原因在于权限差异：只有 LIST 权限时，Label Studio 只能扫描桶内对象的存在性，无法真正读取内容；具备 GET 权限后，Label Studio 才能读取数据并正确解析其中的 JSON 文件。
任务加载方式与预期不符
任务已经同步到 Label Studio，但展示不符合预期（例如显示的是 URL 而不是图片，或者一个文件只出现一条任务而预期是多条），检查以下两点：
- 在云存储中放置 JSON 文件时（参见 docs/source/guide/storage.md），如果同一个文件包含多个任务，必须保证所有任务格式一致——不能在同一个文件中混用「只含
data字段的原始任务」和「包含 annotations、predictions 的完整任务」。 - 如果同步的是图片或音频文件，确保Import method设置为
Files。
Windows 下无法访问本地存储
在 Windows 上使用本地文件存储（Local Storage）时，路径的转义规则容易踩坑，请注意：
- 设置环境变量
LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT时必须使用双反斜杠（\\），因为需要对反斜杠本身进行转义。 - 在项目配置本地存储时填写Absolute local path（绝对本地路径）则应使用单反斜杠（
\）。 - 不要在
LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT或Absolute local path中使用空格或非拉丁字符。
示例：
LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT=c:\\data\\media Absolute local path from Local Storage settings = c:\data\media\subpath源码层面的安全校验：从仓库源码看，本地文件存储并非随意指向任意目录。在 label_studio/io_storages/localfiles/models.py 的validate_connection中，Label Studio 会强制校验：绝对本地路径必须真实存在、不能与LOCAL_FILES_DOCUMENT_ROOT相同（出于安全原因必须指向其子目录），且只有当LOCAL_FILES_SERVING_ENABLED=true时才允许启用。相关的环境变量定义位于 label_studio/core/settings/base.py：默认LOCAL_FILES_SERVING_ENABLED=False（从宿主文件系统提供文件存在安全风险，默认关闭），而LOCAL_FILES_DOCUMENT_ROOT默认指向文件系统根目录。这意味着启用本地存储前需要显式设置上述环境变量并重启服务。
预标注（Pre-annotations）问题
排查预标注问题前，先确认标注单位使用正确。对于图像标注，Label Studio 的x、y、width、height均以图片整体尺寸的百分比表示，而非像素值。完整的换算公式与双向转换代码示例见 docs/source/includes/image_units.md，核心换算关系为：
pixel_x = x / 100.0 * original_width pixel_y = y / 100.0 * original_height pixel_width = width / 100.0 * original_width pixel_height = height / 100.0 * original_height示例任务 JSON 中的标注结果会携带original_width、original_height、image_rotation等字段（相关 schema 可参见 label_studio/tasks/openapi_schema.py），其中value内的x/y/width/height即上述百分比单位。如果你的模型输出是像素坐标，必须先换算成百分比再导入。
标注者看不到预测结果
标注者看不到预测，或在导入预标注后出现异常行为（导入方式参见 docs/source/guide/predictions.md），按以下步骤排查：
首先，在项目的Settings > Annotation设置中，确认Use predictions to pre-label tasks（使用预测为任务预标注）已开启。
检查标注配置与任务的配置值
预标注任务 JSON 中的from_name必须与标注配置中<Labels name="label" toName="text">的name值一致；to_name必须与toName一致。
例如，以下 XML 配置片段：
... <Choices name="choice" toName="image" showInLine="true"> ... <RectangleLabels name="label" toName="image"> ...应对应如下 JSON 片段：
... "type": "rectanglelabels", "from_name": "label", "to_name": "image", ... "type": "choices", "from_name": "choice", "to_name": "image", ...检查配置与任务中的标签
确保已经为标注界面配置了标注配置，且 JSON 文件中的标签（labels）与配置中的标签完全一致。如果使用了转换模型输出的工具（如 label-studio-transformers），请确认工具没有篡改标签文本。
检查 ID 与 toName 值
如果进行了嵌套标注——例如针对特定 Label 或 Choice 值展示 TextArea 标签——那么这些结果的ID 必须相互匹配。
例如，要在命名实体识别任务的同时做文本转写，标注配置如下：
<View> <Labels name="label" toName="text"> <Label value="PER" background="red"/> <Label value="ORG" background="darkorange"/> <Label value="LOC" background="orange"/> <Label value="MISC" background="green"/> </Labels> <Text name="text" value="$text"/> <TextArea name="entity" toName="text" perRegion="true"/> </View>为该配置添加预测文本与建议转写的示例 JSON：
{ "data":{ "text":"The world that we live in is a broad expanse of nothingness, said the existential philosopher, before he rode away with his cat on his motorbike. " }, "predictions":[ { "result":[ { "value":{ "start":135, "end":144, "text":"motorbike", "labels":[ "ORG" ] }, "id":"def", "from_name":"ner", "to_name":"text", "type":"labels" }, { "value":{ "start":135, "end":144, "text":[ "yay" ] }, "id":"def", "from_name":"entity", "to_name":"text", "type":"textarea" } ] } ] }因为 TextArea 标签作用于每个被标注的区域，所以上述例子中标签结果与 textarea 结果的id必须一致（这里均为"def"）。
注意：示例中
from_name为ner，请根据你自己的<Labels name="...">实际取值调整。
只读与隐藏区域
某些场景下，让预标注的边界框、文本片段、音频片段等区域只读或隐藏非常有用。可以在annotations.result列表内的结果字典中设置"readonly": true或"hidden": true实现，例如：
{ "result": [ { "value": { "...": "..." }, "from_name": "label", "to_name": "image", "type": "rectanglelabels", "readonly": true } ] }导出问题
导出的 HTML 标签偏移位置错误
导出 HTML 标注（例如 HTML 命名实体识别任务）时偏移量不对，最常见的原因是HTML 压缩（minification）。上传 HTML 文件到 Label Studio 标注时，HTML 会被压缩以去除空白字符；标注时的偏移量针对的是压缩后的 HTML 版本，而非原始未修改的 HTML 文件。
两种解决思路：
阻止压缩：改用其他导入方式导入 HTML 数据，参见 docs/source/guide/tasks.md 中导入 HTML 数据的部分。
修正已有标注：用与 Label Studio 相同的方式压缩源 HTML 文件，使偏移量与之对齐。压缩脚本如下：
import htmlmin with open("sample.html", "r") as f: html_doc = f.read() minified_html_doc = htmlmin.minify(html_doc, remove_all_empty_space=True)
如果压缩后偏移位置仍然不对，则可能是复杂的 CSS 或其他原因导致。
ML 机器学习后端问题
ML 后端是独立于 Label Studio 运行的另一个服务，排查时务必确认查看的是正确的服务器控制台日志。需要更详细日志时，用--debug选项启动 ML 后端服务器。
日志位置速查：
- 直接运行 ML 后端时：
- 生产环境训练日志位于
my_backend/logs/rq.log - 生产环境运行时日志位于
my_backend/logs/uwsgi.log - 开发模式下训练日志显示在浏览器控制台
- 生产环境训练日志位于
- 使用 Docker Compose 运行 ML 后端时：
- 训练日志位于
logs/rq.log - 主进程与推理日志位于
logs/uwsgi.log
- 训练日志位于
Label Studio 对 ML 服务请求的默认超时设置
Label Studio 对所有发往 ML 服务器的请求都设有默认超时。不同类型的请求对应的超时环境变量如下：
| 请求类型 | 用途 | 环境变量 | 默认值（秒） |
|---|---|---|---|
| Health | 添加新 ML 后端时检查其健康状态 | ML_TIMEOUT_HEALTH | 1 |
| Setup | 初始化 ML 模型 | ML_TIMEOUT_SETUP | 3 |
| Predict | 从 ML 后端获取预测 | ML_TIMEOUT_PREDICT | 100 |
| Train | 训练请求 | ML_TIMEOUT_PREDICT（文档原文如此，实际训练时长建议用ML_TIMEOUT_TRAIN） | 100 / 30 |
| Duplicate model | 复制模型 | ML_TIMEOUT_PREDICT（同训练） | 100 |
| Delete | 删除请求 | ML_TIMEOUT_PREDICT（同训练） | 100 |
| Train job status | 查询训练任务状态 | ML_TIMEOUT_PREDICT（同训练） | 100 |
你可以在启动 Label Studio 时为每种请求单独设置环境变量来调整超时。从源码看，这些超时变量统一定义在 label_studio/ml/api_connector.py：
CONNECTION_TIMEOUT = float(get_env('ML_CONNECTION_TIMEOUT', 1)) # seconds TIMEOUT_DEFAULT = float(get_env('ML_TIMEOUT_DEFAULT', 100)) # seconds TIMEOUT_TRAIN = float(get_env('ML_TIMEOUT_TRAIN', 30)) TIMEOUT_PREDICT = float(get_env('ML_TIMEOUT_PREDICT', 100)) TIMEOUT_HEALTH = float(get_env('ML_TIMEOUT_HEALTH', 1)) TIMEOUT_SETUP = float(get_env('ML_TIMEOUT_SETUP', 3)) TIMEOUT_DUPLICATE_MODEL = float(get_env('ML_TIMEOUT_DUPLICATE_MODEL', 1)) TIMEOUT_DELETE = float(get_env('ML_TIMEOUT_DELETE', 1)) TIMEOUT_TRAIN_JOB_STATUS = float(get_env('ML_TIMEOUT_TRAIN_JOB_STATUS', 1))设置示例：
export ML_TIMEOUT_PREDICT=300 # 大模型推理较慢时延长预测超时 export ML_TIMEOUT_TRAIN=600 # 训练耗时较长时延长训练超时 export ML_CONNECTION_TIMEOUT=5 # 连接超时从实现细节看，连接超时与请求超时会被组合成元组(connection_timeout, request_timeout)传给底层 HTTP 客户端（见 label_studio/ml/api_connector.py），同时请求自动附带User-Agent: heartex/<version>头。另外，仓库默认开启了ML_BLOCK_LOCAL_IP（见 label_studio/core/settings/base.py），它会阻止 ML 后端访问内网/回环地址以防御 SSRF，相关校验在添加 ML 后端时即生效（见 label_studio/ml/serializers.py）。
添加 ML 后端后显示 Disconnected
ML 后端服务器可能没有正常启动。按以下步骤排查：
检查 ML 后端服务器是否在运行，执行健康检查：
curl -X GET http://localhost:9090/health如果健康检查无响应或报错，查看服务器日志。
如果使用 Docker Compose 启动 ML 后端，检查用于配置 Docker 内环境的
requirements.txt是否缺少必要依赖。
点击 Start Training 后提示 Error
点击错误信息可以查看 traceback，常见错误包括：
- 已完成标注的数量不足，无法开始训练；
- 服务器内存不足。
预测结果错误或标注页看不到模型预测
ML 后端可能生成了格式错误的预测。检查：
- ML 后端预测格式是否与导入的预标注格式保持一致；
- 项目的标签配置是否与 ML 后端输出匹配。例如使用
<Choices>标签为文本创建预测类别。更多标签用法参见 Label Studio 标签文档。
模型后端无法启动或运行
如果启动 ML 后端服务器后在终端或日志中看到缺包错误，需要在 ML 后端的requirements.txt中补充相应依赖。
ML 后端无法访问任务
由于 ML 后端与 Label Studio 是两个不同服务，你所标注的资源（图片、音频等）必须托管在 ML 后端可以通过 URL 访问的地方，否则 ML 后端无法基于这些资源生成预测。
添加 ML 后端时出现校验错误
添加 ML 后端 URL 到项目时如果出现校验错误，检查以下几点：
标注界面是否配置了合法有效的标注配置？
ML 后端是否在运行？执行健康检查：
curl -X GET http://localhost:9090/healthML 后端是否对 Label Studio 实例可达？它必须能被运行 Label Studio 的实例访问到。
如果 Label Studio 运行在 Docker 中，则 ML 后端必须运行在同一个 Docker 容器内，或者通过其他方式让该容器可以访问到它。可以使用docker exec在容器内执行命令，或使用docker exec -it <container_id> /bin/sh进入容器 shell。
Windows 下 Docker 报 "No such file or directory"
在 Windows 上运行docker-compose up --build时可能遇到如下错误：
exec /app/start.sh : No such file or directory exited with code 1这通常由Windows 对文本文件换行符的处理方式引起——Git 检出时把 LF 自动转换成了 CRLF，导致容器内的start.sh脚本无法执行。
Step 1：调整 Git 配置。克隆仓库前，先关闭换行符自动转换。在 Git Bash 或终端中执行：
git config --global core.autocrlf falseStep 2：重新克隆仓库。如果之前已经克隆过，需要在调整配置后重新克隆，确保换行符被正确保留：先备份工作内容并删除现有本地仓库，再重新克隆。
Step 3：构建并启动容器。进入克隆仓库中包含 Dockerfile 与docker-compose.yml的目录，依次执行：
docker-compose build docker-compose up补充说明：此方案专门针对 Windows 下自动换行转换引发的问题，其他操作系统不适用；同时注意检查项目中的.gitattributes文件（如存在），它也会影响 Git 对换行符的处理。
重置 Docker 镜像中的 pip 缓存
有时需要重置 pip 缓存以确保安装到依赖的最新版本。例如requirements.txt中以label-studio-ml @ git+https://github.com/HumanSignal/label-studio-ml-backend.git形式引用了 Label Studio ML Backend 库，当它更新后，希望 Docker 镜像直接采用最新版本，可以强制无缓存重建镜像：
docker compose build --no-cacheBad Gateway 与 Service Unavailable 错误
这些错误通常出现在同时发送多个并发请求时。注意：仓库提供的 ML 后端示例均以开发模式提供，不支持生产级的推理服务承载能力，高并发下出现网关类错误属预期现象。
ML 后端无法完成简单自动标注或看不到预测
必须确保 ML 后端能够访问你的 Label Studio 数据，否则可能遇到：
- 服务器日志中出现
no such file or directory错误； - 在 Label Studio 中加载任务时看不到预测；
- ML 后端显示已连接，但无法在任务内完成任何自动标注。
解决方法：确保已设置LABEL_STUDIO_URL与LABEL_STUDIO_API_KEY环境变量。详细说明参见 docs/source/guide/ml.md 中「允许 ML 后端访问 Label Studio 数据」一节。
排查思路总结
面对上述问题时，可以遵循一条通用排查路径：先看浏览器控制台 → 再看服务端日志 → 最后核对配置。
- 前端资源加载类问题（图片、音频、预测展示）优先看浏览器 Console 的 CORS/403 报错；
- 同步、导出、训练类问题优先看 rq worker 状态（
/django-rq页面）与服务端日志（ML 后端注意区分rq.log与uwsgi.log）； - 预标注相关的问题优先核对
from_name/to_name/标签/ID 的一致性； - 部署类问题（Docker 启动失败）优先检查换行符、依赖完整性与超时环境变量配置。
按此顺序定位，绝大多数社区版常见问题都能在数分钟内得到解决。
【免费下载链接】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），仅供参考
