自託管的 macOS 代理程式

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

若要建置及部署 Xcode 應用程式，您需要至少一個 macOS 代理程式。 此代理程式也可以建置及部署 Java 和 Android 應用程式。

瞭解代理人

如果您已經知道什麼是代理及其運作方式，可以直接閱讀下列各節。 但是，如果您想要更多有關其職責內容及運作方式的背景資訊，請參閱 Azure Pipelines 代理程式。

檢查必要條件

• 支援的作業系統
  • x64
    • macOS 10.15 “Catalina”
    • macOS 11.0 “Big Sur”
    • macOS 12.0 “Monterey”
    • macOS 13.0 “Ventura”
    • macOS 14.0 “Sonoma”
  • ARM64
    • macOS 11.0 “Big Sur”
    • macOS 12.0 “Monterey”
    • macOS 13.0 “Ventura”
    • macOS 14.0 “Sonoma”

• Git - Git 2.9.0 或更高版本 （建議使用最新版本 - 您可以使用 Homebrew輕鬆安裝 ）

• .NET - 代理程式軟體會在 .NET 6 上執行，但會安裝自己的 .NET 版本，因此沒有 .NET 必要條件。
• TFVC - 如果您要從 TFVC 存放庫建置，請參閱 TFVC 必要條件。

準備權限設定

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

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

自行架設代理程式的資訊安全

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

代理程式所控制的資料夾應限制為盡可能少的使用者，因為它們包含可以解密或外洩的秘密。

Azure Pipelines 代理程式是一種軟體產品，其設計目的是執行從外部來源下載的程序代碼。 它本質上可能是遠端程式代碼執行 （RCE） 攻擊的目標。

因此，請務必考慮每一次使用管線代理的威脅模型，以及針對不同的執行案例，決定授予負責執行代理的使用者的最低許可權、代理執行所在的機器、擁有管線定義寫入權限的使用者、存放 yaml 的 git 倉庫，及控制新管線集區存取權的使用者群組。

最佳做法是讓執行代理程式的身分識別與具有將代理程式連線到集區之許可權的身分識別不同。 產生認證的使用者（和其他代理程式相關檔案）與需要讀取認證的使用者不同。 因此，請務必仔細考慮對代理機器本身及包含敏感檔案（例如日誌和文件）的代理資料夾授予的存取權限。

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

選擇您要使用的帳戶

您必須進行一次性的代理註冊。 有權 管理代理程式佇列 的人員必須完成這些步驟。 代理人不會在日常運作中使用此人的認證，但需要完成註冊。 深入瞭解 代理如何進行溝通。

確認使用者具有許可權

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

使用者是 Azure DevOps 組織擁有者或 TFS 或 Azure DevOps Server 系統管理員嗎？ 停止這裡，您有許可權。

否則：

1. 開啟瀏覽器並前往 Azure Pipelines 組織、Azure DevOps Server 或 TFS 伺服器的 Agent 集區 標籤頁：

   1. 登入您的組織（https://dev.azure.com/{yourorganization}）。

   2. 選擇 Azure DevOps，[組織設定]。

      

   3. 選擇 代理池。

      

   1. 登入您的專案集合 （http://your-server/DefaultCollection）。

   2. 選擇 Azure DevOps集合設定。

      

   3. 選擇 Agent 集區。

      

   1. 選擇 Azure DevOps集區設定。

      

   2. 選擇 代理集區。

      

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

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

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

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

下載並設定代理程式

伺服器 URL

驗證類型

當您註冊代理程式時，請選擇下列驗證類型，而代理程式設定會提示您輸入每個驗證類型所需的特定其他資訊。 如需詳細資訊，請參閱 自我托管代理驗證選項。

以互動方式執行

如需有關在互動模式或服務模式上執行代理程序的指引，請參閱 代理程式：互動模式 vs. 服務模式。

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

1. 如果您已以服務身分執行代理程式，卸載服務。

2. 執行代理程式。

   ./run.sh
   

若要重新啟動代理程式，請按 Ctrl+C，然後執行 run.sh 以重新啟動它。

