@flun/windows 3.0.11 → 4.0.0

package/README.md

@@ -1,16 +1,18 @@
 # @flun/windows
 
+## 简介
+
 本工具库能将您的 Node.js 应用程序作为 Windows 后台服务来运行和管理,支持服务的安装、启动、停止及卸载全流程;
 还提供事件日志等功能,它主要用于面向生产环境应用程序的部署与运维;如需联系,邮箱: [open@flun.top](mailto:open@flun.top)
 
-### 本包基于 ESM 模块系统编写->拥抱未来趋势
+**本包基于 ESM 模块系统编写;**
 
 - **推荐方式**:使用 `import` / `export` 语法,静态分析更友好,工具链兼容性最佳;
 - **兼容方式**:Node.js ≥ 23.5.0 原生支持 `require(esm)`;22.12+ 需开启 `--experimental-require-module` 标志;
-- **重要**:本文档所有示例均采用 **ESM 标准**,请确保你的项目 `package.json` 中已设置 `"type": "module"`,或将脚本后缀改为 
+- **重要**:本文档所有示例均采用 **ESM 标准**,请确保你的项目 `package.json` 中已设置 `"type": "module"`,或将脚本后缀改为
   `.mjs`;
 
-## 功能概述
+## 特性
 
 @flun/windows 提供以下功能:
 
@@ -22,13 +24,40 @@
   - _权限检测_:检测当前用户是否具有管理员权限
   - _进程列表_:列出运行中的 Windows 进程/服务
   - _终止进程_:通过 PID 终止特定进程
+
 ---
 
-## 配置
+## 包目录结构
+
+随包发布的文件:
+
+```
+@flun/windows/
+├── index.js              库入口,导出 elevate / sudo / isAdminUser / kill / list / Service / EventLogger
+├── index.d.ts            类型声明
+├── lib/binaries.js       外部二进制定位与提权调用
+├── lib/cmd.js            进程列表与终止
+├── lib/daemon.js         Windows 服务管理类
+├── lib/eventlog.js       事件日志写入
+├── lib/winsw.js          winsw 配置生成
+├── lib/wrapper.js        进程包装器
+├── lib/shared.js         共享工具函数
+├── bin/winsw/            winsw 可执行文件(内部资源,非命令)
+├── bin/elevate.vbs       UAC 提权脚本(内部资源,非命令)
+├── bin/cli.js            命令行入口
+├── win-service.config.js 服务配置模板(全量字段,必填项带 *)
+├── copy-files.js         postinstall 复制二进制资源
+├── package.json          包配置
+├── README.md             本文件
+├── CHANGELOG.md          更新日志
+└── LICENSE               许可
+```
+
+## 安装前准备
 
 ### 允许安装脚本执行
 
