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

1. 背景

2. 问题现象

3. 排查步骤

3.1 确认文件是否存在

3.2 检查环境变量配置

4. 解决方案

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

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

5. 最终解决

6. 总结

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/... 可直接访问，标注页面图片正常显示。