Beszel：轻量服务器监控｜Hub+Agent 架构部署与告警配置

监控这件事，Prometheus + Grafana 是标准答案，但为了看几台 VPS 的 CPU 和内存，装一整套 TSDB + 查询引擎 + 面板，实在有点重。Beszel 走的是另一条路：Hub 一个进程、Agent 一个进程，加起来占几十兆内存。

一、项目介绍

官方 README 的定义：Beszel is a lightweight server monitoring platform that includes Docker statistics, historical data, and alert functions。

从架构上说，它只有两个组件：

• Hub：基于 PocketBase 的 Web 应用，负责展示和管理
• Agent：跑在每台被监控的机器上，负责采集指标并推给 Hub

这个拆分很关键——Hub 和 Agent 是解耦的。你可以在 A 机器上跑 Hub，在 B、C、D 上只装 Agent；也可以两个都跑在同一台机器上，通过 Unix Socket 通信（官方 compose 默认就是这个方式）。

技术栈是 Go + PocketBase（后端） + Svelte（前端）。PocketBase 自带 SQLite，所以 Hub 不需要外部数据库，一个数据目录就够。

仓库 2.6 万 star，MIT 许可，最近提交 2026 年 11 月 1 日，维护很活跃。

二、功能拆解

核心能力

• Lightweight：官方原话是「比主流方案更小、更省资源」。实测 Hub 常驻内存几十 MB，Agent 更少
• Simple：官方强调「几乎不需要手动配置」，加一台机器就是复制一份 compose 改两个变量
• Alerts：大多数指标都能配告警，支持多种通知渠道
• Docker stats：单独追踪每个容器的 CPU、内存、网络历史曲线，这是很多人选它的理由
• Network monitoring：直接从 agent 侧发起探测，监控响应时间和中断
• S.M.A.R.T.：硬盘健康数据，盘要挂了提前知道

多人协作与认证

• Multi-user：每个用户管自己的系统，管理员可以把系统共享给其他用户
• OAuth / OIDC：支持多种 OAuth2 提供商，可以关掉密码登录，适合已经有统一认证的团队
• Automatic backups：自动备份到磁盘或 S3 兼容存储

支持的指标

官方 README 列得很全，这决定了它能替代掉多少别的工具：

一句话取舍：它是「够用的监控」，不是「全能的 APM」。要做分布式链路追踪、日志检索，还得上 SigNoz、Grafana 那套；只想知道机器有没有被挖矿、磁盘会不会满，Beszel 的复杂度刚好。

三、官方链接

• GitHub 仓库：https://github.com/henrygd/beszel
• 官网与文档：https://beszel.dev
• 快速开始：https://beszel.dev/guide/getting-started
• 常见问题：https://beszel.dev/guide/common-issues
• 镜像：henrygd/beszel（Hub）、henrygd/beszel-agent（Agent）
• 社区：GitHub Discussions、Matrix 房间 #beszel:matrix.org

四、环境要求

一个容易忽略的点：官方 compose 里 Agent 用了 network_mode: host，并挂载 /var/run/docker.sock。前者是为了拿到宿主机真实网卡指标，后者是为了统计容器。这两个配置不要随意改，改了会丢指标。

另外，如果被监控机器是 LXC 容器或没有独立内核的环境，部分指标（温度、S.M.A.R.T.）拿不到，属于正常现象。

五、部署步骤

官方文档的流程分五步：起 Hub → 建管理员 → 添加系统 → 起 Agent → 回填配置。顺序不能乱，因为 KEY 和 TOKEN 是第三步才生成的。

第一步：创建目录与 compose 文件

mkdir beszel
cd beszel

创建 docker-compose.yml，内容用官方给的那份（完整版，含本地 Agent）：

services:
  beszel:
    image: henrygd/beszel:latest
    container_name: beszel
    restart: unless-stopped
    environment:
      APP_URL: 
    ports:
      - 8090:8090
    volumes:
      - ./beszel_data:/beszel_data
      - ./beszel_socket:/beszel_socket
    # healthcheck:
    #   test: ['CMD', '/beszel', 'health', '--url', '']
    #   interval: 120s
    #   start_period: 10s
    #   timeout: 5s

  beszel-agent:
    image: henrygd/beszel-agent:latest
    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:
      LISTEN: /beszel_socket/beszel.sock
      HUB_URL: 
      TOKEN: <token>
      KEY: "<key>"
    # healthcheck:
    #   test: ['CMD', '/agent', 'health']
    #   interval: 120s

注意 APP_URL：官方说明要改成你实际访问 Hub 的地址。如果走域名反代，就写 https://beszel.your-domain.tld；如果是 IP 直连且带端口，就写 http://1.2.3.4:8090。这个值影响面板里的链接和部分跳转。

