# asai-nodejs-hostweb 中文文档

规范地址：https://npmcn.com/package/asai-nodejs-hostweb/

版本：0\.2\.48
npm 元数据更新时间：2026-11-03T03:30:35.157Z
中文译文更新时间：2026-11-03T03:56:26.264Z
软件包许可：ISC

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/asai-nodejs-hostweb
原文对照：https://npmcn.com/package/asai-nodejs-hostweb/?lang=original
源码仓库：https://gitee.com/guoyansai/asaiplug/asai-nodejs-hostweb

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：67.2 kB，3 个文件
- TypeScript 类型：未声明
- 运行依赖：1 个
- 首次发布：2025-11-05T02:39:42.502Z
- 最新版本发布：2026-11-03T03:30:34.995Z
- 已发布版本数：59（近 12 个月 59 个）

## 中文简介

对你说

## 安装

```sh
npm install asai-nodejs-hostweb
```

也可以使用：`pnpm add asai-nodejs-hostweb`、`yarn add asai-nodejs-hostweb`、`bun add asai-nodejs-hostweb`

## README

# asai-nodejs-hostweb — Web 系统功能插件

## 功能概述

`asai-nodejs-hostweb` 是系统的**Web 功能插件**，为 Web 应用提供四大模块功能：**库工具（lib-install）**、**API 接口**、**系统管理（sys）** 和 **WebSocket 服务**。它作为 `asai-nodejs-host` 的配套插件，注入具体的业务处理逻辑。

* * *

## 文件结构

```
asai-nodejs-hostweb/
├── README.md
└── asai-nodejs-hostweb/
    ├── index.ts              ← 入口文件：整合四大模块
    ├── lib-install/
    │   ├── Index.ts          ← 库工具导出（As, AsSys, AsNodeTool, AsCode, AsAES, AsDb）
    │   └── common/
    │       ├── As.ts         ← 基础工具函数
    │       ├── AsSys.ts      ← 系统方法
    │       ├── AsNodeTool.ts ← Node.js 工具方法
    │       ├── AsCode.ts     ← 编解码工具
    │       ├── AsAES.ts      ← AES 加解密
    │       └── AsDb.ts       ← 数据库插件路由（含 AsDbChannelFile, AsDbPlugs）
    ├── api/
    │   ├── Index.ts          ← API 路由注册（13 个 API 端点）
    │   ├── init/
    │   │   └── code.ts       ← 初始化代码
    │   ├── user/
    │   │   └── userinfo.ts   ← 用户信息 API
    │   ├── channel/
    │   │   ├── channelsqliteserver.ts  ← SQLite 通道服务
    │   │   ├── channelfileserver.ts    ← 文件通道服务
    │   │   └── channeljsonserver.ts    ← JSON 通道服务
    │   └── common/
    │       ├── mmmanage.ts    ← 会员管理
    │       ├── filemanage.ts  ← 文件管理
    │       ├── jsonmanage.ts  ← JSON 管理
    │       ├── logmanage.ts   ← 日志管理
    │       ├── sqlitemanage.ts← SQLite 管理
    │       ├── shellmanage.ts ← Shell 命令执行
    │       ├── dirmanage.ts   ← 目录管理
    │       └── zipmanage.ts   ← ZIP 压缩管理
    ├── sys/
    │   ├── Index.ts          ← 系统路由注册（9 个系统端点）
    │   └── common/
    │       ├── file.ts       ← 文件系统操作
    │       ├── zip.ts        ← 压缩操作
    │       ├── json.ts       ← JSON 操作
    │       ├── shell.ts      ← Shell 执行
    │       ├── upload.ts     ← 文件上传
    │       ├── update.ts     ← 更新操作
    │       ├── upgrade.ts    ← 升级操作
    │       ├── guard.ts      ← 守护进程
    │       └── info.ts       ← 系统信息
    └── ws/
        ├── Index.ts          ← WebSocket 路由注册（5 个 WS 端点）
        ├── common/
        │   └── ping.ts       ← WS 心跳检测
        ├── chat/
        │   └── web.ts        ← Web 聊天处理
        └── user/
            ├── exit.ts       ← 用户退出
            ├── login.ts      ← 用户登录
            └── online.ts     ← 在线用户管理
```

