# 快速安装

> 用一键安装脚本在几分钟内装好 ServerBee 的 Server 与 Agent。

URL: https://docs.serverbee.app/zh/docs/quick-start

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

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

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

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

## 先选择部署方式 [#先选择部署方式]

| 方式                        | 适合场景          | 持久化与运维方式                                                          |
| ------------------------- | ------------- | ----------------------------------------------------------------- |
| 二进制（非交互默认值）               | 小型 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-视角]

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

### 第一步：安装 Server [#第一步安装-server]

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

#### 方式一：用 IP 安装（明文 HTTP） [#方式一用-ip-安装明文-http]

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

```bash
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） [#方式二用域名安装自动-https]

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

```bash
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` 即可。

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

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

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

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

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

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

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

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

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

### 第三步：首次登录 [#第三步首次登录]

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

<Callout type="warn">
  如果先用 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://` 地址。
</Callout>

### 管理 Server [#管理-server]

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

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

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

***

## Client（Agent）视角 [#clientagent视角]

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

### 第一步：添加 Server 并获取 enrollment offer [#第一步添加-server-并获取-enrollment-offer]

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

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

### 第二步：安装并启动 Agent [#第二步安装并启动-agent]

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

```bash
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。

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

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

### 第三步：验证连接 [#第三步验证连接]

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

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

### 管理 Agent [#管理-agent]

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

更多采集、日志等可调项见 [Agent 配置](/zh/docs/agent)和[完整配置参考](/zh/docs/configuration)。

***

## 用 IP 访问还是域名访问 [#用-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 [#备选用-docker-compose-手动部署-server]

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

```yaml title="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:
```

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

```bash
docker compose up -d
docker compose logs serverbee-server
```

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

<Cards>
  <Card title="Server 安装配置" href="/zh/docs/server" />

  <Card title="Agent 安装配置" href="/zh/docs/agent" />

  <Card title="配置告警" href="/zh/docs/alerts" />

  <Card title="Web 终端" href="/zh/docs/terminal" />

  <Card title="故障排查" href="/zh/docs/troubleshooting" />
</Cards>