asai-nodejs-host 0.2.31 → 0.2.33

package/README.md

@@ -2,435 +2,380 @@
 
 ## 功能概述
 
-`asai-nodejs-host` 是整个系统的**核心服务器引擎**，负责创建和管理 **HTTP 服务器**、**HTTPS 服务器**、**代理服务器**和 **WebSocket 服务器**。它基于 Node.js 原生 `http`/`https` 模块和 `ws` 库构建。
-
-支持特性：
-- 多站点并行托管（通过 `hostdir` 区分）
-- HTTP/HTTPS 双模式
-- URL Rewrite / Fallback 机制（SPA 支持）
-- 反向代理服务（Proxy）
-- WebSocket 服务（支持用户鉴权、连接管理）
-- CORS 跨域支持
-- 连接数监控与限流
-- 优雅关闭
+`asai-nodejs-host` 是系统的**核心服务器引擎**，基于 Node.js 原生 `http`/`https` 与 `ws` 库，负责：
+
+- 多站点 HTTP/HTTPS 并行托管（`hosts`）
+- 反向代理（`proxyhosts`）
+- WebSocket 服务（鉴权、在线数限制、广播）
+- 静态资源服务（SPA fallback、ETag、LRU 缓存）
+- 日志、进程守护、传输层桥接（TCP/gRPC/RS485）
+
+配置文件路径：`webserver/websys/sys/asaihost.json`（运行时挂载为 `$asai.hostconfig`）。
 
 ---
 
-## 文件结构
+## 目录结构
 
 ```
 asai-nodejs-host/
-├── README.md
-├── AsaiHost.ts           ← 入口文件
+├── AsaiHost.ts              ← npm/插件入口（fn + AsaiCommon + AsaiUtils + HostApi）
 └── src/
-    ├── index.ts           ← 核心逻辑：主机初始化、服务器启动
-    ├── types.ts           ← 类型定义
-    ├── core.ts            ← 工具函数（IP 获取、配置合并等）
-    ├── http-server.ts     ← HTTP/HTTPS 服务器实现
-    ├── ws-server.ts       ← WebSocket 服务器实现
-    ├── proxy-server.ts    ← 反向代理服务器实现
-    ├── logger.ts          ← 日志系统（带缓冲区、按日轮转）
-    ├── process.ts         ← 进程管理（异常处理、优雅关闭）
-    └── utils.ts           ← 工具函数（用户信息编解码）
+    ├── index.ts             ← 插件工厂：注册 workHandlers、StartAsaiHost
+    ├── types.ts             ← TypeScript 类型
+    ├── host-api.ts          ← 对外公开 API（禁止 deep import src/ 内部）
+    │
+    ├── core/                ← 启动与配置
+    │   ├── init.ts          ← initAsaiHost（IP/日志/进程/AES/注册表）
+    │   ├── host-config.ts   ← getHostCFG / getProxyHostCFG / validateHostdir
+    │   ├── network.ts       ← getIp / getHostIP
+    │   ├── time.ts          ← getNowTime
+    │   └── index.ts
+    │
+    ├── http/                ← HTTP 层
+    │   ├── server.ts        ← 路由编排、启动、asai 守护
+    │   ├── security.ts      ← 安全响应头、Userinfo 解析
+    │   ├── log.ts           ← 请求日志过滤（skip / sample）
+    │   ├── static.ts        ← 静态查找、ETag、SPA fallback
+    │   ├── connection.ts    ← 连接数监控与限流
+    │   └── static-path-cache.ts
+    │
+    ├── ws/                  ← WebSocket 层
+    │   ├── server.ts        ← WSS 创建与 connection 分发
+    │   ├── auth.ts          ← 鉴权、登录态、踢下线
+    │   ├── message.ts       ← 消息序列化、sendws/broadws
+    │   └── route-index.ts   ← WS 路由前缀索引
+    │
+    ├── proxy/
+    │   └── server.ts        ← 反向代理
+    │
+    ├── config/
+    │   ├── syscom.ts        ← syscom 传输配置读取与归一化
+    │   └── validate.ts      ← asaihost.json 启动校验
+    │
+    ├── infra/               ← 基础设施
+    │   ├── logger.ts        ← 缓冲日志、按日轮转
+    │   ├── process.ts       ← 异常捕获、优雅关闭
+    │   ├── registry.ts      ← API/WS 路由注册
+    │   ├── transport-bridge.ts
+    │   ├── safe-path.ts     ← 路径白名单校验
+    │   └── secure-compare.ts
+    │
+    ├── utils/
+    │   ├── userinfo.ts      ← Userinfo AES 解密
+    │   ├── ws-mock.ts       ← WS Mock 工具
+    │   └── index.ts
+    │
+    └── common/              ← 路由处理器基类（Api / Sys / Ws / WsClient）
+        └── server/
 ```
 
