mabkit
v1.0.6
Published
Mabkit - Lightweight Mini Program Backend Framework (Unified CLI，now part of @mabjs/cli)
Readme
💡 设计初衷
微信小程序开发中，云开发（微信云开发 / uniCloud）提供了便捷的后端能力，但随着业务增长，其成本高、数据绑定、难以定制等问题逐渐显现。许多个人开发者和小团队希望拥有 数据自主可控、低成本、与云开发体验一致 的自建后端，却苦于繁琐的环境搭建、域名备案、HTTPS 配置和运维工作。
mabjs(mabkit，Mab.js) 正是为解决这一痛点而生：像使用云开发一样简单，却拥有完全自主的服务器后端。它让你用一行命令创建项目，一行命令启动带 HTTPS 隧道的开发环境，手机扫码即可调试，前端 SDK 完美兼容云开发 API 风格。核心全部开源，可部署在任何轻量服务器上，年成本低至百元以内。
⚙️ 技术框架
整体架构
text
客户端 (小程序 SDK) ←→ HTTPS 隧道 (cloudflared / ngrok) ←→ Express 服务 (Node.js)
↕
SQLite 数据库 (better-sqlite3)
↕
插件系统 (支付、消息、管理后台...)核心依赖
| 模块 | 技术选型 | 用途 | | ------------ | ----------------------- | ---------------------------- | | 运行时 | Node.js + Express | HTTP 服务、路由、中间件 | | 数据库 | SQLite (better-sqlite3) | 单文件数据库，模拟文档型集合 | | 认证 | JWT + 微信登录 | 无状态鉴权，自动刷新 | | CLI | Commander + nodemon | 命令行工具，热重载，隧道管理 | | SDK | 纯 JavaScript | 小程序端封装，链式查询 | | 文档 | VitePress | 官方文档站 | | 管理后台 | Vue 3 + Element Plus | 可视化管理面板（插件） |
项目结构（monorepo）
text
mabjs/
├── packages/
│ ├── mab-core/ # 核心运行时
│ ├── mab-cli/ # 命令行工具 (mab dev / start / deploy)
│ ├── create-mab/ # 项目脚手架 (create-mab my-project)
│ ├── mab-sdk/ # 小程序端 SDK
│ ├── plugin-admin/ # 可视化管理后台插件
│ ├── plugin-payment/ # 微信支付插件
│ ├── plugin-security/ # 安全增强插件
│ ├── plugin-subscribe/ # 订阅消息插件
│ └── plugin-websocket/ # 实时推送插件
├── examples/ # 官方示例项目
├── docs/ # 文档站点源码
└── package.json # monorepo 根配置🚀 预期性能
| 指标 | 预期值 | 说明 | | -------------- | --------------------- | --------------------------------- | | QPS | 500+ (单核轻量服务器) | SQLite WAL 模式，无网络开销 | | 并发连接 | 1000+ | Express + Node.js 异步非阻塞 | | 数据库响应 | ＜ 5ms | 本地文件系统，无网络延迟 | | 内存占用 | ＜ 100 MB | 单进程运行，SQLite 内存缓存可配置 | | 启动时间 | ＜ 2 秒 | 无外部依赖启动 | | 包体积 | 核心运行时 ＜ 2 MB | 适合轻量级部署 |
以上数据基于 2核2G 轻量云服务器测试，实际性能随硬件和插件数量线性变化。
🧩 实现功能
核心能力
- ✅ 微信登录：自动获取 openid，签发 JWT，支持身份鉴权中间件。
- ✅ 数据库操作：完全模拟云开发
collection.add()、.where().get()、.doc().update()等 API，支持条件查询、排序、分页、聚合。 - ✅ 文件上传/删除：本地存储，记录所有者，鉴权删除，支持文件类型和大小限制。
- ✅ 云函数：动态加载
cloudfunctions/下的脚本，通过/api/cf/<name>调用。 - ✅ 自动 HTTPS 隧道：开发环境下自动获取公网 HTTPS 地址（基于 cloudflared 或 ngrok）。
- ✅ 插件系统：可插拔的插件架构，支持支付、消息、管理后台、安全、自建账号、小程序后端迁移等。
- npm i 插件即可安装
官方插件矩阵
| 插件 | 功能 | 状态 |
| ------------------------- | ---------------------------------------- | ------ |
| @mabjs/plugin-admin | 可视化管理后台（用户、数据、文件、审计） | ✅ |
| @mabjs/plugin-payment | 微信支付（JSAPI 下单、退款、回调） | 开发中 |
| @mabjs/plugin-subscribe | 订阅消息发送（模板管理、频率限制） | 开发中 |
| @mabjs/plugin-security | 安全增强（内容审核、审计、加密、限流） | 开发中 |
| @mabjs/plugin-websocket | 实时推送（频道订阅、心跳、多进程） | 开发中 |
✨ 项目优势
| 对比维度 | 微信云开发 | Mab.js | | ------------ | -------------------------- | -------------------------------- | | 数据存储 | 腾讯云数据库 | 你的服务器，SQLite 单文件 | | 成本 | 按调用量计费，高流量时昂贵 | 极低，一台轻量服务器年费百元 | | 合规性 | 数据在腾讯云，需信任平台 | 完全自主可控，满足等保要求 | | 开发体验 | 无需运维，API 简洁 | 同样的 API 风格，零迁移成本 | | 可定制性 | 受限，无法安装自定义库 | 完全自由，Express 生态全开 | | 调试方式 | 必须小程序预览 | 支持 HTTPS | | 插件生态 | 有限 | 持续扩展，按需安装 |
- 🧩 开箱即用：
npx create-mab一键生成项目，mab dev立即启动 HTTPS 开发环境。 - 🔌 高内聚低耦合：插件通过标准接口接入，不侵入框架核心，可独立升级。
- 🌍 通用性强：不仅限于小程序，也可作为轻量 API 服务快速构建其他项目。
- 📦 生产就绪：内置 Helmet、CORS、Rate Limit、日志、审计等安全中间件。
- 💡 TypeScript 友好：所有插件提供
.d.ts类型声明。
🎯 目标人群
| 用户 | 场景 | 痛点 | | -------------------- | ---------------------------- | ------------------------------------ | | 个人开发者 | 接外包私活、开发自己的小程序 | 不懂运维，希望一键部署，控制成本 | | 外包小团队 | 为客户快速交付小程序 | 需要标准化后端，避免重复造轮子 | | 创业产品经理 | 验证 MVP，快速试错 | 只想写前端逻辑，不想碰后端 | | 学生 / 初学者 | 毕业设计、学习小程序开发 | 没钱买云服务，渴望免费自托管方案 | | 有等保需求的企业 | 数据必须存放在自己的服务器 | 需要自主可控、合规审计 |
🏗️ 快速构建
1. 全局安装 CLI
bash
npm install -g mabkit 或@mabjs/cli
# 获得两个命令：create-mab (创建项目) 和 mab (开发/部署)2. 创建项目
bash
create-mab my-project
cd my-project
npm install3. 配置微信凭证
编辑 .env 文件，填入你的小程序 AppID 和 AppSecret。
ini
WX_APPID=wx1234567890abcdef
WX_SECRET=你的Secret
JWT_SECRET=请用 openssl rand -base64 32 生成4. 启动开发服务器（自动 HTTPS 隧道）
bash
mab dev终端输出 [DEV] Public URL: https://xxx.trycloudflare.com。
5. 部署到生产环境
bash
mab deploy --host your-server-ip --user root📚 文档与资源
- GitHub 组织：https://github.com/mabjs
- 示例项目：
examples/todo-backend
🤝 参与贡献
欢迎提交 Issue 和 PR！请在参与前阅读 行为准则。
📄 许可证
Mab.js —— 让你的小程序后端，从未如此简单、自由。