共用方式為


Microsoft 託管的代理程式

Azure DevOps Services

Microsoft裝載的代理程式僅適用於裝載於雲端的 Azure DevOps Services。 您無法將 Microsoft 託管的代理程式或 Azure Pipelines 代理程式集區與內部部署的 TFS 或 Azure DevOps Server 搭配使用。 使用這些內部部署版本,您必須使用 自我裝載的代理程式。

重要

從 Azure DevOps 內容版本選取器選取版本。

選取對應至您平臺和版本的本文版本。 版本選取器位於目錄上方。 查閱您的 Azure DevOps 平臺和版本

如果您的管線位於 Azure Pipelines 中,您可以使用Microsoft裝載的代理程式,輕鬆地執行作業。 使用 Microsoft 託管的代理程式,就不需要自己維護和升級。 您在流程中指定的 VM 映像,會一律取得最新版本。 每次執行管線時,你會為管線中的每個作業獲得全新的虛擬機器。 虛擬機器在一個作業完成後會被丟棄,這表示作業對虛擬機器檔案系統所做的任何變更,例如簽出程式碼,將無法在下一個作業中使用。 Microsoft裝載的代理程式可以直接在 VM容器上執行作業。

Azure Pipelines 提供預先定義的代理程式集區 (名為 Azure Pipelines) 搭配 Microsoft 裝載的代理程式。

對於許多小組來說,這是執行作業的最簡單方式。 您可以先試用,看看這是否適用於您的組建或部署。 如果沒有,您可以使用 規模設置代理程式 或自託管代理程式。

提示

您可以免費試用Microsoft裝載的代理程式。

軟體

Azure Pipelines 代理集區提供多個虛擬機器映像以供選擇,每個映像都內含多種工具和軟體。

圖片 傳統編輯器代理程序規格 YAML VM 映像標籤 包含的軟體
Windows Server 2025 搭配 Visual Studio 2022 (預覽版) windows-2025 windows-2025 連結
Windows Server 2022 與 Visual Studio 2022 windows-2022 windows-latestwindows-2022 連結
Windows Server 2019 搭配 Visual Studio 2019 windows-2019 windows-2019 連結
Ubuntu 24.04 ubuntu-24.04 ubuntu-24.04 連結
Ubuntu 22.04 ubuntu-22.04 ubuntu-latestubuntu-22.04 連結
Ubuntu 20.04 ubuntu-20.04 ubuntu-20.04 連結
macOS 15 Sequoia (預覽) macOS-15 macOS-15 連結
macOS 14 Sonoma macOS-14 macOS-latestmacOS-14 連結
macOS 13 Ventura macOS-13 macOS-13 連結

傳統組建管線的預設代理程式映射為 windows-2019,而 YAML 組建管線的預設代理程式映像為 ubuntu-latest。 如需詳細資訊,請參閱 在管線中指定集區。

您可以選擇資料表中的 [包含的軟體] 連結,以查看每個託管代理程式的 已安裝軟體 。 使用macOS映射時,您可以從工具版本手動選取。 閱讀更多內容

最近的更新

建議客戶移轉至較新版本或 自我裝載的代理程式

如需有關如何更新使用這些映像之管線的詳細資訊和指示,請參閱 在 Azure Pipelines 託管的集區中移除較舊的映像

注意

Azure Pipelines 提供的託管集區取代了之前有名稱對應映像的託管集區。 您在先前託管集區中的任何任務都會自動重新導向到新 Azure Pipelines 託管集區中的正確映像。 在某些情況下,您可能仍會看到舊的集區名稱,但實際上這些作業是在幕後使用 Azure Pipelines 集區執行的。 如需此更新的詳細資訊,請參閱 2019 年 7 月 1 日 Sprint 154 版本資訊中的 單一託管池 發行說明。

重要

若要要求在 Microsoft 代管的代理程式上安裝其他軟體,請勿在此檔案上提供意見反應,也不要開啟支援票證。 相反,請在我們管理指令碼以產生各種映像的存放庫上提出問題。

如何使用已被取代的託管映像來識別管線

若要識別使用已取代映像檔的管線,請瀏覽至您組織中的下列位置:https://dev.azure.com/{organization}/{project}/_settings/agentqueues,並篩選映像檔名稱以檢查。 下列範例會檢查 vs2017-win2016 影像。

