Import docs/server.md
This commit is contained in:
parent
adf456f1c0
commit
4c84ffabfe
491
docs/server.md
491
docs/server.md
|
|
@ -1,471 +1,58 @@
|
|||
# DSH Remote Server 设计说明
|
||||
# Server 职责与接入边界
|
||||
|
||||
状态:Draft v0.1
|
||||
日期:2026-08-15
|
||||
实现状态:**完整站点位于独立 Server 仓库;本仓库 `apps/server` 提供最小自部署子集。**
|
||||
本文说明 Remote 与 Server 的职责划分。线协议统一在 [protocol.md](protocol.md);完整站点的内部实现、数据库 schema、迁移、Admin 和部署配置由独立 Server 仓库维护。
|
||||
|
||||
## 0. 仓库边界(规范性)
|
||||
## 两种 Server
|
||||
|
||||
本文保留完整 Server 的设计与互操作契约。用户于 2026-09-19 授权在当前仓库实现最小自部署版本,其运行方式与支持的 API 见 [最小 Server 说明](../apps/server/README.zh.md)。
|
||||
|
||||
最小版本参考独立仓库的账号/设备 API、WebSocket Gateway 与 Hub 逻辑,使用环境变量单账号和 JSON 文件持久化,支持 Control/Noise handshake forwarding、WebRTC signaling 转发、短期 TURN credential 与 opaque Relay。Web 提供登录与设备状态页。后文记录独立 Server 项目的完整设计。
|
||||
|
||||
## 1. 定位
|
||||
|
||||
DSH Remote Server 是一个自部署的**协调与中继服务**。它负责账号授权设备注册、在线状态、连接授权、WebRTC signaling、短期 TURN credential、加密 Relay 和站点管理;它不执行 Harness 任务,也不保存会话明文。
|
||||
|
||||
Server、Remote Web 和 Admin 是一个站点:
|
||||
|
||||
- 一个 `REMOTE_PUBLIC_URL`
|
||||
- 一个 FastAPI 进程/API 入口
|
||||
- 一个 React 构建
|
||||
- 一个 SQLite 数据库
|
||||
- 一个 WebSocket endpoint
|
||||
- `/app` 为 Remote 用户区
|
||||
- `/app/admin` 为白名单账号可见的管理区(`/admin` 为旧站点路由别名)
|
||||
|
||||
独立 Server 项目内部可以按 Python 后端与 React 前端分层,但生产部署不可拆成两个用户站点。这里描述的是外部 Server 项目的目标结构,不是当前仓库目录规划。
|
||||
|
||||
## 2. 目标与非目标
|
||||
|
||||
### 目标
|
||||
|
||||
- Host 在 NAT 后只通过出站 WSS 即可上线。
|
||||
- Web/其他 Client 登录账号后直接获得同账号 Host 的访问权限。
|
||||
- 只允许同一账号下的 Client 与 Host signaling/relay。
|
||||
- P2P 失败时无缝回退到 TURN 或加密 Relay。
|
||||
- Admin 能诊断设备、连接和 TURN 健康。
|
||||
- 单机 SQLite + Docker Compose 即可自部署。
|
||||
- Server 被入侵时,攻击者仍不能直接读取会话或控制 Host。
|
||||
|
||||
### 非目标
|
||||
|
||||
- 不保存 prompt、conversation、workspace 文件、tool output 或 shell history。
|
||||
- 不提供 Harness RPC 的 HTTP 代理。
|
||||
- 不提供 terminal、SSH、VNC、远程文件系统或模型代理。
|
||||
- MVP 不引入 Redis、Kafka、RabbitMQ、Celery、Postgres 或 Kubernetes。
|
||||
- Admin 不拥有会话解密能力。
|
||||
- MVP 不做组织、RBAC、SSO、计费和多人协作。
|
||||
|
||||
## 3. 系统边界
|
||||
|
||||
```text
|
||||
Host Plugin Browser Launcher / Remote Web
|
||||
| |
|
||||
| WSS outbound | HTTPS / HTTPS + WSS
|
||||
v v
|
||||
DSH Remote Server
|
||||
+---------------------------+
|
||||
| Account + Device API |
|
||||
| WebSocket Connection Hub |
|
||||
| WebRTC Signaling |
|
||||
| Opaque Encrypted Relay |
|
||||
| TURN Credential Service |
|
||||
| Admin API + React Static |
|
||||
+---------------------------+
|
||||
|
|
||||
SQLite
|
||||
```
|
||||
|
||||
控制面包含设备、membership、连接和 signaling 元数据。数据面中的 Harness RPC/Event 在 Host 和 Client 之间端到端加密;Relay 只转发 ciphertext。
|
||||
|
||||
## 4. 技术约束
|
||||
|
||||
- Python 3.12+
|
||||
- FastAPI
|
||||
- SQLAlchemy 2
|
||||
- Alembic
|
||||
- Pydantic v2
|
||||
- SQLite(WAL)
|
||||
- uvicorn
|
||||
- React + Vite + TypeScript(统一站点前端)
|
||||
- coturn(标准部署可选启用)
|
||||
|
||||
## 5. 站点路由
|
||||
|
||||
| 路由 | 内容 |
|
||||
| --- | --- |
|
||||
| `/` | 项目介绍(Landing Page,公开) |
|
||||
| `/guide` | 使用指南(公开) |
|
||||
| `/app/access` | 同账号工作电脑远程访问(需登录) |
|
||||
| `/app/hosts` | Host 接入与状态(需登录) |
|
||||
| `/app/*` | Remote 用户区(需登录) |
|
||||
| `/admin/*` | Admin 管理区 |
|
||||
| `/api/v1/*` | Remote REST API |
|
||||
| `/api/v1/admin/*` | Admin REST API |
|
||||
| `/ws/v1/connect` | Host/Client 统一 WebSocket |
|
||||
| `/health` | liveness |
|
||||
| `/ready` | readiness,按部署策略限制细节 |
|
||||
|
||||
生产环境由 FastAPI 托管 `apps/web/dist`。API/WebSocket route 必须先于 SPA fallback 注册;未知 `/api/*` 返回 JSON 404,不能返回 `index.html`。
|
||||
|
||||
## 6. 身份模型
|
||||
|
||||
### Device
|
||||
|
||||
每个 Host/Client 持有随机 `deviceId` 和本地 X25519 identity key。Server 保存 device descriptor 与 public key,不保存 private key。
|
||||
|
||||
每个设备同时绑定 `owner_account`。账号归属决定设备间访问边界,device token 只用于
|
||||
后续 control plane 身份认证;E2EE peer identity 继续绑定具体 connection。
|
||||
|
||||
### Membership
|
||||
|
||||
Membership 是 Server 根据相同 `owner_account` 自动维护的 Host/Client 授权边。只有
|
||||
active membership 且双方账号仍一致时才能:
|
||||
|
||||
- 查看 Host presence。
|
||||
- 创建 Host/Client connection。
|
||||
- 交换 signaling。
|
||||
- 使用 Relay。
|
||||
- 请求该 connection 的 TURN credential。
|
||||
|
||||
### Admin
|
||||
|
||||
Admin 无独立入口:只有白名单账号(`DSH_ADMIN_EMAILS` / `DSH_ADMIN_ZHIHU_OPEN_IDS`)
|
||||
可作为管理员。Admin API 仅接受 web Bearer 令牌(`typ=web` + 白名单);Remote
|
||||
device Bearer 与普通 web 账号均不能访问 Admin API。
|
||||
|
||||
## 7. 设备注册
|
||||
|
||||
Host 与 Client 的首次账号归属必须携带站点账号 token 注册随机身份并获取 Server credential。
|
||||
Host 还可用账号网页生成的一次性主机匹配码接入。注册行为按 IP/账号限速;重复
|
||||
deviceId 不允许覆盖已有 public key、role 或 owner。
|
||||
|
||||
Server credential 使用短 access token + 可旋转 refresh token,凭据以摘要保存。刷新响应丢失时允许恢复尚未再次轮换、撤销或过期的直接后继;过时 token 被拒绝,但不撤销当前有效凭据。恢复边界与自部署 Server 持久化方式见 [协议 §8.2](protocol.md#82-refresh)。
|
||||
|
||||
Host/Client private key 始终留在设备本地。
|
||||
|
||||
同一 Plugin 安装在任一角色已经归属账号后,可用该角色 device credential 注册本机的
|
||||
相反角色。Server 只继承 owner,仍要求两个角色使用不同 deviceId、identity key 和
|
||||
token pair。
|
||||
|
||||
## 8. 账号授权设计
|
||||
|
||||
- Host 和 Client 注册后,Server 查找同账号下所有未撤销的异角色设备并建立
|
||||
`device_memberships` 行。
|
||||
- 无论 Host 先注册还是 Client 先注册,最终授权结果一致。
|
||||
- 同账号设备重新注册会恢复被撤销的派生授权边;撤销整个设备仍使其 token 与连接失效。
|
||||
- REST 设备详情、presence、TURN 与 WebSocket connect 都继续校验 membership,防止 IDOR。
|
||||
- WebSocket connect 在创建 connection 前再次校验双方 `owner_account` 完全一致。
|
||||
- Host 收到 `connect.incoming.authorization = "account"` 后通过受 membership 保护的
|
||||
设备详情接口交叉校验 Client descriptor,再写入本机 pinned trust 并进入安全握手;
|
||||
不存在额外设备码、确认事件或本机人工确认 UI。
|
||||
|
||||
主机匹配码是另一件事:它只授权一个 Host 加入账号,采用 8 位无歧义 Base32、
|
||||
10 分钟 TTL、单次消费和 keyed hash 存储。
|
||||
|
||||
## 9. REST API
|
||||
|
||||
### Remote API
|
||||
|
||||
| Method | Path | Auth | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| `POST` | `/api/v1/devices/register` | Account | 注册账号拥有的 Host 或 Client,并同步授权边 |
|
||||
| `POST` | `/api/v1/devices/register-owned-role` | Device | 为同一安装注册账号拥有的相反角色 |
|
||||
| `POST` | `/api/v1/account/host-registration-codes` | Account | 生成一次性主机匹配码 |
|
||||
| `POST` | `/api/v1/devices/register-with-code` | rate limited | 使用主机匹配码注册 Host |
|
||||
| `POST` | `/api/v1/auth/browser-authorizations/exchange` | Account | 用当前 Web 授权注册 Browser Client |
|
||||
| `GET` | `/api/v1/account/devices` | Account | 返回账号拥有的 Host 及当前在线状态 |
|
||||
| `GET` | `/api/v1/devices` | Client | 返回该 Client 同账号可访问的 Host |
|
||||
| `GET` | `/api/v1/devices/{id}` | membership | Host 元数据 |
|
||||
| `POST` | `/api/v1/auth/refresh` | refresh token | 旋转 token |
|
||||
| `GET` | `/api/v1/turn/credentials` | active connection | 短期 TURN credential |
|
||||
|
||||
具体 request/response 和错误 envelope 见 [protocol.md](protocol.md)。
|
||||
|
||||
### Admin API
|
||||
|
||||
| Method | Path | 说明 |
|
||||
| 范围 | 本仓库 `apps/server` | 独立完整 Server |
|
||||
| --- | --- | --- |
|
||||
| `GET` | `/api/v1/admin/health` | Server/DB/WebSocket/TURN 健康 |
|
||||
| `GET` | `/api/v1/admin/devices` | 全站设备元数据 |
|
||||
| `POST` | `/api/v1/admin/devices/{id}/revoke` | 撤销设备、token、连接 |
|
||||
| `GET` | `/api/v1/admin/connections` | 连接元数据 |
|
||||
| `GET` | `/api/v1/admin/settings` | 脱敏的生效配置 |
|
||||
| 账号 | 环境变量配置的单账号 | 多账号及站点支持的授权方式 |
|
||||
| 持久化 | JSON 文件 | 由独立仓库维护 |
|
||||
| 设备 | 注册、自有角色、刷新、发现和撤销等已实现 API | 完整账号/设备管理与关系授权 |
|
||||
| 连接 | Control、Noise 握手转发、可配置 WebRTC signaling/TURN credential、加密 Relay | 同一协议及部署实际启用的可选扩展 |
|
||||
| Web | 登录和设备状态页 | Remote Web 会话 UI 与 Admin |
|
||||
| 可选配对/Relay 恢复 | 不声明未实现能力 | 按 capability 协商,不能由版本号推断 |
|
||||
|
||||
Admin API 不提供 conversation、workspace、session title、prompt 或 tool output 字段。
|
||||
最小 Server 的安装、环境变量、API 和 Docker 说明见 [README](../apps/server/README.zh.md)。未配置 STUN/TURN 时保持 Relay-only;它不是完整站点的替代实现。
|
||||
|
||||
## 10. WebSocket Gateway
|
||||
## 职责
|
||||
|
||||
统一入口 `/ws/v1/connect`。连接必须在短超时内发送 hello;未认证连接不能进入 ConnectionHub。
|
||||
Server 处理账号授权、设备 credential、membership、presence、连接协调、ICE/TURN 配置与密文路由,不执行 Harness 或 Agent 任务。
|
||||
|
||||
状态:
|
||||
- Host 与 Client 使用独立设备身份和凭据,主动建立出站 Control WebSocket。
|
||||
- REST、Control、Relay 与 signaling 均校验设备状态、角色、有效关系和连接归属。
|
||||
- 账号 token 与 device token 隔离;账号 token 只用于对应账号 API 和设备 bootstrap,不作为 Control 身份。
|
||||
- 普通同账号设备按协议派生 membership;扫码配对受限设备只取得显式批准的关系,不能恢复全账号自动授权。
|
||||
- 首次公钥分发依赖 Server;既有 key pinning 与 Noise 不构成独立的首次身份验证,见[信任边界](end-to-end-encryption.md#2-设备身份与信任)。
|
||||
|
||||
```text
|
||||
ACCEPTED -> AUTHENTICATING -> READY -> DRAINING -> CLOSED
|
||||
| | |
|
||||
+----------> CLOSED <-------+
|
||||
```
|
||||
## 互操作接口
|
||||
|
||||
hello 校验:
|
||||
稳定入口包括 `/api/v1/*` REST 和 `/ws/v1/connect` Control WebSocket。请求、响应、错误、frame 限额和 capability 以协议为准,不在本文件复制 schema。
|
||||
|
||||
- protocol version
|
||||
- role (`host` / `client`)
|
||||
- deviceId 与 access token subject 一致
|
||||
- device 未撤销
|
||||
- token 未过期
|
||||
- Origin 合法(浏览器 Client)
|
||||
- clientVersion 与 Host harnessVersion 格式(提供时)
|
||||
- capabilities 格式与 frame 大小
|
||||
Host 注册、刷新和本地存储见 [Plugin 接入](plugin-integration.md);Browser Launcher 只换取自己的独立设备凭据、查询 Host 并打开 Remote Web,不在扩展内实现会话 runtime。
|
||||
|
||||
同一 device 新连接的处理策略必须明确:MVP 采用新连接替换旧连接,旧连接收到 `CONNECTION_REPLACED` 后关闭。
|
||||
Server 必须按每条 connection 保持 signaling、`transport.selected` 与 `secure.handshake` 的转发顺序;未知 target、错误角色、越权连接及超限帧拒绝。单条逻辑连接关闭不能影响同一 Host 的其他 Client。
|
||||
|
||||
## 11. Signaling
|
||||
TURN credential 仅向有权限且正在建立连接的双方签发;TURN secret 不返回客户端。Relay 只处理不透明密文,并执行连接归属、大小、背压和慢消费者限制。
|
||||
|
||||
Server 转发 `signal.offer`、`signal.answer` 和 `signal.ice`,但必须校验:
|
||||
## 可选能力
|
||||
|
||||
- connectionId 属于发送方。
|
||||
- targetDeviceId 与 active membership 匹配。
|
||||
- 发送方/目标角色正确。
|
||||
- SDP/candidate 大小、频率和总数在限制内。
|
||||
- connection 已进入允许 signaling 的状态。
|
||||
能力由当前 Server、Host、Client 以及所需节点共同协商,缺少任一方时保留原行为:
|
||||
|
||||
Server 不修改 SDP,不参与 DataChannel 业务协议。
|
||||
- [设备配对](device-pairing-v1.md):手机确认、单次验证码与电脑本机最终提交;不等同普通 OAuth 登录。
|
||||
- 独立 Relay attach:短期 ticket 绑定节点、epoch、connection 与设备对;不能复用到另一条连接。
|
||||
- [控制面恢复](design/control-recovery.md):共用双端授权租约;WebRTC 需健康 DataChannel,独立 Relay 需原 data socket 存活。不恢复主 Server Relay、丢失的 socket 或端点重启。
|
||||
|
||||
同一 `connectionId` 发往同一目标的 `signal.*`、`transport.selected` 与
|
||||
`secure.handshake` 必须通过单一有序发送队列转发,禁止为不同 frame 启动彼此独立的
|
||||
fire-and-forget send task。尤其不能让 `secure.handshake` 越过先收到的
|
||||
`transport.selected`;否则 Client 和 Host 可能把同一条 Noise channel 绑定到不同数据面。
|
||||
`lan` 是 `transport.selected` 的一等线协议值;双方声明 `transport.lan` capability 时必须
|
||||
原样转发。只有目标旧 RC2 Host 未声明该 capability 时,才允许兼容降级为 `p2p`。
|
||||
控制面中断时,已协商租约可能延迟撤销传播;不能宣称 Server 能物理保证断网 P2P 的瞬时断流。恢复不重放业务请求,也不重置 Noise counter。
|
||||
|
||||
## 12. Relay
|
||||
## 安全与运维
|
||||
|
||||
Relay 是 P2P/TURN 不可用时的数据面 fallback。
|
||||
|
||||
外层 envelope 可见字段仅用于路由:protocol、connectionId、sender、target、counter、ciphertext 长度。ciphertext 内是完整 Remote Protocol message。
|
||||
|
||||
Server 必须:
|
||||
|
||||
- 将 payload 视为 opaque bytes。
|
||||
- 不记录 payload、nonce、完整 message size 序列或解密失败细节。
|
||||
- 校验 active membership 和 connection ownership。
|
||||
- 限制单 frame、每秒 frame、每连接队列和总带宽。
|
||||
- 使用有界发送队列;慢消费者触发 `SLOW_CONSUMER` 断开。
|
||||
- device revoke 后立即关闭相关 channel。
|
||||
|
||||
## 13. TURN
|
||||
|
||||
TURN credential 由 `TURN_SECRET` 动态生成,TTL 与 connection 建立窗口匹配。只有 active membership 且处于连接建立阶段的设备可获取。
|
||||
|
||||
Server 不向前端返回 `TURN_SECRET`。Admin 只能看到 TURN URL、是否配置、credential 生成是否正常和可选探测结果。
|
||||
|
||||
## 14. 数据模型
|
||||
|
||||
### `devices`
|
||||
|
||||
`id`, `name`, `role`, `platform`, `public_key`, `owner_account`, `version`, `created_at`, `last_seen_at`, `revoked_at`
|
||||
|
||||
### `host_registration_codes`
|
||||
|
||||
`id`, `code_hash`, `owner_account`, `status`, `created_at`, `expires_at`, `consumed_at`, `consumed_device_id`
|
||||
|
||||
### `device_memberships`
|
||||
|
||||
`id`, `host_device_id`, `client_device_id`, `created_at`, `last_connected_at`, `revoked_at`
|
||||
|
||||
### `refresh_tokens`
|
||||
|
||||
`id`, `device_id`, `membership_id`, `token_hash`, `family_id`, `issued_at`, `expires_at`, `rotated_at`, `revoked_at`
|
||||
|
||||
### `connections`
|
||||
|
||||
`id`, `host_device_id`, `client_device_id`, `transport`, `connected_at`, `disconnected_at`, `disconnect_code`, `bytes_relayed`, `p2p_established_ms`
|
||||
|
||||
### `admin_sessions`
|
||||
|
||||
`id`, `session_hash`, `created_at`, `expires_at`, `revoked_at`, `last_seen_at`
|
||||
|
||||
### `user_accounts`
|
||||
|
||||
站点账号(邮箱或知乎衍生账号 id):`account`(PK), `password_hash`(argon2id,可空),
|
||||
`created_at`, `updated_at`, `archived_at`
|
||||
|
||||
### `oauth_identities`
|
||||
|
||||
知乎 open_id 与账号的绑定及 access token(hash 存储):`id`, `account`(FK),
|
||||
`zhihu_open_id`(unique), `access_token`, `access_token_expires_at`, `created_at`, `updated_at`
|
||||
|
||||
### `user_profiles`
|
||||
|
||||
展示资料:`account`(PK/FK), `open_id`, `name`, `headline`, `avatar_url`, `source`(password|oauth), `updated_at`
|
||||
|
||||
### `invite_codes`
|
||||
|
||||
一次性邀请码:`invite_code`(PK), `inviter_account`(FK), `invitee_account`, `generation_month`, `created_at`, `used_at`
|
||||
|
||||
> 旧 `admin_sessions`(密码会话)表已随白名单 Admin 移除(迁移 `6f2d3e4a5b6c`)。
|
||||
|
||||
数据库 schema 明确禁止加入 conversation payload、workspace、session message、tool output 或密钥字段。
|
||||
|
||||
## 15. 配置
|
||||
|
||||
| 环境变量 | 生产要求 |
|
||||
| --- | --- |
|
||||
| `REMOTE_PUBLIC_URL` | 必填,HTTPS URL |
|
||||
| `REMOTE_SECRET_KEY` | 必填,高熵,不允许默认值 |
|
||||
| `DATABASE_URL` | 默认 `sqlite:////data/remote.db` |
|
||||
| `DSH_ADMIN_EMAILS` | Admin 白名单邮箱(逗号分隔);可选 |
|
||||
| `DSH_ADMIN_ZHIHU_OPEN_IDS` | Admin 白名单知乎 open_id(逗号分隔);可选 |
|
||||
| `STUN_URLS` | 可选 |
|
||||
| `TURN_URL` | TURN 启用时必填 |
|
||||
| `TURN_SECRET` | TURN 启用时必填 |
|
||||
| `HOST_REGISTRATION_CODE_TTL_SECONDS` | 主机匹配码有效期,默认 600 秒 |
|
||||
| `ACCESS_TOKEN_TTL_SECONDS` | 短 TTL |
|
||||
| `REFRESH_TOKEN_TTL_SECONDS` | 可配置并支持轮换 |
|
||||
| `DSH_ZHIHU_OAUTH_APP_ID` | 可选;配置后启用知乎授权登录 |
|
||||
| `DSH_ZHIHU_OAUTH_APP_KEY` | 可选;同上 |
|
||||
| `DSH_WEB_LOGIN_TTL_SECONDS` | web 会话有效期,默认 28 天 |
|
||||
| `DSH_INVITE_CODE_MONTHLY_LIMIT` | 每账号每月邀请码上限,默认 10 |
|
||||
| `DSH_INVITE_CODE` | 可选;站点通用邀请码,配置后任何人可直接用它注册(可重复使用、无 inviter、不占每月配额) |
|
||||
| `LOG_LEVEL` | 默认 `INFO` |
|
||||
|
||||
启动时校验配置、数据库迁移、可写性和 secret 强度。生产安全配置缺失时拒绝启动。
|
||||
|
||||
## 15a. 站点账号登录
|
||||
|
||||
Host 插件的账号登录、设备注册、凭证轮换和 WebSocket 接入约定见
|
||||
[Host 插件接入指南](plugin-integration.md)。
|
||||
|
||||
- 站点路由 `/app/*` 需要登录;`/guide`、`/` 公开;站点管理
|
||||
`/app/admin`(兼容旧 `/admin`)仅白名单账号。
|
||||
- 登录方式一:知乎 OAuth(`/api/v1/auth/oauth/start` → 知乎授权 →
|
||||
`/api/v1/auth/oauth/callback` → 回跳 `?token=`)。state 为内存短时映射 +
|
||||
HttpOnly Cookie 校验;未配置凭据时回跳 `?error=oauth_not_configured`。
|
||||
- 登录方式二:GitHub OAuth(`/api/v1/auth/oauth/github/start` → GitHub 授权 →
|
||||
`/api/v1/auth/oauth/github/callback`);使用不可变 GitHub user id 绑定站点账号。
|
||||
- Android Client 可对两种 OAuth 使用固定 `dshremote://oauth` 回跳并领取一次性
|
||||
Web token 来注册本机 device;其他外部 `return_to` 仍必须拒绝或规范化为 `/app`。
|
||||
- 桌面扫码登录由 `POST /api/v1/auth/oauth/qr/start?provider=zhihu|github` 创建短期
|
||||
一次性会话,原插件轮询 `GET /api/v1/auth/oauth/qr/{qrId}` 领取结果。省略 provider
|
||||
时默认知乎以兼容旧客户端;两种 provider 的 Web token 都不进入二维码、手机回调 URL 或日志。
|
||||
- 登录方式三:邮箱密码,注册需要邀请码
|
||||
(`POST /api/v1/auth/register` / `POST /api/v1/auth/login`)。
|
||||
- web 会话为 HS256 JWT(`typ=web`),与设备令牌隔离;账号接口
|
||||
`/api/v1/auth/me|invite-code|invite-codes` 仅接受 web 令牌。
|
||||
- Browser Launcher 不实现账号、密码或 OAuth 登录。它从已登录的同源 Remote Web 页面临时
|
||||
读取 web token,并调用 `POST /api/v1/auth/browser-authorizations/exchange`,用当前 Web 授权和
|
||||
自己的独立 identity 换取 Browser device token pair。web token 不得写入扩展存储、日志或 URL。
|
||||
- Browser Launcher 不承载 Remote Client runtime。取得自己的 Browser device token 后只查询
|
||||
Host 和 presence;点击在线 Host 直接打开同源 `/app/remote/{hostDeviceId}`,复用浏览器现有
|
||||
Web 登录状态,任何 token 都不得进入 URL。完整约束见 `protocol.md` §8.3。
|
||||
- 邀请码由已注册用户在 `/api/v1/auth/invite-code` 生成(每月限量),一次性使用,
|
||||
不能由创建者本人使用;被使用后记录 `invitee_account` 与 `used_at`。
|
||||
- 可选 `DSH_INVITE_CODE`(站点通用邀请码):`register_account` 优先匹配该配置值
|
||||
(大小写/空格归一后比较),命中即放行注册——不生成 `invite_codes` 行、不记录
|
||||
inviter/invitee、可重复使用;其余码仍走一次性邀请码校验。
|
||||
|
||||
## 15b. Admin(白名单,无独立入口)
|
||||
|
||||
- Admin 无密码登录/独立会话。账号命中 `DSH_ADMIN_EMAILS`(邮箱精确匹配)或
|
||||
`DSH_ADMIN_ZHIHU_OPEN_IDS`(该账号绑定的知乎 open_id 命中)即为管理员。
|
||||
- 判定函数 `account_service.is_admin_account()`;Admin API 统一依赖
|
||||
`web_bearer` + `admin_account`(非白名单 → 403 `AUTH_INVALID`)。
|
||||
- 前端:站点管理并入 `/app` 用户区(`AppArea`:远程访问 + 工作电脑 + 站点管理 标签页),
|
||||
标签页仅对 `isAdmin` 为真的账号渲染;`/me` 返回 `isAdmin` 供前端判断;
|
||||
非管理员直接访问 `/app/admin`(或旧 `/admin`)显示 403 页。导航栏无 Admin 入口。
|
||||
- `admin_sessions` 表与 `ADMIN_PASSWORD_HASH` 已废弃移除;CSRF 双提交不再需要
|
||||
(Admin API 只接受 Bearer web 令牌)。
|
||||
|
||||
## 16. SQLite 与迁移
|
||||
|
||||
- SQLAlchemy 2 typed models。
|
||||
- Alembic 管理所有 schema 变更。
|
||||
- 开启 foreign keys、WAL 和 busy timeout。
|
||||
- 事务完成设备注册、账号授权边同步和 token 签发。
|
||||
- 清理任务只删除过期临时 Host code/token,不删除审计所需的 revoke 事实。
|
||||
- 单进程/少量 worker 是 SQLite MVP 的部署边界;扩展到多实例前迁移 Postgres 和外部 presence store。
|
||||
|
||||
## 17. 日志与指标
|
||||
|
||||
允许记录:requestId、connectionId、截断 deviceId、route、status、transport、duration、bytes、error code、状态迁移。
|
||||
|
||||
禁止记录:Authorization、Cookie、refresh token、主机匹配码明文、private/shared key、TURN secret、E2EE payload、prompt、source code、workspace、tool output。
|
||||
|
||||
MVP 指标:
|
||||
|
||||
- active Host/Client connections
|
||||
- Host 接入成功/失败/过期/限速
|
||||
- P2P/TURN/Relay 比例
|
||||
- connection establishment time
|
||||
- reconnect/disconnect count
|
||||
- relay bytes 和 slow consumer
|
||||
- DB/TURN readiness
|
||||
|
||||
## 18. 安全控制
|
||||
|
||||
- REST 使用严格 Pydantic schema;未知字段按 endpoint 风险决定拒绝。
|
||||
- Host code、login、refresh、register、WebSocket hello 独立限速。
|
||||
- 所有设备查询从 token subject 的 membership 反查,防止 IDOR。
|
||||
- Admin 无 cookie/密码会话:仅白名单账号(email / 知乎 open_id)经 web Bearer
|
||||
令牌访问,普通与设备令牌一律拒绝(401/403)。
|
||||
- WebSocket 浏览器 Origin 只允许 `REMOTE_PUBLIC_URL`。
|
||||
- Static 站点启用严格 CSP、HSTS、`X-Content-Type-Options` 和 frame 限制。
|
||||
- Token hash 存储、refresh rotation 和 reuse detection。
|
||||
- Device revoke 同时撤销 token、membership 和现有连接。
|
||||
- Server 不具有 E2EE identity private key,无法伪造可信 Client。
|
||||
|
||||
## 19. Admin 功能
|
||||
|
||||
Admin 页面并入同一 React 站点的 `/app` 用户区(`/app/admin`,兼容旧 `/admin`),
|
||||
导航栏没有独立 Admin 入口;白名单管理员在用户区多一个「站点管理」标签页,
|
||||
`/api/v1/admin/*` 统一依赖 `web_bearer` + `admin_account`(server.md §15b)。
|
||||
|
||||
MVP 页面:Health、Devices、Connections、Settings。Settings 对环境变量驱动字段只读并脱敏。Admin 能撤销设备,但不能查看 Remote 会话内容。
|
||||
|
||||
## 20. 核心测试策略
|
||||
|
||||
只覆盖 Server 核心安全和状态行为:
|
||||
|
||||
- 账号授权边自动建立、跨账号拒绝与 IDOR
|
||||
- Host 匹配码 expire/single-use/rate-limit
|
||||
- token rotation/reuse/revoke
|
||||
- WebSocket hello auth、origin、replacement
|
||||
- signaling target authorization
|
||||
- relay membership、frame limit、backpressure
|
||||
- device revoke 后实时断连
|
||||
- Admin/Remote auth 隔离
|
||||
- 数据模型和日志不接收业务明文
|
||||
|
||||
静态页面托管、Admin 普通筛选、视觉样式、状态标签和非关键 doctor 展示不单独写测试。
|
||||
|
||||
## 21. 部署
|
||||
|
||||
标准 Compose:
|
||||
|
||||
```text
|
||||
remote-server
|
||||
- FastAPI
|
||||
- React dist
|
||||
- /data/remote.db
|
||||
|
||||
coturn
|
||||
- shared TURN secret
|
||||
|
||||
caddy/nginx(可选)
|
||||
- TLS
|
||||
- HTTPS/WSS reverse proxy
|
||||
```
|
||||
|
||||
对外只有一个站点 URL;TURN 另开放其协议所需端口。备份 `/data/remote.db` 与 Server secret,绝不备份客户端/Host private key(它们不应存在于 Server)。
|
||||
|
||||
## 22. 实现顺序
|
||||
|
||||
1. 配置、数据库、迁移和统一站点静态路由。
|
||||
2. 账号登录、设备注册、token 与 Host 匹配码。
|
||||
3. 同账号 membership 自动同步与设备查询授权。
|
||||
4. WebSocket hello 和 ConnectionHub。
|
||||
5. signaling 与 opaque Relay。
|
||||
6. Admin health/devices/connections/settings。
|
||||
7. rate limit、revoke、backpressure 和日志脱敏。
|
||||
8. TURN credential 和 Docker Compose。
|
||||
9. 根据 [protocol.md](protocol.md) 完成互操作验收。
|
||||
|
||||
|
||||
## WebRTC control recovery
|
||||
|
||||
Optional `transport.webrtc.resume.v1` preserves authenticated LAN/P2P/TURN
|
||||
DataChannels across a temporary control outage using a two-sided, five-minute
|
||||
authorization lease. See [the contract and rollout limits](design/webrtc-control-recovery.md).
|
||||
This is separate from WebSocket Relay and TURN credential TTL; the relay-only
|
||||
self-hosted Server does not enable it. Production/native acceptance is not implied.
|
||||
- 生产 REST/Control 使用 HTTPS/WSS;开发与自托管 HTTP 例外必须符合客户端显式策略。
|
||||
- 浏览器 Origin、令牌 subject、角色、membership 和连接状态独立校验;服务端授权不能替代端到端身份固定。
|
||||
- 不保存或记录 Prompt、会话、工作区路径、源码、工具输出、Relay ciphertext、设备私钥或临时票据。
|
||||
- 可记录脱敏设备/连接 ID、错误码、状态、时长和聚合流量;不得把授权 header、Cookie 或完整敏感请求体写入日志。
|
||||
- refresh 轮换与直接后继恢复必须原子持久化,保留原过期时间;过时 token 不能撤销当前有效 pair。
|
||||
- 设备/关系撤销更新持久状态并终止相关活动连接;不影响其他授权设备。
|
||||
- Admin 只管理账号、设备、连接和部署元数据,不获得会话解密能力。完整站点的 Admin 鉴权与路由在其所属仓库维护。
|
||||
- TLS 反向代理需支持 WebSocket upgrade;API/WS 先于 SPA fallback,未知 API 返回 JSON 错误。健康检查不暴露凭据或敏感配置。
|
||||
- 备份持久设备状态及本 Server 所需 secret;不要把 Host/Client 私钥复制到 Server。恢复、迁移和多实例部署遵循对应 runtime 的运维指南。
|
||||
|
|
|
|||
Loading…
Reference in New Issue