Beszel Hub 保存系统、用户、历史数据和告警；Agent 负责采集所在服务器的 CPU、内存、负载、磁盘、网络、温度以及 Docker/Podman 容器指标。

它适合家庭实验室、小团队和十几台以内的 VPS 快速监控。需要复杂 PromQL、长期指标聚合或业务自定义指标，还是看VPS Prometheus + Grafana 教程。只关心网站能不能打开和公开状态页，用Uptime Kuma更直接。

还有一个现实问题：Hub 和被监控服务放在同一台 VPS，这台机器彻底离线时，Hub 也发不出通知。重要环境最好让 Hub 独立运行，或者启用 Beszel 的外部 Heartbeat，把状态推给另一个监控服务。

Beszel 官方没有给死最低配置。个人使用可以从 1 核、1GB 内存和 10GB 空闲磁盘起步，真正影响磁盘的是节点数量与历史保留时间，不要把它当成保证值。

准备一个域名，例如 monitor.example.com，A/AAAA 记录指向 Hub VPS。端口按连接方式开放：

远程 VPS 默认建议用 WebSocket：Agent 主动连 Hub 的 HTTPS 地址，不必向公网开放 45876。若选择 SSH 模式，则把 Agent 的 45876 只放行给 Hub IP。防火墙修改前可先看UFW 防止 SSH 锁死教程。

部署前先记录基线，后面看到曲线才知道是否异常：

free -h
df -h
uptime
docker system df
timedatectl status

磁盘已经接近满载时，不要指望监控容器自己救场；先处理日志和备份。系统时间也要准确，否则多台 VPS 的图表和告警时间会对不上。准备监控二十台以上服务器时，先用少量节点跑一周，再根据 beszel_data 的实际增长决定磁盘和保留策略，比照搬别人的容量数字可靠。

先装好 Docker Engine 和 Compose 插件，再创建目录：

sudo mkdir -p /opt/beszel
sudo chown "$USER":"$USER" /opt/beszel
cd /opt/beszel
mkdir -p beszel_data beszel_agent_data beszel_socket

新建 docker-compose.yml。Agent 先保留占位值，第一次只启动 Hub：

services:
  beszel:
    image: henrygd/beszel:0.18.7
    container_name: beszel
    restart: unless-stopped
    environment:
      APP_URL: https://monitor.example.com
    ports:
      - 127.0.0.1:8090:8090
    volumes:
      - ./beszel_data:/beszel_data
      - ./beszel_socket:/beszel_socket

  beszel-agent:
    image: henrygd/beszel-agent:0.18.7
    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: http://localhost:8090
      TOKEN: YOUR_SYSTEM_TOKEN
      KEY: "YOUR_SYSTEM_PUBLIC_KEY"

检查配置并只启动 Hub：

docker compose config
docker compose up -d beszel
docker compose ps
docker compose logs --tail=100 beszel
curl -I http://127.0.0.1:8090

镜像版本可从官方 Releases 核对。升级时再改标签，不要让一次重建悄悄跨版本。生产 Compose 的健康检查、日志和资源限制可参考Docker Compose 生产配置清单。

Beszel 的 Agent 可通过 WebSocket 连 Hub，反向代理必须允许长连接。Caddy 配置不能只写最短的一行，官方示例还设置了请求体大小和 360 秒读取超时：

monitor.example.com {
    request_body {
        max_size 10MB
    }
    reverse_proxy 127.0.0.1:8090 {
        transport http {
            read_timeout 360s
        }
    }
}

验证并重载：

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
curl -I https://monitor.example.com
sudo ss -lntup | grep -E ':443|:8090|:45876'

8090 应只监听 127.0.0.1。完整安装过程见Caddy 反向代理指南。APP_URL 必须写最终 HTTPS 地址，它会用于通知链接和 Agent 配置生成。

打开 https://monitor.example.com，创建第一个账户。Beszel 基于 PocketBase，初始设置会同时创建 Hub 用户与 PocketBase superuser；两套账户后续修改密码并不会自动同步，密码管理器里最好分开标记。

点击右上角 Add System，填写系统名称，把 Host/IP 设置为：

/beszel_socket/beszel.sock

界面会给出 Public Key 和 Token。把它们分别替换 Compose 中的 KEY 和 TOKEN，再启动本机 Agent：

docker compose up -d beszel-agent
docker compose logs --tail=100 beszel-agent
docker compose ps

看到系统从 Pending 变成 Up，并出现第一组 CPU 与内存数据，才算接入完成。不要把真实 Key、Token 或通知 URL 提交到 Git 仓库。

