# Label Studio 初體驗：從安裝到自動啟動的實戰教學 **作者：** LHB阿好伯 [:earth_africa:](https://www.facebook.com/LHB0222/) **日期：** 2025年9月5日 --- ## 📚 文章目錄 [TOC] --- ## 前言 在這個 AI 標註工具盛行的時代，**Label Studio** 作為開源界的佼佼者 提供了直觀易用的資料標註介面。但在 Ubuntu 24.04 上安裝時 我們可能會遇到一些「靈異事件」，今天就來分享完整的安裝與設定流程！ > **💡 重點提示：** 本教學適用於 Ubuntu 24.04 LTS，其他版本可能會有些許差異。 --- ## 環境準備 ### 系統資訊確認 首先，讓我們確認系統環境： ```bash # 檢查 Ubuntu 版本 lsb_release -a # 檢查 Python 版本 python3 --version # 更新系統套件 sudo apt update && sudo apt upgrade -y ``` ### GPU 環境檢查（可選） 如果您的系統有 GPU，可以先確認驅動狀態： ```bash # 檢查 NVIDIA GPU nvidia-smi # 檢查 PCI 設備 lspci | grep -i vga ``` **我的環境配置：** - Ubuntu 24.04 LTS (在 Proxmox VE 虛擬機中運行) - NVIDIA GeForce RTX 5070 (GPU 直通) - Python 3.12.3 --- ## 安裝 Label Studio ### 第一次安裝嘗試（踩坑實錄） 一開始，我天真地以為可以直接用 pip 安裝： ```bash pip install label-studio ``` **結果出現錯誤：** ``` error: externally-managed-environment × This environment is externally managed ``` 這個錯誤是 Ubuntu 24.04 的新「保護機制」，為了避免破壞系統 Python 環境。 ### 正確安裝方法：使用 pipx **pipx** 是專門用來安裝 Python 應用程式的工具，會自動建立獨立的虛擬環境： ```bash # 1. 安裝 pipx sudo apt update sudo apt install pipx # 2. 設定 pipx 路徑 pipx ensurepath # 3. 重新載入環境變數 source ~/.bashrc # 4. 安裝 Label Studio pipx install label-studio ``` ### 驗證安裝成功 ```bash # 檢查可執行檔位置 which label-studio # 輸出：/home/huanyu/.local/bin/label-studio # 檢查 pipx 安裝的套件 pipx list # 輸出：package label-studio 1.20.0, installed using Python 3.12.3 ``` --- ## 解決安裝問題 ### 常見問題與解決方案 | 問題 | 原因 | 解決方法 | |------|------|----------| | `externally-managed-environment` | Ubuntu 24.04 保護機制 | 使用 `pipx` 或虛擬環境 | | `command not found` | PATH 未正確設定 | 執行 `pipx ensurepath` | | 權限錯誤 | 嘗試寫入系統目錄 | 使用非 root 使用者安裝 | ### 替代安裝方法 **方法一：虛擬環境** ```bash # 建立虛擬環境 python3 -m venv ~/label-studio-env # 啟動環境 source ~/label-studio-env/bin/activate # 安裝 Label Studio pip install label-studio # 使用完畢後退出 deactivate ``` **方法二：Docker 安裝** ```bash # 使用 Docker 運行 docker run -d --name label-studio \ --restart unless-stopped \ -p 8081:8080 \ -v ~/label-studio-data:/label-studio/data \ heartexlabs/label-studio:latest ``` --- ## 自訂端口啟動 ### 為什麼要更改端口？ 預設的 **8080** 端口經常被其他服務佔用，例如： - Apache Tomcat - Jenkins - Proxmox VE Web 介面 - 各種開發伺服器 ### 端口修改方法 **基本用法：** ```bash # 修改為 8081 端口 label-studio start --port 8081 # 允許外部存取 label-studio start --port 8081 --host 0.0.0.0 ``` **進階參數：** ```bash # 完整參數示例 label-studio start \ --port 8081 \ --host 0.0.0.0 \ --data-dir ./my_data \ --debug ``` ### 檢查端口可用性 ```bash # 檢查端口是否被佔用 netstat -tlnp | grep :8081 ss -tlnp | grep :8081 # 使用 lsof 檢查 sudo lsof -i :8081 ``` --- ## 設定開機自啟動 ### 使用 systemd 服務（推薦） **步驟一：建立服務檔案** ```bash sudo nano /etc/systemd/system/label-studio.service ``` **服務設定內容：** ```ini [Unit] Description=Label Studio Annotation Tool After=network.target [Service] Type=simple User=huanyu Group=huanyu WorkingDirectory=/home/huanyu Environment=PATH=/home/huanyu/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin ExecStart=/home/huanyu/.local/bin/label-studio start --port 8081 --host 0.0.0.0 Restart=always RestartSec=10 [Install] WantedBy=multi-user.target ``` **步驟二：啟用服務** ```bash # 重新載入 systemd 設定 sudo systemctl daemon-reload # 啟用開機自啟動 sudo systemctl enable label-studio.service # 立即啟動服務 sudo systemctl start label-studio.service # 檢查服務狀態 sudo systemctl status label-studio.service ``` ### 進階配置選項 **環境變數設定檔：** ```bash # 建立環境變數檔案 sudo nano /etc/default/label-studio ``` ```bash # Label Studio 環境變數 LABEL_STUDIO_PORT=8081 LABEL_STUDIO_HOST=0.0.0.0 LABEL_STUDIO_DATA_DIR=/home/huanyu/label-studio-data LABEL_STUDIO_LOG_LEVEL=INFO ``` **修改後的服務檔案：** ```ini [Service] EnvironmentFile=/etc/default/label-studio ExecStart=/home/huanyu/.local/bin/label-studio start --port ${LABEL_STUDIO_PORT} --host ${LABEL_STUDIO_HOST} ``` --- ## 服務管理與監控 ### 基本管理命令 ```bash # 啟動服務 sudo systemctl start label-studio # 停止服務 sudo systemctl stop label-studio # 重啟服務 sudo systemctl restart label-studio # 檢查狀態 sudo systemctl status label-studio # 禁用開機自啟動 sudo systemctl disable label-studio ``` ### 日誌監控 ```bash # 查看最新日誌 sudo journalctl -u label-studio -n 50 # 即時監控日誌 sudo journalctl -u label-studio -f # 查看錯誤日誌 sudo journalctl -u label-studio -p err ``` ### 性能監控腳本 建立監控腳本 `monitor-labelstudio.sh`： ```bash #!/bin/bash echo "=== Label Studio 服務監控 ===" echo "服務狀態：$(systemctl is-active label-studio)" echo "開機自啟：$(systemctl is-enabled label-studio)" echo "端口監聽：$(ss -tlnp | grep :8081 | wc -l) 個" echo "記憶體使用：$(ps aux | grep label-studio | grep -v grep | awk '{sum+=$6} END {print sum/1024 "MB"}')" echo "CPU 使用率：$(ps aux | grep label-studio | grep -v grep | awk '{sum+=$3} END {print sum"%"}')" echo "最後重啟：$(systemctl show label-studio -p ActiveEnterTimestamp --value)" ``` ### 健康檢查 ```bash # HTTP 健康檢查 curl -f http://localhost:8081/health/ || echo "服務異常" # 端口檢查 if netstat -tlnp | grep -q :8081; then echo "✅ Port 8081 正常監聽" else echo "❌ Port 8081 未開啟" fi ``` --- ## 總結 ### 🎉 完成檢查清單 - [x] **環境準備**：確認 Ubuntu 24.04 + Python 3.12 - [x] **安裝 Label Studio**：使用 pipx 避免環境衝突 - [x] **自訂端口**：修改為 8081 避免衝突 - [x] **開機自啟動**：建立 systemd 服務 - [x] **服務監控**：設定日誌和健康檢查 ### 📊 最終配置總覽 ``` Label Studio 服務架構 ├── 安裝位置: /home/huanyu/.local/bin/label-studio ├── 服務檔案: /etc/systemd/system/label-studio.service ├── 設定檔案: /etc/default/label-studio ├── 資料目錄: ~/label-studio-data/ └── 存取網址: http://localhost:8081 ``` ### 🔧 故障排除快速指令 ```bash # 一鍵診斷腳本 echo "=== 快速診斷 ===" systemctl status label-studio --no-pager -l ss -tlnp | grep :8081 curl -s http://localhost:8081 > /dev/null && echo "✅ Web 介面正常" || echo "❌ Web 介面異常" ``` ### 🚀 下一步建議 1. **資料備份**：定期備份 `~/label-studio-data/` 目錄 2. **SSL 設定**：生產環境建議設定 HTTPS 3. **使用者管理**：設定多使用者存取權限 4. **資料庫優化**：大量資料時考慮外部資料庫 --- ## [YOLOv8初體驗_環境安裝及基本教學_特定物品影像辨識_以煙囪排放黑白煙為例](/-9V14_oeTwmE0iInsZZtXA) ## 📢 分享與討論 如果這篇教學對您有幫助，歡迎： - 👍 點讚支持 - 💬 留言分享您的安裝經驗 - 🔄 分享給需要的朋友 - 📝 提出改進建議 --- > **版權聲明：** 本文章由 LHB阿好伯 原創撰寫，歡迎轉載但請註明出處。如有技術問題歡迎留言討論！ ![image](https://hackmd.io/_uploads/BJ1yrnDcgx.png)