// 文档 · 管理员手册docs · admin manual

管理员手册Admin manual

面向自建 omts 的管理员：账号体系、OAuth 登录、系统设置、审计与集群。部署本身（docker compose、nginx、多节点上线）见服务端章节；普通用户的操作见客户端手册。 For self-hosted omts administrators: accounts, OAuth, system settings, audit, and the cluster. Deployment itself (docker compose, nginx, multi-node) is in the server chapter; end-user features live in the client manual.

管理员身份与入口Admin identity & entry

  • 首个管理员：首次启动且用户表为空时自动创建。用户名取环境变量 SC_ADMIN_USERNAME（默认 admin）；密码取 OMT_BOOTSTRAP_ADMIN_PASSWORD，未设置则随机生成并写入数据目录旁的 bootstrap-admin-password.txt（0600）——登录后删除该文件。First admin: created automatically on first boot when the user table is empty. The username comes from SC_ADMIN_USERNAME (default admin); the password from OMT_BOOTSTRAP_ADMIN_PASSWORD, or a random one written to bootstrap-admin-password.txt (0600) next to the data directory — delete it after the first login.
  • 角色：只有 admin / user 两级；管理 API 统一经 JWT + admin 守卫中间件。Roles: just admin / user; every admin API passes JWT auth plus an admin-guard middleware.
  • 入口：admin 用户的侧栏菜单出现 Admin 项——浏览器开新标签 /?page=admin，omtn 桌面壳开独立管理窗口。Entry: admins see an Admin item in the sidebar menu — a browser opens /?page=admin in a new tab; the omtn desktop shell opens a dedicated admin window.

用户管理User management

  • 基本操作：列表、创建（用户名 3–32 字符、密码 ≥8、可选角色）、禁用 / 启用、改角色、重置密码（指定或随机 16 位临时密码）、关闭某用户的 TOTP。禁用 / 改角色 / 重置密码都会踢掉该用户的浏览器连接并作废旧 JWT。没有「删除用户」接口——用户可自助删除账号。Basics: list, create (username 3–32 chars, password ≥8, optional role), disable/enable, change role, reset password (chosen or a random 16-char temp), disable a user's TOTP. Disable / role change / password reset also kick the user's browser sockets and invalidate old JWTs. There is no admin-side user deletion — users can delete their own accounts.
  • 每用户配置：文件传输限速（全局 / 不限 / 自定义 bps / 拒绝）、P2P 中继回退开关、不活跃清理豁免（admin 角色天然豁免）。Per-user settings: file-transfer rate limit (global / unlimited / custom bps / deny), P2P relay-fallback switch, inactivity-sweep exemption (admins are exempt by role).

OAuth 登录OAuth sign-in

  • 支持：飞书（feishu）、钉钉（dingtalk）、GitHub、Google。每个 provider 配置：id、显示名、app_id、app_secret（落库加密）、三组回调 URL（browser / desktop / android，必须 HTTPS；browser 最多 8 条）。Supported: Feishu, DingTalk, GitHub, Google. Per provider: id, display name, app_id, app_secret (stored encrypted), and three callback groups (browser / desktop / android, HTTPS only; up to 8 browser callbacks).
  • 镜像源自动派生：回调可从 oauth_allowed_origins（见系统设置）自动派生 <origin>/oauth-callback/<id>；改 origins 会全量重同步各 provider 的回调。Mirror-derived callbacks: callbacks can be auto-derived from oauth_allowed_origins (see system settings) as <origin>/oauth-callback/<id>; changing the origins resyncs every provider's callbacks.
  • scope 确认：feishu / dingtalk / google 保存前须勾选 scope 确认（更换 app 或类型后需重新勾选）。Scope confirmation: feishu / dingtalk / google require an explicit scope checkbox before saving (re-confirm after switching apps or provider type).
  • 进阶选项：GitHub 支持 allowed_users 白名单与自定义 endpoints；Google / 钉钉支持 auto_create_user（首次登录自动建号），Google 另有 allowed_domains。Advanced: GitHub supports an allowed_users allowlist and custom endpoints; Google / DingTalk support auto_create_user (first login creates the account), and Google adds allowed_domains.
  • 生效：保存后登录页的 provider 列表即时更新（/auth/providers）。Effect: the login page's provider list updates immediately on save (/auth/providers).