----
-
-## 入口文件 — `AsaiHost.ts`
-
-```typescript
-module.exports = ($asai: any, opt: any) => {
-    const { StartAsaiHost, asaiWs } = AsaiHost($asai, opt);
-    return { StartAsaiHost, asaiWs };
-};
-```
-
-**返回值**：
-| 名称 | 类型 | 说明 |
-|------|------|------|
-| `StartAsaiHost` | function | 启动所有 HTTP/HTTPS/WebSocket 服务器 |
-| `asaiWs` | object | `ws` 模块引用 |
+> 源码仅保留 TypeScript（`tsx` 直接运行）；`syscom-config.ts` 为对外 API 兼容入口，指向 `config/syscom.ts`。
 
 ---
 
-## 核心模块分析
+## asaihost.json 完整配置说明
 
-### `src/index.ts` — 主机初始化入口
+配置加载后赋值给 `$asai.hostconfig`。各站点实际生效配置 = `hosts.default` 与 `hosts.<站点名>` 浅合并；代理同理 = `proxyhosts.default` + `proxyhosts.<代理名>`。
 
-**功能**：
-1. 将 `opt` 中的处理器（`sysWork`, `apiWork`, `wsWork`, `jsonpWork`）挂载到 `global`
-2. 提供 `StartAsaiHost()` 函数
+### 顶层字段
 
-**`StartAsaiHost()` 启动流程**：
-1. 调用 `initAsaiHost()` 初始化核心环境
-2. 遍历 `$asai.hostconfig.hosts` → 启动 HTTP 服务器
-3. 遍历 `$asai.hostconfig.proxyhosts` → 启动代理服务器
+| 字段 | 类型 | 示例 | 说明 | 读取模块 |
+|------|------|------|------|----------|
+| `website.title` | string | `"WEB"` | 日志文件头 Software 名称 | `infra/logger` |
+| `website.ver` | string | `"1.0.0.0"` | 日志文件头 Version | `infra/logger` |
+| `password` | string | `"asai"` | 系统密码（**必填**，启动校验） | `config/validate` |
+| `ip` | string | `"asai"` | 全局绑定 IP；`"asai"`=自动探测本机 IPv4 并 localhost 监听 | `core/network` |
+| `index` | string | `"index.html"` | 默认首页文件名 | `http/server` |
+| `asaisn` | string | — | Userinfo 解密盐（AsCode.asdecode） | `utils/userinfo` |
+| `wssec` | string[] | `["asai","","-"]` | WS 安全相关（业务层使用） | hostweb |
+| `pkg.type` | number | `1` | 打包模式标识 | 业务层 |
 
----
+### `tm` — 定时器
 
-### `src/types.ts` — 类型定义
+| 字段 | 默认 | 说明 |
+|------|------|------|
+| `tm.c` | — | 通用定时（ms） |
+| `tm.d` | `2000` | asai 守护重启延迟 / WS 踢下线探测超时 |
+| `tm.maxtry` | `100` | 进程异常重启上限窗口内次数 |
+| `tm.restartwindow` | `60000` | 异常重启统计窗口（ms） |
 
-```typescript
-type WorkHandler = (req: any, res: any, hostdir: string) => void;
-type WsWorkHandler = (msg: any, ws: any, hostdir: string, req: any) => void;
+### `path` — 路径
 
-interface AsaiHostOptions {
-    sysWork: WorkHandler;    // /sys/* 路由处理器
-    apiWork: WorkHandler;    // /api/* 路由处理器
-    wsWork: WsWorkHandler;   // WebSocket 消息处理器
-    jsonpWork: WorkHandler;  // /jsonp/* 路由处理器
-}
-```
-
----
+| 字段 | 说明 |
+|------|------|
+| `path.mock` | Mock 数据目录 |
+| `path.ip` | IP 相关资源目录 |
 
-### `src/core.ts` — 核心工具函数
+### `zip`
 
-| 函数 | 说明 |
+| 字段 | 说明 |
 |------|------|
