Jul 28, 2026

Beszel轻量级服务器监控部署文档

一、部署目标

使用 Beszel 统一监控多台 Linux 服务器，重点采集：

宿主机 CPU、内存、Swap、负载；
磁盘使用率、磁盘 IO；
网络上传和下载；
Docker 容器状态；
Docker 容器 CPU、内存和网络；
服务器在线状态；
systemd 服务状态；
CPU、内存、磁盘和服务器离线告警。

Beszel由两个组件组成：

┌──────────────────────────┐
│ Beszel Hub               │
│ Web页面、历史数据、告警   │
│ 监听：8090               │
└────────────┬─────────────┘
             │ HTTPS / WebSocket
             │ Agent主动连接Hub
       ┌─────┴─────┬───────────┐
       │           │           │
┌──────▼─────┐ ┌───▼────────┐ ┌▼───────────┐
│服务器1      │ │服务器2      │ │服务器3      │
│Binary Agent│ │Binary Agent│ │Binary Agent│
│Docker监控   │ │Docker监控   │ │Docker监控   │
└────────────┘ └────────────┘ └────────────┘

Beszel原生支持宿主机和Docker/Podman容器的CPU、内存、网络、磁盘、负载等指标，并提供历史数据和告警功能。

二、推荐部署方式

2.1 Hub部署方式

在一台稳定服务器上使用Docker Compose部署：

Beszel Hub：Docker
数据目录：/opt/beszel/data
内部端口：8090
外部访问：Nginx HTTPS

2.2 Agent部署方式

每台被监控服务器安装：

Beszel Agent：原生二进制
进程管理：systemd
连接方式：WebSocket
Docker监控：读取 /var/run/docker.sock

二进制Agent安装脚本会创建beszel用户和systemd服务，Agent进程本身不会以root身份运行。

2.3 为什么使用WebSocket

Beszel支持两种通信模式：

SSH模式：Hub主动访问Agent的45876端口；
WebSocket模式：Agent主动连接Hub。

本方案使用WebSocket，优点是：

Agent服务器不用开放45876端口；
只需要Agent能够访问Hub；
更适合跨网段、云服务器和存在防火墙的环境；
可以关闭Agent自带SSH监听服务。

WebSocket连接会使用Token、Hub签名和Agent机器指纹进行双向认证。

三、端口规划

位置	端口	方向	用途
Beszel Hub	8090	本机内部	Hub Web服务
Nginx	443	Agent及管理员访问	HTTPS和WebSocket
Nginx	80	可选	跳转到HTTPS
Agent	45876	不开放	WebSocket模式下关闭SSH监听

推荐的网络关系：

管理员电脑 ──HTTPS 443──> Nginx ──> Beszel Hub 8090
Agent服务器 ─HTTPS 443──> Nginx ──> Beszel Hub 8090

四、环境信息示例

部署前确定以下信息：

Hub服务器IP：192.168.10.20
访问域名：monitor.example.com
Hub安装目录：/opt/beszel
数据目录：/opt/beszel/data
Agent系统：Rocky Linux / AlmaLinux / CentOS / Ubuntu

以下命令中的：

monitor.example.com
192.168.10.20
<PUBLIC_KEY>
<TOKEN>

都需要替换成实际值。

五、部署Beszel Hub

5.1 检查Docker环境

docker version
docker compose version

如果两个命令都能正常显示版本，可以继续。

5.2 创建目录

sudo mkdir -p /opt/beszel/data
cd /opt/beszel

5.3 创建docker-compose.yml

sudo vi /opt/beszel/docker-compose.yml

写入：

services:
  beszel:
    image: henrygd/beszel:latest
    container_name: beszel
    restart: unless-stopped

    environment:
      APP_URL: https://monitor.example.com
      CHECK_UPDATES: "true"

    ports:
      - "127.0.0.1:8090:8090"

    volumes:
      - /opt/beszel/data:/beszel_data:Z

    healthcheck:
      test:
        - CMD
        - /beszel
        - health
        - --url
        - http://localhost:8090
      start_period: 10s
      interval: 120s
      timeout: 5s

说明：