依影像名稱篩選管線的螢幕快照。

您也可以使用位於此處的腳本來查詢不同專案中已淘汰映像檔的作業歷程記錄,如下列範例所示。

./QueryJobHistoryForRetiredImages.ps1 -accountUrl https://dev.azure.com/{org} -pat {pat}

使用Microsoft裝載的代理程式

在 YAML 管線中,如果您未指定集區,管線預設為 Azure Pipelines 代理程式集區。 您只需要指定要使用的虛擬機映像。

jobs:
- job: Linux
  pool:
    vmImage: 'ubuntu-latest'
  steps:
  - script: echo hello from Linux
- job: macOS
  pool:
    vmImage: 'macOS-latest'
  steps:
  - script: echo hello from macOS
- job: Windows
  pool:
    vmImage: 'windows-latest'
  steps:
  - script: echo hello from Windows

注意

集區的設定可以在 YAML 檔案中的多個層級進行。 如果您注意到管線未在預期的映射上執行,請確定您在管線、階段和作業層級驗證集區規格。

避免硬編碼引用

當您使用Microsoft裝載的代理程式時,請一律使用 變數 來參考組建環境和代理程序資源。 例如,不要對存放庫所在的驅動器號或資料夾進行硬性編碼。 託管代理程式的精確版面配置可能會變更,而不會發出警告。

硬體

在具有雙核心 CPU、7 GB RAM 和 14 GB SSD 磁碟空間的 Azure 通用虛擬機器上,佈建有執行 Windows 和 Linux 映像的 Microsoft 裝載的代理程式。 這些虛擬機器位於 Azure DevOps 組織所在的地理位置。

執行 macOS 映像的代理程式在佈建 3 核心 CPU、14 GB RAM 和 14 GB SSD 磁碟空間的 Mac 專業版上進行設定。 無論 Azure DevOps 組織位於何處,這些代理程式一律在美國執行。 如果資料主權對您很重要,而且您的組織不在美國,則您不應該使用 macOS 映像。 深入了解

所有這些機器都有至少 10 GB 的可用磁碟空間,以供流程運行。 當您的管線簽出原始程式碼、下載套件、提取 Docker 映像檔案或產生中繼檔案時,這些操作會消耗可用的空間。

重要

我們無法接受增大 Microsoft 裝載的代理程式之磁碟空間,或佈建更強大的機器的要求。 如果 Microsoft 裝載代理程式的規格不符合您的需求,則您應該考慮 自我託管代理程式規模設定代理程式管理式 DevOps 資源池

網路

在某些設定中,您可能需要知道部署代理程式的 IP 位址範圍。 例如,如果需要透過防火牆授與裝載的代理程式的存取權,可以依 IP 位址限制該存取權。 因為 Azure DevOps 使用 Azure 全域網路,因此 IP 範圍會隨時間而變化。 Microsoft發佈 每周 JSON 檔案 ,列出 Azure 數據中心的IP範圍,依區域細分。 此檔案每週更新一次,並包含新計劃的 IP 範圍。 只有最新版本的檔案可供下載。 如果需要舊版,必須在每週檔案發佈時及時下載並封存。 新的 IP 範圍會在隔週生效。 我們建議您經常檢查 (每週至少一次),以確保清單為最新。 如果代理程式作業開始失敗,第一個疑難排解步驟是確定您的設定符合最新的 IP 位址清單。 託管代理程式的 IP 位址範圍列在每週的檔案中,如 AzureCloud.<region>。例如,美國西部區域的 IP 位址範圍檔案為 AzureCloud.westus

裝載的代理程式在組織所在的 Azure 地理位置中執行。 每個地理位置包含一個或多個區域。 雖然代理程式可能會在組織所在的區域執行,但並不保證情況一定如此。 若要取得代理程式之可能的 IP 範圍完整清單,必須使用您所在地理位置所包含之所有區域的 IP 範圍。 例如,如果您的組織位於 美國 地理位置,則必須使用該地理位置中所有區域的IP範圍。

