asaihost-nodejs

Node.js HTTP/WebSocket 服务器宿主：多站点监听、静态资源、反向代理、内置 sysserver 平台 API（登录/RBAC/日志/数据库），以及 IEC 62443 安全内核。

目录结构

asaihost-nodejs/
├── index.ts              # 包入口（默认导出 initAsaiHostNodejs + 命名 API）
├── package.json
├── tsup.config.ts
├── README.md
└── src/
    ├── index.ts          # StartAsaiHostNodejs 启动链
    ├── host-api.ts       # 对外公开 API 聚合
    ├── types.ts          # AsaiRuntime / HostConfig 等类型
    ├── core/             # init、host-config、network
    ├── http/             # server、static、security
    ├── ws/               # server、auth、message
    ├── proxy/            # 反向代理
    ├── config/           # validate、secrets
    ├── infra/            # registry、security
    ├── common/server/    # ServerApi / ServerSys / ServerWs / WsClient 基类
    └── sysserver/        # 内置 api/ws/db/lib

目录

1. 快速开始
2. 在 AsaiCMS monorepo 内使用
3. 独立项目集成
4. 启动与校验流程
5. 配置文件总览
6. 配置 → 运行时映射
7. 公开 API 参考
8. 字段速查
9. 开发与发布 npm 包
10. 约束与前端对应

快速开始

安装

npm install asaihost-nodejs ws
# 若使用 MySQL / SQLite 数据存储
npm install mysql sqlite3

最小引导（app.ts 模式）

import fs from 'node:fs/promises';
import path from 'node:path';
import AsaiHostNodejs from 'asaihost-nodejs';

const $asai: any = {
  $lib: { /* 业务工具库 */ },
  connectionshttp: {},
  connectionsws: {},
  taskshttp: {},
  tasksws: {},
  servershttp: {},
  serversws: {},
  tm: 0,
  tmpdata: {},
};

// 1. 挂载 sysserver 平台能力（api/ws/db/lib）；sqlite/mysql 驱动由独立插件注入
import AsaiHostNodejsDbsqlite from './src/plugs/asaihost-nodejs-dbsqlite/index';
import AsaiHostNodejsDbmysql from './src/plugs/asaihost-nodejs-dbmysql/index';
AsaiHostNodejs.sysserver($asai, {
  db: { sqlite: AsaiHostNodejsDbsqlite, mysql: AsaiHostNodejsDbmysql },
});

$asai.serverRoot = process.cwd();
const cfg = JSON.parse(
  await fs.readFile(path.join($asai.serverRoot, 'websys/sys/asaihost.json'), 'utf8'),
);

// 2. 配置校验与密钥注入
const stripped = AsaiHostNodejs.stripForbiddenSecretsFromHostConfig(cfg);
if (stripped.length) {
  console.warn(`[AsaiHostNodejs] 已从 asaihost.json 剥离敏感字段: ${stripped.join(', ')}`);
}
$asai.hostconfig = AsaiHostNodejs.normalizeHostConfig(cfg);
AsaiHostNodejs.normalizeSecurityConfig($asai.hostconfig);
const errors = AsaiHostNodejs.validateHostConfig($asai.hostconfig);
if (errors.length) throw new Error(errors.join('; '));

const { secrets } = await AsaiHostNodejs.loadAsaiSecrets($asai.serverRoot);
AsaiHostNodejs.applySecretsToHostConfig($asai.hostconfig, secrets);
await AsaiHostNodejs.resolveHttpsCertFromPaths($asai.serverRoot, $asai.hostconfig);

// 3. 注册业务 work 处理器并启动
$asai.asaihost = AsaiHostNodejs;
const { sysWork } = sysMod($asai);
const { apiWork } = apiMod($asai);
const { wsWork } = wsMod($asai);
const { jsonpWork } = jsonpMod($asai);

const { StartAsaiHostNodejs } = AsaiHostNodejs.fn($asai, { sysWork, apiWork, wsWork, jsonpWork });
StartAsaiHostNodejs();