APP_URL必须改成实际访问地址；
127.0.0.1:8090:8090表示8090只允许本机Nginx访问；
:Z适用于启用SELinux的Rocky Linux、AlmaLinux等系统；
/opt/beszel/data保存历史数据、账号和配置；
官方Hub默认监听8090，并使用/beszel_data保存持久化数据。
官方建议健康检查间隔不低于60秒，本方案设置为120秒。

5.4 启动Hub

cd /opt/beszel
sudo docker compose pull
sudo docker compose up -d

5.5 检查运行状态

sudo docker compose ps
sudo docker logs --tail 100 beszel

检查健康接口：

curl http://127.0.0.1:8090/api/health

查看容器资源：

docker stats beszel --no-stream

六、配置Nginx反向代理

Beszel通过WebSocket接收Agent主动连接，因此Nginx必须支持WebSocket Upgrade。官方也建议设置正确的APP_URL，该地址会用于通知链接和Agent配置生成。

6.1 创建Nginx配置

sudo vi /etc/nginx/conf.d/beszel.conf

写入：

server {
    listen 80;
    server_name monitor.example.com;

    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name monitor.example.com;

    ssl_certificate     /etc/nginx/ssl/monitor.example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/monitor.example.com.key;

    client_max_body_size 10M;

    location / {
        proxy_pass http://127.0.0.1:8090;

        proxy_http_version 1.1;
        proxy_read_timeout 360s;
        proxy_send_timeout 360s;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        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;
    }
}

证书路径需要替换成实际证书路径。

6.2 检查并重载Nginx

sudo nginx -t
sudo systemctl reload nginx

浏览器访问：

https://monitor.example.com

第一次访问时，根据页面提示创建管理员账号。

6.3 没有域名时的临时方案

如果仅在内网使用，可以把Compose端口修改为：

ports:
  - "8090:8090"

然后访问：

http://192.168.10.20:8090

此时Agent的Hub地址填写：

http://192.168.10.20:8090

该方式适合可信内网；如果需要经过公网或不可信网络，建议使用HTTPS。

七、防火墙配置

7.1 Hub服务器

使用HTTPS时开放：

sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --reload

检查：

sudo firewall-cmd --list-all

由于8090绑定在127.0.0.1，不需要向外开放8090端口。

7.2 Agent服务器

WebSocket模式下：

不需要开放45876；
Agent需要能够访问Hub的443端口；
Agent需要访问GitHub 443，才能安装或在线更新二进制。

Beszel官方列出的WebSocket网络需求是Agent主动访问Hub地址，SSH模式才需要Hub访问Agent的45876端口。

八、在Hub中添加服务器

登录Beszel后：

点击右上角的“Add System”或“添加系统”；
输入服务器名称；
填写服务器IP或主机名；
选择或使用WebSocket连接配置；
页面会生成：
- Public Key；
- Token；
- Hub URL；
- 二进制Agent安装命令；
暂时不要关闭窗口；
将页面生成的二进制安装命令复制到目标服务器执行。

官方推荐直接从Hub的添加系统窗口复制预生成的二进制安装命令，这样可以避免手工填写Key、Token和Hub URL时出错。

九、安装二进制Agent

以下步骤需要在每台被监控服务器执行。

9.1 安装基础命令

Rocky Linux、AlmaLinux或CentOS：

sudo dnf install -y curl tar ca-certificates

Ubuntu或Debian：

sudo apt update
sudo apt install -y curl tar ca-certificates

9.2 推荐安装方式

直接执行Hub页面生成的命令。

通用安装脚本格式如下：

curl -sL https://get.beszel.dev \
  -o /tmp/install-agent.sh

chmod +x /tmp/install-agent.sh

sudo /tmp/install-agent.sh

安装过程中填写或确认：

Public Key：使用Hub生成的KEY
Token：使用Hub生成的TOKEN
Hub URL：https://monitor.example.com
自动更新：生产环境建议先选择否

安装脚本会：

下载匹配当前CPU架构的二进制；
创建beszel用户；
创建systemd服务；
设置开机自启动；
启动Agent；
可选配置每日自动更新。

9.3 检查Agent服务

sudo systemctl status beszel-agent --no-pager

查看启动日志：

sudo journalctl -u beszel-agent -n 100 --no-pager

实时查看：

sudo journalctl -u beszel-agent -f

检查开机启动：