* * *

## 入口文件 — `index.ts`

```typescript
import libInstall from './lib-install/Index';
import api from './api/Index';
import sys from './sys/Index';
import ws from './ws/Index';

const initHostWeb: any = {
  ...libInstall,    // 展开库工具（As, AsSys, AsNodeTool, AsCode, AsAES, AsDb）
  api,              // API 路由容器
  sys,              // 系统路由容器
  ws,               // WebSocket 路由容器
};

export default initHostWeb;
```

* * *

## 模块分析

### 1\. lib-install — 基础库工具

提供系统运行所需的基础能力：

| 模块 | 说明 |
| --- | --- |
| `As` | 基础工具函数 |
| `AsSys` | 系统级方法 |
| `AsNodeTool` | Node.js 工具方法 |
| `AsCode` | 编解码工具 |
| `AsAES` | AES 加解密（aes-256-gcm） |
| `AsDb` | 数据库插件路由（封装 asai-nodejs-db 调用） |

### 2\. api — API 接口层

通过 `Index.ts` 注册 13 个 API 端点，挂载到 `$asai.$lib.api`：

| 路由 | 模块文件 | 说明 |
| --- | --- | --- |
| `init/code` | `init/code` | 初始化代码 |
| `user/userinfo` | `user/userinfo` | 用户信息查询 |
| `asaichannel/sqlite` | `channel/channelsqliteserver` | SQLite 通道服务 |
| `asaichannel/file` | `channel/channelfileserver` | 文件通道服务 |
| `asaichannel/json` | `channel/channeljsonserver` | JSON 通道服务 |
| `asaimm/manage` | `common/mmmanage` | 会员管理 |
| `asaifile/manage` | `common/filemanage` | 文件管理 |
| `asaijson/manage` | `common/jsonmanage` | JSON 管理 |
| `asaisqlite/manage` | `common/sqlitemanage` | SQLite 管理 |
| `asaishell/manage` | `common/shellmanage` | Shell 命令执行 |
| `asaidir/manage` | `common/dirmanage` | 目录管理 |
| `asaizip/manage` | `common/zipmanage` | ZIP 压缩管理 |

### 3\. sys — 系统管理

通过 `Index.ts` 注册 9 个系统端点，挂载到 `$asai.$lib.sys`：

| 路由 | 模块文件 | 说明 |
| --- | --- | --- |
| `sys/file` | `common/file` | 文件系统操作 |
| `sys/zip` | `common/zip` | ZIP 压缩/解压 |
| `sys/json` | `common/json` | JSON 数据操作 |
| `sys/shell` | `common/shell` | Shell 命令执行 |
| `sys/upload` | `common/upload` | 文件上传处理 |
| `sys/update` | `common/update` | 系统更新 |
| `sys/upgrade` | `common/upgrade` | 系统升级 |
| `sys/guard` | `common/guard` | 守护进程检测 |
| `sys/info` | `common/info` | 系统信息查询 |

### 4\. ws — WebSocket 服务

通过 `Index.ts` 注册 5 个 WebSocket 端点，挂载到 `$asai.$lib.ws`：

| 路由 | 模块文件 | 说明 |
| --- | --- | --- |
| `ping` | `common/ping` | WS 心跳检测（保持连接活跃） |
| `chat/web` | `chat/web` | Web 聊天消息处理 |
| `user/exit` | `user/exit` | 用户退出登录 |
| `user/login` | `user/login` | 用户登录处理 |
| `user/online` | `user/online` | 在线用户状态管理 |

* * *

## 使用示例

