Docker Sandboxes

本页介绍本地沙箱、本地守护进程，以及宿主机 CLI 连接到云沙箱时的代理设置。这些设置 不涉及云沙箱内部产生的流量。关于云沙箱的出站流量控制，请参阅 云网络策略。

IMPORTANT

上游代理支持仍处于实验阶段。本页描述的所有内容——代理 URL、PAC 文件、SOCKS5、 使用操作系统系统代理、代理身份验证以及配置它们的设置——都可能发生变化。请在 docker/sbx-releases 仓库中反馈意见和报告缺陷。

上游代理是企业或网络代理，Docker Sandboxes 把出站流量转发到互联网时经过它。它与 网络策略不同，后者决定允许访问_哪些_目标地址，上游代理则决定允许的流量_如何_到达 这些地址。关于如何设置网络策略，请参阅 沙箱治理。

Docker Sandboxes 会发送两类出站流量，你可以分别对它们配置代理：

  • 沙箱流量——来自本地沙箱内部的网络访问。
  • 守护进程和宿主机 CLI 流量——守护进程自身的访问，包括镜像拉取、遥测和功能标志， 以及宿主机 CLI 请求，包括 sbx login、sbx diagnose --upload、云命令、sbx move、 TUI 和云 SSH。

默认行为 ​

默认情况下，两类流量都使用你操作系统的代理设置，包括其中配置的任何 PAC URL。你 不需要做任何配置。在 macOS 和 Windows 上，sbx 运行期间会跟踪操作系统的代理设置， 因此网络、VPN 或 PAC 配置的变更无需重启即可生效。如果你的操作系统没有配置代理， 流量将直连。

手动设置代理 ​

用 sbx settings set 覆盖某一类或两类流量的默认行为：

console
$ sbx settings set proxy http://proxy.corp:3128          # 两类流量
$ sbx settings set proxy.sandbox socks5://proxy.corp:1080 # 仅沙箱流量
$ sbx settings set proxy.daemon direct                    # 仅守护进程流量

代理值可以是以下任意一种：

值含义
(未设置)回退到更宽的作用域，然后是环境变量，最后是操作系统系统代理（默认行为）
http://host:port 或 https://host:portHTTP 或 HTTPS 代理
socks5://host:port 或 socks5h://host:portSOCKS5 代理
pac+http://host/proxy.pac、pac+https://host/proxy.pac 或 file:///path/proxy.pacPAC（代理自动配置）文件
system强制使用操作系统系统代理
direct强制直连，不使用代理

使用 socks5:// 时，DNS 在本地解析，然后连接才交给代理。使用 socks5h:// 时， DNS 解析交给代理完成。

把目标地址排除在代理之外 ​

排除列表与上述作用域一一对应。每个列表接受以逗号分隔的主机名、域名后缀、IP 地址 或 CIDR 范围，也可以用 * 完全绕过代理：

console
$ sbx settings set no_proxy "*.internal.corp,10.0.0.0/8"    # 两类流量
$ sbx settings set no_proxy.sandbox "*.svc.cluster.local"   # 仅沙箱流量
$ sbx settings set no_proxy.daemon "registry.internal"      # 仅守护进程流量

环境变量 ​

由于 sbx 从你的 shell 中运行，它同样遵循标准的和旧式的代理环境变量，因此现有配置 无需迁移即可继续工作：

  • HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY（以及它们的小写形式）——标准变量。在 没有配置 proxy 或 no_proxy 设置时，它们同时作用于两类流量。
  • DOCKER_SANDBOXES_PROXY 和 DOCKER_SANDBOXES_NO_PROXY——proxy.sandbox 和 no_proxy.sandbox 的环境变量形式。它们仅作用于沙箱流量，绝不影响守护进程流量。

关于如何把环境变量的变更应用到 CLI 和守护进程，请参阅 设置环境变量。

优先级 ​

对每一类流量，最先匹配的生效：

  1. 特定作用域的值：
    • 沙箱流量用 proxy.sandbox 或 DOCKER_SANDBOXES_PROXY
    • 守护进程流量用 proxy.daemon
  2. proxy 设置
  3. shell 中的 HTTP_PROXY 或 HTTPS_PROXY
  4. 操作系统系统代理（默认行为）
  5. 直连

