概览
目标: 在 CI/CD 中集成开发代理
时间: 30 分钟
插件: 各种
先决条件:设置开发代理
在 CI/CD 方案中使用开发代理是一种在受控环境中测试应用程序的好方法。 将 Dev Proxy 与在应用程序中生成 API 请求的测试相结合时,可以涵盖各种场景:从确保应用不使用影子或非生产环境 API,到检查其是否使用最少的 Microsoft Graph 权限。 虽然确切的配置步骤因 CI/CD 系统而异,但应遵循一些一些一般原则。
在大多数情况下,运行器未安装 Dev Proxy。 因此,在使用 Dev Proxy 开发代理工具之前,您需要安装它。 安装步骤取决于运行程序使用的操作系统。
小窍门
若要加快管道速度,请考虑缓存开发代理安装文件夹。 这样,每次运行管道时都不需要下载开发代理。 有关确切步骤,请参阅 CI/CD 系统的文档。
在 CI/CD 安装中安装开发代理时,通常需要固定所安装的开发代理版本。 固定版本可确保每次运行管道时都使用相同的开发代理版本。 固定版本的确切步骤取决于运行器的操作系统。 下面是如何在 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,以便它在后台运行,不会更改运行器的配置,也不会等待用户输入。 我们建议使用以下选项:
| 选项 | 为什么 |
|---|---|
--detach |
在后台运行开发代理,这样就不会阻塞管道。 |
--as-system-proxy false |
防止开发代理在运行器上将自身注册为系统代理。 你的应用仅在指向代理时使用 Dev Proxy,例如使用 http_proxy 和 https_proxy 环境变量。 |
--install-cert false |
阻止开发代理尝试安装其根证书。 在管道中,你自己信任证书,如 “信任 Dev Proxy 根证书”中所述。 |
--no-first-run |
跳过第一次运行体验,这在新的运行器上不需要。 |
--no-watch |
禁用在其配置文件更改时自动重启开发代理。 |
此外,在启动开发代理之前,请将 DEV_PROXY_API_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 命令从开发代理示例库下载 api-inventory 预设:
./devproxy/devproxy config get api-inventory
预设将 UrlDiscoveryPlugin 和 ExecutionSummaryPlugin 与报告器合并,并且不会将开发代理注册为系统代理。 启动 Dev Proxy 时,传递预设的配置文件,将要监视的 URL 替换为应用调用的 API,并使用 建议的 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
有关预设的详细信息,请参阅 使用预设配置。
启动开发代理
安装开发代理后,需要启动它。 在 CI/CD 管道中启动开发代理时,请务必在后台启动它。 否则,您的管道将被阻塞,直到停止 Dev 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 允许 OS 分配随机可用的端口。 分离模式输出显示 OS 分配的实际端口,这在 CI/CD 方案中非常有用,以避免端口冲突。 使用随机端口时,请从输出中读取代理 URL 和 API URL,而不是使用默认值 http://127.0.0.1:8000 和 http://127.0.0.1:8897,如 示例启动脚本 中所示。
或者,如果使用基于 Linux 的运行程序,则可以使用 shell 作业控件在后台启动开发代理:
# 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 在开始发出请求之前准备就绪,请等待其 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时。
信任开发代理根证书
开发代理启动后,需要在发送请求之前信任开发代理根证书,因为开发代理使用自签名根证书。
根据你的权限,在启动开发代理之前,可能需要创建 ~/.config/dev-proxy/rootCert 文件夹,开发代理会在该文件夹中存储其根证书:
# 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
配置代理环境变量
许多应用程序和库使用 http_proxy 环境变量 https_proxy 来确定要用于 HTTP 和 HTTPS 请求的代理服务器。 由于使用开发代理 --as-system-proxy false启动,因此需要将这些环境变量设置为指向开发代理实例,以确保应用程序使用开发代理。
export http_proxy=http://127.0.0.1:8000
export https_proxy=http://127.0.0.1:8000
控制开发代理
在 CI/CD 管道中运行开发代理时,无法以交互方式控制它。 相反,可以通过向 开发代理 API 发送请求来控制它。
所有开发代理 API 请求都需要在 Authorization 标头中提供 Bearer 令牌。 如果按建议设置 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}'
若要停止录制,请发送一个POST请求到/proxy终结点,并将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"
停止开发代理进程后,它可能需要花费一段时间才能完全关闭。 若要确保开发代理已完成,请等待其日志文件(开发代理在分离模式下启动时会打印该文件)中包含其中一条完成消息,例如:
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
所有录制插件都运行完毕后,开发代理会将 DONE 消息输出。 如果没有要处理的请求,开发代理服务器会打印 No requests to process 消息。 如果插件中出现错误,开发代理将输出 An error occurred in a plugin 消息。 看到这些消息中的任何一条消息时,可以确保开发代理已完成处理记录的请求。
示例启动脚本
下面是可用于在 CI/CD 管道中启动 Dev Proxy 的 bash 脚本的示例。 该脚本使用 建议的 CI 标志,从 JSON 输出中读取代理 URL、API URL 和日志文件路径,等待 Dev Proxy 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