-| `getIp()` | 获取本机非 127.0.0.1 的第一个 IPv4 地址 |
-| `getNowTime(type, date)` | 格式化时间，支持 6 种格式 |
-| `validateHostdir(hostdir)` | 验证主机目录名是否合法（字母数字下划线中划线） |
-| `getHostIP(ip, $asai)` | 获取主机 IP |
-| `getHostCFG(hostdir, $asai)` | 合并 host 配置（默认配置 + 站点配置） |
-| `getProxyHostCFG(proxyhostdir, $asai)` | 合并代理配置 |
-| `initAsaiHost($asai, opt)` | 初始化：挂载方法、设置端口、初始化进程/日志、配置 AES |
-
----
+| `zip.zipFileNameEncoding` | 解压文件名编码，如 `"gbk"` |
 
-### `src/logger.ts` — 日志系统
+### `logger` — 日志
 
-**类：`LogBuffer`**
-- 带缓冲区的异步写入，支持按缓冲区大小或定时刷新
-- `flushInterval`: 100ms
-- `maxBufferSize`: 100 条
-- 使用 `$asai.asaifs.append()` 异步写入
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `logger.lv.view` | number/bool | `2` | 控制台输出；truthy 时 WS message 也写日志 |
+| `logger.lv.record` | number/bool | `1` | 是否写入日志文件 |
+| `logger.path.server` | string | `"./webdata/.../server/"` | 服务端日志目录 |
+| `logger.path.client` | string | — | 客户端日志目录 |
+| `logger.path.maxsize` | number | `1048576` | 单文件上限（字节），超出自动轮转 |
+| `logger.sample` | object | `{ "API": 0.15 }` | 按日志类型采样率 0~1，降低高 QPS 写盘 |
+| `logger.skip` | string[] | `["/sys/info/metrics"]` | 静默路径；精确匹配或 `*` 前缀通配 |
 
-**函数**：
+### `guard` — 进程守护（业务层 hostweb）
 
-| 函数 | 说明 |
+| 字段 | 说明 |
 |------|------|
-| `setAppend($asai, src, logstr)` | 追加日志（自动检查文件大小，超 1MB 自动轮转） |
-| `setLog($asai, src, logstr)` | 同步写入日志 |
-| `initLog($asai)` | 初始化日志系统：设置 `$asai.$log` 函数 |
+| `guard.config` | guard.json 路径 |
+| `guard.autoStartOnRestart` | 重启后自动拉起子进程 |
+| `guard.default.*` | 子进程默认参数（app/ispath/trymax/cfg 等） |
 
-**日志配置**（`$asai.hostconfig.logger`）：
-```javascript
-{
-    lv: {
-        view: true,     // 是否在控制台显示
-        record: true    // 是否记录到文件
-    },
-    path: {
-        client: './logs/client/',  // 客户端日志目录
-        server: './logs/server/',  // 服务器日志目录
-        maxsize: 1048576           // 单个日志文件最大字节
-    }
-}
-```
+### `aes` — 加密
 
-**日志类型**：
-- 参数 `0` 或不传：服务器日志（自动添加时间戳）
-- 参数 `1`：客户端日志（独立格式）
-- 参数 `> 666`：静默日志（仅记录，控制台不显示）
+| 字段 | 说明 |
+|------|------|
+| `aes.lv` | 加密等级；`>1` 时 API/WS 全量 AES |
+| `aes.keybase64` | AES 密钥（Base64） |
+| `aes.aad` | 附加认证数据 |
+| `aes.keylength` | 密钥长度（bit） |
+| `aes.ivlength` | IV 长度 |
+| `aes.algorithm` | 如 `"aes-256-gcm"` |
 
----
+启动时若 `aes.lv` 有效且存在 `AsAES`，挂载 `$asai.$lib.aesfns`。
 
-### `src/process.ts` — 进程管理
+### `httpscert` — 全局 HTTPS 证书
 
-| 事件 | 处理方式 |
-|------|----------|
-| `unhandledRejection` | 记录未处理的 Promise 拒绝，含调用堆栈 |
-| `uncaughtException` | 记录未捕获异常，60 秒内最多 10 次自动重启，超出则退出 |
-| `SIGTERM` / `SIGINT` | 优雅关闭所有 HTTP/WS 服务器，超时 60 秒强制退出 |
+| 字段 | 说明 |
+|------|------|
+| `httpscert.key` | PEM 私钥（字符串或 Buffer） |
+| `httpscert.cert` | PEM 证书 |
 