-本包在安装时可能触发某些依赖包的自动脚本(如 `postinstall` 等);如果你的 npm 全局配置或项目配置禁止了脚本执行(例如设置了 
+本包在安装时可能触发某些依赖包的自动脚本(如 `postinstall` 等);如果你的 npm 全局配置或项目配置禁止了脚本执行(例如设置了
 `ignore-scripts=true`),可能会导致安装不完整或运行时异常;
 
 推荐在项目根目录的 `package.json` 中添加 `allowScripts` 字段,显式放行本包及其依赖的脚本:
@@ -37,78 +66,167 @@
 {
   "allowScripts": {
     "@flun/windows": true
-    // 如果依赖的其他包(如 bcrypt、electron-winstaller 等)也有脚本,请按需添加,格式相同
   }
 }
 ```
 
-> 如果你信任所有安装包,也可以直接在项目 `.npmrc` 中设置 `allow-scripts = false`(表示关闭脚本拦截,所有脚本均允许执行),
-  或删除 `ignore-scripts` 字段;
-
 ---
 
 ## 安装
 
-推荐通过 npm 全局安装:`npm i -g @flun/windows`
+全局安装后可直接使用 `windows` 命令:
+
+```bash
+npm i -g @flun/windows
+```
 
-然后在项目根目录执行:`npm link @flun/windows`
+局部安装时用 `npx windows` 调用,或在 `package.json` 的 `scripts` 中直接写 `windows`:
 
-局部安装:`npm i @flun/windows`
+```bash
+npm i @flun/windows
+```
 
-## 无原生模块依赖
+### 无原生模块依赖
 
 Windows 上的原生 Node 模块安装复杂,通常需要 Visual Studio 和 node-gyp 进行编译;@flun/windows **不依赖任何原生模块**,
 所有二进制工具均已预打包,无需安装 Visual Studio 等编译环境;
 
-# Windows 服务管理
+---
+
+## 命令行
+
+命令在 `npm scripts` 中运行时,工作目录取 `INIT_CWD`,即发起 npm 命令的项目根目录;
+
+```bash
+windows <命令> [--键 值]
+```
+
+服务类命令默认读取你项目根目录的配置文件(`win-service.config.js`) ;如果命令行指令后加了 `--键 值` ,那么以命令配置为准;
+
+### 快速开始
+编辑`win-service.config.js`文件,填写带 `*` 的必填项 `name` 与 `script`;
+
+```bash
+windows install # 按配置文件安装并启动服务
+
+windows install --name MyApp --script D:\app\main.js # 带参安装并启动
+```
+
+安装后默认启动服务;若只需安装,加 `--no-start`;
+
+全局安装不触发 `postinstall`,可用 `windows example` 手动生成模板;
+
+### 命令
+
+#### 服务类
+
+| 命令               | 说明                                          |
+| ------------------ | --------------------------------------------- |
+| `install`          | 安装服务,装完默认启动;`--no-start` 只装不启动 |
+| `uninstall`        | 卸载服务                                      |
+| `start`            | 启动服务                                      |
+| `stop`             | 停止服务                                      |
+| `restart`          | 重启服务                                      |
+| `status`           | 查询状态,输出 0-3                             |
+| `xml`              | 输出 winsw 配置 XML                           |
+| `exe [--dir 目录]` | 生成 winsw 可执行文件                         |
+
+#### 其它
+
+| 命令                   | 说明                                        |
+| ---------------------- | ------------------------------------------- |
+| `list [--verbose]`     | 列出运行中的进程                            |
+| `kill <pid> [--force]` | 结束进程                                    |
+| `log <级别> <消息>`    | 写事件日志                                  |
+| `is-admin`             | 检查当前是否管理员                          |
+| `elevate <命令...>`    | 以管理员权限执行命令                        |
+| `example`              | 生成 `win-service.config.js` 模板到当前项目 |
+| `help`                 | 显示帮助                                    |
+
+`status` 输出状态码:`0` 不存在;`1` 有服务无文件;`2` 有文件无服务;`3` 完整存在;
+
+`log` 的级别取 `info`、`warn`、`error`、`success`、`failure`;`success` 与 `failure`
+分别对应 `auditSuccess` 与 `auditFailure`;可加 `--source <名>` 指定事件源,`--id <号>` 指定事件 ID;
+
+### 命令行参数示例
+
+```bash
+# 前提:win-service.config.js 已提供 name 与 script;以下每条只覆盖部分字段
+
+# 1. 覆盖描述:装出的服务在服务管理器中显示为该描述
+windows install --description "我的服务"
+
+# 2. 覆盖 node 启动参数:服务以 --harmony 模式运行
+windows install --nodeOptions '["--harmony"]'
+
+# 3. 打开出错退出:脚本运行出错时进程直接退出(省略值即 true)
+windows install --abortOnError
+```
+
+字符串值用双引号,JSON 值用单引号(避免 shell 解析方括号);值先按 JSON 解析,失败则按字符串处理;
+
+---
+
+## 函数方式
+
+### 快速开始
+配置(`win-service.config.js`)必填项,详见[参考配置](#参考配置);
+
+```js
+// 创建并安装一个 Windows 服务:
+import { Service } from '@flun/windows';
+import config from './win-service.config.js';
+
+const svc = new Service(config);
+
+// 安装并自动启动服务(默认)
+svc.install();
+```
+
+安装后可用 Windows 服务管理器、`NET START/STOP` 或 `sc` 命令管理;
+
+### 配置功能
+
+| 功能          | 类型 | 说明                                  |
+| ------------- | ---- | ------------------------------------- |
+| `Service`     | 类   | Windows 服务管理,安装/卸载/启停       |
+| `EventLogger` | 类   | 写入 Windows 事件日志                 |
+| `elevate`     | 函数 | 以管理员权限运行命令(触发 UAC)        |
+| `sudo`        | 函数 | 以管理员身份执行命令(需系统启用 sudo) |
+| `isAdminUser` | 函数 | 检测当前用户是否具有管理员权限        |
+| `list`        | 函数 | 列出运行中的进程/服务                 |
+| `kill`        | 函数 | 通过 PID 终止进程                     |
+
+以下各节为各导出的详细用法;
+
+### Windows 服务管理
 
 @flun/windows 可将 Node.js 脚本转换为 Windows 服务;注意:创建服务需要管理员权限!!
 
+以下示例仅列常用项,全部可配置字段与默认值见[参考配置](#参考配置);
+
 基础示例:
 
 ```js
 import { Service } from '@flun/windows';
+import config from './win-service.config.js';
 
-// 创建服务对象
-const svc = new Service({
-  name: 'Hello World',
-  description: 'nodejs.org 示例服务器',
-  script: 'C:\\path\\to\\helloworld.js',
-  nodeOptions: [
-    '--harmony',
-    '--max-old-space-size=4096'
-  ]
-  // ===== 其它可选配置 =====
-  //, maxRetries: null             // 最大重试次数(默认null,表示忽略)
-  //, maxRestarts: 3               // 60秒内最大重启次数(默认3)
-  //, stoptimeout: 30              // 停止服务超时时间(秒,默认30)
-  //, wait: 1                      // 重启等待时间(秒,默认1)
-  //, scriptOptions: ''            // 传递给脚本的参数(默认空字符串)
-  //, stopparentfirst: false       // 是否先停止父进程(默认false)
-  //, abortOnError: false          // 遇到错误是否退出进程(默认false)
-  //, grow: 0.25                   // 重启等待时间增长比例(默认0.25即25%)
-  //, logpath: null                // 日志文件路径(默认null,使用默认路径)
-  //, logmode: 'rotate'            // 日志模式('reset', 'roll', 'append')
-  //, execPath: process.execPath   // Node.js可执行文件路径(默认当前Node)
-  //, logOnAs: {}                  // 服务运行的用户凭据('domain'、'account'、'password'和'mungeCredentialsAfterInstall')
-  //, env: undefined               // 环境变量(默认:undefined)
-  //, logging: null                // 日志配置(默认:mode = 'append', pattern = 'yyyMMdd', sizeThreshold = 10240, keepFiles 
-  // = 8)
-  //, allowServiceLogon: undefined // 允许服务登录(默认undefined)
-  //, workingDirectory: process.cwd() // 工作目录(默认当前目录)
-});
-
-// 监听安装完成事件
-svc.on('install', ()=>{
-  svc.start();
-});
+const svc = new Service(config);
 
+// 安装并自动启动服务(默认)
 svc.install();
+
+// 只安装,不自动启动
+// svc.install(undefined, false);
 ```
 
 服务创建后可通过 Windows 服务管理器、`NET START/STOP` 或 `sc` 命令管理;
 
-### 支持的事件
+默认情况下,各方法执行后会在终端打印结果(如 `服务安装完成;`);
+若将本包嵌入到生产项目,终端输出会混入宿主日志,可在配置中设 `quiet: true`,
+此时库只发事件、不打印,通过下方事件获取状态;命令行方式恒为 `quiet`,不受此字段影响;
+
+#### 支持的事件
 
 - _install_ - 服务安装完成
 - _alreadyinstalled_ - 服务已存在
@@ -119,81 +237,63 @@ svc.install();
 - _stop_ - 服务停止
 - _error_ - 发生错误
 
-### 脚本参数传递
-
-通过 `scriptOptions` 配置:
+#### 环境变量设置
 
-```js
-import { Service } from '@flun/windows';
-const svc1 = new Service({
-  ...,          // 基本配置略...
-  scriptOptions: '-c C:\\config\\special.conf -i'
-});
-```
-
-### 环境变量设置
-
-`@flun/windows` 会自动向服务进程注入 `USERPROFILE` 环境变量,其值为**安装服务时当前登录用户的主目录**(例如 
+`@flun/windows` 会自动向服务进程注入 `USERPROFILE` 环境变量,其值为**安装服务时当前登录用户的主目录**(例如
 `C:\Users\你的用户名`;
 这确保了服务中调用 `os.homedir()` 能返回正确的用户目录,即使服务以 `LocalSystem` 等系统账户运;
 
 **你通常不需要手动设置 `USERPROFILE`**,如需添加其他自定义环境变量,可按以下方式:
 
 ```js
-import { Service } from '@flun/windows';
-const svc = new Service({
-  name: 'My Service',
-  script: 'C:\\app\\server.js',
+// win-service.config.js
+export default {
+  // ...其余字段
   env: {
     MY_CUSTOM_VAR: 'some value',
-    ANOTHER_VAR: 'hello'
-  }
-});
-// 也支持数组形式
-const svc2 = new Service({
-  ...,
-  env: [
-    { name: 'VAR1', value: 'value1' },
-    { name: 'VAR2', value: 'value2' }
-  ]
-});
+    ANOTHER_VAR: 'hello',
+  },
+};
 ```
 
-### 指定 Node 执行路径
+也支持数组形式,元素为 `{ name, value }`:
 
 ```js