匹配的排除列表（先 no_proxy.<scope>，再 no_proxy）适用于选定的代理；在走环境 变量这条路径时，标准的 NO_PROXY 变量仍然生效。

例如，如果 proxy 指定了一个共享代理，而 proxy.sandbox 被设为 direct，那么沙箱 流量直连，而守护进程流量使用共享代理。如果没有配置任何代理设置，HTTP_PROXY 的 优先级高于操作系统系统代理。

变更何时生效 ​

代理设置根据使用方的不同在不同时机生效：

  • 沙箱作用域（proxy.sandbox、no_proxy.sandbox，以及 proxy 和 no_proxy 的沙箱 一侧）在创建沙箱网络代理时解析。变更之后创建的沙箱会使用更新后的设置。已有沙箱 会保留其选定的上游代理，直到 sbx daemon restart 重建它们的网络代理。仅重启沙箱 是不够的。
  • 守护进程作用域（proxy.daemon、no_proxy.daemon，以及 proxy 和 no_proxy 的 守护进程一侧）在守护进程启动时解析一次。要改变守护进程自身的流量，需要执行 sbx daemon restart。
  • 宿主机 CLI 客户端在每次调用时读取守护进程作用域的设置。变更会在下次调用时生效， 无需重启守护进程。

DOCKER_SANDBOXES_* 环境变量是另一种情况。如 环境变量所述，它们只控制沙箱流量，但 sbx 是在守护进程 启动时从守护进程的环境中读取它们的，因此更改这些变量同样需要重启守护进程。如果 其中某个变量覆盖了已存储的设置，请取消该变量并重启守护进程，让已存储的设置生效。

使用 system 或 PAC 代理时，sbx 仍会实时跟踪操作系统层面的代理变化（例如切换 网络、连接 VPN 或 PAC 内容更新）。

宿主机的网络变更也可能让已建立的沙箱连接停滞。要调整或禁用关闭这些连接的超时时间， 请参阅 egress.stalledConnectionTimeoutSeconds。

云 SSH ​

云 SSH 使用配置的宿主机代理连接 SSH 网关。有些代理会拒绝连向网关 SSH 端口的连接。 如果你的网络允许直接 SSH 连接，请为云 SSH 绕过代理：

console
$ sbx settings set proxy.sshDirect true

该设置会完全跳过代理用于云 SSH，不会先尝试连接代理。宿主机 CLI 的其他请求仍使用 配置的代理。该变更在下一次 SSH 连接时生效，无需重启守护进程。将其设为 false 即可 重新使用代理。

身份验证 ​

如果上游代理要求你进行身份验证，sbx 支持两种机制。

代理 URL 中的凭据 ​

把凭据放进代理 URL：HTTP 或 HTTPS 代理用 http://user:pass@host:port，SOCKS5 用 socks5://user:pass@host:port。这在所有平台上都可用，也适用于使用 Basic 身份验证 发起质询的代理。

集成式 Windows 身份验证 ​

对 CONNECT 返回 407 质询、且只接受集成式方案（NTLM 或 Kerberos/Negotiate）的 代理，可以使用你的 Windows 登录身份进行验证。该功能需要显式启用，默认关闭：

console
$ sbx settings set proxy.integratedAuth true

该设置没有作用域划分：它同时作用于沙箱流量和守护进程流量。如果代理提供多种方案， 会使用其中最强的一种，优先选择 Negotiate 而非 NTLM。变更遵循与其他代理设置相同的 生效时机：对于受支持的 CLI 客户端在下一次调用时生效， 在你创建沙箱时生效，而守护进程流量和已有沙箱的代理则需要 sbx daemon restart 之后 才生效。

你的身份始终留在宿主机上。对上游代理的身份验证发生在沙箱边界的宿主机一侧，且在 网络策略已经应用之后，因此不会有任何凭据进入沙箱，沙箱可以访问哪些目标地址也不 会发生任何变化。

该功能依赖 Windows SSPI，因此在 macOS 或 Linux 上无效。在这些平台上，代理 URL 中的 凭据仍然是唯一的选项。