这是「Docker 好项目」系列的第 27 期。第 1 期写过 Uptime Kuma——它能告诉你「服务挂没挂」,但回答不了另一个问题:「这台机器跑得累不累」?CPU 是不是常年 90%、内存还剩多少、那块盘写到了几成、十几个容器里到底是谁在吃内存。这期介绍 Beszel——一个轻到 2GB 小盒子都扛得住的自托管服务器监控,hub + agent 两个容器,MIT 协议,Go 写的,界面是这系列里最好看的一档。

痛点开场
服务器监控这个需求,卡在两个极端中间:
- 裸奔派:什么都没装,出事了 SSH 上去敲
top、df -h,看完就走。问题是你不可能 24 小时盯着,内存泄漏这种「慢慢涨、某天突然 OOM」的剧本,top根本抓不到现场 - 重型装备派:Prometheus + Grafana + node_exporter 全家桶,功能确实全,但为了看个 CPU 曲线要维护三四个容器加一堆 YAML,2GB 内存的 NAS 装完直接没余量了
- Netdata 这类单体监控:每台机器都得装一个带 Web 界面的完整 agent,机器一多就是十几个界面各看各的,没有「所有主机一屏总览」的地方
- 云监控 SDK:厂商的云监控只覆盖自家机器,家里的 NAS、朋友的 VPS 管不着
Beszel 的定位卡得很准:hub-agent 架构,hub 是唯一带界面的(基于 PocketBase,单二进制 + SQLite),agent 是一个十几 MB 的纯采集端。所有主机在一个页面里横向对比,历史数据落在 hub 一台机器上。v0.21.0 于 2026-10-02 发布,26k stars,还在高频迭代。

