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)

  1. 登录 Azure 门户,点击侧边栏Entra ID,选择应用注册,注册创建一个新的服务主体。

  2. 复制客户端ID和租户ID,点击客户端凭据添加新的Secret。


  1. 立即复制并永久保存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. 创建目录并解压代理文件。

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

  1. 安装服务 :为了安全,建议指定一个普通用户(需提前创建)来运行该服务。如果使用当前用户,请确保其权限适当。

    bash 复制代码
    # 推荐:以指定用户身份安装
    sudo ./svc.sh install [username] 
    
    # 或者,以 root 身份安装(不推荐)
    # sudo ./svc.sh install
  2. 启动服务 :

    bash 复制代码
    sudo ./svc.sh start
  3. 检查状态 :

    bash 复制代码
    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)。
相关推荐
xbzb1 天前
镜像推上云:华为云 SWR 与阿里云 ACR 的建组织、加速器、上传与公开
阿里云·华为云·云计算·镜像·acr·swr
7177772 天前
支持混合云的 DevOps 平台有哪些:Gitee、Azure DevOps、GitLab、Jenkins、JFrog 横向对比
gitee·azure·devops
Splashtop高性能远程控制软件2 天前
微软2026年11月补丁星期二解析:1094个 CVE、Outlook 零日 CVE-2026-124194 与修复优先级
microsoft·网络安全·outlook·补丁管理·漏洞管理
小南家的青蛙4 天前
微服务体系下DevOps运维岗位面试方案设计
运维·面试·职场和发展·devops
牛奶咖啡135 天前
云计算平台应用实践——云计算与云平台
云计算·云平台·云平台的三大服务模式·云计算与云平台的关系·laas paas saas·云平台的主流架构·国内外的主流云平台对比与选型
公子小六5 天前
基于.NET的Windows窗体编程之WinForms数据持久化(1)
windows·microsoft·c#·.net·winforms
Nerd(BUG版)5 天前
鸿蒙API18~26新增V2组件全解析
microsoft·华为·harmonyos
逐流人6 天前
手工建集群到全自动发布:k8s集群部署与DevOps流水线整合实战
ci/cd·云原生·kubernetes·云计算·devops
wz97546 天前
走进云计算:从硬件到云平台,读懂数字化底层基石
云计算
Kari117 天前
企业大模型RAG知识库从0到1搭建指南:腾讯云ADP+JOTO实战
人工智能·云计算·腾讯云