@openlee/deploy-cli

通过 SSH 将前端和全栈项目部署到云服务器的通用 CLI 工具。

功能特性

• 两种部署模式：静态构建（纯前端）和 Docker（全栈）
• 配置自动发现：自动查找当前目录的 deploy.config.js
• Demo 支持：自动检测并构建 SDK 项目的 demo/ 子目录
• Nginx Proxy Manager 集成：通过 API 同步代理主机配置和 SSL 证书
• 部署历史：支持部署追踪和回滚
• 生命周期钩子：在构建和部署前后执行自定义命令

安装

npm install -g @openlee/deploy-cli

快速开始

# 1. 进入你的项目目录
cd your-project

# 2. 交互式创建配置文件
deploy-cli init

# 3. 部署
deploy-cli deploy stg

命令列表

| 命令 | 说明 | |------|------| | deploy-cli init | 交互式创建配置文件 | | deploy-cli deploy [env] | 部署到指定环境（stg/prd） | | deploy-cli rollback [env] | 回滚到上一次部署 | | deploy-cli list [env] | 查看部署历史 | | deploy-cli status [env] | 查看当前部署状态 | | deploy-cli sync-nginx [env] | 同步 Nginx Proxy Manager 配置 | | deploy-cli find | 查找当前目录的配置文件 |

所有命令支持 -c, --config <path> 指定自定义配置文件。

配置说明

在项目根目录创建 deploy.config.js：

export default {
  app: 'my-app',
  host: '134.175.231.51',

  ssh: {
    port: 22,
    username: 'ubuntu',
    privateKey: '~/.ssh/id_rsa',
  },

  gitee: {
    repo: 'https://gitee.com/user/repo.git',
    branch: 'master',
    token: 'your-token',  // 可选，私有仓库需要
  },

  environments: {
    stg: {
      mode: 'static',  // 或 'docker'
      buildCmd: 'rm -f package-lock.json && npm install && npm run build',
      remoteDir: '/home/ubuntu/apps/my-app/stg',

      // Demo 子项目（如果 demo/ 存在会自动检测）
      demoBuildCmd: 'npm install && npm run build',
      demoDist: 'dist',
      npmStaticDir: '/opt/npm/data/static/my-app',

      npm: {
        domain: 'stg.myapp.com',
        type: 'static',  // 或 'proxy'
        ssl: true,
      },

      hooks: {
        beforeBuild: '',
        afterBuild: '',
        beforeDeploy: '',
        afterDeploy: '',
      },
    },
  },

  npmApi: {
    baseUrl: 'http://134.175.231.51:81',
    username: '[email protected]',
    password: 'password',
  },
};

配置自动发现

不指定 --config 时，deploy-cli 按以下顺序查找配置：

1. deploy.config.js（精确匹配）
2. 包含 app: 和 environments: 的 *.config.js（启发式匹配）
3. 如果只有一个 *.config.js，直接使用

SSH 密钥路径

支持波浪号展开和相对路径：

ssh: {
  privateKey: '~/.ssh/id_rsa',           // ~/ 展开为用户主目录
  privateKey: './keys/Office.pem',       // 相对于配置文件
}

部署模式

静态模式

适用于纯前端项目，在服务器上通过 SSH 构建：

1. 在服务器上克隆或拉取代码
2. 执行构建命令
3. 可选构建 demo/ 子目录
4. 同步到 NPM 静态目录（如已配置）

Docker 模式

适用于全栈项目，使用 Docker Compose：

1. 在服务器上克隆或拉取代码
2. 执行 docker compose down && docker compose up -d --build
3. 可选同步 demo/ 构建产物到 NPM 静态目录

Demo 项目

对于有 demo 的 SDK/库项目，将 demo 放在 demo/ 目录：

project/
├── package.json
├── src/
├── demo/           # 自动检测
│   ├── package.json
│   └── vite.config.js
└── dist/

CLI 会自动：

• 检测 demo/ 目录是否存在
• 在 demo/ 内执行 demoBuildCmd
• 将 demo/dist 复制到 npmStaticDir

Claude Code 集成

本仓库包含 Claude Code skill 文件，位于 .claude/commands/deploy.md。

安装 Skill

将 skill 文件复制到你的 Claude Code commands 目录：

# macOS / Linux
mkdir -p ~/.claude/commands
cp .claude/commands/deploy.md ~/.claude/commands/

# Windows (Git Bash)
mkdir -p ~/.claude/commands
cp .claude/commands/deploy.md ~/.claude/commands/

# Windows (PowerShell)
mkdir -Force "$env:USERPROFILE\.claude\commands"
Copy-Item .claude\commands\deploy.md "$env:USERPROFILE\.claude\commands\"

使用

安装后，在任何项目中使用 Claude Code 的 /deploy 命令：

/deploy          # 交互式部署
/deploy stg      # 部署到测试环境
/deploy prd      # 部署到生产环境

Claude 会引导你完成部署流程，包括配置发现、环境选择和验证。

常见问题

服务器构建时内存不足 (OOM)

服务器内存有限（2GB），添加 swap 空间：

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

npm install 超时

package-lock.json 中的私有 registry URL 可能导致超时。CLI 会在构建前自动删除它。

Top-level await 错误

pdfjs-dist 等库需要 ES2022。在 vite.config.js 中添加：

export default {
  build: { target: 'es2022' },
  esbuild: { target: 'es2022' },
}

许可证

MIT