TOKEN: <token> 和 KEY: "<key>" 先保持原样，第三步会拿到真值。

第二步：先只启动 Hub

因为 Agent 还缺 KEY，此时直接 up -d 会看到 Agent 反复重启。正确做法是先只起 Hub：

docker compose up -d beszel

确认 Hub 起来了：

docker ps --filter name=beszel
curl -I 

第三步：创建管理员账号

浏览器打开 http://<服务器IP>:8090，会直接跳到创建账号页面。填邮箱和密码，这就是管理员。

第四步：添加第一个系统，拿 KEY 和 TOKEN

登录后点右上角 Add System，打开创建系统的对话框。

这里有个关键选择：Host / IP 填什么。

• 本地 Agent（官方 compose 默认）：填 Unix Socket 路径 /beszel_socket/beszel.sock
• 远程 Agent：填那台机器的 IP，端口用 Agent 的监听端口

官方文档明确写了：用本地 socket 这种方式时，Host/IP 就填 /beszel_socket/beszel.sock。

对话框里同时会显示这个系统专属的 Public Key 和 Token。把它们记下来。

0.12.0 之后官方还提供了另一种方式：在 /settings/tokens 创建 universal token，Agent 用这个通用 token 连 Hub，不用提前生成系统配置。适合批量加机器的场景。

第五步：把 KEY / TOKEN 填进 compose，启动 Agent

回到 docker-compose.yml，把占位符替换掉：

    environment:
      LISTEN: /beszel_socket/beszel.sock
      HUB_URL: 
      TOKEN: 你复制到的token
      KEY: "你复制到的key"

注意 KEY 要用双引号包起来——它是一段多行的 SSH 私钥，不加引号 YAML 会解析失败。

docker compose up -d
docker compose logs -f beszel-agent

第六步：完成添加

Agent 起来后，回到刚才的对话框点 Add System。列表里出现这台机器，状态变绿就通了；变红说明 Agent 没连上，看第九节的排查。

加监控第二台机器（远程 Agent）

Hub 已经跑通后，给另一台机器装 Agent：

1. Hub 里 Add System，Host/IP 填那台机器的 IP（不是 socket 路径）
2. 复制对话框里给的 Agent compose 内容，在那台机器上 docker compose up -d
3. 回 Hub 点 Add System

远程 Agent 的 compose 与本地版差别在：LISTEN 是一个端口而不是 socket 文件，HUB_URL 指向 Hub 的真实地址。官方建议直接复制对话框里生成的那份，不用自己改，因为里面已经带好了该系统的 KEY 和 TOKEN。

也可以用二进制方式装 Agent（仅 Linux）：

# 命令从 Add System 对话框里复制，形如：
curl -sL https://get.beszel.dev -o /tmp/install-agent.sh && ...

官方说明这个脚本会做四件事：下载对应架构的二进制、创建 beszel 用户、启动 Agent、创建开机自启服务，并且可选开启每日自动更新。不要凭记忆拼这条命令，从对话框里复制最稳妥。

反代与 HTTPS（可选）

Hub 放公网建议加 HTTPS：

beszel.your-domain.tld {
    reverse_proxy 127.0.0.1:8090
}

配好后记得把 compose 里的 APP_URL 改成 https://beszel.your-domain.tld，然后 docker compose up -d 重启 Hub。

六、配置参数详解

Hub

Hub 的绝大部分配置都在 Web 界面里：用户、通知渠道、OAuth 提供商、备份目标、告警规则。这些不需要改文件。

Agent

卷挂载（别改错）

beszel_data 是唯一必须备份的目录。

七、启动与运维

# 整体启停
docker compose up -d
docker compose stop
docker compose down

# 分开操作（很常用，因为要先起 Hub 再起 Agent）
docker compose up -d beszel
docker compose up -d beszel-agent

# 日志
docker compose logs -f beszel
docker compose logs -f beszel-agent

# 资源占用（顺便验证「轻量」这个说法）
docker stats beszel beszel-agent

备份：

# 停 Hub 后打包最稳
docker compose stop beszel
tar czf beszel-$(date +%F).tar.gz beszel_data/
docker compose start beszel

Beszel 自己也支持在设置里配自动备份到磁盘或 S3 兼容存储，生产环境建议开上。

告警配置：在 Hub 的设置里加通知渠道（支持多种服务），然后在每个系统的设置里给具体指标配阈值。阈值是按系统单独设的，不是全局默认，加机器时别忘了配。

八、实操验证

1. 两个容器都在跑

docker ps --filter name=beszel --format 'table {{.Names}}\t{{.Status}}'