系统设置System settings

  • 开放注册：open_registration 开关——关掉后只有管理员建号或 auto-create 的用户能登录。Open registration: the open_registration switch — off means only admin-created or auto-created users can sign in.
  • 镜像源：oauth_allowed_origins（CSV）。保存需一次性解锁仪式，服务端会逐个探测镜像的 /api/v1/version 存活后才接受。Mirror origins: oauth_allowed_origins (CSV). Saving requires a one-time unlock ceremony, and the server probes each mirror's /api/v1/version for liveness before accepting.
  • P2P 数据面：p2p_relay_enabled 中继回退总开关（P2P Data Plane 标签）；file_transfer_relay_bps 全局文件传输限速默认（0 = 不限）。P2P data plane: the p2p_relay_enabled master switch for relay fallback (P2P Data Plane tab); file_transfer_relay_bps as the global file-transfer default (0 = unlimited).
  • 命令行白名单：omts config set 还可改 feishu_webhook_url（SSRF 校验）、feishu_app_id、oauth_redirect_url。CLI allowlist: omts config set additionally covers feishu_webhook_url (SSRF-checked), feishu_app_id, and oauth_redirect_url.

审计日志Audit log

管理页 Audit Log 标签返回最近 100 条。除全部 admin_* 操作外还记录：设备注册 / 吊销 / 恢复 / 删除 / 迁移、TOFU 信任事件、OAuth 自动建号、密码重授权设置、全设备登出等。 The Audit Log tab returns the latest 100 entries. Beyond every admin_* action it also records device registered/revoked/resumed/deleted/migrated, TOFU trust events, OAuth auto-created users, password-set-via-reauth, and logout-all events.

集群与节点Cluster & nodes

  • 节点列表：GET /api/v1/admin/nodes——node_id、主机名、监听地址、状态、boot epoch、版本、心跳年龄、存活判定（TTL）。Node list: GET /api/v1/admin/nodes — node_id, hostname, listen addr, state, boot epoch, version, heartbeat age, TTL-based aliveness.
  • 排空与迁移：POST /admin/nodes/self/drain 排空本节点（滚动升级用）；POST /admin/devices/{id}/migrate 两阶段把设备迁到目标节点。Drain & migrate: POST /admin/nodes/self/drain drains this node (for rolling upgrades); POST /admin/devices/{id}/migrate moves a device to a target node in two phases.
  • 多节点部署步骤（compose、nginx 双段、滚动升级）见服务端 · 多节点部署。For the multi-node deployment steps (compose, the two nginx files, rolling upgrades) see Server · multi-node.

诊断Diagnostics

  • GET /api/v1/diagnostics（admin）：版本三元组、uptime、全设备 / 全会话（集群视图）、内存日志环形缓冲。GET /api/v1/diagnostics (admin): version triple, uptime, all devices / sessions (cluster view), and the in-memory log ring buffer.
  • /healthz 公开零依赖存活探针；/metrics 按 CIDR 白名单放行；/api/v1/version 公开。/healthz is a public dependency-free liveness probe; /metrics follows the CIDR allowlist; /api/v1/version is public.
  • 设备处置分工：浏览器信任的 trusted devices 由用户自助管理（/settings/trusted-devices：列表 / 改名 / 吊销）；管理员可经 API 吊销 / 恢复 / 删除任意用户的 omtc 设备。Device split: trusted browsers are user-managed (/settings/trusted-devices: list / rename / revoke); administrators can revoke / resume / delete any user's omtc devices via API.