目錄
使用 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/... 可直接訪問，標注頁面圖片正常顯示。
6. 總結
問題原因：
-
LABEL_STUDIO_LOCAL_FILES_DOCUMENT_ROOT定義了 Label Studio 允許訪問的本地文件根目錄； -
d=參數必須是該根目錄下的相對路徑； -
配置不一致會導致訪問路徑錯誤，返回 404。
解決方法：
-
要么保持環境變量為
/obs，路徑寫相對路徑； -
要么環境變量改為
/，路徑保持原始/obs/...格式。
7. 建議
-
生產環境中推薦明確設置 LOCAL_FILES_DOCUMENT_ROOT，避免隨意改動文件路徑結構；
-
如果存在多個文件根目錄，可統一掛載到
/label-studio/files下，減少混亂； -
遇到 404 問題時，優先檢查：
-
容器內文件是否存在；
-
環境變量與路徑是否匹配；
-
Sync Storage 配置是否多加或少加路徑前綴。
-
