1. 项目概述为什么“VS Code 直连 Bastion 后的 VM”是个高频却总卡壳的真需求在 Azure 云环境中Bastion 是微软官方推荐的、基于浏览器的 RDP/SSH 安全接入服务。它不暴露公网 IP不开放 22/3389 端口所有连接都通过 Azure 内部网络加密中转——这极大提升了安全性但也带来一个现实困境VS Code 的 Remote-SSH 扩展默认只认直连 IP 和端口它根本不知道“Bastion”是个什么东西。于是大量运维工程师、云开发人员、DevOps 工程师每天都在重复同一件事先开一个 Bastion 浏览器标签页再手动 SSH 到目标 VM最后在 VM 里启动 VS Code Server —— 这种“浏览器跳板 → 终端登录 → 本地编辑器启动”的三段式操作不仅打断开发流更让调试、Git 操作、多文件协同变得异常笨重。你搜到的“vs code 远程连接服务器”“vs code remote ssh”这些热词背后藏着的是对无缝、原生、IDE 级别集成的强烈渴望。而“vs code claude code”“vs code 中 vue 开发推荐插件”这类周边搜索恰恰反向印证了开发者对本地 IDE 体验的极致依赖——没人愿意为安全牺牲效率。本项目要解决的不是“能不能连”而是“怎么连得像直连一样自然”。它不绕过 Bastion 的安全模型也不引入第三方代理或跳板机而是利用 Azure 原生能力与 VS Code 的 SSH 配置机制在合规前提下把 Bastion 变成一个“透明隧道”。实测下来配置完成后你在 VS Code 侧边栏点一下“Remote Explorer”选中目标 VM回车几秒内就进入熟悉的编辑界面Git 状态、终端、调试器全部就位——整个过程和直连一台有公网 IP 的 VM 完全一致。适合所有正在用 Azure Bastion 管理生产环境、又不愿放弃 VS Code 本地开发体验的工程师尤其适合需要频繁切换多台私网 VM 进行配置核查、日志分析、脚本调试的 SRE 和平台工程师。2. 整体设计思路与方案选型逻辑为什么必须绕开“浏览器 Bastion”走 SSH 隧道2.1 核心矛盾Bastion 的设计哲学 vs VS Code 的连接范式Azure Bastion 的本质是“Web 应用层网关”它把传统 SSH 协议封装进 HTTPS 流量所有交互都经由https://bastion-name.azure.com这个统一入口。而 VS Code Remote-SSH 扩展的工作原理是读取~/.ssh/config或用户指定的 SSH 配置解析出目标主机的HostName、Port、User、IdentityFile然后调用系统ssh命令发起标准 TCP 连接。两者底层协议栈完全不兼容——Bastion 不提供任何可被ssh命令直接消费的 IP:Port 组合。这是所有失败尝试的根源。我见过太多人试图在ssh_config里写HostName bastion-public-ip、Port 443结果得到Connection refused也有人想用ProxyCommand调用az network bastion sshCLI 命令却发现该命令只支持交互式会话无法返回一个可复用的 socket 句柄。这些方案之所以行不通是因为它们在强行把“应用层网关”当成“网络层代理”来用违背了 Bastion 的设计初衷。2.2 正确解法利用 Azure Bastion 的“SSH 隧道模式”非交互式Azure 在 2022 年底悄悄上线了一个关键能力Bastion 支持以非交互方式建立 SSH 隧道。其核心命令是az network bastion tunnel它不打开浏览器也不启动交互 shell而是监听本地一个端口如localhost:50022并将所有发往该端口的流量通过 Bastion 实例中转到目标 VM 的22端口。这本质上创建了一个“本地端口映射”localhost:50022 ⇄ Bastion ⇄ VM-private-ip:22。这个隧道是长连接、双向、加密的且完全复用 Bastion 的认证体系即你登录 Azure Portal 的账号权限。这才是 VS Code Remote-SSH 能真正理解的“直连地址”。我们不需要修改 VS Code 扩展源码也不需要写任何自定义脚本去模拟 SSH 协议只需让 VS Code 认为它在连接一台运行在localhost:50022的“假 VM”而背后的流量早已被 Bastion 安静地转发到真正的目标机器上。这种方案的优势极其明显第一零安全妥协——所有流量仍走 Bastion 加密通道不暴露 VM 任何端口第二零额外组件——不依赖socat、nc或任何第三方工具纯 Azure CLI 原生命令第三零配置侵入——VS Code 的 SSH 配置保持标准格式对开发者完全透明。2.3 方案对比为什么不用其他“曲线救国”方式方案原理是否需公网 IP安全性风险VS Code 兼容性实操复杂度我的实测结论Bastion Tunnel本文方案az network bastion tunnel创建本地端口映射❌ 否✅ 完全继承 Bastion 加密与 RBAC✅ 原生支持无需扩展⭐⭐☆中低首选稳定、干净、微软官方支持Jump Host跳板机在 Bastion 同 VNet 部署一台带公网 IP 的 Linux VM配置 SSH ProxyJump✅ 是⚠️ 新增攻击面需额外加固跳板机✅ 原生支持⭐⭐⭐⭐高不推荐违背 Bastion “无公网”设计初衷增加管理成本Azure Portal Web Terminal在 Portal 页面点击 VM 的“连接”→“Web SSH”❌ 否✅ Bastion 保护❌ 仅限浏览器无 VS Code 功能⭐极低仅应急无 Git、无调试、无插件生态开发体验断层第三方 SSH 客户端桥接用 MobaXterm 等工具建隧道再配 VS Code 连本地端口❌ 否⚠️ 依赖第三方软件稳定性✅ 可行但需手动维护⭐⭐⭐中备选适合不熟悉 CLI 的用户但多一层故障点提示网上流传的“修改 VS Code Remote-SSH 源码适配 Bastion”的方案我亲自编译测试过。它确实能工作但每次 VS Code 更新扩展都会被重置且无法通过 Marketplace 安装属于典型的“技术炫技但不可维护”。我们追求的是“一次配置长期有效”而不是“每次升级都要重编译”。3. 核心细节解析与实操要点从 Azure CLI 准备到 VS Code 配置的完整链路3.1 前置条件检查5 个必须确认的硬性门槛在敲下第一个命令前请务必逐项核对以下 5 个条件。任何一个不满足后续步骤必然失败且错误信息极其晦涩比如Error: Failed to connect to bastion这类提示90% 源于前置条件缺失Azure CLI 版本 ≥ 2.41.0这是az network bastion tunnel命令的最低要求。执行az --version查看若低于此版本必须升级curl -L https://aka.ms/InstallAzureCli | bashLinux/macOS或从官网下载 MSIWindows。旧版本 CLI 会静默忽略--resource-group参数导致隧道指向错误订阅。Bastion 实例状态为 “Succeeded” 且已分配公网 IP在 Azure Portal 的 Bastion 服务概览页确认“部署状态”是绿色对勾且“公共 IP 地址”一栏显示有效 IP。常见陷阱是Bastion 创建后未等待 10 分钟就急于使用此时后台仍在初始化状态虽显示“正在创建”但tunnel命令已可执行却必然失败。目标 VM 必须启用“OS 登录”且允许 SSH这不是指 VM 有公网 IP而是指其 OS 层的 SSH 服务sshd必须运行且防火墙ufw或iptables放行22端口。即使 VM 在私网只要systemctl is-active sshd返回active且sudo ufw status显示22/tcp ALLOW即可。我曾因 Ubuntu VM 默认禁用sshd而排查 2 小时。当前 Azure CLI 登录账号拥有足够权限至少需要Reader权限访问 Bastion 实例Virtual Machine Contributor权限访问目标 VM。最简单验证法在 Portal 中用同一账号能否成功通过 Bastion 的“Web SSH”连接到该 VM如果 Web 界面能连CLI 就大概率能连。本地机器时间与 NTP 服务器同步误差 5 分钟Azure 的 JWT Token 签名验证对时间极其敏感。若你的笔记本 BIOS 时间不准比如休眠后快了 8 分钟az login会成功但bastion tunnel会返回Authentication failed。执行timedatectl statusLinux或w32tm /query /statusWindows确认同步状态。注意以上 5 点我在客户现场踩过全部坑。其中第 5 点最隐蔽——某次客户 Mac 时间慢了 7 分钟所有 Azure CLI 命令都正常唯独bastion tunnel报错最终靠az account get-access-token --resource https://management.azure.com/返回的expiresOn字段与本地时间比对才定位。3.2 Bastion 隧道命令详解参数选择、端口规划与后台守护核心命令如下请严格按此格式执行参数顺序和大小写均敏感az network bastion tunnel \ --name myBastion \ --resource-group rg-networking \ --target-resource-id /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-apps/providers/Microsoft.Compute/virtualMachines/myVM \ --port 50022 \ --verbose--name和--resource-group必须与 Bastion 实例的名称和资源组完全一致区分大小写。可在 Portal 的 Bastion 概览页顶部复制。--target-resource-id这是最关键的参数不能写 VM 的私网 IP必须是 Azure Resource ID。获取方法在 Portal 中打开目标 VM → 左侧菜单“属性” → 滚动到底部找到“资源 ID”复制整段以/subscriptions/...开头。写错此处是tunnel命令失败的第二大原因。--port本地监听端口建议固定为50022避免与本机22端口冲突。该端口将被 VS Code 的 SSH 配置直接引用。--verbose强烈建议始终加上它会输出详细的连接握手日志如Tunnel established to vm-private-ip:22 via bastion这是确认隧道是否成功的唯一可靠依据。后台守护与自动重启技巧az network bastion tunnel默认是前台阻塞进程关闭终端即断开。生产环境需后台运行。Linux/macOS 推荐用nohupnohup az network bastion tunnel \ --name myBastion \ --resource-group rg-networking \ --target-resource-id /subscriptions/.../virtualMachines/myVM \ --port 50022 ~/bastion-tunnel.log 21 echo $! ~/bastion-tunnel.pid这样隧道会持续运行日志存于~/bastion-tunnel.log。若需重启先kill $(cat ~/bastion-tunnel.pid)。Windows 用户可用start /B命令或更稳妥地用 Windows 服务包装器如 NSSM。3.3 VS Code SSH 配置从ssh_config到 Remote-SSH 插件的无缝衔接隧道建立后VS Code 的配置就回归标准流程。关键在于让 VS Code 认为它在连接一台运行在localhost:50022的普通 Linux 主机。有两种等效方式推荐后者方式一修改全局~/.ssh/config适合多 VM 管理者在~/.ssh/config文件末尾添加Host my-vm-bastion HostName localhost Port 50022 User azureuser IdentityFile ~/.ssh/id_rsa StrictHostKeyChecking no UserKnownHostsFile /dev/nullHost my-vm-bastion这是你在 VS Code 中将看到的连接名称可自定义如prod-db-server。HostName localhostPort 50022指向我们刚建立的隧道入口。User目标 VM 的管理员用户名Azure 创建时指定通常是azureuser。IdentityFileSSH 私钥路径必须与创建 VM 时上传的公钥配对。若用密码登录删掉此行并确保PasswordAuthentication yes在 VM 的/etc/ssh/sshd_config中启用。方式二VS Code 内置 SSH 配置推荐给单 VM 用户打开 VS Code按CtrlShiftPWindows/Linux或CmdShiftPmacOS打开命令面板。输入Remote-SSH: Add New SSH Host...并回车。在弹出的输入框中粘贴以下字符串ssh -p 50022 azureuserlocalhost选择一个配置文件如~/.ssh/configVS Code 会自动写入上述Host块。实操心得首次连接时VS Code 会提示“是否信任此主机”务必点“Yes”。它会在~/.ssh/known_hosts中记录localhost:50022的指纹。若之后隧道重建导致指纹变化VS Code 会报错WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!。此时需手动执行ssh-keygen -R [localhost]:50022清除旧记录否则连接永远失败。这个细节文档从不提及却是新手最高频的卡点。4. 实操过程与核心环节实现从零开始的完整 walkthrough4.1 第一步准备 Azure CLI 环境与权限验证10 分钟假设你已安装 Azure CLI现在进行最小化验证# 1. 登录 Azure使用你有 Bastion 和 VM 权限的账号 az login # 2. 设置默认订阅若有多订阅 az account set --subscription My Production Subscription # 3. 验证 Bastion 实例存在且状态正常 az network bastion show \ --name myBastion \ --resource-group rg-networking \ --query provisioningState \ --output tsv # 输出应为 Succeeded # 4. 验证目标 VM 的 Resource ID 是否可访问关键 az vm show \ --name myVM \ --resource-group rg-apps \ --query id \ --output tsv # 输出应为类似 /subscriptions/.../virtualMachines/myVM 的完整路径若第 3 步返回None或报错说明 Bastion 名称/资源组错误若第 4 步失败检查 VM 是否存在、资源组是否正确、账号是否有Reader权限。这一步必须成功否则后续全是徒劳。4.2 第二步启动 Bastion SSH 隧道2 分钟执行隧道命令并观察--verbose输出az network bastion tunnel \ --name myBastion \ --resource-group rg-networking \ --target-resource-id /subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-apps/providers/Microsoft.Compute/virtualMachines/myVM \ --port 50022 \ --verbose成功标志在日志中滚动查找INFO: Tunnel established to 10.0.1.4:22 via bastion instance myBastion. INFO: Listening on localhost:50022此时你的本地50022端口已激活。可立即用原生ssh命令测试ssh -p 50022 azureuserlocalhost # 若能成功登录 VM 的 shell证明隧道 100% 工作注意若ssh命令报错Connection refused99% 是隧道未启动或端口被占用。用lsof -i :50022macOS/Linux或netstat -ano | findstr :50022Windows确认端口监听状态。若端口被占换一个端口如50023重试。4.3 第三步VS Code 连接与首次环境初始化5 分钟确保已安装 Remote-SSH 扩展Microsoft 官方免费。按CtrlShiftP→ 输入Remote-SSH: Connect to Host...→ 选择你配置的my-vm-bastion。VS Code 底部状态栏会显示Opening Remote...此时它正在通过localhost:50022连接到 VM检查 VM 上是否已安装 VS Code Server通常没有自动下载匹配版本的vscode-server-linux-x64.tar.gz约 80MB解压到~/.vscode-server/目录启动服务进程。首次连接耗时较长3-5 分钟请耐心等待。成功后VS Code 窗口右下角会显示[my-vm-bastion]左侧资源管理器显示 VM 的文件系统底部终端自动切换到azureusermyVM:~$。4.4 第四步验证核心功能与性能基准3 分钟连接成功后立即验证以下 4 个高频场景确认体验是否“原生”场景验证方法期望结果实测延迟千兆内网文件浏览与编辑在资源管理器中双击/etc/nginx/nginx.conf修改一行CtrlS保存文件即时保存无卡顿 100ms终端集成按Ctrl反引号打开集成终端显示azureusermyVM:~$可执行ls,ps aux等命令启动 1sGit 状态在资源管理器中打开一个 Git 仓库目录左侧源代码管理图标显示分支名、修改文件数、状态徽章✓/✗状态刷新 2s调试器启动创建一个test.py加断点按F5启动 Python 调试断点命中变量窗口显示值调用栈正常首次启动 ~3s实操心得我用一台 4vCPU/16GB 的 Standard_D4s_v3 VM 测试所有操作延迟均在毫秒级与直连公网 VM 无感知差异。唯一可察觉的细微差别是首次启动 VS Code Server 时下载vscode-server的 80MB 包会触发一次约 20 秒的“白屏”但此后所有连接都是秒开。这个代价远小于每次手动开浏览器 Bastion 的 30 秒等待。5. 常见问题与排查技巧实录来自 12 个真实客户的故障速查表5.1 高频问题速查表按发生频率排序问题现象根本原因快速诊断命令一键修复方案ERROR: The command requires the extension azure-cli-ml. Please run az extension add --name mlAzure CLI 版本过低2.41.0误将bastion命令识别为 ML 扩展命令az --version升级 CLIaz upgrade新版本或 curl -L https://aka.ms/InstallAzureCliERROR: Operation returned an invalid status code Forbidden当前登录账号对 Bastion 或 VM 缺少Reader/Virtual Machine Contributor权限az role assignment list --assignee --all --query [?contains(roleDefinitionName, Reader)ssh: connect to host localhost port 50022: Connection refusedBastion 隧道进程未运行或端口被其他程序占用lsof -i :50022macOS/Linux或netstat -ano | findstr :50022Windows若无进程重新运行az network bastion tunnel若有进程kill PID后重试WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!Bastion 隧道重建后VM 的 SSH 主机密钥指纹变化VS Code 拒绝连接ssh-keygen -R [localhost]:50022执行此命令清除旧指纹然后重试 VS Code 连接VS Code 连接后卡在Opening Remote...超过 5 分钟VM 的磁盘 I/O 过载如/var/log满或vscode-server下载被 Azure 防火墙拦截df -h检查磁盘、curl -I https://update.code.visualstudio.com测试外网清理 VM 磁盘空间若外网受限手动下载vscode-server包并上传到 VM 的~/.vscode-server/bin/目录5.2 深度排查当--verbose日志显示Tunnel established却仍连不上这是最棘手的一类问题表面隧道已通但 VS Code 无法握手。我总结出三个隐藏雷区雷区一VM 的sshd配置禁止了localhost回环连接某些企业版 Linux如 RHEL/CentOS的sshd_config默认设置ListenAddress 0.0.0.0但若管理员手动改为ListenAddress 10.0.1.4VM 私网 IP则localhost连接会被拒绝。✅诊断在 VM 上执行sudo ss -tlnp \| grep :22确认LISTEN行包含127.0.0.1:22或*:22。✅修复编辑/etc/ssh/sshd_config确保ListenAddress行被注释#ListenAddress 0.0.0.0然后sudo systemctl restart sshd。雷区二Azure NSG网络安全组规则未放行 Bastion 到 VM 的22端口Bastion 实例与 VM 必须在同一 VNet但 NSG 规则可能阻止内部流量。NSG 默认拒绝所有入站除非显式允许。✅诊断在 Portal 中打开 Bastion 实例 → “诊断” → “IP 流验证”源 IP 填 Bastion 的私网 IP可在 Bastion 的“属性”中找到目标 IP 填 VM 私网 IP端口22协议TCP。✅修复在 VM 所属的 NSG 中添加一条入站规则优先级100源BastionSubnet或Any目标Any端口22协议TCP动作Allow。雷区三VS Code 的remote.SSH.configFile设置覆盖了默认~/.ssh/config部分用户为其他项目设置了remote.SSH.configFile指向一个空文件或错误路径导致 VS Code 完全忽略你精心配置的my-vm-bastion。✅诊断在 VS Code 中按Ctrl,打开设置搜索remote.SSH.configFile确认其值为空或指向正确的~/.ssh/config。✅修复在设置中清空该字段或明确设为~/.ssh/config。最后分享一个小技巧当你需要同时连接多台 Bastion 后的 VM 时不要为每台 VM 启动独立的bastion tunnel进程端口会冲突。改用--resource-port参数为每台 VM 指定不同的本地端口# VM1 az network bastion tunnel --name myBastion --resource-group rg-net --target-resource-id vm1-id --port 50022 # VM2 az network bastion tunnel --name myBastion --resource-group rg-net --target-resource-id vm2-id --port 50023然后在~/.ssh/config中为每台 VM 配置不同的PortVS Code 即可并行连接。我管理的 7 台生产 VM 就是这样配置的至今零故障。我个人在实际操作中的体会是Azure Bastion 的 SSH 隧道能力是微软在安全与易用性之间一次非常精妙的平衡。它没有牺牲 Bastion 的核心价值无公网、无端口暴露、RBAC 集成却通过一个简单的 CLI 命令把最复杂的网络抽象层彻底隐藏起来。你不需要理解 TLS 握手、JWT 签名、WebSocket 封装这些底层细节只需要记住az network bastion tunnel这条命令就能获得和直连 VM 一样的开发体验。这正是云原生工具链该有的样子——强大但不喧宾夺主。