sudo systemctl is-enabled beszel-agent

应返回：

enabled

十、配置Agent使用WebSocket模式

虽然Agent已经配置了HUB_URL和TOKEN，但默认仍可能监听45876端口，用于SSH模式。

本方案只使用WebSocket，因此建议关闭Agent内置SSH监听。

10.1 创建systemd覆盖配置

sudo systemctl edit beszel-agent.service

写入：

[Service]
Environment="DISABLE_SSH=true"
Environment="DOCKER_HOST=unix:///var/run/docker.sock"

保存后执行：

sudo systemctl daemon-reload
sudo systemctl restart beszel-agent

检查端口：

sudo ss -lntp | grep 45876

设置DISABLE_SSH=true后，正常情况下不应再监听45876。该环境变量用于完全关闭Agent内置SSH服务器，仅保留WebSocket连接。

十一、配置Docker容器监控

11.1 检查Docker Socket

ls -l /var/run/docker.sock

通常显示：

srw-rw---- 1 root docker ... /var/run/docker.sock

检查beszel用户：

id beszel

11.2 测试读取权限

sudo -u beszel test -r /var/run/docker.sock
echo $?

表示有读取权限。

还可以执行：

sudo -u beszel docker ps

如果能够正常列出容器，Beszel Agent就能够访问Docker接口。

11.3 添加beszel用户到docker组

如果提示权限不足：

sudo usermod -aG docker beszel
sudo systemctl restart beszel-agent

再次检查：

id beszel
sudo -u beszel docker ps

需要注意，Docker官方明确说明：加入docker组会授予接近root级别的Docker控制权限。因此，只应将受信任的专用服务用户加入该组。

11.4 检查Agent日志

sudo journalctl -u beszel-agent -n 200 --no-pager

重点查找：

docker
container
permission denied
docker.sock

也可以过滤：

sudo journalctl -u beszel-agent --no-pager | grep -Ei "docker|container|socket|permission"

11.5 安全性更高的方案

生产环境对安全要求较高时，可以部署Docker Socket Proxy，只向Beszel开放容器查询接口。

Beszel只需要读取容器信息；官方文档建议Socket Proxy只启用：

CONTAINERS=1

然后在Agent中设置：

Environment="DOCKER_HOST=tcp://127.0.0.1:2375"

这比直接授予docker.sock权限更安全，但会额外增加一个代理容器。

十二、监控其他磁盘和挂载目录

二进制Agent可以通过EXTRA_FILESYSTEMS监控额外磁盘、分区和挂载点。

例如服务器上还有：

/data
/data02
/mnt/nfs

执行：

sudo systemctl edit beszel-agent.service

写入或合并：

[Unit]
RequiresMountsFor=/data /data02 /mnt/nfs

[Service]
Environment="DISABLE_SSH=true"
Environment="DOCKER_HOST=unix:///var/run/docker.sock"
Environment="EXTRA_FILESYSTEMS=/data,/data02,/mnt/nfs"

重新加载：

sudo systemctl daemon-reload
sudo systemctl restart beszel-agent

查看日志：

sudo journalctl -u beszel-agent -n 100 --no-pager

注意：

网络挂载可以显示容量和使用率；
网络文件系统通常无法显示底层磁盘IO；
多个目录使用英文逗号分隔，不要添加空格。

十三、调整内存计算方式

如果Beszel内存使用率与free较接近，但与htop差异较大，可以将计算方式切换为htop。

执行：

sudo systemctl edit beszel-agent.service

添加：

[Service]
Environment="MEM_CALC=htop"

重新启动：

sudo systemctl daemon-reload
sudo systemctl restart beszel-agent

Beszel默认使用gopsutil的内存计算方式，设置MEM_CALC=htop后会尽量与htop的显示方式保持一致。

十四、验证监控结果

返回Beszel Hub页面。

服务器状态应从红色或Pending变成绿色。

依次检查：

14.1 宿主机指标

CPU；
内存；
Swap；
Load Average；
磁盘容量；
磁盘IO；
网络流量；
温度传感器。

14.2 Docker指标

确认页面中能够看到：

容器名称；
容器运行状态；
容器CPU；
容器内存；
容器网络；
容器历史趋势。

14.3 systemd服务

