jumpserver-deploy

通过 JumpServer Connection Token 将静态资源部署到远程服务器（SSH/SFTP）。

适用于企业微信扫码登录等无法直接 SSH 密码认证的场景：使用 Access Key 创建 Connection Token，经 KoKo 网关上传并解压。

安装

npm install @roxybrowser/jumpserver-deploy
# 或
pnpm add @roxybrowser/jumpserver-deploy

要求 Node.js >= 20.12（使用 process.loadEnvFile）。

环境变量

JMS_BASE_URL=https://jumpweb.example.com
JMS_HOST=jumpweb.example.com
JMS_PORT=2222
JMS_ACCESS_KEY_ID=your-access-key-id
JMS_ACCESS_KEY_SECRET=your-access-key-secret
JMS_ORG_ID=00000000-0000-0000-0000-000000000002
JMS_SYSTEM_USERNAME=root

快速开始

import path from 'node:path'
import {
  JumpServerClient,
  JumpServerDeployer,
  createSplitZipPackages,
  loadDeployEnvFile,
  loadJumpServerConfigFromEnv,
} from '@roxybrowser/jumpserver-deploy'

loadDeployEnvFile(path.resolve('.env.deploy'))

const config = loadJumpServerConfigFromEnv()

const packages = createSplitZipPackages({
  sourceDir: './dist',
  // 相对路径使用正斜杠。静态站点把入口放到延后包，js/css 会先上线
  isDelayedFile: relativePath =>
    relativePath.endsWith('.html') || relativePath.endsWith('.html.gz'),
})

const deployer = new JumpServerDeployer({
  client: JumpServerClient.fromConfig(config),
  jumpServerHost: config.host,
  jumpServerPort: config.port,
})

await deployer.deploy({
  targets: [
    {
      label: 'web-server',
      assetId: '84416d8e-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
      remoteBasePath: '/var/www/app/dist',
    },
  ],
  packages,
  systemUsername: config.systemUsername,
})

部署顺序与完整性

packages 按数组顺序逐个上传并解压。createSplitZipPackages 返回的顺序是资源包在前、延后包在后，因此 html 只会在资源解压成功之后更新。

多台目标且 parallel 为 true（默认）时，所有目标都解压完当前包，才会开始下一个包。任意一台失败，其余目标不再部署后续包。

单个包的远端步骤：

1. 上传到 sftpStagingDir（默认 /tmp），文件名在 remoteZipName 后追加时间戳和随机后缀，避免并发部署互相覆盖。
2. unzip -tq 校验通过后才解压。校验或解压失败时，目标目录不会写入这个包，临时文件会被删除。
3. 命令成功输出标记后才视为完成。退出码为 0 但没有标记（例如被 JumpServer 命令过滤拦截）会报错，不会继续后续包。

isDelayedFile 收到的是源目录下的相对路径，分隔符为正斜杠。一个文件都匹配不到时会直接抛错。远端旧文件不会删除，只覆盖同名文件。目标机器需要已安装 unzip，且对临时目录有写权限。

单个包场景使用 createDeployZipPackage，没有「资源先于入口」的顺序保证。

API

| 导出 | 说明 | |------|------| | JumpServerClient | JumpServer REST API，创建/销毁 Connection Token | | JumpServerDeployer | SSH/SFTP 上传 + 远程校验解压 | | createSplitZipPackages | 将目录拆为主资源包 + 延后部署包 | | createDeployZipPackage | 将目录打成单个 zip | | getDeployPackagesSizeMb | 计算部署包总体积（MB） | | loadJumpServerConfigFromEnv | 从环境变量读取 JumpServer 配置 | | loadDeployEnvFile | 加载 .env.deploy 文件 | | requireDeployEnv | 读取单个必填环境变量，缺失时抛错 |

发布

pnpm install
pnpm build
npm publish --access public

License

MIT