快速安装

部署 ServerBee 推荐用 deploy/install.sh 一键脚本。架构检测、二进制下载、服务注册这些繁琐步骤它都替你做好了，开箱即用：

交互式向导：不带参数运行就进入向导，按提示选语言、组件和安装方式
架构自适应：自动识别 amd64/arm64，下载匹配的 Release 二进制
服务管理集成：自动创建并拉起 systemd 或 OpenRC 服务，配好开机自启
二进制 / Docker 双模式：用 --method 切换；Server 推荐 Docker，Agent 推荐二进制
HTTPS 自动配置：装 Server 时传 --domain，脚本会自动装好 Caddy 并签发证书
统一管理 CLI：装完会生成 serverbee 命令，升级、重启、改配置、卸载全用它

下面分别从 Server（服务端） 和 Client（被监控节点 / Agent） 两个视角介绍部署流程。

本站跟随仓库 main 分支，已发布版本可能落后于页面。默认 auto 通道会在稳定版存在时选择最新稳定版，否则回退到最新预发布版；升级会复用安装时保存的策略。只有在明确固定发布轨道时才使用 --channel stable 或 --channel beta。需要可重复部署时，用 --version vX.Y.Z 固定版本，并先核对该 Release 的 changelog 再使用新文档功能。

先选择部署方式

方式	适合场景	持久化与运维方式
二进制（非交互默认值）	小型 VPS、最短上手路径	文件位于 `/opt/serverbee`；systemd 或 OpenRC 管服务；`serverbee upgrade` 升级
Docker（已有 Docker 运维体系时推荐）	需要容器隔离、镜像式升级	named volume 存数据；Compose 管容器；配置和 volume 都要备份
Railway	希望托管公网 HTTPS	必须挂载 `/data` volume；从 Railway 日志取首次凭据

下方命令显式使用 --method binary，确保文件、日志和服务命令一致。需要 Docker 生命周期时改为 --method docker。

前置条件

Linux 主机（amd64 / arm64），需以 root 运行（脚本会校验，非 root 直接报错）。普通用户用 sudo；已经是 root（如直接以 root 登录或在容器内）可省略命令里的 sudo
二进制方式需要 systemd 或 OpenRC；Docker 方式需要 Docker 20.10+ 与 Compose V2
IP 直连 / HTTP：放行入站 TCP 9527
域名 / HTTPS：让 A/AAAA 记录指向本机，放行入站 TCP 80、443，并确认这两个端口没有被非 Caddy 服务占用。不要把 9527 暴露到公网，Caddy 会连接其回环地址

Server 视角

Server 是中心节点：接收 Agent 上报的指标、落库存储，并提供 Web 管理面板。

第一步：安装 Server

Server 有两种快速安装方式，按你是否有域名选一种即可。

方式一：用 IP 安装（明文 HTTP）

最快上手，没有域名时用这种。装完通过 http://<服务器IP>:9527 访问：

curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/deploy/install.sh | sudo sh -s -- server --method binary -y

脚本会写入 auth.secure_cookie = false，让浏览器在普通 HTTP 下也能登录。该方式不会加密浏览器、Agent、终端、文件或命令流量，只应用于可信网络或初次评估；生产环境优先使用 HTTPS。

方式二：用域名安装（自动 HTTPS）

如果你已有域名，且 DNS A 记录已指向这台服务器，加上 --domain 即可让脚本自动装好 Caddy 并签发 HTTPS 证书，装完通过 https://你的域名 访问：

curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/deploy/install.sh | sudo sh -s -- server \
  --method binary \
  --domain monitor.example.com \
  --email admin@example.com \
  -y

脚本会先校验域名是否解析到这台服务器；没解析或指向了别的 IP，安装会中止并提示你该加哪条 DNS 记录。--email 用于 Let's Encrypt 证书通知，可以省略。已经装好的 Server 想补配域名，单独执行 sudo serverbee domain setup --domain monitor.example.com --email admin@example.com 即可。

也可以不带参数运行进入交互式向导，按提示选语言、二进制还是 Docker、是否配域名：curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/deploy/install.sh | sudo sh。

对于上方二进制方式，脚本会检测架构、下载并校验 Release、创建 /opt/serverbee/{bin,etc,data}、注册 systemd 或 OpenRC 服务，并把管理 CLI 安装到 /usr/local/bin/serverbee。Docker 方式则在 /opt/serverbee 生成 Compose 与配置文件，并把数据持久化到 named volume。

有 Docker 的环境推荐用 Docker 方式跑 Server，升级和隔离都更省心。加上 --method docker 即可：... | sudo sh -s -- server --method docker -y。

第二步：拿到首次管理员密码

Server 首次启动会自动创建管理员账号并随机生成密码，这串密码只在日志里打印一次：

sudo journalctl -u serverbee-server --no-pager | grep -A8 'FIRST-RUN ADMIN CREDENTIALS' | tail -n 9

Docker 方式请显式读取最后一段完整凭据：

docker logs serverbee-server 2>&1 | grep -A8 'FIRST-RUN ADMIN CREDENTIALS' | tail -n 9

