Server 安装配置
ServerBee 服务端的安装、配置和运维指南。
Server 是 ServerBee 的核心组件,负责接收 Agent 上报的数据、存储历史指标、评估告警规则、提供 Web 管理面板和 API 接口。
安装方式
安装脚本(推荐)
最省事的方式是一键安装脚本。二进制模式会自动检测架构、下载二进制、生成配置、注册并启动 systemd 或 OpenRC 服务,并软链 serverbee 管理 CLI。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
# 方式二:用域名安装(自动 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脚本安装后的目录布局:二进制在 /opt/serverbee/bin/,配置在 /opt/serverbee/etc/server.toml,数据在 /opt/serverbee/data/,管理 CLI 软链为 /usr/local/bin/serverbee。完整步骤见快速安装。
二进制安装(手动)
从 GitHub Releases 下载对应平台的预编译二进制并自行运行:
chmod +x serverbee-server
./serverbee-serverDocker
docker run -d \
--name serverbee-server \
-p 9527:9527 \
-v serverbee-data:/data \
-e MALLOC_ARENA_MAX=2 \
ghcr.io/zingerlittlebee/serverbee-server:1.0.0-beta.4源码编译
# 先构建前端(会嵌入到 Server 二进制中)
cd apps/web && bun install && bun run build && cd ../..
# 构建 Server
cargo build --release -p serverbee-server配置文件
Server 按以下顺序读取 TOML 配置,靠后的来源会覆盖靠前的:
/etc/serverbee/server.toml(系统级)server.toml(工作目录)- 以
SERVERBEE_为前缀的环境变量
通过安装脚本部署时,配置文件位于 /opt/serverbee/etc/server.toml,数据目录为 /opt/serverbee/data/(脚本会显式写入这些路径,覆盖下方的内置默认值)。/etc/serverbee、/var/lib/serverbee 是旧版布局,仅在历史安装中出现,脚本会自动迁移。
下面的 server.toml 列出最常用的配置项及其默认值。完整选项见配置参考。
[server]
listen = "0.0.0.0:9527" # 监听地址和端口
data_dir = "./data" # 数据库及其他数据文件的存储目录
trusted_proxies = [] # 默认为内网/回环 CIDR;设为 [] 表示禁用
[database]
path = "serverbee.db" # 数据库文件名(相对于 data_dir)
max_connections = 10 # SQLite 连接池最大连接数
[auth]
session_ttl = 86400 # Session 过期时间,单位秒(默认 24 小时)
max_servers = 0 # 新接入服务器的软上限(0 表示不限制)
secure_cookie = true # 是否给 Session Cookie 设置 Secure 标记(纯 HTTP 本地调试需关闭)
[retention]
records_days = 7 # 分钟级指标保留天数
records_hourly_days = 90 # 小时级聚合指标保留天数
gpu_records_days = 7 # GPU 指标保留天数
ping_records_days = 7 # Ping 探测记录保留天数
audit_logs_days = 180 # 审计日志保留天数
network_probe_days = 7 # 网络探测记录保留天数
network_probe_hourly_days = 90 # 小时级网络探测聚合保留天数
traffic_hourly_days = 7 # 流量小时记录保留天数
traffic_daily_days = 400 # 流量日记录保留天数
task_results_days = 7 # 任务执行结果保留天数
docker_events_days = 7 # Docker 事件记录保留天数
service_monitor_days = 30 # 服务监控记录保留天数
[rate_limit]
login_max = 5 # 每个时间窗口内最大登录尝试次数
register_max = 10 # 每个窗口内最大 Agent 注册尝试次数(Railway 覆盖为 3)
[scheduler]
timezone = "UTC" # 每日流量聚合所用时区(如 Asia/Shanghai)
[log]
level = "info" # 日志级别:trace / debug / info / warn / error
file = "" # 日志文件路径(留空仅输出到 stdout)
[upgrade]
release_base_url = "https://github.com/ZingerLittleBee/ServerBee/releases" # Agent 升级的基础 URL
[geoip]
mmdb_path = "" # MaxMind GeoLite2-City.mmdb 路径(非空即启用 GeoIP)
[oauth]
base_url = "" # ServerBee 实例的公网 URL
allow_registration = false # 是否允许首次 OAuth 登录时自动创建用户
[oauth.github]
client_id = ""
client_secret = ""
[oauth.google]
client_id = ""
client_secret = ""
[oauth.oidc]
issuer_url = ""
client_id = ""
client_secret = ""
scopes = ["openid", "email", "profile"]环境变量
每个配置项都可以通过环境变量设置:前缀 SERVERBEE_,层级用 __(双下划线)分隔。环境变量的优先级高于配置文件。
# server.listen
export SERVERBEE_SERVER__LISTEN="0.0.0.0:9527"
# retention.records_days
export SERVERBEE_RETENTION__RECORDS_DAYS=14
# oauth.github.client_id
export SERVERBEE_OAUTH__GITHUB__CLIENT_ID="your-github-client-id"
# geoip.mmdb_path(路径非空即启用 GeoIP)
export SERVERBEE_GEOIP__MMDB_PATH="/path/to/GeoLite2-City.mmdb"数据库
ServerBee 使用 SQLite 存储所有持久化数据。首次启动时会自动在 data_dir 下创建数据库文件。
以下 SQLite pragma 会自动设置:
| Pragma | 取值 | 作用 |
|---|---|---|
journal_mode | WAL | 提高并发读性能 |
synchronous | NORMAL | 兼顾安全性与速度 |
busy_timeout | 5000ms | 数据库被锁时最多等待 5 秒 |
foreign_keys | ON | 强制外键引用完整性 |
启动时自动运行数据库迁移,无需手动维护表结构。
初始管理员账户
Server 首次启动时,如果 users 表为空,会自动创建管理员账户。这里没有用户名/密码环境变量:密码始终随机生成,并以醒目的凭据横幅在 Server/容器日志中打印一次。
========================================
ServerBee initial admin credentials
Username: admin
Password: aB3xK9mP2qR5
========================================请从日志中获取该密码。首次登录时你将被要求修改它,并可在此时选择一个新的用户名。
自动生成的密码只在日志中显示一次。请在日志轮转前记录下来,并在首次登录时完成强制改密,再将 Server 暴露到公网。
Agent 接入
添加 Server 是一个幂等的 onboarding 操作。POST /api/servers 必须携带 onboarding_request_id,并在同一个事务中创建 Server 配置、标签、默认探测目标、Agent Authority 事件和一个绑定到该 Server 的 enrollment offer。使用相同 request ID 和相同输入重试会返回已有 Server。重放响应绝不会再次返回明文 code,但可以标识当前 outstanding offer,管理员随后可精确替换该 offer。
Enrollment offer 绑定到具体 Server,单次使用且短时有效(默认 10 分钟)。它的终态只有 consumed、revoked、replaced 和 expired,进入终态后不能恢复为 outstanding。明文 code 仅在新建或替换 offer 时返回一次。
Agent 在 claim offer 前自行生成并持久化 run token,然后通过 POST /api/agent/register 提交 proposed token。Server 只保存哈希,并且只返回 server_id。如果 HTTP 结果不明确,Agent 会先用已暂存的 token 尝试 WebSocket,再决定是否重新 claim。
Server 的 agent_authority.status 只有 claimed 与 unclaimed,它与 Agent 当前是否在线相互独立。Server 详情 API 和 UI 会展示 Agent Authority 状态及 outstanding offer。你可以用 auth.max_servers 限制新 Server onboarding,并用 Clean up unconnected 清理从未初始化的离线占位条目。
重新接入与吊销
已 claimed 的 Agent 需要更换 run token 时,在 Server 详情页使用 Agent 重新接入:
- Graceful 保留现有 authority,同时发出 enrollment offer。新 claim 完成前,当前 Agent 可继续运行。
- Emergency 立即吊销现有 authority、隔离旧连接,并在同一状态转换中发出 enrollment offer。
每个 Server 同时最多有一个 outstanding offer。替换或吊销必须指定界面中可见的准确 offer ID,过期页面因此不能覆盖较新的 offer。吊销 Agent Authority 是独立的破坏性操作,它会使当前 run token 失效并断开 Agent,但不会顺手生成新 offer。
所有 Agent Authority 状态转换都会记录不含密钥的事件。即使 Server 记录已删除,历史事件仍会保留。
GeoIP 设置
启用 Agent 地理位置识别:
- 下载免费的 MaxMind GeoLite2-City MMDB 数据库(需要免费的 MaxMind 账号)
- 将
GeoLite2-City.mmdb文件放到服务器上的某个可访问路径 - 在配置中启用:
[geoip]
mmdb_path = "/path/to/GeoLite2-City.mmdb"启用后,Agent 连接时 Server 会自动把其 IP 解析为所在地区和国家代码。
OAuth 设置
ServerBee 支持通过 GitHub、Google 以及任意 OpenID Connect 提供商进行第三方登录。
前置条件
把 oauth.base_url 设为 ServerBee 实例的公网 URL,用于拼接回调地址:
[oauth]
base_url = "https://serverbee.example.com"
allow_registration = true # 设为 true 时,首次 OAuth 登录会自动创建账户GitHub
- 前往 GitHub Developer Settings 创建一个 OAuth App
- 回调地址设为
https://serverbee.example.com/api/auth/oauth/github/callback - 把凭据填入配置:
[oauth.github]
client_id = "your-client-id"
client_secret = "your-client-secret"- 在 Google Cloud Console 创建 OAuth 凭据
- 回调地址设为
https://serverbee.example.com/api/auth/oauth/google/callback - 把凭据填入配置:
[oauth.google]
client_id = "your-client-id"
client_secret = "your-client-secret"通用 OIDC
适用于任意 OpenID Connect 提供商(如 Keycloak、Authentik、Authelia):
[oauth.oidc]
issuer_url = "https://auth.example.com/realms/main"
client_id = "serverbee"
client_secret = "your-client-secret"
scopes = ["openid", "email", "profile"]反向代理
不想手动配反向代理的话,安装脚本可以全自动完成这件事:安装时加 --domain monitor.example.com --email admin@example.com,或对已装好的 Server 执行 sudo serverbee domain setup --domain monitor.example.com --email admin@example.com。脚本会校验 DNS、装好 Caddy、写 Caddyfile 并签发 HTTPS 证书,同时把 auth.secure_cookie 设为 true。下面的手动配置仅在你想自己掌控反向代理时才需要。
在反向代理后运行时,必须正确转发 WebSocket 连接。
Nginx
server {
listen 443 ssl http2;
server_name serverbee.example.com;
ssl_certificate /etc/ssl/certs/serverbee.pem;
ssl_certificate_key /etc/ssl/private/serverbee.key;
location / {
proxy_pass http://127.0.0.1:9527;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# WebSocket 支持
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 86400s;
proxy_send_timeout 86400s;
}
}较大的 proxy_read_timeout 和 proxy_send_timeout 对 WebSocket 连接很重要。不配置的话,Nginx 可能过早关闭空闲连接,导致 Agent 和终端会话断开。
Caddy
Caddy 会自动处理 HTTPS 证书和 WebSocket 代理,配置更加简洁:
monitor.example.com {
reverse_proxy 127.0.0.1:9527
}配置反向代理后,Agent 应使用 https:// 协议连接:
server_url = "https://monitor.example.com"更多反向代理配置(含 Traefik)请参阅部署指南。
后台任务
Server 会自动运行多个后台任务:
| 任务 | 间隔 | 作用 |
|---|---|---|
| RecordWriter | 60s | 把缓存的 Agent 上报写入数据库 |
| OfflineChecker | 10s | 检测停止上报的 Agent(30s 阈值) |
| Aggregator | 每小时 | 将原始记录聚合为小时级汇总 |
| Cleanup | 每小时 | 按保留策略清理过期记录 |
| SessionCleaner | 定期 | 清理过期的用户 Session |
| AlertEvaluator | 60s | 评估所有启用的告警规则 |
所有任务自动启动,无需手动配置。