若要使用代理程式，請使用代理程式的資源池來執行 作業。 如果您未選擇不同的集區，您的代理程式會放在 預設 集區中。

執行一次

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

./run.sh --once

此模式中的代理程式僅接受一項工作，然後優雅地關閉（這對於在 Azure Container Instances 等服務上執行非常有用）。

以已啟動的服務身分執行

我們提供 ./svc.sh 腳本，讓您以 launchd LaunchAgent 服務的形式執行和管理代理程式。 此文稿會在您設定代理程序之後產生。 服務可以存取 UI 來執行 UI 測試。

令牌

在下一節中，會取代這些令牌：

• {agent-name}

• {tfs-name}

例如，您已配置了一個名叫 our-osx-agent的代理程式（如上一個範例所示）。 在下列範例中，{tfs-name} 可以是：

• Azure Pipelines：您組織的名稱。 例如，如果您連線到 https://dev.azure.com/fabrikam，則服務名稱會 vsts.agent.fabrikam.our-osx-agent

• TFS：內部部署 TFS AT 伺服器的名稱。 例如，如果您連線到 http://our-server:8080/tfs，則服務名稱會 vsts.agent.our-server.our-osx-agent

命令

變更為代理目錄

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

cd ~/myagent$

安裝

命令：

./svc.sh install

此命令會建立指向 ./runsvc.sh的 launchd plist。 此腳本會設定環境（下一節中的詳細數據），並啟動代理程式的主機。

開始

命令：

./svc.sh start

輸出：

starting vsts.agent.{tfs-name}.{agent-name}
status vsts.agent.{tfs-name}.{agent-name}:

/Users/{your-name}/Library/LaunchAgents/vsts.agent.{tfs-name}.{agent-name}.plist

Started:
13472 0 vsts.agent.{tfs-name}.{agent-name}

如果服務正在執行，左邊的數字是 pid。 如果第二個數位不是零，則發生問題。

地位

命令：

./svc.sh status

輸出：

status vsts.agent.{tfs-name}.{agent-name}:

/Users/{your-name}/Library/LaunchAgents/vsts.{tfs-name}.{agent-name}.testsvc.plist

Started:
13472 0 vsts.agent.{tfs-name}.{agent-name}

如果服務正在執行，則左邊的數字是 pid。 如果第二個數位不是零，則發生問題。

停

命令：

./svc.sh stop

輸出：

stopping vsts.agent.{tfs-name}.{agent-name}
status vsts.agent.{tfs-name}.{agent-name}:

/Users/{your-name}/Library/LaunchAgents/vsts.{tfs-name}.{agent-name}.testsvc.plist

Stopped

卸載

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

命令：

./svc.sh uninstall

自動登入和鎖定

一般而言，代理程式服務只會在使用者登入之後執行。 如果您希望代理程式服務在機器重新啟動時自動啟動，您可以將電腦設定為在啟動時自動登入和鎖定。 請參閱 將 Mac 設定為啟動期間自動登入 - Apple 支援服務。

更新環境變數

當您設定服務時，它會為目前的登入使用者擷取一些實用的環境變數快照，例如PATH、LANG、JAVA_HOME、ANT_HOME和MYSQL_PATH。 如果您需要更新變數（例如，安裝一些新軟體之後）：

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

環境變數的快照集會儲存在代理程式根目錄下的 .env 檔案中，您也可以直接變更該檔案以套用環境變數變更。

在服務啟動之前執行指示

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

1. 編輯 runsvc.sh。

2. 使用您的指示取代下列這一行：

   # insert anything to setup env when running as a service
   

服務檔案

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

.plist 服務檔案

已建立 .plist 服務檔案：

~/Library/LaunchAgents/vsts.agent.{tfs-name}.{agent-name}.plist

例如：

~/Library/LaunchAgents/vsts.agent.fabrikam.our-osx-agent.plist

./svc.sh install 從此範本產生此檔案：./bin/vsts.agent.plist.template

.service 檔案

./svc.sh start 讀取 .service 檔案來尋找服務，其中包含上述 plist 服務檔案的路徑。

替代服務機制