预期两行，都 Up。beszel-agent 如果反复 Restarting，先看第九节第一条。

2. Hub 端口通

curl -I 

返回 200 或 302。

3. 面板能登录

浏览器打开 http://<IP>:8090，用第二步建的账号登录，能看到系统列表。

4. 系统状态是绿色

列表里那台机器的状态点变绿，说明 Agent 已经连上并开始上报。点进去应该能看到 CPU、内存、磁盘的实时曲线。

5. 容器指标有没有

点进系统详情，找 Containers 区域。如果这里是空的，但 CPU 曲线正常，说明 /var/run/docker.sock 没挂对，或者当前用户没权限读 socket。

6. 历史数据是否在累积

等 10 分钟，把时间范围切到「1 小时」，看曲线是不是连续的。PocketBase 的 SQLite 在 beszel_data/ 里，确认它没有被写到容器临时层：

ls -lh beszel_data/

应该能看到 .db 文件，且几分钟内文件大小有增长。

7. 告警是否生效

故意把 CPU 告警阈值调到 1%，等一个采集周期，看通知渠道有没有收到。验证完记得改回去。

九、故障排查

Agent 反复重启 / 日志里报认证失败

按顺序检查：

1. TOKEN 和 KEY 是不是从当前这个系统的对话框复制的？不同系统的 token 不通用，复制串了就必然失败
2. KEY 有没有加双引号？多行私钥不加引号，YAML 解析就出错
3. 私钥缩进有没有被编辑器改坏？如果用的是 KEY: | 多行文本块写法，每一行的缩进要一致

看具体报错：

docker compose logs beszel-agent | tail -50

系统状态一直是红色

先确认 Agent 到 Hub 的网络：

# 在 Agent 所在机器上
docker exec beszel-agent wget -qO- http://<hub-ip>:8090/api/health

不通就是网络或防火墙问题。远程 Agent 还要确认 Hub 那边能反向访问到 Agent 的监听端口——Beszel 的通信是双向的，只放行一个方向不够。

容器指标空白

# 确认 socket 挂进去了
docker inspect beszel-agent --format '{{range .Mounts}}{{.Source}} -> {{.Destination}}{{"\n"}}{{end}}'

要能看到 /var/run/docker.sock -> /var/run/docker.sock。没有的话检查 compose 的 volumes 段。

温度、风扇、S.M.A.R.T. 没有数据

这几个指标依赖宿主机内核接口（/sys/class/hwmon、smartctl）。三种常见原因：跑在 LXC/OpenVZ 容器里没有权限、虚拟机没有暴露传感器、物理机上没装 smartmontools。

# 物理机上装一下
apt install -y smartmontools

页面能开但没有历史曲线

beszel_data 挂载失败，数据写进了容器临时层。检查：

ls -la beszel_data/

目录为空说明挂载路径不对。改成绝对路径再试。

加了域名反代后登录跳转异常

APP_URL 还写着 。改成实际域名后重启 Hub。

十、升级、回滚与卸载

升级

cd beszel
docker compose pull
docker compose up -d

Hub 和 Agent 建议一起升。Hub 从 0.12.0 起支持 universal token，新旧版本混用时 token 机制可能有差异，同版本最稳。

升级前备份 beszel_data/。

回滚

镜像标签改成具体版本：

image: henrygd/beszel:0.11.1
image: henrygd/beszel-agent:0.11.1

docker compose up -d

如果新版本已经迁移了数据库结构，回滚要把升级前的 beszel_data/ 一起还原，否则旧版本可能读不了新库。

卸载

cd beszel
docker compose down
docker rmi henrygd/beszel henrygd/beszel-agent
rm -rf beszel

远程机器上的 Agent 单独清：

# compose 方式
docker compose down && rm -rf beszel-agent

# 二进制方式（官方脚本装的）
systemctl stop beszel-agent
systemctl disable beszel-agent
rm -f /etc/systemd/system/beszel-agent.service
userdel beszel
systemctl daemon-reload

十一、商用许可

Beszel 使用 MIT 许可证，是几种常见开源协议里最宽松的一种。

要点：

• 可以商用，内部部署、给客户部署都行，不需要付费、不需要授权
• 可以修改，改成什么样都可以
• 可以闭源分发，把改过的版本打包进自己的商业产品也不需要开源
• 唯一义务：分发时保留原始的版权声明和许可证文本
• 不提供任何担保

也就是说，如果你想基于 Beszel 做一个「带自己品牌 logo 的监控面板」卖给客户，MIT 完全允许，只要别把原作者版权声明删掉。这是它和一些 AGPL 项目（比如前面的 Glance、Vaultwarden）最大的区别，做商业产品选型时这一点值得纳入考量。