介绍 — SnowLuma Docs

SnowLuma 是一个高性能的下一代远程协议框架，旨在桥接 NTQQ 协议与 OneBot 生态系统。为机器人开发提供结构化的 API。

你可以用它做什么

接入 OneBot v11：HTTP / WebSocket / 反向 WebSocket / HTTP 上报四种适配器。
桥接 NTQQ：通过 Hook 捕获并解析 NTQQ 数据包，再转换为上层事件 / 动作。
多账号会话：每个 UIN 一个独立 OneBot 实例，配置可继承全局或单独覆盖。
内置 WebUI：完整构建启动后可访问 Web 控制台查看状态、管理网络适配器。
TypeScript SDK：@snowluma/sdk 提供类型完备的 OneBot HTTP / WS 客户端。

三种用法

场景	推荐方式
部署到服务器	Docker 容器 —— 镜像内置 QQ + Xvfb + VNC，开箱即用
本机使用预发行版	从 GitHub Release 下载对应平台的 `lite` / 完整 tarball，解压后 `node ./index.mjs`

发行目录

pnpm build:all 产物输出到仓库根目录 dist/：

dist/
├─ index.mjs            # 主入口
├─ launcher.bat         # Windows 启动器
├─ package.json
├─ webui/               # 内置 WebUI 静态资源
└─ native/              # 平台原生产物
   ├─ snowluma-win32-x64.node
   ├─ snowluma-win32-x64.dll
   ├─ snowluma-linux-x64.node
   ├─ snowluma-linux-x64.so
   └─ websocket-<platform>-<arch>.node

Windows 下也可以通过 launcher.bat 启动：

node ./index.mjs
pause

GitHub Release 还会发布两类 tarball：

SnowLuma-<TAG>-<platform>-<arch>.tar.gz —— 含 Node.js 运行时的完整包。
SnowLuma-<TAG>-<platform>-<arch>-lite.tar.gz —— 不含 Node.js（适合容器或本机已装 Node 22+ 的用户，体积小很多）。

默认服务

首次启动 OneBot 实例时，SnowLuma 会自动创建 config/onebot.json、config/onebot_<uin>.json 和 config/runtime.json。

服务	默认地址	配置项
OneBot HTTP	`http://0.0.0.0:3000/`	`networks.httpServers[].port`
OneBot WebSocket	`ws://0.0.0.0:3001/`	`networks.wsServers[].port`
WebUI	`http://0.0.0.0:5099/`	`runtime.json` 的 `webuiPort`

详细字段说明见配置参考。

项目状态

SnowLuma 仍在早期开发，破坏性更新概率较高。遇到接口缺失、平台原生产物缺失或 OneBot 行为不一致时，请优先检查当前分支的 README、配置文件和构建产物。

介绍

你可以用它做什么

三种用法

发行目录

默认服务

项目状态

本页目录