二进制Agent一般不需要额外配置即可读取systemd服务状态，包括CPU、内存、状态和重启次数。

十五、推荐告警规则

建议先配置以下基础告警：

指标	建议阈值	持续时间
服务器离线	Down	1～2分钟
CPU使用率	大于85%	5分钟
内存使用率	大于90%	5分钟
Swap使用率	大于50%	10分钟
根磁盘使用率	大于85%	立即或5分钟
数据盘使用率	大于85%	立即或5分钟
Load Average	超过CPU核心数	10分钟
温度	大于80℃	5分钟

生产服务器可以设置两级阈值：

警告：磁盘使用率超过80%
严重：磁盘使用率超过90%

CPU偶尔达到100%不一定是故障，因此建议使用持续5分钟或10分钟的平均值，而不是瞬时值。

十六、配置企业微信告警

Beszel支持使用企业微信群机器人接收通知。

16.1 创建群机器人

在企业微信群中：

打开群设置；
添加群机器人；
创建自定义机器人；
获取Webhook地址；
找到地址中key=后面的内容。

例如Webhook地址最后是：

key=XXXXXXXXXXXXXXXXXXXXXXXX

则Beszel通知地址填写：

wecom://XXXXXXXXXXXXXXXXXXXXXXXX

需要提醒所有人时：

wecom://XXXXXXXXXXXXXXXXXXXXXXXX?mentioned_list=@all

Beszel官方企业微信通知使用wecom://key格式。

16.2 测试通知

保存通知渠道后：

点击测试；
确认企业微信群收到消息；
再创建CPU、内存、磁盘和离线告警。

十七、Hub数据备份

Beszel支持本地或S3兼容存储的自动备份；管理员页面也可以管理备份。

除此之外，建议定期备份整个数据目录。

17.1 创建备份目录

sudo mkdir -p /backup/beszel

17.2 手工备份

cd /opt/beszel

sudo docker compose stop beszel

sudo tar -czf \
  /backup/beszel/beszel_$(date +%Y%m%d_%H%M%S).tar.gz \
  docker-compose.yml data

sudo docker compose start beszel

查看备份：

ls -lh /backup/beszel

17.3 定时备份示例

sudo crontab -e

添加：

30 2 * * * cd /opt/beszel && docker compose stop beszel && tar -czf /backup/beszel/beszel_$(date +\%Y\%m\%d_\%H\%M\%S).tar.gz docker-compose.yml data && docker compose start beszel

建议再配置旧备份清理策略，例如保留30天。

十八、升级Beszel Hub

升级前先备份。

cd /opt/beszel

sudo docker compose stop beszel

sudo tar -czf \
  /backup/beszel/before_upgrade_$(date +%Y%m%d_%H%M%S).tar.gz \
  docker-compose.yml data

sudo docker compose pull
sudo docker compose up -d

检查：

sudo docker compose ps
sudo docker logs --tail 100 beszel
curl http://127.0.0.1:8090/api/health

确认正常后清理无用镜像：

sudo docker image prune -f

生产环境不建议在没有备份的情况下直接升级。

十九、升级二进制Agent

先确认Agent二进制路径：

sudo systemctl cat beszel-agent

通常安装路径为：

/opt/beszel-agent/beszel-agent

执行更新：

sudo /opt/beszel-agent/beszel-agent update
sudo systemctl restart beszel-agent

检查：

sudo systemctl status beszel-agent --no-pager
sudo journalctl -u beszel-agent -n 50 --no-pager

Beszel二进制Agent内置update命令，安装脚本也可以选择启用每日自动更新。

二十、常见故障排查

20.1 Hub页面打不开

检查容器：

docker ps -a | grep beszel
docker logs --tail 200 beszel

检查端口：

ss -lntp | grep 8090

检查本机接口：

curl -v http://127.0.0.1:8090/api/health

如果本机正常但域名不通，检查：

nginx -t
systemctl status nginx
firewall-cmd --list-all

20.2 Agent显示红色或离线

检查服务：

sudo systemctl status beszel-agent --no-pager

检查日志：

sudo journalctl -u beszel-agent -n 200 --no-pager

测试Hub：

curl -I https://monitor.example.com

检查域名解析：

getent hosts monitor.example.com

