HZX Deploy CLI

一个现代化的前端自动部署脚手架工具，支持多环境配置、前置后置指令和集群部署。基于 TypeScript 开发，使用 pnpm 管理依赖。

✨ 特性

• 🚀 现代化技术栈: TypeScript + pnpm + Vitest
• 🔧 灵活配置: 支持多环境配置和集群部署
• 📋 前置后置指令: 支持自定义前置和后置指令执行
• 🔐 安全连接: 支持密码和SSH密钥认证
• 🗂️ 自动备份: 部署前自动备份远程文件
• 📊 详细日志: 支持详细模式和步骤显示
• 🎯 演练模式: 支持干跑模式验证配置
• 🔄 集群部署: 支持一键部署到多个环境

📦 安装

全局安装

npm install -g hzx-deploy-cli
# 或者
pnpm add -g hzx-deploy-cli

本地安装

npm install --save-dev hzx-deploy-cli
# 或者
pnpm add -D hzx-deploy-cli

🚀 快速开始

1. 初始化配置文件

hzx-deploy init

根据提示填写配置信息，将在项目根目录生成 deploy.config.js 文件。

2. 修改配置文件

编辑生成的 deploy.config.js 文件，根据实际情况配置各环境参数：

module.exports = {
  projectName: 'my-project',
  privateKey: '/Users/username/.ssh/id_rsa', // 可选
  passphrase: '', // 可选
  readyTimeout: 20000,
  cluster: [], // 集群部署配置: ['dev', 'test', 'prod']
  
  // 开发环境
  dev: {
    name: '开发环境',
    script: 'npm run build', // 构建命令
    host: '192.168.1.100',
    port: 22,
    username: 'root',
    password: '123456', // 或使用privateKey
    distPath: 'dist', // 本地构建目录
    webDir: '/var/www/html', // 远程部署目录
    bakDir: '/var/www/backup', // 备份目录
    isRemoveRemoteFile: true,
    isRemoveLocalFile: true,
    preCommands: [
      'echo "开始部署..."',
      'sudo systemctl stop nginx'
    ],
    postCommands: [
      'sudo systemctl start nginx',
      'echo "部署完成!"'
    ]
  }
}

3. 执行部署

# 部署到指定环境
hzx-deploy deploy --mode dev

# 集群部署（需要配置cluster字段）
hzx-deploy deploy

# 演练模式（只验证配置）
hzx-deploy deploy --mode dev --dry

# 详细日志模式
hzx-deploy deploy --mode dev --verbose

📖 命令详解

初始化命令

hzx-deploy init
hzx-deploy i  # 简写

部署命令

hzx-deploy deploy [options]
hzx-deploy d [options]  # 简写

选项：

• -m, --mode <mode>: 指定部署环境 (dev/test/prod)
• -c, --config <path>: 指定配置文件路径
• --dry: 演练模式，只验证配置不执行实际部署
• --verbose: 显示详细日志

示例：

hzx-deploy deploy --mode prod --verbose
hzx-deploy deploy --config ./custom.config.js
hzx-deploy deploy --dry  # 演练模式

⚙️ 配置文件详解

基本配置

module.exports = {
  projectName: 'project-name',    // 项目名称（必需）
  privateKey: '/path/to/key',     // SSH私钥路径（可选）
  passphrase: 'key-passphrase',   // 私钥密码（可选）
  readyTimeout: 20000,            // 连接超时时间（毫秒）
  cluster: ['dev', 'test']        // 集群部署环境列表
}

环境配置

每个环境配置支持以下字段：

