@winner-fed/winner-deploy

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

简介

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

特性

• 🚀 支持外框架（bizframe）和子系统（subsystem）两种应用类型
• 📦 自动生成 SEE 平台所需的 manifest.json 和 deploy.xml 配置文件
• 🐳 支持 Docker 容器化部署
• 🔧 灵活的模板变量配置系统
• 📝 支持 Python 和 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: '我的应用'
});

完整配置示例

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

generateSeePackageZip(
  {
    system: 'winner-front',
    type: 'subsystem',
    name: 'my-app',
    appType: 'my-app',
    version: '1.0.0',
    group: 'bizframe',
    configName: 'config.local',
    outputName: 'dist',
    description: '我的应用部署包',
    seePackageType: 'web',
    scriptsType: 'python',
    copyFiles: ['version.js', 'logo.png'],
    templateFunc: () => {
      return './dist/config.local.js';
    },
    variablesFunc: () => {
      return [
        {
          type: 'input',
          label: '应用标题',
          name: 'APP_TITLE',
          default: '默认标题'
        }
      ];
    }
  },
  (err, result) => {
    if (err) {
      console.error('生成失败:', err);
    } else {
      console.log('生成成功:', result);
    }
  }
);

API 文档

generateSeePackageZip(options, callback)

生成 SEE 平台部署包的主要函数。

参数说明

| 参数名 | 类型 | 默认值 | 必填 | 说明 | | -------------- | ------------- | ------------------------------ | ---- | -------------------------------------------------------- | | system | string | 'winner-front' | 否 | 系统类型，SEE 平台的分组维度 | | type | string | 'subsystem' | 否 | 应用类型：'bizframe'（外框架）或 'subsystem'（子系统） | | name | string | - | 是 | 发布物名称 | | appType | string | name 的值 | 否 | 发布物类型 | | version | string | - | 是 | 发布包版本 | | group | string | 'bizframe' | 否 | 应用分组 | | configName | string | 'config.local' | 否 | 配置文件名称（不含 .js 后缀） | | outputName | string | 'dist' | 否 | 输出目录名称 | | description | string | - | 否 | 发布包说明 | | seePackageName | string | ${system}-${name}-${version} | 否 | SEE 发布物的包名（zip 文件名） | | seePackageType | string | 'web' | 否 | SEE 平台发布物包类型：'web' 或 'docker' | | dockerImage | string | - | 否 | Docker 容器化镜像名（seePackageType 为 'docker' 时生效） | | scriptsType | string | 'python' | 否 | 脚本类型：'python' 或 'bash' | | copyFiles | Array | [] | 否 | 需要直接拷贝到 SEE 包的文件列表 | | templateFunc | function | - | 否 | 自定义变量配置文件生成函数 | | variablesFunc | function | - | 否 | deploy.xml 模板变量配置函数 |

templateFunc 函数

用于自定义变量配置文件的生成逻辑。

templateFunc: function() {
  if (type === 'bizframe') {
    return `./dist/config.local.js`;
  }
  // 返回配置文件路径
}

variablesFunc 函数

用于配置 deploy.xml 模板变量，支持动态配置。

variablesFunc: function() {
  const context = process.cwd();
  if (type === 'bizframe') {
    try {
      const { variables } = require(path.resolve(
        context,
        'build',
        'package',
        './variables.js'
      ));
      return variables || [];
    } catch (error) {
      console.error(error);
      return [];
    }
  }
  return [];
}

copyFiles 配置

指定需要直接拷贝到 SEE 包中但不包含在 manifest.json 配置中的文件。

copyFiles: [
  'version.js', // 项目根目录下的 version.js
  'assets/logo.png', // assets 目录下的 logo.png
  'config/env.json' // config 目录下的 env.json
];

callback 回调函数

function callback(error, result) {
  if (error) {
    // 处理错误
    console.error('生成失败:', error);
  } else {
    // 处理成功结果
    console.log('生成成功:', result);
  }
}

模板变量配置

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

支持的控件类型

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

示例配置

const variables = [
  {
    type: 'input',
    label: '应用标题',
    tooltip: '设置应用的显示标题',
    name: 'APP_TITLE',
    default: '默认应用标题'
  },
  {
    type: 'select',
    label: '环境选择',
    options: 'dev:开发环境;test:测试环境;prod:生产环境',
    tooltip: '选择部署环境',
    name: 'ENVIRONMENT',
    default: 'dev'
  },
  {
    type: 'switch',
    label: '启用调试',
    tooltip: '是否启用调试模式',
    name: 'DEBUG_MODE',
    default: false
  },
  {
    type: 'password',
    label: '数据库密码',
    tooltip: '数据库连接密码',
    name: 'DB_PASSWORD',
    required: true,
    default: ''
  },
  {
    type: 'hidden',
    label: '应用版本号',
    tooltip: '应用内部版本号，用于系统识别',
    name: 'APP_VERSION',
    default: '1.0.0'
  }
];

项目结构

生成的 SEE 部署包包含以下文件：

see-package.zip
├── manifest.json          # 应用清单文件
├── deploy.xml            # 部署配置文件
├── install.py/.sh        # 安装脚本
├── uninstall.py/.sh      # 卸载脚本
├── start.py/.sh          # 启动脚本
├── stop.py/.sh           # 停止脚本
├── config.local.js       # 配置文件（如果存在）
└── dist/                 # 应用文件目录
    └── ...

使用场景

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: '用户管理子系统'
});

3. Docker 容器化部署

支持生成容器化部署的 SEE 包。

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

注意事项

1. 文件路径: copyFiles 中的文件路径是相对于项目根目录的
2. 配置文件: 配置文件名不需要包含 .js 后缀
3. 版本号: 建议使用语义化版本号格式
4. Docker 镜像: 使用 Docker 部署时需要确保镜像已构建并推送到镜像仓库
5. 脚本类型: Python 脚本需要目标环境支持 Python 运行时

更新日志

详细的更新日志请查看 CHANGELOG.md。

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目。