ChrAlpha's Blog

Thumbnail-thumbnail

写给非科班的 HPC 无痛上手：在超算节点上使用 VS Code

2025-12-18·笔记本

题图由 Nano Banana Pro 生成。

TL;DR

  • 在登录节点使用 VS Code 请时刻谨记它仅作为编辑器、不要视作 IDE，不要碰任何运行计算相关操作

  • 在计算节点使用 VS Code 全程计费，不论仅是编辑还是运行代码

  • VS Code Remote - SSH 插件配合 ProxyJump 可无痛运行在（申请预留的）计算节点上

    # ~/.ssh/config

Host compute-node
  HostName <COMPUTE_NODE_ADDRESS>
  ProxyJump login-node
  # other configs...

Host login-node
  HostName <LOGIN_NODE_ADDRESS>
  # other configs...

  • VS Code Remote - Tunnels 插件配合 dev tunnels

    • 登录过账号（Microsoft、GitHub）

      在计算节点内运行：

      VSCODE_CLI_USE_FILE_KEYRING=1 ./code tunnel --name <TUNNEL_NAME> --accept-server-license-terms

    • 未登录过

      • 先登录
        ./code tunnel user login --provider github（或 microsoft）
      • 再隧穿 ./code tunnel --name <TUNNEL_NAME> --accept-server-license-terms

高性能计算（HPC）的实践通常完全围绕命令行展开。对于应用物理、材料或生物等非 CS 专业的同学而言，这种交互方式往往伴随着陡峭的学习曲线：陌生的 Vim/Emacs 编辑器、繁琐的文件管理，以及难以配置的代码补全、Linter 和 AI coding agnet 等。这些阻碍在很大程度上消耗了本应投入到科研本身的精力。幸运的是，VS Code 凭借其开箱即用的特性、强大的远程开发插件以及对学生免费提供 Copilot Pro 等 AI 工具的无感支持，能极大降低上手 HPC 科学计算的门槛。

虽然部分 HPC 提供了基于 Web 的可视化 Studio 界面、可以创建 Code Server，但在浏览器中编码往往面临快捷键冲突、配置同步困难等问题。相比之下，基于 SSH 的远程开发 能让用户在享受高性能计算资源的同时，保留本地 IDE 极致流畅的编辑体验与个性化配置。本文将以 VS Code Remote 系列插件为核心展开介绍。需要说明的是，该连接方案完全通用：无论是 Cursor、Antigravity 等 VS Code 衍生编辑器，还是纯命令行的 SSH 连接，底层的配置逻辑均是一致的。

HPC 基础

大多数 HPC 集群采用 Slurm 系统1 管理资源。集群分为 「登录节点 (Login Node)」 和 「计算节点 (Compute Node)」以及其他辅助节点（数据节点、代理节点等）。

本文并不试图系统介绍 Slurm，而仅覆盖 VS Code 远程开发所需的最小基础知识。完整命令请参考 Slurm Man Pages2。

当你通过 SSH 连接到集群时，通常无法直接连接计算节点、而是默认处于「登录节点」。它仅仅是一个 前台接待处，负责接收任务指令，而不负责实际的运算。**因此其硬件资源非常有限。严禁在此直接编译大型项目、运行复杂脚本。**这些行为会导致节点卡顿，不仅影响所有用户，还极可能导致你的账号被管理员限制乃至封禁。对于插件较多的 VS Code 来说有时甚至仅仅是启动 VS Code Server 本身就可能触发资源限制警告。

为了在计算节点中使用 VS Code 开发，你需要在登录节点预先申请计算节点资源。

临时交互式开发

使用 salloc 或 srun 申请一个带 Shell 的计算节点，适合当你需要通过终端直接操作计算节点时短时间调试使用。

# 申请保留 1个节点，6核CPU，1张GPU，时长12小时
salloc -p dgx2 -N 1 -c 6 --gres=gpu:1 -t 12:00:00
# 申请 1个节点，6核CPU，1张GPU，时长12小时，并启动伪终端
srun -p dgx2 -N 1 -c 6 --gres=gpu:1 -t 12:00:00 --pty /bin/bash

注意 srun 申请的交互式 Shell 在网络波动或其他原因导致窗口关闭时会立刻被认为任务完成进而计算资源被回收。建议在登录节点先运行 tmux、screen 等终端复用器──让 Shell 会话与窗口解绑。

生产环境、长时间运行脚本

sbatch 用于提交生产环境、长时间运行、无人值守的作业脚本（bash task.sh => sbatch task.sh）。这是在超算上进行计算任务最标准的方式。

  • 已写好完善的代码和流程： 你不需要实时输入命令。
  • 任务运行时间长： 任务需要跑几个小时甚至几天。你不太可能一直开着终端。
  • 资源排队： 集群很忙，你的任务可能需要排队等几小时。用 sbatch 提交后，Slurm 会自动调度。
  • 需要记录日志： 标准输出（stdout）和错误信息（stderr）会自动保存到文件中（如 slurm-12345.out），方便后续查看。

