部署教程

Beszel 部署教程：VPS 资源监控、Agent 接入与告警

发布于 2026-10-03

使用 VPS 部署 Beszel，介绍配置、访问方式、实际操作及数据备份。

开始前

Beszel 将服务器和 Docker 容器的 CPU、内存、磁盘与网络变化保存为图表，服务器失联或指标达到阈值时可以发送通知。本篇部署 Hub，再为本机和其他 VPS 接入 Agent。

前往雨云选购 ↗

注册推荐码：KuZhuJi

准备一台机器和一个域名

Beszel 分为 Hub 和 Agent。Hub 保存数据、提供网页和发送通知；每台需要监控的服务器运行一个 Agent，负责采集数据。第一台 VPS 可以同时运行两者，不必另外购买一台服务器才能试用。

如果几台机器已经承担正式业务，把 Hub 放到其中一台时要想清楚：这台机器宕机，面板和通知也会一起停。以后有需要，再把 Hub 放到另一台独立服务器，并从外部检查它是否在线。

本文约定：

使用 Ubuntu 24.04 LTS 或相近的 Linux 服务器，已有 Docker Engine 和 Compose 插件。
以 root 执行服务器命令；若使用普通用户，按需要加 `sudo`。
把 `beszel.example.com` 替换成自己的域名，DNS 指向 Hub 的公网地址。
HTTPS 由运行在宿主机上的 Caddy 处理，公网开放 80、443；SSH 保持原有访问规则。

还没装 Docker，可以按 Docker 官方 Ubuntu 安装说明配置软件源；Caddy 的安装见官方安装页。如果服务器已经有 1Panel、Nginx 或其他反向代理，继续用现有入口，把请求代理到下面的 8090 端口，别再启动一个程序争抢 80 和 443。

先检查环境：

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

docker version
docker compose version
ss -lntp

8090 如果已经被使用，就把后面 Compose 中左侧的宿主机端口换掉，SSH 转发和反向代理的目标端口也一起改。容器内部仍然使用 8090。

准备单独放置监控面板时，可以根据现有服务器所在地区和自己的访问线路选择 VPS。先确认网络可达和备份空间，再考虑扩大配置；下面保留雨云的配置入口，价格和库存以页面为准。

先启动 Hub，把第一个账号建好

创建目录：

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

mkdir -p /opt/beszel
cd /opt/beszel
umask 077

保存为 `compose.yml`：

yaml；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

services:
  hub:
    image: henrygd/beszel:0.20.0
    restart: unless-stopped
    ports:
      - "127.0.0.1:8090:8090"
    environment:
      APP_URL: https://beszel.example.com
    volumes:
      - ./beszel_data:/beszel_data

这里绑定的是宿主机回环地址。8090 不直接对公网提供服务，浏览器稍后通过 Caddy 访问。数据保存在当前目录的 `beszel_data`，重建容器不会删掉它，也无需再安装 MySQL 或 Redis。Hub 安装文档提供了对应的目录与环境变量说明。

启动并检查：

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

docker compose config --quiet
docker compose up -d hub
docker compose ps
docker compose logs --tail 50 hub
curl -fsS http://127.0.0.1:8090/api/health

HTTP 健康检查通过后，先创建管理员，再公开域名入口。在自己的电脑执行下面这条命令，把用户名与服务器地址换掉。这里使用本机 18090，避免占用电脑上可能已经运行的 8090：

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

ssh -N -L 18090:127.0.0.1:8090 root@YOUR_VPS_IP

保持这个终端打开，在电脑浏览器访问 `http://127.0.0.1:18090`。首次进入会要求创建账号，填写自己的邮箱和独立密码。确认能进入系统列表后，再配置域名。SSH 转发只为初始化提供临时入口，关闭这个终端不会停止服务器上的 Hub。

用域名访问面板

如果采用宿主机 Caddy，在现有 Caddyfile 中新增下面的站点块，不要覆盖其他网站配置：

caddyfile；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

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

检查并重载：

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy

确认 DNS 的 A 记录正确；若设置了 AAAA，IPv6 也必须能够访问这台机器。云厂商安全组和系统防火墙都要允许证书验证与网页访问所需的端口。浏览器打开 `https://beszel.example.com`，应该能看到登录页，并使用刚才建立的账号登录。