-import { Service } from '@flun/windows';
-const svc = new Service({
-  ...,          // 基本配置略...
-  execPath: 'C:\\特定路径\\node.exe'
-});
+// win-service.config.js
+export default {
+  // ...其余字段
+  env: [
+    { name: 'VAR1', value: 'value1' },
+    { name: 'VAR2', value: 'value2' },
+  ],
+};
 ```
 
-### 用户账户配置
+#### 用户账户配置
 
 ```js
 import { Service } from '@flun/windows';
-const svc = new Service({
-  ...,          // 基本配置略...
-});
+import config from './win-service.config.js';
+
+const svc = new Service(config);
 
 // 安装后指定特定用户或凭据以登录运行
 svc.logOnAs.domain = 'mydomain.local';
 svc.logOnAs.account = 'username';
 svc.logOnAs.password = 'password';
-svc.logOnAs.mungeCredentialsAfterInstall: true // 默认
+svc.logOnAs.mungeCredentialsAfterInstall = true; // 默认
 ```
-> 💡 **提示**:即使你使用默认的 `LocalSystem` 账户运行服务,`@flun/windows` 也会通过自动注入 `USERPROFILE` 环境变量,
-  使你的应用能够正确获取当前登录用户的目录(例如读取用户目录下的配置文件);因此,你不需要为了修正 `os.homedir()` 而特意配置 
+> **提示**:即使你使用默认的 `LocalSystem` 账户运行服务,`@flun/windows` 也会通过自动注入 `USERPROFILE` 环境变量,
+  使你的应用能够正确获取当前登录用户的目录(例如读取用户目录下的配置文件);因此,你不需要为了修正 `os.homedir()` 而特意配置
   `logOnAs` 账户和密码;
 
-### 服务卸载
+#### 服务卸载
 
 ```js
 import { Service } from '@flun/windows';
