@winner-fed/winner-deploy
Version:
Generate a publication deployed by the See platform
316 lines (258 loc) • 9.22 kB
Markdown
# @winner-fed/winner-deploy
> 用于生成 SEE 平台部署包的工具库
## 简介
`@winner-fed/winner-deploy` 是一个专门为 SEE 平台设计的部署包生成工具。它可以将前端项目打包成符合 SEE 平台规范的部署包，支持多种应用类型和部署模式。
## 特性
- 🚀 支持外框架（bizframe）和子系统（subsystem）两种应用类型
- 📦 自动生成 SEE 平台所需的 manifest.json 和 deploy.xml 配置文件
- 🐳 支持 Docker 容器化部署
- 🔧 灵活的模板变量配置系统
- 📝 支持 Python 和 Bash 两种脚本类型
- 🎯 可自定义文件拷贝和配置生成逻辑
## 安装
```bash
npm install @winner-fed/winner-deploy
# 或
yarn add @winner-fed/winner-deploy
# 或
pnpm add @winner-fed/winner-deploy
```
## 快速开始
### 基础用法
```javascript
import { generateSeePackageZip } from '@winner-fed/winner-deploy';
// 最简单的使用方式
generateSeePackageZip({
name: 'my-app',
version: '1.0.0',
description: '我的应用'
});
```
### 完整配置示例
```javascript
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<string> | [] | 否 | 需要直接拷贝到 SEE 包的文件列表 |
| templateFunc | function | - | 否 | 自定义变量配置文件生成函数 |
| variablesFunc | function | - | 否 | deploy.xml 模板变量配置函数 |
#### templateFunc 函数
用于自定义变量配置文件的生成逻辑。
```javascript
templateFunc: function() {
if (type === 'bizframe') {
return `./dist/config.local.js`;
}
// 返回配置文件路径
}
```
#### variablesFunc 函数
用于配置 deploy.xml 模板变量，支持动态配置。
```javascript
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 配置中的文件。
```javascript
copyFiles: [
'version.js', // 项目根目录下的 version.js
'assets/logo.png', // assets 目录下的 logo.png
'config/env.json' // config 目录下的 env.json
];
```
#### callback 回调函数
```javascript
function callback(error, result) {
if (error) {
// 处理错误
console.error('生成失败:', error);
} else {
// 处理成功结果
console.log('生成成功:', result);
}
}
```
## 模板变量配置
SEE 平台支持多种类型的模板变量控件，用于在部署时动态配置应用参数。详细的模板变量配置说明请参考 [TYPE.md](./TYPE.md)。
### 支持的控件类型
- **input**: 普通文本输入框
- **select**: 单选下拉框
- **switch**: 开关组件
- **smallfile**: 文件上传控件（小于 2M）
- **switchForm**: 开关表单
- **complexSelect**: 复杂单选框
- **table**: 表格控件
- **division**: 分栏折叠控件
- **password**: 密码输入框（数据加密存储）
- **hidden**: 隐藏输入框（不显示给用户）
### 示例配置
```javascript
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）
适用于作为主框架的运行的子应用。
```javascript
generateSeePackageZip({
type: 'bizframe',
name: 'main-frame',
version: '1.0.0',
description: '主框架应用'
});
```
### 2. 子系统应用（subsystem）
适用于业务子系统，通常作为微前端模块。
```javascript
generateSeePackageZip({
type: 'subsystem',
name: 'user-management',
version: '1.0.0',
description: '用户管理子系统'
});
```
### 3. Docker 容器化部署
支持生成容器化部署的 SEE 包。
```javascript
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](./CHANGELOG.md)。
## 许可证
MIT License
## 贡献
欢迎提交 Issue 和 Pull Request 来改进这个项目。