Caddy 的这个写法适用于它直接运行在宿主机的情况。如果 Caddy 自己也在容器里，`127.0.0.1` 指向的是 Caddy 容器，需要改用共同 Docker 网络中的 Hub 服务名，或按现有面板的网络方式配置。

Beszel 的 Agent 会用到 WebSocket，反向代理必须支持协议升级。Caddy 会处理这部分；使用 Nginx 或 1Panel 自定义反代时，可对照官方反向代理示例。面板能打开却收不到 Agent 数据时，这里尤其值得检查。`APP_URL` 则影响通知链接和生成的 Agent 配置，应当填写最终访问地址。

准备独立实例时，可在雨云选择适合的云服务器配置，优惠码 `KuZhuJi`。配置按实际任务选择，数据库和附件另做备份。

把这台 VPS 加入监控

点击面板右上角 Add System，给服务器起一个容易辨认的名字，例如 `博客主机`。Host / IP 可填该服务器的地址，保留默认端口。窗口中会生成 Public Key 和 Token，并提供可复制的 Docker 配置。

本教程使用 Agent 主动连接 Hub 的 WebSocket 方式，并关闭 Agent 的 SSH 监听。因此面板里的 Host / IP、Port 不负责这条连接，也不需要开放 45876。先填写名称、保存这台系统，随后启动 Agent。连接方式说明解释了两种模式的区别。

回到 `/opt/beszel`，用编辑器新建 `agent.env`：

ini；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

KEY='替换成面板生成的完整 Public Key'
TOKEN='替换成面板生成的 Token'

保留引号，换掉其中的中文占位内容，然后执行：

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

chmod 600 agent.env

在已有 `compose.yml` 的 `services` 下追加 Agent，与 `hub` 保持同级缩进：

yaml；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

  agent:
    image: henrygd/beszel-agent:0.20.0
    restart: unless-stopped
    network_mode: host
    env_file:
      - agent.env
    environment:
      HUB_URL: http://127.0.0.1:8090
      DISABLE_SSH: "true"
    volumes:
      - ./beszel_agent_data:/var/lib/beszel-agent
      - /var/run/docker.sock:/var/run/docker.sock:ro

这个 Agent 与 Hub 在同一台 Linux VPS，通过回环地址连接，不绕公网域名。`network_mode: host` 让它读取宿主机网络接口的数据；`DISABLE_SSH` 是当前版本支持的变量，用于关闭另一路入站监听，具体见环境变量说明。不要再为这个服务添加 `ports`。

Docker socket 用于读取容器统计。挂载中的 `:ro` 表示文件系统挂载只读，不等于 Docker API 获得了只读权限；能接触这个 socket 的进程仍然拥有很高权限。这里只把它交给已核对来源的官方 Agent。如果不需要容器监控，可以删除这一行。

保存后启动：

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

docker compose config --quiet
docker compose up -d agent
docker compose logs --tail 50 agent

正常情况下，日志会出现 WebSocket 连接成功的信息，面板中的机器变为在线。稍等一会再点进去，CPU、内存和磁盘等图表会开始积累数据。刚安装时历史曲线很短，这不代表采集失败。

第二台 VPS 只装 Agent

其他服务器不必再装 Hub。在同一个面板里新增系统，分别生成并保存它的配置。给每台机器保留自己的 `agent.env` 和 `beszel_agent_data`，不要整份复制第一台已经运行过的身份数据。

在第二台机器新建目录，保存 `agent.env`，然后使用完整的 Agent Compose：

yaml；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

services:
  agent:
    image: henrygd/beszel-agent:0.20.0
    restart: unless-stopped
    network_mode: host
    env_file:
      - agent.env
    environment:
      HUB_URL: https://beszel.example.com
      DISABLE_SSH: "true"
    volumes:
      - ./beszel_agent_data:/var/lib/beszel-agent
      - /var/run/docker.sock:/var/run/docker.sock:ro

与上一段相比，关键变化是 `HUB_URL` 改成可以从第二台 VPS 访问的 HTTPS 域名。执行 `docker compose up -d` 后，它会向 Hub 发起连接；云安全组无需为这个 Agent 新开入站端口。

如果 Hub 前面还有访问登录页、验证码或额外认证中间件，要确认机器请求能到达 Beszel 的 Agent 接口。浏览器能通过验证码，并不意味着 Agent 也能通过。不要为了排障关闭整站认证，应按现有入口方案处理机器连接的访问规则。

需要增加服务器时，可以打开雨云选购页面，填写优惠码 `KuZhuJi`；迁移前保留数据与原有部署配置。

