管理员指南

用户管理、审计日志、远程命令和计费信息管理。

本页介绍仅管理员（Admin 角色）可使用的功能。

用户管理

ServerBee 支持多用户，分为两种角色：

角色权限
Admin完全管理权限：用户管理、服务器配置、告警规则、通知渠道、审计日志等
Member对所有服务器监控数据的只读权限——Dashboard、服务器详情、Ping 结果、安全事件、公网 IP，以及自助设置（自己的密码、2FA、API Key 列表、移动设备）

Member 的可见范围是全部服务器，不支持按服务器隔离。Member 账号仅适合完全信任的协作者。如需向外部人员（如客户）展示部分服务器，请改用状态页。

管理用户

进入 Settings → Users 页面：

  • 创建用户：输入用户名、密码和角色
  • 编辑角色：修改用户的角色（Admin/Member）
  • 删除用户：删除用户账号（禁止删除最后一个 Admin）

找回丢失的管理员账号

系统没有"忘记密码"流程（自托管部署没有邮件通道），密码以 argon2 哈希存储，无法手工改库重置。如果唯一的管理员凭证（密码或 2FA 设备）丢失：

  1. 停止服务端。
  2. 执行 sqlite3 /path/to/serverbee.db "DELETE FROM users;"。
  3. 重新启动服务端——users 表为空时会重新创建 admin 用户，并在启动日志中打印一次性的新随机密码横幅。

此操作会删除所有用户账号，其 API Key 随之失效；监控数据、服务器与配置不受影响。

API 端点

端点方法说明
/api/usersGET列出所有用户
/api/usersPOST创建用户
/api/users/{id}GET获取用户详情
/api/users/{id}PUT更新用户角色
/api/users/{id}DELETE删除用户

审计日志

ServerBee 自动记录关键操作的审计日志，帮助管理员追踪安全事件。

记录的事件

  • 用户登录（成功/失败）
  • 密码修改
  • 2FA 启用/禁用
  • 终端连接/断开
  • Capability 拒绝事件
  • capability_temporarily_granted —— 主机本地的临时授予开启了某个默认关闭的能力
  • capability_grant_expired —— 临时授予到期，能力自动关回
  • capability_grant_revoked —— 主机操作者提前撤销了临时授予

查看审计日志

进入 Settings → Audit Logs 页面，可以：

  • 浏览所有审计记录（分页显示）
  • 查看用户、操作类型、详情、IP 地址和时间

API 端点

GET /api/audit-logs?limit=50&offset=0

返回分页的审计记录列表，支持 limit 和 offset 参数。每条记录包含：

{
  "id": 1,
  "user_id": "user-uuid",
  "action": "login",
  "detail": "Login successful",
  "ip": "192.168.1.100",
  "created_at": "2026-03-14T10:30:00Z"
}

审计日志默认保留 180 天（可通过 retention.audit_logs_days 配置）。

远程命令

管理员可以向在线服务器下发远程命令并获取执行结果。

使用方式

  1. 进入 Settings → Tasks 页面
  2. 输入要执行的命令
  3. 选择目标服务器（可多选）
  4. 点击 Execute

执行流程

  1. Server 创建 Task 记录
  2. 通过 WebSocket 向每台目标 Agent 发送执行命令
  3. Agent 执行命令，将 stdout/stderr 和 exit_code 回写
  4. 结果存储在 task_results 表中

限制

  • 命令执行超时：300 秒
  • 需要目标 Agent 具有 exec 能力（CAP_EXEC），该能力默认关闭。能力由 Agent 拥有 —— 在 Agent 主机的 [capabilities] allow 列表中加入 exec（或 --allow-cap exec）开启。见 功能开关
  • Agent 未上报 CAP_EXEC 的服务器会收到合成结果：exit_code = -2，提示功能被禁用
  • 仅 Admin 角色可以创建任务

API 端点

端点方法说明
/api/tasksPOST创建并下发命令
/api/tasks/{id}GET获取任务详情
/api/tasks/{id}/resultsGET获取执行结果

创建一次性任务请求体：

{
  "command": "uptime",
  "server_ids": ["server-id-1", "server-id-2"],
  "timeout": 60
}

计划任务

计划任务在远程命令基础上增加了 cron 调度、重试和运行历史。

创建计划任务

  1. 进入 Settings → Tasks。
  2. 切换到计划任务区域。
  3. 填写名称、命令、cron 表达式、目标服务器、超时、重试次数和重试间隔。
  4. 保存任务。启用状态的任务会立即注册到服务端调度器。

计划任务使用服务端 scheduler.timezone 配置计算 next_run_at。

字段

字段说明
name计划任务显示名称
task_typecron 任务使用 scheduled；省略/默认表示 oneshot
cron_expression服务端调度器解析的 cron 表达式
command下发给每个目标 Agent 的 Shell 命令
server_ids目标服务器
timeout每次尝试的命令超时时间（秒）；默认执行超时为 300 秒
retry_count首次尝试后的重试次数，范围 0-10
retry_interval重试之间等待秒数，必须至少为 1
enabled禁用后会从调度器移除，不再自动运行

