bm2

    A lightweight Linux process manager for Bun and Node.js applications, written in MoonBit

    bun
    nodejs
    process-manager
    linux
    Download zip
    Author
    Version
    0.10.0
    License
    MIT
    Last updated
    yesterday
    Downloads
    215

    #bm2

    搞定 Node.js 与 Bun 项目的线上部署

    手册与官网:https://bm2.moonbitlang.dev

    bm2 架构与执行流程

    #亮点

    异常退出自动重启

    实例异常退出后自动重启,连续重启达到上限时停止自愈并等待人工处理。

    多实例与连接分流

    同一项目可启动多个实例,共用一个端口时由系统按连接分配,各用独立端口时由网关分流。

    看管进程故障不影响业务

    负责监督的进程退出后业务进程继续运行,新的看管进程识别原实例并继续监督,不需要重启应用。

    升级不中断服务

    执行升级后换入新版本,服务不中断,应用进程号保持不变。

    日志自动轮转

    日志达到设定大小后自动切分,归档代数可配置,无需额外组件。

    内置通知上报

    崩溃、内存超限、实例离线、磁盘空间不足、连续重启等事件,可推送至飞书、钉钉、企业微信、Slack、Discord、自定义 webhook 与邮箱,上报由 bm2 内部实现,无需额外部署服务。

    定时运行报告

    支持按 cron 表达式定时推送,报告包含每个实例的状态、端口、内存、峰值、CPU、运行时长与重启次数,以及项目汇总。

    也可以只生成增量统计,包含区间内存峰值与自动重启次数。

    关键指标阈值提醒

    内存占用、离线时长、连续重启次数、启动超时、磁盘剩余空间、短时间内的重启次数均可设置阈值,同一告警按时间窗口去重,推送频率受配置限制。

    运行状态可追溯

    实例的运行状态、重启次数与退出原因全部写入状态目录,事后可查。

    #安装 bm2

    bm2 只通过 MoonBit 的工具链分发,所以先装工具链,再用它安装 bm2。

    安装 MoonBit 工具链

    curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bash

    这个脚本把 moon 放进 ~/.moon/bin,并把这个目录写进 shell 配置的 PATH。

    工具链只需要装一次,升级 bm2 时不用重装。

    安装 bm2

    moon install chensuiyi/bm2/...

    bm2 与 bm2d 会一起装进 ~/.moon/bin,不需要再配 PATH。

    安装过程会在本机编译一次,没有预编译包,所以需要 C 工具链。

    #快速开始

    在项目目录写一份 bm2.toml。

    name = "api" script = "src/index.ts" instances = 2 port = 3000

    然后在这个目录执行。

    bm2 serve # 生产模式:登记、启动、写状态 bm2 list # 看实例表 bm2 dev # 开发模式:单实例,前台跟随日志

    应用里这样监听端口。

    Bun.serve({ port: Number(Bun.env.BM2_APP_PORT), reusePort: true, fetch: () => new Response('ok'), })

    reusePort: true 只在多实例的 cluster 模式下需要:那时探测发现没开会停下整个项目并说明原因,而不是让第二个实例随机发疯。单实例的 cluster 不共享端口,不要求这一项。

    #日报与巡检

    通知属于项目,写在同一份 bm2.toml 里。只有两个概念:事件和目标——哪些事值得说,说给谁听。

    [notify] enabled = true [[notify.target]] platform = "feishu" url = "https://open.feishu.cn/open-apis/bot/v2/hook/__FEISHU__"

    • 目标不写 events 就收全部事件。只关心一部分时,events = ["crash", "oom_kill"] 是白名单,events = ["!lifecycle"] 是排除——两种写法不能混用。
    • 每日统计也是一个事件(daily_stats),几点发由 daily_report_hour 定,默认 8(本地时间整点);写 events = ["!daily_stats"] 就是不要日报。
    • 同一件事在 dedupe_window_s(默认 3600 秒)内只说一次,重复只计数,下一次带出去。
    • 邮件目标的 SMTP 通道在 [notify] 上写一份(mail_url / mail_from / mail_username / mail_password),每个邮件目标只写收件人 to。
    • threshold_* 阈值不写就是推荐值(内存 80%、离线 5 分钟、连续重启 5 次、拉起 30 秒、磁盘 1G、十分钟 20 次),要关掉某一项才写 0。
    • 消息本身跟着语言走:中文项目的通知从标题到字段名全中文(事件: 实例崩溃、应用: api、运行时长: 0s),机器读的那一侧仍是语言中立的事件键 event 与 event_name。
    • 凭据用 __NAME__ 占位符,真值放 .env 或启动环境,不要写进仓库。

    改完先 bm2 check 看汇总,再 bm2 notify 发一条测试消息到所有目标。

    #命令速查

    命令用途
    bm2 serve生产模式:登记、启动、写状态
    bm2 dev开发模式:单实例,前台跟随日志,--no-follow 关闭跟随
    bm2 stop <name>停下,但保留登记,随时可以再起来
    bm2 remove <name>退役:停下、注销、交还名字,日志默认保留
    bm2 remove <name> -f退役并删除它的状态目录,连日志一起
    bm2 clean清掉状态目录里已经没有归属的旧目录,--dry-run 只看不删
    bm2 list [name]查看实例表,--json 给机器读
    bm2 check只校验当前目录的 bm2.toml,不碰守护进程
    bm2 reload换入新的守护进程,应用继续运行
    bm2 notify给本项目所有通知目标发一条测试消息
    bm2 upgrade用 moon install 换入新版本并让新守护进程接管
    bm2 kill -y停掉全部项目并退出守护进程

    stop 是暂停,名字还在册,remove 是退役,名字交还出去,日志保留,想翻日志的时刻往往在项目消失之后。

    #配置速查

    能省就省:没写出来的字段一律取默认值,默认值就是绝大多数项目该用的值。最小可用配置只有四项:

    name = "api" # 项目名,也是状态目录下的目录名 script = "index.js" # 相对 cwd instances = 2 port = 3000

    cwd 默认就是 bm2.toml 所在目录,两者一致时不用写。

    其余字段按需添加,括号里是默认值:

    字段默认什么时候才需要写
    cwd配置文件所在目录应用不在配置文件旁边
    runtimebun用 Node 跑:runtime = "node"(需 Node ≥ 24)
    exec_modecluster单实例且需要 fork 语义
    max_memory_mb512服务吃得多,或要让内存预警更早/更晚触发
    max_tree_processes512进程树很深,默认统计上限不够
    max_restarts10想更快放弃自愈(0 = 首次异常即停)
    restart_delay_ms1000重启太密或太慢
    min_uptime_ms10000短命进程被误判成崩溃
    stop_timeout_ms10000停机要等更久(如排空连接)
    [logs]10MB / 代数不限要限制日志磁盘占用
    [notify]关闭要事件告警与每日统计
    lang跟随操作者环境要钉死输出语言

    [notify] 里只写偏离推荐值的那几项:threshold_* 不写就是推荐值,写 0 才是关闭该项, 关闭之后对应事件不会出现。

    #环境变量文件(.env)

    .env 归运行时,不归 bm2。 bm2 只注入自己的基线,业务的环境变量由 bun / node 自己加载:

    • bun:开箱即用。它按 .env → .env.<NODE_ENV> → .env.local → .env.<NODE_ENV>.local 的顺序加载,后者覆盖前者。
    • node:不会自动读。要么在启动命令里显式给 --env-file,要么由应用自己 process.loadEnvFile()。bm2 的配置里没有参数位(script 只是脚本路径),传不了 --env-file。
    • bm2 按模式写 NODE_ENV(bm2 dev → development,bm2 serve → production),运行时据此挑文件。

    bm2 自己也会读一遍 .env,但只用于两件事,不注入业务进程:

    1. bm2.toml 里的 __NAME__ 占位符(例如通知地址、SMTP 密码)
    2. 校验 NODE_ENV:.env 里写了与模式冲突的值会直接报错

    读取位置是 bm2.toml 所在目录;而运行时读的是应用的 cwd。两者不同(用 cwd 字段指到别处)时,以 cwd 为准——那是运行时的规则。

    注入给实例的只有基线:PATH/HOME/TMPDIR、BM2_* 前缀变量,外加 BM2_APP_NAME/BM2_APP_PORT/NODE_ENV 这些保留变量。shell 里其它变量不会被继承。

    Node 项目在自己的 package.json 里补上加载参数即可(顺序与 Bun 一致,后者覆盖前者):

    "dev": "node --env-file=.env --env-file=.env.development --env-file-if-exists=.env.local --env-file-if-exists=.env.development.local src/index.js", "start": "node --env-file=.env --env-file=.env.production --env-file-if-exists=.env.local --env-file-if-exists=.env.production.local src/index.js"

    • --env-file-if-exists 需要 Node 22.9 及以上(Node 24 已是正式特性);更老的版本只能全用 --env-file,那就得保证文件存在
    • 生产机上不要留 .env.local,它会在 .env.production 之后把线上值覆盖掉
    • Node 的 --env-file 不做 $VAR 展开,值里的 $ 会原样保留;Bun 会展开。同一份文件要在两个运行时下都稳定,值里就别依赖 $

    .env 的解析语义以 Bun 为准(引号、注释、$VAR / ${VAR:-默认}、单层展开、逐文件作用域),实现是独立库 chensuiyi/dotenv,bm2 引它来解析自己那两件事。

    #与 pm2 的对比

    对比项bm2pm2
    形态两个原生静态二进制Node.js 应用
    额外依赖无需要 Node.js
    空闲守护进程内存约 2.6 MB约 50 MB
    日志轮转内置需装 pm2-logrotate
    cluster 分发层内核 SO_REUSEPORT,无中间层cluster master 进程
    守护进程崩溃应用继续运行,新守护进程接管cluster 应用随之中断
    配置静态 TOML,字段强校验ecosystem.config.js,可执行代码

    #环境要求

    • Linux,内核 5.4 及以上,pidfd 进程跟踪与退出码需要它。
    • runtime = "bun" 需要 Bun 1.4.0 及以上。
    • runtime = "node" 需要 Node.js 24.0.0 及以上。
    • 只有安装与升级 bm2 时需要 MoonBit 工具链,运行 bm2 不需要。

    版本下限在启动那一刻实测,低于下限会直接拒绝启动并说清缺什么,而不是让实例反复崩溃给你看。