版本: 1.0
最后更新: 2025年7月24日

1. 概述

本文檔旨在提供一個安全、可靠且可重復的詳細步驟，指導如何在 Linux 環境下，使用服務主體 (Service Principal) 作為身份驗證方式，成功配置和運行一個 Azure DevOps 自托管代理。

好對于在生產環境或任何需要高安全性的自動化場景中，最佳實踐是使用服務主體 (Service Principal, SP)。

服務主體 (SP) 是 Azure 中一個獨立的、非人類的身份標識，專為應用程序、服務或自動化工具（比如我們的 self-hosted agent）設計。

• 適用場景:
  • 生產環境部署: 這是絕對的首選。當你的代理需要訪問 Azure 資源（例如部署到虛擬機、應用服務或管理資源）時，使用 SP 可以實現最小權限原則。
  • 自動化腳本/無人值守環境: 任何不需要人工干預的場景，SP 都是最理想的選擇，因為它不需要用戶賬戶的生命周期管理。
  • 需要精細化權限控制: 你可以為一個 SP 分配一個非常具體且權限受限的角色 (Role)，比如只允許它對某個特定資源組有“參與者(Contributor)”權限。

驗證方式	核心場景	安全性	推薦指數 (生產環境)
Service Principal (SP)	生產環境、自動化、需要訪問 Azure 資源	最高	★★★★★ (強烈推薦)
Personal Access Token (PAT)	快速測試、個人項目、無云資源訪問	較低	★★☆☆☆ (不推薦用于生產)
Device code flow	交互式設置、需要 MFA 的環境	較高	★★★☆☆ (適用于手動設置階段)
Integrated (Windows)	內網域環境、與本地 AD 集成	較高	★★★★☆ (特定企業場景下推薦)

2. 在 Azure AD 中創建服務主體 (SP)

1. 登錄 Azure 門戶，點擊側邊欄Entra ID，選擇應用注冊，注冊創建一個新的服務主體。
   
   

2. 復制客戶端ID和租戶ID，點擊客戶端憑據添加新的Secret。

3. 立即復制并永久保存Secret的值，往后不再出現
   

3. 授予 Azure DevOps 權限

3.1. 組織層級：用戶身份與訪問級別

1. 進入 Azure DevOps Organization Settings -> General -> Users。
2. 確認你的 服務主體 已經出現在用戶列表中，添加進入，分配Project Contributor權限。
3. Access Level，將其修改為 Basic。這是它能執行有效操作的基礎。
   

3.2. 組織層級：Agent pools管理員

1. 回到 Organization Settings -> Pipelines -> Agent pools。
2. 選擇你要使用的代理池（例如 Default）。
3. 進入 Security 標簽頁。
4. 點擊 Add +，搜索并添加你的 SP，并授予其 Administrator 角色。
   • 目的：這是我們最關鍵一步。授予代理程序本身注冊、連接和管理自己的權限。
     

打開Third-party application access via OAuth，它控制了 是否允許 OAuth 授權的 AAD 應用（包括你創建的 Service Principal）訪問 Azure DevOps API

3.3. 在 Linux VM 上安裝和配置代理

1. 在Project層級或者組織層級，選擇Agent Pool，添加New Agent，點擊Download下載vsts-agent-linux-x64-4.258.1.tar.gz包，傳輸到Linux主機上
   

2. 創建目錄并解壓代理文件。

mkdir myagent && cd myagent
tar zxvf {your_path}/vsts-agent-linux-x64-4.258.1.tar.gz
./config.sh

---

跟隨以下步驟輸入

Enter (Y/N) Accept the Team Explorer Everywhere license agreement now? (press enter for N) > Y>> Connect:Enter server URL > https://dev.azure.com/{yourorganization}Enter authentication type (press enter for PAT) > spEnter Client(App) ID > {your_Client(App) ID}Enter Tenant ID > {your_Tenant ID}Enter Client secret > ****************************************Connecting to server ...>> Register Agent:Enter agent pool (press enter for default) >default
Enter agent name (press enter for MyProxy) >MyProxy
Scanning for tool capabilities.Connecting to the server.Successfully added the agentTesting agent connection.Enter work folder (press enter for _work) >/home/MyProxy/myagent/_work

3.4. 啟動并設置為系統服務

1. 安裝服務：為了安全，建議指定一個普通用戶（需提前創建）來運行該服務。如果使用當前用戶，請確保其權限適當。

   # 推薦：以指定用戶身份安裝
   sudo ./svc.sh install [username] # 或者，以 root 身份安裝（不推薦）
   # sudo ./svc.sh install
   

2. 啟動服務：

   sudo ./svc.sh start
   

3. 檢查狀態：

   sudo ./svc.sh status
   

   此時，回到 DevOps 界面，代理狀態應為綠色的 Online。
   

3.5. 授予 Azure 資源權限 (可選，用于部署)

如果你的流水線需要部署 Azure 資源，請確保 SP 擁有對應資源的 IAM 權限。

1. 在 Azure 門戶中，導航到具體的目標資源（如 App Service, 虛擬機）。
2. 進入 Access control (IAM)。
3. 點擊 Add role assignment，將你的 SP 添加到具有最小必要權限的角色中（如 Website Contributor）。