@winner-fed/winner-deploy

用于生成 SEE 平台部署包的工具库

简介

@winner-fed/winner-deploy 是一个专门为 SEE 平台设计的部署包生成工具。它可以将前端项目打包成符合 SEE 平台规范的部署包，支持多种应用类型和部署模式。

特性

• 🚀 支持外框架（bizframe）和子系统（subsystem）两种应用类型
• 📦 自动生成 SEE 平台所需的 deploy.xml 与 template 配置文件
• 🐳 支持 Docker 容器化部署（seePackageType: 'docker'）
• 🔧 灵活的模板变量配置系统（variablesFunc / tplPath）
• 📝 支持 Python 和 Bash 两种脚本类型
• 🔒 可选的安装后配置 JS 混淆（enableObfuscation）：有 node 走强混淆，无 node 回退 bash 轻量混淆
• 🎯 可自定义文件拷贝和配置生成逻辑

安装

npm install @winner-fed/winner-deploy
# 或
yarn add @winner-fed/winner-deploy
# 或
pnpm add @winner-fed/winner-deploy

快速开始

基础用法

import { generateSeePackageZip } from '@winner-fed/winner-deploy';

generateSeePackageZip(
  {
    name: 'my-app',
    version: '1.0.0',
    description: '我的应用'
  },
  () => {
    console.log('生成完成');
  }
);

完整配置示例

import { generateSeePackageZip } from '@winner-fed/winner-deploy';

generateSeePackageZip(
  {
    system: 'winner-front',
    type: 'subsystem',
    name: 'my-app',
    appType: 'my-app',
    appName: 'my-app',
    version: '1.0.0',
    group: 'bizframe',
    configName: 'config.local',
    outputName: 'dist',
    description: '我的应用部署包',
    seePackagePath: 'package',
    seePackageType: 'web',
    scriptsType: 'python',
    enableObfuscation: false,
    copyFiles: ['version.js'],
    tplPath: {},
    templateFunc: () => './dist/my-app/sysconfig.js',
    variablesFunc: () => [
      {
        type: 'input',
        label: '应用标题',
        name: 'APP_TITLE'
      }
    ]
  },
  () => {
    console.log('生成成功');
  }
);

API 文档

generateSeePackageZip(options, callback)

生成 SEE 平台部署包。name、version 缺失时会抛出错误；name 与 seePackageName 中的 @、/ 会自动替换为 -。

参数说明

| 参数名 | 类型 | 默认值 | 必填 | 说明 | | ----------------- | -------------------------------------- | ------------------------------------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | system | string | 'winner-front' | 否 | 系统类型，SEE 平台分组维度 | | type | 'bizframe' \| 'subsystem' | 'bizframe' | 否 | 应用类型：外框架或子系统 | | name | string | - | 是 | 发布物名称（子系统标识、脚本目录名等） | | version | string | - | 是 | 发布包版本 | | description | string | - | 否 | 发布包说明，写入 deploy.xml | | appType | string | name | 否 | 发布物类型 | | appName | string | name | 否 | deploy.xml 中 appName 标签 | | group | string | 'bizframe' | 否 | 应用分组 | | configName | string | 'config.local' | 否 | 配置文件名（不含 .js）。为空时可构建不含配置 JS 的静态包，此时 scriptsType 应使用 bash。实际写入 template 的文件名还会按项目类型自动推断：存在 dist/config.local.js 时用 config.local，存在 dist/sysconfig.js（或子包路径下）时用 sysconfig | | outputName | string | 'dist' | 否 | 构建产物目录名（相对项目根目录） | | seePackageName | string | `${system}-${name}-${version}` | 否 | zip 包文件名（不含 .zip） | | seePackagePath | string | 'package' | 否 | zip 输出目录，相对项目根目录；设为 '/' 时输出到当前目录 | | seePackageType | 'web' \| 'docker' | 'web' | 否 | 发布物类型 | | dockerImage | string | - | 否 | Docker 镜像名，seePackageType 为 'docker' 时生效 | | scriptsType | 'python' \| 'bash' | 'python' | 否 | 集群脚本语言 | | enableObfuscation | boolean | false | 否 | 为 true 时打包 scripts/{name}/js/，并在 afterInstall 中对已注入变量后的配置 JS 做混淆：有 node 用 confuse.js（javascript-obfuscator 强混淆），无 node 用 confuse.sh（base64 + TextDecoder/new Function 轻量包裹，UTF-8 安全，强度较弱）；为 false 时不拷贝、不执行混淆 | | tplPath | Record<string, string> | {} | 否 | 自定义模板：key 为包内文件名，value 为本地绝对路径。deploy.xml 同名则覆盖生成的 deploy.xml；sysconfig.js / config.local.js 会跳过自动生成对应配置 | | copyFiles | string[] | - | 否 | 额外拷贝到包内 source/{name}/ 的文件名列表，源路径为 `${outputName}/${name}/${file}` | | templateFunc | () => string \| undefined | 见下文 | 否 | 返回待写入 template 的配置 JS 源文件路径 | | variablesFunc | () => FieldAttributes[] \| undefined | 见下文 | 否 | 返回 deploy.xml 动态表单项 |

templateFunc 默认值

未传入时按 type 与 outputName 解析：

// type === 'bizframe'
() => `./${outputName}/config.local.js`

// type === 'subsystem'
() => `./${outputName}/${name}/sysconfig.js`

variablesFunc 默认值

未传入时尝试加载项目根目录下 build/package/variables.js 的 variables 字段；加载失败则返回 []（与 type 无关）。

variablesFunc: () => {
  try {
    const { variables } = require('./build/package/variables.js');
    return variables || [];
  } catch {
    return [];
  }
};

