certctl-cli 1.0.5 → 1.0.6

package/API.md

@@ -0,0 +1,600 @@
+# Certctl Programmatic API 使用指南
+
+如果你在 Node.js 项目中需要通过代码调用证书申请功能，有以下两种方式：
+
+---
+
+## 方式一：通过子进程调用 CLI（推荐，当前可用）
+
+这是目前最稳定的方式，直接调用 `certctl` 命令。
+
+### 安装
+
+```bash
+npm install certctl-cli
+```
+
+### 基础用法
+
+```javascript
+const { spawn } = require('child_process');
+const path = require('path');
+
+// 获取 certctl 二进制路径
+function getCertctlPath() {
+  return path.join(__dirname, 'node_modules', '.bin', 'certctl');
+}
+
+/**
+ * 申请证书
+ * @param {Object} options - 配置选项
+ * @param {string} options.domain - 域名 (必填)
+ * @param {string} options.email - 邮箱 (必填)
+ * @param {string} options.output - 输出目录 (可选，默认 ./certs)
+ * @param {string} options.dns - DNS 提供商 (可选: aliyun/tencentcloud)
+ * @param {Object} options.credentials - DNS 凭证 (可选)
+ */
+function applyCertificate(options) {
+  return new Promise((resolve, reject) => {
+    const args = [
+      'apply',
+      '-d', options.domain,
+      '-e', options.email,
+      '-o', options.output || './certs'
+    ];
+
+    // 自动 DNS 验证
+    if (options.dns) {
+      args.push('--dns', options.dns);
+      
+      if (options.dns === 'aliyun' && options.credentials) {
+        args.push(
+          '--ali-key', options.credentials.accessKeyId,
+          '--ali-secret', options.credentials.accessKeySecret
+        );
+      }
+      
+      if (options.dns === 'tencentcloud' && options.credentials) {
+        args.push(
+          '--tencent-id', options.credentials.secretId,
+          '--tencent-secret', options.credentials.secretKey
+        );
+      }
+    }
+
+    const certctl = spawn(getCertctlPath(), args, {
+      stdio: ['inherit', 'pipe', 'pipe']
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    certctl.stdout.on('data', (data) => {
+      stdout += data.toString();
+      console.log(data.toString()); // 实时输出日志
+    });
+
+    certctl.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+
+    certctl.on('close', (code) => {
+      if (code === 0) {
+        resolve({
+          success: true,
+          domain: options.domain,
+          output: options.output || './certs',
+          stdout
+        });
+      } else {
+        reject(new Error(`证书申请失败: ${stderr || stdout}`));
+      }
+    });
+  });
+}
+
+// 使用示例
+async function main() {
+  try {
+    // 示例 1: 阿里云自动验证
+    const result = await applyCertificate({
+      domain: 'example.com',
+      email: 'admin@example.com',
+      output: './my-certs',
+      dns: 'aliyun',
+      credentials: {
+        accessKeyId: process.env.ALICLOUD_ACCESS_KEY,
+        accessKeySecret: process.env.ALICLOUD_SECRET_KEY
+      }
+    });
+    
+    console.log('证书申请成功:', result);
+    
+    // 证书文件位置
+    const certPath = `./my-certs/${result.domain}/${result.domain}.pem`;
+    const keyPath = `./my-certs/${result.domain}/${result.domain}.key`;
+    
+    console.log('证书路径:', certPath);
+    console.log('私钥路径:', keyPath);
+    
+  } catch (error) {
+    console.error('申请失败:', error.message);
+  }
+}
+
+main();
+```
+
+### 续期证书
+
+```javascript
+const { spawn } = require('child_process');
+
+function renewCertificate(domain, outputDir = './certs') {
+  return new Promise((resolve, reject) => {
+    const certctl = spawn('certctl', [
+      'renew',
+      '-d', domain,
+      '-o', outputDir
+    ], {
+      stdio: 'pipe'
+    });
+
+    let output = '';
+    certctl.stdout.on('data', (data) => {
+      output += data.toString();
+    });
+
+    certctl.on('close', (code) => {
+      if (code === 0) {
+        resolve({ success: true, output });
+      } else {
+        reject(new Error(`续期失败: ${output}`));
+      }
+    });
+  });
+}
+
+// 使用
+renewCertificate('example.com', './my-certs')
+  .then(() => console.log('续期成功'))
+  .catch(err => console.error(err));
+```
+
+### 验证证书
+
+```javascript
+const { spawn } = require('child_process');
+
+function verifyCertificate(domain, certPath) {
+  return new Promise((resolve, reject) => {
+    const args = ['verify', '-d', domain];
+    if (certPath) {
+      args.push('-p', certPath);
+    }
+
+    const certctl = spawn('certctl', args, {
+      stdio: 'pipe'
+    });
+
+    let output = '';
+    certctl.stdout.on('data', (data) => {
+      output += data.toString();
+    });
+
+    certctl.on('close', (code) => {
+      resolve({
+        valid: code === 0,
+        output
+      });
+    });
+  });
+}
+
+// 使用
+verifyCertificate('example.com')
+  .then(result => {
+    console.log('验证结果:', result.valid ? '通过' : '失败');
+    console.log(result.output);
+  });
+```
+
+### 修复证书链
+
+```javascript
+const { spawn } = require('child_process');
+
+function fixCertificateChain(domain, certPath) {
+  return new Promise((resolve, reject) => {
+    const args = ['fix-chain'];
+    
+    if (certPath) {
+      args.push('-p', certPath);
+    } else if (domain) {
+      args.push('-d', domain);
+    }
+
+    const certctl = spawn('certctl', args, {
+      stdio: 'pipe'
+    });
+
+    let output = '';
+    certctl.stdout.on('data', (data) => {
+      output += data.toString();
+    });
+
+    certctl.on('close', (code) => {
+      if (code === 0) {
+        resolve({ success: true, output });
+      } else {
+        reject(new Error(`修复失败: ${output}`));
+      }
+    });
+  });
+}
+```
+
+---
+
+## 方式二：完整的 Node.js SDK（需要额外开发）
+
+如果你需要更优雅的 API，可以开发一个包装器。以下是一个设计提案：
+
+### 安装方式
+
+```bash
+npm install certctl-sdk
+```
+
+### 期望的 API 设计
+
+```javascript
+const { CertctlClient } = require('certctl-sdk');
+
+// 创建客户端
+const client = new CertctlClient({
+  email: 'admin@example.com',
+  outputDir: './certs',
+  staging: false // 是否为测试环境
+});
+
+// 申请证书
+const cert = await client.apply({
+  domain: 'example.com',
+  dns: {
+    provider: 'aliyun',
+    accessKeyId: 'your-key',
+    accessKeySecret: 'your-secret'
+  }
+});
+
+console.log(cert.paths);
+// {
+//   cert: './certs/example.com/example.com.pem',
+//   key: './certs/example.com/example.com.key'
+// }
+
+// 续期
+await client.renew('example.com');
+
+// 验证
+const isValid = await client.verify('example.com');
+
+// 修复证书链
+await client.fixChain('example.com');
+```
+
+### 是否需要开发 SDK？
+
+| 场景 | 建议 |
+|------|------|
+| 只是简单调用 | 使用方式一（子进程）即可 |
+| 需要深度集成 | 可以开发 `certctl-sdk` |
+| 需要事件通知 | 子进程方式可以实时获取输出 |
+| 需要类型支持 | 可以添加 TypeScript 定义 |
+
+---
+
+## TypeScript 类型定义
+
+如果你使用 TypeScript，以下是类型定义：
+
+```typescript
+// certctl.d.ts
+
+export interface ApplyOptions {
+  domain: string;
+  email: string;
+  output?: string;
+  dns?: 'aliyun' | 'tencentcloud';
+  credentials?: {
+    accessKeyId?: string;
+    accessKeySecret?: string;
+    secretId?: string;
+    secretKey?: string;
+  };
+  staging?: boolean;
+}
+
+export interface ApplyResult {
+  success: boolean;
+  domain: string;
+  output: string;
+  stdout: string;
+}
+
+export interface VerifyResult {
+  valid: boolean;
+  output: string;
+}
+
+export declare function applyCertificate(options: ApplyOptions): Promise<ApplyResult>;
+export declare function renewCertificate(domain: string, outputDir?: string): Promise<{ success: boolean; output: string }>;
+export declare function verifyCertificate(domain: string, certPath?: string): Promise<VerifyResult>;
+export declare function fixCertificateChain(domain?: string, certPath?: string): Promise<{ success: boolean; output: string }>;
+```
+
+---
+
+## 完整项目示例
+
+```
+my-project/
+├── src/
+│   ├── certctl-wrapper.js    # 封装 certctl 调用
+│   ├── server.js             # 你的应用
+│   └── config.js
+├── certs/                    # 证书输出目录
+├── package.json
+└── .env
+```
+
+### certctl-wrapper.js
+
+```javascript
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+class CertctlWrapper {
+  constructor(options = {}) {
+    this.email = options.email;
+    this.outputDir = options.outputDir || './certs';
+    this.binaryPath = options.binaryPath || 'certctl';
+  }
+
+  _spawn(args) {
+    return new Promise((resolve, reject) => {
+      const proc = spawn(this.binaryPath, args, {
+        stdio: ['pipe', 'pipe', 'pipe']
+      });
+
+      let stdout = '';
+      let stderr = '';
+
+      proc.stdout.on('data', (data) => {
+        stdout += data.toString();
+      });
+
+      proc.stderr.on('data', (data) => {
+        stderr += data.toString();
+      });
+
+      proc.on('close', (code) => {
+        if (code === 0) {
+          resolve({ stdout, stderr, code });
+        } else {
+          reject(new Error(`Process exited with code ${code}: ${stderr || stdout}`));
+        }
+      });
+    });
+  }
+
+  async apply(domain, dnsOptions = null) {
+    const args = [
+      'apply',
+      '-d', domain,
+      '-e', this.email,
+      '-o', this.outputDir
+    ];
+
+    if (dnsOptions) {
+      args.push('--dns', dnsOptions.provider);
+      
+      if (dnsOptions.provider === 'aliyun') {
+        args.push(
+          '--ali-key', dnsOptions.accessKeyId,
+          '--ali-secret', dnsOptions.accessKeySecret
+        );
+      } else if (dnsOptions.provider === 'tencentcloud') {
+        args.push(
+          '--tencent-id', dnsOptions.secretId,
+          '--tencent-secret', dnsOptions.secretKey
+        );
+      }
+    }
+
+    const result = await this._spawn(args);
+    
+    return {
+      success: true,
+      domain,
+      paths: {
+        cert: path.join(this.outputDir, domain, `${domain}.pem`),
+        key: path.join(this.outputDir, domain, `${domain}.key`)
+      },
+      output: result.stdout
+    };
+  }
+
+  async renew(domain) {
+    const args = ['renew', '-d', domain, '-o', this.outputDir];
+    const result = await this._spawn(args);
+    return { success: true, output: result.stdout };
+  }
+
+  async verify(domain) {
+    const args = ['verify', '-d', domain];
+    try {
+      const result = await this._spawn(args);
+      return { valid: true, output: result.stdout };
+    } catch (err) {
+      return { valid: false, output: err.message };
+    }
+  }
+
+  async fixChain(domain) {
+    const args = ['fix-chain', '-d', domain];
+    const result = await this._spawn(args);
+    return { success: true, output: result.stdout };
+  }
+
+  getCertificatePaths(domain) {
+    return {
+      cert: path.join(this.outputDir, domain, `${domain}.pem`),
+      key: path.join(this.outputDir, domain, `${domain}.key`)
+    };
+  }
+
+  exists(domain) {
+    const paths = this.getCertificatePaths(domain);
+    return fs.existsSync(paths.cert) && fs.existsSync(paths.key);
+  }
+}
+
+module.exports = { CertctlWrapper };
+```
+
+### server.js
+
+```javascript
+const { CertctlWrapper } = require('./certctl-wrapper');
+const express = require('express');
+
+const app = express();
+const certClient = new CertctlWrapper({
+  email: process.env.ACME_EMAIL,
+  outputDir: './certs'
+});
+
+// API: 申请证书
+app.post('/api/certs/:domain', async (req, res) => {
+  try {
+    const { domain } = req.params;
+    
+    // 检查是否已存在
+    if (certClient.exists(domain)) {
+      return res.json({ 
+        success: true, 
+        message: '证书已存在',
+        paths: certClient.getCertificatePaths(domain)
+      });
+    }
+
+    // 申请证书
+    const result = await certClient.apply(domain, {
+      provider: 'aliyun',
+      accessKeyId: process.env.ALI_KEY,
+      accessKeySecret: process.env.ALI_SECRET
+    });
+
+    res.json(result);
+  } catch (error) {
+    res.status(500).json({ success: false, error: error.message });
+  }
+});
+
+// API: 获取证书信息
+app.get('/api/certs/:domain', async (req, res) => {
+  try {
+    const { domain } = req.params;
+    const verifyResult = await certClient.verify(domain);
+    
+    res.json({
+      domain,
+      exists: certClient.exists(domain),
+      valid: verifyResult.valid,
+      paths: certClient.getCertificatePaths(domain)
+    });
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+
+app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000');
+});
+```
+
+---
+
+## 常见问题
+
+### Q: 如何在 Docker 中使用？
+
+```dockerfile
+FROM node:18-alpine
+
+# 安装 certctl
+RUN npm install -g certctl-cli
+
+WORKDIR /app
+COPY package*.json ./
+RUN npm install
+
+COPY . .
+
+CMD ["node", "server.js"]
+```
+
+### Q: 如何监控证书到期？
+
+```javascript
+const fs = require('fs');
+const { spawn } = require('child_process');
+
+// 定期检查证书有效期
+function checkCertExpiry(domain, certPath) {
+  return new Promise((resolve) => {
+    const certctl = spawn('certctl', ['verify', '-d', domain, '-p', certPath]);
+    let output = '';
+    
+    certctl.stdout.on('data', (data) => {
+      output += data.toString();
+    });
+    
+    certctl.on('close', () => {
+      // 解析输出获取剩余天数
+      const match = output.match(/剩余 (\d+) 天/);
+      if (match) {
+        const days = parseInt(match[1]);
+        resolve({ days, needsRenew: days <= 30 });
+      } else {
+        resolve({ days: 0, needsRenew: true });
+      }
+    });
+  });
+}
+
+// 定时任务
+setInterval(async () => {
+  const domains = ['example.com', 'api.example.com'];
+  
+  for (const domain of domains) {
+    const status = await checkCertExpiry(domain, `./certs/${domain}/${domain}.pem`);
+    
+    if (status.needsRenew) {
+      console.log(`证书 ${domain} 即将过期 (${status.days} 天)，开始续期...`);
+      await renewCertificate(domain);
+    }
+  }
+}, 24 * 60 * 60 * 1000); // 每天检查一次
+```
+
+---
+
+## 下一步
+
+1. **当前可用**：使用方式一（子进程调用）
+2. **未来规划**：如果需要真正的 Node.js SDK，可以开发 `certctl-sdk` 包
+3. **需求反馈**：如果有特定需求，请提交 Issue

