npm package: @fimagine/frontend_deployer
Description: frontend deployer
Author: Gim
Latest version: 1.1.3

# frontend_deployer

基于nodejs、ssh2、ali-oss实现的部署工具

## 命令

- 完整命令 `fdeploy -p deployer.config.json -i deployer.private.json -s release_0,release_1`

- ~~已通过pkg直接生成了各平台直接使用的执行文件，可以在此[下载](https://gitee.com/fimagine/frontend_deployer/releases/tag/v1.0.7)~~

- 参数说明

|参数名|说明|
|-|-|
| -p | 公共配置文件，默认deployer.config.json，当文件不存在时，则会帮你创建，需要编辑后才能用 |
| -i | 私有配置文件，默认deployer.private.json，当文件不存在时，则会帮你创建，需要编辑后才能用 |
| -s | 打包**方案**, 多个则以逗号分隔，参数: -s，比如执行两个**方案**“production”与“stage”，则参数填写为: -s production,stage |

## 安装到项目中

若项目是npm包项目，可以使用如下命令，单独安装至项目中

`npm install @fimagine/frontend_deployer --save-dev`

当然，也支持全局安装

`npm install @fimagine/frontend_deployer -g`

## 配置文件

要让fdeploy工作必须有“公共配置”与“私有配置”，配置文件是标准的json文件

配置根节点下，除了**NOT_EDITED**，其他均视为**方案**，**方案**在公共配置与私有配置是意义对应的

由于json是多层的，后续表格字段采用路径表示。

例： `{ "A": { "B": 0 } }`中，B的字段路径为 `A/B`。

### 公共配置示例

```json
{
  "stage_0": {
    "SSH_HOST": "123.123.123.123",
    "SSH_PORT": "2022",
    "REMOTE_DIR": "/opt/demo",
    "REMOTE_BACKUP_DIR": "/opt/demo_backup",
    "LOCAL_PATH": "./build",
    "GIT_BRANCH": "origin/main",
    "GIT_IGNORED": false,
    "GIT_NO_BEHIND": true,
    "GIT_NO_AHEAD": true,
    "GIT_NO_DIRTY": true,
  },
  "release_1": {
    "...": "...",
  },
  "release_2": {
    "...": "...",
  }
}
```

### 公共配置说明

当工作目录下不存在私有配置文件，deployer将会创建一个默认的私有配置文件（默认名为deployer.config.json）

| 字段路径 | 值类型 | 必填 | 默认 | 说明 |
| - | - | - | - | - |
| NOT_EDITED             | any    | 否 | -     | 配置文件根下，存在此字段说明配置文件未完成编辑，deployer将不能使用此配置，生成的空白配置文件才会存在此字段，用户自己不需要使用 |
| 方案                   | object | 否 | -     | 配置文件根下，除了**NOT_EDITED**，其他均视为**方案** |
| 方案/SSH_HOST          | string | 是 | -     | ssh主机的地址 |
| 方案/SSH_PORT          | string | 否 | 22    | ssh主机的ssh服务端口 |
| 方案/REMOTE_DIR        | string | 否 | -     | ssh主机上的目标目录（绝对路径），若LOCAL_PATH指向文件，将会将LOCAL_PATH指向的文件上传至REMOTE_DIR，若LOCAL_PATH指向目录，将会将LOCAL_PATH目录下全部文件上传至REMOTE_DIR中（目录结构会被保留） |
| 方案/REMOTE_BACKUP_DIR | string | 否 | -     | ssh主机上的备份目录（绝对路径），每一次发布，原来的目标文件将拷贝至此目录下的“以日期时间为名”的子目录中。若不设置，将不进行“远端本机备份” |
| 方案/LOCAL_PATH        | string | 否 | -     | 本地相对路径（相对于工作目录），可以是单个文件，可以是目录，当为目录，目录下全部文件将会被上传 |
| 方案/GIT_IGNORED       | string | 否 | false | 若true，则不比较git历史 |
| 方案/GIT_BRANCH        | string | 否 | false | 远端分支名，允许为正则表达式，例：origin/main、origin/develop-(.*) |
| 方案/GIT_NO_BEHIND     | string | 否 | true  | 若true，则不允许本地提交落于远端 |
| 方案/GIT_NO_AHEAD      | string | 否 | true  | 若true，则不允许本地提交超前远端 |
| 方案/GIT_NO_DIRTY      | string | 否 | true  | 若true，则不允许存在未提交代码 |

### 私有配置示例

```json
{
  "stage_0": {
    "SSH_USER": "root",
    "SSH_PASS": "password",
    "SSH_PRI_KEY_PATH": "demo.pem",
    "SSH_PRI_KEY_PASS": "demo_pem_password"
  },
  "release_1": {
    "...": "...",
  },
  "release_2": {
    "...": "...",
  }
}
```

### 私有配置说明

当工作目录下不存在私有配置文件，deployer将会创建一个默认的私有配置文件（默认名为deployer.private.json）

注意：**私有配置文件不应提交至代码仓库中**

| 字段路径 | 值类型 | 必填 | 默认 | 说明 |
| - | - | - | - | - |
| NOT_EDITED             | any    | 否 | -     | 配置文件根下，存在此字段说明配置文件未完成编辑，deployer将不能使用此配置，生成的空白配置文件才会存在此字段，用户自己不需要使用 |
| 方案                   | object | 否 | -     | 配置文件根下，除了**NOT_EDITED**，其他均视为**方案** |
| 方案/SSH_USER          | string | 否 | root  | ssh登录用户名，若不需要，移除此字段 |
| 方案/SSH_PASS          | string | 否 | -     | ssh登录密码，若不需要，移除此字段 |
| 方案/SSH_PRI_KEY_PATH  | string | 否 | -     | ssh密钥文件路径，可以是绝对目录，也可以是相对目录（相对于工作目录），例: ./demo.pem |
| 方案/SSH_PRI_KEY_PASS  | string | 否 | -     | ssh密钥密码，若不需要，移除此字段 |

## 待办项

- 支持“预执行命令”
- 支持“后执行命令”
- 支持“远端备份到本地”
- 支持“远端备份到远端”