-**`gracefulShutdown($asai)` 关闭顺序**：
-1. 关闭所有 HTTP 服务器
-2. 关闭所有 WebSocket 服务器
-3. 清除守护定时器
-4. 清除 WS 心跳监控
-5. 3 秒后退出进程
+站点 `httptype` 为 `https://` 时，优先用站点级 `httpscert`，否则回退全局。
 
----
+### `mimetypes` — 全局 MIME
 
-### `src/http-server.ts` — HTTP/HTTPS 服务器
+扩展名 → Content-Type 映射。站点可覆盖：`hosts.<name>.mimetypes` 与全局合并。
 
-**核心函数**：
+### `hosts` — HTTP/WS 站点
 
-#### `getHTTPServer(httptype, cfg, $asai)`
-根据协议类型返回 `http` 或 `https` 模块，并注入 `AsCreateServer` 方法。
+#### `hosts.default`（模板，不单独启动）
 
-#### `startHTTPServer($asai, hostdir)`
-启动一个站点的 HTTP/HTTPS 服务器。
+| 字段 | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| `close` | 0/1 | `0` | `1` 跳过启动 |
+| `port` | number | `9198` | 监听端口 |
+| `httptype` | string | `"http://"` | `"http://"` 或 `"https://"` |
+| `wstype` | string | `"ws://"` | 控制台 WS 地址展示 |
+| `ip` | string | — | 站点级绑定 IP，覆盖全局 |
+| `ws` | 0/1 | — | 是否挂载 WebSocket |
+| `ckhttp` | 0/1 | `0` | 启用 HTTP 连接数监控与限流 |
+| `ckws` | 0/1 | `0` | 启用 WS 用户鉴权与在线表 |
+| `maxhttp` | number | `100` | HTTP 最大并发连接 |
+| `maxws` | number | `100` | WS 最大连接数（ckws 模式下按已登录用户计） |
+| `maxonline` | number | `100` | 最大在线用户数（ckws） |
+| `oncors` | 0/1 | `0` | API CORS 严格模式（0=*，1=校验 cors 列表） |
+| `cors` | string[] | `[]` | 允许的 Origin 列表 |
+| `hostdirs` | string[] | — | 静态文件查找目录（按序） |
+| `mimetypes` | object | — | 站点级 MIME 覆盖 |
 
-**路由规则**：
-| URL 前缀 | 处理器 |
-|----------|--------|
-| `/sys/*` | `sysWork()` |
-| `/api/*` | `apiWork()` |
-| `/jsonp/*` | `jsonpWork()` |
-| 其他 | 静态文件服务 |
+#### `hosts.<站点名>.weburls` — SPA 路由
 
-**静态文件服务特性**：
-- URL Rewrite 支持 — 如果配置了 `weburls.rewrite` 和 `keys`，匹配的 URL 重写回首页（SPA 支持）
-- 多目录查找 — 依次在 `hostdirs` 配置的目录中查找文件
-- 目录遍历防护 — 拒绝包含 `..` 的路径
-- MIME 类型自定义 — 通过 `mimetypes` 配置
-- 文件流缓存 — `Cache-Control: public, max-age=3600`
+| 字段 | 说明 |
+|------|------|
+| `weburls.rewrite` | `true` 启用 SPA fallback |
+| `weburls.webdir` | 前端构建目录（如 `"webclient"`） |
+| `weburls.keys` | URL 前缀列表，匹配则返回 `index.html` |
 
-**连接管理**：
-- 通过 `ckhttp` 和 `maxhttp` 配置连接数限制
-- 当连接数达到 `80%` 时记录警告
-- 当达到 `95%` 时强制清理空闲超过 5 分钟的连接
-- 每 30 分钟检查一次
+**静态查找顺序**：`hostdirs` 各目录 → 未命中且启用 rewrite → fallback 到 `webdir/index.html`。
 
-#### `asaiGuard($asai)`
-守护机制 — 当 `asai` 端口被占用时退出进程；否则延迟 2 秒重新启动。
+#### 特殊站点名
 