| 字段 | 类型 | 必需 | 默认值 | 说明 | |------|------|------|--------|------| | name | string | ✓ | - | 环境名称 | | host | string | ✓ | - | 服务器地址 | | username | string | ✓ | - | 登录用户名 | | distPath | string | ✓ | - | 本地构建目录 | | webDir | string | ✓ | - | 远程部署目录 | | script | string | ✗ | - | 构建脚本 | | port | number | ✗ | 22 | SSH端口 | | password | string | ✗ | - | 登录密码 | | privateKey | string | ✗ | - | SSH私钥路径 | | passphrase | string | ✗ | - | 私钥密码 | | bakDir | string | ✗ | - | 备份目录 | | isRemoveRemoteFile | boolean | ✗ | true | 是否删除远程文件 | | isRemoveLocalFile | boolean | ✗ | true | 是否删除本地文件 | | preCommands | string[] | ✗ | [] | 前置指令 | | postCommands | string[] | ✗ | [] | 后置指令 | | readyTimeout | number | ✗ | 20000 | 连接超时时间 |

🔧 前置和后置指令

支持在部署过程中执行自定义指令：

dev: {
  // ... 其他配置
  preCommands: [
    'echo "准备部署..."',
    'sudo systemctl stop nginx',
    'rm -rf /tmp/deploy-cache'
  ],
  postCommands: [
    'sudo systemctl start nginx',
    'curl -f http://localhost/health',
    'echo "部署完成，服务已启动"'
  ]
}

执行时机：

1. 构建项目
2. 验证本地文件
3. 连接SSH服务器
4. 执行前置指令 ← 新功能
5. 备份远程文件
6. 上传文件
7. 执行后置指令 ← 新功能
8. 清理本地文件

🔗 集群部署

配置 cluster 字段启用集群部署：

module.exports = {
  cluster: ['dev', 'test', 'prod'],
  dev: { /* 开发环境配置 */ },
  test: { /* 测试环境配置 */ },
  prod: { /* 生产环境配置 */ }
}

执行集群部署：

hzx-deploy deploy  # 自动部署到cluster配置的所有环境

🛡️ 安全性

SSH认证方式

支持两种认证方式：

1. 密码认证：

{
  username: 'root',
  password: '123456'
}

2. 密钥认证（推荐）：

{
  username: 'root',
  privateKey: '/Users/username/.ssh/id_rsa',
  passphrase: 'key-password'  // 如果私钥有密码
}

密码保护

如果不想在配置文件中保存密码，可以删除 password 字段，部署时会提示输入。

📊 本地开发

安装依赖

pnpm install

开发模式

pnpm dev

构建项目

pnpm build

运行测试

pnpm test
pnpm test:coverage
pnpm test:ui

代码检查

pnpm lint
pnpm lint:fix
pnpm format

🧪 测试

单元测试

pnpm test

测试覆盖率

pnpm test:coverage

交互式测试

pnpm test:ui

📝 示例配置

package.json 脚本配置

如果使用本地安装，可以在 package.json 中添加脚本：

{
  "scripts": {
    "deploy": "hzx-deploy deploy",
    "deploy:dev": "hzx-deploy deploy --mode dev",
    "deploy:test": "hzx-deploy deploy --mode test",
    "deploy:prod": "hzx-deploy deploy --mode prod",
    "deploy:dry": "hzx-deploy deploy --dry"
  }
}

然后使用：

npm run deploy:dev

Docker环境配置示例

prod: {
  name: '生产环境',
  script: 'npm run build:prod',
  host: 'prod.example.com',
  username: 'deploy',
  privateKey: '/Users/username/.ssh/id_rsa',
  distPath: 'dist',
  webDir: '/var/www/html',
  bakDir: '/var/www/backup',
  preCommands: [
    'docker-compose down',
    'docker system prune -f'
  ],
  postCommands: [
    'docker-compose up -d',
    'docker ps'
  ]
}

🔧 故障排除

常见问题

1. SSH连接失败

   • 检查服务器地址和端口
   • 确认用户名和认证信息
   • 检查防火墙设置

2. 构建失败

   • 检查构建脚本是否正确
   • 确认本地环境是否正常
   • 查看详细错误日志

3. 文件上传失败

   • 检查远程目录权限
   • 确认磁盘空间充足
   • 检查网络连接

调试技巧

使用详细模式获取更多信息：

hzx-deploy deploy --mode dev --verbose

使用演练模式验证配置：

hzx-deploy deploy --mode dev --dry

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 支持

如果遇到问题，请提交 Issue。