Azure DevOps 使用服务主体配置自托管代理 (Self-hosted Agent) 配置指南

1. 概述

本文档旨在提供一个安全、可靠且可重复的详细步骤，指导如何在 Linux 环境下，使用服务主体 (Service Principal) 作为身份验证方式，成功配置和运行一个 Azure DevOps 自托管代理。

好对于在生产环境或任何需要高安全性的自动化场景中，最佳实践是使用服务主体 (Service Principal, SP)。

服务主体 (SP) 是 Azure 中一个独立的、非人类的身份标识，专为应用程序、服务或自动化工具（比如我们的 self-hosted agent）设计。

• 适用场景:
  • 生产环境部署: 这是绝对的首选。当你的代理需要访问 Azure 资源（例如部署到虚拟机、应用服务或管理资源）时，使用 SP 可以实现最小权限原则。
  • 自动化脚本/无人值守环境: 任何不需要人工干预的场景，SP 都是最理想的选择，因为它不需要用户账户的生命周期管理。
  • 需要精细化权限控制: 你可以为一个 SP 分配一个非常具体且权限受限的角色 (Role)，比如只允许它对某个特定资源组有“参与者(Contributor)”权限。

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) > sp

Enter 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 agent

Testing 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）。