若要判斷地理位置,請流覽至 https://dev.azure.com/<your_organization>/_settings/organizationOverview,取得您的區域,並從 Azure geography 數據表尋找相關聯的地理位置。 識別地理位置之後,請針對該地理位置中的所有區域,使用每周檔案中的IP範圍

重要

您無法使用 ExpressRoute 或 VPN 之類的私人連線,將Microsoft裝載的代理程式連線到公司網路。 Microsoft 裝載的代理程式與伺服器之間的流量會流經公用網路。

辨識由 Microsoft 托管的代理程式的可能的 IP 範圍

  1. 在 [組織設定] 中識別您組織的區域。
  2. 識別您組織區域的 Azure 地理位置
  3. 將您地理位置中區域的名稱對應至每周檔案中使用的格式,參照AzureCloud.<region>的格式,如AzureCloud.westus。 您可以參考 Azure Geography 清單來將區域名稱對應至每周檔案使用的格式,方法是檢閱位於 適用於 .NET 的 Azure 管理程式庫中的 Region 類別原始碼中,傳遞至建構函式的區域名稱。

    注意

    由於 Azure 管理連結庫 for .NET沒有 API 可列出地理位置的區域,因此您必須手動列出它們,如下列範例所示。

  4. 每周檔案擷取地理位置中所有區域的IP位址。 如果您的區域是 巴西南部西歐,您必須根據後援地理位置包含其他IP範圍,如下列注意事項所述。

注意

由於容量限制,巴西南部西歐地區的某些組織可能會偶爾看到他們的託管代理位於預期的地理區域之外。 在這些情況下,除了包含您所在地理位置中所有區域的 IP 範圍(如上一節所述)之外,還必須納入容量備援地理位置中的區域的其他 IP 範圍。

如果您的組織位於巴西南部區域,您的容量後援地理位置會 美國

如果您的組織位於 西歐 區域,則容量後援地理位置為 法國

我們的 Mac IP 範圍不會包含在上述 Azure IP 中,因為其裝載於 GitHub 的 macOS 雲端。 要擷取 IP 範圍,可依此處的指示使用 GitHub 元數據 API。

範例

在下列範例中,會從每周檔案擷取美國西部區域中組織的託管代理程式IP位址範圍。 由於美國西部區域位於 美國 地理位置中,因此會包含 美國 地理位置中所有區域的 IP 位址。 在此範例中,IP 位址會寫入主控台。

using Newtonsoft.Json.Linq;
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;

namespace WeeklyFileIPRanges
{
    class Program
    {
        // Path to the locally saved weekly file
        const string weeklyFilePath = @"C:\MyPath\ServiceTags_Public_20230904.json";

        static void Main(string[] args)
        {
            // United States geography has the following regions:
            // Central US, East US, East US 2, East US 3, North Central US, 
            // South Central US, West Central US, West US, West US 2, West US 3
            // This list is accurate as of 9/8/2023
            List<string> USGeographyRegions = new List<string>
            {
                "centralus",
                "eastus",
                "eastus2",
                "eastus3",
                "northcentralus",
                "southcentralus",
                "westcentralus",
                "westus",
                "westus2",
                "westus3"
            };

            // Load the weekly file
            JObject weeklyFile = JObject.Parse(File.ReadAllText(weeklyFilePath));
            JArray values = (JArray)weeklyFile["values"];

            foreach (string region in USGeographyRegions)
            {
                string tag = $"AzureCloud.{region}";
                Console.WriteLine(tag);

                var ipList =
                    from v in values
                    where tag.Equals((string)v["name"], StringComparison.OrdinalIgnoreCase)
                    select v["properties"]["addressPrefixes"];

                foreach (var ip in ipList.Children())
                {
                    Console.WriteLine(ip);
                }
            }
        }
    }
}

服務標籤

服務標籤無法列出Microsoft裝載的代理程式。 如果您要授予代管代理程式存取您的資源的權限,您必須遵循 IP 範圍的允許清單方法。

安全性

