服务端 omtsServer · omts

omts 是 API 与 WebSocket 中继服务：浏览器用户认证（密码/TOTP/OAuth）、设备注册与会话管理、浏览器与 omtc 之间的密文中继，以及 P2P 信令与 STUN 响应。它不接触明文载荷——加密发生在两端。库表启动时自动迁移，无需手工 schema。 omts is the API and WebSocket relay: browser authentication (password/TOTP/OAuth), device registry and session management, ciphertext relay between browsers and omtc, plus P2P signaling and a STUN responder. It never touches plaintext payloads — encryption happens at the endpoints. Schema migrations run automatically at startup.

单机部署Single-node deployment

一台 Linux 主机：宿主机 nginx 终止 TLS，omts 在容器里监听 loopback，后接本机 MySQL。绝大多数自托管场景从这里开始。 One Linux host: host nginx terminates TLS, omts listens on loopback inside a container, backed by local MySQL. Where most self-hosted setups start.

浏览器 / omtc ──https──▶ nginx :443 ──▶ omts 127.0.0.1:6444 ──▶ MySQL 127.0.0.1:3306

• 前置：Linux 主机（glibc 动态链接，Alpine 跑不起来）、Docker + docker compose、宿主机 nginx（或其他能配 WebSocket upgrade 的反代）、编译好的 omts 二进制（源码仓 cargo build --release -p omts，或从 Releases 取）。Prerequisites: a Linux host (glibc, not Alpine), Docker + compose, host nginx (or any proxy that can pass WebSocket upgrades), and the omts binary (cargo build --release -p omts from source, or from Releases).
• MySQL：docker 起一个 MySQL 8（数据落卷、绑定 127.0.0.1），创建 omts 库与用户。建表由 omts 启动时自动完成。MySQL: run MySQL 8 in docker (data on a volume, bound to 127.0.0.1) and create the omts database and user. Tables are created automatically at startup.
• 目录：/opt/omt/bin/omts（二进制，volume 挂进容器）、/opt/omt/data/（运行状态，属主 65532:65532）、docker-compose.yml 与 .env。Layout: /opt/omt/bin/omts (the binary, mounted read-only into the container), /opt/omt/data/ (state, owned 65532:65532), plus docker-compose.yml and .env.

