文档首页

宝塔一键安装

1. 准备宝塔 Linux 服务器

准备运行 Nginx 的宝塔 Linux 面板，并安装 Docker Engine、Compose V2 插件和 OpenSSL。准备一个指向此服务器的域名，例如 vm.example.com。请将整个项目上传到 /opt/vm-bandwidth 等站点根目录以外的位置。部署时服务器需要能拉取 Node 容器镜像。

Docker Compose 插件安装说明

2. 一条命令安装平台

打开宝塔终端，以可操作 Docker 的管理员账户执行。按实际上传位置修改路径。

cd /opt/vm-bandwidth && bash install.sh

脚本生成随机管理员令牌，构建并启动服务，等待容器通过健康检查。已有的 .env 和数据库卷会继续使用。服务监听 127.0.0.1:18765，数据库放在 Docker 命名卷内。

curl --fail http://127.0.0.1:18765/healthz
docker compose ps

3. 在宝塔添加 HTTPS 反向代理

  1. 在「网站」添加域名站点。为此站点申请或导入 SSL 证书，并开启强制 HTTPS。
  2. 在站点设置中添加反向代理，代理目录为 /，目标 URL 为 http://127.0.0.1:18765/。关闭代理缓存，保留请求的 Authorization 头。如果站点配置限制请求体大小，按宿主机规模将其调到至少 2m。
  3. 访问 https://vm.example.com/healthz，应返回 {"ok":true}。然后访问站点首页，用安装目录 .env 中 ADMIN_TOKEN= 后面的值完成一次性初始化，设置一级管理员用户名和密码。之后使用账号密码登录。
  4. 点击「添加宿主机」，为每台宿主机分别生成令牌，然后按 Agent 接入教程配置。

初始化令牌用于创建首个管理员，保存在安装目录的 .env 中。建议将站点开放给管理网或 VPN。Agent 访问 HTTPS 域名时需要信任站点的证书。宝塔公开入口使用 443，平台内部端口无需在防火墙放行。

宝塔官方反向代理教程

4. 更新、备份与排查

更新前在安装目录运行以下命令。第一条命令短暂停止平台，使 SQLite 文件和 WAL 文件可一起一致备份。备份应与 .env 分开妥善保存。

docker compose stop platform
docker compose cp platform:/app/data ./bandwidth-backup
docker compose start platform

覆盖项目代码时保留 .env，再执行 bash install.sh。从旧版令牌登录升级后，首次进入首页会提示创建一级管理员，宿主机注册和已有策略仍从原数据库读取。日常停止可用 docker compose stop。docker compose down -v 会删除数据库卷。账号密码管理见 管理员与监控大屏。

浏览器出现 502 时检查本机健康接口与宝塔代理地址。Agent 无法接入时先核对 HTTPS 证书、独立令牌和代理是否透传认证头。

docker compose logs --tail 100 platform