通过脚本中的 #SBATCH 注释声明作业信息、所需硬件计算资源。

#!/bin/bash
#SBATCH -J VSCode
#SBATCH -p dgx2
#SBATCH -N 1
#SBATCH --ntasks-per-node=1
#SBATCH -c 6
#SBATCH --gres=gpu:2
#SBATCH -t 12:00:00
#SBATCH -o log/%j.out
#SBATCH -e log/%j.err
while true; do sleep 240; done
  • -J/--job-name：作业名称
  • -p/--partition：分区名称（集群中不同硬件配置的节点组）
  • -N/--nodes：请求节点数
  • --ntasks-per-node：每节点任务数
  • -c/--cpus-per-task：每任务 CPU 核数
  • -t/--time：最长运行时限
  • --gres：请求 generic resources（如 GPU）
  • -o/--output：标准输出日志文件路径
  • -e/--error：标准错误日志文件路径

而在 sbatch 脚本中使用 srun 则用于在分配的计算资源上启动任务，并且受 --ntasks/--ntasks-per-node 等参数影响并行行为。具体请参考 sbatch 文档3 与 srun 文档4，不熟悉的用户谨慎使用以免产生预期不一致的行为。

SSH 跳板连接

在成功申请计算节点后，我们可以通过 SSH 将登录节点用作跳板连接至计算节点。

┌──────────┐      SSH       ┌──────────────┐    ProxyJump   ┌──────────────┐
│  Client  │ ─────────────> │  Login Node  │ ─────────────> │ Compute Node │
└──────────┘                └──────────────┘                └──────────────┘

在正确配置 SSH 后，VS Code Remote-SSH 插件即可自动复现此连接路径正确运行在计算节点上。

ProxyJump

SSH 命令提供了一种简便的方法，通过 ProxyJump 自行创建初始连接和后续连接。无需先通过 SSH 连接到中继节点，然后再在中继节点上使用 SSH 连接到远程主机。

对于普通 SSH config 文件：

# ~/.ssh/config

Host login-node
  # configs...

Host compute-node
  HostName <COMPUTE_NODE_ADDRESS>
  ProxyJump login-node
  # other configs...

每次分配到的计算节点可能不一致，需要及时修改 <COMPUTE_NODE_ADDRESS>。而鉴权一般只需要在登录节点处进行（密钥、密码等）。良好配置的 HPC 内部通常不需要额外的鉴权。请根据实际情况判断是否进行 ForwardAgent。

在按照上面示例配置好后，每次 SSH 连接 compute-node 时自动使用 login-node 作为跳板。

也可以在使用 SSH 命令时通过 -J 选项指定跳板主机：

ssh -J login-node compute-node

ProxyCommand

ProxyJump 是现代 OpenSSH 最为推荐方式，实现最简便。ProxyCommand 则是进阶方案，适用于更复杂（或老版本 OpenSSH 不支持 ProxyJump）的场景。

对于普通 SSH config 文件：

# ~/.ssh/config

Host login-node
    # configs...

Host compute-node
    HostName <COMPUTE_NODE_ADDRESS>
    ProxyCommand ssh -W %h login-node
    # other configs...

同样的，每次分配到的计算节点可能不一致，需要及时修改 <COMPUTE_NODE_ADDRESS>。

既然是完整 Command，则可以实现更复杂的逻辑。例如每次连接时动态获取计算节点地址（计算任务名为 VSCode）：

Host compute-node
    ProxyCommand ssh -W "\$(squeue --me --name=VSCode --states=R -h -O NodeList)" login-node

抑或每次连接时动态申请计算节点（注意避免资源浪费）：

Host compute-node
    ProxyCommand ssh -W "\$(salloc -p dgx2 -N 1 --ntasks-per-node=1 -c 6 --gres=gpu:1 --time=12:00:00 srun --pty hostname)" login-node

对于一般用户而言，ProxyJump 已经足够使用。上述 ProxyCommand 示例均是不可直接复制使用的，此处仅为展示其灵活性、仅供充分理解其意义的读者自行修改使用。

本地端口转发

此外一种补充方法是在本地建立隧道进行端口转发，不依赖配置文件，便于临时调试。同样的，建议先运行 tmux、screen 等终端复用器让 Shell 会话与窗口解绑避免意外中断。

ssh -L 2222:<COMPUTE_NODE_ADDRESS>:22 <LOGIN_NODE_ADDRESS>

然后 SSH 连接至 user@localhost:2222 即可。

Code Tunnel 连接

VS Code Remote - Tunnels5 扩展利用 Microsoft dev tunnels6 中继服务，允许用户从任何位置安全连接至远程主机，无需配置 SSH 并保持直接连通性，即可获得原生般的开发体验。对于港科大等院校的 HPC 集群，官方文档常推荐将其作为最佳连接实践。

