@noahyu/cd-cli 1.0.0 → 1.1.0

package/README.md

@@ -1,4 +1,4 @@
-# CD CLI - 简易部署工具
+# 简易项目部署工具
 
 一个简易的部署工具，支持版本管理和零停机部署。
 
@@ -9,7 +9,7 @@
 - 🔄 零停机部署：使用软链接实现原子性切换
 - ⏪ 快速回滚：一键回滚到任意历史版本
 - 📝 版本列表：查看服务器上所有已部署版本
-- 🔒 安全连接：支持密码和私钥认证
+- 🔒 SSH 认证：支持密码、密钥
 - 🔄 PM2 集成：自动重启 PM2 应用
 - 📝 配置灵活：支持部署前后执行自定义命令
 - 🎯 文件过滤：支持排除不需要的文件
@@ -92,65 +92,139 @@ PM2 配置始终指向软链接 `.output/server/index.mjs`，这样切换版本
 ```javascript
 // pcli-cd 部署配置文件
 export default {
-  // 构建命令 (可选)
+  /** 构建命令 (可选)：构建项目 */
   buildCommand: 'npm run build',
-
-  // 构建输出目录
+  /** 构建输出目录 */
   buildDir: '.output',
-
-  // 版本号 (可选，不指定会在部署时询问)
+  /** 版本号 (可选，不指定会在部署时询问) */
   version: 'v1.0.0',
-
-  // 服务器配置
+  /** 服务器配置 */
   server: {
+    /** 服务器地址 */
     host: '192.168.1.100',
+    /** 端口号 */
     port: 22,
+    /** 用户名 */
     username: 'root',
-    password: 'your-password', // 密码或私钥二选一
-    // privateKey: '/path/to/private/key',
+    // SSH 认证方式（优先级：privateKey > privateKeyPath > password）
+    /** 私钥 */
+    privateKey: '-----BEGIN OPENSSH PRIVATE KEY-----\n...\n-----END OPENSSH PRIVATE KEY-----',
+    /** 私钥文件路径 */
+    privateKeyPath: '/home/user/.ssh/id_rsa',
+    /** 密码 */
+    password: 'your-password',
+    /** 部署目录 */
     deployPath: '/var/www/your-app',
   },
-
-  // PM2 配置 (可选)
+  /** PM2 配置 (可选) */
   pm2: {
+    /** 进程名称 */
     appName: 'your-app-name',
+    /** 是否立即重启 */
     restart: true,
   },
 
-  // 排除的文件 (可选) - 作用于构建产物目录
-  // 请根据构建输出的实际内容谨慎配置
+  /**
+   * 排除的文件 (可选) - 作用于构建产物目录
+   *
+   * 请根据构建输出的实际内容谨慎配置
+   */
   excludeFiles: [
     // '**/*.map',        // Source Map 文件
     // '**/.DS_Store',    // macOS 系统文件
     // '**/Thumbs.db'     // Windows 缩略图缓存
   ],
-
-  // 部署前命令 (可选)
+  /** 部署前命令 (可选) */
   beforeDeploy: ['npm run test'],
-
-  // 部署后命令 (可选)
+  /** 部署后命令 (可选) */
   afterDeploy: ['npm install --production'],
 }
 ```
 
+## SSH 认证配置
+
+工具支持三种 SSH 认证方式，优先级为：`privateKey` > `privateKeyPath` > `password`
+
+### 方式一：私钥内容（推荐用于 CI/CD）
+
+适用于 CI/CD 环境，将私钥内容作为环境变量传入：
+
+```javascript
+export default {
+  server: {
+    host: '192.168.1.100',
+    username: 'root',
+    privateKey: process.env.SSH_PRIVATE_KEY, // 从环境变量读取
+    deployPath: '/var/www/app',
+  },
+}
+```
+
+### 方式二：私钥文件路径（推荐用于本地开发）
+
+适用于本地开发环境，使用本地私钥文件：
+
+```javascript
+export default {
+  server: {
+    host: '192.168.1.100',
+    username: 'root',
+    privateKeyPath: '/home/user/.ssh/id_rsa',
+    deployPath: '/var/www/app',
+  },
+}
+```
+
+### 方式三：密码认证
+
+适用于简单测试环境（生产环境不推荐）：
+
+```javascript
+export default {
+  server: {
+    host: '192.168.1.100',
+    username: 'root',
+    password: 'your-password',
+    deployPath: '/var/www/app',
+  },
+}
+```
+
+### 优先级说明
+
+当配置了多种认证方式时，工具会按以下优先级选择：
+
+1. **privateKey**（私钥内容）- 最高优先级
+2. **privateKeyPath**（私钥文件路径）- 中等优先级
+3. **password**（密码）- 最低优先级
+
+### 安全建议
+
+- ✅ **生产环境**：使用私钥认证（`privateKey` 或 `privateKeyPath`）
+- ✅ **CI/CD**：使用 `privateKey` + 环境变量
+- ✅ **本地开发**：使用 `privateKeyPath`
+- ⚠️ **测试环境**：可以使用密码认证
+- ❌ **避免**：在配置文件中硬编码密码或私钥内容
+
 ## 配置选项
 
