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

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 — 基础库工具

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

2. api — API 接口层

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

3. sys — 系统管理

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

4. ws — WebSocket 服务

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

使用示例

// 在 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）；以下为插件内路径与响应安全要点：

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/

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

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