安装 Code CLI

对于仅提供命令行的 HPC 节点，建议安装独立的 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
# rm vscode_cli.tar.gz

登录账号

Code Tunnel 依赖 Microsoft 或 GitHub 账号进行身份验证。你可以在登录节点或已申请的计算节点（交互式 Shell）中运行。

VSCODE_CLI_USE_FILE_KEYRING=1 ./code tunnel

根据提示访问 https://microsoft.com/devicelogin7 并输入设备代码完成登录。初次登录时会询问机器名称，可自定义或接受以主机名为默认值。

VS Code 默认倾向于将身份验证令牌存储在系统级密钥环（System Keyring）中，然而这在无头或高频重置的 HPC 节点上难以保持登录认证。设置环境变量 VSCODE_CLI_USE_FILE_KEYRING 可以改用混淆文件存储，将登录凭证保存在 ~/.vscode/cli/ 目录下。

自动化与持久化登录

通常情况下，登录凭证会保存的相当一段时间。但在 HPC 中，如果你申请的新计算节点主机名（Hostname）发生变化，可能频繁需要重新认证。

为避免出现登录 Provider 的交互式选择，特定分解「登录」和「隧穿」命令，以实现半自动化启动。（登录间隔不长时只运行后者通常也可。）

  • 先登录：./code tunnel user login --provider github（或 microsoft）
  • 再隧穿：./code tunnel --name <TUNNEL_NAME> --accept-server-license-terms

同样推荐上述 VSCODE_CLI_USE_FILE_KEYRING 环境变量设置以获得更好的地持久化登录体验。

建立连接

在本地 VS Code 中安装 VS Code Remote - Tunnels8 插件后，登录相同账号，即可在远程资源列表中看到已建立的隧道，点击连接即可。

但是在 Windows 版本的 VS Code 中，遇到同时登录 Microsoft 和 GitHub 账号时，账号界面会出现异常一直 Loading 状态（不论是否同步，即便禁用其他所有插件后依然复现）。通过插件 Bisect 排查是 GitHub Copilot Chat 插件问题。可先禁用该插件后退出一个账号再重新登录，简单检索并未发现类似问题报告，可能仅是特例。macOS 和 Linux 版本未复现该问题。

后记

在搜索引擎相关英文搜索结果中，诸如耶鲁、伯克利、加州理工、港科大等许多高校或研究所的 HPC 文档均涉及 VS Code 连接教9101112，并推荐在有需求时直接连接至计算节点。

遗憾的是，在搜索引擎相关中文搜索结果中，第一条看似是十分值得参考的著名高校文档，实则具备一定误导性──其仅仅引导用户将 VS Code 连接至登录节点。

且不提误操作导致在登录节点进行计算任务，就算是只运行 VS Code 当插件较多、目录较为复杂时也容易触发资源限制警告。我收到两次警告都仅仅是刚连接上登录节点、尚未进行任何操作。

而同校更加专注的高性能计算比赛团队提供的入门指南则提供了一个良好的 ProxyJump 连接实践。

更无语的是，该校这周 HPC 内部互相 SSH 鉴权出现问题，不识别门户网站创建的密钥（还以安全为由禁止自行创建密钥上传），ForwardAgent 也不正常工作，要么回退使用密码。迫使我明明在内网中却还转而使用 Code Tunnel 连接。

嘛。

Footnotes

  1. https://slurm.schedmd.com/ ↩

  2. https://slurm.schedmd.com/man_index.html ↩

  3. https://slurm.schedmd.com/sbatch.html ↩

  4. https://slurm.schedmd.com/srun.html ↩

  5. https://code.visualstudio.com/docs/remote/tunnels ↩

  6. https://learn.microsoft.com/en-us/azure/developer/dev-tunnels/overview ↩

  7. https://microsoft.com/devicelogin ↩

  8. https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-tunnels ↩

  9. https://docs.ycrc.yale.edu/clusters-at-yale/access/ood-vscode/ ↩

  10. https://computing.stat.berkeley.edu/access/vscode-remote-ssh/#connect-to-an-scf-cluster-node ↩

  11. https://www.hpc.caltech.edu/documentation/software-and-modules/vscode, https://gist.github.com/haakon-e/e444972b99a5cd885ef6b29c86cb388e ↩

  12. https://itso.hkust.edu.hk/services/academic-teaching-support/high-performance-computing/superpod/usage-tips/vscode ↩

写给非科班的 HPC 无痛上手：在超算节点上使用 VS Code
https://blog.ichr.me/post/hpc-vscode/
本文作者
ChrAlpha
发布日期
2025-12-18
更新日期
2025-12-18
转载或引用本文时请遵守 CC BY-NC-SA 4.0 许可协议，注明出处、不得用于商业用途！
CC BY-NC-SA 4.0
#VS Code#HPC