我們提供 ./svc.sh 腳本，讓您以 launchd LaunchAgent 服務的方式執行和管理代理程式。 但是，您可以使用任何偏好的服務機制。

您可以使用上述範本來協助產生其他類型的服務檔案。 例如，如果您不需要UI測試，而且不想設定自動登入和鎖定，您可以修改範本來產生以啟動精靈的形式執行的服務。 請參閱 Apple 開發人員連結庫：建立啟動精靈和代理程式。

取代代理人

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

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

拿掉並重新設定代理程式

若要移除代理程式：

1. 停止並卸載服務，如上一節所述。

2. 拿掉代理程式。

   ./config.sh remove
   

3. 輸入您的認證。

移除代理程序之後，您可以再次設定它 。

無人值守設定

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

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

診斷

如果您在使用自行裝載的代理程式時遇到問題，您可以嘗試執行診斷。 設定代理程式之後：

./run.sh --diagnostics

這會透過診斷套件執行，以協助您針對問題進行疑難解答。 診斷功能可從代理程式 2.165.0 版開始使用。

其他選項的說明

若要瞭解其他選項：

./config.sh --help

說明提供有關驗證替代方案和無人值守配置的資訊。

能力

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

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

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

常見問題

如何確定我有最新的代理程式版本？

1. 瀏覽至 [代理程式集區] 標籤頁：

   1. 登入您的組織（https://dev.azure.com/{yourorganization}）。

   2. 選擇 Azure DevOps，[組織設定]。

      

   3. 選擇 Agent 集區。

      

   1. 登入您的專案集合 （http://your-server/DefaultCollection）。

   2. 選擇 Azure DevOps，集合設定。

      

   3. 選擇 代理程式集區。

      

   1. 選擇 Azure DevOps，集合設定。

      

   2. 選擇 Agent 集區。

      

2. 點擊包含代理的集區。

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

4. 瀏覽至 [功能] 頁籤：

   1. 從 [代理集區] 索引標籤中，選取所需的代理集區。

      

   2. 選取 代理人 並選擇所需的代理人。

      

   3. 選擇 [功能] 選項卡。

      

      注意

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

   1. 從 [Agent 集區] 分頁中，選取所需的集區。

      

   2. 選取 代理程式 並選擇所需的代理程式。

      

   3. 選擇「功能」標籤。

      

   1. 從 [代理集區] 選項卡中，選取所需的代理集區。

      

   2. 選取 代理 並選擇所需的代理。

      

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

      

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

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

如何確定我有最新的代理程式版本？

1. 瀏覽至 代理集區 標籤：

   1. 登入您的組織（https://dev.azure.com/{yourorganization}）。

   2. 選擇 Azure DevOps，[組織設定]。

      

   3. 選擇 Agent 集區。

      

   1. 登入您的專案集合 （http://your-server/DefaultCollection）。

   2. 選擇 Azure DevOps，集區設定。

      

   3. 選擇 Agent 集區。

      

   1. 選擇 Azure DevOps中的 集合設定。

      

   2. 選擇 代理集區。

      

2. 點擊包含代理程式的集區。

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

4. 瀏覽至 [功能] 索引標籤：

   1. 從 [代理集區] 標籤中，選取所需的代理集區。

      

   2. 選取 代理人 並選擇所需的代理人。

      

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

      

      注意

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

   1. 從 [Agent 工作池] 標籤中，選取所需的工作池。

      

   2. 選擇 代理程式 並選擇所需的代理程式。

      

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

      

   1. 從 [Agent 集區] 標籤中，選取所需的集區。

      

   2. 選取 [代理程式 並選擇所需的代理程式。

      

   3. 選擇 功能 索引標籤。

      

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

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

我可以在哪裡深入瞭解已啟動的服務運作方式？

Apple 開發人員連結庫：建立啟動精靈和代理程式

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

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

如何在 Web Proxy 後方執行代理程式？

在網路代理伺服器後面執行代理程式

如何重新啟動代理程式

如果您是以互動方式執行代理程式，請參閱 以互動方式執行中的重新啟動指示。 如果您以服務身分執行代理程式，請依照步驟 停止，然後 啟動 代理程式。

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

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

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