Microsoft裝載的代理程式會在安全的 Azure 平台上執行。 不過,您必須注意下列安全性考慮。

  • 雖然Microsoft裝載的代理程式是在 Azure 公用網路上執行,但不會指派公用 IP 位址。 因此,外部實體無法以Microsoft裝載的代理程序為目標。
  • Microsoft 裝載的代理程式會在個別的 VM 中執行,這些 VM 會在每次執行後重新製作映像。 每個代理程式都專用於單一組織,而每個 VM 只會裝載單一代理程式。
  • 從安全性的觀點來看,在 Microsoft 託管的代理上執行您的管線具有數個優勢。 如果您在管線中執行不受信任的程式碼,例如來自分支的貢獻,最好在由 Microsoft 託管的代理程式上執行管線,這樣會比在公司網路中的自我託管代理程式上更安全。
  • 當管道需要存取防火牆後方的公司資源時,您必須允許 Azure 區域的 IP 位址範圍。 這可能會增加您的曝光率,因為IP位址的範圍相當大,而且因為此範圍中的機器也可以屬於其他客戶。 若要避免這種情況,最好的方法是避免需要存取內部資源。 如需將工件部署至一組伺服器的資訊,請參閱 部署至目標伺服器的通訊
  • 裝載的映像不符合 CIS 強化基準。 若要使用 CIS 強化的映像,您必須建立自行託管代理程式、規模設定代理程式或管理的 DevOps 資源池。

功能和限制

Microsoft裝載的代理程式:

  • 具有 上述軟體。 您也可以在構建或發行期間使用 工具安裝程式任務 新增軟體。
    • 您會為管線中的每個作業取得全新的映像代理程式。
  • 為您的來源和建置輸出提供 10 GB 的記憶體。
  • 提供免費等級
    • 公用專案:提供 10 個由 Microsoft 主機託管的免費平行作業,每次可執行最多 360 分鐘(6 小時),每月無整體時間限制。 請與我們聯繫,以便增加您的免費級限制。
    • 私人專案:每個月最多可以執行 60 分鐘的免費平行作業,直到您每月使用 1,800 分鐘(30 小時)。 您可以為每個並行作業的額外容量付費。 付費平行作業會移除每月時間限制,並可讓您執行每個作業最多 360 分鐘 (6 小時)。 購買由 Microsoft 托管的平行工作
    • 當您建立新的 Azure DevOps 組織時,預設不會獲得這些免費授與。 若要要求公用或私人項目的免費授與,請提交 要求
  • Microsoft Azure 一般用途虛擬機 Standard_DS2_v2上執行。
  • 在 Windows 上以系統管理員身分執行,並在 Linux 上以無密碼 sudo 使用者身分執行。
  • (僅限 Linux)在 cgroup 中執行步驟,提供 6 GB 物理記憶體和 13 GB 總記憶體。
  • 使用定期更新的 VM 映像(每 3 周)。

Microsoft裝載的代理程序不提供:

  • 遠端連線的能力。
  • 資料投放至 UNC 檔案分享的能力。
  • 能夠將機器直接加入公司網路。
  • 具備建造更大或更強大機器的能力。
  • 預先載入自定義軟體的能力。 您可以在管線執行期間安裝軟體,例如透過 工具安裝程式工作 或在腳本中安裝軟體。
  • 使用自我託管代理程式可能帶來的潛在效能優勢是,它們能更快啟動和執行組建。 深入了解
  • 執行 XAML 組建的能力。
  • 回復至先前虛擬機器映像版本的能力。 您一律會使用最新版本。

如果 Microsoft 託管的代理程式不符合您的需求,您可以部署自己的自託管代理程式,或使用擴展集代理程式或受控 DevOps 集區。

常見問題集

如何查看映像中包含的軟體?

您可以選擇 [軟體] 資料表中的 [包含的軟體] 連結,以查看每個託管代理程式的已安裝軟體

注意

根據預設,Windows 代理程式會使用隨附於代理程式軟體的 Git 版本。 Microsoft 建議使用內建於代理程式中的 Git 版本,但您有數個選項可以覆寫此預設行為,並使用已安裝在代理程式電腦路徑中的 Git 版本。

  • 在管線中將名為 System.PreferGitFromPath 的管線變數設定為 true
  • 在自我裝載代理程式上,您可以在代理程式根目錄中建立名為 .env 的檔案,並將一 System.PreferGitFromPath=true 行新增至檔案。 如需詳細資訊,請參閱 如何? 為每個個別代理程式設定不同的環境變數?

