@noahyu/cd-cli 1.0.0 → 1.0.1

package/README.md

@@ -1,4 +1,4 @@
-# CD CLI - 简易部署工具
+# 简易项目部署工具
 
 一个简易的部署工具，支持版本管理和零停机部署。
 
@@ -9,7 +9,7 @@
 - 🔄 零停机部署：使用软链接实现原子性切换
 - ⏪ 快速回滚：一键回滚到任意历史版本
 - 📝 版本列表：查看服务器上所有已部署版本
-- 🔒 安全连接：支持密码和私钥认证
+- 🔒 SSH 认证：支持密码、密钥
 - 🔄 PM2 集成：自动重启 PM2 应用
 - 📝 配置灵活：支持部署前后执行自定义命令
 - 🎯 文件过滤：支持排除不需要的文件
@@ -92,65 +92,143 @@ 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: '~/.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: '~/.ssh/id_rsa',
+    deployPath: '/var/www/app',
+  },
+}
+```
+
+- `~/.ssh/id_rsa` - 用户主目录下的私钥
+- `/home/user/.ssh/id_ed25519` - 绝对路径
+- `./keys/deploy_key` - 相对路径
+
+### 方式三：密码认证
+
+适用于简单测试环境（生产环境不推荐）：
+
+```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[] | 否   | 部署后执行的命令                   |
 
 ## 命令详解
 
@@ -212,7 +290,7 @@ export default {
   server: {
     host: 'your-server.com',
     username: 'root',
-    password: 'your-password',
+    privateKeyPath: '~/.ssh/id_rsa', // 推荐使用私钥认证
     deployPath: '/var/www/nuxt-app',
   },
   pm2: {
@@ -333,12 +411,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 +444,44 @@ ls pcli-cd.config.js
 pcli-cd init
 ```
 
+### SSH 连接失败
+
+**1. 私钥文件不存在**
+
+```bash
+# 检查私钥文件是否存在
+ls -la ~/.ssh/id_rsa
+
+# 检查私钥文件权限
+chmod 600 ~/.ssh/id_rsa
+```
+
+**2. 私钥格式错误**
+
+```bash
+# 检查私钥格式（应该以此开头）
+head -1 ~/.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 ~/.ssh/id_rsa -p 22 root@your-server.com
+```
+
 ## License
 
 MIT

package/dist/src/index.js

@@ -71,14 +71,7 @@ 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('服务器连接成功');
         const versionDirName = `${buildDirName}-${version}`;
         const versionPath = join(config.server.deployPath, versionDirName);
@@ -225,10 +218,9 @@ async function initConfig() {
             validate: (input) => input.trim() !== '' || '请输入用户名',
         },
         {
-            type: 'password',
-            name: 'password',
-            message: '密码 (留空使用私钥):',
-            mask: '*',
+            type: 'input',
+            name: 'privateKeyPath',
+            message: '私钥路径 (留空稍后填写):',
         },
         {
             type: 'input',
@@ -249,7 +241,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 +275,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 +341,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 +378,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);
@@ -450,5 +421,32 @@ 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)}`);
+    }
+}
 
 export { deployCommand, initConfig, listVersions, rollbackVersion };

package/package.json

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