自我裝載 Linux 代理程式

Azure DevOps Services |Azure DevOps Server 2022 - Azure DevOps Server 2019 |TFS 2018

注意

管線小組正在發行目前處於預覽狀態的 3.x 代理程式軟體版本。 如需詳細資訊,請參閱 代理程式軟體第 3 版預覽

注意

在 Microsoft Team Foundation Server (TFS) 2018 和舊版中,組建和發行管線稱為定義、執行稱為組建服務連線稱為服務端點階段稱為環境,而作業稱為階段

若要執行作業,您至少需要一個代理程式。 Linux 代理程式可以建置和部署不同類型的應用程式,包括 JAVA 和 Android 應用程式。 我們支援 Ubuntu、Red Hat 和 CentOS。

開始之前:

  • 如果您的管線位於 Azure Pipelines 中,且 Microsoft 裝載的代理程式 符合您的需求,您可以略過設定私人 Linux 代理程式。
  • 否則,您已前往正確的位置,在 Linux 上設定代理程式。 繼續進行下一節。

瞭解代理程式

如果您已經知道代理程式是什麼及其運作方式,請放心地直接跳到下列各節。 但是,如果您想要更多有關其用途及其運作方式的背景,請參閱 Azure Pipelines 代理程式

檢查先決條件

代理程式是以 .NET Core 3.1 為基礎。 您可以在數個 Linux 發行版本上執行此代理程式。 我們支援下列 .NET Core 支援的發行版本子集:

  • x64
    • CentOS 7、6 (請參閱附注 1)
    • Debian 9
    • Fedora 30,29
    • Linux Mint 18、17
    • openSUSE 42.3 或更新版本
    • Oracle Linux 8,7
    • Red Hat Enterprise Linux 8、7、6 (請參閱附注 1)
    • SUSE Enterprise Linux 12 SP2 或更新版本
    • Ubuntu 20.04、18.04、16.04
    • CBL-Mariner 1.0 (請參閱附注 3)
  • ARM32 (請參閱附注 2)
    • Debian 9
    • Ubuntu 18.04
  • ARM64
    • Debian 9
    • Ubuntu 21.04、20.04、18.04

注意

附注 1:RHEL 6 和 CentOS 6 需要安裝特殊 rhel.6-x64 版本的代理程式。

注意

附注 2:需要 ARM 指令集 ARMv7 或更新版本。 執行 uname -a 以查看 Linux 發行版本的指示集。

注意

Azure DevOps 代理程式目前有部分支援的訂閱者 OS 散發套件。 我們會在腳本中 installdependencies.sh 提供偵測此 OS 散發的機制,但由於缺少來自.Net Core端的支援,我們無法保證在此 OS 散發套件上執行時,所有代理程式函式的完整操作性。

無論您的平臺為何,您都需要安裝 Git 2.9.0 或更高版本。 強烈建議您安裝最新版的 Git。

注意

代理程式安裝程式知道如何檢查其他相依性。 您可以在代理程式目錄中執行 ./bin/installdependencies.sh ,在支援的 Linux 平臺上安裝這些相依性。

請注意,.NET Core 所需的部分相依性是從協力廠商網站擷取,例如 packages.efficios.com 。 檢閱 installdependencies.sh 腳本,並確定在執行腳本之前,可以從您的 Linux 電腦存取任何參考的協力廠商網站。