完整 monorepo 示例见仓库根目录 webserver/app.ts。

在 AsaiCMS monorepo 内使用

本仓库 webserver 通过相对路径引用插件源码，开发时无需先 npm pack：

// webserver/app.ts
import AsaiHostNodejsMod from './src/plugs/asaihost-nodejs/index';

本地构建 npm 产物：

cd webserver/src/plugs/asaihost-nodejs
npm install
npm run build

构建产物位于 dist/：asaihost-nodejs.es.js（ESM）、asaihost-nodejs.cjs（CJS）、index.d.ts（类型声明）。

独立项目集成

1. 项目结构建议

your-server/
├── app.ts                 # 引导入口（见上文）
├── websys/sys/
│   ├── asaihost.json      # 非敏感配置（可进 Git）
│   └── asaihost.secrets.local.json   # 本地密钥（勿提交）
├── .env                   # 生产推荐：环境变量注入密钥
├── webclient/             # 静态前端（hostdirs 指向）
└── src/work/              # 业务 api/sys/ws 模块

2. TypeScript

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "esModuleInterop": true
  }
}

从 npm 安装后：

import AsaiHostNodejs, { PLUGIN_NAME, type AsaiRuntime, type HostConfig } from 'asaihost-nodejs';

3. 运行方式

• 开发：tsx app.ts 或 ts-node --esm app.ts
• 生产：先 npm run build（若打包业务代码），再 node dist/app.js

4. 与传输层插件协作

TCP / gRPC / RS485 等传输插件通过 $asai.asaihost 挂载，禁止跨包 deep import src/。在 asaihost.json 中配置 tcp / grpc / rs485 块，由对应 npm 插件读取。

启动与校验流程

读取 asaihost.json
  → stripForbiddenSecretsFromHostConfig（敏感字段不得写在 JSON）
  → normalizeHostConfig + normalizeSecurityConfig
  → validateHostConfig（结构 fail-fast）
  → validateProductionSecurity（生产 IEC 62443 检查）
  → loadAsaiSecrets（.env / secrets.local.json / process.env）
  → applySecretsToHostConfig + resolveHttpsCertFromPaths
  → sysserver($asai) 已提前执行
  → fn($asai, { sysWork, apiWork, wsWork, jsonpWork })
  → StartAsaiHostNodejs()  → 多端口 HTTP/WS + 反向代理

默认导出 API 形状

interface AsaiNodejsHostPlugin {
  readonly name: 'asaihost-nodejs';
  fn(runtime, options): { StartAsaiHostNodejs; asaiWs };
  sysserver(runtime, opt?: SysserverBootOptions): void;
  AsaiCommon: { ServerApi; ServerWs; ServerSys; WsClient };
  AsaiUtils: { deUserInfoWithAsai; wsMock };
  // …配置、路由、安全、传输桥接等（见 host-api.ts）
}

配置文件总览

本插件的配置由 两份 组成，启动时合并到 $asai.hostconfig：

加载优先级（高 → 低）：process.env > webserver/.env > asaihost.secrets.local.json → 仅注入内存 hostconfig（不写回 JSON）。

敏感字段（password / asaisn / aes.keybase64 / PEM 内联 / sessionSecret / wssec[0]）禁止写入 asaihost.json，启动时会剥离并报错。

欧盟合规：密钥如何保存（CRA / NIS2 / GDPR Art.32 / IEC 62443-4-2）

密钥分离（必做）

生成随机密钥

cd webserver
npm run secrets:gen              # 打印 .env 片段
npm run secrets:gen:write        # 写入 .env（已存在则拒绝覆盖）
npm run secrets:gen:json         # 打印 secrets.local 模板

落盘后建议：chmod 600 .env（Linux）；Windows 限制 ACL 仅服务账户可读。轮换时分别更新 ASAI_ASAISN / ASAI_SESSION_SECRET，避免一钥多用。

用户数据存储（dataStores.user）