若要查看管線所使用的 Git 版本,您可以查看管線中如以下範例所示的 checkout 步驟記錄。

Syncing repository: PathFilter (Git)
Prepending Path environment variable with directory containing 'git.exe'.
git version
git version 2.26.2.windows.1

Microsoft如何選擇要放在映像上的軟體和版本?

如需映像上所含軟體版本的詳細資訊,請參閱 所安裝專案的指導方針。

映像何時更新?

影像通常會每周更新一次。 您可以檢查 狀態徽章,格式 20200113.x 的第一部分指出影像更新的日期。

如果我需要的軟體已移除或取代為較新版本,該怎麼辦?

您可以在 使用 Microsoft 託管代理 表格中,通過選擇 包含的軟體 連結來提交 GitHub 問題告知我們。

您也可以使用包含所需軟體確切版本的自我裝載代理程式。 如需詳細資訊,請參閱 自我托管代理

如果我需要具有更多處理能力、記憶體或磁碟空間的較大計算機,該怎麼辦?

我們無法增加 Microsoft 托管代理程式的記憶體、處理能力或磁碟空間,但您可以使用 自我托管代理程式伸縮設定代理程式受控 DevOps 資源池,這些是裝載於具有所需規格的電腦上。

我無法選取由 Microsoft 託管的代理,也無法將我的組建或部署排入佇列。 我該怎麼做?

Microsoft裝載的代理程式僅適用於 Azure Pipelines,不適用於 TFS 或 Azure DevOps Server。

根據預設,組織中的所有項目參與者都可以存取Microsoft裝載的代理程式。 但是,您的組織系統管理員可能會限制Microsoft裝載的代理程式的存取權,以選取使用者或專案。 要求 Azure DevOps 組織的擁有者授與您使用Microsoft裝載代理程序的許可權。 請參閱 代理程式集區安全性

在 Microsoft 託管的代理程式上執行的管線需要更多時間才能完成。 如何加快速度?

如果您的管線最近速度變慢,請參閱我們的狀態頁面查看是否存在問題。 我們的服務可能有問題。 或者,檢閱您在應用程式程式碼或管線中所做的任何變更。 在簽出期間,您的存放庫大小可能已增加、您可能正在上傳大型成品,或者您可能正在執行更多測試。

如果您正在設定管線,並比較 Microsoft 裝載代理程式的效能與本機電腦或自我裝載代理程式的效能,請注意我們用來執行作業的硬體規格。 我們無法為您提供更大或功能更強大的機器。 如果無法接受此效能,您可以考慮使用 自架代理程式自動調整代理程式受控 DevOps 集區

我需要更多的代理人。 我能做什麼?

所有 Azure DevOps 組織都會為開放原始碼專案提供數個免費平行作業,並為私人專案每個月提供一個免費平行作業和有限的分鐘數。 如果您需要開放原始碼專案的額外分鐘數或平行作業,請連絡 支持人員。 如果您需要私人專案的額外分鐘數或平行作業,您可以 購買更多數量

我的管線會在自我託管的代理程式上成功,但在Microsoft託管的代理程式上失敗。 我該怎麼做?

您的自行裝載代理程式可能已安裝所有正確的相依性,而 Microsoft 裝載的代理程式上則沒有安裝這些相依性、工具和軟體。 首先,請仔細檢閱安裝在 Microsoft 託管代理程式上的軟體清單,方法是參閱上表中的 包含的軟體 連結。 然後,將這與安裝在自我託管代理程式上的軟體進行比較。 在某些情況下,Microsoft裝載的代理程式可能會有您需要的工具(例如 Visual Studio),但可能尚未安裝所有必要的選擇性元件。 如果您發現差異,則您有兩個選項:

  • 您可以在存放庫中建立新的議題,我們會在其中追蹤新增軟體的請求。 連絡支持人員無法協助您在Microsoft裝載的代理程式上設定新軟體。

  • 您可以使用 自我托管代理規模設定代理托管 DevOps 集區。 使用這些代理,您可以完全控制用來執行工作流程的映像檔。

我的組建會在本機計算機上成功,但在Microsoft裝載的代理程序上失敗。 我該怎麼做?