这串密码只显示一次，记得在日志轮转前复制下来。首次登录会强制改密码，请在公网暴露前完成。

第三步：首次登录

打开浏览器访问 http://<服务器IP>:9527（域名方式则是 https://你的域名）
用默认账户 admin 和日志里的随机密码登录
按页面提示完成强制改密，也可以顺便换一个新用户名

如果先用 IP 明文 HTTP 装好，之后想切到域名 HTTPS：执行 sudo serverbee domain setup --domain monitor.example.com --email admin@example.com 补配，并把 /opt/serverbee/etc/server.toml 里的 auth.secure_cookie 改回 true 重启 Server，同时把已接入 Agent 的 server_url 换成新的 https:// 地址。

管理 Server

装好后用 serverbee 命令管理实例：

sudo serverbee status                     # 查看所有组件状态
sudo serverbee upgrade -y                  # 升级到最新版
sudo serverbee restart                     # 重启服务
sudo serverbee config                      # 查看当前配置
sudo serverbee config set <key> <value>    # 修改配置
sudo serverbee uninstall server --purge    # 卸载服务端并清除数据

uninstall --purge 会永久删除 Server 数据库、配置和受管 Docker 卷。请先创建并验证备份；希望保留数据以便恢复或重装时，不要使用 --purge。

Client（Agent）视角

Agent 是跑在被监控机器上的轻量探针，负责把 CPU、内存、磁盘、网络等指标上报给 Server。

第一步：添加 Server 并获取 enrollment offer

以管理员身份登录管理面板，进入「Servers（服务器）」页面，点击「Add Server（添加服务器）」并提交机器配置。ServerBee 会原子地创建待接入 Server 及其绑定的 enrollment offer，然后显示一次性 code 和安装命令。

注册码只能用一次，而且很快过期（默认 10 分钟），只在 Agent 首次注册时用得到。每接入一台新 Agent，就重新生成一个。

第二步：安装并启动 Agent

在被监控的机器上执行安装脚本，把 Server 地址和注册码作为参数传进去：

curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/deploy/install.sh | sudo sh -s -- agent \
  --server-url http://your-server-ip:9527 \
  --enrollment-code YOUR_ONE_TIME_CODE

脚本会自动识别架构、下载二进制、写入配置、注册 systemd 服务并拉起 Agent。

Agent 推荐用二进制方式安装，这样才能采集到宿主机的完整指标；不建议用 Docker 跑 Agent。

Agent 首次启动时会在 claim offer 前自行生成并持久化 run token。Server 只保存其哈希并返回已有 server_id；之后启动都用这份持久化 token，不再需要注册码。如果 token 丢失，在该 Server 详情页发起 graceful 或 emergency 重新接入。

第三步：验证连接

回到面板的仪表盘，几秒内就能看到新服务器上线、实时指标开始刷新。也可以在 Agent 这台机器上验证：

sudo serverbee status
sudo journalctl -u serverbee-agent -n 80 --no-pager

管理 Agent

sudo serverbee status               # 查看 Agent 状态
sudo serverbee upgrade -y            # 升级 Agent
sudo serverbee restart               # 重启 Agent
sudo serverbee uninstall agent       # 卸载 Agent

更多采集、日志等可调项见 Agent 配置和完整配置参考。

用 IP 访问还是域名访问

ServerBee 既能直接用服务器 IP 访问，也能走域名 + 反向代理。具体要额外配什么，取决于浏览器最终走的是 HTTP 还是 HTTPS。

访问方式	浏览器地址	Server Cookie 配置	Agent `server_url`	额外配置
IP 直连，普通 HTTP	`http://your-server-ip:9527`	`auth.secure_cookie = false` 或 `SERVERBEE_AUTH__SECURE_COOKIE=false`	`http://your-server-ip:9527`	防火墙放行 `9527` 端口
域名 + HTTPS	`https://monitor.example.com`	`auth.secure_cookie = true` 或 `SERVERBEE_AUTH__SECURE_COOKIE=true`	`https://monitor.example.com`	DNS 指向服务器 IP；放行 80/443；保持 9527 非公网；脚本会自动配好 Caddy（也可自行配 Nginx、Traefik）

备选：用 Docker Compose 手动部署 Server

如果你更习惯自己用 Compose 文件管理 Server，新建一个 docker-compose.yml：

docker-compose.yml

services:
  serverbee-server:
    image: ghcr.io/zingerlittlebee/serverbee-server:1.0.0-beta.4
    container_name: serverbee-server
    ports:
      - "9527:9527"
    volumes:
      - serverbee-data:/data
    environment:
      - SERVERBEE_AUTH__SECURE_COOKIE=false
    restart: unless-stopped

volumes:
  serverbee-data:

启动并查看首次管理员密码：

docker compose up -d
docker compose logs serverbee-server

上面示例关掉了 Cookie 的 Secure 标记，因为这里走的是普通 HTTP；切到 HTTPS 后记得设回 SERVERBEE_AUTH__SECURE_COOKIE=true。Agent 仍建议用 install.sh agent 二进制方式接入。