-#### `checkHttpHeader(req, $asai)`
-检查 HTTP 请求头中的用户信息并解码。
+| 名称 | 行为 |
+|------|------|
+| `default` | 仅作默认模板，**不启动** |
+| `asai` | 内置守护站点；端口冲突时进程退出或延迟重启 |
+| 其它 | 须匹配 `^[a-zA-Z0-9_-]+$` 且长度 ≤100 |
+
+#### 示例（节选）
+
+```json
+"estunweb": {
+  "ckhttp": 1,
+  "ckws": 1,
+  "ws": 1,
+  "maxhttp": 1000,
+  "maxws": 200,
+  "maxonline": 10,
+  "weburls": {
+    "rewrite": true,
+    "webdir": "webclient",
+    "keys": ["/cocontrol", "/couser"]
+  },
+  "hostdirs": ["home", "websys/webpage", "webdata/upload"]
+}
+```
 
----
+### `proxyhosts` — 反向代理
 
-### `src/ws-server.ts` — WebSocket 服务器
+#### `proxyhosts.default`
 
-**核心函数**：
+| 字段 | 默认 | 说明 |
+|------|------|------|
+| `proxyhttptype` | `"http://"` | 代理监听协议 |
+| `proxyport` | — | 代理监听端口 |
+| `httptype` | `"http://"` | 目标协议（用于自动拼 url） |
+| `port` | — | 目标端口 |
+| `redirect` | `false` | `true` 时 301 重定向而非转发 |
+| `maxSockets` | `2000` | Agent 最大 socket |
+| `maxFreeSockets` | `200` | 空闲 socket 池上限 |
+| `keepAlive` | `true` | HTTP Agent keepAlive |
+| `timeout` | `60000` | 请求超时（ms） |
+| `keepAliveMsecs` | `30000` | keepAlive 间隔 |
+| `rejectUnauthorized` | `false` | HTTPS 目标自签名证书 |
+| `passUserInfo` | `false` | 是否向目标转发 `Userinfo` 头 |
+
+#### `proxyhosts.<代理名>`
+
+| 字段 | 说明 |
+|------|------|
+| `url` | 目标完整 URL；空则按 `httptype`+`ip`+`port` 自动拼接 |
+| `proxyip` | 代理绑定 IP |
+| `proxyport` | 代理端口 |
+| `proxyhttptype` | 代理 HTTPS 时用 `"https://"` |
 
-#### `createWSHost($asai, hostdir)`
-为指定 hostdir 创建 WebSocket 服务（附加到已有的 HTTP 服务器）。
+### `syscom` — 传输层默认连接（TCP / gRPC / RS485）
 
-**`wss.sendws(msg, type, curws)` — 发送消息**：
-| type | 行为 |
-|------|------|
-| 0 | 仅发送给当前连接 |
-| 1 | 发送给除当前连接外的所有人 |
-| 2 | 发送给所有人（广播） |
+推荐结构：`syscom.{tcp|grpc|rs485}.default`。启动时 `normalizeHostConfig` 会合并到顶层同名键，并兼容 legacy 键 `1tcp`/`serial485` 等。
 
-**`wss.broadws(msg)` — 广播消息**：发送给所有连接。
+#### 通用 `default` 字段
 
-**WebSocket 连接鉴权**：
-1. 从 `Sec-WebSocket-Protocol` 请求头获取用户信息
-2. 调用 `deUserInfoWithAsai()` 解码用户信息（AES 解码）
-3. 如果启用了鉴权（`hostcfg.ckws`），执行 `isOkWs()`
+| 字段 | 说明 |
+|------|------|
+| `id` | 连接 ID（如 `testtcp`） |
+| `label` | 显示名称 |
+| `autoConnect` | 启动时自动连接（默认 true，显式 `false` 关闭） |
+| `reconnect.enabled` | 是否自动重连 |
+| `reconnect.maxRetries` | 最大重试次数（默认 60 或 `tm.maxtry`） |
+| `reconnect.initialDelay` | 首次重连延迟（ms） |
+| `reconnect.maxDelay` | 最大重连间隔（ms） |
+| `reconnect.factor` | 退避倍数 |
+
+#### TCP `default`
+
+| 字段 | 说明 |
+|------|------|
+| `host` | 目标主机 |
+| `port` | 目标端口 |
 
-**`isOkWs()` 鉴权检查**：
-1. 用户名是否存在
-2. 同一用户名是否已登录（踢下线旧连接或阻止新连接）
-3. 同一 Token 是否已登录
-4. 在线人数是否达到上限（`maxonline`）
+#### gRPC `default`
 
