Beszel 部署文档

1. 部署概览

Beszel Hub 和本机 Agent 运行在 Docker Compose 中，由 Nginx 负责 HTTPS 反向代理，Cloudflare 负责 DNS 与可选的代理接入。

2. 部署逻辑图

flowchart LR
    U[管理员浏览器]
    CF[Cloudflare DNS / Proxy\nDNS Only 或 Proxied]
    N[Nginx\n80 / 443\nWebSocket 反代]
    H[Beszel Hub 容器\n127.0.0.1:8090]
    A[Beszel Agent 容器\n主机网络模式]
    S[Unix Socket\n/beszel_socket/beszel.sock]
    D[(Hub 持久化数据)]
    AD[(Agent 持久化数据)]
    T[Agent 公钥与 Token\n服务器本地受保护文件]

    U -->|HTTPS| CF
    CF -->|80/443| N
    N -->|HTTP + WebSocket| H
    H <-->|共享 Unix Socket| S
    S <--> A
    H --> D
    A --> AD
    A -.读取.-> T

数据流：浏览器访问域名，Cloudflare 将请求解析或转发到服务器；Nginx 终止 TLS 并把 HTTP/WebSocket 转发到 Hub；本机 Agent 通过共享 Unix socket 接入，远程 Agent 则主动通过 WebSocket 连接 Hub，8090 和远程 Agent 端口都不需要直接暴露公网。

3. 前置条件

• Debian 或兼容 Linux 服务器。
• 域名 beszel.xxxx 已解析到部署服务器。
• 公网放行 TCP 80 和 443，SSH 按既有安全策略放行。
• 具备 root 或 sudo 权限。
• Cloudflare 初始使用 DNS Only，证书签发完成后再切换 Proxied。

4. 安装依赖

apt-get update
apt-get install -y docker.io docker-cli docker-buildx docker-compose \
  nginx certbot python3-certbot-nginx ca-certificates

systemctl enable --now docker nginx

5. 创建部署目录

install -d -m 0750 /opt/beszel
cd /opt/beszel

目录结构：

/opt/beszel/
├── docker-compose.yml
├── .env                       # 仅 root 可读，不提交 Git
├── beszel_data/
├── beszel_agent_data/
└── beszel_socket/

6. Docker Compose 配置

创建 /opt/beszel/docker-compose.yml：

services:
  beszel:
    image: henrygd/beszel:latest
    container_name: beszel
    restart: unless-stopped
    env_file:
      - .env
    ports:
      - "127.0.0.1:8090:8090"
    volumes:
      - ./beszel_data:/beszel_data
      - ./beszel_socket:/beszel_socket

  beszel-agent:
    image: henrygd/beszel-agent:latest
    container_name: beszel-agent
    restart: unless-stopped
    network_mode: host
    env_file:
      - .env
    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://127.0.0.1:8090

创建 /opt/beszel/.env，不要将真实值写入文档或代码仓库：

APP_URL=https://beszel.ysoo.de
KEY=<从安全存储读取的 Agent 公钥>
TOKEN=<从安全存储读取的 Agent Token>

chmod 600 /opt/beszel/.env
cd /opt/beszel
docker compose pull
docker compose up -d
docker compose ps

预期状态：beszel 和 beszel-agent 均为 Up。

7. Nginx 反向代理

创建 /etc/nginx/sites-available/beszel：

server {
    listen 80;
    listen [::]:80;
    server_name beszel.ysoo.de;

    client_max_body_size 10M;

    location / {
        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;
        proxy_pass http://127.0.0.1:8090;
    }
}

ln -sfn /etc/nginx/sites-available/beszel /etc/nginx/sites-enabled/beszel
rm -f /etc/nginx/sites-enabled/default
nginx -t
systemctl reload nginx

8. 申请 HTTPS 证书

确认 DNS 已指向部署服务器，并确保 TCP 80 可从公网访问：

certbot --nginx \
  -d beszel.xxxx \
  --non-interactive \
  --agree-tos \
  --register-unsafely-without-email \
  --redirect

生产环境建议将无邮箱参数替换为维护邮箱。检查自动续期：

systemctl is-enabled certbot.timer
systemctl is-active certbot.timer
certbot renew --dry-run

9. 首次初始化与添加本机系统

1. 打开 beszel.xxxx，创建第一个管理员账户。

2. 进入 Add System / 添加系统。

3. 主机/IP 填入：

   /beszel_socket/beszel.sock
   