默认 file（webdata/webdb/users/users.json + sessions.json）。在 websys/sys/asaihost.json 中修改 dataStores.user 即可切换，重启 webserver 后生效（app.ts 须已注入 sqlite/mysql 驱动）。

"dataStores": {
  "user": {
    "type": "file",
    "opt": { "dir": "webdata/webdb/users/", "ext": ".json", "create": 1 }
  }
}

切换 SQLite：

"user": {
  "type": "sqlite",
  "opt": { "database": "./webdata/webdb/users/users.db", "create": 1 }
}

切换 MySQL：

"user": {
  "type": "mysql",
  "opt": {
    "host": "127.0.0.1",
    "user": "root",
    "password": "",
    "database": "asai",
    "create": 1
  }
}

运行时可通过 GET /api/user/login/config/ 查看 userStore.type（file / sqlite / mysql）。兼容旧字段 userStore，但推荐只维护 dataStores.user。

日志子系统已下线

asaihost.json 不再有 logger 配置。控制台级别、干预日志（CEF / 哈希链 / 5 年留存）、SIEM 令牌与 /api/asailog/* 均已删除。

• $asai.$log 是立即返回的空函数，不读配置、不向控制台输出；
• 启动校验会丢弃历史 logger 字段，不再创建 webdata/webdb/log/intervention 目录；
• WEB 操作记录（security.auditLog、接口追踪、日志只读门槛）已去掉，不再向控制台输出。

清理历史遗留日志

已下线前写出的文件不会自动消失，用根目录脚本一次性回收（默认只预览，不删除）：

npm run logs:purge          # dry-run 预览清单与总大小
npm run logs:purge:apply    # 确认后真正删除

脚本清理 webdata/webdb/log/{client,server,access,store,intervention,intervention-test} 下的 .txt/.log/.jsonl/.gz/.cef。

完整配置 — asaihost.json（合成示例）

{
  "website": { "title": "WEB", "ver": "1.0.0.0" },
  "dataStores": {
    "user": {
      "type": "file",
      "opt": { "dir": "webdata/webdb/users/", "ext": ".json", "create": 1 }
    }
  },
  "security": {
    "requireAuth": 0,
    "csp": 0,
    "authSkipPaths": [
      "/api/sys/errorcodes/*",
      "/api/user/login/auth/*",
      "/api/user/login/register/*",
      "/sys/info/*",
      "/jsonp/*"
    ],
    "minUserLevel": 0,
    "allowRegister": 1,
    "lockoutMaxFails": 5,
    "lockoutMinutes": 15,
    "sessionTtlHours": 24,
    "passwordMinLength": 8,
    "quota": {
      "enabled": 0,
      "maxApiConcurrent": 500,
      "maxApiPerIp": 30,
      "maxApiPerIpPerMin": 120,
      "maxWsPerIp": 5,
      "maxLoginSessions": 100,
      "maxSessionsPerUser": 3,
      "onUserSessionOverflow": "reject"
    }
  },
  "hosts": {
    "default": {
      "port": 9198,
      "httptype": "http://",
      "maxhttp": 2000,
      "maxws": 2000,
      "maxonline": 100,
      "hostdirs": ["webclient", "websys", "webdata/upload"]
    },
    "asai": {
      "ws": 1,
      "port": 9199,
      "hostdirs": ["webclient", "websys", "webdata/upload"]
    }
  },
  "proxyhosts": {
    "default": {
      "proxyport": 9298,
      "port": 9198,
      "httptype": "http://",
      "proxyhttptype": "http://"
    }
  },
  "aes": {
    "lv": 1,
    "aad": "asai aes aad",
    "keylength": 256,
    "ivlength": 12,
    "algorithm": "aes-256-gcm"
  },
  "httpscert": {
    "keyPath": "websys/sys/certs/local.key",
    "certPath": "websys/sys/certs/local.crt"
  },
  "ip": "asai",
  "index": "index.html"
}

完整字段模板见 monorepo webserver/websys/sys/asaihost.json；校验规则以 validateHostConfig 源码为准。

密钥侧车

复制 websys/sys/asaihost.secrets.example.json 为 asaihost.secrets.local.json：

{
  "_comment": "禁止提交仓库。生产请改用环境变量或密钥托管。",
  "password": "<强密码≥12>",
  "asaisn": "<随机盐≥32，与 sessionSecret 不同>",
  "aesKeyBase64": "<与前端 VITE_ASAI_AES_KEYBASE64 一致>",
  "sessionSecret": "<随机密钥≥32，与 asaisn 不同>",
  "wssecToken": "<随机 token>"
}

环境变量（等价）

ASAI_HOST_PASSWORD=
ASAI_ASAISN=
ASAI_AES_KEYBASE64=
ASAI_SESSION_SECRET=
ASAI_WSSEC_TOKEN=
ASAI_REQUIRE_ENV_SECRETS=1
ASAI_HTTPS_KEY_PATH=websys/sys/certs/local.key
ASAI_HTTPS_CERT_PATH=websys/sys/certs/local.crt

配置 → 运行时映射

asaihost.json + secrets
├── website / ip / index / mimetypes / pkg     → 全局
├── tm.*                                       → init, ws/auth, process
├── security.*                                 → access-control, user-store, quota
├── userStore.*                                → sysserver/api/login/store
├── aes.* (+ secrets.keybase64)                → API/WS 加解密
├── httpscert.*                                → https.createServer
├── hosts.default + hosts.<site>               → http/*, ws/*
│   ├── weburls.*                              → SPA fallback
│   └── ckhttp / ckws / max*                   → 连接监控与限流
├── proxyhosts.*                               → proxy/server
└── tcp|grpc|rs485                             → 传输插件（可选）

站点合并规则

• 实际站点 = hosts.default 浅合并 hosts.<name>
• default 仅作模板，不单独监听
• asai 为内置守护站点；9199 端口冲突时 process.exit(1)

请求路由

公开 API 参考

npm 消费者仅使用包入口导出，禁止 deep import src/。

配置与密钥

路由注册

安全与基础设施

传输桥接（供 TCP/gRPC/RS485 插件）

类型导出

AsaiRuntime、HostConfig、AsaiHostNodejsOptions、HostBootResult、AsaiSecrets、SecurityConfig 等见 import type { … } from 'asaihost-nodejs'。

字段速查

security

hosts.default 常用

aes

开发与发布 npm 包

cd webserver/src/plugs/asaihost-nodejs
npm install
npm run typecheck    # 仅类型检查
npm run build        # tsup 打包 + tsc 声明
npm pack             # 本地验证 .tgz 内容
npm publish --access public

package.json exports 约定

注意事项

1. 修改 asaihost.json 后需重启 Node 进程。
2. 端口冲突以 listen 的 EADDRINUSE 为准（启动前不再用 netstat 预告警，避免误报）；排查 9198/9199。
3. CONFIG_WARN 表示使用 dev 默认密码，生产请设 ASAI_HOST_PASSWORD。
4. 业务处理器经模块级 workHandlers Map 注册，不污染 global。
5. 静态路径经 resolvePathUnderRoots 防目录穿越。

近期修复（鉴权 / 会话 / WS）

测试

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

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

# 或单文件（现有示例）
npx tsx --test .youmengyu/test/unit/webserver/plugs/asaihost-nodejs/login/resolve-user-lv.test.mjs
npx tsx --test .youmengyu/test/unit/webserver/plugs/asaihost-nodejs/ws/auth-isOkWs.test.mjs

约束与前端对应

• 与 asaihost-vue（前端）配对使用时，保持 asaihost.json / aes 密钥 / VITE_ASAI_AES_KEYBASE64 一致。
• 插件间禁止跨包 plugs/*/src/ 引用；消费方只走 import from 'asaihost-nodejs'。
• 传输层插件仅通过 $asai.asaihost.* 与宿主协作。

配置以本 README 与 validateHostConfig 源码为准；monorepo 实参见 webserver/websys/sys/asaihost.json 与 webserver/app.ts。