您的本機電腦可能已安裝所有正確的相依套件,而相同的相依套件、工具和軟體不會安裝在由Microsoft托管的代理程式上。 首先,請仔細檢閱安裝在 Microsoft 託管代理程式上的軟體清單,方法是參閱上表中的 包含的軟體 連結。 然後,將這與安裝在本機計算機上的軟體進行比較。 在某些情況下,Microsoft裝載的代理程式可能會有您需要的工具(例如 Visual Studio),但可能尚未安裝所有必要的選擇性元件。 如果您發現差異,則您有兩個選項:

  • 您可以在存放庫中建立新的議題,我們會在其中追蹤新增軟體的請求。 這是安裝新軟體的最佳選擇。 連絡支持人員將無法協助您在Microsoft裝載的代理程式上設定新的軟體。

  • 您可以使用 自我托管代理規模設定代理托管 DevOps 集區。 使用這些代理,您可以完全控制用來執行工作流程的映像檔。

我的管線失敗,並出現錯誤:「裝置上沒有剩餘空間」。

Microsoft 裝載的代理程式僅有 10 GB 的磁碟空間可供執行您的作業。 當您簽出原始碼、下載套件、下載 Docker 映像或產生中繼檔案時,會耗用此空間。 不幸的是,我們無法增加 Microsoft 主機映像上的可用空間。 您可以重新建構管線,使其可以納入此空間。 或者,您可以考慮使用 自我托管代理程式縮放集代理程式受管理的 DevOps 集區

我們在 Microsoft 託管代理上執行的派送程序需要存取我們企業內網絡上的伺服器。 如何取得防火牆中允許的IP位址清單?

請參閱代理程式IP範圍一節

在Microsoft代管代理上執行的流水線無法解析我們公司網路中伺服器的名稱。 如何修正此問題?

如果您依 DNS 名稱參照伺服器,請確定您的伺服器可透過其 DNS 名稱在因特網上公開存取。 如果您依其IP位址參照您的伺服器,請確定IP位址可在因特網上公開存取。 在這兩種情況下,請確定代理程式與公司網路之間的任何防火牆都 允許代理程式IP範圍

我收到一個來自 Azure 儲存帳戶的 SAS IP 驗證錯誤

如果您收到 SAS 錯誤碼,很可能是因為您的 Azure 儲存體規則不允許 Microsoft 裝載代理程式的 IP 位址範圍。 有一些因應措施:

  1. 管理您 Azure 儲存體 帳戶的IP網路規則,並新增託管代理程式的IP位址範圍。
  2. 在您的管線中,使用 Azure CLI 來更新 Azure 儲存體帳戶的網路規則集,在存取儲存體之前,然後恢復先前的規則集。
  3. 使用 自行架設代理程式可擴展代理程式受控 DevOps 集區

如何在託管 macOS 代理程式上手動選取工具的版本?

Xcode

如果您使用 Azure Pipelines 和 TFS 隨附的 Xcode 工作 ,您可以在該工作的屬性中選取 Xcode 版本。 否則,若要手動將 Xcode 版本設定為在託管 macOS 代理程式集區上使用,請在xcodebuild建置工作之前,視需要執行此命令行,並視需要取代 Xcode 版本號碼 13.2:

/bin/bash -c "sudo xcode-select -s /Applications/Xcode_13.2.app/Contents/Developer"

Xcode 版本可以在 Hosted macOS 代理程式集區 這裡找到。

Mono

若要在裝載的 macOS 代理程式集區上手動選取要使用的 Mono 版本,請在您的 Mono 建置工作之前,於組建的每個作業中執行此腳本,並指定具有所需 Mono 版本的符號連結:

SYMLINK=<symlink>
MONOPREFIX=/Library/Frameworks/Mono.framework/Versions/$SYMLINK
echo "##vso[task.setvariable variable=DYLD_FALLBACK_LIBRARY_PATH;]$MONOPREFIX/lib:/lib:/usr/lib:$DYLD_LIBRARY_FALLBACK_PATH"
echo "##vso[task.setvariable variable=PKG_CONFIG_PATH;]$MONOPREFIX/lib/pkgconfig:$MONOPREFIX/share/pkgconfig:$PKG_CONFIG_PATH"
echo "##vso[task.setvariable variable=PATH;]$MONOPREFIX/bin:$PATH"