在开发容器和 GitHub Codespaces 中使用 Dev Proxy

概览
目标:在开发容器或 GitHub Codespaces 中安装 Dev Proxy
时间: 10 分钟
先决条件:包含 devcontainer.json 文件的项目、Docker 或 GitHub Codespaces

如果在开发容器或GitHub Codespaces中开发,则可以使用 Dev Proxy Dev Container Feature 安装 Dev Proxy。 该功能在容器中安装开发代理,并在创建容器后生成容器唯一的开发代理根证书并信任它。 无需按照 首次运行步骤 自行信任证书。

将 Dev Proxy 功能添加到开发容器

若要在开发容器中安装 Dev Proxy,请将 Dev Proxy 功能添加到 .devcontainer/devcontainer.json 文件的 features 部分:

{
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/dotnet/dev-proxy/dev-proxy:1": {}
  }
}

重新生成容器或创建新的代码空间以应用更改。 容器启动后,验证是否已安装 Dev Proxy:

devproxy --version

注意

该功能独立于 Dev Proxy 进行版本控制。 ghcr.io/dotnet/dev-proxy/dev-proxy:1 是指该功能的版本 1。 若要选择要安装的 Dev Proxy 版本,请使用 version 此选项。

配置该功能

此功能支持以下选项:

选项 Description 类型 默认
version 要安装的 Dev Proxy 版本:latest、beta或特定版本,例如 4.0.0 或 v4.0.0。 字符串 latest
trustCertificate 创建容器后,生成容器专用的开发代理根证书,并将其设为系统范围受信任,同时使常见运行时也信任它。 boolean true

例如,若要安装特定版本的 Dev Proxy,请使用以下配置:

{
  "features": {
    "ghcr.io/dotnet/dev-proxy/dev-proxy:1": {
      "version": "4.0.0"
    }
  }
}

若要尝试最新的预览功能,请将 version 设置为 beta。 安装 beta 版本时,该功能还会添加 devproxy-beta 命令。

如果在共享开发容器配置中使用 Dev Proxy,请考虑将 Dev Proxy 固定到特定版本,而不是 latest 或 beta。 这样,可确保处理项目的每个人都使用相同版本的 Dev Proxy。

功能如何处理根证书

开发代理使用根证书解密 HTTPS 流量。 生成映像时,该功能不会生成证书。 如果确实如此,证书及其私钥最终将出现在映像层中,并且使用同一映像或 Codespaces 预构建的每个人都会共享相同的受信任 CA 证书。

相反,在创建容器后 (postCreateCommand),该功能:

  1. 以远程用户身份运行 devproxy cert ensure,以生成该容器专有的根证书。
  2. 将证书添加到系统证书存储(/usr/local/share/ca-certificates),以便 curl、.NET 和其他使用系统存储的工具信任它。

某些运行时不使用系统证书存储,因此功能会设置以下环境变量,使其指向系统 CA 捆绑包(/etc/ssl/certs/ca-certificates.crt):

可变 使用者
NODE_EXTRA_CA_CERTS Node.js
REQUESTS_CA_BUNDLE Python requests
SSL_CERT_FILE Python和其他基于 OpenSSL 的工具

为了信任证书,该功能会安装一个归 root 所有的帮助程序脚本,并允许远程用户在不使用密码的情况下使用 sudo 运行它。 如果不希望该功能生成并信任证书,请将trustCertificate设置为false:

{
  "features": {
    "ghcr.io/dotnet/dev-proxy/dev-proxy:1": {
      "trustCertificate": false
    }
  }
}

重要

此功能不会配置Java密钥存储,因此Java应用不信任开发代理根证书。

Python 3.13 及更新版本启用严格的证书验证,这将拒绝 Dev Proxy v3 及更早版本为截获的主机生成的证书。 若要从 Python 3.13 或更高版本通过 Dev Proxy 调用 API,请使用 Dev Proxy v4 或更高版本。

在开发容器中使用 Dev Proxy

该功能不会启动开发代理,也不会为整个容器设置 HTTP_PROXY 或 HTTPS_PROXY 环境变量。 容器范围的代理变量将通过开发代理路由包管理器、git 和 VS Code 自己的流量,这会在开发代理未运行时中断它们。

若要使用 Dev Proxy,请使用配置文件在开发容器的终端中启动它:

devproxy --config-file .devproxy/devproxyrc.json

然后,配置要测试的应用以使用 Dev Proxy。 例如,若要通过开发代理从 Node.js 应用路由请求,请使用 HTTPS_PROXY 环境变量启动应用:

HTTPS_PROXY=http://127.0.0.1:8000 npm start

有关将应用配置为使用 Dev Proxy 的详细信息,请参阅适用于您的堆栈的指南,例如 将 Dev Proxy 与 Node.js 应用程序配合使用 或 将 Dev Proxy 用于 .NET 应用程序。

开发者代理工具包

此功能将 Dev Proxy Toolkit 扩展添加到开发容器内的 VS Code 中。 如果不想安装扩展,请在你的devcontainer.json文件中排除它:

{
  "features": {
    "ghcr.io/dotnet/dev-proxy/dev-proxy:1": {}
  },
  "customizations": {
    "vscode": {
      "extensions": ["-garrytrinder.dev-proxy-toolkit"]
    }
  }
}

支持的图像

此功能支持 x64 和 arm64 上的基于 Debian 和 Ubuntu 的映像。 不支持 Alpine 和其他基于 musl 的镜像。

另请参阅