npulink

将内网独自授权的 CPU/NPU 环境通过公网服务器中转提供任意 SSH 访问。

安装

在已经安装 Node.js 20+ 的 Linux 环境中：

npm install -g npulink
npulink --help

如果 NPU 环境没有 Node.js，也可以直接执行 npm 包中的 shell 脚本；脚本本身只依赖系统的 sh、sudo、sshd、ssh-keygen 和 base64。

架构

使用者的 SSH 客户端
  -> npu.example.com:公网端口
  -> 公网服务器 TCP 中转
  -> 公网服务器 127.0.0.1:内部端口
  -> NPU 反向 SSH 隧道
  -> NPU 127.0.0.1:2222

公网服务器只做 TCP 中转，不承载 NPU 的 shell，也不解密 SSH 数据。NPU 自建 sshd 负责密码认证和拦截 scp、sftp、rsync。

端口分配

公网端口和公网服务器回环端口分开编号：

| NPU | 域名 | 公网 SSH 端口 | 公网服务器内部端口 | |---|---|---:|---:| | 第一台 | npu.example.com | 20001 | 30001 | | 第二台 | npu.example.com | 20002 | 30002 | | 第三台 | npu.example.com | 20003 | 30003 |

DNS 只需要有一条 npu.example.com A <公网服务器 IP> 记录，并保持“仅 DNS”。不同 NPU 通过不同端口区分。npu.example.com 仅为示例，请替换成实际域名。

接入流程

NPU 提供者只需要执行管理员发来的完整 join 命令并设置共享登录密码。脚本会自动生成包含 CONNECTOR_PUBLIC_KEY 的完整 auth 命令；不要提供 CANNLab 登录 token、公网服务器管理密码或 NPU 私钥。

整个接入只需要三个步骤：

1. 公网服务器管理员执行 npulink prepare，把输出的完整 npulink join 命令发给 NPU 提供者；
2. NPU 提供者直接复制执行该命令，设置共享密码并得到完整的 npulink auth 命令；
3. 公网服务器管理员复制执行 NPU 返回的 npulink auth 命令。

第三步不能交给 NPU 提供者自动完成，否则必须向其开放公网服务器管理权限或额外部署注册服务。

1. 公网服务器管理员准备连接服务

在公网服务器上执行：

sudo npulink prepare team-02 20002 <公网服务器IP或域名>

其中 team-02 是自定义的 NPU 环境标识，用于区分不同 NPU 环境；20002 是自定义的公网 SSH 端口，只要不与公网服务器上其他环境重复即可。命令会提示输入公网服务器地址，也可以作为第三个参数传入。内部端口会自动使用 30002。公网服务器上需预先安装 socat。

脚本会创建受限连接用户、SSH 反向端口规则和 systemd TCP 中转服务，并输出发给 NPU 提供者的完整接入命令。

2. NPU 提供者配置 connector

管理员执行 prepare 后会输出一条完整的 npulink join 命令。将这条命令直接复制到 NPU 中执行：

npulink join \
  <公网服务器地址> \
  <prepare 输出的连接用户> \
  <prepare 自动分配的内部端口> \
  '<公网服务器后端公钥的 base64 内容>' \
  <环境标识>

脚本会完成：

• 创建 NPU 自建 sshd:2222；
• 创建 npu 登录用户；
• 创建 /mnt/workspace/npu 并设为登录后的默认工作目录；
• 开启 npu 密码登录；
• 拦截 scp、sftp、rsync；
• 安装断线重连的反向 connector；
• 输出 CONNECTOR_PUBLIC_KEY。

脚本会调用 sudo passwd npu 设置共享密码。完成后会输出一条完整的 npulink auth 命令，直接复制到公网服务器执行。

3. 公网服务器管理员登记公钥

join 完成后会输出下面这种完整命令。将 NPU 终端输出的命令原样复制回公网服务器执行，不要手工复制或修改公钥：

printf '%s\n' 'ssh-ed25519 AAAA...NPU 提供者发来的完整公钥...' | \
  sudo npulink auth team-02

上面只是输出格式示例；实际使用时以 join 输出的 CONNECTOR_PUBLIC_KEY 和环境标识为准。该公钥只能监听对应 NPU 的内部端口，不能获得公网服务器 shell，也不能创建其他转发。

使用和验证

普通 SSH 登录：

# 示例地址：203.0.113.10；实际使用时替换成公网服务器 IP 或域名
ssh -p 20002 [email protected]

登录后默认目录为 /mnt/workspace/npu，可以执行：

pwd
npu-smi info

验证文件传输被禁止：

# 示例地址：203.0.113.10；实际使用时替换成公网服务器 IP 或域名
scp -P 20002 local.txt [email protected]:/mnt/workspace/npu/
sftp -P 20002 [email protected]

普通 SSH 命令仍然可用：

ssh -p 20002 [email protected] 'hostname && npu-smi info'

数据目录

建议将数据集、模型、checkpoint 和编译产物放在 /mnt/workspace/npu；配置、SSH 文件和 Shell 文件放在 /home/npu。不要把重要数据放在 /、/tmp、/dev/shm、/etc/devenv 或 /usr/.devenv。

安全边界

• 公网服务器管理 SSH 端口 22 只允许管理员密钥登录；
• NPU 不开放公网入站端口；
• 受限连接用户只能建立指定的反向端口；
• scp、sftp、rsync 在 NPU sshd 侧拦截；
• 共享密码无法区分具体登录人，人员变化时应立即更换；
• 重要数据仍需单独备份，磁盘持久化不等于备份。

故障排查

# 公网服务器查看反向端口
ss -ltnp | grep 30002

# 公网服务器查看中转服务
systemctl status cannlab-npu-team-02.service

# NPU 查看 connector
ps -ef | grep cannlab-vps-connector | grep -v grep

如果 NPU 容器被平台重建，需要重新运行 NPU 安装脚本；如果只是网络断线，connector 会自动重连。