VS Code 通过 Tunnels 连接 Dev Containers:远程容器开发实战指南
VS Code 通过 Tunnels 连接 Dev Containers:远程容器开发实战指南
导读
本文基于 VS Code 远程开发(Remote Development)2023 年 9 月发布的 1.83 版更新说明,深入讲解 通过 Tunnels(安全隧道)连接 Dev Containers(开发容器) 这一核心新特性:无需配置 SSH,即可让本地 VS Code 客户端与运行在远程机器上的开发容器无缝协作,且只有远程隧道机器需要安装 Docker。读完本文,你将掌握从搭建隧道、安装 Docker,到在远程容器中打开工作区并开始编码的完整流程,并了解该能力在后续版本(1.84 等)中的演进与限制。
特性概述:把 Dev Containers 也带到隧道之上
在 1.83 版本之前,VS Code 已经可以通过 Remote - Tunnels 连接到远程机器(台式机、虚拟机等)并在其上运行 VS Code Server;通过 Remote - SSH 也可以把 Dev Containers 扩展到远程 SSH 主机上。1.83 版把这两种能力合二为一:你可以像通过 SSH 连接 Dev Containers 一样,通过 Tunnels 连接 Dev Containers。
原始发布说明(remote-release-notes/v1_83.md)给出了该特性的三条核心语义:
- 与 SSH 场景类似:Tunnels 场景与 SSH 场景在“远程主机 + 远程容器”的工作方式上保持一致,只是连接通道从 SSH 换成了安全隧道;
- 只有隧道机器需要 Docker:本地客户端不需要安装 Docker,Dev Container 会在隧道目标机器(即工作区文件夹所在、通过隧道连接到的远程机器)上完成构建与运行;
- 平台限制:当时要求隧道机器运行 Linux 才能使用 Dev Containers,该限制在后续里程碑中被移除。
换句话说,这一特性让“远程开发容器”摆脱了对 SSH 服务器配置的依赖——只要远程机器能建立一条出站隧道连接,就能在容器中开发。
架构解析:Tunnels、VS Code Server 与 Dev Containers 如何协作
要理解该特性,先要厘清三个组件的分工(可参考 docs/remote/remote-overview.md 与 docs/remote/vscode-server.md):
- VS Code Server:运行在远程机器上的后端服务,是 VS Code 远程体验的根基。它既可以由 Remote Development 系列扩展按需安装,也可以作为独立服务自行运行(见 docs/remote/vscode-server.md)。
- Remote - Tunnels 扩展:负责建立并维护客户端与远程机器之间的安全隧道连接,是本地客户端的“连接器”。
- Dev Containers 扩展:负责在远程机器上构建、启动并附着到开发容器。
三者组合后的工作流程如下:
- 远程机器运行
code tunnel或通过 UI 开启隧道访问,VS Code Server 在远程机器上启动; - 本地客户端(桌面版或 vscode.dev 网页版)通过隧道连接到远程机器,打开其中的工作区文件夹;
- Dev Containers 扩展检测到该文件夹中的
.devcontainer/devcontainer.json配置,在远程机器上构建并启动容器; - 客户端与容器之间仍通过同一隧道通信,扩展在容器内部运行,拥有容器内完整的工具链与文件系统访问权限。
需要强调的是,这一链路中 Docker 只安装在远程隧道机器上,本地客户端完全不需要 Docker。这与 docs/devcontainers/containers.md 中“在远程 SSH 主机上打开容器”的场景在操作模型上完全一致,只是把 Remote - SSH 替换成了 Remote - Tunnels。
实操指南:从零到一在远程容器中开发
综合 1.83 发布说明与 docs/remote/tunnels.md、docs/devcontainers/containers.md 中的正式文档,完整步骤如下。
第一步:在远程机器上建立隧道
两种方式任选其一,最终效果相同:
方式 A:使用 code CLI(推荐用于无法安装完整 VS Code Desktop 的机器)
code tunnel
该命令会在当前机器上下载并启动 VS Code Server,随后建立隧道。首次运行时会被提示接受服务器许可条款,也可用 --accept-server-license-terms 参数跳过交互提示。命令运行后会输出一个绑定到该机器的 vscode.dev 地址,例如 https://vscode.dev/tunnel/<machine_name>/<folder_name>,在任何客户端上打开该地址即可连接。首次从客户端连接时,会引导你登录 GitHub 或 Microsoft 账户完成认证。
对于无法安装 VS Code Desktop 的远程机器,CLI 还提供独立安装包,也可在远程终端中直接下载解压:
curl -Lk 'https://code.visualstudio.com/sha/download?build=stable&os=cli-alpine-x64' --output vscode_cli.tar.gz
tar -xf vscode_cli.tar.gz
注意:使用独立安装或终端解压安装时,后续命令前缀为
./code而非code。
方式 B:通过 VS Code UI 开启
在远程机器的 VS Code 中,打开 Account 菜单选择 Turn on Remote Tunnel Access,或通过命令面板(F1)执行 Remote Tunnels: Turn on Remote Tunnel Access...,登录账户后隧道即在当前机器上启动。
第二步:在隧道机器上安装 Docker
参照 docs/devcontainers/containers.md 的安装章节,在隧道机器上安装并配置 Docker:
- Linux:按发行版官方文档安装 Docker CE/EE(18.06+)及 Docker Compose(1.21+),并将当前用户加入
docker组:sudo usermod -aG docker $USER; - Windows / macOS:安装 Docker Desktop 2.0+;
- 远程主机资源要求:至少 1 GB 内存,建议 2 GB 内存与 2 核 CPU。
本步骤无需在本地客户端安装 Docker。
第三步:连接隧道主机并打开文件夹
在本地客户端中安装 Remote - Tunnels 扩展(通过 code tunnel CLI 或 UI 打开的 vscode.dev 实例已预装该扩展),执行命令 Remote Tunnels: Connect to Tunnel 连接到远程机器,并在其中打开工作区文件夹。已注册的远程机器会显示在 Remote Explorer 视图中(可通过命令 Remote Explorer: Focus on Remote View 聚焦),连接状态同样会体现在左下角绿色的远程指示器中。
第四步:在容器中重新打开工作区
在命令面板(F1)中执行 Dev Containers: Reopen in Container。Dev Containers 扩展会读取远程机器工作区中的 dev container 配置(.devcontainer/devcontainer.json 或 Dockerfile / Docker Compose 文件),在远程机器上构建并启动容器,随后 VS Code 自动附着到容器中。之后 docs/devcontainers/containers.md 中关于 Dev Containers 快速上手的其余流程(容器构建进度、首次构建后加速复用、Features 定制等)均原样适用。
如果你更倾向“远程 Docker 主机”模型(例如让容器运行在独立的 Docker 主机上,而不是隧道机器本机),可以进一步阅读 remote/advancedcontainers/develop-remote-host.md 中的备选方案。
隧道相关 CLI 命令速查
code CLI 内置了完整的隧道管理子命令,可随时通过 code tunnel --help 查看全部选项(对应文档见 docs/configure/command-line.md 的“Create remote tunnel”章节与 docs/remote/vscode-server.md):
| 命令 | 作用 |
|---|---|
code tunnel |
在当前机器上创建隧道并启动 VS Code Server |
code tunnel service install |
将隧道安装为系统服务(支持 Windows、macOS 及 systemd 的 Linux),保持隧道常驻 |
code tunnel service uninstall |
卸载已安装的隧道服务 |
code tunnel --no-sleep |
防止远程机器休眠,保持隧道可用 |
code tunnel unregister |
取消当前机器与隧道服务的关联(也可在 Remote Explorer 中右键机器选择 unregister) |
code tunnel --accept-server-license-terms |
免交互接受服务器许可条款 |
code tunnel --disable-telemetry |
禁用遥测 |
code tunnel --telemetry-level error |
指定初始遥测级别(如仅收集错误) |
code -v tunnel |
以 verbose 模式启动隧道,用于排查问题并收集日志 |
另外,隧道在远程机器上遵循“单例”原则(自 1.77 版起):同一台机器上已存在运行中的隧道时,重复执行 code tunnel 或再次请求开启隧道访问只会产生一个“监视”进程,你仍可通过在终端输入 x(停止)或 r(重启)来管理现有隧道(见 remote-release-notes/v1_77.md)。自 1.81 版起,UI 中的 Turn on Remote Tunnel Access 命令还允许选择“在本次 VS Code 实例中运行”或“安装为系统服务”,后者可通过 Turn off Remote Tunnel Access 卸载(见 remote-release-notes/v1_81.md)。
平台支持与限制演进
1.83 版明确:当时隧道机器需要运行 Linux 才能通过 Tunnels 使用 Dev Containers,官方承诺将在未来里程碑中移除该限制。
这一承诺在随后的 1.84 版兑现:发布说明 remote-release-notes/v1_84.md 宣布,现在可以通过 Tunnels 或 SSH 连接到 远程 Windows 机器 上的 Dev Containers(此前仅支持 Linux 与 macOS 作为远程操作系统)。此外,1.84 版还为 Tunnels 增加了 Microsoft 账户(MSA 或 AAD)登录:启动隧道时会提示选择认证方式,首次连接隧道时也需要确认认证方式。
值得注意的是,官方文档 docs/devcontainers/containers.md 中列出的容器平台要求依然生效,包括:
- Windows 容器镜像不支持;
- 容器镜像支持 x86_64 / ARMv7l / ARMv8l 架构的 Debian 9+、Ubuntu 16.04+、CentOS / RHEL 7+,以及 x86_64 Alpine Linux 3.9+;
- Ubuntu Docker snap 包与 Windows Docker Toolbox 均不受支持;
- 若在容器内使用基于
glibc的原生扩展,Alpine 容器可能因缺少glibc依赖而无法正常工作。
安全与认证要点
Tunnels 场景下的安全模型同样适用于“通过 Tunnels 连接 Dev Containers”:
- 双向认证:建立与连接隧道都要求使用同一个 GitHub 或 Microsoft 账户完成认证;
- 纯出站连接:VS Code 会向托管在 Azure 中的服务发起出站连接,通常无需更改防火墙,也不会在远程机器上建立网络监听端口;
- 端到端加密:连接建立后,隧道之上会创建 SSH 连接以提供端到端加密,当前优先使用的加密算法为 CTR 模式的 AES-256(底层 dev-tunnels 实现为开源项目,可参阅 docs/remote/tunnels.md 的常见问题章节);
- 使用限制:为避免滥用,隧道服务存在资源配额,例如每个账户当前最多注册 10 条隧道;若已满,CLI 会随机选取一条未使用的隧道并删除。
常见问题
Q1:本地客户端没有 Docker,能通过 Tunnels 使用 Dev Containers 吗?
能。这正是该特性的设计目标——Docker 只需安装在隧道机器上,Dev Container 在远程构建与运行,本地仅作为客户端。
Q2:远程机器退出 VS Code 后隧道会怎样?
隧道仅在 VS Code 运行期间保持可达。退出 VS Code 后,需重新启动 VS Code 或再次执行 code tunnel 才能恢复隧道(可将隧道安装为服务以保持常驻)。
Q3:能否在 Tunnels 场景中同时使用其他远程扩展?
可以。目前可以通过 Remote - Tunnels 连接 WSL 与 Dev Containers;在隧道窗口中,容器工具/扩展的 Attach VS Code 操作会要求再次选择可用容器(见 docs/devcontainers/containers.md 的已知限制章节)。
Q4:如何卸载或移除隧道机器?
CLI 场景按 Ctrl+C 停止隧道,或执行 code tunnel unregister 取消机器关联;UI 场景执行 Remote Tunnels: Turn off Remote Tunnel Access... 即可。
参考资料
- 1.83 版远程发布说明:remote-release-notes/v1_83.md
- 1.84 版远程发布说明(Windows 支持与 Microsoft 账户登录):remote-release-notes/v1_84.md
- 1.82 版远程发布说明(serve-web、WSL 中安装 Docker):remote-release-notes/v1_82.md
- Remote - Tunnels 完整文档:docs/remote/tunnels.md
- VS Code Server 文档:docs/remote/vscode-server.md
- Dev Containers 文档(含“在远程 Tunnel 主机上打开容器”章节):docs/devcontainers/containers.md
codeCLI 文档(Create remote tunnel 章节):docs/configure/command-line.md- 远程 Docker 主机备选方案:remote/advancedcontainers/develop-remote-host.md
