#bm2

#bm2与pm2对比

#功能特性

• 一个 bm2.toml 配置一个项目（单个应用，一个或多个独立实例，上限 1024）。
• 命令：start、kill、list、reload、upgrade、version、notify。
• 优雅停止：SIGTERM 宽限期后 SIGKILL；start 总是对其项目执行一次完整重启。

• 崩溃自动重启：异常退出按 restart_delay_ms 延迟重启，spawn 失败按次数递增退避。
• 崩溃预算 max_restarts：连续异常重启超预算即进入 errored，停止自愈等待人工介入。
• 干净退出（超 min_uptime 的 code 0）不消耗崩溃预算，按计划重启。
• 内存限制 max_memory_mb：超限按异常重启处理。

• cluster 模式基于 SO_REUSEPORT：所有实例共享一个端口，内核分发，无中间层、无单点。
• fork 模式连续端口，交给 Nginx / Caddy 分发。
• 启动后实测 reusePort，缺失即停止整个项目并明确报错。

• pidfd 进程跟踪：守护进程崩溃后新守护进程原地收养应用，应用无感继续运行。
• 状态持久化：掉电、崩溃后实例状态不丢、不半截（原子写 + fsync）。
• 本机 TCP + 共享令牌控制通道，令牌常量时间比较，敏感目录 0700。
• CLI 与守护进程互相校验协议版本。

• stdout / stderr / crash 诊断三路分离，严格区别于 bm2 自身管理日志。
• 按 10 MB 轮转，保留十代；事件日志 JSONL，不含任何敏感数据。

• 七平台预设（飞书/钉钉/企业微信/Slack/Discord/webhook/邮件），按项目独立配置。
• 覆盖崩溃、预算耗尽、内存超限、reusePort 缺失、生命周期、阈值告警、定期体检。
• 去重、限流、队列、退避重试内置；凭据零泄露。

• bm2 upgrade 比对版本、安装新二进制并自动换入新守护进程，应用继续运行。

#环境要求

• 仅支持 Linux，非 Linux 构建会拒绝运行并给出明确提示。
• 需要 Linux 内核 >= 5.3（pidfd 进程跟踪）。
• MoonBit（仅安装/升级 bm2 时需要）
• Bun，版本 >= 1.4.0
• Node.js，版本 >= 24.0.0（仅 runtime = "node" 的项目需要）

#安装与升级

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

moon install chensuiyi/bm2/...

bm2 upgrade          # 比对版本、执行 moon install，并自动换入新守护进程

#配置参数

# 项目名：字母开头，后接字母、数字和下划线。
# 同时也是应用名，在所有已注册项目中必须唯一。
name = "api"

# 应用工作目录（绝对路径），默认为 bm2.toml 所在目录。
cwd = "/srv/api"

# 相对 cwd 的脚本路径，禁止 .. 段。
script = "src/index.ts"

# 运行时：bun 或 node。
runtime = "bun"

# 执行模式：cluster（默认，所有实例共享同一个 port，由内核分发
# 连接，应用监听需开启 reusePort）或 fork（端口从 port 起连续分配）。
exec_mode = "cluster"

# 实例数量（1..1024）。
instances = 2
port = 3000

# 单实例内存上限（MiB），超过按异常重启处理，至少为 1。
max_memory_mb = 512

# 连续异常重启预算，0 表示首次异常即 errored。
max_restarts = 10

# 自动重启前的延迟（毫秒），崩溃后固定，spawn 失败后按次数递增。
restart_delay_ms = 1000

# 干净退出早于此时长（毫秒）会计入重启预算。
min_uptime_ms = 10000

# SIGTERM 到 SIGKILL 的宽限期（毫秒），最大 60000。
stop_timeout_ms = 10000

#环境变量

[env]
MYSQL_HOST = "127.0.0.1"
MYSQL_PORT = "3306"

• BM2_APP_NAME（项目名）
• BM2_INSTANCE_ID（实例编号，第一个实例为 "0"）
• BM2_APP_INSTANCE（同实例编号，命名对齐 PM2 的 NODE_APP_INSTANCE 习惯）
• BM2_APP_PORT（分配给该实例的端口：默认（cluster）恒为 port，fork 模式等于 port 加实例编号）
• NODE_ENV（恒为 "production"）

• 用 BM2_APP_PORT 绑定监听端口，多实例各占一个端口。
• 用 BM2_APP_INSTANCE === "0" 判断主实例，只在主实例执行数据库迁移、定时任务等一次性逻辑。
• 用 NODE_ENV === "production" 走生产分支。

const PORT = Number(process.env.BM2_APP_PORT ?? 3000);
const isPrimary = process.env.BM2_APP_INSTANCE === "0";

Bun.serve({ port: PORT, fetch: () => new Response("ok") });

