Appearance
Azure Pipelines Self-Hosted Agent — Ubuntu 安裝與服務設定
Azure DevOps Self-Hosted Agent 在 Ubuntu 上安裝、向 ADO 組織註冊，並透過
svc.sh設為 systemd 開機常駐服務的完整 SOP。
概述
Azure Pipelines 的 Agent 分為 Microsoft-hosted（雲端代管）與 Self-Hosted（自行維護）兩類。Self-Hosted Agent 讓 Pipeline 能存取內部網路資源（私有 K8s 叢集、內部 Container Registry 等），也可預先安裝所需工具（kubectl、helm、az CLI）避免每次 Pipeline 重複安裝。
安裝流程分三個階段：下載並解壓 Agent tarball → 執行 config.sh 向 Azure DevOps 組織完成註冊（此步驟會產生 svc.sh）→ 透過 svc.sh 將 Agent 安裝為 systemd service，確保開機自動啟動、常駐背景執行。
理解各腳本的職責分工是操作此流程的關鍵：config.sh 是一次性的註冊工具，svc.sh 管理 systemd service 的生命週期，runsvc.sh 才是 systemd 實際呼叫的啟動腳本（由 svc.sh install 自動建立）。
核心內容
目錄結構的兩個狀態
Agent 解壓後只有 config.sh、run.sh 等基本檔案；svc.sh 必須在執行 config.sh 完成註冊後才會自動產生。若在 config 完成前找不到 svc.sh，是正常現象而非錯誤。
| 狀態 | 目錄內容 |
|---|---|
config 前 | bin config.sh env.sh externals license.html reauth.sh run-docker.sh run.sh |
config 後 | 同上 + _diag/ svc.sh |
各腳本職責
| 腳本 | 用途 | 備註 |
|---|---|---|
config.sh | 向 ADO 組織註冊 Agent，產生 svc.sh | 僅需執行一次 |
run.sh | 前景執行（測試用） | Terminal 關閉即停止 |
run-docker.sh | Docker 容器模式執行 | 容器環境適用 |
svc.sh | 管理 systemd service（install / start / stop / uninstall） | config 後產生 |
runsvc.sh | systemd 實際呼叫的啟動腳本 | 由 svc.sh install 建立 |
runsvc.sh 的啟動邏輯
runsvc.sh 本身不含開機自啟邏輯，僅執行三件事：
- 從
.path檔載入PATH環境變數 - 偵測 Node 版本（優先 node20，fallback node16）
- 執行
AgentService.js
開機自啟的設定完全由 svc.sh install 在 systemd 層面完成。
服務命名規則
systemd service 的命名格式為：
vsts.agent.<Org>.<Pool>.<AgentName>.service例如：vsts.agent.DigitalInnovationDevDiv.Default.master2.service
特殊字元（如 -）在 systemd unit 名稱中會以 \x2d 表示，查詢時需注意。
關鍵要點
svc.sh是config.sh完成後自動產生的，執行前不存在sudo ./svc.sh install同時完成「建立 service file」與「設為 enabled」兩件事run.sh是前景測試工具，不適合正式環境；正式環境必須用svc.shsystemctl is-enabled可確認服務是否已設定開機自啟- 無
svc.sh的情況下需手動撰寫/etc/systemd/system/*.service檔
實際應用
典型使用情境：在公司內部伺服器（Ubuntu VM 或裸機）上常駐一個或多個 Self-Hosted Agent，讓 Azure DevOps Pipeline 能透過它存取私有 K8s 叢集（AKS Private Cluster 或內網 K8s）、內部 Container Registry，以及公司網路內的資料庫或其他服務。
若同一台 Server 上同時跑多個 Pipeline，建議搭配 Azure Pipeline — Kubeconfig 隔離最佳實踐 避免 kubeconfig 競態問題。
部署設定參考
以下為完整安裝流程指令，供日後查詢與複製使用。
安裝流程
bash
# Step 1: 下載並解壓 Agent
mkdir ~/devops-agent && cd ~/devops-agent
tar zxvf vsts-agent-linux-x64-*.tar.gz
# Step 2: 向 ADO 組織註冊（依提示輸入 URL、PAT Token、Pool 名稱、Agent 名稱）
./config.sh
# Step 3: 安裝為 systemd 開機服務
sudo ./svc.sh install
sudo ./svc.sh start
sudo ./svc.sh statusconfig.sh 需要輸入的資訊
| 項目 | 說明 |
|---|---|
| Azure DevOps URL | 例如 https://dev.azure.com/YourOrg |
| PAT Token | Personal Access Token，需有 Agent Pools (read, manage) 權限 |
| Agent Pool 名稱 | 預設為 Default |
| Agent 名稱 | 辨識用，可自訂 |
svc.sh 常用指令
bash
sudo ./svc.sh install # 註冊 systemd service 並設定 enabled
sudo ./svc.sh start # 啟動服務
sudo ./svc.sh stop # 停止服務
sudo ./svc.sh status # 查看服務狀態
sudo ./svc.sh uninstall # 移除開機服務（不刪除 agent 本身）服務狀態檢測指令
bash
# 確認服務是否運行中
systemctl list-units --all | grep -i "Azure Pipelines Agent"
# 確認服務是否設為開機自啟
systemctl is-enabled "vsts.agent.<Org>.<Pool>.<AgentName>.service"
# 全面掃描開機啟動設定
echo "=== systemd ===" && systemctl list-unit-files | grep -i devops
echo "=== systemd files ===" && find /etc/systemd/system/ /lib/systemd/system/ -name "*devops*" 2>/dev/null
echo "=== crontab (user) ===" && crontab -l 2>/dev/null | grep -i devops
echo "=== crontab (root) ===" && sudo crontab -l 2>/dev/null | grep -i devops
echo "=== rc.local ===" && grep -i devops /etc/rc.local 2>/dev/null服務正常狀態判讀
systemctl list-units 應顯示：
| 欄位 | 值 | 說明 |
|---|---|---|
LOAD | loaded | unit 檔已載入 |
ACTIVE | active | 服務已啟動 |
SUB | running | 程序正在執行中 |
is-enabled | enabled | 開機會自動啟動 |
開機自啟常見設定位置
| 機制 | 位置 | 檢查指令 |
|---|---|---|
| systemd service | /etc/systemd/system/ | systemctl list-unit-files | grep <name> |
| crontab @reboot | 使用者 crontab | crontab -l |
| crontab @reboot | root crontab | sudo crontab -l |
| rc.local | /etc/rc.local | cat /etc/rc.local |
相關概念
- Azure DevOps Pipeline CI/CD 設定指南 — 使用 Self-Hosted Agent 的 Pipeline YAML 完整設定
- Azure Pipeline — Kubeconfig 隔離最佳實踐 — 多 Pipeline 並行時 kubeconfig 的正確隔離方式