版本: 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）。