执行行为

  • 每次计划触发都会生成 run_id，用于把所有目标服务器和重试尝试的结果分组。
  • ServerBee 会避免同一个计划任务重叠运行。如果上一次运行仍未结束，新的触发会被跳过。
  • POST /api/tasks/{id}/run 可手动运行任务，且手动运行会跳过重试逻辑。
  • 禁用或删除任务会取消当前活动运行。
  • 结果中包含 attempt，用于区分重试次数。

合成退出码：

退出码含义
-2CAP_EXEC 未启用，或被 Agent 本地 capability 策略阻止
-3服务器离线或下发失败
-4超时前没有收到 Agent 响应

API 示例

{
  "task_type": "scheduled",
  "name": "Daily disk check",
  "command": "df -h",
  "server_ids": ["server-id-1"],
  "cron_expression": "0 0 8 * * *",
  "timeout": 120,
  "retry_count": 2,
  "retry_interval": 60
}

相关端点：

端点方法说明
/api/tasks?type=scheduledGET列出计划任务
/api/tasksPOST创建一次性任务或计划任务
/api/tasks/{id}PUT更新任务字段、启用/禁用状态和调度注册
/api/tasks/{id}DELETE删除任务并取消活动执行
/api/tasks/{id}/runPOST手动运行任务
/api/tasks/{id}/resultsGET获取按 task/run/attempt 分组的任务结果

计费信息

管理员可以为每台服务器记录计费相关信息，方便追踪 VPS 费用和到期时间。

管理计费信息

  1. 进入服务器详情页 → 点击编辑按钮
  2. 在 "Billing" 区域填写以下信息：
字段说明
price价格
billing_cycle计费周期（monthly/quarterly/yearly 等）
currency货币单位（CNY/USD 等）
expired_at到期时间
traffic_limit流量限额（字节）

到期告警

可以创建 expiration 类型的告警规则，在服务器到期前 N 天自动发送通知：

  1. 进入 Settings → Alerts
  2. 创建新规则，指标类型选择 expiration
  3. 设置阈值为提前提醒天数（如 7 表示到期前 7 天告警）
  4. 关联通知组

流量告警

使用 transfer_in_cycle / transfer_out_cycle / transfer_all_cycle 告警类型，可以监控当前计费周期内的累计流量是否超过设定阈值。详见 告警与通知。

成本洞察

填写 price 和 billing_cycle 之后，ServerBee 会基于已记录的计费信息以及 Agent 上报的资源、利用率和在线时长，自动衍生出一组成本相关的信号。这些洞察会在三个位置展示：

  • 服务器列表的成本单元格 —— /servers 表格在 CPU/内存/磁盘/流量旁边直接展示每台服务器的月度等价成本以及成本提醒，不必再到编辑弹窗里翻找账单字段
  • 仪表盘服务器卡片 —— 每张卡片会显示一行紧凑的成本信号和注脚，概括消耗速率；计费配置缺失或非法时自动隐藏
  • 服务器详情的成本洞察面板 —— 服务器详情页展示完整明细：月度等价成本、当前计费周期已消耗 / 剩余成本与消耗百分比、剩余天数、归一化的资源单位成本（每 CPU 核 / 每 GB 内存 / 每 GB 磁盘 / 每 TB 流量限额），以及成本提醒

成本提醒

ServerBee 不再计算合成价值分，而是为每台已配置成本的服务器给出一组客观的、无需机群对比的提醒 advisories——expired_billing、sleeping_money、idle_burn、low_uptime。具体触发条件、输入校验与数据来源见成本洞察。

API

同样的数据也通过只读 API 暴露，便于自动化使用：GET /api/cost/overview（按币种汇总的机群总览 + 每台服务器摘要）和 GET /api/servers/{id}/cost-insights（单台服务器的完整明细）。认证细节见 API 参考。

Agent Authority 管理

管理员通过 添加 Server 和各 Server 的详情操作管理首次接入与重新接入。添加 Server 会原子地创建配置和一个绑定到该 Server 的 enrollment offer。明文 code 仅显示一次，后续页面只展示 offer ID、前缀、过期时间和 Agent Authority 状态。

对于 unclaimed Server，管理员可以发出 offer。对于 claimed Server，可以选择 graceful 重新接入（新 claim 完成前保留当前 authority）或 emergency 重新接入（立即吊销并隔离当前 authority）。每个 Server 同时最多一个 outstanding offer，替换或吊销都必须针对准确 offer ID。吊销 Agent Authority 是独立操作，不会隐式生成 offer。

Agent Authority 历史会记录操作者、来源、状态转换、模式、offer 结果和前后状态，但不会保存明文密钥。这些事件在 Server 删除后仍会保留，便于运维追查。

清理未连接的占位服务器

中止的接入可能会留下离线 Server 占位条目。此时 服务器 页面会显示 Clean up unconnected 操作，它只删除从未完成初始化的离线占位服务器，并刻意保留在线但尚未初始化的 Agent。

功能开关

安全设置

告警与通知

安全设置

配置双因素认证、OAuth 登录、密码管理和登录安全策略。

成本洞察

ServerBee 如何把账单字段与 agent 指标转换为消耗速率、单位资源成本，以及客观的成本提醒。