也請確定所有必要的存放庫都已連線到像是 或 zypper) 等 apt (中使用的 installdependencies.sh 相關套件管理員。

如需相依性安裝 (的問題,例如「存放庫中找不到相依性」或「擷取存放庫索引檔案時發生問題」) - 您可以連絡散發擁有者以取得進一步支援。

TFS 2018 RTM 和較舊版本:出貨的代理程式是以 CoreCLR 1.0 為基礎。 如果能夠,建議您升級至較新的代理程式版本 (2.125.0 或更高版本) 。 如需執行較新代理程式所需的詳細資訊,請參閱 Azure Pipelines 代理程式前置 詞。

如果您必須停留在較舊的代理程式上,請確定您的電腦已備妥我們的其中一個支援散發套件的必要條件:

Subversion

如果您要從 Subversion 存放庫建置,則必須在電腦上安裝 Subversion 用戶端。

您應該第一次手動執行代理程式設定。 當您瞭解代理程式的運作方式,或想要自動設定許多代理程式之後,請考慮使用 自動設定

TFVC

如果您要使用 TFVC,您也需要 Oracle JAVA JDK 1.6 或更高版本。 (Oracle JRE 和 OpenJDK 不足以達到此目的。)

TEE 外掛程式 用於 TFVC 功能。 其具有 EULA,如果您打算使用 TFVC,則必須在設定期間接受此 EULA。

由於 TEE 外掛程式已不再維護,且包含一些過時的 JAVA 相依性,從 Agent 2.198.0 開始,它不再包含在代理程式散發中。 不過,如果您要取出 TFVC 存放庫,則會在簽出工作執行期間下載 TEE 外掛程式。 工作執行之後,將會移除 TEE 外掛程式。

注意

注意:您可能會注意到您的簽出工作因為此下載機制而需要很長的時間才能開始工作。

如果代理程式在 Proxy 或防火牆後方執行,您必須確保存取下列網站: https://vstsagenttools.blob.core.windows.net/ 。 TEE 外掛程式將會從此位址下載。

如果您使用自我裝載代理程式並遇到 TEE 下載的問題,您可以手動安裝 TEE:

  1. 將環境或管線變數設定 DISABLE_TEE_PLUGIN_REMOVALtrue 。 此變數可防止代理程式在簽出 TFVC 存放庫之後移除 TEE 外掛程式。
  2. Team Explorer Everywhere GitHub 版本手動下載 TEE-CLC 14.135.0 版。
  3. 將資料夾的內容 TEE-CLC-14.135.0 解壓縮至 <agent_directory>/externals/tee

準備許可權

自我裝載代理程式的資訊安全性

設定代理程式的使用者需要集區管理員許可權,但執行代理程式的使用者則不需要。

代理程式所控制的資料夾應盡可能限制為最少的使用者,而且它們包含可解密或外泄的秘密。

Azure Pipelines 代理程式是一種軟體產品,其設計目的是執行從外部來源下載的程式碼。 它原本可能是遠端程式碼執行 (RCE) 攻擊的目標。

因此,請務必考慮管線代理程式每個個別使用方式的相關威脅模型來執行工作,並決定可以授與執行代理程式之使用者的最小許可權、代理程式執行所在的電腦、具有管線定義寫入權限的使用者、儲存 yaml 的 git 存放庫、 或控制新管線集區存取權的使用者群組。

最佳做法是讓執行代理程式的身分識別與具有將代理程式連線到集區之許可權的身分識別不同。 產生認證 (和其他代理程式相關檔案的使用者) 與需要讀取認證的使用者不同。 因此,請謹慎考慮授與代理程式電腦本身的存取權,以及包含敏感性檔案的代理程式資料夾,例如記錄和成品。

只有 DevOps 系統管理員和執行代理程式程式程式的使用者身分識別,才能授與代理程式資料夾的存取權。 系統管理員可能需要調查檔案系統,以瞭解組建失敗或取得記錄檔,才能回報 Azure DevOps 失敗。

決定您將使用的使用者

您必須註冊代理程式,才能進行單次步驟。 有權 管理代理程式佇列 的人員必須完成這些步驟。 代理程式不會在日常作業中使用此人員的認證,但必須完成註冊。 深入瞭解 代理程式如何通訊

使用個人存取權杖進行驗證 (PAT)

  1. 使用您打算在 Team Foundation Server 入口網站中使用的使用者帳戶登入, https://{your-server}:8080/tfs/ () 。
  1. 使用您打算在Azure DevOps Server入口網站中使用的使用者帳戶登入, (https://{your-server}/DefaultCollection/) 。
  1. 使用您計畫在 Azure DevOps 組織 (https://dev.azure.com/{your_organization}) 中使用的使用者帳戶登入。
  1. 從首頁開啟您的設定檔。 移至您的安全性詳細資料。

    移至您的安全性詳細資料。

  2. 建立個人存取權杖

    建立個人存取權杖。

    注意

    如果您要設定部署群組代理程式,或在註冊 VM 環境資源時看到錯誤,您必須將 PAT 範圍設定為 [所有可存取的組織]。 將 PAT 範圍設定為所有可存取組織的螢幕擷取畫面。

  1. 從您的首頁開啟使用者設定,然後選取 [個人存取權杖]。

    移至您的安全性詳細資料。

  2. 建立個人存取權杖

    建立個人存取權杖。

  1. 如需範圍,請選取 [代理程式組件區] (讀取、管理) ,並確定已清除所有其他方塊。 如果是 部署群組 代理程式,請針對範圍選取 [ 部署群組] (讀取、管理) ,並確定已清除所有其他方塊。

    選取 [建立新的個人存取權杖] 視窗視窗底部的 [顯示所有範圍],以查看範圍的完整清單。

  2. 複製權杖。 當您設定代理程式時,將會使用此權杖。

確認使用者具有許可權

請確定您要使用的使用者帳戶具有註冊代理程式的許可權。

使用者是 Azure DevOps 組織擁有者或 TFS 或Azure DevOps Server系統管理員嗎? 在此停止,您有許可權。

否則:

  1. 開啟瀏覽器並流覽至 Azure Pipelines 組織的[代理程式組件區] 索引標籤,或Azure DevOps Server或 TFS 伺服器:

    1. 選擇 [Azure DevOps]、 [組織設定]。

      選擇 [組織設定]。

    2. 選擇 [代理程式組件區]。

      選擇 [代理程式組件區] 索引標籤。

    1. 選擇 [Azure DevOps]、 [集合設定]。

      選擇 [集合設定]。

    2. 選擇 [代理程式組件區]。

      選擇 [代理程式組件區]。

    1. 選擇 [Azure DevOps]、 [集合設定]。

      集合設定 2019。

    2. 選擇 [代理程式組件區]。

      選擇 [代理程式組件區],[2019]。

    1. 流覽至您的專案,然後選擇 [設定] (齒輪圖示) >[代理程式佇列]。

      選擇 [設定]、[代理程式佇列]、[2018]。

    2. 選擇 [管理集區]。

      選擇 [管理集區],2018 年。

  2. 選取頁面右側的集區,然後按一下 [ 安全性]。

  3. 如果未顯示您要使用的使用者帳戶,請取得系統管理員來新增它。 系統管理員可以是代理程式組件區管理員、Azure DevOps 組織擁有者TFS 或Azure DevOps Server系統管理員

    如果是部署群組代理程式,系統管理員可以是部署群組管理員、Azure DevOps 組織擁有者TFS 或Azure DevOps Server系統管理員

    您可以在Azure Pipelines的 [部署群組] 頁面的 [安全性] 索引標籤中,將使用者新增至部署群組管理員角色。

注意

如果您看到如下的訊息:很抱歉,我們無法新增身分識別。請嘗試不同的身分識別。您可能已針對組織擁有者或 TFS 或Azure DevOps Server系統管理員遵循上述步驟。 您不需要執行任何動作;您已經擁有管理代理程式佇列的許可權。

下載並設定代理程式

Azure Pipelines

  1. 使用您已備妥許可權的帳戶登入電腦,如上所述。

  2. 在您的網頁瀏覽器中,登入 Azure Pipelines,然後流覽至 [代理程式組件區 ] 索引標籤:

    1. 選擇 [Azure DevOps]、 [組織設定]。

      選擇 [組織設定]。

    2. 選擇 [代理程式組件區]。

      選擇 [代理程式組件區] 索引標籤。

    1. 選擇 [Azure DevOps]、 [集合設定]。

      選擇 [集合設定]。

    2. 選擇 [代理程式組件區]。

      選擇 [代理程式組件區]。

    1. 選擇 [Azure DevOps]、 [集合設定]。

      集合設定 2019。

    2. 選擇 [代理程式組件區]。

      選擇 [代理程式組件區],[2019]。

    1. 流覽至您的專案,然後選擇 [設定] (齒輪圖示) >[代理程式佇列]。

      選擇 [設定]、[代理程式佇列]、[2018]。

    2. 選擇 [管理集區]。

      選擇 [管理集區],2018 年。

  3. 選取 [預設 集區],選取 [ 代理程式 ] 索引標籤,然後選擇 [ 新增代理程式]。

  4. 在 [ 取得代理程式 ] 對話方塊中,按一下 [Linux]。

  5. 在左窗格中,選取特定類別。 我們針對大部分的 Linux 發行版本提供 x64 或 ARM。 我們也提供 Red Hat Enterprise Linux 6 的特定組建。

  6. 在右窗格中,按一下 [ 下載] 按鈕。

  7. 遵循頁面上的指示執行。

  8. 將代理程式解壓縮到您選擇的目錄中。 cd 至該目錄並執行 ./config.sh

Azure DevOps Server 2019 和 Azure DevOps Server 2020

  1. 使用您已備妥許可權的帳戶登入電腦,如上所述。

  2. 在您的網頁瀏覽器中,登入 Azure DevOps Server 2019,然後流覽至[代理程式組件區] 索引標籤:

    1. 選擇 [Azure DevOps]、 [組織設定]。

      選擇 [組織設定]。

    2. 選擇 [代理程式組件區]。

      選擇 [代理程式組件區] 索引標籤。

    1. 選擇 [Azure DevOps]、 [集合設定]。

      選擇 [集合設定]。

    2. 選擇 [代理程式組件區]。

      選擇 [代理程式組件區]。

    1. 選擇 [Azure DevOps]、 [集合設定]。

      集合設定 2019。

    2. 選擇 [代理程式組件區]。

      選擇 [代理程式組件區],[2019]。

    1. 流覽至您的專案,然後選擇 [設定] (齒輪圖示) >[代理程式佇列]。

      選擇 [設定]、[代理程式佇列]、[2018]。

    2. 選擇 [管理集區]。

      選擇 [管理集區],2018 年。

  3. 按一下 [下載代理程式]。

  4. 在 [ 取得代理程式 ] 對話方塊中,按一下 [Linux]。

  5. 在左窗格中,選取特定類別。 我們針對大部分的 Linux 發行版本提供 x64 或 ARM。 我們也提供 Red Hat Enterprise Linux 6 的特定組建。

  6. 在右窗格中,按一下 [ 下載] 按鈕。

  7. 遵循頁面上的指示執行。

  8. 將代理程式解壓縮到您選擇的目錄中。 cd 至該目錄並執行 ./config.sh

TFS 2018

  1. 使用您已備妥許可權的帳戶登入電腦,如上所述。

  2. 在您的網頁瀏覽器中,登入 TFS,然後流覽至 [代理程式組件區] 索引標籤:

    1. 流覽至您的專案,然後選擇 [設定] (齒輪圖示) >[代理程式佇列]。

      選擇 [設定]、[代理程式佇列]、[2018]。

    2. 選擇 [管理集區]。

      選擇 [管理集區],2018 年。

  3. 按一下 [下載代理程式]。

  4. 在 [ 取得代理程式 ] 對話方塊中,按一下 [Linux]。

  5. 按一下 [ 下載] 按鈕。

  6. 遵循頁面上的指示執行。

  7. 將代理程式解壓縮到您選擇的目錄中。 cd 至該目錄並執行 ./config.sh 。 請確定目錄的路徑不包含空格,因為工具和腳本不一定會正確逸出空格。

伺服器 URL

Azure Pipelines: https://dev.azure.com/{your-organization}

Azure DevOps Server 2019:https://{your_server}/DefaultCollection

TFS 2018: https://{your_server}/tfs

驗證類型

Azure Pipelines

選擇 PAT,然後將 您建立的 PAT 權杖 貼到命令提示字元視窗中。

注意

使用 PAT 作為驗證方法時,PAT 權杖只會用於代理程式的初始設定。 若要深入瞭解 ,請參閱與 Azure Pipelines 或 TFS 的通訊

TFS 或 Azure DevOps Server

重要

請確定您的伺服器已 設定為支援您想要使用的驗證方法

當您將代理程式設定為連線到 TFS 時,您有下列選項:

  • 互生使用基本驗證連線到 TFS 或Azure DevOps Server。 選取 [替代] 之後,系統會提示您輸入認證。

  • 綜合 macOS 或 Linux 不支援。

  • 交涉 (預設) 透過 NTLM 或 Kerberos 等Windows 驗證配置連線到 TFS 或Azure DevOps Server作為登入使用者以外的使用者。 選取 [交涉] 之後,系統會提示您輸入認證。

  • 派特 僅支援 Azure Pipelines 和 TFS 2017 和更新版本。 選擇 PAT 之後,請將 您建立的 PAT 權杖 貼到命令提示字元視窗中。 如果您的Azure DevOps Server或 TFS 實例和代理程式電腦不在受信任的網域中,請使用個人存取權杖 (PAT) 。 PAT 驗證是由您的 Azure DevOps Server 或 TFS 實例處理,而不是網域控制站。

注意

使用 PAT 作為驗證方法時,PAT 權杖只會用於Azure DevOps Server和較新版本 TFS 上的代理程式初始設定。 若要深入瞭解 ,請參閱與 Azure Pipelines 或 TFS 的通訊

以互動方式執行

如需是否要在互動式模式或服務中執行代理程式的指引,請參閱 代理程式:互動式與服務

若要以互動方式執行代理程式:

  1. 如果您已經以服務的形式執行代理程式, 請卸載服務

  2. 執行代理程式。

    ./run.sh
    

若要重新開機代理程式,請按 Ctrl+C,然後執行 run.sh 以重新開機代理程式。

若要使用代理程式,請使用代理程式的集區執行 作業 。 如果您未選擇不同的集區,您的代理程式將會位於 預設 集區中。

執行一次

針對設定為以互動方式執行的代理程式,您可以選擇讓代理程式只接受一個作業。 若要在此組態中執行:

./run.sh --once

此模式中的代理程式只會接受一項作業,然後正常地向下微調, (適用于在docker 中執行的服務,例如Azure 容器執行個體) 。

以系統服務身分執行

如果您的代理程式在這些作業系統上執行,您可以執行代理程式即 systemd 服務:

  • Ubuntu 16 LTS 或更新版本
  • Red Hat 7.1 或更新版本

我們提供範例 ./svc.sh 腳本供您執行和管理代理程式即 systemd 服務。 此腳本會在您設定代理程式之後產生。 建議您先檢閱,並視需要更新腳本,再執行腳本。

一些重要的注意事項:

  • 如果您以服務的形式執行代理程式,則無法以使用者身分 root 執行代理程式服務。
  • 執行 SELinux 的使用者回報了所提供 svc.sh 腳本的困難。 請參閱 此代理程式問題 作為起點。 SELinux 不是正式支援的組態。

注意

如果您有不同的散發,或偏好其他方法,則可以使用您偏好的服務機制。 請參閱 服務檔案

命令

變更為代理程式目錄

例如,如果您在主目錄的子資料夾中安裝 myagent

cd ~/myagent$

安裝

命令:

sudo ./svc.sh install [username]

此命令會建立指向 ./runsvc.sh 的服務檔案。 此腳本會設定環境 (下列) 並啟動代理程式主機的詳細資料。 如果未 username 指定 parameter,則使用者名稱取自 sudo 命令所設定的 $SUDO_USER 環境變數。 此變數一律等於叫 sudo 用命令的使用者名稱。

開始

sudo ./svc.sh start

狀態

sudo ./svc.sh status

Stop

sudo ./svc.sh stop

解除安裝

卸載之前,您應該先停止。

sudo ./svc.sh uninstall

更新環境變數

當您設定服務時,它會為目前的登入使用者擷取一些有用的環境變數快照集,例如 PATH、LANG、JAVA_HOME、ANT_HOME和MYSQL_PATH。 例如,如果您需要更新變數 (,請在安裝一些新的軟體之後) :

./env.sh
sudo ./svc.sh stop
sudo ./svc.sh start

環境變數的快照集儲存在 .env 檔案中, PATH (儲存在 .path 代理程式根目錄下的) ,您也可以直接變更這些檔案以套用環境變數變更。

在服務啟動之前執行指示

您也可以執行自己的指示和命令,以在服務啟動時執行。 例如,您可以設定環境或呼叫腳本。

  1. 編輯 runsvc.sh

  2. 以您的指示取代下列這一行:

    # insert anything to setup env when running as a service
    

服務檔案

當您安裝服務時,會就地放置某些服務檔案。

systemd 服務檔案

系統會建立系統服務檔案:

/etc/systemd/system/vsts.agent.{tfs-name}.{agent-name}.service

例如,您已設定代理程式, (請參閱上述名稱) 。 our-linux-agent 服務檔案會是:

  • Azure Pipelines:貴組織的名稱。 例如,如果您連線到 https://dev.azure.com/fabrikam ,則服務名稱會是 /etc/systemd/system/vsts.agent.fabrikam.our-linux-agent.service

  • TFS 或Azure DevOps Server:內部部署伺服器的名稱。 例如,如果您連線到 http://our-server:8080/tfs ,則服務名稱會是 /etc/systemd/system/vsts.agent.our-server.our-linux-agent.service

sudo ./svc.sh install 從此範本產生此檔案: ./bin/vsts.agent.service.template

.service 檔案

sudo ./svc.sh start 藉由讀取檔案來 .service 尋找服務,其中包含上述 systemd 服務檔案的名稱。

替代服務機制

./svc.sh我們提供腳本作為方便的方式,讓您以系統服務的形式執行和管理代理程式。 但是,您可以使用您偏好的任何服務機制 (例如:initd 或 upstart) 。

您可以使用上述範本來協助產生其他類型的服務檔案。

使用 cgroup 以避免代理程式失敗

請務必避免代理程式失敗或變成無法使用的情況,因為代理程式無法將管線記錄或報告管線狀態串流回伺服器。 您可以使用 cgroups 和較低的 oom_score_adj ,降低這種問題所造成的風險。 完成此動作之後,Linux 會先從管線作業進程回收系統記憶體,再從代理程式進程回收記憶體。 瞭解如何設定 cgroups 和 OOM 分數

取代代理程式

若要取代代理程式,請遵循 下載並再次設定代理程式 步驟。

當您使用與已經存在之代理程式相同的名稱來設定代理程式時,系統會詢問您是否要取代現有的代理程式。 如果您回答 Y ,請確定您將代理程式移除 (請參閱下方) 您要取代的代理程式。 否則,在幾分鐘的衝突之後,其中一個代理程式將會關閉。

移除並重新設定代理程式

移除代理程式:

  1. 如上所述,停止並卸載服務。

  2. 移除代理程式。

    ./config.sh remove
    
  3. 輸入認證。

移除代理程式之後,您可以 再次加以設定

自動設定

您可以從腳本設定代理程式,而不需要人為介入。 您必須傳遞 --unattended 和所有問題的答案。

若要設定代理程式,它必須知道貴組織的 URL,或已獲授權設定代理程式的某人的集合和認證。 所有其他回應都是選擇性的。 您可以改用環境變數來指定任何命令列參數:將其名稱放在大寫和前面 VSTS_AGENT_INPUT_ 。 例如, VSTS_AGENT_INPUT_PASSWORD 而不是指定 --password

必要選項

  • --unattended - 代理程式設定不會提示輸入資訊,而且必須在命令列上提供所有設定
  • --url <url> - 伺服器的 URL。 例如:https://dev.azure.com/myorganization 或 http://my-azure-devops-server:8080/tfs
  • --auth <type> - 驗證類型。 有效值為:
    • pat (個人存取權杖) - PAT 是唯一適用于Azure DevOps Services的配置。
    • negotiate (Kerberos 或 NTLM)
    • alt (基本驗證)
    • integrated (Windows 預設認證)

驗證選項

  • 如果您選擇 --auth pat
    • --token <token> - 指定您的個人存取權杖
    • PAT 是唯一可與 Azure DevOps Services 搭配運作的配置。
  • 如果您選擇 --auth negotiate--auth alt
    • --userName <userName> - 指定格式 domain\userName 為 或 的 Windows 使用者名稱 userName@domain.com
    • --password <password> - 指定密碼

集區和代理程式名稱

  • --pool <pool> - 要加入之代理程式的集區名稱
  • --agent <agent> - 代理程式名稱
  • --replace - 取代集區中的代理程式。 如果另一個代理程式以相同名稱接聽,它將會開始失敗併發生衝突

代理程式設定

  • --work <workDirectory> - 工作目錄,其中會儲存作業資料。 預設為 _work 在代理程式目錄的根目錄下。 工作目錄是由指定的代理程式所擁有,不應在多個代理程式之間共用。
  • --acceptTeeEula- 僅接受 macOS 和 Linux (使用者授權合約Team Explorer Everywhere)
  • --disableloguploads - 不要將主控台記錄輸出串流或傳送至伺服器。 相反地,您可以在作業完成之後,從代理程式主機的檔案系統擷取它們。

僅限 Windows 啟動

  • --runAsService - 將代理程式設定為以 Windows 服務身分執行, (需要系統管理員許可權)
  • --runAsAutoLogon - 設定自動登入並在啟動時執行代理程式, (需要系統管理員許可權)
  • --windowsLogonAccount <account> - 與 或 搭配 --runAsService 使用,以或 --runAsAutoLogon 格式 domain\userName 指定 Windows 使用者名稱 userName@domain.com
  • --windowsLogonPassword <password> - 用於 --runAsService--runAsAutoLogon 來指定 群組受管理服務帳戶 和 Windows 內建帳戶不需要的 Windows 登入密碼 (,例如 'NT AUTHORITY\NETWORK SERVICE')
  • --overwriteAutoLogon - 用來 --runAsAutoLogon 覆寫電腦上現有的自動登入
  • --noRestart - 用來 --runAsAutoLogon 在代理程式設定完成之後停止主機重新開機

使用 runAsAutoLogon 選項設定代理程式進行疑難排解

使用 runAsAutoLogon 選項設定代理程式,會在每次重新開機機器之後執行代理程式。 如果代理程式在重新開機機器之後未執行,請執行後續步驟。

如果已在機器上設定代理程式

在重新設定代理程式之前,必須先移除舊的代理程式組態,因此請嘗試從代理程式資料夾執行此命令:

.\config.cmd remove --auth 'PAT' --token '<token>'

在執行 命令之後,檢查代理程式是否已從代理程式組件區中移除:

<Azure DevOps organization> / <Project> / Settings / Agent pools / <Agent Pool> / Agents

如果代理程式組件區未執行 命令,請手動從您的代理程式組件區中移除該代理程式。

然後,從代理程式資料夾執行此命令,嘗試重新設定代理程式:

.\config.cmd --unattended --agent '<agent-name>' --pool '<agent-pool-name>' --url '<azure-dev-ops-organization-url>' --auth 'PAT' --token '<token>' --runAsAutoLogon --windowsLogonAccount '<domain\user-name>' --windowsLogonPassword '<windows-password>'

指定代理程式名稱 (任何特定的唯一名稱) ,並在重新設定之後檢查此代理程式是否出現在您的代理程式組件區中。

將代理程式封存解壓縮 (,最好 在這裡 下載) ,並從新的解壓縮代理程式資料夾執行此命令。

檢查是否已記錄並正確儲存 Windows 登錄機碼

whoami /user執行 命令以取得 <sid> 。 開啟 Registry Editor 並遵循路徑:

Computer\HKEY_USERS\<sid>\SOFTWARE\Microsoft\Windows\CurrentVersion\Run

檢查是否有 VSTSAgent 金鑰。 如果此機碼存在,請關閉並設定 Registry Editor 代理程式,方法是執行 .\config.cmd 命令 (,而不需從代理程式資料夾) 。 在回答問題 Enter Restart the machine at a later time? 之前,請再次開啟 Registry Editor 並檢查金鑰是否已 VSTSAgent 出現。 按 Enter 以回答問題,並檢查金鑰在重新開機機器之後是否 VSTSAgent 留在其位置。

檢查 Windows 登錄機碼在您的電腦上是否正常運作

建立 autorun.cmd 包含下列這一行的檔案: echo "Hello from AutoRun!" 。 在新的索引鍵/值組與索引鍵 AutoRun 和值上方的路徑中開啟 Registry Editor 並建立

C:\windows\system32\cmd.exe /D /S /C start "AutoRun" "D:\path\to\autorun.cmd"

重新啟動您的電腦。 如果您沒有看到含有訊息的 Hello from AutoRun! 主控台視窗,您有 Windows 登錄機碼的問題。

僅限部署群組

  • --deploymentGroup - 將代理程式設定為部署群組代理程式
  • --deploymentGroupName <name> - 用於 --deploymentGroup 指定要加入之代理程式的部署群組
  • --projectName <name> - 用於 --deploymentGroup 設定專案名稱
  • --addDeploymentGroupTags - 用來 --deploymentGroup 指出應該新增部署群組標籤
  • --deploymentGroupTags <tags> - 用於 --addDeploymentGroupTags 指定部署群組代理程式的逗號分隔標籤清單 - 例如 「web, db」

僅限環境

  • --addvirtualmachineresourcetags - 用來指出應該新增環境資源標籤
  • --virtualmachineresourcetags <tags> - 用於 --addvirtualmachineresourcetags 指定環境資源代理程式的逗號分隔標籤清單 - 例如 「web, db」

./config.sh --help 一律會列出最新的必要和選擇性回應。

診斷

如果您遇到自我裝載代理程式的問題,您可以嘗試執行診斷。 設定代理程式之後:

./run.sh --diagnostics

這會透過診斷套件來執行,以協助您針對問題進行疑難排解。 診斷功能可從代理程式 2.165.0 版開始取得。

其他選項的說明

若要瞭解其他選項:

./config.sh --help

說明提供有關驗證替代專案和自動設定的資訊。

功能

代理程式的功能會在集區中編錄並公告,以便只指派其可處理的組建和發行。 請參閱 建置和發行代理程式功能

在許多情況下,部署代理程式之後,您必須安裝軟體或公用程式。 一般而言,您應該在代理程式上安裝您在開發電腦上使用的任何軟體和工具。

例如,如果您的組建包含 npm 工作,則除非集區中有已安裝 npm 的組建代理程式,否則不會執行組建。

重要

功能包括所有環境變數,以及代理程式執行時所設定的值。 如果代理程式執行時有任何值變更,則必須重新開機代理程式以挑選新的值。 在代理程式上安裝新軟體之後,您必須重新開機代理程式,才能在集區中顯示新功能,讓組建可以執行。

如果您想要將環境變數排除為功能,您可以藉由設定具有逗號分隔變數清單的環境變數 VSO_AGENT_IGNORE 來加以指定。

常見問題集

如何?確定我有最新的 v2 代理程式版本嗎?

  1. 流覽至 [代理程式組件區 ] 索引標籤:

    1. 選擇 [Azure DevOps]、 [組織設定]。

      選擇 [組織設定]。

    2. 選擇 [代理程式組件區]。

      選擇 [代理程式組件區] 索引標籤。

    1. 選擇 [Azure DevOps]、 [集合設定]。

      選擇 [集合設定]。

    2. 選擇 [代理程式組件區]。

      選擇 [代理程式組件區]。

    1. 選擇 [Azure DevOps]、 [集合設定]。

      集合設定 2019。

    2. 選擇 [代理程式組件區]。

      選擇 [代理程式組件區],[2019]。

    1. 流覽至您的專案,然後選擇 [設定] (齒輪圖示) >[代理程式佇列]。

      選擇 [設定]、[代理程式佇列]、[2018]。

    2. 選擇 [管理集區]。

      選擇 [管理集區],2018 年。

  2. 按一下包含代理程式的集區。

  3. 請確定代理程式已啟用。

  4. 流覽至 [功能] 索引標籤:

    1. 從 [ 代理程式組件區 ] 索引標籤中,選取所需的代理程式組件區。

      從 [代理程式組件區] 中,選取所需的代理程式組件區。

    2. 選取 [代理程式 ],然後選擇所需的代理程式。

      選取 [代理程式],然後選擇代理程式。

    3. 選擇 [ 功能] 索引卷 標。

      選擇 [功能] 索引標籤。

      注意

      Microsoft 裝載的代理程式不會顯示系統功能。 如需 Microsoft 裝載代理程式上安裝的軟體清單,請參閱 使用 Microsoft 裝載的代理程式

    1. 從 [ 代理程式組件區 ] 索引標籤中,選取所需的集區。

      選取所需的集區。

    2. 選取 [代理程式 ],然後選擇所需的代理程式。

      選取 [代理程式],然後選擇所需的代理程式。

    3. 選擇 [ 功能] 索引卷 標。

      [代理程式功能] 索引標籤。

    1. 從 [ 代理程式組件區 ] 索引標籤中,選取所需的集區。

      選取所需的索引標籤 2019。

    2. 選取 [代理程式 ],然後選擇所需的代理程式。

      選擇所需的代理程式 2019。

    3. 選擇 [ 功能] 索引卷 標。

      選擇 [功能] 索引標籤 2019。

    選取所需的代理程式,然後選擇 [功能] 索引 標。

    [代理程式功能] 索引標籤,2018 年。

  5. 尋找 Agent.Version 功能。 您可以針對最新的已發佈代理程式版本檢查此值。 請參閱 Azure Pipelines 代理程式 ,並檢查頁面中所列的最高版本號碼。

  6. 當每個代理程式執行需要較新版本代理程式的工作時,每個代理程式都會自動更新本身。 如果您想要手動更新某些代理程式,請以滑鼠右鍵按一下集區,然後選取 [ 更新所有代理程式]。

我可以更新屬於Azure DevOps Server集區一部分的 v2 代理程式嗎?

是的 從 Azure DevOps Server 2019 開始,您可以設定伺服器來尋找本機磁片上的代理程式套件檔案。 此組態將會覆寫伺服器發行時隨附的預設版本。 當伺服器無法存取網際網路時,也會套用此案例。

  1. 從具有網際網路存取的電腦,從 Azure Pipelines Agent GitHub Releases 頁面下載最新版的代理程式套件檔案 (.zip或 .tar.gz 表單) 。

  2. 使用您選擇的方法,將下載的套件檔案傳送至每個Azure DevOps Server應用層 (,例如 USB 磁片磁碟機、網路傳輸等等) 。 將代理程式檔案放在 資料夾底下 %ProgramData%\Microsoft\Azure DevOps\Agents

  3. 您全都已設定! 每當更新代理程式時,您的Azure DevOps Server現在會使用本機檔案。 當每個代理程式執行需要較新版本代理程式的工作時,每個代理程式都會自動更新本身。 但如果您想要手動更新某些代理程式,請以滑鼠右鍵按一下集區,然後選擇 [ 更新所有代理程式]。

為什麼需要 sudo 才能執行服務命令?

./svc.sh 會使用 systemctl ,其需要 sudo

原始程式碼: GitHub 上的 systemd.svc.sh.template

我正在執行防火牆,而我的程式碼是 Azure Repos。 代理程式需要哪些 URL 才能進行通訊?

如果您在防火牆後方的安全網路中執行代理程式,請確定代理程式可以起始與下列 URL 和 IP 位址的通訊。

網域 URL 描述
https://{organization_name}.pkgs.visualstudio.com 使用網域的組織使用 {organization_name}.visualstudio.com Azure DevOps 封裝 API
https://{organization_name}.visualstudio.com 針對使用網域的組織 {organization_name}.visualstudio.com
https://{organization_name}.vsblob.visualstudio.com 使用網域的組織使用 {organization_name}.visualstudio.com Azure DevOps 遙測
https://{organization_name}.vsrm.visualstudio.com 使用網域的組織 {organization_name}.visualstudio.com Release Management服務
https://{organization_name}.vssps.visualstudio.com 使用 {organization_name}.visualstudio.com 網域的組織使用 Azure DevOps Platform Services
https://{organization_name}.vstmr.visualstudio.com 使用 {organization_name}.visualstudio.com 網域的組織使用 Azure DevOps 測試管理服務
https://*.blob.core.windows.net Azure Artifacts
https://*.dev.azure.com 針對使用網域的組織 dev.azure.com
https://*.vsassets.io 透過 CDN 的 Azure 成品
https://*.vsblob.visualstudio.com 使用網域的組織使用 dev.azure.com Azure DevOps 遙測
https://*.vssps.visualstudio.com 使用 dev.azure.com 網域的組織使用 Azure DevOps Platform Services
https://*.vstmr.visualstudio.com 使用 dev.azure.com 網域的組織使用 Azure DevOps 測試管理服務
https://app.vssps.visualstudio.com 針對使用網域的組織 {organization_name}.visualstudio.com
https://dev.azure.com 針對使用網域的組織 dev.azure.com
https://login.microsoftonline.com Azure Active Directory 登入
https://management.core.windows.net Azure 管理 API 的
https://vstsagentpackage.azureedge.net 代理程式套件

若要確保您的組織使用任何現有的防火牆或 IP 限制,請確定 dev.azure.com 和 已開啟並 *dev.azure.com 更新允許列出的 IP,以根據您的 IP 版本包含下列 IP 位址。 如果您目前允許列出 13.107.6.18313.107.9.183 IP 位址,請保留這些位址,因為您不需要移除它們。

IPv4 範圍

  • 13.107.6.0/24
  • 13.107.9.0/24
  • 13.107.42.0/24
  • 13.107.43.0/24

IPv6 範圍

  • 2620:1ec:4::/48
  • 2620:1ec:a92::/48
  • 2620:1ec:21::/48
  • 2620:1ec:22::/48

注意

如需允許位址的詳細資訊,請參閱 允許的地址清單和網路連線

如何?使用自我簽署憑證執行代理程式嗎?

使用自我簽署憑證執行代理程式

如何? Web Proxy 後方執行代理程式嗎?

在 Web Proxy 後方執行代理程式

如何?重新開機代理程式

如果您是以互動方式執行代理程式,請參閱 以互動方式執行中的重新開機指示。 如果您是以 systemd 服務的形式執行代理程式,請遵循步驟來 停止 ,然後 啟動 代理程式。

如何?設定代理程式略過 Web Proxy 並聯機到 Azure Pipelines?

如果您想要讓代理程式略過 Proxy 並直接連線到 Azure Pipelines,則您應該設定 Web Proxy 來讓代理程式存取下列 URL。

針對使用網域的組織 *.visualstudio.com

https://login.microsoftonline.com
https://app.vssps.visualstudio.com 
https://{organization_name}.visualstudio.com
https://{organization_name}.vsrm.visualstudio.com
https://{organization_name}.vstmr.visualstudio.com
https://{organization_name}.pkgs.visualstudio.com
https://{organization_name}.vssps.visualstudio.com

針對使用網域的組織 dev.azure.com

https://dev.azure.com
https://*.dev.azure.com
https://login.microsoftonline.com
https://management.core.windows.net
https://vstsagentpackage.azureedge.net
https://vssps.dev.azure.com

若要確保您的組織使用任何現有的防火牆或 IP 限制,請確定 dev.azure.com 和 已開啟並 *dev.azure.com 更新允許列出的 IP,以根據您的 IP 版本包含下列 IP 位址。 如果您目前允許列出 13.107.6.18313.107.9.183 IP 位址,請保留這些位址,因為您不需要移除它們。

IPv4 範圍

  • 13.107.6.0/24
  • 13.107.9.0/24
  • 13.107.42.0/24
  • 13.107.43.0/24

IPv6 範圍

  • 2620:1ec:4::/48
  • 2620:1ec:a92::/48
  • 2620:1ec:21::/48
  • 2620:1ec:22::/48

注意

此程式可讓代理程式略過 Web Proxy。 您的組建管線和腳本仍必須針對您在組建中執行的每個工作和工具,處理略過您的 Web Proxy。

例如,如果您使用 NuGet 工作,您必須設定 Web Proxy 以支援略過裝載您正在使用之 NuGet 摘要的伺服器 URL。

我在上述各節中使用 TFS 和 URL 不適用於我。 我可以在哪裡取得協助?

網站設定和安全性

我使用內部部署 TFS,但看不到其中一些功能。 為什麼不用?

其中部分功能僅適用于 Azure Pipelines ,但尚未提供內部部署。 如果您已 升級至最新版的 TFS,有些功能可在內部部署使用。