-**连接数控制**：
-- 通过 `maxws` 配置限制 WS 连接数（默认 100）
-- 超过限制时发送错误消息并关闭连接（1013 状态码）
+同 TCP：`host` + `port`（如 `50051`）。
 
----
+#### RS485 `default`
 
-### `src/proxy-server.ts` — 反向代理服务器
-
-**函数**：`startProxyServer($asai, proxyhostdir)`
-
-**代理配置**（`$asai.hostconfig.proxyhosts`）：
-| 参数 | 默认值 | 说明 |
-|------|--------|------|
-| `url` | — | 目标服务器 URL |
-| `httptype` | `http://` | 代理协议类型 |
-| `port` | — | 代理端口 |
-| `proxyhttptype` | — | 代理服务器自身协议类型 |
-| `proxyport` | — | 代理服务器端口 |
-| `redirect` | false | 设为 true 时做 301 重定向而非代理 |
-| `keepAlive` | true | 是否保持连接 |
-| `timeout` | 60000 | 请求超时(ms) |
-| `maxSockets` | 1000 | 最大 socket 数 |
-
-**特性**：
-- 支持 HTTP→HTTPS、HTTPS→HTTP、HTTPS→HTTPS 代理
-- 请求头过滤（去掉 transfer-encoding、connection 等转发无关头）
-- 错误处理：502 Bad Gateway、504 Gateway Timeout
-- 用户信息透传（在 `Userinfo` 头中传递）
+| 字段 | 说明 |
+|------|------|
+| `path` | 串口路径（Windows `COM3`，Linux `/dev/ttyUSB0`） |
+| `baudRate` | 波特率 |
+| `dataBits` / `stopBits` / `parity` | 串口参数 |
 
 ---
 
-### `src/utils.ts` — 工具函数
+## 请求路由
 
-| 函数 | 说明 |
-|------|------|
-| `deUserInfoWithAsai(userinfo, $asai)` | 解码加密后的用户信息（用户名、等级、token） |
-| `deUserInfo(userinfo)` | 旧版兼容函数（不处理解码） |
+| URL 前缀 | 处理器 | 注册来源 |
+|----------|--------|----------|
+| `/sys/*` | `sysWork` | hostweb 注入 |
+| `/api/*` | `apiWork` | hostweb 注入 |
+| `/jsonp/*` | `jsonpWork` | hostweb 注入 |
+| 其它 | 静态文件 | `http/static` |
 
-**用户信息编码格式**：
-```
-[decode(用户名, token), decode(等级, token), token本身]
-```
-使用 `$asai.$lib.AsCode.asdecode()` 进行解码。
+WebSocket 消息 → `wsWork`（hostweb 注入）。
 
 ---
 