.env 最小集合（secrets 用 SC_* 命名，compose 显式映射到进程的 OMT_*）：Minimal .env (secrets use SC_* names; compose maps them onto the process's OMT_* explicitly):

SC_REG_TOKEN=<设备注册令牌>
SC_JWT_SECRET=<随机串>
SC_CRYPTO_SECRET=<随机串>
SC_DB_URL=mysql://omts:<password>@127.0.0.1:3306/omts
OMT_ENV_ROLE=production
OMT_ENV_SERVER_URL=https://omt.example.com
OMT_ENV_URL_PREFIX=/omt
OMT_TRUST_PROXY=true
OMT_METRICS_ALLOW_CIDRS=127.0.0.1/32

compose 要点（安全内建，勿弱化）：Compose essentials (hardened by default — do not weaken):

• 容器 network_mode: host + omts 监听 127.0.0.1:6444——只有 nginx 能到达。Container uses network_mode: host while omts binds 127.0.0.1:6444 — only nginx can reach it.
• 以非 root（65532）运行，cap_drop: [ALL]、pids_limit；二进制只读挂载。Runs as non-root (65532) with cap_drop: [ALL] and a pids_limit; the binary is mounted read-only.
• secrets 经 显式 environment 列表注入（不要改回 env_file——那会把全部 secret 整包暴露给 docker inspect）。Secrets are injected via an explicit environment list (do not switch back to env_file — it exposes every secret wholesale to docker inspect).

nginx：TLS 终止在 nginx；WebSocket 必须透传 Upgrade/Connection，读超时要放宽到会话级别：nginx: terminate TLS here; WebSocket upgrade headers must pass through, and read timeouts must be session-scale:

location /omt/ {
    proxy_pass http://127.0.0.1:6444;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_read_timeout 3600s;          # 会话长连接
}

要浏览器 UX，还需把官方 dist 静态集（ui/ 页面、metainfo.json、版本化下载物）放到 nginx 静态目录，由 nginx 直接 serve（生产模板随源码仓提供，含 CSP、安全头与缓存策略）。只要 CLI（omtc）用法则完全不需要静态文件。 For the browser UX, also place the official dist static set (ui/ pages, metainfo.json, versioned downloads) in an nginx-served directory (the production template ships with the source repo, covering CSP, security headers, and caching). A CLI-only (omtc) deployment needs no static files at all.

• 首次启动：docker compose up -d 后 curl http://127.0.0.1:6444/api/v1/version 应返回 200；/opt/omt/data/ 会落一份一次性 bootstrap 管理员密码（0600），用它登录管理页后删除。First boot: after docker compose up -d, curl http://127.0.0.1:6444/api/v1/version should return 200; a one-time bootstrap admin password (0600) lands in /opt/omt/data/ — log in once, then delete it.
• 升级：新二进制 cp 到 bin/omts（temp+rename，运行中的旧 inode 不受影响）后 docker compose up -d 重建容器。schema 迁移自动且只增列，可回滚到上一个二进制；单机重启会断在线会话（客户端自动重连），要求无感请用多节点。Upgrades: cp the new binary into bin/omts (temp+rename — the running old inode is untouched) and docker compose up -d to recreate the container. Migrations are additive-only and rollback-safe; a single-node restart drops live sessions (clients reconnect) — use multi-node for zero-interruption.

多节点部署Multi-node deployment

同一主机（或多台主机）跑多个 omts 实例，共享同一个 MySQL。价值：滚动升级时在线会话不中断（节点逐个 drain）并扩容。节点之间没有任何直接通信——所有协调（会话归属、epoch、租约）都走共享数据库。 Run several omts instances (same host or many) over one shared MySQL. The payoff: rolling upgrades without dropping live sessions (nodes drain one by one) and more capacity. Nodes never talk to each other directly — all coordination (session ownership, epochs, leases) happens through the shared database.

                ┌─▶ omts1 (--node-id 1, 127.0.0.1:6444) ─┐
浏览器/omtc ──▶ nginx（omts_pool 轮询 + /n1/ /n2/ 钉定） ├─▶ MySQL（同一实例）
                └─▶ omts2 (--node-id 2, 127.0.0.1:6445) ─┘

• 起点：先完成单机部署。集群 compose 与单机文件并存不替换——回滚就是 multi-node down && 单机 up。Start from a finished single-node deployment. The cluster compose file coexists with (does not replace) the single-node one — rollback is multi-node down && single-node up.
• compose 差异：两个 service（omts1 --node-id 1 :6444 / omts2 --node-id 2 :6445）；同一个 DSN 与 ./data 卷；stop_grace_period: 75s——SIGTERM 后先广播 reconnect_hint、等在线设备离开（最长 60s drain），compose 默认 10s 会在排水中途 SIGKILL。Compose differences: two services (omts1 --node-id 1 :6444 / omts2 --node-id 2 :6445); the same DSN and ./data volume; stop_grace_period: 75s — after SIGTERM the node broadcasts a reconnect hint and waits for online devices to leave (up to 60s drain); the compose default of 10s would SIGKILL mid-drain.
• nginx 装两段：upstream/map 属 http 作用域、location 属 server 作用域，drop-in 被 include 在 server 里，所以要拆两个文件（upstreams 放 sites-enabled/，路由放 sites-available/）：nginx needs two files: upstream/map live in the http scope while location lives in the server scope, and drop-ins are included inside server blocks — so split them (upstreams into sites-enabled/, routing into sites-available/):

# http 作用域：upstreams.conf
upstream omts_pool {
    server 127.0.0.1:6444;
    server 127.0.0.1:6445;
}

# server 作用域：路由 drop-in
location /omt/n1/ { proxy_pass http://127.0.0.1:6444; }   # 钉定节点（排障/灰度）
location /omt/n2/ { proxy_pass http://127.0.0.1:6445; }
location /omt/    { proxy_pass http://omts_pool; }        # 默认轮询
# （同单机：每个 location 都要透传 Upgrade/Connection 与长读超时）

• 顺序：先装 nginx 再起第二节点（/n2/ 路由在节点注册前就该存在）。备份文件不要放 sites-enabled/——nginx glob 会把它当第二份配置加载（duplicate upstream）。Order: install the nginx config before starting the second node (the /n2/ route must exist before the node registers). Never park backup files in sites-enabled/ — nginx globs them in as a second copy (duplicate upstream).
• 启动与验证：docker compose -f docker-compose.multi-node.yml up -d；管理页的集群面板应显示两个 epoch 成员。P2P 的 STUN 地址按节点配置（OMT_STUN_LISTEN/OMT_STUN_PUBLIC_ADDR 每节点一对），第二节点缺 STUN 对会静默退化成中继——部署后 ss -ulnp | grep 3478 核对。Start & verify: docker compose -f docker-compose.multi-node.yml up -d; the admin cluster panel should show both epoch members. STUN is per-node (OMT_STUN_LISTEN/OMT_STUN_PUBLIC_ADDR, one pair each); a node missing its STUN pair silently degrades to relay — check with ss -ulnp | grep 3478 after deploying.
• 滚动升级：替换二进制后逐节点重建——先 n2 后 n1（n1 是默认池成员，最后动）。在线设备收到 reconnect_hint 后换节点重连，会话不中断。Rolling upgrade: swap the binary, then recreate node by node — n2 first, n1 last (n1 is the default pool member). Online devices follow the reconnect hint to the other node; sessions survive.
• 回滚到单机：docker compose -f docker-compose.multi-node.yml down 然后 docker compose up -d（单机栈从未被修改）。Roll back to single node: docker compose -f docker-compose.multi-node.yml down, then docker compose up -d (the single-node stack was never modified).

启动参数CLI flags

每个参数都有对应的环境变量绑定（表中 env 列）；带 secret 的参数只走环境变量。 Every flag has an environment binding (the env column); secret-bearing flags are env-only.

监听与 TLSListen & TLS

数据库与密钥Database & secrets

对外地址与多节点 / P2PURL, multi-node & P2P

限流、观测与不活跃清理Limits, observability & inactivity

登录与企业集成Auth & integrations

子命令：omts config set <key> <value> [--db-url …] [--dry-run] 绕过 HTTP 管理 API、直改库内配置项（按 key 类型校验）。Subcommand: omts config set <key> <value> [--db-url …] [--dry-run] sets a config key directly in the DB, bypassing the HTTP admin API (type-checked per key).

网络要求Networking

• P2P 直连需要 STUN 端口（默认 UDP 3478）可达：宿主机 iptables 与云防火墙/安全组两层都要放行，只开一层会静默退化为中继。集群每个节点要独立的公网 STUN 端口。P2P direct needs the STUN port (UDP 3478 by default) reachable: open it in BOTH host iptables and the cloud firewall/security group — one layer alone silently degrades to relay. Each cluster node needs its own public STUN port.
• 中继走 HTTPS/WSS 443，无额外端口；弱网下自动回落。The relay rides HTTPS/WSS on 443 with no extra ports, and is the automatic weak-network fallback.