-const svc = new Service({
-  ...,          // 基本配置略...
-});
+import config from './win-service.config.js';
+
+const svc = new Service(config);
 svc.on('uninstall', ()=>{
   console.log('卸载完成');
   console.log('服务是否存在:', svc.exists);
@@ -209,29 +309,13 @@ svc.uninstall();
 
 注:卸载仅移除服务相关文件,**不会删除您的 Node.js 脚本**;
 
-### 智能重启机制
-
-@flun/windows 提供可配置的重启策略:
-
-```js
-import { Service } from '@flun/windows';
-const svc = new Service({
-  ...,          // 基本配置略...
-  wait: 2,      // 初始等待时间(秒)
-  grow: 0.5,    // 等待时间增长比例(50%)
-  maxRetries: 5, // 最大重试次数
-  maxRestarts: 3 // 60秒内最大重启次数
-});
-```
-
-### 服务实现原理
+#### 服务实现原理
 
-使用 [winsw]为每个服务生成独立的 `.exe` 和 `.xml` 配置文件,存储在脚本所在目录的 `daemon` 子文件夹中;服务日志可通过 Windows 
+使用 [winsw]为每个服务生成独立的 `.exe` 和 `.xml` 配置文件,存储在脚本所在目录的 `daemon` 子文件夹中;服务日志可通过 Windows
 事件查看器查看;
 此外,服务启动时会自动设置 `USERPROFILE` 环境变量为安装服务时当前用户的用户目录,保证路径相关 API 的行为与预期一致;
----
 
-# 事件日志系统
+### 事件日志系统
 
 @flun/windows 提供非 C++ 依赖的事件日志功能:
 
@@ -256,11 +340,9 @@ const eLog2 = new EventLogger({
 });
 ```
 
----
-
-# 系统命令工具
+### 系统命令工具
 
-## elevate(权限提升)
+#### elevate(权限提升)
 
 `elevate` 类似于 Linux/Mac 上的 `sudo`,它会尝试将当前用户的权限提升为本地管理员;但要求当前用户具有管理员权限,
 若无管理员权限,命令将失败并返回 `access denied` 错误;
@@ -275,12 +357,8 @@ const eLog2 = new EventLogger({
 import { elevate } from '@flun/windows';
 // 基本用法
 elevate('echo "Hello World" && whoami',{}, (error, stdout, stderr) => {
-    if (error) {
-        console.error('执行失败:', error);
-    } else {
-        console.log('执行成功,输出:', stdout);
-        console.log('错误输出:', stderr);
-    }
+    if (error) console.error('执行失败:', error);
+    else console.log('执行成功,输出:', stdout), console.log('错误输出:', stderr);
 });
 
 // 带选项参数
@@ -291,7 +369,7 @@ elevate('echo "Hello World" && whoami', (err, stdout)=> { }); // options视为
 elevate('echo "Hello World" && whoami'); // 无回调
 ```
 
-## sudo(管理员执行)
+#### sudo(管理员执行)
 
 `sudo` 与 Linux/Mac 上的 `sudo` 类似;与 `elevate` 雷同,但稳定性更高,这仍要求用户具有管理员权限,
 并且需在Windows上启用sudo命令,否则命令将失败;
@@ -311,10 +389,7 @@ import { sudo } from '@flun/windows';
 // 基本用法 - 命令、选项和回调
 sudo('echo "Hello World" && whoami', {}, (error, stdout, stderr) => {
     if (error) console.error('执行失败:', error);
-    else {
-        console.log('执行成功,输出:', stdout);
-        console.log('错误输出:', stderr);
-    }
+    else console.log('执行成功,输出:', stdout), console.log('错误输出:', stderr);
 });
 
 // 带选项参数
@@ -323,7 +398,7 @@ sudo('echo "Hello World" && whoami', {cwd:'C:\\'}, callback);
 sudo('echo "Hello World" && whoami' ); // 无回调
 ```
 
-## 管理员权限检测
+#### 管理员权限检测
 
 此异步命令用于判断当前用户是否拥有管理员权限;它会向回调函数传递一个布尔值,如果用户是管理员则返回 `true`,否则返回 `false`;
 
@@ -339,7 +414,7 @@ isAdminUser(isAdmin => {
 });
 ```
 
-## 进程列表
+#### 进程列表
 
 获取运行中的 Windows 进程/服务列表;
 
@@ -350,22 +425,53 @@ list(processes => {
 }, true); // true 显示详细信息
 ```
 
-## 终止进程
+#### 终止进程
 
-通过 PID 终止特定进程;
+通过进程 PID 终止特定进程;
 
 ```js
 import { kill } from '@flun/windows';
-kill(进程PID, () => {
+kill(PID, () => {
   console.log('进程已终止');
 });
 ```
 
 ---
 
-# 故障排除
+## 参考配置
+
+以下为 `win-service.config.js` 的字段说明,属查阅性内容,使用前无需通读;
+带 * 的字段为必填项;
+
+| 参数                | 作用                                                                             |
+| ------------------- | -------------------------------------------------------------------------------- |
+| `name` *            | 服务名称,同时作为注册表与服务标识;不能含 `<>:"\/` 与 `?*` 及竖线                 |
+| `script` *          | 启动服务的入口脚本绝对路径                                                       |
+| `description`       | 服务描述,显示在服务管理器中;默认空字符串                                         |
+| `nodeOptions`       | 传递给 node 进程的选项;默认 `--harmony`                                          |
+| `scriptOptions`     | 传递给脚本的选项;默认空字符串                                                    |
+| `execPath`          | node 可执行文件路径;默认取当前进程 `execPath`                                    |
+| `workingDirectory`  | 服务工作目录;默认取当前工作目录                                                  |
+| `maxRetries`        | 无响应或故障前的最大重试次数;默认 `null`,不启用                                  |
+| `maxRestarts`       | 60 秒内最大重启次数;默认 `3`,`0` 表示不启用                                      |
+| `stoptimeout`       | 停止服务的超时秒数;默认 `30`                                                     |
+| `wait`              | 脚本停止后等待重启的秒数;默认 `1`                                                |
+| `grow`              | 重启等待时间的增长百分比;默认 `0.25`                                             |
+| `abortOnError`      | 脚本运行错误时是否退出进程;默认 `false`                                          |
+| `stopparentfirst`   | 是否先停止父进程;默认 `false`                                                    |
+| `logpath`           | 日志文件路径;默认与可执行文件同目录                                              |
+| `logmode`           | 日志模式,取 `rotate`、`truncate`、`append`;默认 `rotate`                         |
+| `env`               | 环境变量,形如 `{ name, value }` 或同构数组                                       |
+| `logging`           | 日志配置对象,可替代 `logmode`;含 `mode`、`pattern`、`sizeThreshold`、`keepFiles` |
+| `logOnAs`           | 服务登录凭据,含 `account`、`password`、`domain`、`mungeCredentialsAfterInstall`  |
+| `allowServiceLogon` | 是否允许服务登录                                                                 |
+| `quiet`             | 为 `true` 时不打印执行结果,只发事件;默认 `false`;命令行方式恒为 `true`           |
+
+---
+
+## 常见问题
 
-## elevate 和 sudo 函数常见问题
+### elevate 和 sudo 函数常见问题
 
 1. **sudo 函数执行失败**:这可能是因为 `sudo.exe` 外部工具不兼容当前系统,建议使用 `elevate` 函数作为替代
 
@@ -375,17 +481,19 @@ kill(进程PID, () => {
 
 4. **sudo 函数需要在系统中设置并启用sudo**
 
-## 服务管理常见问题
+### 服务管理常见问题
 
 - `invalidinstallation` 错误通常表示 daemon 目录文件不完整
 - 卸载时若文件被锁定,可重新运行卸载或手动删除 `daemon` 目录
 
 ---
 
-# 致谢!!!
+## 许可证
+
+winsw 和 sudowin 遵循各自所有者的许可证;@flun/windows 核心代码采用 ISC 许可证(具体内容请见许可证文档)
 
-感谢所有贡献者,特别感谢 @arthurblake、@hockeytim11 等开发者的贡献;
+---
 
-# 许可证
+## 贡献
 
-winsw 和 sudowin 遵循各自所有者的许可证;@flun/windows 核心代码采用 ISC 许可证(具体内容请见许可证文档)
+感谢所有贡献者,特别感谢 @arthurblake、@hockeytim11 等开发者的贡献;