-## 配置参考
-
-### `hostconfig` 结构
-
-```javascript
-{
-    ip: '0.0.0.0',              // 绑定 IP
-    index: 'index.html',        // 默认首页文件
-    mimetypes: { '.html': 'text/html' }, // 自定义 MIME 类型
-    tm: { c: 2000, d: 3000 },   // 定时器配置
-    aes: {                       // AES 加密配置
-        lv: 0,                   // 加密等级
-        keybase64: '...',        // 密钥（Base64）
-        aad: '...',              // 附加认证数据
-        ivlength: 16,            // IV 长度
-        algorithm: 'aes-256-gcm' // 加密算法
-    },
-    logger: {
-        lv: { view: true, record: true },
-        path: { client: './logs/', server: './logs/', maxsize: 1048576 }
-    },
-    
-    // 站点配置
-    hosts: {
-        default: {               // 默认配置
-            httptype: 'http://',
-            port: 80,
-            hostdirs: [],        // 静态文件目录列表
-            ws: true,            // 是否启用 WebSocket
-            ckws: true,          // 是否鉴权
-            cors: ['*'],         // 允许的跨域来源
-            maxws: 100,          // 最大 WS 连接数
-            maxonline: 100,      // 最大在线人数
-            maxhttp: 100         // 最大 HTTP 连接数
-        },
-        mysite: {               // 具体站点
-            httptype: 'https://',
-            port: 443,
-            weburls: {           // SPA URL 重写
-                rewrite: true,
-                webdir: './dist',
-                keys: ['/app', '/user']
-            },
-            httpscert: {         // HTTPS 证书
-                key: fs.readFileSync('./cert/key.pem'),
-                cert: fs.readFileSync('./cert/cert.pem')
-            }
-        }
-    },
-    
-    // 代理配置
-    proxyhosts: {
-        api: {
-            url: 'http://localhost:3000',
-            proxyport: 8080
-        }
-    }
-}
-```
+## 模块职责速查
+
+| 模块 | 核心导出 | 职责 |
+|------|----------|------|
+| `core/init` | `initAsaiHost` | 启动期挂载 $asai 方法、日志、进程、AES |
+| `core/host-config` | `getHostCFG` | 合并并缓存 hosts/proxyhosts |
+| `http/server` | `startHTTPServer` | HTTP 创建、路由、监听、asaiGuard |
+| `http/static` | `createStaticHandler` | 静态文件 + SPA + ETag |
+| `http/connection` | `setupHttpConnectionMonitor` | 80%/95% 阈值、空闲清理 |
+| `ws/server` | `createWSHost` | WSS 生命周期 |
+| `ws/auth` | `isOkWs`, `loginWs` | 用户名/Token/在线数鉴权 |
+| `proxy/server` | `startProxyServer` | 反向代理、hop-by-hop 头过滤 |
+| `config/validate` | `validateHostConfig` | 启动前 fail-fast 校验 |
+| `config/syscom` | `normalizeHostConfig` | syscom 归一化 |
+| `infra/logger` | `initLog` | `$asai.$log`、缓冲写盘 |
+| `infra/process` | `gracefulShutdown` | SIGTERM/SIGINT 优雅关闭 |
+| `infra/registry` | `registerApi/Ws` | 路由注册双写 $lib 与 hostserver* |
 
 ---
 
 ## 使用示例
 
 ```javascript
-const AsaiHost = require('./AsaiHost');
+import AsaiHost from './AsaiHost';
 
-const { StartAsaiHost, asaiWs } = AsaiHost($asai, {
-    sysWork: (req, res, hostdir) => { /* 系统路由处理 */ },
-    apiWork: (req, res, hostdir) => { /* API 路由处理 */ },
-    wsWork: (msg, ws, hostdir, req) => { /* WS 消息处理 */ },
-    jsonpWork: (req, res, hostdir) => { /* JSONP 处理 */ }
+const { StartAsaiHost } = AsaiHost.fn($asai, {
+  sysWork: (req, res, hostdir) => { /* /sys */ },
+  apiWork: (req, res, hostdir) => { /* /api */ },
+  wsWork: (msg, ws, hostdir, req) => { /* WS */ },
+  jsonpWork: (req, res, hostdir) => { /* /jsonp */ },
 });
 
-StartAsaiHost(); // 启动所有服务器
+StartAsaiHost();
 ```
 
----
-
-## 注意事项
-
-1. 所有处理器（`sysWork`/`apiWork`/`wsWork`/`jsonpWork`）在 `index.ts` 中被挂载到 `global`
-2. `validateHostdir()` 拒绝名称为 `default` 和 `asai` 的站点
-3. `http-server.ts` 中的 `checkFileExists()` 同时检查文件权限
-4. 代理服务器中包含 SSL 错误处理（`rejectUnauthorized: false` 用于自签名证书）
-5. 日志系统使用缓冲区异步写入，不会阻塞主线程
-
----
-
-## 代码分析与优化建议
-
-### ✅ 已优化项目
-
-#### 1. 全局变量污染 ➔ 模块级 Map ✅
+启动校验：
 