能力边界
能干什么(以下来自官方文档与 v0.21.0 源码核实,不是 README 吹的)
- 主机指标:CPU、内存(含 swap 和 ZFS ARC)、磁盘用量与 I/O、网络流量、负载平均、温度、风扇转速、电池
- 容器级统计:只读挂载 docker.sock 后,自动发现所有 Docker/Podman 容器,每个容器的 CPU、内存、网络单独画线——排查「哪个容器在吃内存」就靠这张图
- 磁盘健康:S.M.A.R.T. 数据(含 eMMC 磨损度和 mdraid 阵列健康)+ ZFS 池容量/健康/scrub 状态。轻量归轻量,这两样它没偷懒
- 网络监测(agent 上发起):ICMP、TCP、HTTP、DNS 探测,v0.21.0 还加了 HTTPS 证书到期检查和自定义 DNS 服务器——第 1 期 Uptime Kuma 的部分活它现在也能干
- GPU:NVIDIA / AMD / Intel 的占用与功耗(NVIDIA 要换专用 agent 镜像,见下文)
- 告警:几乎所有指标都能设阈值(CPU/内存/磁盘/带宽/温度),外加状态类告警——系统离线、容器启停、systemd 服务挂了、ZFS 池不健康、SMART 报警
- 通知:基于 Shoutrrr,一个 URL 搞定一个通道——ntfy、Telegram、Discord、Slack、Gotify、Bark、Pushover、Lark(飞书)、Teams 等,设置页里每个 URL 都有 Test 按钮直接试发
- 多用户 + OAuth/OIDC:可以关掉密码登录只走 OIDC(可接第 20 期 Pocket ID);API 也有
不干什么
- 不做日志。要看容器日志请用第 22 期 Dozzle,Beszel 只管数字
- 历史数据最长 30 天。源码里保留分级是硬编码的(
internal/records/records_deletion.go):1 分钟粒度只留 1 小时、10 分钟留 12 小时、8 小时粒度留 30 天。想回看三个月前某个小时的内存曲线,它给不了 - 不做复杂可视化。没有 Grafana 那种自定义大屏,图表是固定的,好在每张都画得对
- agent 本身不做告警判断。所有阈值判断在 hub,hub 挂了告警就断了——它自己没有「监控自己的监控」这种套娃功能
部署前准备
| 项 | 说明 |
|---|---|
| 镜像 | hub:henrygd/beszel;agent:henrygd/beszel-agent(Docker Hub) |
| tag 规则 | 次版本 tag 真滚动:实测 0.21 == 0.21.0 == latest(digest 全同),历史 0.20==0.20.0、0.19==0.19.0 也一致。tag 不带 v 前缀(v0.21.0 实测 404)。本期推荐 :0.21,不想追 patch 就钉 :0.21.0。另注意 :0 这个大版本 tag 目前也指向 latest,别拿它当稳定锚 |
| 平台 | amd64 / arm64,飞牛 NAS 的 ARM 盒子、树莓派都能跑 |
| hub 端口 | 8090(镜像 EXPOSE 8090,CMD serve --http=0.0.0.0:8090) |
| hub 数据卷 | /beszel_data——SQLite 数据库 + 密钥全在这一个目录里 |
| agent 端口 | 45876(源码默认 :45876;LISTEN 变量可改,老写法 PORT 仍兼容) |
| agent 数据卷 | /var/lib/beszel-agent(存状态用,很小) |
| 基础镜像 | 两个都是 FROM scratch——容器里除了二进制什么都没有:没有 shell、没有 curl。健康检查必须用二进制自带的 health 子命令,排障靠 docker logs |
| 连接方式 | 两种:SSH 模式(hub 主动连 agent 的 45876,用 hub 生成的 ed25519 密钥对认证)或 WebSocket 模式(agent 主动外连 hub,配 HUB_URL + TOKEN)。细节见下文,家里没公网 IP 的重点看后者 |
想清楚一个架构问题再动手:hub 装在哪? 装在最常看的那台机器上(一般是家里常开的 NAS 或主服务器),agent 装到每一台要监控的机器。agent 本身占用极小(十几 MB 内存),放在哪里都不心疼。
docker run 一行版
hub(装在「看板机」上):
mkdir -p ./beszel_data && cd beszel
docker run -d --name beszel --restart unless-stopped \
-p 8090:8090 \
-e APP_URL=http://192.168.31.193:8090 \
-v $PWD/beszel_data:/beszel_data \
henrygd/beszel:0.21
APP_URL 建议在起容器前就想好——它决定 OAuth 回调、通知里的链接指向哪。内网裸 IP 跑就写 http://内网IP:8090,打算上域名就直接写最终域名,后面配反代不用改。
agent(装在每台被监控的机器上;KEY 先留占位,见「首次访问」):
docker run -d --name beszel-agent \
--network host \
--restart unless-stopped \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-e LISTEN=45876 \
-e KEY="ssh-ed25519 AAAA...hub页面生成的公钥" \
henrygd/beszel-agent:0.21
两个点:--network host 不是可省的——agent 要读宿主机网卡的真实流量,bridge 模式下流量统计全是 0;docker.sock 用只读挂载,拿到容器统计的权限就够了。
docker-compose 推荐版
hub 和 agent 在同一台机器(最常见的起步姿势,官方 same-system 模板改写):
services:
beszel:
image: henrygd/beszel:0.21
container_name: beszel
restart: unless-stopped
environment:
APP_URL: http://192.168.31.193:8090
ports:
- "8090:8090"
volumes:
- ./beszel_data:/beszel_data
- ./beszel_socket:/beszel_socket
# scratch 镜像没有 curl/wget,健康检查用二进制自带的子命令
healthcheck:
test: ["CMD", "/beszel", "health", "--url", "http://localhost:8090"]
interval: 120s
start_period: 10s
timeout: 5s
beszel-agent:
image: henrygd/beszel-agent:0.21
container_name: beszel-agent
restart: unless-stopped
network_mode: host
volumes:
- ./beszel_agent_data:/var/lib/beszel-agent
- ./beszel_socket:/beszel_socket
- /var/run/docker.sock:/var/run/docker.sock:ro
environment:
# 走 unix socket 而不是 TCP 端口,同机部署更干净
LISTEN: /beszel_socket/beszel.sock
HUB_URL: http://beszel:8090
TOKEN: "在hub的 /settings/tokens 页面创建"
KEY: "hub的Add System弹窗里给的公钥"
注意:同机部署不要让 hub 连 localhost:45876——两个容器网络不通,localhost 在各自容器里指自己。官方推荐的做法就是上面这样用 unix socket:agent 监听 /beszel_socket/beszel.sock,hub 里添加系统时 Host/IP 直接填这个路径。
hub 在 A 机、监控多台远程机器(agent 各自跑 compose):
services:
beszel:
image: henrygd/beszel:0.21
container_name: beszel
restart: unless-stopped
environment:
APP_URL: https://beszel.example.com
ports:
- "8090:8090"
volumes:
- ./beszel_data:/beszel_data
远程 agent(跑在被监控机上,SSH 模式):
services:
beszel-agent:
image: henrygd/beszel-agent:0.21
container_name: beszel-agent
restart: unless-stopped
network_mode: host
volumes:
- ./beszel_agent_data:/var/lib/beszel-agent
- /var/run/docker.sock:/var/run/docker.sock:ro
# 要看其他磁盘/分区,挂到 /extra-filesystems 下面(只读)
# - /vol1/.beszel:/extra-filesystems/vol1:ro
environment:
LISTEN: 45876
KEY: "hub的Add System弹窗里给的公钥"
不想在公网给 45876 开口?给 agent 加 HUB_URL 和 TOKEN 两个变量,它就会主动外连 hub(WebSocket 模式),SSH 端口一个都不用开。家里宽带是 CGNAT、没有公网 IP 的(比如家庭 NAS),这条是唯一正路——agent 在内网主动拨出去,hub 完全不用摸到你的内网。更彻底一点可以在 hub 侧设 BESZEL_HUB_DISABLE_SSH=true,把 SSH 回退通道也关掉,只认 WebSocket。
监控 NVIDIA GPU 的机器,agent 镜像换成 henrygd/beszel-agent-nvidia(还有 -intel、-alpine 等变体),官方仓库 supplemental/docker/ 下有对应模板。
配置项逐项解释
| 变量 | 推荐值 | 为什么这么写 |
|---|---|---|
APP_URL(hub) |
最终访问的完整 URL | 影响 OAuth 回调、通知消息里的链接。不设也能跑,但一上反代/域名就会出现「通知里的链接点不开」这类问题。hub 侧所有变量都支持 BESZEL_HUB_ 前缀写法(如 BESZEL_HUB_APP_URL),优先级更高 |
USER_EMAIL + USER_PASSWORD(hub) |
可选 | 启动前预建管理员。不设的话首次打开网页手动建(见下文)。想无人值守初始化(比如写在自动化脚本里)就靠这两个变量 |
DISABLE_PASSWORD_AUTH(hub) |
接了 OIDC 后设 true |
关掉密码登录,只留 OAuth/OIDC。第 20 期 Pocket ID 用户可以串起来:公网暴露的监控面板,密码爆破面直接归零 |
SYNC_SYSTEM_NAMES(hub,设 true) |
可选 | 系统名自动跟主机名同步,加了新 agent 不用回网页改名。v0.21.0 新增 |
LISTEN(agent) |
45876 或 unix socket 路径 |
监听地址。源码解析顺序:命令行参数 > LISTEN > 老的 PORT > 默认 :45876。以 / 开头自动按 unix socket 处理 |
KEY(agent) |
hub 公钥 | SSH 模式的信任锚:hub 私钥签、agent 验公钥。没它 hub 连不上(WebSocket 模式可无) |
HUB_URL + TOKEN(agent) |
WebSocket 模式必填 | agent 主动外连 hub 的地址和凭证。CGNAT/防火墙后面机器的唯一选择。agent 侧同样支持 BESZEL_AGENT_ 前缀 |
NETWORK(agent) |
一般不用设 | unix 或 tcp。默认按 LISTEN 值的格式自动判断,只有监听特殊地址才需要显式给 |
| docker.sock(挂载) | :ro 只读 |
容器统计的数据源。不想给监控碰 docker.sock,可以不挂——损失容器级统计,主机指标照常 |
/extra-filesystems(挂载) |
想监控的额外盘 | agent 默认只报根分区。像飞牛那种数据在 /vol1(RAID/btrfs)上的,把挂载点只读挂进来才能看到真实用量 |
1Panel 面板怎么搞
好消息:1Panel 应用商店里就有 Beszel(实测收录,当前版本 0.21.0,分类「实用工具」),hub 直接从商店装,省掉建编排的功夫。装完在「容器」里能看到 beszel 服务,日志和升级都在面板里点。
agent 商店管不着(它要装到每一台被监控机上),手动走「容器 → 编排」:
- 先在宿主机建目录:
mkdir -p /opt/beszel-agent/beszel_agent_data。Docker 会以 root 创建缺失的 bind mount 目录,先建好能避免权限绕不清 - 创建编排,名字填
beszel-agent,把上面远程 agent 的 compose 贴进去,KEY换成真实公钥 - 公网机器注意防火墙:SSH 模式要在面板防火墙放行 45876(最好限定来源只放行 hub 那台机器的 IP);WebSocket 模式则什么都不用开
- 起来后
docker logs -f beszel-agent看到Listening on :45876(或 socket 路径)即成功
hub 是 scratch 镜像,docker exec -it beszel sh 进不去(没有 shell),排障看 docker logs,管理操作全在网页里。
首次访问
浏览器打开 http://服务器IP:8090,第一屏就是建管理员账号——邮箱 + 密码,建完直接登录。这个账号存的就是 PocketBase 的超管,密码丢了没有找回流程,进密码管理器。
点右上角 Add System,弹窗里三样东西一次给齐:
- Name:这台机器叫什么(随便起,
fnos-nas、huawei-cloud都行) - Host / IP:agent 的地址——远程机器填 IP,同机 unix socket 部署填
/beszel_socket/beszel.sock - Port:默认 45876
弹窗同时给出公钥(ssh-ed25519 AAAA... 开头)和现成的 agent 部署命令(docker run / compose 都有,内容已经把你的 KEY 填好了)——复制到目标机器执行就行,这是 Beszel 体验最好的地方:加机器的命令是按你的实际配置现场生成的,不用回文档查参数。
保存后十几秒内系统状态翻绿,数据开始进来。翻绿失败先看 agent 日志和两边防火墙。
最小可用配置
上面的 compose 就是全部——Beszel 没有配置文件,指标采集零配置,agent 起来就开始报。上手路径:
- 总览页横向对比所有机器,哪台 CPU/内存/磁盘异常一眼可见
- 点进某台机器,细节全在:CPU、内存、磁盘 I/O、带宽、温度、GPU、每个容器的 CPU 和内存堆叠图
- 历史区间右上角切换(1 小时到 30 天)

