# Table of Contents - [What is Beszel? | Beszel](#what-is-beszel-beszel) - [Getting Started | Beszel](#getting-started-beszel) - [Beszel | Simple, lightweight server monitoring](#beszel-simple-lightweight-server-monitoring) - [GPU Monitoring | Beszel](#gpu-monitoring-beszel) - [Additional Disks | Beszel](#additional-disks-beszel) - [Agent Installation | Beszel](#agent-installation-beszel) - [Environment Variables | Beszel](#environment-variables-beszel) - [Hub Installation | Beszel](#hub-installation-beszel) - [OAuth / OIDC | Beszel](#oauth-oidc-beszel) - [Compiling | Beszel](#compiling-beszel) - [什么是 Beszel？ | Beszel](#-beszel-beszel) - [Podman Monitoring | Beszel](#podman-monitoring-beszel) - [REST API | Beszel](#rest-api-beszel) - [User Roles | Beszel](#user-roles-beszel) - [开始使用 | Beszel](#-beszel) - [其他磁盘 | Beszel](#-beszel) - [Common Issues | Beszel](#common-issues-beszel) - [Docker Shell | Beszel](#docker-shell-beszel) - [Multilingual and localization | Beszel](#multilingual-and-localization-beszel) - [环境变量 | Beszel](#-beszel) - [Beszel | 轻量易用的服务器监控](#beszel-) - [Security | Beszel](#security-beszel) - [用户角色 | Beszel](#-beszel) - [OAuth / OIDC 认证 | Beszel](#oauth-oidc-beszel) - [编译 | Beszel](#-beszel) - [Home Assistant Agent | Beszel](#home-assistant-agent-beszel) - [Podman 监控 | Beszel](#podman-beszel) - [Developer Guide | Beszel](#developer-guide-beszel) - [GPU 监控 | Beszel](#gpu-beszel) - [Hub 安装 | Beszel](#hub-beszel) - [常见问题 | Beszel](#-beszel) - [REST API | Beszel](#rest-api-beszel) - [代理安装 | Beszel](#-beszel) - [Docker Shell | Beszel](#docker-shell-beszel) - [Email Protection | Cloudflare](#email-protection-cloudflare) - [安全 | Beszel](#-beszel) - [开发者指南 | Beszel](#-beszel) - [多语言和本地化 | Beszel](#-beszel) - [Home Assistant 代理 | Beszel](#home-assistant-beszel) --- # What is Beszel? | Beszel Return to top What is Beszel? [​](#what-is-beszel) ===================================== Beszel is a lightweight server monitoring platform that includes Docker statistics, historical data, and alert functions. It has a friendly web interface, simple configuration, and is ready to use out of the box. It supports automatic backup, multi-user, OAuth authentication, and API access. [![Hub Docker Image Size](https://img.shields.io/docker/image-size/henrygd/beszel-agent/0.6.0?logo=docker&label=agent%20image%20size)](https://hub.docker.com/r/henrygd/beszel-agent) [![Agent Docker Image Size](https://img.shields.io/docker/image-size/henrygd/beszel/0.1.0?logo=docker&label=hub%20image%20size)](https://hub.docker.com/r/henrygd/beszel) [![MIT license](https://img.shields.io/github/license/henrygd/beszel?color=%239944ee)](https://github.com/henrygd/beszel/blob/main/LICENSE) [![Crowdin translations](https://badges.crowdin.net/beszel/localized.svg)](https://crowdin.com/project/beszel) Features [​](#features) ------------------------ * **Lightweight**: Smaller and less resource-intensive than leading solutions. * **Simple**: Easy setup, no need for public internet exposure. * **Docker stats**: Tracks CPU, memory, and network usage history for each container. * **Alerts**: Configurable alerts for CPU, memory, disk, bandwidth, temperature, and status. * **Multi-user**: Users manage their own systems. Admins can share systems across users. * **OAuth / OIDC**: Supports many OAuth2 providers. Password auth can be disabled. * **Automatic backups**: Save and restore data from disk or S3-compatible storage. * **REST API**: Use or update your data in your own scripts and applications. Architecture [​](#architecture) -------------------------------- Beszel consists of two main components: the **hub** and the **agent**. * **Hub**: A web application built on [PocketBase](https://pocketbase.io/) that provides a dashboard for viewing and managing connected systems. * **Agent**: Runs on each system you want to monitor, creating a minimal SSH server to communicate system metrics to the hub. Screenshots [​](#screenshots) ------------------------------ [![Dashboard](/image/dashboard.png)](/image/dashboard.png) [![System page](/image/system-full.png)](/image/system-full.png) [![Notification Settings](/image/settings-notifications.png)](/image/settings-notifications.png) Supported metrics [​](#supported-metrics) ------------------------------------------ * **CPU usage** - Host system and Docker / Podman containers. * **Memory usage** - Host system and containers. Includes swap and ZFS ARC. * **Disk usage** - Host system. Supports multiple partitions and devices. * **Disk I/O** - Host system. Supports multiple partitions and devices. * **Network usage** - Host system and containers. * **Temperature** - Host system sensors. * **GPU usage / temperature / power draw** - Nvidia and AMD only. Must use binary agent. --- # Getting Started | Beszel Return to top Getting Started [​](#getting-started) ====================================== For background information, see the [What is Beszel?](./what-is-beszel) page. 1\. Start the hub [​](#_1-start-the-hub) ----------------------------------------- The hub can be run with a single binary file or with Docker / Podman. * [Binary](./hub-installation#binary) * [Docker or Podman](./hub-installation#docker-or-podman) Click to view complete `docker-compose.yml` config including local agent IMPORTANT This configuration should work out of the box, but you must follow these steps when adding the system in the web UI: 1. Update the `KEY` value with your public key, then run `docker compose up -d` again to restart the agent. 2. Use `host.docker.internal` as the **Host / IP**. Do not use `localhost` or `127.0.0.1`. docker-compose.yml yaml services: beszel: image: henrygd/beszel:latest container_name: beszel restart: unless-stopped extra_hosts: - host.docker.internal:host-gateway ports: - 8090:8090 volumes: - ./beszel_data:/beszel_data beszel-agent: image: henrygd/beszel-agent:latest container_name: beszel-agent restart: unless-stopped network_mode: host volumes: - /var/run/docker.sock:/var/run/docker.sock:ro environment: PORT: 45876 # Do not remove quotes around the key KEY: 'UPDATE WITH YOUR PUBLIC KEY (copy from "Add system" dialog)' Click to view instructions for running `docker compose` NOTE If you prefer to set up containers in a different way, please feel free to do so. 1. Install [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/) if you haven't already. 2. Copy the `docker-compose.yml` content. 3. Create a directory somewhere to store the `docker-compose.yml` file. bash mkdir beszel cd beszel 4. Create a `docker-compose.yml` file, paste in the content, and save it. nanovimemacsvscode bash nano docker-compose.yml bash vim docker-compose.yml bash emacs docker-compose.yml bash code docker-compose.yml 5. Start the service. bash docker compose up -d 2\. Create an admin user [​](#_2-create-an-admin-user) ------------------------------------------------------- After starting the hub, navigate to [http://localhost:8090](http://localhost:8090) or your chosen address. You will be prompted to create an account: [![Screenshot of user creation form](/image/admin-creation.png)](/image/admin-creation.png) 3\. Configure your first system [​](#_3-configure-your-first-system) --------------------------------------------------------------------- Click the **Add System** button in the top right corner to open the system creation dialog. We're using localhost in this example, but you may use a remote agent instead. Do not click the **Add System** button inside the dialog until you've started up the agent. [![Screenshot of system creation form](/image/add-system.png)](/image/add-system.png) 4\. Start the agent [​](#_4-start-the-agent) --------------------------------------------- Docker instructions NOTE If you prefer to set up containers in a different way, please feel free to do so. 1. Copy the `docker-compose.yml` content from the **Add System** dialog. 2. Create a directory somewhere to store the agent's `docker-compose.yml` file. bash mkdir beszel-agent cd beszel-agent 3. Create a `docker-compose.yml` file and paste in the content provided in the **Add System** dialog. nanovimemacsvscode bash nano docker-compose.yml bash vim docker-compose.yml bash emacs docker-compose.yml bash code docker-compose.yml 4. Start the agent. bash docker compose up -d Binary instructions The install script is for Linux only If you use a different OS, please manually download and run the correct binary for your system. See the [Agent Installation](./agent-installation#binary) page or the [Compiling](./compiling) page for more information. 1. Copy the binary install command from the **Add System** dialog. 2. Open a terminal and run the command. This will download the correct binary, create a user called `beszel`, and start the agent. It also creates a service to keep it running after reboot, and optionally enables automatic daily updates. 5\. Finish adding the system [​](#_5-finish-adding-the-system) --------------------------------------------------------------- Now that the agent is running, click the **Add System** button in the dialog. You will see the new system in table. If it flips to green, you're good to go. [![Screenshot of system creation form](/image/new-system.png)](/image/new-system.png) If it changes to red, check the [Common Issues](./common-issues) page. --- # Beszel | Simple, lightweight server monitoring Beszel ====== Simple, lightweight server monitoring With Docker stats, historical data, and alerts. [What is Beszel?](/guide/what-is-beszel) [Quickstart](/guide/getting-started) [GitHub](https://github.com/henrygd/beszel) ![Slideshow Image](/image/home-alerts.webp) ![Slideshow Image](/image/home-dashboard.png) ![Slideshow Image](/image/home-system.png) Lightweight ----------- Smaller and less resource-intensive than leading solutions. Simple ------ Easy setup, no need for public internet exposure. Docker / Podman stats --------------------- Tracks CPU, memory, and network usage history for each container. Alerts ------ Configurable alerts for CPU, memory, disk, bandwidth, temperature, and system status. Multi-user ---------- Each user manages their own systems. Admins can share systems across users. OAuth / OIDC ------------ Supports multiple OAuth2 providers. Password authentication can be disabled. Automatic backups ----------------- Save and restore data from disk or S3-compatible storage. REST API -------- Use or update your data in your own scripts and applications. --- # GPU Monitoring | Beszel Return to top GPU Monitoring [​](#gpu-monitoring) ==================================== Beszel can monitor GPU usage, temperature, and power draw. Binary agent only The Docker agent does not support GPU monitoring. You **must use the binary agent**. AMD GPUs [​](#amd-gpus) ------------------------ Beszel uses `rocm-smi` to monitor AMD GPUs. This must be installed on the system. #### Make sure `rocm-smi` is accessible [​](#make-sure-rocm-smi-is-accessible) Installing `rocm-smi-lib` on Arch and Debian places the `rocm-smi` binary in `/opt/rocm`. If this isn't in the `PATH` of the user running `beszel-agent`, symlink to `/usr/local/bin`: bash sudo ln -s /opt/rocm/bin/rocm-smi /usr/local/bin/rocm-smi Nvidia GPUs [​](#nvidia-gpus) ------------------------------ Beszel uses `nvidia-smi` to monitor Nvidia GPUs. This must be installed on the system. Nvidia Jetson [​](#nvidia-jetson) ---------------------------------- Jetson is not compatible with `nvidia-smi` and not currently supported. It should be possible to get usage and system power using `tegrastats`. I will try to add support for this in the future. Intel GPUs [​](#intel-gpus) ---------------------------- Intel GPUs are not currently supported for two reasons: 1. I don't have an Intel GPU to test with. 2. There doesn't seem to be a straightforward utility like `nvidia-smi` to get utilization and memory usage. Please see [issue #262](https://github.com/henrygd/beszel/issues/262) for more information. --- # Additional Disks | Beszel Return to top Additional Disks [​](#additional-disks) ======================================== You can use Beszel to monitor disks, partitions, or remote mounts. The charts will use the name of the device or partition if available, and fall back to the directory name. You will not get I/O stats for network mounted drives. Finding device information Use `lsblk` to find the names and mount points of your partitions. If you have trouble, set `LOG_LEVEL=debug` on the agent and check the logs for the lines starting with `DEBUG Disk partitions` and `DEBUG Disk I/O diskstats`. The configuration differs depending on your deployment method. Docker agent [​](#docker-agent) -------------------------------- Mount a folder from the target filesystem in the container's `/extra-filesystems` directory: yaml volumes: - /mnt/disk1/.beszel:/extra-filesystems/sdb1:ro - /dev/mmcblk0/.beszel:/extra-filesystems/mmcblk0:ro TIP If you get disk usage but not I/O (common for encrypted devices) you can specify the device to use for I/O with the mounted directory name. This should be an entry in `/proc/diskstats`. See [0.7.3 release notes](https://github.com/henrygd/beszel/releases/tag/v0.7.3) for more details. Binary agent [​](#binary-agent) -------------------------------- Set the `EXTRA_FILESYSTEMS` environment variable to a comma-separated list of devices, partitions, or mount points to monitor. For example: bashbeszel-agent.service bash EXTRA_FILESYSTEMS="sdb,sdc1,mmcblk0,/mnt/network-share" KEY="..." ./beszel-agent ini [Service] Environment="EXTRA_FILESYSTEMS=sdb,sdc1,mmcblk0,/mnt/network-share" --- # Agent Installation | Beszel Return to top Agent Installation [​](#agent-installation) ============================================ Beszel Agent supports installation via Docker / Podman container, single binary file, or Home Assistant add-on. TIP Check the [Getting Started](./getting-started) guide if you're setting up Beszel for the first time. Requirements [​](#requirements) -------------------------------- If the agent and hub are on different hosts, you may need to update the firewall on your agent system to allow incoming TCP connections on the agent's port. Alternatively, you can use software like Wireguard or Cloudflare Tunnel ([instructions](https://github.com/henrygd/beszel/discussions/250) ) to securely bypass the firewall. Using the Hub [​](#using-the-hub) ---------------------------------- The `docker-compose.yml` or binary install command is provided for copy/paste in the hub's web UI when adding a new system. [![Add system dialog](/image/add-system-2.png)](/image/add-system-2.png) Docker or Podman [​](#docker-or-podman) ---------------------------------------- TIP Preconfigured `docker-compose.yml` content can be copied the hub's web UI when adding a new system, so in most cases you do not need to set this up manually. docker-compose.ymldocker runpodman run yaml services: beszel-agent: image: henrygd/beszel-agent container_name: beszel-agent restart: unless-stopped network_mode: host volumes: - /var/run/docker.sock:/var/run/docker.sock:ro # monitor other disks / partitions by mounting a folder in /extra-filesystems # - /mnt/disk1/.beszel:/extra-filesystems/disk1:ro environment: PORT: 45876 KEY: '' bash docker run -d \ --name beszel-agent \ --network host \ --restart unless-stopped \ -v /var/run/docker.sock:/var/run/docker.sock:ro \ -e KEY="" \ -e PORT=45876 \ henrygd/beszel-agent:latest bash podman run -d \ --name beszel-agent \ --network host \ --restart unless-stopped \ -v /var/run/docker.sock:/var/run/docker.sock:ro \ -e KEY="" \ -e PORT=45876 \ docker.io/henrygd/beszel-agent:latest ### Why host network mode? [​](#why-host-network-mode) The agent must use host network mode to access network interface metrics, which automatically exposes the port. Change the port using an environment variable if needed. If you don't need network stats, you can remove that line from the compose file and map the port manually. Binary [​](#binary) -------------------- There are multiple ways to install the binary. Choose your preference below. ### 1\. Quick script (Linux) [​](#_1-quick-script-linux) TIP A preconfigured command can be copied in the hub's web UI when adding a new system, so in most cases you do not need to run this command manually. This command downloads and runs our `install-agent.sh` script. The script installs the latest binary and creates a systemd service to keep it running after reboot. You may optionally enable automatic daily updates. * `-p`: Port (default: 45876) * `-k`: Public key (enclose in quotes; interactive if not provided) * `-u`: Uninstall * `--china-mirrors`: Use GitHub mirror to resolve network issues in mainland China bash curl -sL https://raw.githubusercontent.com/henrygd/beszel/main/supplemental/scripts/install-agent.sh -o install-agent.sh && chmod +x install-agent.sh && ./install-agent.sh ### 2\. Manual download and start [​](#_2-manual-download-and-start) Click to expand/collapse #### Download the binary [​](#download-the-binary) Download the latest binary from [releases](https://github.com/henrygd/beszel/releases) that matches your server's OS / architecture. bash curl -sL "https://github.com/henrygd/beszel/releases/latest/download/beszel-agent_$(uname -s)_$(uname -m | sed -e 's/x86_64/amd64/' -e 's/armv6l/arm/' -e 's/armv7l/arm/' -e 's/aarch64/arm64/').tar.gz" | tar -xz -O beszel-agent | tee ./beszel-agent >/dev/null && chmod +x beszel-agent #### Start the agent [​](#start-the-agent) * `PORT` : Port * `KEY` : Public Key bash PORT=45876 KEY="" ./beszel-agent #### Update the agent [​](#update-the-agent) bash ./beszel-agent update #### Create a service (optional) [​](#create-a-service-optional) If your system uses systemd, you can create a service to keep the agent running after reboot. 1. Create a service file in `/etc/systemd/system/beszel-agent.service`. ini [Unit] Description=Beszel Agent Service After=network.target [Service] Environment="PORT=$PORT" Environment="KEY=$KEY" # Environment="EXTRA_FILESYSTEMS=sdb" Restart=always RestartSec=5 ExecStart={/path/to/working/directory}/beszel-agent [Install] WantedBy=multi-user.target 2. Enable and start the service. bash sudo systemctl daemon-reload sudo systemctl enable beszel-agent.service sudo systemctl start beszel-agent.service ### 3\. Manual compile and start [​](#_3-manual-compile-and-start) Click to expand/collapse #### Compile [​](#compile) See [Compiling](./compiling) for information on how to compile the agent yourself. #### Start the agent [​](#start-the-agent-1) * `PORT` : Port * `KEY` : Public Key bash PORT=45876 KEY="" ./beszel-agent #### Update the agent [​](#update-the-agent-1) bash ./beszel-agent update #### Create a service (optional) [​](#create-a-service-optional-1) If your system uses systemd, you can create a service to keep the agent running after reboot. 1. Create a service file in `/etc/systemd/system/beszel-agent.service`. ini [Unit] Description=Beszel Agent Service After=network.target [Service] Environment="PORT=$PORT" Environment="KEY=$KEY" # Environment="EXTRA_FILESYSTEMS=sdb" Restart=always RestartSec=5 ExecStart={/path/to/working/directory}/beszel-agent [Install] WantedBy=multi-user.target 2. Enable and start the service. bash sudo systemctl daemon-reload sudo systemctl enable beszel-agent.service sudo systemctl start beszel-agent.service Home Assistant [​](#home-assistant) ------------------------------------ See the [Home Assistant Agent page](./home-assistant) for instructions on setting up the agent as a Home Assistant add-on. --- # Environment Variables | Beszel Return to top Environment Variables [​](#environment-variables) ================================================== Hub [​](#hub) -------------- | Name | Default | Description | | --- | --- | --- | | `CSP` | unset | Adds a [Content-Security-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)
header with this value. | | `DISABLE_PASSWORD_AUTH` | false | Disables password authentication. | | `USER_CREATION` | false | Enables automatic user creation for OAuth2 / OIDC. | Agent [​](#agent) ------------------ | Name | Default | Description | | --- | --- | --- | | `DOCKER_HOST` | unset | Overrides the docker host (docker.sock) if using a proxy. | | `EXTRA_FILESYSTEMS` | unset | Monitor extra disks if using binary. See [Additional Disks](./additional-disks)
. | | `FILESYSTEM` | unset | Device, partition, or mount point to use for root disk stats. | | `KEY` | unset | Public SSH key to use for authentication. Provided in hub. | | `LOG_LEVEL` | info | Logging level. Valid values: "debug", "info", "warn", "error". | | `MEM_CALC` | unset | Overrides the default memory calculation. | | `NICS` | unset | Whitelist of network interfaces to monitor for bandwidth. | | `PORT` | 45876 | Port or address:port to listen on. | | `SENSORS` | unset | Whitelist of temperature sensors to monitor. | | `SYS_SENSORS` | unset | Overrides sys path for sensors. See [#160](https://github.com/henrygd/beszel/discussions/160)
. | ### `DOCKER_HOST` [​](#docker-host) Beszel only needs access to read container information. For [linuxserver/docker-socket-proxy](https://github.com/linuxserver/docker-socket-proxy) you would set `CONTAINERS=1`. ### `MEM_CALC` [​](#mem-calc) The default value for used memory is based on gopsutil's [Used](https://pkg.go.dev/github.com/shirou/gopsutil/v4@v4.24.6/mem#VirtualMemoryStat) calculation, which should align fairly closely with `free`. Set `MEM_CALC` to `htop` to align with htop's calculation. --- # Hub Installation | Beszel Return to top Hub Installation [​](#hub-installation) ======================================== Beszel supports installation via Docker/ Podman or single binary file. TIP Check the [Getting Started](./getting-started) guide if you're setting up Beszel for the first time. Docker or Podman [​](#docker-or-podman) ---------------------------------------- All methods will start the Beszel service on port `8090` and mount the `./beszel_data` directory for persistent storage. docker-compose.ymldocker runpodman run yaml services: beszel: image: henrygd/beszel container_name: beszel restart: unless-stopped ports: - 8090:8090 volumes: - ./beszel_data:/beszel_data bash mkdir -p ./beszel_data && \ docker run -d \ --name beszel \ --restart=unless-stopped \ -v ./beszel_data:/beszel_data \ -p 8090:8090 \ henrygd/beszel bash mkdir -p ./beszel_data && \ podman run -d \ --name beszel \ --restart=unless-stopped \ -v ./beszel_data:/beszel_data \ -p 8090:8090 \ docker.io/henrygd/beszel Click to view complete `docker-compose.yml` config including local agent IMPORTANT This configuration should work out of the box, but you must follow these steps when adding the system in the web UI: 1. Update the `KEY` value with your public key, then run `docker compose up -d` again to restart the agent. 2. Use `host.docker.internal` as the **Host / IP**. Do not use `localhost` or `127.0.0.1`. docker-compose.yml yaml services: beszel: image: henrygd/beszel:latest container_name: beszel restart: unless-stopped extra_hosts: - host.docker.internal:host-gateway ports: - 8090:8090 volumes: - ./beszel_data:/beszel_data beszel-agent: image: henrygd/beszel-agent:latest container_name: beszel-agent restart: unless-stopped network_mode: host volumes: - /var/run/docker.sock:/var/run/docker.sock:ro environment: PORT: 45876 # Do not remove quotes around the key KEY: 'UPDATE WITH YOUR PUBLIC KEY (copy from "Add system" dialog)' Click to view instructions for running `docker compose` NOTE If you prefer to set up containers in a different way, please feel free to do so. 1. Install [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/) if you haven't already. 2. Copy the `docker-compose.yml` content. 3. Create a directory somewhere to store the `docker-compose.yml` file. bash mkdir beszel cd beszel 4. Create a `docker-compose.yml` file, paste in the content, and save it. nanovimemacsvscode bash nano docker-compose.yml bash vim docker-compose.yml bash emacs docker-compose.yml bash code docker-compose.yml 5. Start the service. bash docker compose up -d Binary [​](#binary) -------------------- There are multiple ways to install the binary. Choose your preference below. ### 1\. Quick script (Linux) [​](#_1-quick-script-linux) This command downloads and runs our `install-hub.sh` script. The script installs the latest binary and creates a systemd service to keep it running after reboot. * `-u` : Uninstall * `-p ` : Specify a port number (default: 8090) bash curl -sL https://raw.githubusercontent.com/henrygd/beszel/main/supplemental/scripts/install-hub.sh -o install-hub.sh && chmod +x install-hub.sh && ./install-hub.sh ### 2\. Manual download and start [​](#_2-manual-download-and-start) Click to expand/collapse #### Download [​](#download) Download the latest binary from [releases](https://github.com/henrygd/beszel/releases) that matches your server's CPU architecture and run it manually. You will need to create a service manually to keep it running after reboot. bash curl -sL "https://github.com/henrygd/beszel/releases/latest/download/beszel_$(uname -s)_$(uname -m | sed -e 's/x86_64/amd64/' -e 's/armv6l/arm/' -e 's/armv7l/arm/' -e 's/aarch64/arm64/').tar.gz" | tar -xz -O beszel | tee ./beszel >/dev/null && chmod +x beszel #### Start the hub [​](#start-the-hub) bash ./beszel serve --http "0.0.0.0:8090" #### Update the hub [​](#update-the-hub) bash ./beszel update #### Create a service (optional) [​](#create-a-service-optional) If your system uses systemd, you can create a service to keep the hub running after reboot. 1. Create a service file in `/etc/systemd/system/beszel.service`. A non-root user can be used if the user has write access to the working directory. ini [Unit] Description=Beszel Hub After=network.target [Service] Type=simple Restart=always RestartSec=3 User=root WorkingDirectory={/path/to/working/directory} ExecStart={/path/to/working/directory}/beszel serve --http "0.0.0.0:8090" [Install] WantedBy=multi-user.target 2. Enable and start the service. bash sudo systemctl daemon-reload sudo systemctl enable beszel.service sudo systemctl start beszel.service ### 3\. Manual compile and start [​](#_3-manual-compile-and-start) Click to expand/collapse #### Compile [​](#compile) See [Compiling](./compiling) for information on how to compile the hub yourself. #### Start the hub [​](#start-the-hub-1) bash ./beszel serve --http "0.0.0.0:8090" #### Update the hub [​](#update-the-hub-1) bash ./beszel update #### Create a service (optional) [​](#create-a-service-optional-1) If your system uses systemd, you can create a service to keep the hub running after reboot. 1. Create a service file in `/etc/systemd/system/beszel.service`. A non-root user can be used if the user has write access to the working directory. ini [Unit] Description=Beszel Hub After=network.target [Service] Type=simple Restart=always RestartSec=5 User=root WorkingDirectory={/path/to/working/directory} ExecStart={/path/to/working/directory}/beszel serve --http "0.0.0.0:8090" [Install] WantedBy=multi-user.target 2. Enable and start the service. bash sudo systemctl daemon-reload sudo systemctl enable beszel.service sudo systemctl start beszel.service --- # OAuth / OIDC | Beszel Return to top OAuth / OIDC [​](#oauth-oidc) ============================== You can authenticate users with an OAuth2 provider, like GitHub or Google, or a custom OpenID Connect provider, like Authelia or Zitadel. Redirect URL When creating your OAuth2 app, use **`/api/oauth2-redirect`** as the callback/redirect URL. Setup [​](#setup) ------------------ 1. Toggle off the "Hide collection create and edit controls" switch on `/_/#/settings`. [![hide-collection-create-and-edit-controls](/image/edit-toggle-off.png)](/image/edit-toggle-off.png) 2. Edit the `users` collection. [![edit-users-collection](/image/edit-users-collection.png)](/image/edit-users-collection.png) 3. In the "Options" tab, enable OAuth2 and add your provider. [![edit-users-collection-options](/image/oauth-settings.png)](/image/oauth-settings.png) 4. Toggle the switch back on in `/_/#/settings`. [![hide-collection-create-and-edit-controls](/image/edit-toggle-on.png)](/image/edit-toggle-on.png) Automatic user creation [​](#automatic-user-creation) ------------------------------------------------------ Beszel does not allow automatic user creation by default. To enable it, set `USER_CREATION=true` in the hub environment variables. Supported providers [​](#supported-providers) ---------------------------------------------- * Apple * Bitbucket * Discord * Facebook * Gitea * Gitee * GitHub * GitLab * Google * Instagram * Kakao * Linear * LiveChat * mailcow * Microsoft * monday.com * Notion * OpenID Connect * Patreon (v2) * Spotify * Strava * Twitch * Twitter * VK * WakaTime * Yandex --- # Compiling | Beszel Return to top Compiling [​](#compiling) ========================== Both the hub and agent are written in Go, so you can easily build them yourself, or cross-compile for different platforms. Please [install Go](https://go.dev/doc/install) first if you haven't already. Clone the repository [​](#clone-the-repository) ------------------------------------------------ bash # Clone the repository git clone --branch v0.9.1 --depth 1 https://github.com/henrygd/beszel.git # Navigate to the project directory cd beszel/beszel Commands below assume you are in the project directory (`/beszel`). Using Makefile [​](#using-makefile) ------------------------------------ Run `make`. This creates a `build` directory containing the binaries. bash # Builds both the agent and hub make # Builds the agent only make build-agent # Builds the hub only (requires Node or Bun) make build-hub You can also build for different platforms: bash make OS=freebsd ARCH=arm64 See a list of valid options by running `go tool dist list`. Manual compilation [​](#manual-compilation) -------------------------------------------- ### Prepare dependencies [​](#prepare-dependencies) bash go mod tidy ### Agent [​](#agent) Go to `beszel/cmd/agent` and run the following command to create a binary in the current directory: bash go build -ldflags "-w -s" . ### Hub [​](#hub) The hub embeds the web UI in the binary, so you must build the website first. I use [Bun](https://bun.sh/) , but you may use Node.js if you prefer: bash cd site bun install bun run build Then in `/beszel/cmd/hub`: bash go build -ldflags "-w -s" . ### Cross-compiling [​](#cross-compiling) You can cross-compile for different platforms using the `GOOS` and `GOARCH` environment variables. For example, to build for FreeBSD ARM64: bash GOOS=freebsd GOARCH=arm64 go build -ldflags "-w -s" . See a list of valid options by running `go tool dist list`. --- # 什么是 Beszel？ | Beszel 回到顶部 什么是 Beszel？ [​](#什么是-beszel) ============================= Beszel 是一个轻量级的服务器监控平台，包含 Docker 统计信息、历史数据和警报功能。 它拥有友好的 Web 界面、简单的配置，并且开箱即用。它支持自动备份、多用户、OAuth 身份验证和 API 访问。 [![代理镜像大小](https://img.shields.io/docker/image-size/henrygd/beszel-agent/0.6.0?logo=docker&label=agent%20image%20size)](https://hub.docker.com/r/henrygd/beszel-agent) [![中心镜像大小](https://img.shields.io/docker/image-size/henrygd/beszel/0.1.0?logo=docker&label=hub%20image%20size)](https://hub.docker.com/r/henrygd/beszel) [![MIT 许可证](https://img.shields.io/github/license/henrygd/beszel?color=%239944ee)](https://github.com/henrygd/beszel/blob/main/LICENSE) [![Crowdin 翻译](https://badges.crowdin.net/beszel/localized.svg)](https://crowdin.com/project/beszel) 功能 [​](#功能) ------------ * **轻量级**: 比主要解决方案更小，资源占用更少。 * **简单**: 易于设置，无需公网暴露。 * **Docker 统计**: 跟踪每个容器的 CPU、内存和网络使用历史。 * **警报**: 可配置 CPU、内存、磁盘、带宽、温度和状态的警报。 * **多用户**: 用户管理自己的系统。管理员可以在用户之间共享系统。 * **OAuth / OIDC**: 支持多种 OAuth2 提供程序。可以禁用密码验证。 * **自动备份**: 从磁盘或 S3 兼容的存储保存和恢复数据。 * **REST API**: 在您自己的脚本和应用程序中使用或更新您的数据。 架构 [​](#架构) ------------ Beszel 由两个主要组件组成：**中心 (hub)** 和 **代理 (agent)**。 * **中心 (hub)**: 一个基于 [PocketBase](https://pocketbase.io/) 构建的 Web 应用程序，提供用于查看和管理连接系统的仪表板。 * **代理 (agent)**: 在您要监控的每个系统上运行，创建一个最小的 SSH 服务器以将系统指标传递到中心。 屏幕截图 [​](#屏幕截图) ---------------- [![仪表板](/image/dashboard.png)](/image/dashboard.png) [![系统页面](/image/system-full.png)](/image/system-full.png) [![通知设置](/image/settings-notifications.png)](/image/settings-notifications.png) 支持的指标 [​](#支持的指标) ------------------ * **CPU 使用率** - 主机系统和 Docker / Podman 容器。 * **内存使用率** - 主机系统和容器。包括交换分区和 ZFS ARC。 * **磁盘使用率** - 主机系统。支持多个分区和设备。 * **磁盘 I/O** - 主机系统。支持多个分区和设备。 * **网络使用率** - 主机系统和容器。 * **温度** - 主机系统传感器。 * **GPU 使用率 / 温度 / 功耗** - 仅限 Nvidia 和 AMD。必须使用二进制代理。 --- # Podman Monitoring | Beszel Return to top Podman Monitoring [​](#podman-monitoring) ========================================== Note that currently this is an either-or situation. You can either use the Podman API or the Docker API, but not both at the same time. If you need both, let me know and I'll add it at some point. Start and enable the Podman API [​](#start-and-enable-the-podman-api) ---------------------------------------------------------------------- This runs the REST API service as a regular user on any Linux machine with Podman installed: bash systemctl --user enable podman.socket systemctl --user start podman.socket Restart the agent to allow it to connect to the Podman API. Permissions [​](#permissions) ------------------------------ You must run the agent as the same user that runs Podman. beszel-agent.servicepodman run ini [Service] User=beszel User=1000 bash podman run -d \ --name beszel-agent \ --user 1000 \ --network host \ --restart unless-stopped \ -v /var/run/docker.sock:/var/run/docker.sock:ro \ -e KEY="" \ -e PORT=45876 \ docker.io/henrygd/beszel-agent:latest Specifying a different socket path [​](#specifying-a-different-socket-path) ---------------------------------------------------------------------------- The agent checks for the Podman socket at `/run/user/{uid}/podman/podman.sock`. If you need to use a different path, specify it in the `DOCKER_HOST` environment variable: `DOCKER_HOST=unix:///path/to/podman.sock`. --- # REST API | Beszel Return to top REST API [​](#rest-api) ======================== Because Beszel is built on PocketBase, you can use the PocketBase [web APIs](https://pocketbase.io/docs/api-records/) and [client-side SDKs](https://pocketbase.io/docs/client-side-sdks/) to read or update data from outside Beszel itself. Basic example [​](#basic-example) ---------------------------------- This example uses the [PocketBase JS SDK](https://github.com/pocketbase/js-sdk) to read data from the `systems` collection. ts import PocketBase from 'pocketbase' const pb = new PocketBase('http://localhost:8090') // authenticate as regular user const userData = await pb.collection('users').authWithPassword('[email protected]', '123456') // list and filter system records const systems = await pb.collection('systems').getList(1, 20, { filter: 'status = "up" && created > "2024-06-01 10:00:00"', }) console.log(systems) Adding users to systems [​](#adding-users-to-systems) ------------------------------------------------------ This example adds specific users to specific systems. ts import PocketBase from 'pocketbase' const pb = new PocketBase('http://localhost:8090') // users we will add to systems const userEmails = ['[email protected]', '[email protected]'] // system names we will add users to const systemNames = ['localhost', 'kagemusha'] // authenticate as admin await pb.admins.authWithPassword(process.env.EMAIL, process.env.PASSWORD) // get user ids const userIds = await pb .collection('users') .getFullList({ fields: 'id', filter: `email='${userEmails.join(`'||email='`)}'`, }) .then((records) => records.map(({ id }) => id)) // get id and current users for systems const systemsData = await pb.collection('systems').getFullList({ fields: 'id,users', filter: `name='${systemNames.join(`'||name='`)}'`, }) // loop through systems and add users to them for (const system of systemsData) { const updatedUsers = Array.from(new Set([...system.users, ...userIds])) await pb.collection('systems').update(system.id, { users: updatedUsers }) } --- # User Roles | Beszel Return to top User Roles [​](#user-roles) ============================ Admin [​](#admin) ------------------ Admins have access to additional links in the hub, such as backups, SMTP settings, etc. The first user created is automatically set to admin and has a PocketBase superuser account with the same email and password. PocketBase superusers are separate from Beszel user roles Changing a user's role to admin does not create a PocketBase superuser account. If you want to allow them to access the PocketBase admin panel, you must create a superuser account manually. User [​](#user) ---------------- Users can create their own systems and alerts. Links to PocketBase settings are not shown in the hub. Read only [​](#read-only) -------------------------- Read-only users cannot create systems but can view any system shared with them by an admin and create alerts. --- # 开始使用 | Beszel 回到顶部 开始使用 [​](#开始使用) ================ 有关背景信息，请参阅 [什么是 Beszel？](./what-is-beszel) 页面。 1\. 启动中心 (hub) [​](#_1-启动中心-hub) --------------------------------- 中心可以通过单独的二进制文件或 Docker / Podman 容器运行。 * [二进制文件](./hub-installation#二进制文件) * [Docker / Podman](./hub-installation#docker-或-podman) 单击查看完整的 `docker-compose.yml` 配置，包括本地代理 重要 此配置通常可以直接使用，但在 Web 界面添加系统时需要执行以下步骤： 1. 使用您的公钥更新 `KEY` 值，然后再次运行 `docker compose up -d` 以重新启动代理 2. 将 `host.docker.internal` 用作 **主机/IP**。 请勿使用 `localhost` 或 `127.0.0.1` docker-compose.yml yaml services: beszel: image: henrygd/beszel:latest container_name: beszel restart: unless-stopped extra_hosts: - host.docker.internal:host-gateway ports: - 8090:8090 volumes: - ./beszel_data:/beszel_data beszel-agent: image: henrygd/beszel-agent:latest container_name: beszel-agent restart: unless-stopped network_mode: host volumes: - /var/run/docker.sock:/var/run/docker.sock:ro environment: PORT: 45876 # 请勿删除密钥周围的引号 KEY: '使用“添加系统”对话框复制的公钥进行更新' 单击查看运行 `docker compose` 的说明 注意 如果您更喜欢以不同的方式设置容器，请随意 1. 如果尚未安装，请安装 [Docker](https://docs.docker.com/engine/install/) 和 [Docker Compose](https://docs.docker.com/compose/install/) . 2. 复制 `docker-compose.yml` 内容 3. 创建一个目录用于存储 `docker-compose.yml` 文件 bash mkdir beszel cd beszel 4. 创建一个 `docker-compose.yml` 文件，粘贴内容并保存 nanovimemacsvscode bash nano docker-compose.yml bash vim docker-compose.yml bash emacs docker-compose.yml bash code docker-compose.yml 5. 启动服务 bash docker compose up -d 2\. 创建管理员用户 [​](#_2-创建管理员用户) ----------------------------- 启动中心 (hub) 后，导航至 [http://localhost:8090](http://localhost:8090) 或您选择的地址。 系统将提示您创建帐户： [![用户创建表单截图](/image/admin-creation.png)](/image/admin-creation.png) 3\. 配置您的第一个系统 [​](#_3-配置您的第一个系统) --------------------------------- 单击右上角的 添加系统 (Add System) 按钮以打开系统创建对话框。本示例中我们使用的是 localhost，但您也可以使用远程代理。 在启动代理之前，请勿点击对话框中的 添加系统 (Add System) 按钮。 [![系统创建表单截图](/image/add-system.png)](/image/add-system.png) 4\. 启动代理 [​](#_4-启动代理) ----------------------- Docker 指令 注意 如果您更喜欢以不同的方式设置容器，请随意操作。 1. 从 添加系统 (Add System) 对话框复制 docker-compose.yml 内容。 2. 创建一个目录来存储代理的 docker-compose.yml 文件。 bash mkdir beszel-agent cd beszel-agent 3. 创建一个名为 docker-compose.yml 的文件，并粘贴 添加系统 (Add System) 对话框中提供的内容。 nanovimemacsvscode bash nano docker-compose.yml bash vim docker-compose.yml bash emacs docker-compose.yml bash code docker-compose.yml 4. 启动代理 bash docker compose up -d 二进制文件安装说明 安装脚本仅适用于 Linux 系统 如果您使用的是其他操作系统，请手动下载并运行适合您系统的正确二进制文件。有关详细信息，请参阅 代理安装 页面或 编译 页面。 从 添加系统 (Add System) 对话框复制二进制安装命令。 打开终端并运行该命令。 这将下载正确的二进制文件，创建一个名为 beszel 的用户，并启动代理。它还将创建一个服务以使其在重新启动后继续运行，并可以选择启用自动每日更新。 5\. 完成添加系统 [​](#_5-完成添加系统) --------------------------- 现在代理正在运行，请单击对话框中的 添加系统 (Add System) 按钮。 您将在表格中看到新系统。如果它变为绿色，则表示一切正常。 [![系统创建表单截图](/image/new-system.png)](/image/new-system.png) 如果它变为红色，请查看 [常见问题](./common-issues) 页面。 --- # 其他磁盘 | Beszel 回到顶部 其他磁盘 [​](#其他磁盘) ================ 您可以使用 Beszel 监控磁盘、分区或远程挂载。 图表将使用设备或分区的名称（如果可用），否则将回退到目录名。您将无法获得网络挂载驱动器的 I/O 统计信息。 查找设备信息 使用 `lsblk` 命令查找分区的名称和挂载点。 如果遇到问题，请在代理上设置 `LOG_LEVEL=debug` 并检查日志中以 `DEBUG Disk partitions` 和 `DEBUG Disk I/O diskstats` 开头的行。 配置会根据您的部署方式而异。 Docker 代理 [​](#docker-代理) -------------------------- 在容器的 `/extra-filesystems` 目录中挂载目标文件系统中的文件夹： yaml volumes: - /mnt/disk1/.beszel:/extra-filesystems/sdb1:ro # 只读模式 - /dev/mmcblk0/.beszel:/extra-filesystems/mmcblk0:ro # 只读模式 提示 如果您可以看到磁盘使用情况但看不到 I/O（加密设备常见），您可以使用挂载目录名指定用于 I/O 的设备。这应该是 `/proc/diskstats` 中的条目。有关详细信息，请参阅 [0.7.3 发布说明](https://github.com/henrygd/beszel/releases/tag/v0.7.3) 。 二进制代理 [​](#二进制代理) ------------------ 将 `EXTRA_FILESYSTEMS` 环境变量设置为要监视的设备、分区或挂载点的逗号分隔列表。例如： bashbeszel-agent.service bash EXTRA_FILESYSTEMS="sdb,sdc1,mmcblk0,/mnt/network-share" KEY="..." ./beszel-agent ini [Service] Environment="EXTRA_FILESYSTEMS=sdb,sdc1,mmcblk0,/mnt/network-share" --- # Common Issues | Beszel Return to top Common Issues [​](#common-issues) ================================== Agent is not connecting [​](#agent-is-not-connecting) ------------------------------------------------------ Check the logs page in PocketBase (`/_/#/logs`) for information about the error. The most likely cause is a firewall blocking the connection request. In this case you have two options: 1. Add an inbound rule to the agent system's firewall(s) to allow TCP connections to the port. Check any active firewalls, like iptables, and your cloud provider's firewall settings if applicable. 2. Alternatively, use software like WireGuard, Tailscale ([video instructions](https://www.youtube.com/watch?v=O_9wT-5LoHM) ), or Cloudflare Tunnel ([instructions](https://github.com/henrygd/beszel/discussions/250) ) to securely bypass the firewall. You can test connectivity by running `telnet ` from another device on your network. Connecting hub and agent on the same system using Docker [​](#connecting-hub-and-agent-on-the-same-system-using-docker) ------------------------------------------------------------------------------------------------------------------------ If using host network mode for the agent but not the hub, add your system using the hostname `host.docker.internal`, which resolves to the internal IP address used by the host. See the [Getting Started](./getting-started) guide for a full `docker-compose.yml` example. If using host network mode for both, you can use `localhost` as the hostname. Otherwise, use the agent's `container_name` as the hostname if both are in the same Docker network. Finding the correct filesystem [​](#finding-the-correct-filesystem) -------------------------------------------------------------------- Specify the filesystem/device/partition for root disk stats using the `FILESYSTEM` environment variable. If not set, the agent will try to find the partition mounted on `/` and use that. This may not work correctly in a container, so it's recommended to set this value. Use one of the following methods to find the correct filesystem: * Run `lsblk` and choose an option under "NAME." * Run `df -h` and choose an option under "Filesystem." * Run `sudo fdisk -l` and choose an option under "Device." Docker container charts are empty or missing [​](#docker-container-charts-are-empty-or-missing) ------------------------------------------------------------------------------------------------ If container charts show empty data or don't appear at all, you may need to enable cgroup memory accounting. To verify, run `docker stats`. If that shows zero memory usage, follow this guide to fix the issue: [https://akashrajpurohit.com/blog/resolving-missing-memory-stats-in-docker-stats-on-raspberry-pi/](https://akashrajpurohit.com/blog/resolving-missing-memory-stats-in-docker-stats-on-raspberry-pi/) Docker containers are not populating reliably [​](#docker-containers-are-not-populating-reliably) -------------------------------------------------------------------------------------------------- Upgrade your Docker version on the agent system if possible. There is a bug in Docker 24, and possibly earlier versions, that may cause this issue. We've added a workaround to the agent to mitigate this issue, but it's not a perfect fix. Month / week records are not populating reliably [​](#month-week-records-are-not-populating-reliably) ------------------------------------------------------------------------------------------------------ Records for longer time periods are created by averaging stats from shorter periods. The agent must run uninterrupted for a full set of data to populate these records. Pausing/unpausing the agent for longer than one minute will result in incomplete data, resetting the timing for the current interval. --- # Docker Shell | Beszel Return to top Docker Shell [​](#docker-shell) ================================ Beszel uses a [scratch image](https://hub.docker.com/_/scratch) with no shell. This means you can't use `docker exec -it /bin/sh` to debug from inside the container. However, you can use the `build` option with a custom Dockerfile to move the binary into the base image of your choice. Create a Dockerfile [​](#create-a-dockerfile) ---------------------------------------------- Save the following as `Dockerfile` in the same directory as your `docker-compose.yml`: HubAgent dockerfile FROM henrygd/beszel:latest as beszel # Define the new base image FROM alpine:latest # Add tools (curl, telnet, traceroute, netstat, host, nslookup, dig, delv) RUN apk add --no-cache bash curl busybox-extras bind-tools # Copy the binary into the new image COPY --from=beszel /beszel /beszel ENTRYPOINT [ "/beszel" ] CMD ["serve", "--http=0.0.0.0:8090"] dockerfile FROM henrygd/beszel-agent:latest as beszel # Define the new base image FROM alpine:latest # Add tools (curl, telnet, traceroute, netstat, host, nslookup, dig, delv) RUN apk add --no-cache bash curl busybox-extras bind-tools # Copy the binary into the new image COPY --from=beszel /agent /agent ENTRYPOINT ["/agent"] Update your `docker-compose.yml` [​](#update-your-docker-compose-yml) ---------------------------------------------------------------------- Remove the `image` key and add a `build` key to your service: HubAgent yaml beszel: image: henrygd/beszel build: . yaml beszel-agent: image: henrygd/beszel-agent build: . Restart the container and access the shell [​](#restart-the-container-and-access-the-shell) -------------------------------------------------------------------------------------------- bash docker-compose up -d --build docker exec -it bash Multiple Dockerfiles in one compose file [​](#multiple-dockerfiles-in-one-compose-file) ---------------------------------------------------------------------------------------- Use this approach if your hub and agent share the same compose file and you want to debug both. Save the dockerfiles with different names, e.g. `Dockerfile_hub` and `Dockerfile_agent` and update the `build` key in your `docker-compose.yml`: yaml beszel: build: context: . dockerfile: Dockerfile_hub beszel-agent: build: context: . dockerfile: Dockerfile_agent --- # Multilingual and localization | Beszel Return to top Multilingual and localization [​](#multilingual-and-localization) ================================================================== Thanks for your interest in contributing to Beszel! Software [​](#software) ------------------------ [![Crowdin](https://badges.crowdin.net/beszel/localized.svg)](https://crowdin.com/project/beszel) Contributions to improve Beszel's translations are welcome: [crowdin/beszel](https://crowdin.com/project/beszel) If you want to add a new language, please [post a discussion on Crowdin](https://crowdin.com/project/beszel/discussions) or open an issue on GitHub. I don't always get notified when languages are requested using the native Crowdin functionality. Documentation [​](#documentation) ---------------------------------- The repository for this documentation located at [https://github.com/henrygd/beszel-docs](https://github.com/henrygd/beszel-docs) . If you want to contribute, please fork the repository and submit a pull request. Reference the `zh` directory for the Chinese translations. If you want to add a new language, create a new directory with the language code (`es`, `fr`, etc.). --- # 环境变量 | Beszel 回到顶部 环境变量 [​](#环境变量) ================ 中心 (Hub) [​](#中心-hub) ---------------------- | 名称 | 默认值 | 描述 | | --- | --- | --- | | `CSP` | 未设置 | 添加具有此值的 [Content-Security-Policy](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Content-Security-Policy)
头。 | | `DISABLE_PASSWORD_AUTH` | false | 禁用密码认证。 | | `USER_CREATION` | false | 启用 OAuth2 / OIDC 的自动用户创建。 | 代理 (Agent) [​](#代理-agent) -------------------------- | 名称 | 默认值 | 描述 | | --- | --- | --- | | `DOCKER_HOST` | 未设置 | 如果使用代理，则覆盖 Docker 主机 (docker.sock)。 | | `EXTRA_FILESYSTEMS` | 未设置 | 如果使用二进制文件，则监控额外的磁盘。请参阅 [其他磁盘](./additional-disks)
。 | | `FILESYSTEM` | 未设置 | 用于根磁盘统计的设备、分区或挂载点。 | | `KEY` | 未设置 | 用于身份验证的公共 SSH 密钥。在中心提供。 | | `LOG_LEVEL` | info | 日志级别。有效值: "debug", "info", "warn", "error"。 | | `MEM_CALC` | 未设置 | 覆盖默认内存计算。 | | `NICS` | 未设置 | 用于监控带宽的网络接口白名单。 | | `PORT` | 45876 | 要监听的端口或地址:端口。 | | `SENSORS` | 未设置 | 用于监控的温度传感器白名单。 | | `SYS_SENSORS` | 未设置 | 覆盖用于传感器的系统路径。请参阅 [#160](https://github.com/henrygd/beszel/discussions/160)
。 | ### `DOCKER_HOST` [​](#docker-host) Beszel 只需要访问读取容器信息权限。对于 [linuxserver/docker-socket-proxy](https://github.com/linuxserver/docker-socket-proxy) 您将设置 `CONTAINERS=1`。 ### `MEM_CALC` [​](#mem-calc) 已用内存的默认值基于 gopsutil 的 [Used](https://pkg.go.dev/github.com/shirou/gopsutil/v4@v4.24.6/mem#VirtualMemoryStat) 计算，该计算应该与 `free` 非常接近。将 `MEM_CALC` 设置为 `htop` 以使其与 htop 的计算保持一致。 --- # Beszel | 轻量易用的服务器监控 Beszel ====== 轻量易用的服务器监控 包含 Docker 统计信息、历史数据和警报。 [什么是 Beszel？](/zh/guide/what-is-beszel) [快速入门](/zh/guide/getting-started) [GitHub](https://github.com/henrygd/beszel) ![Slideshow Image](/image/home-alerts.webp) ![Slideshow Image](/image/home-dashboard.png) ![Slideshow Image](/image/home-system.png) 轻量级 --- 比主要解决方案更小，资源占用更少。 简单 -- 易于设置，无需公网暴露。 Docker / Podman 统计 ------------------ 跟踪每个容器的 CPU、内存和网络使用历史。 警报 -- 可配置 CPU、内存、磁盘、带宽、温度和系统状态的警报。 多用户 --- 每个用户管理自己的系统。管理员可以在用户之间共享系统。 OAuth / OIDC ------------ 支持多种 OAuth2 提供程序。可以禁用密码验证。 自动备份 ---- 从磁盘或 S3 兼容的存储保存和恢复数据。 REST API -------- 在您自己的脚本和应用程序中使用或更新您的数据。 --- # Security | Beszel Return to top Security [​](#security) ======================== The hub and agent communicate over SSH, so they don't need to be exposed to the internet. Even if you place an external auth gateway, such as Authelia, in front of the hub, it won't disrupt or break the connection between the hub and agent. When the hub is started for the first time, it generates an ED25519 key pair. The agent's SSH server is configured to accept connections using this key only. It does not provide a pseudo-terminal or accept input, so it's impossible to execute commands on the agent even if your private key is compromised. Reporting a Vulnerability [​](#reporting-a-vulnerability) ---------------------------------------------------------- If you find a vulnerability in the latest version, please [submit a private advisory](https://github.com/henrygd/beszel/security/advisories/new) . If it's low severity (use best judgement) you may open an issue instead of an advisory. Network requirements [​](#network-requirements) ------------------------------------------------ This is a list of ports and remote hosts that Beszel communicates with, based on the default configuration. Using SMTP for email or S3 for backups will require connections to other hosts. ### Agent [​](#agent) #### Incoming [​](#incoming) | Port | Purpose | | --- | --- | | 45876 | Allows the hub to connect to the agent via SSH | #### Outgoing [​](#outgoing) | Remote host | Port | Purpose | | --- | --- | --- | | github.com | 443 | Check / download updates (not needed if using Docker) | ### Hub [​](#hub) #### Incoming [​](#incoming-1) | Port | Purpose | | --- | --- | | 8090 | HTTP access to the web UI | #### Outgoing [​](#outgoing-1) | Remote host | Port | Purpose | | --- | --- | --- | | agents | 45876 | SSH connection to your agents | | github.com | 443 | Check / download updates (not needed if using Docker) | --- # 用户角色 | Beszel 回到顶部 用户角色 [​](#用户角色) ================ 管理员 `admin` [​](#管理员-admin) ---------------------------- 管理员可以访问中心 (hub) 中的其他链接，例如备份、SMTP 设置等。 创建的第一个用户会自动设置为管理员，并拥有使用相同电子邮件和密码的 PocketBase 超级用户帐户。 提示 PocketBase 超级用户与 Beszel 用户角色是分开的 将用户的角色更改为管理员不会创建 PocketBase 超级用户帐户。如果您想允许他们访问 PocketBase 管理面板，则必须手动创建一个超级用户帐户。 用户 `user` [​](#用户-user) ------------------------ 用户可以创建自己的系统和警报。中心 (hub) 中不显示 PocketBase 设置的链接。 只读 `readonly` [​](#只读-readonly) -------------------------------- 只读用户无法创建系统，但可以查看管理员与他们共享的任何系统并创建警报。 --- # OAuth / OIDC 认证 | Beszel 回到顶部 OAuth / OIDC 认证 [​](#oauth-oidc-认证) ==================================== 您可以使用 OAuth2 提供商（例如 GitHub 或 Google）或自定义 OpenID Connect 提供商（例如 Authelia 或 Zitadel）来验证用户身份。 重定向 URL 创建 OAuth2 应用时，请将 **`<您的 Beszel URL>/api/oauth2-redirect`** 用作回调/重定向 URL。 设置 [​](#设置) ------------ 1. 在 `/_/#/settings` 中关闭“隐藏收藏创建和编辑控件”开关。 [![隐藏收藏创建和编辑控件](/image/edit-toggle-off.png)](/image/edit-toggle-off.png) 2. 编辑“用户”集合。 [![编辑用户集合](/image/edit-users-collection.png)](/image/edit-users-collection.png) 3. 在“选项”标签中，启用 OAuth2 并添加您的提供商。 [![编辑用户集合选项](/image/oauth-settings.png)](/image/oauth-settings.png) 4. 在 `/_/#/settings` 中重新打开开关。 [![隐藏收藏创建和编辑控件](/image/edit-toggle-on.png)](/image/edit-toggle-on.png) 自动用户创建 [​](#自动用户创建) -------------------- Beszel 默认情况下不允许自动创建用户。要启用它，请在中心的环境变量中设置 `USER_CREATION=true`。 支持的提供商 [​](#支持的提供商) -------------------- * Apple * Bitbucket * Discord * Facebook * Gitea * Gitee * GitHub * GitLab * Google * Instagram * Kakao * Linear * LiveChat * mailcow * Microsoft * monday.com * Notion * OpenID Connect * Patreon (v2) * Spotify * Strava * Twitch * Twitter * VK * WakaTime * Yandex --- # 编译 | Beszel 回到顶部 编译 [​](#编译) ============ Beszel 中心 (hub) 和代理都使用 Go 语言编写，因此您可以轻松地自己构建它们，或者为不同的平台进行交叉编译。 如果您还没有安装 Go 语言，请先 [安装 Go](https://go.dev/doc/install) 。 克隆代码库 [​](#克隆代码库) ------------------ bash # 克隆代码库 git clone --branch v0.9.1 --depth 1 https://github.com/henrygd/beszel.git # 导航到项目目录 cd beszel/beszel 以下命令假设您位于项目目录 (`/beszel`) 中。 使用 Makefile [​](#使用-makefile) ------------------------------ 运行 `make` 命令。这将在 `build` 目录中创建包含二进制文件的目录。 bash # 构建中心和代理（同时） make # 只构建代理 make build-agent # 只构建中心（需要 Node 或 Bun） make build-hub 您还可以为不同的平台进行构建： bash make OS=freebsd ARCH=arm64 运行 `go tool dist list` 命令查看有效的选项列表。 手动编译 [​](#手动编译) ---------------- ### 准备依赖项 [​](#准备依赖项) bash go mod tidy ### 代理 [​](#代理) 进入 `beszel/cmd/agent` 目录并运行以下命令可在当前目录中创建二进制文件： bash go build -ldflags "-w -s" . ### 中心 [​](#中心) 中心会将 Web UI 嵌入到二进制文件中，因此您必须首先构建网站。我使用的是 [Bun](https://bun.sh/) ，但如果您愿意也可以使用 Node.js： bash cd site bun install bun run build 然后在 `/beszel/cmd/hub` 中： bash go build -ldflags "-w -s" . ### 交叉编译 [​](#交叉编译) 您可以使用 `GOOS` 和 `GOARCH` 环境变量为不同的平台进行交叉编译。 例如，要为 FreeBSD ARM64 构建： bash GOOS=freebsd GOARCH=arm64 go build -ldflags "-w -s" . 运行 `go tool dist list` 命令查看有效的选项列表。 --- # Home Assistant Agent | Beszel Return to top Home Assistant Agent [​](#home-assistant-agent) ================================================ Home Assistant Add-ons are maintained by third parties. Currently there are two options: * `Obamium69/hassio-beszel_agent` ([GitHub](https://github.com/Obamium69/hassio-beszel_agent) ) * `matthewhadley/homeassistant-beszel-agent` ([GitHub](https://github.com/matthewhadley/homeassistant-beszel-agent) ) Add Repo to Home Assistant [​](#add-repo-to-home-assistant) ------------------------------------------------------------ 1. Log in to your Home Assistant instance and go to "Add-ons". [![Agent add-on visible in Home Assistant](/image/hass/open-addons.png)](/image/hass/open-addons.png) 2. Click on "ADD-ON STORE", open the three dots, and choose "Repositories". [![Agent add-on visible in Home Assistant](/image/hass/open-addonsstore.png)](/image/hass/open-addonsstore.png) [![Agent add-on visible in Home Assistant](/image/hass/add-repo.png)](/image/hass/add-repo.png) 3. Add one of the following repositories: * `https://github.com/Obamium69/hassio-beszel_agent` * `https://github.com/matthewhadley/homeassistant-beszel-agent` Configure Add-on [​](#configure-add-on) ---------------------------------------- 1. The add-on should now appear in the add-ons store. Just click on it and press "Install". [![Agent add-on visible in Home Assistant](/image/hass/homeassistant-addon.png)](/image/hass/homeassistant-addon.png) 2. The add-on is now installed. Go back to the overview of the currently installed add-ons, open the agent add-on, and switch to the "Configuration" tab. 3. Follow [these](./getting-started#_3-configure-your-first-system) instructions to configure the agent, and then copy the public key. 4. Go back to Home Assistant, paste the public key into the input field, and press "SAVE". 5. Start the add-on. --- # Podman 监控 | Beszel 回到顶部 Podman 监控 [​](#podman-监控) ========================== 请注意，目前这是一个非此即彼的情况。您可以使用 Podman API 或 Docker API，但不能同时使用两者。如果您都需要，请告诉我，我稍后会添加它。 启动并启用 Podman API [​](#启动并启用-podman-api) ---------------------------------------- 以下命令可在安装了 Podman 的任何 Linux 机器上以普通用户身份运行 REST API 服务： bash systemctl --user enable podman.socket systemctl --user start podman.socket 重新启动代理以使其连接到 Podman API。 权限 [​](#权限) ------------ 您必须以运行 Podman 的相同用户身份运行代理程序。 beszel-agent.servicepodman run ini [Service] User=beszel User=1000 bash podman run -d \ --name beszel-agent \ --user 1000 \ --network host \ --restart unless-stopped \ -v /var/run/docker.sock:/var/run/docker.sock:ro \ -e KEY="" \ -e PORT=45876 \ docker.io/henrygd/beszel-agent:latest 指定不同的套接字路径 [​](#指定不同的套接字路径) ---------------------------- 代理程序会在 `/run/user/{uid}/podman/podman.sock` 处检查 Podman 套接字。 如果您需要使用不同的路径，请在 `DOCKER_HOST` 环境变量中指定它：`DOCKER_HOST=unix:///path/to/podman.sock` --- # Developer Guide | Beszel Return to top Developer Guide [​](#developer-guide) ====================================== Thanks for your interest in contributing to Beszel! Contributions are welcome, but it's a good idea to check with us first in a discussion or issue if you plan on doing anything significant. Prerequisites [​](#prerequisites) ---------------------------------- * Go 1.23+ (for making changes in the Go code) * Bun 1.1.38+ or Node 18+ (for making changes in the web UI) If you haven't already, [fork the repository](https://github.com/henrygd/beszel/fork) and clone your fork to work locally: bash git clone https://github.com/your_username/beszel.git Separate branches for separate changes It is recommended to create a new branch for each of your bugfixes and features. This is required if you are planning to submit multiple PRs in order to keep the changes separate for review until they eventually get merged. Development environment [​](#development-environment) ------------------------------------------------------ Three processes need to be started in order to work on the project: 1. The hub (Go) 2. The agent (Go) 3. The web UI (TypeScript / Vite) There are `make` commands to start each of these jobs (run in `/beszel`). bash # Start the hub make dev-hub # Start the agent KEY="..." make dev-agent # Start the web UI make dev-server Alternatively, you can start all processes at once with combined output: bash KEY="..." make -j dev Navigate to [http://localhost:8090](http://localhost:8090) to view the web UI. TIP If [`entr`](https://github.com/eradman/entr) is installed, the hub / agent will automatically rebuild when you save changes to the code. --- # GPU 监控 | Beszel 回到顶部 GPU 监控 [​](#gpu-监控) ==================== Beszel 可以监控 GPU 使用率、温度和功耗。 WARNING 仅适用于二进制代理 Docker 代理不支持 GPU 监控。您 **必须使用二进制代理**. AMD GPU [​](#amd-gpu) ---------------------- Beszel 使用 `rocm-smi` 监控 AMD GPU。该工具必须安装在系统上。 #### 确保可以访问 `rocm-smi` [​](#确保可以访问-rocm-smi) 在 Arch 和 Debian 上安装 `rocm-smi-lib` 会将 `rocm-smi` 二进制文件放置在 `/opt/rocm` 中。如果该目录不在运行 `beszel-agent` 的用户的 `PATH` 环境变量中，请将其符号链接到 `/usr/local/bin`: bash sudo ln -s /opt/rocm/bin/rocm-smi /usr/local/bin/rocm-smi Nvidia GPU [​](#nvidia-gpu) ---------------------------- Beszel 使用 `nvidia-smi` 监控 Nvidia GPU。该工具必须安装在系统上。 Nvidia Jetson [​](#nvidia-jetson) ---------------------------------- Jetson 不兼容 `nvidia-smi`，目前也不受支持。 应该可以使用 `tegrastats` 获取使用情况和系统功耗。我将尝试在未来添加对此的支持。 Intel GPU [​](#intel-gpu) -------------------------- 由于以下两个原因，目前不支持英特尔显卡： 1. 我没有可用于测试的英特尔显卡。 2. 似乎没有像 `nvidia-smi` 这样可以直接获取利用率和内存使用情况的简单工具。 有关更多信息，请参阅 [issue #262](https://github.com/henrygd/beszel/issues/262) 。 --- # Hub 安装 | Beszel 回到顶部 Hub 安装 [​](#hub-安装) ==================== Beszel 支持通过 Docker/ Podman 或单个二进制文件进行安装。 提示 如果您是首次设置 Beszel，请查看 [开始使用](./getting-started) 指南。 Docker 或 Podman [​](#docker-或-podman) -------------------------------------- 所有方法都将在端口 `8090` 上启动 Beszel 服务，并挂载 `./beszel_data` 目录用于持久存储。 docker-compose.ymldocker runpodman run yaml services: beszel: image: henrygd/beszel container_name: beszel restart: unless-stopped ports: - 8090:8090 volumes: - ./beszel_data:/beszel_data bash mkdir -p ./beszel_data && \ docker run -d \ --name beszel \ --restart=unless-stopped \ -v ./beszel_data:/beszel_data \ -p 8090:8090 \ henrygd/beszel bash mkdir -p ./beszel_data && \ podman run -d \ --name beszel \ --restart=unless-stopped \ -v ./beszel_data:/beszel_data \ -p 8090:8090 \ docker.io/henrygd/beszel 单击查看完整的 `docker-compose.yml` 配置，包括本地代理 重要 此配置通常可以直接使用，但在 Web 界面添加系统时需要执行以下步骤： 1. 使用您的公钥更新 `KEY` 值，然后再次运行 `docker compose up -d` 以重新启动代理 2. 将 `host.docker.internal` 用作 **主机/IP**。 请勿使用 `localhost` 或 `127.0.0.1` docker-compose.yml yaml services: beszel: image: henrygd/beszel:latest container_name: beszel restart: unless-stopped extra_hosts: - host.docker.internal:host-gateway ports: - 8090:8090 volumes: - ./beszel_data:/beszel_data beszel-agent: image: henrygd/beszel-agent:latest container_name: beszel-agent restart: unless-stopped network_mode: host volumes: - /var/run/docker.sock:/var/run/docker.sock:ro environment: PORT: 45876 # 请勿删除密钥周围的引号 KEY: '使用“添加系统”对话框复制的公钥进行更新' 单击查看运行 `docker compose` 的说明 注意 如果您更喜欢以不同的方式设置容器，请随意 1. 如果尚未安装，请安装 [Docker](https://docs.docker.com/engine/install/) 和 [Docker Compose](https://docs.docker.com/compose/install/) . 2. 复制 `docker-compose.yml` 内容 3. 创建一个目录用于存储 `docker-compose.yml` 文件 bash mkdir beszel cd beszel 4. 创建一个 `docker-compose.yml` 文件，粘贴内容并保存 nanovimemacsvscode bash nano docker-compose.yml bash vim docker-compose.yml bash emacs docker-compose.yml bash code docker-compose.yml 5. 启动服务 bash docker compose up -d 二进制文件 [​](#二进制文件) ------------------ 安装二进制文件有多种方法。 请选择您喜欢的方式。 ### 1\. 快速脚本 (Linux) [​](#_1-快速脚本-linux) 此命令下载并运行我们的 install-hub.sh 脚本。该脚本将安装最新二进制文件并创建 systemd 服务，使其在重新启动后继续运行。 * `-u` : 卸载 * `-p ` : 指定端口号（默认: 8090） bash curl -sL https://raw.githubusercontent.com/henrygd/beszel/main/supplemental/scripts/install-hub.sh -o install-hub.sh && chmod +x install-hub.sh && ./install-hub.sh ### 2\. 手动下载和启动 [​](#_2-手动下载和启动) 点击展开/收起 #### 下载 [​](#下载) 从 [releases](https://github.com/henrygd/beszel/releases) 下载匹配您服务器 CPU 架构的最新二进制文件，并手动运行它。您需要手动创建一个服务才能使其在重新启动后继续运行。 bash curl -sL "https://github.com/henrygd/beszel/releases/latest/download/beszel_$(uname -s)_$(uname -m | sed -e 's/x86_64/amd64/' -e 's/armv6l/arm/' -e 's/armv7l/arm/' -e 's/aarch64/arm64/').tar.gz" | tar -xz -O beszel | tee ./beszel >/dev/null && chmod +x beszel #### 启动中心 [​](#启动中心) bash ./beszel serve --http "0.0.0.0:8090" #### 更新中心 [​](#更新中心) bash ./beszel update #### 创建服务（可选） [​](#创建服务-可选) 如果您的系统使用 systemd，则可以创建一个服务来使中心在重新启动后继续运行。 1. 在 `/etc/systemd/system/beszel.service` 中创建一个服务文件。如果用户对工作目录具有写入权限，则可以使用非 root 用户。 ini [Unit] Description=Beszel Hub After=network.target [Service] Type=simple Restart=always RestartSec=3 User=root WorkingDirectory={/path/to/working/directory} ExecStart={/path/to/working/directory}/beszel serve --http "0.0.0.0:8090" [Install] WantedBy=multi-user.target 2. 启用并启动服务。 bash sudo systemctl daemon-reload sudo systemctl enable beszel.service sudo systemctl start beszel.service ### 3\. 手动编译和启动 [​](#_3-手动编译和启动) 点击展开/收起 #### 编译 [​](#编译) 请参阅 [编译](./compiling) 了解有关如何自己编译中心的更多信息。 #### 启动中心 [​](#启动中心-1) bash ./beszel serve --http "0.0.0.0:8090" #### 更新中心 [​](#更新中心-1) bash ./beszel update #### 创建服务（可选） [​](#创建服务-可选-1) 如果您的系统使用 systemd，则可以创建一个服务来使中心在重新启动后继续运行。 1. 在 `/etc/systemd/system/beszel.service` 中创建一个服务文件。如果用户对工作目录具有写入权限，则可以使用非 root 用户。 ini [Unit] Description=Beszel Hub After=network.target [Service] Type=simple Restart=always RestartSec=5 User=root WorkingDirectory={/path/to/working/directory} ExecStart={/path/to/working/directory}/beszel serve --http "0.0.0.0:8090" [Install] WantedBy=multi-user.target 2. 启用并启动服务。 bash sudo systemctl daemon-reload sudo systemctl enable beszel.service sudo systemctl start beszel.service --- # 常见问题 | Beszel 回到顶部 常见问题 [​](#常见问题) ================ 代理程序未连接 [​](#代理程序未连接) ---------------------- 请查看 PocketBase 中的日志页面 (`/_/#/logs`) 以获取有关错误的信息。 最可能的原因是防火墙阻止了连接请求。在这种情况下，您有两个选择： 1. 在代理系统的防火墙中添加入站规则，以允许 TCP 连接到该端口。检查所有活动的防火墙，例如 iptables，以及您的云服务提供商的防火墙设置（如果适用）。 2. 或者，使用 WireGuard、Tailscale（[视频教程](https://www.youtube.com/watch?v=O_9wT-5LoHM) ）或 Cloudflare Tunnel（[教程](https://github.com/henrygd/beszel/discussions/250) ）等软件安全地绕过防火墙。 您可以通过在网络中的另一台设备上运行 `telnet <代理IP> <端口>` 来测试连接性。 在同一系统上使用 Docker 连接中心和代理 [​](#在同一系统上使用-docker-连接中心和代理) ------------------------------------------------------ 如果为代理程序使用主机网络模式，但不为中心使用，请使用主机名 `host.docker.internal` 添加您的系统，该主机名解析为主机使用的内部 IP 地址。有关完整的 `docker-compose.yml` 示例，请参阅 [入门](./getting-started) 指南。 如果都使用主机网络模式，则可以使用 `localhost` 作为主机名。 否则，如果两者都在同一个 Docker 网络中，请使用代理程序的 `container_name` 作为主机名。 查找正确的文件系统 [​](#查找正确的文件系统) -------------------------- 使用 `FILESYSTEM` 环境变量指定用于根磁盘统计的文件系统/设备/分区。 如果没有设置，代理程序将尝试找到挂载在 `/` 上的分区并使用它。这在容器中可能无法正常工作，因此建议设置此值。使用以下方法之一查找正确的文件系统： * 运行 `lsblk` 并选择 "NAME" 下的选项。 * 运行 `df -h` 并选择 "Filesystem" 下的选项。 * 运行 `sudo fdisk -l` 并选择 "Device" 下的选项。 Docker 容器图表为空或丢失 [​](#docker-容器图表为空或丢失) ---------------------------------------- 如果容器图表显示为空数据或根本不显示，您可能需要启用 cgroup 内存记帐。要进行验证，请运行 `docker stats`。如果显示内存使用率为零，请遵循以下指南解决问题： [https://akashrajpurohit.com/blog/resolving-missing-memory-stats-in-docker-stats-on-raspberry-pi/](https://akashrajpurohit.com/blog/resolving-missing-memory-stats-in-docker-stats-on-raspberry-pi/) Docker 容器填充不可靠 [​](#docker-容器填充不可靠) ------------------------------------ 如果可能，请升级代理程序系统上的 Docker 版本。Docker 24 及更早版本可能存在导致此问题的错误。我们已经向代理程序添加了缓解此问题的解决方法，但这不是完美的解决方案。 月/周记录填充不可靠 [​](#月-周记录填充不可靠) ---------------------------- 较长时间段的记录是通过平均较短时期的统计数据创建的。代理程序必须不间断运行才能使这些记录填充完整的数据集。 暂停/取消暂停代理程序超过一分钟将导致数据不完整，重置当前间隔的计时。 --- # REST API | Beszel 回到顶部 REST API [​](#rest-api) ======================== 由于 Beszel 基于 PocketBase 构建，您可以使用 PocketBase [Web API](https://pocketbase.io/docs/api-records/) 和 [客户端 SDK](https://pocketbase.io/docs/client-side-sdks/) 来读取或更新 Beszel 自身之外的数据。 基本示例 [​](#基本示例) ---------------- 此示例使用 [PocketBase JS SDK](https://github.com/pocketbase/js-sdk) 从 `systems` 集合中读取数据。 typescript import PocketBase from 'pocketbase' const pb = new PocketBase('http://localhost:8090') // 作为普通用户进行身份验证 const userData = await pb.collection('users').authWithPassword('[email protected]', '123456') // 列出并过滤系统记录 const systems = await pb.collection('systems').getList(1, 20, { filter: 'status = "up" && created > "2024-06-01 10:00:00"', }) console.log(systems) 将用户添加到系统 [​](#将用户添加到系统) ------------------------ 此示例将特定用户添加到特定系统。 ts import PocketBase from 'pocketbase' const pb = new PocketBase('http://localhost:8090') // 我们将添加到系统的用户 const userEmails = ['[email protected]', '[email protected]'] // 我们将向其添加用户的系统名称 const systemNames = ['localhost', 'kagemusha'] // 作为管理员进行身份验证 await pb.admins.authWithPassword(process.env.EMAIL, process.env.PASSWORD) // 获取用户 ID const userIds = await pb .collection('users') .getFullList({ fields: 'id', filter: `email='${userEmails.join(`'||email='`)}'`, }) .then((records) => records.map(({ id }) => id)) // 获取系统 ID 和当前用户 const systemsData = await pb.collection('systems').getFullList({ fields: 'id,users', filter: `name='${systemNames.join(`'||name='`)}'`, }) // 循环遍历系统并将用户添加到其中 for (const system of systemsData) { const updatedUsers = Array.from(new Set([...system.users, ...userIds])) await pb.collection('systems').update(system.id, { users: updatedUsers }) } --- # 代理安装 | Beszel 回到顶部 代理安装 [​](#代理安装) ================ Beszel 代理支持通过 Docker / Podman 容器、单一二进制文件或 Home Assistant 插件进行安装。 提示 如果您是首次设置 Beszel，请查看 [开始使用](./getting-started) 指南。 要求 [​](#要求) ------------ 如果代理和中心 (hub) 位于不同的主机上，您可能需要在代理系统的防火墙上更新配置，以允许代理端口上的传入 TCP 连接。 或者，您可以使用 Wireguard 或 Cloudflare Tunnel 等软件（[说明](https://github.com/henrygd/beszel/discussions/250) ）安全地绕过防火墙。 使用中心 (Hub) [​](#使用中心-hub) -------------------------- 在添加新系统时，中心 (hub) 的 Web UI 中提供了可供复制/粘贴的 `docker-compose.yml` 或二进制安装命令。 [![添加系统对话框](/image/add-system-2.png)](/image/add-system-2.png) Docker 或 Podman [​](#docker-或-podman) -------------------------------------- 提示 在添加新系统时，可以从中心 (hub) 的 Web UI 复制预配置的 `docker-compose.yml` 内容，因此在大多数情况下，您不需要手动进行设置。 docker-compose.ymldocker runpodman run yaml services: beszel-agent: image: henrygd/beszel-agent container_name: beszel-agent restart: unless-stopped network_mode: host volumes: - /var/run/docker.sock:/var/run/docker.sock:ro # 通过在 /extra-filesystems 中挂载文件夹来监控其他磁盘/分区 # - /mnt/disk1/.beszel:/extra-filesystems/disk1:ro environment: PORT: 45876 KEY: '<公钥>' bash docker run -d \ --name beszel-agent \ --network host \ --restart unless-stopped \ -v /var/run/docker.sock:/var/run/docker.sock:ro \ -e KEY="<公钥>" \ -e PORT=45876 \ henrygd/beszel-agent:latest bash podman run -d \ --name beszel-agent \ --network host \ --restart unless-stopped \ -v /var/run/docker.sock:/var/run/docker.sock:ro \ -e KEY="<公钥>" \ -e PORT=45876 \ docker.io/henrygd/beszel-agent:latest ### 为什么要使用主机网络模式？ [​](#为什么要使用主机网络模式) 代理必须使用主机网络模式才能访问网络接口指标，这将自动暴露端口。如果需要，可以使用环境变量更改端口。 如果您不需要网络统计信息，可以从 compose 文件中删除该行并手动映射端口。 二进制文件 [​](#二进制文件) ------------------ 安装二进制文件有多种方法。请选择您喜欢的方式。 ### 1\. 快速脚本 (Linux) [​](#_1-快速脚本-linux) 提示 在添加新系统时，可以从中心 (hub) 的 Web UI 复制预配置的命令，因此在大多数情况下，您不需要手动运行此命令。 此命令下载并运行我们的 `install-agent.sh` 脚本。 该脚本将安装最新的二进制文件并创建一个 systemd 服务，以使其在重新启动后继续运行。您可以选择启用自动每日更新。 * `-p`：端口（默认：45876） * `-k`：公钥（用引号括起来；如果未提供则进入交互模式） * `-u`：卸载 * `--china-mirrors`：使用 GitHub 镜像以解决中国大陆的网络问题 bash curl -sL https://raw.githubusercontent.com/henrygd/beszel/main/supplemental/scripts/install-agent.sh -o install-agent.sh && chmod +x install-agent.sh && ./install-agent.sh ### 2\. 手动下载和启动 [​](#_2-手动下载和启动) 点击展开/收起 #### 下载二进制文件 [​](#下载二进制文件) 从 [releases](https://github.com/henrygd/beszel/releases) 下载与您的服务器操作系统/架构匹配的最新二进制文件。 bash curl -sL "https://github.com/henrygd/beszel/releases/latest/download/beszel-agent_$(uname -s)_$(uname -m | sed -e 's/x86_64/amd64/' -e 's/armv6l/arm/' -e 's/armv7l/arm/' -e 's/aarch64/arm64/').tar.gz" | tar -xz -O beszel-agent | tee ./beszel-agent >/dev/null && chmod +x beszel-agent #### 启动代理 [​](#启动代理) * `PORT` : 端口 * `KEY` : 公钥（用引号括起来） bash PORT=45876 KEY="<公钥>" ./beszel-agent #### 更新代理 [​](#更新代理) bash ./beszel-agent update #### 创建服务（可选） [​](#创建服务-可选) 如果您的系统使用 systemd，您可以创建一个服务以使中心在重新启动后继续运行。 1. 在 `/etc/systemd/system/beszel-agent.service` 中创建一个服务文件。 ini [Unit] Description=Beszel Agent Service After=network.target [Service] Environment="PORT=$PORT" Environment="KEY=$KEY" # Environment="EXTRA_FILESYSTEMS=sdb" Restart=always RestartSec=5 ExecStart={/path/to/working/directory}/beszel-agent [Install] WantedBy=multi-user.target 2. 启用并启动服务。 bash sudo systemctl daemon-reload sudo systemctl enable beszel-agent.service sudo systemctl start beszel-agent.service ### 3\. 手动编译和启动 [​](#_3-手动编译和启动) 点击展开/收起 #### 编译 [​](#编译) 请参阅 [编译](./compiling) 了解有关如何自己编译中心的更多信息。 #### 启动代理 [​](#启动代理-1) * `PORT` : 端口 * `KEY` : 公钥（用引号括起来） bash PORT=45876 KEY="<公钥>" ./beszel-agent #### 更新代理 [​](#更新代理-1) bash ./beszel-agent update #### 创建服务（可选） [​](#创建服务-可选-1) 如果您的系统使用 systemd，您可以创建一个服务以使中心在重新启动后继续运行。 1. 在 `/etc/systemd/system/beszel-agent.service` 中创建一个服务文件。 ini [Unit] Description=Beszel Agent Service After=network.target [Service] Environment="PORT=$PORT" Environment="KEY=$KEY" # Environment="EXTRA_FILESYSTEMS=sdb" Restart=always RestartSec=5 ExecStart={/path/to/working/directory}/beszel-agent [Install] WantedBy=multi-user.target 2. 启用并启动服务。 bash sudo systemctl daemon-reload sudo systemctl enable beszel-agent.service sudo systemctl start beszel-agent.service Home Assistant [​](#home-assistant) ------------------------------------ 请参阅 [Home Assistant 代理页面](./home-assistant) 获取将代理设置为 Home Assistant 插件的说明。 --- # Docker Shell | Beszel 回到顶部 Docker Shell [​](#docker-shell) ================================ Beszel 使用了一个没有 Shell 的 [scratch 镜像](https://hub.docker.com/_/scratch) 。这意味着您无法使用 `docker exec -it <容器> /bin/sh` 从容器内部进行调试。 不过，您可以使用 `build` 选项配合自定义的 Dockerfile，将二进制文件移动到您选择的基础镜像中。 创建 Dockerfile [​](#创建-dockerfile) ---------------------------------- 将以下内容保存为 `Dockerfile`，并放在与 `docker-compose.yml` 相同的目录中： HubAgent dockerfile FROM henrygd/beszel:latest as beszel # 定义新的基础镜像 FROM alpine:latest # 添加工具（curl、telnet、traceroute、netstat、host、nslookup、dig、delv） RUN apk add --no-cache bash curl busybox-extras bind-tools # 将二进制文件复制到新镜像中 COPY --from=beszel /beszel /beszel ENTRYPOINT [ "/beszel" ] CMD ["serve", "--http=0.0.0.0:8090"] dockerfile FROM henrygd/beszel-agent:latest as beszel # 定义新的基础镜像 FROM alpine:latest # 添加工具（curl、telnet、traceroute、netstat、host、nslookup、dig、delv） RUN apk add --no-cache bash curl busybox-extras bind-tools # 将二进制文件复制到新镜像中 COPY --from=beszel /agent /agent ENTRYPOINT ["/agent"] 更新您的 `docker-compose.yml` [​](#更新您的-docker-compose-yml) -------------------------------------------------------- 移除 `image` 键，并在服务中添加 `build` 键： HubAgent yaml beszel: image: henrygd/beszel build: . yaml beszel-agent: image: henrygd/beszel-agent build: . 重启容器并访问 Shell [​](#重启容器并访问-shell) ---------------------------------- bash docker-compose up -d --build docker exec -it <容器> bash 在一个 compose 文件中使用多个 Dockerfile [​](#在一个-compose-文件中使用多个-dockerfile) -------------------------------------------------------------------- 如果您的 Hub 和 Agent 共享同一个 compose 文件，并且您希望调试两者，可以使用此方法。 将 Dockerfile 保存为不同的名称，例如 `Dockerfile_hub` 和 `Dockerfile_agent`，并更新 `docker-compose.yml` 中的 `build` 键： yaml beszel: build: context: . dockerfile: Dockerfile_hub beszel-agent: build: context: . dockerfile: Dockerfile_agent --- # Email Protection | Cloudflare Please enable cookies. Email Protection ================ You are unable to access this email address beszel.dev ------------------------------------------------------ The website from which you got to this page is protected by Cloudflare. Email addresses on that page have been hidden in order to keep them from being accessed by malicious bots. **You must enable Javascript in your browser in order to decode the e-mail address**. If you have a website and are interested in protecting it in a similar way, you can [sign up for Cloudflare](https://www.cloudflare.com/sign-up?utm_source=email_protection) . * [How does Cloudflare protect email addresses on website from spammers?](https://support.cloudflare.com/hc/en-us/articles/200170016-What-is-Email-Address-Obfuscation-) * [Can I sign up for Cloudflare?](https://support.cloudflare.com/hc/en-us/categories/200275218-Getting-Started) Cloudflare Ray ID: **90548522d89d3b77** • Your IP: Click to reveal 54.237.218.47 • Performance & security by [Cloudflare](https://www.cloudflare.com/5xx-error-landing) --- # 安全 | Beszel 回到顶部 安全 [​](#安全) ============ 中心和代理程序通过 SSH 进行通信，因此它们不需要暴露于互联网。即使您在中心前面放置外部身份验证网关（例如 Authelia），也不会破坏或中断中心和代理程序之间的连接。 当中心首次启动时，它会生成一个 ED25519 密钥对。 代理程序的 SSH 服务器仅配置为使用此密钥接受连接。它不提供伪终端或接受输入，因此即使您的私钥泄露，也无法在代理程序上执行命令。 报告漏洞 [​](#报告漏洞) ---------------- 如果您发现最新版本存在严重的安全漏洞，请 [提交漏洞报告](https://github.com/henrygd/beszel/security/advisories/new) 。 如果漏洞严重性较低（请自行判断），您可以提交一个 issue。 网络需求 [​](#网络需求) ---------------- 以下是 Beszel 基于默认配置与之通信的端口和远程主机列表。使用 SMTP 发送邮件或使用 S3 进行备份将需要连接到其他主机。 ### 代理程序 [​](#代理程序) #### 入站 [​](#入站) | 端口 | 用途 | | --- | --- | | 45876 | 允许中心通过 SSH 连接到代理程序 | #### 出站 [​](#出站) | 远程主机 | 端口 | 用途 | | --- | --- | --- | | github.com | 443 | 检查/下载更新（如果使用 Docker 则不需要） | ### 中心 [​](#中心) #### 入站 [​](#入站-1) | 端口 | 用途 | | --- | --- | | 8090 | HTTP 访问 Web UI | #### 出站 [​](#出站-1) | 远程主机 | 端口 | 用途 | | --- | --- | --- | | agents | 45876 | 与您的代理程序的 SSH 连接 | | github.com | 443 | 检查/下载更新（如果使用 Docker 则不需要） | --- # 开发者指南 | Beszel 回到顶部 开发者指南 [​](#开发者指南) ================== 感谢您对 Beszel 开发的兴趣！ 我们欢迎您的贡献，如果您计划进行任何重大更改，最好先在讨论或问题中与我们联系。 先决条件 [​](#先决条件) ---------------- * Go 1.23+（用于修改 Go 代码） * Bun 1.1.38+ 或 Node 18+（用于修改 Web 用户界面） 如果您还没有，请 [fork 仓库](https://github.com/henrygd/beszel/fork) 并克隆您的 fork 到本地工作： bash git clone https://github.com/your_username/beszel.git 为不同的更改创建单独的分支 建议为每个错误修复和功能创建一个新的分支。 如果您计划提交多个 PR 以便在最终合并之前单独进行审查，则这是必需的。 开发环境 [​](#开发环境) ---------------- 为了进行项目开发，需要启动三个进程： 1. 中心 (Go) 2. 代理程序 (Go) 3. Web UI (TypeScript / Vite) 每个作业都有一个 `make` 命令启动（在 `/beszel` 目录中运行）。 bash # 启动中心 make dev-hub # 启动代理程序 KEY="..." make dev-agent # 启动 Web UI make dev-server 或者，您可以一次启动所有进程并结合输出： bash KEY="..." make -j dev 导航到 [http://localhost:8090](http://localhost:8090) 查看 Web UI。 提示 如果安装了 [`entr`](https://github.com/eradman/entr) ，则当您保存代码更改时，中心/代理程序会自动重建。 --- # 多语言和本地化 | Beszel 回到顶部 多语言和本地化 [​](#多语言和本地化) ====================== 感谢您对 Beszel 做出贡献的兴趣！ 软件 [​](#软件) ------------ [![Crowdin](https://badges.crowdin.net/beszel/localized.svg)](https://crowdin.com/project/beszel) 欢迎您帮助改进 Beszel 的翻译：[crowdin/beszel](https://crowdin.com/project/beszel) 如果您想要添加一种新的语言，请在 Crowdin 上 [发布讨论](https://crowdin.com/project/beszel/discussions) 或打开一个 issue 在 GitHub 上。 我并不总是会收到使用 Crowdin 原生功能请求添加语言的通知。 文档 [​](#文档) ------------ 此文档的仓库位于 [https://github.com/henrygd/beszel-docs](https://github.com/henrygd/beszel-docs) 如果您想要贡献，请克隆仓库并提交一个 pull request。 参考 `zh` 目录了解中文翻译。 如果您想要添加一种新的语言，请创建一个新的目录并使用语言代码命名 (例如 `es`、`fr` 等)。 --- # Home Assistant 代理 | Beszel 回到顶部 Home Assistant 代理 [​](#home-assistant-代理) ========================================== Home Assistant 插件由第三方维护。目前有两个选项： * `Obamium69/hassio-beszel_agent` ([GitHub](https://github.com/Obamium69/hassio-beszel_agent) ) * `matthewhadley/homeassistant-beszel-agent` ([GitHub](https://github.com/matthewhadley/homeassistant-beszel-agent) ) 将仓库添加到 Home Assistant [​](#将仓库添加到-home-assistant) -------------------------------------------------- 1. 登录到您的 Home Assistant 实例，然后转到“插件”。 [![Home Assistant 中的代理插件可见](/image/hass/open-addons.png)](/image/hass/open-addons.png) 2. 点击“插件商店”，打开右上角的三点菜单，然后选择“仓库”。 [![Home Assistant 中的代理插件可见](/image/hass/open-addonsstore.png)](/image/hass/open-addonsstore.png) [![Home Assistant 中的代理插件可见](/image/hass/add-repo.png)](/image/hass/add-repo.png) 3. 添加以下仓库之一： * `https://github.com/Obamium69/hassio-beszel_agent` * `https://github.com/matthewhadley/homeassistant-beszel-agent` 配置插件 [​](#配置插件) ---------------- 1. 插件现在应该出现在插件商店中。只需点击它，然后按下“安装”。 [![Home Assistant 中的代理插件可见](/image/hass/homeassistant-addon.png)](/image/hass/homeassistant-addon.png) 2. 插件现已安装。返回已安装插件的概览，打开代理插件，然后切换到“配置”选项卡。 3. 按照[这些](./getting-started#_3-configure-your-first-system) 说明配置代理，然后复制公钥。 4. 返回 Home Assistant，将公钥粘贴到输入字段中，然后按下“保存”。 5. 启动插件。 ---