检查Nginx是否包含：

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 360s;

如果普通页面正常但Agent始终离线，优先检查WebSocket反向代理配置。

20.3 宿主机数据正常，但没有容器数据

执行：

docker stats --no-stream
sudo -u beszel docker ps
ls -l /var/run/docker.sock
id beszel

如果sudo -u beszel docker ps报权限错误：

sudo usermod -aG docker beszel
sudo systemctl restart beszel-agent

检查Agent配置：

sudo systemctl show beszel-agent \
  --property=Environment

应包含：

DOCKER_HOST=unix:///var/run/docker.sock

20.4 Rocky Linux或AlmaLinux出现203/EXEC

如果状态中出现：

status=203/EXEC
Permission denied

先检查：

ls -lZ /opt/beszel-agent/beszel-agent
getenforce

确认执行权限：

sudo chmod 755 /opt/beszel-agent/beszel-agent

如果SELinux阻止执行，可以临时修正上下文：

sudo chcon -t bin_t /opt/beszel-agent/beszel-agent
sudo systemctl restart beszel-agent

然后检查：

sudo ausearch -m AVC -ts recent
sudo systemctl status beszel-agent --no-pager

该问题在部分AlmaLinux/Rocky Linux部署中表现为Agent二进制被SELinux拒绝执行。

不建议直接长期关闭SELinux。

20.5 数据盘没有显示

检查挂载：

df -hT
lsblk

检查Agent环境变量：

sudo systemctl show beszel-agent \
  --property=Environment

确认包含：

EXTRA_FILESYSTEMS=/data,/data02

重启：

sudo systemctl daemon-reload
sudo systemctl restart beszel-agent

20.6 内存使用率与htop不一致

设置：

Environment="MEM_CALC=htop"

然后：

sudo systemctl daemon-reload
sudo systemctl restart beszel-agent

20.7 K8s节点看不到Pod

如果Kubernetes节点使用的是containerd而不是Docker：

可以查看节点宿主机CPU、内存、磁盘和网络；
可以查看systemd中的kubelet等服务；
不能把Beszel当成完整的Kubernetes Pod监控平台；
不应预期完整显示每个Pod、Deployment和containerd容器指标。

Beszel官方当前主要将Docker和Podman列为容器指标采集对象。

二十一、安全建议

正式环境建议落实以下措施：

Hub的8090只绑定127.0.0.1；
对外只开放Nginx 443；
Agent使用WebSocket主动连接；
设置DISABLE_SSH=true；
不向公网开放Agent 45876；
使用HTTPS证书；
管理员使用高强度密码；
定期备份/opt/beszel/data；
升级前先备份；
不开放Docker TCP API；
Docker Socket权限只授予专用beszel用户；
高安全环境使用Docker Socket Proxy；
不长期关闭SELinux；
将Beszel管理页面限制在VPN、内网或可信IP范围内。

二十二、部署验收清单

Hub验收

□ beszel容器正常运行
□ /api/health返回正常
□ Nginx代理正常
□ HTTPS证书正常
□ 管理员账号已创建
□ 数据目录已持久化
□ 已配置备份目录

Agent验收

□ beszel-agent服务为active
□ beszel-agent已设置开机启动
□ Agent能够主动连接Hub
□ 45876端口没有对外监听
□ CPU和内存数据正常
□ 根磁盘数据正常
□ 其他数据盘正常
□ Docker容器列表正常
□ Docker CPU和内存正常
□ systemd服务正常显示

告警验收

□ CPU告警已创建
□ 内存告警已创建
□ 磁盘告警已创建
□ 离线告警已创建
□ 企业微信通知测试成功
□ 实际告警消息能够收到

二十三、最终推荐配置

对于普通Docker服务器：

Hub：Docker Compose
Agent：二进制 + systemd
通信：HTTPS WebSocket
Agent SSH：关闭
Docker：读取本地docker.sock
额外磁盘：EXTRA_FILESYSTEMS
告警：CPU、内存、磁盘、离线
通知：企业微信

对于Kubernetes/containerd节点：

使用Beszel监控节点宿主机资源
不将其作为完整Kubernetes监控平台
重点监控CPU、内存、磁盘、网络、kubelet状态和节点在线状态