```javascript
// 在 asai-nodejs-host 初始化时注入
import initHostWeb from './asai-nodejs-hostweb/index';

const hostWeb = initHostWeb;

// hostWeb 展开为：
// {
//   As, AsSys, AsNodeTool, AsCode, AsAES, AsDb,  // lib-install
//   api,                                           // API 路由容器
//   sys,                                           // 系统路由容器
//   ws                                             // WebSocket 路由容器
// }

// 这些模块在 asai-nodejs-host 初始化时被挂载到 $asai.$lib
// $asai.$lib.api['asaifile/manage'](...)
// $asai.$lib.sys['sys/file'](...)
// $asai.$lib.ws['user/login'](...)
```

* * *

## 安全 / 鉴权

本插件的业务 handler 依赖宿主 `asaihost-nodejs` 的 HTTP 鉴权（`validateHttpAuthAsync`）；以下为插件内路径与响应安全要点：

| 项 | 说明 |
| --- | --- |
| **路径白名单** | `sys/guard`、`sys/zip` 等对 `fpath` 调用 `AsSys.resolveSafePath()`，**必须使用返回值** 读写，禁止直接用原始 query 路径 |
| **鉴权失败必响应** | `sys/file`、`sys/shell`、`sys/upload`、`sys/json` 等在密码/权限失败时 `writeHead` + `res.end(...)`，避免连接挂起 |
| **Shell 注入防护** | `sys/shell` 拒绝含 `\r`、`\n` 及 \`;& |
| **批量上传路径 containment** | `api/asaifile/manage/up*batch` 通过 `resolveUnderDir(rootDir, el.name)` 校验，阻止 `../` 逃逸上传目录 |
| **通道文件路径** | `api/asaichannel/file` 对 `query.path` 经 `resolveSafePath` 解析后再使用 |

`AsSys.resolveSafePath` / `fsReadFile` / `fsWriteFile` 在路径越界时同步 `res.end` 错误 JSON，handler 须 `return` 终止。

* * *

## 依赖关系

```
asai-nodejs-host  (服务器引擎)
    └── asai-nodejs-hostweb  (Web 功能插件)
            └── asai-nodejs-db  (数据库操作)
            └── asai-nodejs-fs  (文件系统操作)
            └── asai-nodejs-zip (ZIP 压缩)
```

`asai-nodejs-hostweb` 是业务逻辑的核心插件，它通过 `asai-nodejs-host` 提供的路由机制，将具体的业务处理函数注册到对应的 API、系统管理和 WebSocket 路由中。

* * *

## 注意事项

1.  本插件需配合 `asai-nodejs-host` 使用，通过 `opt` 参数注入处理器
2.  API 路由使用 `$asai.$lib.api` 命名空间，WS 路由使用 `$asai.$lib.ws` 命名空间
3.  `lib-install` 中的基础工具会在系统初始化时扩展到 `$asai.$lib` 下
4.  各模块采用 `require.context` 风格的静态导入注册，启动时完成所有路由映射

* * *

## 测试

单元测试目录：`.youmengyu/test/unit/webserver/plugs/asai-nodejs-hostweb/`

```bash
# 仓库根目录
node .youmengyu/test/asaitest.mjs --no-open

# 或单文件
npx tsx --test .youmengyu/test/unit/webserver/plugs/asai-nodejs-hostweb/<file>.test.mjs
```

## 常见问题

### asai-nodejs-hostweb 是什么？

对你说

### 如何安装 asai-nodejs-hostweb？

在项目目录运行 npm install asai-nodejs-hostweb，或使用 pnpm add / yarn add / bun add。

### asai-nodejs-hostweb 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/asai-nodejs-hostweb 是否存在。

### asai-nodejs-hostweb 可以商用吗？

asai-nodejs-hostweb 使用 ISC 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### asai-nodejs-hostweb 还在维护吗？

最新版本 0\.2\.48 发布于 2026/11/03（今天）；至今共发布 59 个版本，其中过去 12 个月发布了 59 个；首次发布于 2025/11/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。