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

Azure DevOps 使用服务主体配置自托管代理配置指南

- [1. 概述](#1. 概述)
- [2. 在 Azure AD 中创建服务主体 (SP)](#2. 在 Azure AD 中创建服务主体 (SP))
- [3. 授予 Azure DevOps 权限](#3. 授予 Azure DevOps 权限)
- - [3.1. 组织层级：用户身份与访问级别](#3.1. 组织层级：用户身份与访问级别)
  - [3.2. 组织层级：Agent pools管理员](#3.2. 组织层级：Agent pools管理员)
  - [3.3. 在 Linux VM 上安装和配置代理](#3.3. 在 Linux VM 上安装和配置代理)
  - [3.4. 启动并设置为系统服务](#3.4. 启动并设置为系统服务)
  - [3.5. 授予 Azure 资源权限 (可选，用于部署)](#3.5. 授予 Azure 资源权限 (可选，用于部署))

版本: 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)

登录 Azure 门户，点击侧边栏Entra ID，选择应用注册，注册创建一个新的服务主体。
复制客户端ID和租户ID，点击客户端凭据添加新的Secret。

立即复制并永久保存Secret的值，往后不再出现

3. 授予 Azure DevOps 权限

3.1. 组织层级：用户身份与访问级别

进入 Azure DevOps Organization Settings -> General -> Users。
确认你的服务主体已经出现在用户列表中，添加进入，分配Project Contributor权限。
Access Level ，将其修改为 Basic 。这是它能执行有效操作的基础。

3.2. 组织层级：Agent pools管理员

回到 Organization Settings -> Pipelines -> Agent pools。
选择你要使用的代理池（例如 Default）。
进入 Security 标签页。
点击 Add +，搜索并添加你的 SP，并授予其 Administrator 角色。
- 目的：这是我们最关键一步。授予代理程序本身注册、连接和管理自己的权限。

打开Third-party application access via OAuth，它控制了是否允许 OAuth 授权的 AAD 应用（包括你创建的 Service Principal）访问 Azure DevOps API

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

在Project层级或者组织层级，选择Agent Pool，添加New Agent，点击Download下载vsts-agent-linux-x64-4.258.1.tar.gz包，传输到Linux主机上
创建目录并解压代理文件。

bash 复制代码

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

跟随以下步骤输入

bash 复制代码

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. 启动并设置为系统服务

安装服务 ：为了安全，建议指定一个普通用户（需提前创建）来运行该服务。如果使用当前用户，请确保其权限适当。
bash 复制代码
```
# 推荐：以指定用户身份安装
sudo ./svc.sh install [username] 

# 或者，以 root 身份安装（不推荐）
# sudo ./svc.sh install
```
启动服务 ：
bash 复制代码
```
sudo ./svc.sh start
```
检查状态 ：
bash 复制代码
```
sudo ./svc.sh status
```
此时，回到 DevOps 界面，代理状态应为绿色的 Online 。

3.5. 授予 Azure 资源权限 (可选，用于部署)

如果你的流水线需要部署 Azure 资源，请确保 SP 拥有对应资源的 IAM 权限。

在 Azure 门户中，导航到具体的目标资源（如 App Service, 虚拟机）。
进入 Access control (IAM)。
点击 Add role assignment，将你的 SP 添加到具有最小必要权限的角色中（如 Website Contributor）。