收到测试通知之后，再设置阈值

进入 Settings → Notifications，配置自己使用的通知服务。Beszel 使用 Shoutrrr 格式，例如 Gotify、Telegram、Bark 等都有对应地址写法，详见通知文档。地址里的令牌往往能够直接发送消息，应当像密码一样保存。

先使用通知测试功能，确认消息确实到达手机或接收端，再回到系统列表为服务器启用告警。配置了通知渠道，并不意味着每台机器的告警都已经打开。

第一天可以先关注失联和磁盘空间。CPU 阈值则要结合业务：每天固定时间压缩备份的机器，短暂满载未必需要叫醒人。能设置持续时间的告警，按自己的任务时长留出余量，避免曲线一抖就发消息。不要直接照搬别人的阈值，先看一两个正常业务周期再调整。

可以选择一台非关键测试机，短暂停止它的 Agent，检查是否收到预期的失联通知，再恢复运行。这里停止的是采集程序，不是整台 VPS；能收到这条消息，说明监控中断会触发通知，不能据此证明网站故障也一定被发现。

图表不对时，按连接和采集分别查

机器一直离线：先看 Agent 日志。域名解析失败、证书验证失败、Token 错误和 WebSocket 被反代拦截，处理方法不同。核对 `HUB_URL`，确认密钥来自当前 Hub；修改环境变量以后执行 `docker compose up -d` 让容器重建，仅仅改文件不会更新正在运行的进程环境。

主机在线，容器列表为空：检查 Docker socket 是否存在、挂载路径是否正确，以及这台机器有没有运行中的容器。Rootless Docker 的 socket 路径与常规安装不同，不能原样复制 `/var/run/docker.sock`。相关差异见 Agent 安装说明。

数据盘没有出现：默认图表不一定包含所有挂载点。可以按额外磁盘文档，把目标磁盘上的目录只读挂载到 Agent 的 `/extra-filesystems/` 下，再核对图表。先用 `df -h` 确认路径属于哪块盘，别把根分区里的普通文件夹误认为新磁盘。

没有温度、风扇或硬盘健康数据：VPS 通常不会把宿主机的物理传感器交给租户。缺少这些指标不一定是安装错误，不要为了追求“图表全亮”给容器追加不明用途的特权。

备份好数据，再升级镜像

需要保留的至少有 Hub 的 `beszel_data`、Agent 的 `beszel_agent_data`、`compose.yml` 和 `agent.env`。其中包括配置、身份及历史数据，备份不能放到公开下载目录。Beszel 也支持通过后台管理备份；对于这套单目录部署，停机打包比较容易检查。

下面在服务器 Bash 中执行，备份期间面板和本机 Agent 会短暂停止。请先选择可接受的维护时间：

bash；使用前请核对本文前提。如内容超出，可左右滑动，键盘使用方向键或 Home/End 查看。

仅复制文本，不会执行。

bash <<'BASH'
set -e
cd /opt/beszel
umask 077
mkdir -p /opt/beszel-backups
backup_file="/opt/beszel-backups/beszel-$(date +%Y%m%d-%H%M%S).tar.gz"
trap 'docker compose start' EXIT
docker compose stop
tar -czf "$backup_file" compose.yml agent.env beszel_data beszel_agent_data
sha256sum "$backup_file" > "$backup_file.sha256"
BASH

脚本退出时会尝试重新启动服务，执行完再用 `docker compose ps` 确认状态。备份成功后复制到另一台机器或独立存储，只留在同一 VPS 上无法应对整机丢失。

升级时先读版本发布记录，把 Hub 与 Agent 的镜像标签改成准备使用的版本，再执行 `docker compose pull` 和 `docker compose up -d`。本篇使用 0.20.0；升级时同时调整 Hub 和 Agent 的版本。

恢复演练可以在独立目录或测试机解压备份，先只启动 Hub，并绑定另一个回环端口，检查账号、系统列表和历史数据。不要让恢复出来的 Agent 与原 Agent 同时使用同一套身份连接正式 Hub。若升级涉及数据库迁移，回退时使用升级前的数据副本与对应旧版本，别直接让旧程序打开已经升级过的数据库。

部署完成后，留下域名、数据目录、备份位置和通知接收方式。下次 VPS 变慢，先找到对应时间段，再结合应用日志判断原因；Beszel 留下的曲线会让这一步有据可查。