feat: 部署 Beszel 服务器监控（/beszel/ 子路径）并新增首页入口

2026-08-31 23:01:55 +08:00
parent 70353ef4c4
commit 67caaa428e
6 changed files with 157 additions and 4 deletions
@@ -511,6 +511,99 @@ sudo rm -rf /var/www/certbot /opt/komari
 sudo nginx -t && sudo systemctl reload nginx
 ```

+## 12. 部署 Beszel 服务器监控（https://lzwlab.cn/beszel/）
+
+### 12.1 方案与要点
+
+- 组件：Beszel **hub**（基于 PocketBase 的 Web 面板，Docker 镜像 `henrygd/beszel:latest`）。每个被监控服务器再运行一个 **agent**（`henrygd/beszel-agent`），由用户在 Web 面板中添加系统时生成配置。
+- 入口：按需求将 Beszel 主页反代到主站子路径 `https://lzwlab.cn/beszel/`（首页欢迎页“📊 服务器状态”按钮）。
+- 端口：Beszel 默认端口 8090 与本机文件快传的 gunicorn（127.0.0.1:8090）冲突，因此容器 8090 只映射到宿主机 `127.0.0.1:8092`。
+- 子路径关键配置：hub 的 `APP_URL` 必须设为 `https://lzwlab.cn/beszel`，否则通知链接与 Agent 配置生成会指向错误地址。
+- 参考文档：https://www.beszel.dev/zh/guide/getting-started 、https://www.beszel.dev/zh/guide/hub-installation 、https://www.beszel.dev/zh/guide/reverse-proxy 。
+
+### 12.2 部署命令
+
+Compose 文件为仓库内 `beszel/docker-compose.yml`，服务器安装到 `/opt/beszel/`。首次启动通过 `.env`（root:root 0600）设置 `USER_EMAIL` / `USER_PASSWORD` 自动创建第一个管理员：
+
+```bash
+# 本地：SFTP 上传 beszel/docker-compose.yml 与临时 .env 到 /tmp
+# 远程：
+sudo mkdir -p /opt/beszel
+sudo install -m 600 -o root -g root /tmp/beszel.env /opt/beszel/.env
+sudo install -m 644 -o root -g root /tmp/beszel-compose.yml /opt/beszel/docker-compose.yml
+sudo rm -f /tmp/beszel.env /tmp/beszel-compose.yml
+cd /opt/beszel && sudo docker compose up -d
+# 验证管理员已创建后，清空 .env 中的明文密码（管理员账号已持久化在 beszel_data）
+sudo sh -c 'echo > /opt/beszel/.env' && sudo chmod 600 /opt/beszel/.env
+cd /opt/beszel && sudo docker compose up -d
+```
+
+`.env` 内容（仅首次启动需要，密码记录在 `Authentication.md`）：
+
+```dotenv
+USER_EMAIL=beszel@lzwlab.cn
+USER_PASSWORD=$PASS
+```
+
+### 12.3 nginx 反代（/beszel/）
+
+按 Beszel 官方 “使用 Nginx 在子路径提供服务” 方案，在 `lzwlab.nginx.conf` 的 443 server 块新增（已并入仓库配置）：
+
+```nginx
+location = /beszel {
+    return 301 /beszel/;
+}
+location /beszel/ {
+    client_max_body_size 10M;
+    proxy_read_timeout 360s;
+    proxy_http_version 1.1;
+    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;
+    rewrite /beszel/(.*) /$1 break;
+    proxy_pass http://127.0.0.1:8092;
+}
+```
+
+改配置后执行 `sudo nginx -t && sudo systemctl reload nginx`。
+
+### 12.4 验证结果
+
+```bash
+sudo docker ps --filter name=beszel   # Up (healthy)，127.0.0.1:8092->8090/tcp
+curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8092/    # 200（本机 hub）
+# 公网：
+curl -s -o /dev/null -w "%{http_code} -> %{redirect_url}\n" https://lzwlab.cn/beszel
+# 301 -> https://lzwlab.cn/beszel/
+curl -s -o /dev/null -w "%{http_code}\n" https://lzwlab.cn/beszel/   # 200
+curl -sL https://lzwlab.cn/beszel/ | grep -o '<title>.*</title>'      # <title>Beszel</title>
+curl -s https://lzwlab.cn/ | grep -o '服务器状态'                       # 服务器状态（首页按钮已生效）
+```
+
+### 12.5 添加监控节点（Agent）
+
+1. 打开 `https://lzwlab.cn/beszel/`，用 `Authentication.md` 中的管理员邮箱/密码登录。
+2. 点击右上角 **Add System**，填写系统名称，选择 WebSocket 或 SSH 连接方式，复制对话框生成的 Docker Compose 或二进制安装命令到目标服务器执行。
+3. 若目标服务器就是本机，且用 Docker 运行 agent：agent 默认监听 45876，与本机其他服务无端口冲突；WebSocket 模式将 `HUB_URL` 设为 `https://lzwlab.cn/beszel`，`KEY`/`TOKEN` 使用对话框生成的值。若想监控宿主机网络/容器，需给 agent 挂载 `/var/run/docker.sock:ro` 并使用 host 网络。
+4. 完成后回到对话框点击 **Add System**，系统状态变为绿色即接入成功。
+
+### 12.6 运维
+
+```bash
+cd /opt/beszel && sudo docker compose ps                     # hub 容器状态
+sudo docker logs -f beszel                                   # hub 日志
+cd /opt/beszel && sudo docker compose pull && sudo docker compose up -d   # 升级 hub
+# 备份：PocketBase 数据在数据卷内，直接备份 /opt/beszel/beszel_data/ 即可
+```
+
+### 12.7 踩坑
+
+- Beszel hub 默认端口 8090 与本机文件快传 gunicorn 冲突，必须改映射（本项目使用 127.0.0.1:8092:8090）。
+- 子路径部署必须设置 `APP_URL=https://lzwlab.cn/beszel`，并让 nginx 用 rewrite 去掉 `/beszel` 前缀；否则通知链接和 Agent 配置会指向错误地址。
+- `USER_EMAIL` / `USER_PASSWORD` 只在首次启动（尚无用户）时用于创建管理员；创建完成后应清空 `.env`，避免明文密码残留在服务器配置文件中。
 ## 附：踩坑记录