4. 填入服务器上已配置的 Agent 公钥与 Token。

5. 保存并确认系统状态变为绿色。

如果 Agent 日志出现 401，检查 KEY、TOKEN 是否与 Web UI 中添加系统时一致：

docker compose -f /opt/beszel/docker-compose.yml logs --tail=100 beszel-agent
docker compose -f /opt/beszel/docker-compose.yml restart beszel-agent

10. 添加远程 Agent 机器

远程 Agent 机器不需要安装 Nginx，也不需要把 Agent 端口暴露到公网。推荐让 Agent 主动通过 WebSocket 连接 Hub。

10.1 在 Hub Web UI 创建系统

1. 登录 beszel.xxxx。
2. 点击 Add System / 添加系统。
3. 填写远程机器名称。
4. 选择 Docker 安装方式。
5. 复制页面生成的 docker-compose.yml，尤其保留页面生成的 KEY、TOKEN、HUB_URL 和监听端口。

不要直接复用本机 Agent 的密钥和 Token；每台远程机器应使用独立的 Agent 配置。

10.2 在远程 Agent 机器执行安装命令

以下命令在远程 Agent 机器执行：

apt-get update
apt-get install -y docker.io docker-cli docker-buildx docker-compose ca-certificates
systemctl enable --now docker

install -d -m 0750 /opt/beszel-agent
cd /opt/beszel-agent

创建 /opt/beszel-agent/docker-compose.yml。实际生产配置优先使用 Hub Web UI 生成的内容；下面是脱敏模板：

services:
  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
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      LISTEN: 45876
      KEY: <Hub 添加系统时生成的公钥>
      TOKEN: <Hub 添加系统时生成的 Token>
      HUB_URL: beszel.xxxx

启动远程 Agent：

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

10.3 网络与防火墙要求

远程 Agent 至少需要能够访问 beszel.xxxx:443，用于向 Hub 建立 HTTPS/WebSocket 连接；同时需要可用 DNS。通常不需要开放远程 Agent 的 45876 入站端口，因为 Agent 使用主动出站连接。

10.4 在 Hub 中完成确认

回到 Hub 的 Add System / 添加系统 对话框，确认系统名称、主机/IP、端口和认证信息与远程 Agent 配置一致，保存后等待系统状态变为绿色。

如果状态为红色，在远程 Agent 机器执行：

curl -fsSI beszel.xxxx/
docker compose -f /opt/beszel-agent/docker-compose.yml ps
docker compose -f /opt/beszel-agent/docker-compose.yml logs --tail=100 beszel-agent

常见错误：401 Unauthorized 优先检查 KEY、TOKEN；connection refused 优先检查 Hub 域名、TCP 443、Cloudflare 和防火墙；指标为空优先检查 Docker socket 挂载。

11. Cloudflare 切换建议

源站 HTTPS 验证完成后，可以将记录从 DNS Only 切换为 Proxied。

• SSL/TLS 加密模式：Full (strict)。
• WebSocket：保持启用。
• 源站 TCP 80/443：按防火墙策略放行。
• 不要在文档、截图、聊天记录或 Git 仓库中公开 Token 和私钥。

12. 验证清单

# Hub 仅本机监听
ss -ltnp | grep ':8090'

# Nginx 监听公网 HTTP/HTTPS
ss -ltnp | grep -E ':(80|443)'

# Compose 服务状态
docker compose -f /opt/beszel/docker-compose.yml ps

# HTTPS 应返回 200
curl -fsSI https://beszel.xxxx/

# HTTP 应返回 301 并跳转 HTTPS
curl -sSI http://beszel.xxxx/

预期结果：8090 仅绑定 127.0.0.1；HTTPS 返回 200；HTTP 返回 301；Hub 和 Agent 均为运行状态；Web UI 中本机系统为绿色。

13. 常见问题

页面打不开

getent ahostsv4 beszel.xxxx
nginx -t
systemctl status nginx --no-pager
docker compose -f /opt/beszel/docker-compose.yml ps

WebSocket 断开

确认 Nginx 中存在 proxy_http_version 1.1、Upgrade、Connection 和 proxy_read_timeout 360s 配置。

更新 Beszel

cd /opt/beszel
docker compose pull
docker compose up -d
docker image prune

更新前建议备份：

tar -czf /root/beszel-backup-$(date +%F).tar.gz \
  /opt/beszel/beszel_data \
  /opt/beszel/beszel_agent_data