-| 选项                | 类型     | 必填 | 说明                             |
-| ------------------- | -------- | ---- | -------------------------------- |
-| `buildCommand`      | string   | 否   | 构建命令，如 "npm run build"     |
-| `buildDir`          | string   | 是   | 构建输出目录，如 ".output"       |
-| `version`           | string   | 否   | 版本号，不指定会在部署时询问     |
-| `server.host`       | string   | 是   | 服务器地址                       |
-| `server.port`       | number   | 否   | SSH 端口，默认 22                |
-| `server.username`   | string   | 是   | 用户名                           |
-| `server.password`   | string   | 否   | 密码                             |
-| `server.privateKey` | string   | 否   | 私钥路径                         |
-| `server.deployPath` | string   | 是   | 服务器部署路径                   |
-| `pm2.appName`       | string   | 否   | PM2 应用名称                     |
-| `pm2.restart`       | boolean  | 否   | 是否重启 PM2 应用                |
-| `excludeFiles`      | string[] | 否   | 排除的文件模式（相对于构建目录） |
-| `beforeDeploy`      | string[] | 否   | 部署前执行的命令                 |
-| `afterDeploy`       | string[] | 否   | 部署后执行的命令                 |
+| 选项                    | 类型     | 必填 | 说明                             |
+| ----------------------- | -------- | ---- | -------------------------------- |
+| `buildCommand`          | string   | 否   | 构建命令，如 "npm run build"     |
+| `buildDir`              | string   | 是   | 构建输出目录，如 ".output"       |
+| `version`               | string   | 否   | 版本号，不指定会在部署时询问     |
+| `server.host`           | string   | 是   | 服务器地址                       |
+| `server.port`           | number   | 否   | SSH 端口，默认 22                |
+| `server.username`       | string   | 是   | 用户名                           |
+| `server.password`       | string   | 否   | SSH 密码                         |
+| `server.privateKey`     | string   | 否   | SSH 私钥内容，优先级最高         |
+| `server.privateKeyPath` | string   | 否   | SSH 私钥文件路径                 |
+| `server.deployPath`     | string   | 是   | 服务器部署路径                   |
+| `pm2.appName`           | string   | 否   | PM2 应用名称                     |
+| `pm2.restart`           | boolean  | 否   | 是否重启 PM2 应用                |
+| `excludeFiles`          | string[] | 否   | 排除的文件模式（相对于构建目录） |
+| `beforeDeploy`          | string[] | 否   | 部署前执行的命令                 |
+| `afterDeploy`           | string[] | 否   | 部署后执行的命令                 |
 
 ## 命令详解
 