-**优化内容**：`index.ts` 中改用模块级 `workHandlers` Map 存储处理器，通过 `getWorkHandler()` 导出，`http-server.ts` 和 `ws-server.ts` 通过该函数获取，不再污染 `global`。
+```javascript
+import { validateHostConfig, normalizeHostConfig } from './src/host-api';
 
-```typescript
-// 优化后：模块级 Map，可多实例并行
-const workHandlers = new Map<string, Function>();
-export function getWorkHandler(name: string): Function | undefined {
-    return workHandlers.get(name);
-}
+const cfg = normalizeHostConfig(JSON.parse(fs.readFileSync('asaihost.json', 'utf8')));
+const errors = validateHostConfig(cfg);
+if (errors.length) throw new Error(errors.join('\n'));
 ```
 
-**优化收益**：避免全局命名冲突，支持多实例并行运行，单元测试可独立 mock。
-
----
-
-#### 2. 静态文件服务增加 ETag 和 Last-Modified ✅
-
-**优化内容**：新增 `serveStaticFile()` 函数，增加 `ETag` 和 `Last-Modified` 响应头，支持客户端条件请求（`If-None-Match` / `If-Modified-Since`），返回 304 Not Modified 减少不必要的文件传输。
-
-**优化收益**：节省带宽约 30-50%。
-
----
-
-#### 3. URL 解析增加编码保护 ✅
-
-**优化内容**：`parseUrlPath()` 在解析前对 URL 进行 `encodeURI()` 编码，避免中文等特殊字符导致 `new URL()` 抛出异常。
-
----
-
-#### 4. 日志缓冲区增加进程退出刷新 ✅
-
-**优化内容**：`LogBuffer` 构造函数和 `initLog()` 中注册 `process.once('beforeExit')` 钩子，确保进程退出前刷新所有日志缓冲区，防止日志数据丢失。
-
 ---
 
-#### 5. WebSocket 鉴权 `ws.send` + `close` 竞争修复 ✅
-
-**优化内容**：`isOkWs()` 中所有 `ws.send(msg)` 改为在回调中执行 `ws.close()`，确保消息发送完毕后再关闭连接。
-
----
-
-#### 6. 代理服务器 Userinfo 透传增加开关 ✅
-
-**优化内容**：在 `startProxyServer()` 中增加 `passUserInfo` 配置开关（默认关闭），避免用户信息泄露给第三方后端。
-
----
-
-#### 7. HTTP 连接监控间隔缩短 ✅
-
-**优化内容**：连接监控间隔从 30 分钟缩短为 5 分钟，更及时地处理连接数激增。
-
----
-
-#### 8. 代码可维护性改进 ✅
+## 注意事项
 
-**优化内容**：将静态文件服务逻辑拆分为独立的 `serveStaticFile()` 函数，包含完整的 ETag 校验和流式文件服务逻辑。
+1. 处理器通过模块级 `workHandlers` Map 注册，**不污染 global**。
+2. `validateHostdir()` 拒绝 `default` / `asai` 作为普通站点名启动。
+3. 静态路径经 `resolvePathUnderRoots` 白名单校验，拒绝目录穿越；代理默认**不透传** Userinfo。
+4. HTTP 连接监控间隔 **5 分钟**；超 95% 清理空闲 5 分钟以上连接。
+5. 日志异步缓冲写入，进程退出时 `beforeExit` 刷盘。
 
 ---
 
-### 🔜 待优化项目
+## 配置 → 代码映射图
 
-| 优先级 | 问题 | 状态 |
-|--------|------|------|
-| 🟡 P1 | 代码拆分完成（http-server.ts 仍需进一步细化） | 待处理 |
+```
+asaihost.json
+├── website/password/ip/index/asaisn/aes/httpscert/mimetypes  → 全局
+├── logger.*                                                    → infra/logger, http/log
+├── tm.*                                                        → core/init, ws/auth, infra/process
+├── hosts.default + hosts.<site>                                → core/host-config → http/*, ws/*
+│   ├── weburls.*                                               → http/static (SPA)
+│   ├── ckhttp/maxhttp                                          → http/connection
+│   └── ckws/maxws/maxonline                                    → ws/auth
+├── proxyhosts.default + proxyhosts.<name>                      → proxy/server
+└── syscom.{tcp|grpc|rs485}                                     → config/syscom → infra/transport-bridge
+```
 
 ---
 
-### 优化优先级总结
+## 版本与优化记录
 
-| 优先级 | 问题 | 影响 |
-|--------|------|------|
-| ✅ 已修复 | 全局变量污染 | 可维护性/多实例兼容 |
-| ✅ 已修复 | 缺少 ETag、日志丢失、鉴权竞争 | 性能/可靠性 |
-| ✅ 已修复 | 代理信息泄露、URL 解析异常 | 安全/稳定性 |
-| ✅ 已修复 | 代码拆分、监控粒度 | 可维护性 |
+- ✅ 模块级 workHandlers（替代 global）
+- ✅ 静态 ETag / 304、LRU 路径缓存
+- ✅ URL encodeURI 保护、日志 exit 刷盘
+- ✅ WS send→close 竞争修复、代理 passUserInfo 开关
+- ✅ HTTP 模块职责拆分（core/http/ws/proxy/config/infra/utils）
+- ✅ 删除冗余 .js 编译产物与 re-export shim；LRU O(1)；日志 skip 启动期编译
+- ✅ 静态资源 safe-path 防穿越；HTTPS 站点 HSTS 响应头