# Label Studio 初體驗：從安裝到自動啟動的實戰教學

**作者：** LHB阿好伯 [:earth_africa:](https://www.facebook.com/LHB0222/)

**日期：** 2025年9月5日

---

## 📚 文章目錄

[TOC]

---

## 前言

在這個 AI 標註工具盛行的時代，**Label Studio** 作為開源界的佼佼者
提供了直觀易用的資料標註介面。但在 Ubuntu 24.04 上安裝時
我們可能會遇到一些「靈異事件」，今天就來分享完整的安裝與設定流程！

> **💡 重點提示：** 本教學適用於 Ubuntu 24.04 LTS，其他版本可能會有些許差異。

---

## 環境準備

### 系統資訊確認

首先，讓我們確認系統環境：

# 檢查 Ubuntu 版本
lsb_release -a

# 檢查 Python 版本
python3 --version

# 更新系統套件
sudo apt update && sudo apt upgrade -y

### GPU 環境檢查（可選）

如果您的系統有 GPU，可以先確認驅動狀態：

# 檢查 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 安裝：

pip install label-studio

**結果出現錯誤：**

error: externally-managed-environment
× This environment is externally managed

這個錯誤是 Ubuntu 24.04 的新「保護機制」，為了避免破壞系統 Python 環境。

### 正確安裝方法：使用 pipx

**pipx** 是專門用來安裝 Python 應用程式的工具，會自動建立獨立的虛擬環境：

# 1. 安裝 pipx
sudo apt update
sudo apt install pipx

# 2. 設定 pipx 路徑
pipx ensurepath

# 3. 重新載入環境變數
source ~/.bashrc

# 4. 安裝 Label Studio
pipx install label-studio

### 驗證安裝成功

# 檢查可執行檔位置
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 使用者安裝 |

### 替代安裝方法

**方法一：虛擬環境**

# 建立虛擬環境
python3 -m venv ~/label-studio-env

# 啟動環境
source ~/label-studio-env/bin/activate

# 安裝 Label Studio
pip install label-studio

# 使用完畢後退出
deactivate

**方法二：Docker 安裝**

# 使用 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 介面
- 各種開發伺服器

### 端口修改方法

**基本用法：**

# 修改為 8081 端口
label-studio start --port 8081

# 允許外部存取
label-studio start --port 8081 --host 0.0.0.0

**進階參數：**

# 完整參數示例
label-studio start \
  --port 8081 \
  --host 0.0.0.0 \
  --data-dir ./my_data \
  --debug

### 檢查端口可用性

# 檢查端口是否被佔用
netstat -tlnp | grep :8081
ss -tlnp | grep :8081

# 使用 lsof 檢查
sudo lsof -i :8081

---

## 設定開機自啟動

### 使用 systemd 服務（推薦）

**步驟一：建立服務檔案**

sudo nano /etc/systemd/system/label-studio.service

**服務設定內容：**

[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

**步驟二：啟用服務**

# 重新載入 systemd 設定
sudo systemctl daemon-reload

# 啟用開機自啟動
sudo systemctl enable label-studio.service

# 立即啟動服務
sudo systemctl start label-studio.service

# 檢查服務狀態
sudo systemctl status label-studio.service

### 進階配置選項

**環境變數設定檔：**

# 建立環境變數檔案
sudo nano /etc/default/label-studio

# 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

**修改後的服務檔案：**

[Service]
EnvironmentFile=/etc/default/label-studio
ExecStart=/home/huanyu/.local/bin/label-studio start --port ${LABEL_STUDIO_PORT} --host ${LABEL_STUDIO_HOST}

---

## 服務管理與監控

### 基本管理命令

# 啟動服務
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

### 日誌監控

# 查看最新日誌
sudo journalctl -u label-studio -n 50

# 即時監控日誌
sudo journalctl -u label-studio -f

# 查看錯誤日誌
sudo journalctl -u label-studio -p err

### 性能監控腳本

建立監控腳本 `monitor-labelstudio.sh`：

#!/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)"

### 健康檢查

# 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

### 🔧 故障排除快速指令

# 一鍵診斷腳本
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阿好伯 原創撰寫，歡迎轉載但請註明出處。如有技術問題歡迎留言討論！