@@ -200,63 +274,6 @@ Options:
 pcli-cd init
 ```
 
-## 使用场景
-
-### 1. Nuxt 3 项目部署
-
-```javascript
-// Nuxt.js 项目配置
-export default {
-  buildCommand: 'npm run build',
-  buildDir: '.output',
-  server: {
-    host: 'your-server.com',
-    username: 'root',
-    password: 'your-password',
-    deployPath: '/var/www/nuxt-app',
-  },
-  pm2: {
-    appName: 'nuxt-app',
-    restart: true,
-  },
-  excludeFiles: [
-    // 注意：以下路径相对于 .output 目录
-    // 请根据实际构建产物内容调整
-    'src/**', // 如果源码被复制到输出目录
-    '**/.DS_Store', // macOS 系统文件
-  ],
-}
-```
-
-### 2. Node.js API 项目部署
-
-```javascript
-// Node.js API 项目配置
-export default {
-  buildCommand: 'npm run build',
-  buildDir: 'dist',
-  server: {
-    host: 'your-server.com',
-    username: 'root',
-    privateKey: '~/.ssh/id_rsa',
-    deployPath: '/var/www/api'
-  },
-  pm2: {
-    appName: 'api-server',
-    restart: true
-  },
-  excludeFiles: [
-    // 注意：以下路径相对于 dist 目录
-    // 请根据实际构建产物内容调整
-    'src/**',         // 如果源码被复制到输出目录
-    '**/.DS_Store', // macOS 系统文件
-  ]
-  afterDeploy: [
-    'npm install --production'
-  ]
-}
-```
-
 ## excludeFiles 配置说明
 
 ⚠️ **重要提醒**：`excludeFiles` 作用于**构建产物目录**（如 `dist/`、`.output/` 等），不是项目根目录。
@@ -333,12 +350,16 @@ pcli-cd rollback
 
 - **全局安装后首次使用**：安装后可在任意目录使用 `pcli-cd` 命令
 - **配置文件位置**：每个项目根目录需要有 `pcli-cd.config.js` 配置文件
-- 确保服务器已安装 `unzip` 命令
-- 如果使用 PM2，确保服务器已安装 PM2
-- 私钥文件需要有正确的权限 (600)
-- 建议在生产环境使用私钥认证而非密码
-- PM2 配置文件中的启动路径应该指向软链接而非具体版本目录
-- 部署过程中会自动清理旧版本，默认保留最近3个版本
+- **SSH 认证**：
+  - 支持 OpenSSH 格式的 RSA、ECDSA、Ed25519 私钥
+  - 私钥文件需要有正确的权限 (600)
+  - 生产环境建议使用私钥认证而非密码
+  - CI/CD 环境推荐使用 `privateKey` + 环境变量
+- **服务器要求**：
+  - 确保服务器已安装 `unzip` 命令
+  - 如果使用 PM2，确保服务器已安装 PM2
+- **PM2 配置**：PM2 配置文件中的启动路径应该指向软链接而非具体版本目录
+- **版本管理**：部署过程中会自动清理旧版本，默认保留最近3个版本
 
 ## 故障排除
 
@@ -362,6 +383,44 @@ ls pcli-cd.config.js
 pcli-cd init
 ```
 
+### SSH 连接失败
+
+**1. 私钥文件不存在**
+
+```bash
+# 检查私钥文件是否存在
+ls -la /home/user/.ssh/id_rsa
+
+# 检查私钥文件权限
+chmod 600 /home/user/.ssh/id_rsa
+```
+
+**2. 私钥格式错误**
+
+```bash
+# 检查私钥格式（应该以此开头）
+head -1 /home/user/.ssh/id_rsa
+# RSA: -----BEGIN RSA PRIVATE KEY-----
+# OpenSSH: -----BEGIN OPENSSH PRIVATE KEY-----
+# ECDSA: -----BEGIN EC PRIVATE KEY-----
+```
+
+**3. SSH 认证配置问题**
+
+- 确保至少配置了 `password`、`privateKey` 或 `privateKeyPath` 之一
+- 检查私钥文件路径是否正确
+- 验证服务器用户名和地址是否正确
+
+**4. 网络连接问题**
+
+```bash
+# 测试 SSH 连接
+ssh -p 22 root@your-server.com
+
+# 测试指定私钥连接
+ssh -i /home/user/.ssh/id_rsa -p 22 root@your-server.com
+```
+
 ## License
 
 MIT

package/dist/src/index.js

