使用 Docker 部署 Label Studio 时本地文件无法显示的排查与解决

[使用 Docker 部署 Label Studio 时本地文件无法显示的排查与解决](#使用 Docker 部署 Label Studio 时本地文件无法显示的排查与解决)

[1. 背景](#1. 背景)

[2. 问题现象](#2. 问题现象)

[3. 排查步骤](#3. 排查步骤)

[3.1 确认文件是否存在](#3.1 确认文件是否存在)

[3.2 检查环境变量配置](#3.2 检查环境变量配置)

[4. 解决方案](#4. 解决方案)

[方法一：修改 Sync Storage 路径（相对路径）](#方法一：修改 Sync Storage 路径（相对路径）)

[方法二：修改环境变量为 /](#方法二：修改环境变量为 /)

[5. 最终解决](#5. 最终解决)

[6. 总结](#6. 总结)

[7. 建议](#7. 建议)

使用 Docker 部署 Label Studio 时本地文件无法显示的排查与解决

1. 背景

在生产环境中，我们常使用 Docker 部署 Label Studio 来进行数据标注。标注文件通常存储在一个挂载目录中，例如 /obs，并通过 同步存储（Sync Storage） 功能导入到项目中。

但在配置过程中遇到一个常见问题：图片无法显示，日志中报 404 错误。

2. 问题现象

启动容器后访问项目页面，标注图片无法正常加载，日志出现以下报错：

复制代码

[WARNING] Not Found: /data/local-files/
"GET /data/local-files/?d=obs/fish/%E5%9B%8A%E8%82%BF%E7%89%99%E9%B2%86%E9%B1%BC/img/1927190418391302144_20250527102953_1-1.jpg HTTP/1.1" 404 0

可以看到请求路径是：

复制代码

/data/local-files/?d=obs/fish/囊肿牙鲆鱼/img/xxx.jpg

但返回了 404。

3. 排查步骤

3.1 确认文件是否存在

进入容器查看文件是否挂载成功：

复制代码

docker exec -it label-studio bash
ls /obs/fish/囊肿牙鲆鱼/img/

文件存在，说明挂载没问题。

3.2 检查环境变量配置

启动脚本中配置了：

复制代码

--env LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT=/obs

意味着 Label Studio 期望所有访问路径是相对于 /obs 的，例如：

复制代码

/fish/囊肿牙鲆鱼/img/xxx.jpg

但实际 Sync Storage 路径是：

复制代码

/obs/fish/囊肿牙鲆鱼/img/xxx.jpg

导致系统拼接后路径错误，变成：

复制代码

/obs/obs/fish/囊肿牙鲆鱼/img/xxx.jpg

自然找不到文件。

4. 解决方案

方法一：修改 Sync Storage 路径（相对路径）

保持 LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT=/obs 不变，将路径改为相对路径：

复制代码

/fish/囊肿牙鲆鱼/img/xxx.jpg

这样拼接后路径正确。

方法二：修改环境变量为 `/`

如果无法调整 Sync Storage 路径格式，可以直接让 Label Studio 以 / 作为本地文件根目录：

复制代码

--env LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT=/

这样 d=obs/fish/... 会直接解析为 /obs/fish/...，无需改 Sync Storage 配置。

5. 最终解决

本案例中选择了方法二 ，即将环境变量改为 /：

复制代码

docker run -d \
    --name label-studio \
    -p 9002:8080 \
    -v /data1/apps/label-studio/data:/label-studio/data \
    -v /data1/apps/label-studio/files:/label-studio/files \
    -v /obs:/obs \
    --env LABEL_STUDIO_LOCAL_FILES_SERVING_ENABLED=true \
    --env LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT=/ \
    heartexlabs/label-studio:latest

修改后，图片路径 /obs/fish/... 可直接访问，标注页面图片正常显示。

6. 总结

问题原因：

LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT 定义了 Label Studio 允许访问的本地文件根目录；
d= 参数必须是该根目录下的相对路径；
配置不一致会导致访问路径错误，返回 404。

解决方法：

要么保持环境变量为 /obs，路径写相对路径；
要么环境变量改为 /，路径保持原始 /obs/... 格式。

7. 建议

生产环境中推荐明确设置 LOCAL_FILES_DOCUMENT_ROOT，避免随意改动文件路径结构；
如果存在多个文件根目录，可统一挂载到 /label-studio/files 下，减少混乱；
遇到 404 问题时，优先检查：
1. 容器内文件是否存在；
2. 环境变量与路径是否匹配；
3. Sync Storage 配置是否多加或少加路径前缀。