{"_id":"@cjwddz/service-manager","name":"@cjwddz/service-manager","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@cjwddz/service-manager","version":"0.0.1","type":"module","description":"A service management framework for Node.js applications with daemon support","main":"./dist/index.js","types":"./dist/index.d.ts","bin":{"service-manager":"dist/cli.js"},"scripts":{"build":"tsc","test":"node --test dist/test/index.test.js","lint":"eslint src --ext .ts"},"keywords":["service","daemon","process-manager","cli","service-manager"],"author":"","license":"MIT","dependencies":{"commander":"^11.1.0"},"devDependencies":{"@types/node":"^20.0.0","@typescript-eslint/eslint-plugin":"^6.0.0","@typescript-eslint/parser":"^6.0.0","eslint":"^8.0.0","eslint-config-prettier":"^9.0.0","prettier":"^3.0.0","typescript":"^5.0.0"},"_id":"@cjwddz/service-manager@0.0.1","gitHead":"6963950df40993cae5f7f988dafeee5107b9a71d","_nodeVersion":"20.19.6","_npmVersion":"10.8.2","dist":{"integrity":"sha512-vBVj2nBXBOa/YQsiLQNmDNbi0ovwXqwcgybAon9JRgjWkd7fClQOVh5fWVpZrV0D01fCW9NMrq/6JgfRXqSnsw==","shasum":"cccc2761ef8b85adf4c2d47e02e3c6cd2081cb61","tarball":"https://registry.npmjs.org/@cjwddz/service-manager/-/service-manager-0.0.1.tgz","fileCount":62,"unpackedSize":117535,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIB9B72etn3mlpvKjIBGozteZioWCHHJCXNf/Qz6yEadSAiEA7it28GRjLApbE1SX50NQe8+fufJReOydz0w5pMDwTjk="}]},"_npmUser":{"name":"cjwddz","email":"1436983000@qq.com"},"directories":{},"maintainers":[{"name":"cjwddz","email":"1436983000@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/service-manager_0.0.1_1768315504071_0.011284738702439512"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-13T14:45:03.978Z","0.0.1":"2026-01-13T14:45:04.223Z","modified":"2026-01-13T14:45:04.526Z"},"maintainers":[{"name":"cjwddz","email":"1436983000@qq.com"}],"description":"A service management framework for Node.js applications with daemon support","keywords":["service","daemon","process-manager","cli","service-manager"],"license":"MIT","readme":"# @cjwddz/service-manager\n\n一个支持守护进程的 Node.js 服务管理框架。\n\n## 特性\n\n- 🚀 **易于使用**：只需实现 `start()` 方法\n- 🔄 **生命周期钩子**：`beforeStart`、`afterStart`、`beforeStop`、`beforeRestart`、`afterRestart`、`onUpdateAvailable`\n- 📊 **自动状态检查**：框架自动提供状态和健康检查\n- 🛠️ **CLI 命令**：`start`、`stop`、`restart`、`status`\n- 🔒 **进程管理**：PID 文件管理、优雅关闭\n- 🔁 **自动重启**：可配置的自动重启，支持重启限制和退避策略\n- 🔄 **自动更新检查**：自动检查更新，支持自定义检查逻辑\n- 📝 **日志管理**：自动日志文件管理\n\n## 安装\n\n```bash\nnpm install @cjwddz/service-manager\n```\n\n## 快速开始\n\n### 最小示例\n\n```typescript\n// src/index.ts\nimport { createService } from '@cjwddz/service-manager';\nimport { Hono } from 'hono';\nimport { serve } from '@hono/node-server';\n\nconst app = new Hono();\napp.get('/', (c) => c.json({ message: 'Hello' }));\n\n// 只需调用 createService()，框架自动处理一切：\n// - 守护进程模式检测和自动运行\n// - CLI 命令注册\n// - 所有管理逻辑\ncreateService({\n  name: 'my-service',\n  start: async () => {\n    return serve({\n      fetch: app.fetch,\n      port: 3000,\n    });\n  },\n});\n```\n\n```typescript\n// bin/cli.ts\n#!/usr/bin/env node\nimport '../src/index.js'; // 注册服务\nimport '@cjwddz/service-manager/cli'; // 注册 CLI 命令\n```\n\n### 使用生命周期钩子\n\n```typescript\n// src/index.ts\nimport { createService, IService, UpdateInfo } from '@cjwddz/service-manager';\nimport { Hono } from 'hono';\nimport { serve } from '@hono/node-server';\nimport { initDatabase, closeDatabase } from './db';\n\nclass MyService implements IService {\n  async start() {\n    const app = new Hono();\n    app.get('/', (c) => c.json({ message: 'Hello' }));\n\n    return serve({\n      fetch: app.fetch,\n      port: 3000,\n    });\n  }\n\n  hooks = {\n    beforeStart: async () => {\n      await initDatabase();\n    },\n\n    afterStart: async () => {\n      await registerToRegistry();\n    },\n\n    beforeStop: async () => {\n      await saveState();\n      await closeDatabase();\n    },\n\n    beforeRestart: async () => {\n      await backupData();\n    },\n\n    afterRestart: async () => {\n      await verifyService();\n    },\n\n    // 更新检查钩子\n    onUpdateAvailable: async (updateInfo: UpdateInfo) => {\n      console.log(`Update available: ${updateInfo.currentVersion} → ${updateInfo.latestVersion}`);\n      // 返回 true 表示执行自动更新，false 表示只通知\n      return false; // 默认只通知，不自动更新\n    },\n  };\n}\n\ncreateService(new MyService(), {\n  name: 'my-service',\n  version: '1.0.0',\n  // 自动重启配置\n  autoRestart: {\n    enabled: true,\n    maxRestarts: 5, // 1 分钟内最多重启 5 次\n    restartWindow: 60 * 1000, // 1 分钟时间窗口\n    backoff: 'exponential', // 指数退避：1s, 2s, 4s, 8s...\n  },\n  // 自动更新检查配置\n  updateCheck: {\n    enabled: true,\n    interval: 24 * 60 * 60 * 1000, // 每 24 小时检查一次\n    autoUpdate: false, // 默认不自动更新，只通知\n    // checkFunction: customUpdateCheck, // 可选：自定义检查函数\n  },\n});\n```\n\n## CLI 使用\n\n### 在 package.json 中配置 CLI\n\n```json\n{\n  \"name\": \"my-service\",\n  \"version\": \"1.0.0\",\n  \"bin\": {\n    \"my-service\": \"./bin/cli.js\"\n  }\n}\n```\n\n### 创建 CLI 入口\n\n```typescript\n// bin/cli.ts\n#!/usr/bin/env node\n// 1. 先导入服务代码（注册服务，框架会自动处理守护进程模式）\nimport '../src/index.js';\n// 2. 然后导入 CLI（注册命令）\nimport '@cjwddz/service-manager/cli';\n```\n\n**就是这么简单！** 框架会自动：\n\n- ✅ 检测守护进程模式并自动运行服务\n- ✅ 注册 CLI 命令\n- ✅ 处理所有管理逻辑\n\n**用户无需手动处理守护进程模式检测和 CLI 注册！**\n\n### 使用 CLI 命令\n\n```bash\n# 启动服务\nmy-service start\n\n# 停止服务\nmy-service stop\n\n# 重启服务\nmy-service restart\n\n# 查看状态\nmy-service status\n```\n\n## API 参考\n\n### `createService(service, config?)`\n\n创建服务管理器实例。\n\n**参数：**\n\n- `service: IService` - 服务实现\n- `config?: Partial<ServiceConfig>` - 可选配置\n\n**返回：** `ServiceManager`\n\n### `IService` 接口\n\n```typescript\ninterface IService {\n  start(): Promise<void | Server>;\n  hooks?: {\n    beforeStart?: () => Promise<void> | void;\n    afterStart?: () => Promise<void> | void;\n    beforeStop?: () => Promise<void> | void;\n    beforeRestart?: () => Promise<void> | void;\n    afterRestart?: () => Promise<void> | void;\n    onUpdateAvailable?: (updateInfo: UpdateInfo) => Promise<boolean> | boolean;\n  };\n}\n```\n\n### `ServiceConfig` 接口\n\n```typescript\ninterface ServiceConfig {\n  name: string;\n  version?: string;\n  cwd?: string;\n  dataDir?: string;\n  pidFile?: string;\n  logFile?: string;\n  startTimeout?: number;\n  stopTimeout?: number;\n  restartDelay?: number;\n  autoRestart?: {\n    enabled: boolean;\n    maxRestarts?: number; // 最大重启次数（默认：5）\n    restartWindow?: number; // 重启时间窗口（毫秒，默认：60000）\n    restartDelay?: number; // 重启延迟（毫秒，默认：1000）\n    backoff?: 'linear' | 'exponential'; // 退避策略（默认：exponential）\n    baseDelay?: number; // 基础延迟（毫秒，默认：1000）\n  };\n  updateCheck?: {\n    enabled: boolean; // 是否启用更新检查（默认：false）\n    interval?: number; // 检查间隔（毫秒，默认：24小时）\n    autoUpdate?: boolean; // 是否自动更新（默认：false）\n    checkFunction?: () => Promise<UpdateInfo | null>; // 自定义检查函数\n  };\n  env?: Record<string, string>;\n  stdout?: string | 'inherit' | 'ignore';\n  stderr?: string | 'inherit' | 'ignore';\n}\n```\n\n### `UpdateInfo` 接口\n\n```typescript\ninterface UpdateInfo {\n  currentVersion: string;\n  latestVersion: string;\n  packageName: string;\n  updateAvailable: boolean;\n  changelog?: string;\n  [key: string]: any;\n}\n```\n\n## 工作原理\n\n1. **框架控制管理逻辑**：所有 start/stop/restart 逻辑都由框架处理\n2. **业务代码提供钩子**：您的代码实现 `start()` 和可选的生命周期钩子\n3. **自动状态检查**：框架自动检查进程状态、运行时间和健康状态\n4. **进程管理**：框架管理 PID 文件、信号处理和优雅关闭\n5. **自动重启**：如果启用，框架会自动重启失败的服务，支持重启限制和退避策略\n6. **更新检查**：框架自动检查更新并通过钩子通知\n\n## 自动重启保护机制\n\n框架防止无限重启循环：\n\n- **重启限制**：时间窗口内的最大重启次数（默认：1 分钟内最多 5 次）\n- **退避策略**：重启之间的指数或线性延迟\n- **时间窗口**：时间窗口过期后重启计数器重置\n\n### 退避策略示例\n\n**指数退避（exponential）**：\n\n- 第 1 次重启：等待 1 秒\n- 第 2 次重启：等待 2 秒\n- 第 3 次重启：等待 4 秒\n- 第 4 次重启：等待 8 秒\n- 第 5 次重启：等待 16 秒\n\n**线性退避（linear）**：\n\n- 第 1 次重启：等待 1 秒\n- 第 2 次重启：等待 2 秒\n- 第 3 次重启：等待 3 秒\n- 第 4 次重启：等待 4 秒\n- 第 5 次重启：等待 5 秒\n\n## 更新检查\n\n框架可以自动检查更新：\n\n- **默认行为**：检查 npm registry 中的包更新\n- **可自定义**：您可以提供自定义的 `checkFunction` 来覆盖默认逻辑\n- **基于钩子**：当有更新可用时，会调用 `onUpdateAvailable` 钩子\n- **自动更新**：可选的自动更新（默认禁用以确保安全）\n\n### 默认更新检查逻辑\n\n1. 读取 `package.json` 获取包名和当前版本\n2. 检查是否是 npm 包（排除本地包）\n3. 查询 npm registry 获取最新版本\n4. 比较版本号\n5. 如果有更新，调用 `onUpdateAvailable` 钩子\n\n### 自定义更新检查\n\n```typescript\nimport { defaultUpdateCheck, UpdateInfo } from '@cjwddz/service-manager';\n\nasync function customUpdateCheck(): Promise<UpdateInfo | null> {\n  // 使用默认检查\n  const result = await defaultUpdateCheck();\n\n  // 添加自定义逻辑\n  if (result && result.updateAvailable) {\n    // 从 GitHub API 获取 changelog\n    const changelog = await fetchChangelog(result.latestVersion);\n    return {\n      ...result,\n      changelog,\n    };\n  }\n\n  return result;\n}\n\ncreateService(\n  {\n    start: async () => {\n      /* ... */\n    },\n  },\n  {\n    updateCheck: {\n      enabled: true,\n      checkFunction: customUpdateCheck, // 使用自定义检查函数\n    },\n  }\n);\n```\n\n## 许可证\n\nMIT\n","readmeFilename":"README.md","_rev":"1-5be8ab61b1d425f601d993e0cc1442a3"}