@@ -71,15 +71,12 @@ async function deploy(config) {
         await createZip(buildPath, zipPath, config.excludeFiles);
         spinner.succeed('文件压缩完成');
         spinner.start('正在连接服务器...');
-        const ssh = new NodeSSH();
-        await ssh.connect({
-            host: config.server.host,
-            port: config.server.port || 22,
-            username: config.server.username,
-            password: config.server.password,
-            privateKey: config.server.privateKey,
-        });
+        const ssh = await createSSHConnection(config.server);
         spinner.succeed('服务器连接成功');
+        await cleanTempLinks(ssh, config.server.deployPath, buildDirName);
+        spinner.start('检查部署环境...');
+        await handleExistingDeployDir(ssh, config.server.deployPath, buildDirName);
+        spinner.succeed('部署环境检查完成');
         const versionDirName = `${buildDirName}-${version}`;
         const versionPath = join(config.server.deployPath, versionDirName);
         const currentLinkPath = join(config.server.deployPath, buildDirName);
@@ -111,9 +108,22 @@ async function deploy(config) {
         }
         spinner.start(`正在切换到新版本 ${version}...`);
         const tempLinkPath = `${currentLinkPath}.tmp.${Date.now()}`;
-        await ssh.execCommand(`ln -sfn ${versionPath} ${tempLinkPath}`);
-        await ssh.execCommand(`mv ${tempLinkPath} ${currentLinkPath}`);
-        spinner.succeed(`版本切换完成: ${buildDirName} -> ${versionDirName}`);
+        try {
+            const linkResult = await ssh.execCommand(`ln -sfn ${versionPath} ${tempLinkPath}`);
+            if (linkResult.code !== 0) {
+                throw new Error(`创建临时软链接失败: ${linkResult.stderr}`);
+            }
+            const moveResult = await ssh.execCommand(`mv ${tempLinkPath} ${currentLinkPath}`);
+            if (moveResult.code !== 0) {
+                await ssh.execCommand(`rm -f ${tempLinkPath}`);
+                throw new Error(`切换软链接失败: ${moveResult.stderr}`);
+            }
+            spinner.succeed(`版本切换完成: ${buildDirName} -> ${versionDirName}`);
+        }
+        catch (error) {
+            await ssh.execCommand(`rm -f ${tempLinkPath}`);
+            throw error;
+        }
         if (config.pm2) {
             spinner.start('正在重启 PM2 应用...');
             const { appName, restart = true } = config.pm2;
@@ -225,10 +235,9 @@ async function initConfig() {
             validate: (input) => input.trim() !== '' || '请输入用户名',
         },
         {
-            type: 'password',
-            name: 'password',
-            message: '密码 (留空使用私钥):',
-            mask: '*',
+            type: 'input',
+            name: 'privateKeyPath',
+            message: '私钥路径 (留空稍后填写):',
         },
         {
             type: 'input',
@@ -249,7 +258,7 @@ async function initConfig() {
             host: answers.host,
             port: parseInt(answers.port),
             username: answers.username,
-            password: answers.password || undefined,
+            privateKeyPath: answers.privateKeyPath || undefined,
             deployPath: answers.deployPath,
         },
         excludeFiles: [],
@@ -283,14 +292,7 @@ async function listVersions(options) {
     const spinner = ora('正在获取版本列表...');
     spinner.start();
     try {
-        const ssh = new NodeSSH();
-        await ssh.connect({
-            host: config.server.host,
-            port: config.server.port || 22,
-            username: config.server.username,
-            password: config.server.password,
-            privateKey: config.server.privateKey,
-        });
+        const ssh = await createSSHConnection(config.server);
         const buildDirName = config.buildDir.split('/').pop() || 'build';
         const currentLinkPath = join(config.server.deployPath, buildDirName);
         const currentResult = await ssh.execCommand(`readlink ${currentLinkPath}`);
@@ -356,14 +358,7 @@ async function rollbackVersion(options) {
     const buildDirName = config.buildDir.split('/').pop() || 'build';
     let targetVersion = options.version;
     if (!targetVersion) {
-        const ssh = new NodeSSH();
-        await ssh.connect({
-            host: config.server.host,
-            port: config.server.port || 22,
-            username: config.server.username,
-            password: config.server.password,
-            privateKey: config.server.privateKey,
-        });
+        const ssh = await createSSHConnection(config.server);
         const result = await ssh.execCommand(`find ${config.server.deployPath} -maxdepth 1 -type d -name "${buildDirName}-*" | sort -V`);
         if (result.code !== 0) {
             console.log(chalk.red('❌ 无法获取版本列表'));
@@ -400,14 +395,7 @@ async function performRollback(config, targetVersion, buildDirName) {
     const spinner = ora();
     try {
         spinner.start('正在连接服务器...');
-        const ssh = new NodeSSH();
-        await ssh.connect({
-            host: config.server.host,
-            port: config.server.port || 22,
-            username: config.server.username,
-            password: config.server.password,
-            privateKey: config.server.privateKey,
-        });
+        const ssh = await createSSHConnection(config.server);
         spinner.succeed('服务器连接成功');
         const versionDirName = `${buildDirName}-${targetVersion}`;
         const versionPath = join(config.server.deployPath, versionDirName);
@@ -420,9 +408,22 @@ async function performRollback(config, targetVersion, buildDirName) {
         spinner.succeed('目标版本检查通过');
         spinner.start(`正在回滚到版本 ${targetVersion}...`);
         const tempLinkPath = `${currentLinkPath}.tmp.${Date.now()}`;
-        await ssh.execCommand(`ln -sfn ${versionPath} ${tempLinkPath}`);
-        await ssh.execCommand(`mv ${tempLinkPath} ${currentLinkPath}`);
-        spinner.succeed(`回滚完成: ${buildDirName} -> ${versionDirName}`);
+        try {
+            const linkResult = await ssh.execCommand(`ln -sfn ${versionPath} ${tempLinkPath}`);
+            if (linkResult.code !== 0) {
+                throw new Error(`创建临时软链接失败: ${linkResult.stderr}`);
+            }
+            const moveResult = await ssh.execCommand(`mv ${tempLinkPath} ${currentLinkPath}`);
+            if (moveResult.code !== 0) {
+                await ssh.execCommand(`rm -f ${tempLinkPath}`);
+                throw new Error(`切换软链接失败: ${moveResult.stderr}`);
+            }
+            spinner.succeed(`回滚完成: ${buildDirName} -> ${versionDirName}`);
+        }
+        catch (error) {
+            await ssh.execCommand(`rm -f ${tempLinkPath}`);
+            throw error;
+        }
         if (config.pm2) {
             spinner.start('正在重启 PM2 应用...');
             const { appName } = config.pm2;
@@ -450,5 +451,82 @@ async function performRollback(config, targetVersion, buildDirName) {
         process.exit(1);
     }
 }
+async function createSSHConnection(server) {
+    const ssh = new NodeSSH();
+    const connectConfig = {
+        host: server.host,
+        port: server.port || 22,
+        username: server.username,
+    };
+    if (server.privateKey) {
+        connectConfig.privateKey = server.privateKey;
+    }
+    else if (server.privateKeyPath) {
+        connectConfig.privateKeyPath = server.privateKeyPath;
+    }
+    else if (server.password) {
+        connectConfig.password = server.password;
+    }
+    else {
+        throw new Error('SSH 认证配置错误：必须提供 password、privateKey 或 privateKeyPath 之一');
+    }
+    try {
+        await ssh.connect(connectConfig);
+        return ssh;
+    }
+    catch (error) {
+        throw new Error(`SSH 连接失败: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+async function cleanTempLinks(ssh, deployPath, buildDirName) {
+    try {
+        await ssh.execCommand(`find ${deployPath} -name "${buildDirName}.tmp.*" -type l -delete`);
+    }
+    catch (error) {
+        console.warn(chalk.yellow(`⚠️ 清理临时链接时出现警告: ${error}`));
+    }
+}
+async function handleExistingDeployDir(ssh, deployPath, buildDirName) {
+    const currentLinkPath = join(deployPath, buildDirName);
+    const checkResult = await ssh.execCommand(`test -e ${currentLinkPath}`);
+    if (checkResult.code !== 0) {
+        return;
+    }
+    const linkCheckResult = await ssh.execCommand(`test -L ${currentLinkPath}`);
+    if (linkCheckResult.code === 0) {
+        return;
+    }
+    const typeResult = await ssh.execCommand(`stat -c %F ${currentLinkPath} 2>/dev/null || file -b ${currentLinkPath}`);
+    const fileType = typeResult.stdout.trim();
+    if (fileType.includes('directory') || fileType === 'directory') {
+        const backupPath = `${currentLinkPath}.backup.${Date.now()}`;
+        console.log(chalk.yellow(`⚠️ 检测到已存在的目录: ${currentLinkPath}`));
+        console.log(chalk.blue(`📁 将备份到: ${backupPath}`));
+        const answers = await inquirer.prompt([
+            {
+                type: 'confirm',
+                name: 'proceed',
+                message: '是否继续部署？（已存在的目录将被备份）',
+                default: true,
+            },
+        ]);
+        if (!answers.proceed) {
+            throw new Error('用户取消部署');
+        }
+        const backupResult = await ssh.execCommand(`mv ${currentLinkPath} ${backupPath}`);
+        if (backupResult.code !== 0) {
+            throw new Error(`备份目录失败: ${backupResult.stderr}`);
+        }
+        console.log(chalk.green(`✅ 目录已备份到: ${backupPath}`));
+    }
+    else {
+        const backupPath = `${currentLinkPath}.backup.${Date.now()}`;
+        const backupResult = await ssh.execCommand(`mv ${currentLinkPath} ${backupPath}`);
+        if (backupResult.code !== 0) {
+            throw new Error(`备份文件失败: ${backupResult.stderr}`);
+        }
+        console.log(chalk.green(`✅ 文件已备份到: ${backupPath}`));
+    }
+}
 
 export { deployCommand, initConfig, listVersions, rollbackVersion };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noahyu/cd-cli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Global CLI tool for simple project deployment with version management",
   "type": "module",
   "main": "./dist/bin/cli.js",