if (isPrimary) {
  // 只在主实例执行：数据库迁移、定时任务等
}

#命令使用

bm2 start             # 注册/更新当前目录中的项目并启动它
bm2 kill <name>       # 停止一个项目并注销它；bm2d 继续运行
bm2 kill -y           # 停止所有项目、注销它们并退出 bm2d（裸 `kill` 会拒绝执行）
bm2 list [name]       # 显示所有已注册项目的状态;--json 输出机器可读 JSON
bm2 reload            # 换入新的 bm2d；被管理的应用继续运行
bm2 upgrade           # 把 bm2 升级到 mooncakes 上的最新版本
bm2 version           # 显示 bm2 版本

#负载均衡

# exec_mode 可省略，默认即 cluster
instances = 4
port = 3000

const PORT = Number(process.env.BM2_APP_PORT);

// Bun
Bun.serve({ port: PORT, reusePort: true, fetch: () => new Response("ok") });

// Node.js
const http = require("node:http");
http.createServer((req, res) => res.end("ok")).listen({ port: PORT, reusePort: true });

upstream bm2_app {
    server 127.0.0.1:3000;
    server 127.0.0.1:3001;
}

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://bm2_app;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

example.com {
    reverse_proxy 127.0.0.1:3000 127.0.0.1:3001
}

#状态与日志

daemon.port                      # 控制通道端口（本机 TCP）
daemon.token                     # 控制通道共享令牌，0700 目录内
bm2d.pid                         # 守护进程 PID
bm2.events.jsonl                 # CLI 连接与重试事件
bm2d.log                         # 守护进程 stderr / 运行时诊断
bm2d.events.jsonl                # 守护进程与监督事件
<name>/project.json              # 每个项目的注册信息（配置路径）
<name>/<name>-<id>.json          # 持久化的实例状态
<name>/logs/<name>-<id>.out.log    # 应用 stdout
<name>/logs/<name>-<id>.error.log  # 应用 stderr
<name>/logs/<name>-<id>.crash.log  # 异常退出诊断

tail -f ~/.bm2/bm2d.events.jsonl
jq -c . ~/.bm2/bm2d.events.jsonl

#通知与上报

bm2 notify            # 在项目目录执行,给该项目所有目标发一条测试消息

#主配置

#上报条目 [[notify.report]]

[[notify.report]]
name = "健康巡检"
cron = "*/5 * * * *"       # 每 5 分钟
template = "health"

[[notify.report]]
name = "统计"
cron = "0 8 * * *"         # 每天 8:00
template = "stats"

#端点 [[notify.report.target]]

#事件与内容

#完整示例

[notify]
enabled = true
lang = "zh"
dedupe_window_s = 60
max_per_minute = 60
events = ["lifecycle", "daemon", "crash", "errored", "memory_limit",
          "reuseport_missing", "threshold", "oom_kill", "disk_pressure",
          "start_timeout"]
threshold_rss_percent = 80
start_timeout_ms = 30000
threshold_disk_mb = 1024

mail_url = "smtps://smtp.example.com:465"
mail_from = "bm2@example.com"
mail_username = "bm2@example.com"
mail_password = "${BM2_MAIL_PASSWORD}"

# 即时上报:故障 → 主群 + 值班邮件
[[notify.report]]
name = "故障告警"
events = ["crash", "errored", "memory_limit", "oom_kill", "disk_pressure", "reuseport_missing"]
min_level = "warn"

[[notify.report.target]]
platform = "feishu"
url = "${BM2_MAIN_WEBHOOK_URL}"

[[notify.report.target]]
platform = "email"
to = ["oncall@example.com"]
min_level = "error"

# 周期上报:健康巡检每 5 分钟 → 监控群
[[notify.report]]
name = "健康巡检"
cron = "*/5 * * * *"
template = "health"

[[notify.report.target]]
platform = "feishu"
url = "${BM2_REPORT_WEBHOOK_URL}"

# 周期上报:每日 8 点统计 → 报表群
[[notify.report]]
name = "每日统计"
cron = "0 8 * * *"
template = "stats"

[[notify.report.target]]
platform = "feishu"
url = "${BM2_STATS_WEBHOOK_URL}"

#上报行为

• 按项目隔离:每个项目只上报自己的事件,收件人只来自自己的配置;一个项目没配 [notify] 就完全不上报。
• 凭据零泄露:失败原因、事件日志、CLI 输出永不包含 url / secret / password;校验错误只报字段与下标。
• 即时上报:去重 → 限流 → 队列(丢最新保最旧)→ 重试(全败才重试,5s/15s 最多 3 次);发送成功静默。
• 周期上报:到点直发,不经去重限流;失败记事件日志不重试。
• 中文文案:lang = "zh" 后聊天消息为中文(启动/崩溃/统计报告等),bm2d started 等全部条目覆盖。