package/README.md

@@ -1,8 +1,8 @@
 # certctl-cli
 
-轻量级 SSL 证书申请工具 / Lightweight SSL Certificate CLI Tool
+轻量级 SSL 证书申请工具 / Lightweight SSL Certificate Tool
 
-支持通配符证书申请 & 阿里云 DNS 自动验证。
+支持通配符证书申请 & 阿里云/腾讯云 DNS 自动验证。
 
 ## 安装
 
@@ -10,7 +10,7 @@
 npm install -g certctl-cli
 ```
 
-## 使用
+## CLI 使用
 
 ```bash
 # 交互式菜单
@@ -22,16 +22,71 @@ certctl apply -d example.com -e admin@example.com
 # 阿里云 DNS 自动验证
 certctl apply -d example.com --dns aliyun --ali-key YOUR_KEY --ali-secret YOUR_SECRET
 
+# 腾讯云 DNS 自动验证  
+certctl apply -d example.com --dns tencentcloud --tencent-id YOUR_ID --tencent-secret YOUR_KEY
+
 # 查看证书
 certctl list
 
 # 续期证书
 certctl renew
+
+# 验证证书
+certctl verify -d example.com
+
+# 修复证书链（自动补全中间证书）
+certctl fix-chain -d example.com
+```
+
+## Programmatic API（在代码中调用）
+
+如果你需要在 Node.js 项目中通过代码调用证书申请功能，请参考：
+
+📚 **[完整 API 文档](./API.md)**
+
+快速示例：
+
+```javascript
+const { spawn } = require('child_process');
+
+// 申请证书
+const certctl = spawn('certctl', [
+  'apply',
+  '-d', 'example.com',
+  '-e', 'admin@example.com',
+  '--dns', 'aliyun',
+  '--ali-key', process.env.ALI_KEY,
+  '--ali-secret', process.env.ALI_SECRET
+]);
+
+certctl.on('close', (code) => {
+  if (code === 0) {
+    console.log('证书申请成功！');
+    console.log('证书位置: ./certs/example.com/example.com.pem');
+  }
+});
 ```
 
+完整封装示例见 [API.md](./API.md)。
+
+## 特性
+
+- 🔐 **通配符证书**：支持 `*.example.com`
+- 🤖 **自动 DNS 验证**：阿里云/腾讯云 DNS 自动验证
+- 🛠️ **证书链修复**：自动补全缺失的中间证书
+- 📱 **微信小程序兼容**：确保证书链完整
+- 🌍 **多语言**：中英文界面
+- 🚀 **轻量快速**：Go 实现，单二进制文件
+
+## 环境要求
+
+- Node.js >= 14
+- 支持 macOS、Linux、Windows
+
 ## 文档
 
-完整文档: https://github.com/Heartbeatc/certctl
+- CLI 文档：https://github.com/Heartbeatc/certctl#readme
+- API 文档：[API.md](./API.md)
 
 ## License
 

package/examples/README.md

@@ -0,0 +1,84 @@
+# Certctl Node.js 示例
+
+这里提供了在 Node.js 项目中使用 certctl 的各种示例。
+
+## 示例列表
+
+### 1. basic-usage.js - 基础使用示例
+
+展示如何在 Node.js 代码中调用 certctl 命令。
+
+**功能：**
+- 申请证书（支持阿里云自动验证）
+- 验证证书
+- 修复证书链
+- 续期证书
+
+**运行：**
+```bash
+# 使用手动验证
+node basic-usage.js example.com
+
+# 使用阿里云自动验证（需设置环境变量）
+export ALI_KEY=your-access-key
+export ALI_SECRET=your-access-secret
+export ACME_EMAIL=admin@example.com
+node basic-usage.js example.com
+```
+
+### 2. express-server.js - Express HTTP API
+
+提供一个完整的 HTTP API 服务，通过 REST API 管理证书。
+
+**功能：**
+- 列出所有证书
+- 申请新证书
+- 续期证书
+- 验证证书
+- 修复证书链
+- 下载证书文件
+
+**安装：**
+```bash
+npm install express certctl-cli
+```
+
+**运行：**
+```bash
+node express-server.js
+```
+
+**API 调用示例：**
+
+```bash
+# 列出所有证书
+curl http://localhost:3000/api/certs
+
+# 申请证书（阿里云自动验证）
+curl -X POST http://localhost:3000/api/certs/example.com \
+  -H "Content-Type: application/json" \
+  -d '{
+    "dns": {
+      "provider": "aliyun",
+      "accessKeyId": "your-key",
+      "accessKeySecret": "your-secret"
+    }
+  }'
+
+# 验证证书
+curl -X POST http://localhost:3000/api/certs/example.com/verify
+
+# 续期证书
+curl -X POST http://localhost:3000/api/certs/example.com/renew
+
+# 修复证书链
+curl -X POST http://localhost:3000/api/certs/example.com/fix-chain
+
+# 下载证书
+curl http://localhost:3000/api/certs/example.com/download?type=cert -o cert.pem
+curl http://localhost:3000/api/certs/example.com/download?type=key -o key.pem
+```
+
+## 完整 API 文档
+
+更多详细信息请参考：[API.md](../API.md)

package/examples/basic-usage.js

@@ -0,0 +1,231 @@
+/**
+ * Certctl Node.js 基础使用示例
+ * 
+ * 运行前请确保：
+ * 1. npm install certctl-cli
+ * 2. 设置环境变量：ALI_KEY 和 ALI_SECRET（如果使用阿里云）
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+// ==================== 配置 ====================
+const CONFIG = {
+  email: process.env.ACME_EMAIL || 'admin@example.com',
+  outputDir: './my-certificates',
+  // 阿里云配置
+  aliyun: {
+    accessKeyId: process.env.ALI_KEY,
+    accessKeySecret: process.env.ALI_SECRET
+  }
+};
+
+// ==================== 工具函数 ====================
+
+/**
+ * 执行 certctl 命令
+ */
+function runCertctl(args) {
+  return new Promise((resolve, reject) => {
+    console.log(`执行: certctl ${args.join(' ')}`);
+    
+    const certctl = spawn('certctl', args, {
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    certctl.stdout.on('data', (data) => {
+      stdout += data.toString();
+      console.log(data.toString());
+    });
+
+    certctl.stderr.on('data', (data) => {
+      stderr += data.toString();
+      console.error(data.toString());
+    });
+
+    certctl.on('close', (code) => {
+      if (code === 0) {
+        resolve({ stdout, stderr, code });
+      } else {
+        reject(new Error(`命令失败 (code ${code}): ${stderr || stdout}`));
+      }
+    });
+  });
+}
+
+/**
+ * 申请证书
+ */
+async function applyCertificate(domain) {
+  console.log(`\n📝 正在为 ${domain} 申请证书...\n`);
+  
+  const args = [
+    'apply',
+    '-d', domain,
+    '-e', CONFIG.email,
+    '-o', CONFIG.outputDir
+  ];
+
+  // 如果配置了阿里云，使用自动验证
+  if (CONFIG.aliyun.accessKeyId && CONFIG.aliyun.accessKeySecret) {
+    args.push(
+      '--dns', 'aliyun',
+      '--ali-key', CONFIG.aliyun.accessKeyId,
+      '--ali-secret', CONFIG.aliyun.accessKeySecret
+    );
+    console.log('使用阿里云 DNS 自动验证');
+  } else {
+    console.log('使用手动 DNS 验证，请按提示添加 TXT 记录');
+  }
+
+  try {
+    await runCertctl(args);
+    
+    const certPath = path.join(CONFIG.outputDir, domain, `${domain}.pem`);
+    const keyPath = path.join(CONFIG.outputDir, domain, `${domain}.key`);
+    
+    console.log('\n✅ 证书申请成功！');
+    console.log(`📄 证书路径: ${certPath}`);
+    console.log(`🔑 私钥路径: ${keyPath}`);
+    
+    return { success: true, certPath, keyPath };
+  } catch (error) {
+    console.error('\n❌ 证书申请失败:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * 验证证书
+ */
+async function verifyCertificate(domain) {
+  console.log(`\n🔍 正在验证 ${domain} 的证书...\n`);
+  
+  try {
+    const result = await runCertctl(['verify', '-d', domain, '-o', CONFIG.outputDir]);
+    console.log('\n✅ 证书验证通过');
+    return { valid: true, output: result.stdout };
+  } catch (error) {
+    console.log('\n⚠️ 证书验证未通过');
+    return { valid: false, error: error.message };
+  }
+}
+
+/**
+ * 修复证书链
+ */
+async function fixCertificateChain(domain) {
+  console.log(`\n🔧 正在修复 ${domain} 的证书链...\n`);
+  
+  try {
+    await runCertctl(['fix-chain', '-d', domain, '-o', CONFIG.outputDir]);
+    console.log('\n✅ 证书链修复完成');
+    return { success: true };
+  } catch (error) {
+    console.error('\n❌ 证书链修复失败:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * 续期证书
+ */
+async function renewCertificate(domain) {
+  console.log(`\n🔄 正在续期 ${domain} 的证书...\n`);
+  
+  try {
+    await runCertctl(['renew', '-d', domain, '-o', CONFIG.outputDir]);
+    console.log('\n✅ 证书续期成功');
+    return { success: true };
+  } catch (error) {
+    console.error('\n❌ 证书续期失败:', error.message);
+    throw error;
+  }
+}
+
+/**
+ * 检查证书是否存在
+ */
+function certificateExists(domain) {
+  const certPath = path.join(CONFIG.outputDir, domain, `${domain}.pem`);
+  const keyPath = path.join(CONFIG.outputDir, domain, `${domain}.key`);
+  return fs.existsSync(certPath) && fs.existsSync(keyPath);
+}
+
+/**
+ * 获取证书路径
+ */
+function getCertificatePaths(domain) {
+  return {
+    cert: path.join(CONFIG.outputDir, domain, `${domain}.pem`),
+    key: path.join(CONFIG.outputDir, domain, `${domain}.key`)
+  };
+}
+
+// ==================== 主程序 ====================
+
+async function main() {
+  const domain = process.argv[2] || 'example.com';
+  
+  console.log('========================================');
+  console.log('Certctl Node.js 示例');
+  console.log('========================================');
+  console.log(`域名: ${domain}`);
+  console.log(`邮箱: ${CONFIG.email}`);
+  console.log(`输出目录: ${CONFIG.outputDir}`);
+  console.log('========================================\n');
+
+  try {
+    // 步骤 1: 检查证书是否已存在
+    if (certificateExists(domain)) {
+      console.log(`证书已存在，跳过申请步骤`);
+      
+      // 步骤 2: 验证现有证书
+      const verifyResult = await verifyCertificate(domain);
+      
+      if (!verifyResult.valid) {
+        console.log('证书验证失败，尝试修复...');
+        await fixCertificateChain(domain);
+        
+        // 重新验证
+        const recheck = await verifyCertificate(domain);
+        if (!recheck.valid) {
+          console.error('修复后仍无法通过验证');
+          process.exit(1);
+        }
+      }
+    } else {
+      // 步骤 1: 申请证书
+      await applyCertificate(domain);
+      
+      // 步骤 2: 验证证书
+      await verifyCertificate(domain);
+    }
+
+    // 输出证书信息
+    const paths = getCertificatePaths(domain);
+    console.log('\n📋 证书信息:');
+    console.log(`   域名: ${domain}`);
+    console.log(`   证书: ${paths.cert}`);
+    console.log(`   私钥: ${paths.key}`);
+    
+    // 读取证书内容（可选）
+    if (fs.existsSync(paths.cert)) {
+      const stats = fs.statSync(paths.cert);
+      console.log(`   大小: ${(stats.size / 1024).toFixed(2)} KB`);
+    }
+
+    console.log('\n✨ 完成！');
+    
+  } catch (error) {
+    console.error('\n💥 发生错误:', error.message);
+    process.exit(1);
+  }
+}
+
+// 运行
+main();

package/examples/express-server.js

@@ -0,0 +1,398 @@
+/**
+ * Certctl + Express 集成示例
+ * 
+ * 提供 HTTP API 来管理证书
+ * 
+ * 安装依赖:
+ * npm install express certctl-cli
+ * 
+ * 运行:
+ * node express-server.js
+ */
+
+const express = require('express');
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const app = express();
+app.use(express.json());
+
+// 配置
+const CONFIG = {
+  email: process.env.ACME_EMAIL || 'admin@example.com',
+  certsDir: process.env.CERTS_DIR || './certs',
+  port: process.env.PORT || 3000
+};
+
+// ==================== Certctl 封装类 ====================
+
+class CertctlService {
+  constructor(options) {
+    this.email = options.email;
+    this.certsDir = options.certsDir;
+  }
+
+  /**
+   * 执行 certctl 命令
+   */
+  exec(args) {
+    return new Promise((resolve, reject) => {
+      const proc = spawn('certctl', args, {
+        stdio: ['pipe', 'pipe', 'pipe']
+      });
+
+      let stdout = '';
+      let stderr = '';
+
+      proc.stdout.on('data', (data) => stdout += data);
+      proc.stderr.on('data', (data) => stderr += data);
+
+      proc.on('close', (code) => {
+        if (code === 0) {
+          resolve({ stdout, stderr, code });
+        } else {
+          reject(new Error(stderr || stdout));
+        }
+      });
+    });
+  }
+
+  /**
+   * 申请证书
+   */
+  async apply(domain, dnsOptions = null) {
+    const args = [
+      'apply',
+      '-d', domain,
+      '-e', this.email,
+      '-o', this.certsDir
+    ];
+
+    if (dnsOptions?.provider === 'aliyun') {
+      args.push(
+        '--dns', 'aliyun',
+        '--ali-key', dnsOptions.accessKeyId,
+        '--ali-secret', dnsOptions.accessKeySecret
+      );
+    } else if (dnsOptions?.provider === 'tencentcloud') {
+      args.push(
+        '--dns', 'tencentcloud',
+        '--tencent-id', dnsOptions.secretId,
+        '--tencent-secret', dnsOptions.secretKey
+      );
+    }
+
+    await this.exec(args);
+    return this.getCertificateInfo(domain);
+  }
+
+  /**
+   * 验证证书
+   */
+  async verify(domain) {
+    try {
+      await this.exec(['verify', '-d', domain, '-o', this.certsDir]);
+      return { valid: true };
+    } catch (error) {
+      return { valid: false, error: error.message };
+    }
+  }
+
+  /**
+   * 修复证书链
+   */
+  async fixChain(domain) {
+    await this.exec(['fix-chain', '-d', domain, '-o', this.certsDir]);
+    return { success: true };
+  }
+
+  /**
+   * 续期证书
+   */
+  async renew(domain) {
+    await this.exec(['renew', '-d', domain, '-o', this.certsDir]);
+    return this.getCertificateInfo(domain);
+  }
+
+  /**
+   * 获取证书信息
+   */
+  getCertificateInfo(domain) {
+    const certPath = path.join(this.certsDir, domain, `${domain}.pem`);
+    const keyPath = path.join(this.certsDir, domain, `${domain}.key`);
+    
+    const exists = fs.existsSync(certPath) && fs.existsSync(keyPath);
+    
+    let stats = null;
+    if (exists) {
+      stats = fs.statSync(certPath);
+    }
+
+    return {
+      domain,
+      exists,
+      paths: {
+        cert: certPath,
+        key: keyPath
+      },
+      createdAt: stats ? stats.birthtime : null
+    };
+  }
+
+  /**
+   * 列出所有证书
+   */
+  listCertificates() {
+    const certs = [];
+    
+    if (!fs.existsSync(this.certsDir)) {
+      return certs;
+    }
+
+    const domains = fs.readdirSync(this.certsDir);
+    
+    for (const domain of domains) {
+      const domainPath = path.join(this.certsDir, domain);
+      const stat = fs.statSync(domainPath);
+      
+      if (stat.isDirectory()) {
+        certs.push(this.getCertificateInfo(domain));
+      }
+    }
+    
+    return certs;
+  }
+}
+
+// ==================== 初始化服务 ====================
+
+const certService = new CertctlService({
+  email: CONFIG.email,
+  certsDir: CONFIG.certsDir
+});
+
+// ==================== API 路由 ====================
+
+/**
+ * GET /api/certs
+ * 列出所有证书
+ */
+app.get('/api/certs', (req, res) => {
+  try {
+    const certs = certService.listCertificates();
+    res.json({ success: true, data: certs });
+  } catch (error) {
+    res.status(500).json({ success: false, error: error.message });
+  }
+});
+
+/**
+ * GET /api/certs/:domain
+ * 获取证书信息
+ */
+app.get('/api/certs/:domain', async (req, res) => {
+  try {
+    const { domain } = req.params;
+    const info = certService.getCertificateInfo(domain);
+    
+    if (!info.exists) {
+      return res.status(404).json({ 
+        success: false, 
+        error: '证书不存在' 
+      });
+    }
+
+    // 同时验证证书有效性
+    const verifyResult = await certService.verify(domain);
+    
+    res.json({
+      success: true,
+      data: {
+        ...info,
+        valid: verifyResult.valid
+      }
+    });
+  } catch (error) {
+    res.status(500).json({ success: false, error: error.message });
+  }
+});
+
+/**
+ * POST /api/certs/:domain
+ * 申请证书
+ * 
+ * Body:
+ * {
+ *   "dns": {
+ *     "provider": "aliyun",
+ *     "accessKeyId": "xxx",
+ *     "accessKeySecret": "xxx"
+ *   }
+ * }
+ */
+app.post('/api/certs/:domain', async (req, res) => {
+  try {
+    const { domain } = req.params;
+    const { dns } = req.body;
+
+    // 检查是否已存在
+    if (certService.getCertificateInfo(domain).exists) {
+      return res.status(409).json({
+        success: false,
+        error: '证书已存在，请先删除或使用续期接口'
+      });
+    }
+
+    // 申请证书
+    const result = await certService.apply(domain, dns);
+    
+    res.json({
+      success: true,
+      message: '证书申请成功',
+      data: result
+    });
+  } catch (error) {
+    res.status(500).json({ success: false, error: error.message });
+  }
+});
+
+/**
+ * POST /api/certs/:domain/renew
+ * 续期证书
+ */
+app.post('/api/certs/:domain/renew', async (req, res) => {
+  try {
+    const { domain } = req.params;
+    
+    if (!certService.getCertificateInfo(domain).exists) {
+      return res.status(404).json({
+        success: false,
+        error: '证书不存在'
+      });
+    }
+
+    const result = await certService.renew(domain);
+    
+    res.json({
+      success: true,
+      message: '证书续期成功',
+      data: result
+    });
+  } catch (error) {
+    res.status(500).json({ success: false, error: error.message });
+  }
+});
+
+/**
+ * POST /api/certs/:domain/verify
+ * 验证证书
+ */
+app.post('/api/certs/:domain/verify', async (req, res) => {
+  try {
+    const { domain } = req.params;
+    const result = await certService.verify(domain);
+    
+    res.json({
+      success: true,
+      data: result
+    });
+  } catch (error) {
+    res.status(500).json({ success: false, error: error.message });
+  }
+});
+
+/**
+ * POST /api/certs/:domain/fix-chain
+ * 修复证书链
+ */
+app.post('/api/certs/:domain/fix-chain', async (req, res) => {
+  try {
+    const { domain } = req.params;
+    
+    if (!certService.getCertificateInfo(domain).exists) {
+      return res.status(404).json({
+        success: false,
+        error: '证书不存在'
+      });
+    }
+
+    await certService.fixChain(domain);
+    
+    res.json({
+      success: true,
+      message: '证书链修复成功'
+    });
+  } catch (error) {
+    res.status(500).json({ success: false, error: error.message });
+  }
+});
+
+/**
+ * GET /api/certs/:domain/download
+ * 下载证书文件
+ */
+app.get('/api/certs/:domain/download', (req, res) => {
+  try {
+    const { domain } = req.params;
+    const { type } = req.query; // 'cert' 或 'key'
+    
+    const info = certService.getCertificateInfo(domain);
+    
+    if (!info.exists) {
+      return res.status(404).json({
+        success: false,
+        error: '证书不存在'
+      });
+    }
+
+    const filePath = type === 'key' ? info.paths.key : info.paths.cert;
+    
+    if (!fs.existsSync(filePath)) {
+      return res.status(404).json({
+        success: false,
+        error: '文件不存在'
+      });
+    }
+
+    res.download(filePath);
+  } catch (error) {
+    res.status(500).json({ success: false, error: error.message });
+  }
+});
+
+// ==================== 启动服务 ====================
+
+app.listen(CONFIG.port, () => {
+  console.log(`
+╔════════════════════════════════════════╗
+║     Certctl HTTP API Server            ║
+╠════════════════════════════════════════╣
+║  端口: http://localhost:${CONFIG.port}         ║
+║  邮箱: ${CONFIG.email}          ║
+║  目录: ${CONFIG.certsDir}                 ║
+╚════════════════════════════════════════╝
+
+API 列表:
+  GET    /api/certs              - 列出所有证书
+  GET    /api/certs/:domain      - 获取证书信息
+  POST   /api/certs/:domain      - 申请证书
+  POST   /api/certs/:domain/renew - 续期证书
+  POST   /api/certs/:domain/verify - 验证证书
+  POST   /api/certs/:domain/fix-chain - 修复证书链
+  GET    /api/certs/:domain/download?type=cert|key - 下载证书
+  
+示例:
+  curl http://localhost:${CONFIG.port}/api/certs
+  
+  curl -X POST http://localhost:${CONFIG.port}/api/certs/example.com \\
+    -H "Content-Type: application/json" \\
+    -d '{
+      "dns": {
+        "provider": "aliyun",
+        "accessKeyId": "your-key",
+        "accessKeySecret": "your-secret"
+      }
+    }'
+`);
+});

package/package.json

@@ -1,12 +1,14 @@
 {
       "name": "certctl-cli",
-      "version": "1.0.5",
+      "version": "1.0.6",
       "description": "Lightweight SSL Certificate CLI Tool",
       "bin": {
             "certctl": "bin/run.js"
       },
       "files": [
-            "bin/"
+            "bin/",
+            "examples/",
+            "API.md"
       ],
       "keywords": [
             "ssl",