tplPath 说明

tplPath: {
  'deploy.xml': '/abs/path/custom-deploy.xml',
  'sysconfig.js': '/abs/path/sysconfig.js'
}

• 除 deploy.xml 外，其余文件复制到包内 template/ 目录。
• 提供 sysconfig.js 或 config.local.js 时，不再根据 templateFunc 生成同名配置。

copyFiles 说明

适用于 manifest 未收录、但需要打进 SEE 包的文件：

// 将 dist/my-app/version.js 拷贝到包内 source/my-app/version.js
copyFiles: ['version.js'];

callback 回调

第二个参数为无参函数，在 zip 写入完成且临时目录清理后调用，不传递 error / result：

generateSeePackageZip(options, () => {
  console.log('打包结束');
});

打包过程中会先组装 tmp/，在回调阶段写入 source/（及 python 的 manifest 相关文件），再压缩为 zip。

模板变量配置

SEE 平台支持多种类型的模板变量控件，用于在部署时动态配置应用参数。详细说明见 TYPE.md。

支持的控件类型

• input: 普通文本输入框
• editor: 大文本编辑框
• select: 单选下拉框
• switch: 开关组件
• smallfile: 文件上传控件（小于 2M）
• switchForm: 开关表单
• complexSelect: 复杂单选框
• table: 表格控件
• division: 分栏折叠控件
• password: 密码输入框（加密存储）
• hidden: 隐藏输入框

示例配置

const variables = [
  {
    type: 'input',
    label: '应用标题',
    tooltip: '设置应用的显示标题',
    name: 'APP_TITLE'
  },
  {
    type: 'select',
    label: '环境选择',
    options: 'dev:开发环境;test:测试环境;prod:生产环境',
    name: 'ENVIRONMENT'
  },
  {
    type: 'switch',
    label: '启用调试',
    name: 'DEBUG_MODE'
  }
];

发布包结构

默认输出路径：{seePackagePath}/{seePackageName}.zip（例如 package/winner-front-my-app-1.0.0.zip）。

see-package.zip
├── deploy.xml
├── template/
│   └── config.local.js | sysconfig.js | 自定义名.js
├── scripts/
│   └── {name}/
│       ├── install.py | install.sh
│       ├── afterInstall.py | afterInstall.sh
│       ├── uninstall.py | uninstall.sh
│       ├── utils.py              # 仅 python
│       ├── beforeInstall.sh        # 仅 python
│       ├── conf/manifest.*.json    # 仅 python 且 dist 含 manifest 时
│       └── js/                     # 仅 enableObfuscation === true
│           ├── confuse.js          # node 强混淆入口
│           ├── confuse.sh          # 无 node 时的 bash 轻量混淆
│           └── obfuscator.js       # javascript-obfuscator 运行时
└── source/                         # 安装脚本从 tmp/source 部署到 workspace
    └── ...

scriptsType === 'python' 且存在 manifest.{timestamp}.json 时，按 manifest 拷贝文件到 source/；否则将整个 outputName 目录拷贝到 source/。scriptsType === 'bash' 时始终拷贝整个 outputName 到 source/。

使用场景

1. 外框架应用（bizframe）

generateSeePackageZip(
  {
    type: 'bizframe',
    name: 'main-frame',
    version: '1.0.0',
    description: '主框架应用'
  },
  () => {}
);

2. 子系统应用（subsystem）

generateSeePackageZip(
  {
    type: 'subsystem',
    name: 'user-management',
    version: '1.0.0',
    description: '用户管理子系统'
  },
  () => {}
);

子系统安装目录需指向具体前端根目录（如 /home/hsiar/hsiar-green/html/），详见控制台完成提示。

3. 开启配置 JS 混淆

混淆必须在 SEE 注入配置变量之后执行，因此放在 afterInstall，不能提前到打包阶段。

generateSeePackageZip(
  {
    name: 'my-app',
    version: '1.0.0',
    scriptsType: 'bash',
    enableObfuscation: true,
    description: '开启 afterInstall 混淆'
  },
  () => {}
);

运行时策略（bash / python 脚本一致）：

1. 检测到 node → 执行 confuse.js（AST 级强混淆）
2. 未检测到 node → 执行 confuse.sh（整文件 base64 + TextDecoder/new Function 包裹，UTF-8 安全）
3. 文件已含 __WINNER_BASH_OBFUSCATED__ 标记时，confuse.sh 会跳过，避免重复包裹

confuse.sh 仅作无 node 环境的兼容兜底，防护强度远低于 confuse.js。

4. Docker 容器化部署

generateSeePackageZip(
  {
    name: 'my-app',
    version: '1.0.0',
    seePackageType: 'docker',
    dockerImage: 'my-app:1.0.0',
    description: '容器化应用'
  },
  () => {}
);

注意事项

1. copyFiles：源文件路径为 `${outputName}/${name}/文件名`，不是项目根目录直写路径。
2. configName：除手动指定外，会根据 outputName 下是否存在 config.local.js / sysconfig.js 自动选用文件名。
3. name 特殊字符：@、/ 会在打包前替换为 -。
4. Docker：使用 Docker 部署时需确保镜像已构建并可被 SEE 环境拉取。
5. 混淆：enableObfuscation: true 时打包 scripts/{name}/js/；afterInstall 优先用 node+confuse.js，无 node 时回退 bash+confuse.sh。纯 bash 无法复现 javascript-obfuscator 级别的混淆。
6. Python 脚本：目标环境需具备 Python 运行时；开启混淆时建议有 node，否则走 bash 轻量混淆（仍需系统有 bash / base64）。

更新日志

详见 CHANGELOG.md。

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request。