一目了然
目標: 在 CI/CD 中整合開發代理
時間: 30分鐘
插件: 各種
前置條件:設定開發代理
在 CI/CD 情境中使用 Dev Proxy 是在受控環境中測試應用程式的絕佳方式。 當您將 Dev Proxy 與在應用程式中產生 API 要求的測試相結合時,可以涵蓋各種不同的情境:從確保應用程式不會使用陰影或非生產 API,到確認其僅使用最低限度的 Microsoft Graph 權限。 雖然確切的設定步驟會根據您的 CI/CD 系統而有所不同,但以下是您應該遵循的一些一般原則。
在大部分情況下,您的執行器未安裝開發代理。 在您可以使用 Dev Proxy 之前,您需要先安裝它。 的安裝步驟 取決於您的執行器所使用的操作系统。
提示
為了加速流水線,您可以考慮對開發 Proxy 的安裝資料夾進行快取。 如此一來,您就不需要在每次執行管道時下載 Dev Proxy。 如需確切步驟,請參閱 CI/CD 系統的文件。
在 CI/CD 設定中安裝 Dev Proxy 時,您通常會想要固定所安裝的 Dev Proxy 版本。 鎖定版本可確保每次執行管線時都使用相同的 Dev Proxy 版本。 釘選版本的確切步驟取決於您的執行環境的作業系統。 以下是如何在以 Linux 為基礎的執行器上鎖定 Dev Proxy 版本的範例:
# install Dev Proxy v1.0.0
bash -c "$(curl -sL https://aka.ms/devproxy/setup.sh)" -- v1.0.0
推薦的 CI 旗標
在 CI/CD 流程中,每次啟動 Dev Proxy 時都用相同的選項,讓它在背景執行,不會改變執行者的設定,也不會等待使用者輸入。 建議您採用下列選項:
| Option | 原因為何 |
|---|---|
--detach |
在背景執行 Dev Proxy,避免阻塞你的管線。 |
--as-system-proxy false |
防止 Dev Proxy 在執行環境上註冊為系統代理。 你的應用程式只有在指向代理時才會使用 Dev Proxy,例如使用 http_proxy 和 https_proxy 環境變數。 |
--install-cert false |
阻止 Dev Proxy 嘗試安裝根憑證。 在管線中,你需要自行信任憑證,如信任 Dev Proxy 根憑證中所述。 |
--no-first-run |
這樣可以跳過首次執行體驗,這對全新的 runner 來說是不需要的。 |
--no-watch |
停用當 Dev Proxy 的設定檔變更時自動重新啟動 Dev Proxy 的功能。 |
另外,在啟動 Dev Proxy 之前,先將 DEV_PROXY_API_TOKEN 環境變數設為你產生的 token。 這樣你就知道要用來呼叫 Dev Proxy API 的令牌,而不必從 Dev Proxy 取回該令牌。 代幣長度必須至少為 32 個字元。 完整需求請參見 代理API。
# generate an API token for this run
export DEV_PROXY_API_TOKEN=$(openssl rand -hex 32)
本文範例使用了這些選項及 DEV_PROXY_API_TOKEN 環境變數。
取得錄製 API 呼叫的設定
如果你想記錄應用程式在 CI 執行時呼叫的 API,不需要從零開始建立設定。 請使用config get以下指令從 Dev Proxy 範例展示區下載預設:api-inventory
./devproxy/devproxy config get api-inventory
預設結合了 UrlDiscoveryPlugin 和 ExecutionSummaryPlugin 與 reporter,並不會將開發代理註冊為系統代理。 啟動 Dev Proxy 時,傳遞預設的設定檔,用應用程式呼叫的 API 覆蓋要監控的 URL,並使用 推薦的 CI 標誌:
./devproxy/devproxy --config-file "~dataFolder/configs/api-inventory/.devproxy/devproxyrc.json" --urls-to-watch "https://api.contoso.com/*" --detach --as-system-proxy false --install-cert false --no-first-run --no-watch
如需更多預設集的相關資訊,請參閱 使用預設組態。
啟動開發代理伺服器
安裝開發 Proxy 之後,您必須啟動它。 在 CI/CD 管線中啟動 Dev Proxy 時,請務必在背景中啟動它。 否則,您的管線會遭到封鎖,直到您停止開發 Proxy 為止。
在背景啟動開發代理,使用 推薦的 CI 標誌:
# start Dev Proxy in detached mode
./devproxy/devproxy --detach --as-system-proxy false --install-cert false --no-first-run --no-watch
開發代理會列印啟動資訊,包括程序 ID(PID)、代理 URL、API URL 及日誌檔案路徑:
Dev Proxy started in background.
PID: 6456
Proxy URL: http://127.0.0.1:8000
API URL: http://127.0.0.1:8897
Log file: /home/runner/.local/dev-proxy/logs/devproxy-6456-2026-03-05.log
機器可讀輸出時,請使用 --output json 以取得 JSONL:
./devproxy/devproxy --detach --as-system-proxy false --install-cert false --no-first-run --no-watch --output json
{"type":"result","data":{"pid":6456,"proxyUrl":"http://127.0.0.1:8000","apiUrl":"http://127.0.0.1:8897","logFile":"/home/runner/.local/dev-proxy/logs/devproxy-6456-2026-03-05.log"},"timestamp":"2026-03-05T14:22:42.0000000Z"}
提示
用 --port 0 和 --api-port 0 讓作業系統隨機分配可用埠口。 分離模式輸出顯示作業系統實際分配的埠,這在 CI/CD 情境中有助於避免埠衝突。 使用隨機埠時,請從輸出讀取代理 URL 和 API URL,而不是如http://127.0.0.1:8897所示使用預設的 和 http://127.0.0.1:8000。
或者,如果你使用的是基於 Linux 的運行程式,也可以在背景使用 shell 工作控制啟動 Dev Proxy:
# start Dev Proxy in the background
./devproxy/devproxy --as-system-proxy false --install-cert false --no-first-run --no-watch > devproxy.log 2>&1 &
等待開發代理伺服器啟動
當你在背景啟動 Dev Proxy 時,腳本會立即繼續執行。 不過,開發 Proxy 需要一些時間才能開始。 為了確保 Dev Proxy 在開始發出請求前已經準備好,請等其 API 回應對 GET /proxy 的請求:
api_url=http://127.0.0.1:8897
echo "Waiting for Dev Proxy to start..."
until curl -sf -o /dev/null "$api_url/proxy" -H "Authorization: Bearer $DEV_PROXY_API_TOKEN"; do
sleep 1
done
# the rest of your script
無論開發代理監聽的是哪個埠,輪詢 API 都會正常運作,包括使用 --port 0 時。
信任開發代理伺服器根證書
Dev Proxy 啟動後,你需要信任 Dev Proxy 的根憑證才能發送請求,因為 Dev Proxy 使用自簽的根憑證。
根據你的權限,你可能需要在啟動 Dev Proxy 前建立 ~/.config/dev-proxy/rootCert 資料夾,Dev Proxy 會將其根憑證儲存在其中:
# ensure the rootCert folder
echo "Ensuring the Dev Proxy rootCert folder"
mkdir -p ~/.config/dev-proxy/rootCert
要取得根憑證的公鑰,請使用 Dev Proxy API 下載它。 如果你使用的是基於 Linux 的執行器,你可以將憑證複製到系統受信任的 CA 憑證儲存庫來安裝:
# download the Dev Proxy's Root Certificate
echo "Downloading the Dev Proxy's Root Certificate"
curl -sf -o dev-proxy-ca.crt "$api_url/proxy/rootCertificate?format=crt" -H "Authorization: Bearer $DEV_PROXY_API_TOKEN"
# install root certificate
echo "Installing the Dev Proxy's Root Certificate"
sudo cp dev-proxy-ca.crt /usr/local/share/ca-certificates/
# update CA certificates
echo "Updating the CA certificates"
sudo update-ca-certificates
設定 Proxy 環境變數
許多應用程式和連結庫都會使用 http_proxy 和 https_proxy 環境變數來判斷要用於 HTTP 和 HTTPS 要求的 Proxy 伺服器。 因為你使用 --as-system-proxy false 啟動 Dev Proxy,你需要設定這些環境變數指向 Dev Proxy 實例,以確保你的應用程式使用 Dev Proxy。
export http_proxy=http://127.0.0.1:8000
export https_proxy=http://127.0.0.1:8000
控制開發人員 Proxy
當您在 CI/CD 管線中執行開發 Proxy 時,您無法以互動方式控制它。 相反地,您可以將要求傳送至 開發 Proxy API 來控制它。
所有開發代理 API 請求都需要在標頭中 Authorization 放置承載憑證。 如果你已依建議設定 DEV_PROXY_API_TOKEN 環境變數,請使用其值。 否則,因為 Dev Proxy 當設定 CI 環境變數時啟動時不會列印權杖,請使用 API 令牌 指令擷取:
export DEV_PROXY_API_TOKEN=$(./devproxy/devproxy api token)
如果你想分析應用程式發出的 API 請求,可以向 /proxy 端點發送 POST 請求,以開始記錄:
curl -sf -X POST "$api_url/proxy" -H "Authorization: Bearer $DEV_PROXY_API_TOKEN" -H "Content-Type: application/json" -d '{"recording": true}'
要停止錄影,請向/proxy端點發送POST請求,並將recording設為false:
curl -sf -X POST "$api_url/proxy" -H "Authorization: Bearer $DEV_PROXY_API_TOKEN" -H "Content-Type: application/json" -d '{"recording": false}'
若要停止 Dev Proxy,您可以將POST要求傳送至/proxy/stopproxy端點:
curl -sf -X POST "$api_url/proxy/stopproxy" -H "Authorization: Bearer $DEV_PROXY_API_TOKEN"
停止 Dev Proxy 過程之後,可能需要一些時間才能完全關閉。 為了確保 Dev Proxy 已結束,請等待其記錄檔(Dev Proxy 在分離模式下啟動時會列印)包含其中一個完成訊息,例如:
echo "Waiting for Dev Proxy to complete..."
while true; do
if grep -q -e "DONE" -e "No requests to process" -e "An error occurred in a plugin" "$log_file"; then
break
fi
sleep 1
done
當所有錄製外掛程式都執行完畢時,Dev Proxy 會將 DONE 訊息列印至輸出。 如果沒有處理要求,Dev Proxy 會列印 No requests to process 訊息。 如果外掛程式發生錯誤,Dev Proxy 會列印 An error occurred in a plugin 訊息。 當您看到上述任何訊息時,您可以確定 Dev Proxy 已完成處理記錄的要求。
範例啟動腳本
這裡有一個 bash 腳本的範例,可以用來啟動 CI/CD 管線中的 Dev Proxy。 腳本使用 建議的 CI 標誌,從 JSON 輸出讀取代理 URL、API URL 和日誌檔案路徑,等待開發代理 API 回應,並信任從 API 下載的根憑證。 它用 jq 來解析 JSON 輸出。
echo "Generating the Dev Proxy API token"
export DEV_PROXY_API_TOKEN=$(openssl rand -hex 32)
echo "Ensuring Dev Proxy rootCert folder"
mkdir -p ~/.config/dev-proxy/rootCert
echo "Starting Dev Proxy"
result=$(./devproxy/devproxy --detach --as-system-proxy false --install-cert false --no-first-run --no-watch --output json | jq -c 'select(.type == "result")')
if [ -z "$result" ]; then
echo "Failed to start Dev Proxy"
exit 1
fi
proxy_url=$(echo "$result" | jq -r '.data.proxyUrl')
api_url=$(echo "$result" | jq -r '.data.apiUrl')
log_file=$(echo "$result" | jq -r '.data.logFile')
echo "Waiting for Dev Proxy to start..."
until curl -sf -o /dev/null "$api_url/proxy" -H "Authorization: Bearer $DEV_PROXY_API_TOKEN"; do
sleep 1
done
echo "Downloading the Dev Proxy's Root Certificate"
curl -sf -o dev-proxy-ca.crt "$api_url/proxy/rootCertificate?format=crt" -H "Authorization: Bearer $DEV_PROXY_API_TOKEN"
echo "Installing the Dev Proxy's Root Certificate"
sudo cp dev-proxy-ca.crt /usr/local/share/ca-certificates/
echo "Updating the CA certificates"
sudo update-ca-certificates
echo "Set proxy variables"
export http_proxy=$proxy_url
export https_proxy=$proxy_url