远程节点最省事的是在 Hub 的 Add System 页面复制生成的 Compose。WebSocket 模式由 Agent 主动访问 Hub，可使用下面的结构：

services:
  beszel-agent:
    image: henrygd/beszel-agent:0.18.7
    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
    environment:
      HUB_URL: https://monitor.example.com
      TOKEN: YOUR_SYSTEM_TOKEN
      KEY: "YOUR_SYSTEM_PUBLIC_KEY"
      DISABLE_SSH: "true"

DISABLE_SSH=true 表示只用 WebSocket，不再启动 Agent 的 SSH 服务。若改用 SSH 模式，连接方向相反：Hub 主动访问 Agent 的 45876；严格的 iptables FORWARD DROP 还可能阻止 Hub 容器出站，此时切回 WebSocket 更好排查。

每个节点使用自己的系统 Token，不要多台机器复制同一份 Agent 数据目录。服务器迁移后若指纹变化，应在 Hub 中确认目标节点再重新注册，而不是反复重启碰运气。

Agent 通过 Docker Socket 读取容器列表和统计数据，先比较两边输出：

docker ps
docker stats --no-stream
docker compose logs --tail=150 beszel-agent
ls -l /var/run/docker.sock

常见原因是 Socket 路径不对、Podman 使用另一条 Socket、Agent 没有重新创建，或容器被 EXCLUDE_CONTAINERS 排除。修改挂载后执行：

docker compose up -d --force-recreate beszel-agent

:ro 只限制容器内文件系统的挂载方式，并不能把 Docker Socket 变成低权限接口；能访问 Socket 的进程通常拥有很高的主机控制能力。不要把 Docker API 裸露到 0.0.0.0:2375，也不要为了看指标直接给 Agent privileged: true。

在系统列表打开告警，先设置离线、磁盘、内存或 CPU 阈值。阈值别照抄：一台长期 80% 内存但没有 Swap 抖动的数据库，和突然从 30% 涨到 80% 的 Web 服务不是一回事。

通知入口在 Settings > Notifications，Beszel 使用 Shoutrrr URL。比如自建 ntfy 可写：

ntfy://:[email protected]/beszel-alerts

保存后先发测试通知，再把某个非生产节点的阈值短暂调低，确认告警触发和恢复都能收到。通知 URL 本身含凭据，截图和日志分享前要打码。若 Hub 与通知服务也在同一台故障 VPS，告警依然送不出去。

Beszel 还支持向外部地址周期发送 Heartbeat。把 HEARTBEAT_URL 指向另一套 Uptime Kuma、Healthchecks.io 或类似服务后，即使 Hub 整体失联，外部服务也能发现心跳中断。它不是资源告警的替代品，而是专门盯住“监控系统本身死了没人知道”这个盲区。配置后要停一次测试环境的 Hub，确认外部告警确实触发，再恢复服务。

核心数据在 /opt/beszel/beszel_data。管理后台支持保存到磁盘或 S3 兼容存储，但仍要定期做一次可恢复验证。简单的停机备份可以这样做：

cd /opt/beszel
backup_date="$(date +%F)"
docker compose stop beszel
sudo tar -czf "/var/backups/beszel-${backup_date}.tar.gz" \
  beszel_data docker-compose.yml
docker compose start beszel
sudo tar -tzf "/var/backups/beszel-${backup_date}.tar.gz" | head
curl -I https://monitor.example.com

压缩包还要复制到另一台机器或对象存储。正式操作可结合VPS 备份恢复演练。

升级前看 Releases，备份完成后修改 Hub 和 Agent 的同一版本标签：

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 beszel
docker compose logs --tail=100 beszel-agent

页面、一个本机 Agent 和一个远程 Agent 都正常后再结束维护。失败时恢复原镜像标签；若新版本已经修改数据结构，再恢复同一升级前备份，别只降镜像硬顶。

上线前再做一轮验收：重启 Docker 后 Hub 与 Agent 应自动恢复；关闭一台测试 Agent，离线告警应按预期到达；恢复后状态应重新变绿；从另一台机器解压备份，至少能看到 PocketBase 数据和 Compose 文件。只看首页有曲线，不代表告警、持久化和恢复链路都能用。

• 想快速看多台服务器和 Docker 资源：选 Beszel；
• 想监控 URL、证书到期和公开状态页：选 Uptime Kuma；
• 想采集业务指标、写复杂查询和长期扩展：选 Prometheus + Grafana。

Beszel 的优势是部署轻、上手快，短板是定制查询和生态不如 Prometheus。先接一台非关键 VPS，制造一次测试告警，再做一份能解压的异机备份；这三步都通过后，再把生产节点批量加进去。