(图为官方单机详情页截图:左列主机指标,右列 Docker 容器堆叠图——排查「谁在吃内存」就看右下那张。)
被监控机不是 Docker 也有办法:官方安装脚本直接装二进制 + systemd 服务,还带 --china-mirrors 参数解决 GitHub 下载慢的问题:
curl -sL https://get.beszel.dev -o /tmp/install-agent.sh && chmod +x /tmp/install-agent.sh \
&& /tmp/install-agent.sh -k "ssh-ed25519 AAAA...公钥" --china-mirrors
告警/通知配置
两层结构:先在 Settings → Notifications 配「发到哪」,再回到系统列表点铃铛图标配「什么情况发」。

(图为官方通知设置截图:Webhook / Push 部分每行一个 Shoutrrr URL,右侧 Test URL 一键试发。)
通知走 Shoutrrr 协议,一行 URL 一个通道。配第 13 期的 ntfy:
ntfy://ntfy.example.com/服务器告警主题
Telegram:
telegram://123456:BOT-TOKEN@telegram?chats=@你的频道
填完点 Test URL 立刻验证,不用等真出事。源码里确认 ntfy 通道会自动带上「查看详情」的 Actions 按钮,手机上点一下直达面板。
然后是告警规则(系统列表里点对应系统的铃铛):
| 告警类型 | 典型配置 |
|---|---|
| CPU / 内存 / 磁盘 / 温度 / 带宽 | 大于阈值持续 N 分钟(比如内存 > 85% 持续 10 分钟) |
| Status | agent 失联 N 秒(机器断电/宕机第一时间知道) |
| 容器状态 | 某容器停止时告警(第 22 期 Dozzle 看日志,这里管「它死了」) |
| SMART / ZFS | 盘健康出问题、ZFS 池降级时告警 |
个人的最小配置建议就三条:内存 > 85%、磁盘 > 90%、系统离线——前两条覆盖慢性病,第三条管猝死。2GB 内存还跑着一堆容器的机器(说的就是某些 NAS),内存告警几乎是刚需。
反向代理与 HTTPS
hub 是普通 HTTP 服务,没有 WebSocket 硬依赖(agent 反连走的是 hub 的 WebSocket 端点,但那对反代是标准升级请求,nginx/NPM 都正常透传)。
1Panel / 手写 nginx 最小配置:
server {
listen 443 ssl;
server_name beszel.example.com;
# ssl_certificate / ssl_certificate_key 略
location / {
proxy_pass http://127.0.0.1:8090;
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;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
Upgrade/Connection 两行是给 agent 的 WebSocket 反连用的;SSH 模式用户不加也能用,加了更稳。
第 2 期 Nginx Proxy Manager 用户:Proxy Host 转发到 服务器IP:8090,SSL 页签申请证书 + Force SSL,Websockets 开关勾上即可。
上完 HTTPS 记得把 APP_URL 同步改成 https://beszel.example.com 并重启 hub。公网部署强烈建议再走一步:接 OIDC(设置里配 Provider)然后 BESZEL_HUB_DISABLE_PASSWORD_AUTH=true 关掉密码登录。
踩坑清单
- 同机部署 hub 连不上 agent——
localhost:45876在容器网络里指自己。用官方 unix socket 方案(compose 见上文),或 Host/IP 填宿主机内网 IP - agent 流量图一直是 0——没加
--network host。bridge 模式下 agent 只能看到自己的虚拟网卡,必须 host 网络才能读到宿主机网卡统计 - 家里没公网 IP,hub 一直连不上 agent——SSH 模式要求 hub 能主动连到 agent 的 45876,CGNAT 后面这条路天然不通。改 WebSocket 模式:agent 配
HUB_URL+TOKEN主动外连,hub 侧顺手设BESZEL_HUB_DISABLE_SSH=true docker exec beszel sh报 executable file not found——scratch 镜像没有 shell。健康检查用/beszel health --url ...和/agent health子命令- 照抄老教程的
PORT=45876——新写法是LISTEN(PORT只是兼容保留)。变量名变过不止一次的还有 agent 数据目录,老文章里见到的别的路径以官方 compose 为准 - tag 写成
v0.21.0拉不到镜像——Beszel 的 Docker tag 没有 v 前缀,v0.21.0实测 404,正确写法0.21.0或滚动的0.21 - 数据盘看不到——agent 默认只报根分区。额外挂载点要挂进容器的
/extra-filesystems/下(只读),UI 里才会多出来 - 想改历史数据保留期——改不了,分级硬编码在源码里,最细粒度只留 1 小时、最长 30 天。要长期归档得自己定期导出,或接受「Beszel 只看近期趋势」的定位
- 升级 hub 后 agent 版本号对不上——hub 和 agent 建议同步升级(都是
0.21跟着走就行),跨多个小版本混搭一般兼容,但告警规则这类新特性可能两边行为不一致 - 公网暴露 8090 前——至少做三件事:改强密码、上 HTTPS、接 OIDC 关密码登录。监控面板能看到你所有机器的 IP 和负载情况,别让它裸奔
备份
Beszel 的全部状态就在 beszel_data 一个目录里(SQLite + 密钥对),备份两层:
内置备份(推荐):网页右上角 → Settings → Backups,可以定时备份到本机磁盘或任意 S3 兼容存储,恢复也在同一页面点一下。定期任务 + 异地 S3,这条链路不用自己搭。
暴力方案:
docker stop beszel && tar czf beszel-$(date +%F).tar.gz beszel_data && docker start beszel
agent 没什么可备份的(beszel_agent_data 里只有少量状态,删了重建也无妨)。把备份产物喂给第 21 期 Kopia 做异地同步,这个系列的老链路了。
小结
适合谁:手里有两台以上机器(家里 NAS + 云上 VPS 是最典型组合)、想要一屏看清所有主机家底的人;被 Prometheus 全家桶的资源占用劝退过的人;2GB 小内存设备也想被监控的(agent 内存占用十几 MB);已经在用 Uptime Kuma 但发现「服务活着、机器快死了」这种盲区的人。
不适合谁:只需要探测几个 URL 存活状态的(Uptime Kuma 更简单,别为这个上 hub-agent 架构);要自定义大屏、长期归档历史数据的(上 Grafana + Prometheus 或 VictoriaMetrics);要在监控里看日志、做链路追踪的(那是 Dozzle 和 Observability 全家桶的活)。
一句话定位:它是「每台机器的家底账本」,不是「全链路观测平台」——把这几十 MB 的轻活干好,就已经是同类里最省心的了。
项目地址
- GitHub:https://github.com/henrygd/beszel(MIT,当前 v0.21.0,2026-10-02 发布)
- 官网与文档:https://beszel.dev/
- 镜像:
henrygd/beszel:0.21(hub)、henrygd/beszel-agent:0.21(agent) - 1Panel 应用商店:已收录(「实用工具」分类,装 hub 用,agent 手动编排)