asai-nodejs-hostweb 0.2.14 → 0.2.16

package/README.md

@@ -0,0 +1,795 @@
+# asai-nodejs-hostweb — Web 管理后端插件
+
+## 功能概述
+
+`asai-nodejs-hostweb` 是一个**综合性的 Web 管理后端插件**，为 AsaiWeb 系统提供完整的 RESTful API 服务、系统管理接口和 WebSocket 通信服务。它包含四大模块：
+
+| 模块 | 路径 | 说明 |
+|------|------|------|
+| **API 服务** | `api/` | RESTful 接口层，处理 `/api/*` 请求 |
+| **系统服务** | `sys/` | 系统管理功能，处理 `/sys/*` 请求 |
+| **WebSocket 服务** | `ws/` | WS 通信层，处理实时消息 |
+| **库文件** | `lib-install/` | 基础工具库、加解密、数据库通道 |
+
+---
+
+## 文件结构
+
+```
+asai-nodejs-hostweb/
+├── README.md
+└── asai-nodejs-hostweb/
+    ├── index.ts                              ← 入口文件
+    │
+    ├── api/Index.ts                          ← API 路由注册中心
+    ├── api/init/code.ts                      ← 初始化码生成
+    ├── api/user/userinfo.ts                  ← 用户信息 API（登录验证）
+    ├── api/common/                           ← API 管理模块
+    │   ├── utils/reqWork.ts                  ← 请求工具函数
+    │   ├── dirmanage.ts                      ← 目录管理
+    │   ├── filemanage.ts                     ← 文件管理
+    │   ├── jsonmanage.ts                     ← JSON 管理
+    │   ├── logmanage.ts                      ← 日志管理
+    │   ├── mmmanage.ts                       ← 加密文件管理
+    │   ├── shellmanage.ts                    ← Shell 命令执行
+    │   ├── sqlitemanage.ts                   ← SQLite 数据管理
+    │   └── zipmanage.ts                      ← ZIP 压缩管理
+    ├── api/channel/                          ← 数据通道模块
+    │   ├── channelfileserver.ts              ← 文件通道
+    │   ├── channeljsonserver.ts              ← JSON 通道
+    │   └── channelsqliteserver.ts            ← SQLite 通道
+    │
+    ├── sys/Index.ts                          ← 系统路由注册中心
+    ├── sys/common/                           ← 系统管理功能
+    │   ├── file.ts                           ← 系统文件管理
+    │   ├── json.ts                           ← 系统 JSON 编辑
+    │   ├── upload.ts                         ← 系统文件上传
+    │   ├── update.ts                         ← 系统更新（上传+解压）
+    │   ├── upgrade.ts                        ← 系统升级（部署）
+    │   ├── guard.ts                          ← 守护服务控制台
+    │   ├── info.ts                           ← 系统信息
+    │   ├── shell.ts                          ← 系统 Shell 执行
+    │   └── zip.ts                            ← 系统 ZIP 管理
+    │
+    ├── ws/Index.ts                           ← WS 路由注册中心
+    ├── ws/common/ping.ts                     ← WS 心跳 Ping
+    ├── ws/user/login.ts                      ← WS 用户登录
+    ├── ws/user/exit.ts                       ← WS 用户退出
+    ├── ws/user/online.ts                     ← WS 在线用户列表
+    ├── ws/chat/web.ts                        ← WS Web 聊天
+    │
+    └── lib-install/                          ← 基础库（挂载到 $asai.$lib）
+        ├── Index.ts                          ← 库入口（汇总导出）
+        ├── common/
+        │   ├── As.ts                         ← 通用工具（响应封装、UUID、防抖节流）
+        │   ├── AsAES.ts                      ← AES 加解密
+        │   ├── AsCode.ts                     ← 自定义编码加密
+        │   ├── AsNodeTool.ts                 ← Node 工具（Shell、二进制上传、守护进程）
+        │   ├── AsDb.ts                       ← 数据库服务封装
+        │   ├── AsDbChannelFile.ts            ← 文件通道数据操作
+        │   ├── AsDbPlugs.ts                  ← 数据库插件扩展
+        │   └── AsSys.ts                      ← 系统工具（读写文件、ZIP、关闭服务）
+        └── server/
+            ├── Api.ts                        ← API 请求分发引擎
+            ├── Sys.ts                        ← 系统请求分发引擎
+            ├── Ws.ts                         ← WebSocket 消息分发引擎
+            └── WsClient.ts                   ← WebSocket 客户端
+```
+
+---
+
+## 一、入口文件分析 — `index.ts`
+
+```typescript
+module.exports = {
+    ...require('./lib-install/Index.ts'),  // 基础库
+    api: require('./api/Index.ts'),         // API 路由
+    sys: require('./sys/Index.ts'),         // 系统路由
+    ws: require('./ws/Index.ts'),           // WS 路由
+};
+```
+
+将四大模块合并导出，其中 `lib-install/Index.ts` 的所有导出被展开在顶层。
+
+---
+
+## 二、基础库 (`lib-install/`)
+
+### `lib-install/Index.ts` — 库入口
+
+```typescript
+module.exports = {
+    As: require('./common/As.ts'),
+    AsSys: require('./common/AsSys.ts'),
+    AsNodeTool: require('./common/AsNodeTool.ts'),
+    AsCode: require('./common/AsCode.ts'),
+    AsAES: require('./common/AsAES.ts'),
+    AsDb: require('./common/AsDb.ts'),
+    ServerApi: require('./server/Api.ts'),
+    ServerWs: require('./server/Ws.ts'),
+    ServerSys: require('./server/Sys.ts'),
+    WsClient: require('./server/WsClient.ts'),
+};
+```
+
+---
+
+### `common/As.ts` — 通用工具库
+
+| 函数 | 说明 |
+|------|------|
+| `ctxSuccess(val, opt)` | 成功响应 `{ code: 909, data: val }` |
+| `ctxFail(val)` | 失败响应 `{ code: 907, data: val }` |
+| `ctxEmpty(val)` | 空响应 `{ code: 908, data: val }` |
+| `getPath(str)` | 净化路径（仅保留字母数字和 `./\-_`） |
+| `getName(str)` | 净化文件名（仅保留字母数字和 `.-_`） |
+| `toDirPath(relativePath)` | 相对路径 → 目录路径 |
+| `toAbsolutePath(relativePath)` | 相对路径 → 绝对路径（基于 `cwd()`） |
+| `ensureDir(fs, relativePath)` | 同步创建多层文件夹 |
+| `makeDir(fs, filePaths)` | Promise 版创建文件夹 |
+| `getFilePath(str)` | 获取文件路径（上传专用） |
+| `debounce(fn, opt)` | 防抖 |
+| `throttle(fn, opt)` | 节流 |
+| `Uuid(startsWord, index, hex)` | 生成 12-16 位唯一 ID |
+| `getIp(req)` | 获取请求 IP |
+
+---
+
+### `common/AsAES.ts` — AES 加解密
+
+基于 Node.js `crypto` 模块，使用 `aes-256-gcm` 算法。
+
+| 函数 | 说明 |
+|------|------|
+| `encrypt(plaintext)` | 加密字符串，返回 `{ data, iv, auth }` |
+| `decrypt(encrypto)` | 解密，接收 `{ data, iv, auth }` |
+| `reqAES(opt, fn)` | 请求解密自动处理 |
+| `resAES(data)` | 响应加密自动处理 |
+
+**配置**（`$asai.hostconfig.aes`）：
+| 参数 | 说明 |
+|------|------|
+| `keybase64` | 密钥（Base64 编码） |
+| `aad` | 附加认证数据 |
+| `ivlength` | 初始向量长度（默认16） |
+| `algorithm` | 加密算法（默认 `aes-256-gcm`） |
+| `lv` | 加密等级（>1 时全局启用） |
+
+---
+
+### `common/AsCode.ts` — 自定义编码加密
+
+一种基于字符置换的自编加密算法，用于编码敏感信息（如用户信息、Token）。
+
+| 函数 | 说明 |
+|------|------|
+| `asencode(str, keys)` | 加密字符串，返回值：每 4 字符一组（3 位数据 + 1 位随机） |
+| `asdecode(str, keys)` | 解密字符串 |
+| `getCodeData(data, keys)` | 解码嵌套加密的数据 |
+| `sendCodeData(data, keys, code)` | 编码嵌套数据 |
+| `asnewkey(str)` | 打乱字符串字符顺序（用于生成新密钥） |
+
+---
+
+### `common/AsNodeTool.ts` — Node 工具函数
+
+| 函数 | 说明 |
+|------|------|
+| `upBinary(req)` | 解析 multipart/form-data 上传，提取二进制文件数据。支持进度日志 |
+| `doShell(cmd)` | 执行 Shell 命令（支持中文编码 cp936），超时 600 秒 |
+| `saveData(fs, filePaths, data)` | 保存数据到文件 |
+| `startGuardServer($asai, config, opt)` | 启动守护子进程，支持自动重启（指数退避） |
+
+**`startGuardServer()` 配置**：
+| 参数 | 说明 |
+|------|------|
+| `app` | 子进程入口文件路径 |
+| `ispath` | 是否基于 `__dirname` 解析路径 |
+| `isexe` | 是否可执行文件 |
+| `cfg` | `spawn` 配置参数 |
+| `trymax` | 最大重试次数 |
+| `trytm` | 初始重试延迟(ms) |
+| `tryft` | 重试延迟增长因子 |
+| `maxtm` | 最大重试延迟(ms) |
+| `isoff` | 是否关闭守护 |
+| `log` | 是否输出日志 |
+
+---
+
+### `common/AsDb.ts` — 数据库服务封装
+
+将 HTTP 请求参数转换为 `Idb` 结构并执行数据库操作。
+
+**核心功能**：
+| 函数 | 说明 |
+|------|------|
+| `getSqlParamsByUrl(req, opt)` | 从 URL 和请求体中提取 SQL 参数 |
+| `reqfield(queryData)` | 提取查询字段 |
+| `reqwhere(queryData)` | 构建 WHERE 条件（支持等级、分类、搜索） |
+| `reqorder(queryData)` | 构建 ORDER 排序 |
+| `reqlimit(queryData)` | 构建 LIMIT 限制（支持分页） |
+| `post(req, res, hostdir, opt)` | POST 请求处理 |
+| `get(req, res, hostdir, opt)` | GET 请求处理 |
+| `dbFresh(req, resdb)` | 特殊请求封装（如 selectlist） |
+| `dbCodePm(req, resdb)` | 加密返回数据 |
+
+**URL 路由模式**：
+```
+/api/{table}/{action}/{key}
+```
+- `action` = `insert`, `update`, `delete`, `select`（留空默认 select）
+- `key` 为主键值（指定单条记录）
+
+**自定义处理器**：通过 `cfg.post` 和 `cfg.get` 可扩展自定义逻辑。
+
+---
+
+### `common/AsDbChannelFile.ts` — 文件通道数据操作
+
+用于管理基于文件系统的内容通道数据（分类数据 + 内容文件）：
+
+| 函数 | 说明 |
+|------|------|
+| `getFileList(req, res, hostdir, opt, field, query)` | 获取文件列表（支持搜索、排序、分页） |
+| `editFileData(req, res, hostdir, opt, field, query)` | 编辑文件内容（含分类 JSON 和内容文件） |
+| `delFileData(req, res, hostdir, opt, field, query)` | 删除文件内容 |
+
+**数据存储结构**：
+```
+{dir}/
+├── class/{fl}.json    ← 分类数据（JSON 列表）
+└── file/{sn}.txt      ← 具体内容文件
+```
+
+**缓存机制**：`$asai.channel` 缓存分类列表数据
+
+---
+
+### `common/AsDbPlugs.ts` — 数据库插件扩展
+
+提供基于文件通道的扩展查询功能：
+
+| 函数 | 说明 |
+|------|------|
+| `getFileChannel(req, res, hostdir, opt, field, query)` | 文件通道查询（支持过滤、排序、分页、字段选择） |
+| `getFileList(req, res, hostdir, opt, field, query)` | 文件列表查询（基于分类 JSON） |
+
+---
+
+### `common/AsSys.ts` — 系统工具
+
+| 函数 | 说明 |
+|------|------|
+| `fsReadFile(filePaths, res)` | 读取文件并响应 |
+| `fsWriteFile(filePaths, data, res)` | 写入文件并响应 |
+| `zipWork(workcfg)` | ZIP 压缩解压工作流（支持预清理、文件复制） |
+| `copyFileWork(workcfg)` | 文件复制工作流（支持文件和目录级别的复制） |
+| `closeConnections(servername, callback)` | 优雅关闭服务（WS → HTTP → 回调） |
+
+**`zipWork()` 配置**：
+| 参数 | 说明 |
+|------|------|
+| `type` | `'zip'` 或 `'unzip'` |
+| `zipfile` | ZIP 文件路径 |
+| `zipdir` | 压缩源目录（zip 模式） |
+| `unzipdir` | 解压目标目录（unzip 模式） |
+| `clean` | 是否先清空目标目录 |
+| `files` | 文件复制列表 `[src, dest, type]` |
+| `dirs` | 目录复制列表 |
+
+---
+
+### `server/Api.ts` — API 请求分发引擎
+
+处理所有 `/api/*` 请求的核心路由引擎。
+
+**功能**：
+1. **CORS 处理**：支持跨域白名单和预检请求
+2. **URL 解析**：支持 GET 参数的 `pm` 加密、AES 加密
+3. **POST 处理**：支持普通 JSON、AES 加密、`AsCode` 加密、二进制上传
+4. **路由匹配**：前缀匹配式路由查找
+
+**AES 加密请求处理**：
+- GET：`?aes={data, iv, auth}` 格式
+- POST：`{"aes": 1/2, "data": "...", "iv": "...", "auth": "..."}` 格式
+
+**用户信息处理**：从 `Userinfo` 请求头获取解码后的用户身份，用于数据权限控制。
+
+---
+
+### `server/Sys.ts` — 系统请求分发引擎
+
+处理所有 `/sys/*` 请求的路由引擎。
+
+- 前缀匹配式路由查找
+- 返回 `handler.show()` 处理结果
+
+---
+
+### `server/Ws.ts` — WebSocket 消息分发引擎
+
+处理所有 WebSocket 消息的路由引擎。
+
+**消息解析**：
+1. Buffer → string → JSON parse
+2. 检查 `msg.ty` 前缀匹配路由
+3. 如无匹配，转交 `$asai.asaimock.wsWorkMock()` 处理
+
+**AES 解密**：自动检测 `msg.db.aes` 字段，调用 `aesfns.reqAES()` 解密。
+
+---
+
+### `server/WsClient.ts` — WebSocket 客户端
+
+用于作为客户端连接其他 WebSocket 服务器。
+
+| 函数 | 说明 |
+|------|------|
+| `clientwsInit()` | 初始化 WebSocket 连接 |
+| `clientwsSend(message)` | 发送消息 |
+| `clientwsApi(messageData)` | 发送请求并等待响应（Promise） |
+| `clientwsWatch(messageData, cb)` | 注册监听回调 |
+| `clientwsWatchOff(messageData)` | 取消监听 |
+
+---
+
+## 三、API 管理模块 (`api/common/`)
+
+### `utils/reqWork.ts` — 共享工具函数
+
+为所有管理模块提供统一的请求处理工具：
+
+| 函数 | 说明 |
+|------|------|
+| `getPathFromOpt(opt)` | 从请求选项中提取并解码文件路径 |
+| `sendSuccess(res, data, opt)` | 发送成功响应 |
+| `sendFail(res, err, opt)` | 发送失败响应 |
+| `mnLog(...arg)` | 统一日志输出 |
+
+---
+
+### `dirmanage.ts` — 目录管理
+
+| 路由 | 方法 | 功能 |
+|------|------|------|
+| `/api/asaidir/manage/select/{path}` | GET | 读取目录内容列表 |
+| `/api/asaidir/manage/delete/{path}` | GET | 删除目录 |
+| `/api/asaidir/manage/update/{path}` | POST | 清空目录 |
+
+---
+
+### `filemanage.ts` — 文件管理
+
+| 路由 | 方法 | 功能 |
+|------|------|------|
+| `/api/asaifile/manage/copy/{path}` | POST | 复制文件/目录 |
+| `/api/asaifile/manage/update/{path}` | POST | 更新文件内容 |
+| `/api/asaifile/manage/upbase64/{path}` | POST | Base64 上传文件 |
+| `/api/asaifile/manage/upbinary/{path}` | POST | 二进制上传文件 |
+| `/api/asaifile/manage/upbase64batch/{path}` | POST | 批量 Base64 上传 |
+| `/api/asaifile/manage/upbinarybatch/{path}` | POST | 批量二进制上传 |
+| `/api/asaifile/manage/once/{path}` | GET | 读取文件（带缓存） |
+| `/api/asaifile/manage/select/{path}` | GET | 读取文件 |
+| `/api/asaifile/manage/delete/{path}` | GET | 删除文件 |
+
+---
+
+### `jsonmanage.ts` — JSON 管理
+
+| 路由 | 方法 | 功能 |
+|------|------|------|
+| `/api/asaijson/manage/rankings/{path}` | POST | 排行榜数据更新 |
+| `/api/asaijson/manage/update/{path}` | POST | 更新 JSON 文件 |
+| `/api/asaijson/manage/upbatch/{path}` | POST | 批量更新 JSON |
+| `/api/asaijson/manage/add/{path}` | POST | 追加数据到 JSON |
+| `/api/asaijson/manage/select/{path}` | GET | 读取 JSON 文件 |
+| `/api/asaijson/manage/delete/{path}` | GET | 删除 JSON 文件 |
+
+---
+
+### `logmanage.ts` — 日志管理
+
+| 路由 | 方法 | 功能 |
+|------|------|------|
+| `/api/asailog/manage/addclient/{path}` | POST | 添加客户端日志 |
+| `/api/asailog/manage/add/{path}` | POST | 添加服务器日志 |
+| `/api/asailog/manage/update/{path}` | POST | 更新日志文件 |
+| `/api/asailog/manage/selectlist/{path}` | GET | 列出日志目录 |
+| `/api/asailog/manage/select/{path}` | GET | 读取日志文件 |
+| `/api/asailog/manage/delete/{path}` | GET | 删除日志文件 |
+
+---
+
+### `mmmanage.ts` — 加密文件管理 (`asaimm/manage`)
+
+| 路由 | 方法 | 功能 |
+|------|------|------|
+| `/api/asaimm/manage/update/{path}` | POST | 更新加密文件 |
+| `/api/asaimm/manage/selectlist/{path}` | GET | 读取目录中所有文件（AES 解密后，敏感字段置空） |
+| `/api/asaimm/manage/select/{path}` | GET | 读取单个文件 |
+| `/api/asaimm/manage/delete/{path}` | GET | 删除文件 |
+
+---
+
+### `shellmanage.ts` — Shell 命令管理
+
+| 路由 | 方法 | 功能 |
+|------|------|------|
+| `/api/asaishell/manage/post/{path}` | POST | 执行 Shell 命令 |
+| `/api/asaishell/manage/get/{path}` | GET | 执行 Shell 命令 |
+| `/api/asaishell/manage/gettm/{path}` | GET | 获取当前时间戳 |
+
+---
+
+### `sqlitemanage.ts` — SQLite 数据管理
+
+| 路由 | 方法 | 功能 |
+|------|------|------|
+| `/api/asaisqlite/manage/post` | POST | 自定义处理器 |
+| `/api/asaisqlite/manage/get` | GET | 查询表数据 |
+
+**数据库配置**：`./webdata/webdb/testkdd/sqlite/asaisqlitetest.db`
+
+---
+
+### `zipmanage.ts` — ZIP 压缩管理
+
+| 路由 | 方法 | 功能 |
+|------|------|------|
+| `/api/asaizip/manage/post` | POST | 执行压缩/解压工作 |
+| `/api/asaizip/manage/get` | GET | 执行压缩/解压工作 |
+| `/api/asaizip/manage/zipdir` | GET | 直接压缩目录 |
+
+---
+
+## 四、数据通道 (`api/channel/`)
+
+### `channelfileserver.ts` — 文件通道
+
+提供基于文件系统的内容管理通道：
+
+| 参数 | 默认值 | 说明 |
+|------|--------|------|
+| `model` | `'asai'` | 模型名称 |
+| `channel` | `'asaichannel'` | 通道名称 |
+| `field` | 参考 query | 数据字段 |
+| `path` | — | 自定义存储目录 |
+| `key` | `sn` | 主键字段 |
+| `class` | `class` | 分类字段 |
+
+**数据目录**：`webdata/webdb/channelfile/{model}/channel/{channel}/`
+
+**文件结构**：
+```
+{dir}/
+├── class/{fl}.json    ← 分类索引
+└── file/{sn}.txt      ← 内容
+```
+
+---
+
+### `channeljsonserver.ts` — JSON 通道
+
+基于文件系统的纯 JSON 数据通道：
+
+| 参数 | 说明 |
+|------|------|
+| `as` | 固定为 2（JSON 解析模式） |
+| `type` | `'file'` |
+
+**数据目录**：`webdata/webdb/channeljson/{model}/channel/{channel}/`
+
+---
+
+### `channelsqliteserver.ts` — SQLite 通道
+
+基于 SQLite 的数据通道：
+
+| 参数 | 说明 |
+|------|------|
+| `type` | `'sqlite'` |
+| `field.data` | 默认 `['sn', 'tit', 'class', 'us']` |
+
+**数据库路径**：`./webdata/webdb/channelsqlite/{model}/channel/{channel}/sqlite.db`
+
+---
+
+## 五、API 基础服务 (`api/`)
+
+### `api/init/code.ts` — 初始化码
+
+| 路由 | 方法 | 功能 |
+|------|------|------|
+| `/api/init/code` | GET/POST | 返回初始化加密码（基于 `asaisn` 序列号） |
+
+---
+
+### `api/user/userinfo.ts` — 用户信息
+
+基于 `AsDb` 封装，提供用户数据管理：
+
+| 配置项 | 说明 |
+|--------|------|
+| 存储类型 | 默认 `file`（JSON 文件） |
+| 存储目录 | `webdata/webdbuser/` |
+| 数据字段 | `['us', 'pw', 'lv']`（用户名、密码、等级） |
+| 主键 | `us`（用户名） |
+
+---
+
+## 六、系统管理 (`sys/`)
+
+所有系统管理接口均需在 URL 中传递密码：`/sys/{name}/submit/{password}/...`
+
+### `sys/common/file.ts` — 系统文件管理
+
+| 路由 | 功能 |
+|------|------|
+| `/sys/file/delete/{pwd}/?fpath=` | 删除文件 |
+| `/sys/file/manage/{pwd}/?fpath=` | 读取目录内容 |
+| `/sys/file/submit/{pwd}/?fpath=` | 读取/写入文件 |
+
+### `sys/common/json.ts` — 系统 JSON 编辑
+
+| 路由 | 功能 |
+|------|------|
+| `/sys/json/submit/{pwd}/?fpath=` | 读取/写入 JSON 文件，自动格式化 |
+
+### `sys/common/upload.ts` — 系统文件上传
+
+| 路由 | 功能 |
+|------|------|
+| `/sys/upload/submit/{pwd}/?uppath=` | 上传二进制文件到指定路径 |
+
+### `sys/common/update.ts` — 系统更新
+
+| 路由 | 功能 |
+|------|------|
+| `/sys/update/submit/{pwd}/?unzippath=` | 上传 ZIP 包并解压到指定目录 |
+
+### `sys/common/upgrade.ts` — 系统升级
+
+| 路由 | 功能 |
+|------|------|
+| `/sys/upgrade/msg` | 获取升级日志 |
+| `/sys/upgrade/submit/{pwd}/work` | 提交升级配置并执行部署 |
+| `/sys/upgrade/submit/{pwd}/upload` | 上传升级包 ZIP |
+
+**升级流程**：上传 ZIP → 解压到 `webdata/upload/upgrade/` → 读取 `config.json` → 执行文件复制部署
+
+### `sys/common/guard.ts` — 守护服务
+
+| 路由 | 功能 |
+|------|------|
+| `/sys/guard/msg` | 获取守护进程日志 |
+| `/sys/guard/login/{pwd}` | 登录验证 |
+| `/sys/guard/work/{pwd}/?fpath=` | 读取/写入守护配置 |
+| `/sys/guard/submit/{pwd}/?pm=` | 重启/关闭指定站点 |
+
+### `sys/common/info.ts` — 系统信息
+
+| 路由 | 功能 |
+|------|------|
+| `/sys/info/map` | 获取系统服务映射 |
+| `/sys/info/submit/{pwd}` | 获取系统性能信息（带密码：详细性能数据；无密码：基本系统信息） |
+
+**返回数据**包括：CPU 使用率、内存占用、堆内存、系统负载、进程信息、网络接口等。
+
+### `sys/common/shell.ts` — 系统 Shell
+
+| 路由 | 功能 |
+|------|------|
+| `/sys/shell/submit/{pwd}/?cmd=` | 执行 Shell 命令 |
+
+### `sys/common/zip.ts` — 系统 ZIP 管理
+
+| 路由 | 功能 |
+|------|------|
+| `/sys/zip/msg` | 获取 ZIP 操作日志 |
+| `/sys/zip/submit/{pwd}/?fpath=` | 读取/写入 ZIP 配置并执行压缩 |
+
+---
+
+## 七、WebSocket 服务 (`ws/`)
+
+### `ws/common/ping.ts` — 心跳检测
+
+| 消息类型 | 响应 |
+|----------|------|
+| `ping` | 返回 `pong` |
+
+### `ws/user/login.ts` — WebSocket 登录
+
+验证用户身份并同步连接状态，处理同一账号多端登录的踢下线逻辑。
+
+### `ws/user/exit.ts` — WebSocket 退出
+
+| 消息类型 | 行为 |
+|----------|------|
+| `user/exit` | 返回空数据确认退出 |
+
+### `ws/user/online.ts` — 在线用户列表
+
+| 消息类型 | 响应 |
+|----------|------|
+| `user/online` | 返回所有在线用户名列表 |
+
+### `ws/chat/web.ts` — Web 聊天
+
+| 消息类型 | 说明 |
+|----------|------|
+| `chat/web/send` | 进入消息广播模式，收集消息后节流广播 |
+| `chat/web/broadcast` | 自动发送的广播消息 |
+
+**支持房间功能**：通过 `msgdata.db.room` 指定聊天室。
+
+---
+
+## 配置参考
+
+### API 服务配置 (`$asai.hostconfig`)
+
+```javascript
+{
+    // API 安全
+    password: 'admin123',     // 系统管理密码
+    asaisn: 'SN-2024-001',   // 序列号（用于加解密）
+    oncors: true,            // 是否启用严格 CORS 校验
+    website: {
+        title: 'AsaiWeb',
+        ver: '1.0.0'
+    },
+    
+    // ZIP 配置
+    zip: {
+        zipFileNameEncoding: 'gbk'
+    }
+}
+```
+
+### 响应格式
+
+所有 API 响应均为 JSON 格式：
+```javascript
+{ code: 909, data: ... }   // 成功
+{ code: 907, data: ... }   // 失败
+{ code: 908, data: ... }   // 空
+```
+
+---
+
+## 使用示例
+
+### API 请求示例
+
+```bash
+# 初始化码
+GET /api/init/code
+→ {"code": 909, "data": ["abc123", "加密后的初始化码"]}
+
+# 读取 JSON 文件
+GET /api/asaijson/manage/select/webdata/config/setting.json
+→ {"code": 909, "data": {...}}
+
+# 更新文件（POST）
+POST /api/asaifile/manage/update/webdata/config/setting.json
+Body: {"key": "value"}
+
+# 目录管理
+GET /api/asaidir/manage/select/webdata/config/
+→ {"code": 909, "data": { "name": "config", "children": [...] }}
+
+# 执行 Shell 命令
+POST /api/asaishell/manage/post/
+Body: {"cmd": "node -v"}
+→ {"code": 909, "data": "v18.12.0\n"}
+```
+
+---
+
+## 注意事项
+
+1. 所有 `/sys/*` 路由需要在 URL 中明文传递系统密码，建议在生产环境限制访问
+2. `AsCode` 加密算法为自己的实现，非标准加密算法
+3. WS 消息的 `ty` 字段是路由匹配的关键字
+4. 数据通道（Channel）的 `as=2` 模式将数据作为 JSON 解析
+5. `mmmanage` 返回数据时敏感字段（`pw`、`mm`）会被自动置空
+
+---
+
+## 代码分析与优化建议
+
+### 一、安全相关问题 🔴
+
+#### 1. 系统密码明文传输 🔴 严重
+
+**当前问题**：所有 `/sys/*` 路由的密码通过 URL 明文传递，如 `/sys/file/delete/{password}/?fpath=...`。密码会记录在服务器日志、浏览器历史、反向代理日志中。
+
+**建议方案**：
+- 改用请求头传递密码（如 `Authorization: Bearer {token}`）
+- 或使用 `POST` + 请求体传递密码
+- 增加 Session/Token 机制，一次认证多次使用
+
+**优化收益**：消除密码泄露风险。
+
+---
+
+#### 2. AsCode 加密是自定义算法，非标准加密 🔴 严重
+
+**当前问题**：`AsCode.ts` 实现的 `asencode/asdecode` 是自研的字符置换算法，没有经过密码学安全性验证，存在可预测风险。
+
+**建议**：
+- 传输层敏感数据（如 Token）应使用标准 AES（`AsAES.ts` 已实现）
+- `AsCode` 仅作为数据混淆使用（如隐藏 URL 参数），不做安全加密
+- 在文档中明确标注 `AsCode` 不是安全加密算法
+
+---
+
+#### 3. 路径遍历攻击风险 🟡 中
+
+**当前问题**：多个 API 和系统接口直接拼接用户输入的 `fpath` 参数到文件路径中，未做充分的路径白名单校验。
+
+**建议**：增加路径白名单校验：
+```typescript
+function sanitizePath(inputPath: string, allowedBase: string): string {
+    const resolved = path.resolve(allowedBase, inputPath);
+    if (!resolved.startsWith(path.resolve(allowedBase))) {
+        throw new Error('Path traversal detected');
+    }
+    return resolved;
+}
+```
+
+---
+
+### ✅ 已优化项目
+
+#### 9. CPU 百分比计算不准确（info.ts）✅
+
+**优化内容**：`getSystemPerformance()` 中 CPU 百分比计算增加 `os.cpus().length` 核心数校准，使用更准确的分母。
+
+```typescript
+// 优化前：
+((cpuUsage.user + cpuUsage.system) / (1000 * 1000 * os.uptime()) * 100).toFixed(2)
+// 优化后（增加核心数校准）：
+((cpuUsage.user + cpuUsage.system) / (1000 * 1000 * os.uptime() * os.cpus().length) * 100).toFixed(2)
+```
+
+---
+
+#### 10. `AsNodeTool.doShell()` 动态选择编码 ✅
+
+**优化内容**：根据平台动态选择编码（Windows `cp936` / Linux `utf-8`），使用 `encoding: 'buffer'` 替代已废弃的 `'binary'` 编码。
+
+```typescript
+// 优化后：
+const encoding = process.platform === 'win32' ? 'cp936' : 'utf-8';
+exec(cmd, { encoding: 'buffer', timeout: 600000 }, (error, stdout, stderr) => {
+    if (error) reject(error);
+    resolve(iconv.decode(stdout, encoding));
+});
+```
+
+---
+
+### 待优化项目
+
+| 优先级 | 问题 | 影响 |
+|--------|------|------|
+| 🔴 P0 | 密码明文传输、AsCode 安全、路径遍历 | 严重安全风险 |
+| 🟡 P1 | 路由匹配、通道缓存、频率限制 | 功能健壮性 |
+| 🟢 P2 | 聊天室限制 | 准确性/安全性 |
+
+---
+
+### 八、全插件通用优化建议
+
+以下优化建议适用于本插件乃至整个 `plugs` 目录下的所有插件：
+
+| 改进项 | 说明 | 工作量 |
+|--------|------|--------|
+| **TypeScript 严格模式** | 所有文件从 `any` 改为精确类型 | 大 |
+| **统一错误处理中间件** | 统一 `ctxSuccess`/`ctxFail` 风格，增加错误码枚举 | 中 |
+| **日志可追踪 ID** | 每次请求生成 `traceId`，贯穿所有日志 | 中 |
+| **配置式路由** | 用声明式路由表替代 `if/else` 链 | 中 |
+| **单元测试覆盖** | 为核心模块（Sql.ts、As.ts、Api.ts）增加 Jest 测试 | 大 |