380 lines
18 KiB
Markdown
380 lines
18 KiB
Markdown
# DeepSeek Harness 远程同步服务端 — 架构方案
|
||
|
||
> 目标：为团队私有使用的 DeepSeek Harness 提供 **账号设置、团队配置、插件内容** 的远程同步。
|
||
> 规模假设：2–50 人团队，单机部署即可，不追求高可用。
|
||
|
||
---
|
||
|
||
## 0. 落地后的代码结构（2026-09-10 重构）
|
||
|
||
方案本身不变，`main.py` 曾是 530 行单体，按资源拆成了包：
|
||
|
||
```
|
||
server/dsh_sync/
|
||
├── main.py # 仅组装：配置 + 中间件 + include_router（~55 行）
|
||
├── config.py # 环境变量 → Config
|
||
├── db.py # SCHEMA + connect/init_db/reset_schema/record_audit
|
||
├── auth.py # token 签发、请求鉴权、Ctx
|
||
├── deps.py # FastAPI 依赖（get_cfg / get_ctx）
|
||
├── storage.py # 制品与 APK 的路径解析（相对 data_dir）
|
||
├── ratelimit.py # 滑动窗口限流（单进程内存态）
|
||
├── connect.py # 内网地址探测
|
||
├── routers/
|
||
│ ├── pages.py # /app /apk /sw.js /manifest /icon + APK 分发
|
||
│ ├── connect.py # /v1/connect/{info,qr}
|
||
│ ├── tokens.py # /v1/tokens*
|
||
│ ├── users.py # /v1/users /v1/me
|
||
│ ├── settings.py # /v1/settings*
|
||
│ ├── plugins.py # /v1/plugins*
|
||
│ └── audit.py # /v1/audit
|
||
└── static/ # mobile.html（PWA）、apk.html（安装页）、sw.js、图标
|
||
```
|
||
|
||
Android 客户端在 `android/`，产物 `data/dist/dsh-sync.apk`，见 §12。
|
||
|
||
---
|
||
|
||
## 1. 可行性评估
|
||
|
||
**结论：完全可行，建议做，但要做"小"。**
|
||
|
||
| 维度 | 评估 |
|
||
|---|---|
|
||
| 技术难度 | 低。本质是「带版本号的 KV 存储 + 带校验和的文件分发」，没有实时协同、没有海量并发 |
|
||
| 成本 | 一台 1C1G VPS 或一台内网机器 + Docker Compose 即可运行 |
|
||
| 主要风险 | ① 同步敏感信息（API Key）的安全设计；② 插件与 harness 版本的兼容管理；③ 离线时的客户端行为。三者都有成熟解法，见 §5–§7 |
|
||
| 不建议的方向 | 不要做成实时双向同步/CRDT（团队场景不存在并发编辑冲突的真实需求），不要上微服务/消息队列 |
|
||
|
||
一句话定位：**这不是"云盘"，而是一个"带权限和版本的配置/插件仓库"，客户端以拉取为主、带本地缓存。**
|
||
|
||
---
|
||
|
||
## 2. 总体架构
|
||
|
||
```
|
||
┌──────────────────────────────────────┐
|
||
│ 同步服务端（单机） │
|
||
│ │
|
||
┌──────────┐ HTTPS │ ┌─────────┐ ┌──────────────────┐ │
|
||
│ 团队成员 │──────────┼─▶│ Caddy │──▶│ 同步 API 服务 │ │
|
||
│ 的 dsh │ Token │ │ (TLS) │ │ (FastAPI/Node) │ │
|
||
└──────────┘ │ └─────────┘ └───────┬──────────┘ │
|
||
│ │ │
|
||
│ ┌─────────┴──────────┐ │
|
||
│ │ │ │
|
||
│ ┌─────▼─────┐ ┌───────▼──────┐
|
||
│ │ PostgreSQL │ │ 磁盘目录 │
|
||
│ │ 用户/设置/ │ │ 插件制品文件 │
|
||
│ │ 插件元数据 │ │ (带 sha256) │
|
||
│ └───────────┘ └──────────────┘
|
||
└──────────────────────────────────────┘
|
||
|
||
客户端分层配置（dsh 本地）：
|
||
内置默认 < 团队设置(缓存) < 用户设置(服务端) < 本地覆盖(不同步)
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 技术选型（及为什么）
|
||
|
||
| 方案 | 评价 |
|
||
|---|---|
|
||
| **A. 轻量自研 API（推荐）** | FastAPI + PostgreSQL + 磁盘存储，约 600–1000 行代码。完全掌控数据结构，能精确适配 harness 的设置/插件格式 |
|
||
| B. Git 仓库当同步源 | 零服务端代码，但权限粒度粗、无法区分"每用户的私有设置"、插件二进制分发体验差。可作为 MVP 的过渡方案，不适合作为终态 |
|
||
| C. 现成 SaaS（ConfigCat 等）/ Gitea + OCI registry | 引入外部依赖或运维负担，且字段模型不贴合 harness，团队私有场景下反而更复杂 |
|
||
|
||
**推荐栈**：Python FastAPI（或 Node Hono）+ PostgreSQL（psycopg 3）+ 本地磁盘 + Caddy（自动 HTTPS）+ Docker Compose。全流程无外部服务依赖；备份 = `pg_dump` + 打包插件制品目录。
|
||
|
||
---
|
||
|
||
## 4. 数据模型
|
||
|
||
```sql
|
||
-- 用户与凭证
|
||
users (id, username, role['admin'|'member'], created_at)
|
||
tokens (token_hash, user_id, name, created_at, last_used_at, revoked)
|
||
|
||
-- 设置：按 key 分条存储，团队设置只有 admin 可写
|
||
settings (scope['team'|'user'], scope_id, key, value_json,
|
||
version, updated_by, updated_at,
|
||
PRIMARY KEY(scope, scope_id, key))
|
||
|
||
-- 插件：不可变版本，发布后不修改（只能删或发新版本）
|
||
plugins (id, name, description, latest_version, updated_at)
|
||
plugin_versions (plugin_id, version, channel['stable'|'beta'],
|
||
sha256, size_bytes, manifest_json,
|
||
min_harness_version, artifact_path, published_by, published_at)
|
||
```
|
||
|
||
要点：
|
||
- **设置按 key 分条**而非整包 JSON，是为了做细粒度的乐观并发控制（见 §6）。
|
||
- **插件版本不可变** + sha256，客户端可放心缓存和校验。
|
||
- `min_harness_version` 解决"插件比客户端新"的兼容问题。
|
||
- 数据库为独立 PostgreSQL 实例（compose 内置 postgres:16 服务），便于备份、升级与后续扩容。
|
||
|
||
---
|
||
|
||
## 5. API 设计
|
||
|
||
所有请求走 `Authorization: Bearer <token>`。
|
||
|
||
```
|
||
GET /healthz # 无需认证，部署探活
|
||
|
||
POST /v1/tokens # 用邀请码/初始密码换长期 token
|
||
GET /v1/me # 校验 token，返回身份和角色
|
||
|
||
GET /v1/settings # 合并视图：team ∪ user（user 优先），
|
||
# 响应带整体 ETag 和各 key 的 version
|
||
PUT /v1/settings/user/{key} # 写自己的设置
|
||
# body: {value, base_version}
|
||
# 版本不符 → 409 Conflict
|
||
PUT /v1/settings/team/{key} # 仅 admin
|
||
|
||
GET /v1/plugins?harness_version=x.y # 列出插件及最新版本（按渠道过滤）
|
||
GET /v1/plugins/{id}/{version} # 插件清单（manifest + sha256 + 大小）
|
||
GET /v1/plugins/{id}/{version}/download # 制品文件（支持 Range/断点续传）
|
||
POST /v1/plugins/{id} # 仅 admin，multipart 上传 tar.gz + manifest
|
||
DELETE /v1/plugins/{id}/{version} # 仅 admin
|
||
GET /v1/audit?since=... # 变更审计日志（可选）
|
||
```
|
||
|
||
### 插件制品格式
|
||
|
||
```
|
||
plugin-{id}-{version}.tar.gz
|
||
├── manifest.json # {id, version, min_harness_version, entry, files[], channel}
|
||
└── files/... # 插件实际内容（skills / commands / hooks 等）
|
||
```
|
||
|
||
服务端上传时校验 manifest 与目录一致性，计算 sha256 入库。
|
||
|
||
---
|
||
|
||
## 6. 同步协议设计（核心）
|
||
|
||
**模式：拉取为主 + 乐观并发写。** 团队场景写入频率极低，无需实时推送。
|
||
|
||
### 客户端启动流程
|
||
```
|
||
1. 读本地缓存（上次同步快照 + 各 key version）
|
||
2. GET /v1/settings（带 If-None-Match）→ 304 则直接用缓存
|
||
3. 合并到生效配置：defaults < team < user < local_overrides
|
||
4. 若开启了自动同步插件：比对已装插件 sha256 → 增量下载 → 校验 → 原子安装
|
||
5. 服务器不可达 → 使用缓存并标记 stale（在 UI/日志里提示"配置可能过期"）
|
||
```
|
||
|
||
### 写冲突规则
|
||
- 每个 key 有单调递增 `version`。客户端提交 `base_version`，不匹配返回 409。
|
||
- 409 时客户端拉取最新值，**默认提示用户**（不静默覆盖）——团队设置尤其如此。
|
||
- 团队设置仅 admin 可写，天然把冲突面缩到最小。
|
||
|
||
### 插件分发规则
|
||
- 版本不可变；客户端按 sha256 决定是否需要下载（本地已有同校验和则跳过）。
|
||
- 安装 = 解压到临时目录 → 校验 sha256 与 manifest → 原子替换插件目录（rename）。
|
||
- `channel: stable/beta`，客户端配置里选择跟随哪个渠道。
|
||
|
||
---
|
||
|
||
## 7. 安全设计（重点：API Key 怎么办）
|
||
|
||
**强烈建议：不同步明文 API Key。** 推荐分层策略：
|
||
|
||
| 数据 | 策略 |
|
||
|---|---|
|
||
| 每人自己的 DeepSeek API Key | **只存本地**（系统 keychain / 环境变量 / 本地配置文件 600 权限），永不入服务端 |
|
||
| 团队级供应商配置（base_url、可用模型列表、默认参数、代理地址）| 同步，admin 维护 |
|
||
| 其余偏好设置（主题、权限策略、快捷键等）| 同步，无敏感信息 |
|
||
|
||
如果团队确实有"统一管理 DeepSeek Key"的诉求，正确做法是走**网关代理**：团队部署一个轻量 LLM 网关（如 one-api / LiteLLM），harness 里只配置网关地址 + 网关发的个人 token，真实 Key 只在网关侧。这比把 Key 放进同步服务端安全得多，还附带用量统计。
|
||
|
||
其他安全基线：
|
||
- Token 只存哈希（服务端）；Token 可撤销、可命名、记录 last_used。
|
||
- 全程 HTTPS（Caddy 自动证书；纯内网部署可自签或 Tailscale 内网直达）。
|
||
- 插件上传仅限 admin；下载制品时客户端**必须校验 sha256**（防传输损坏与服务端被篡改的纵深防御）。
|
||
- 上传大小上限（如 20MB）+ 解压路径校验（防 zip-slip）。
|
||
- 审计日志记录所有 team 设置变更和插件发布。
|
||
|
||
---
|
||
|
||
## 8. 部署方案
|
||
|
||
```yaml
|
||
# docker-compose.yml（示意，实际文件已含 postgres 服务与健康检查）
|
||
services:
|
||
postgres:
|
||
image: postgres:16-alpine
|
||
volumes:
|
||
- pg_data:/var/lib/postgresql/data
|
||
dsh-sync:
|
||
build: .
|
||
depends_on:
|
||
postgres: { condition: service_healthy }
|
||
environment:
|
||
- DSH_DATABASE_URL=postgresql://dsh:${POSTGRES_PASSWORD}@postgres:5432/dsh
|
||
- DSH_BOOTSTRAP_ADMIN_TOKEN=... # 首次启动生成 admin token
|
||
volumes:
|
||
- ./data:/data # 插件制品
|
||
caddy:
|
||
image: caddy:2
|
||
ports: ["443:443"]
|
||
```
|
||
|
||
- **网络隔离（满足"只为团队使用"）**：首选部署在内网/Tailscale 网络内，不暴露公网；若必须公网，Caddy + HTTPS + token 已足够，因为攻击面只有这几个 API。
|
||
- **备份**：`pg_dump -U dsh dsh` + 打包 `data/plugins/`，cron 每日一次。
|
||
- **资源**：1C/1G VPS 足够支撑百人以下团队（PG 与应用同机）。
|
||
|
||
---
|
||
|
||
## 9. 客户端集成（dsh 侧需要做什么）
|
||
|
||
新增一个 `sync` 模块，约几百行：
|
||
|
||
```
|
||
配置层叠：defaults < team(缓存) < user(缓存) < local(本地覆盖，永不上传)
|
||
|
||
dsh sync login # 一次性：输入服务端地址 + 邀请码 → 存 token
|
||
dsh sync pull # 手动拉取（默认启动时自动做）
|
||
dsh sync push # 把本地"用户设置"的改动推上去
|
||
dsh sync status # 显示同步状态、落后版本、stale 标记
|
||
dsh plugin install/update # 走服务端分发，带 sha256 校验
|
||
```
|
||
|
||
本地状态目录（如 `~/.dsh/`）：
|
||
```
|
||
~/.dsh/
|
||
├── config.local.toml # 本地覆盖 + 服务端地址 + token（600 权限）
|
||
├── sync-cache.json # 上次同步快照：各 key version + 插件 sha256 清单
|
||
└── plugins/ # 原子安装的插件目录
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 实施里程碑
|
||
|
||
| 阶段 | 内容 | 工作量 |
|
||
|---|---|---|
|
||
| M1 | API 骨架 + token 认证 + team/user 设置读写（含 409 冲突） | 0.5–1 天 |
|
||
| M2 | 插件发布/分发（上传、sha256、清单、下载） | 0.5 天 |
|
||
| M3 | 客户端 `sync` 模块 + 分层配置合并 + 离线缓存 | 1–1.5 天 |
|
||
| M4 | Docker Compose 部署 + Caddy + 备份脚本 + 审计日志 | 0.5 天 |
|
||
| 合计 | 可用的 MVP | **约 2.5–4 天** |
|
||
|
||
M2 之后即可让团队试用"团队设置 + 插件分发"两条最有价值的主线；用户级设置的 push 可以放最后。
|
||
|
||
---
|
||
|
||
## 11. 明确不做的事（防止过度设计）
|
||
|
||
- ❌ 实时推送/WebSocket —— 拉取 + 启动时同步足够
|
||
- ❌ CRDT/双向合并 —— key 级 last-writer-wins + 409 提示已覆盖真实场景
|
||
- ❌ 多租户、计费、注册开放 —— 团队内部，admin 手工管理成员
|
||
- ❌ 同步明文 API Key —— 见 §7，走本地存储或 LLM 网关
|
||
- ❌ 会话/对话历史同步 —— 属于另一类数据（大、私有、价值存疑），一期不做
|
||
|
||
---
|
||
|
||
## 12. 安卓客户端与 APK 分发
|
||
|
||
### 12.1 为什么是 WebView 壳，而不是原生重写
|
||
|
||
移动端 UI 只有一份实现：`static/mobile.html`。原生 App 若是重写一套，就会长期存在
|
||
"设置页改了、App 没改"的漂移。壳方案下 App 打开即是服务端当前版本，改前端不用重新发版。
|
||
|
||
壳比手机浏览器多提供三件事，这也是它存在的全部理由：
|
||
|
||
| 能力 | 浏览器 | App |
|
||
|---|---|---|
|
||
| 记住服务端地址 | 每次输 IP（或靠书签） | 首启填一次，之后直进 |
|
||
| 发布插件 tar.gz | 手机端文件选择器不认 tar.gz | `onShowFileChooser` 原生选择器 |
|
||
| 扫二维码 | 只能跳浏览器 | 认领 `/app#invite=` 深链，直进 App 并预填邀请码 |
|
||
|
||
### 12.2 构建
|
||
|
||
```bash
|
||
bash android/build.sh
|
||
```
|
||
|
||
工具链：JDK 17 + Android SDK（build-tools 34 / platform 34）+ Gradle 8.7。
|
||
脚本默认从 `~/Desktop/android-tools` 找，可用 `ANDROID_TOOLS` / `GRADLE_BIN` 覆盖。
|
||
|
||
产物写入 `data/dist/dsh-sync.apk` + 同名 `.json` 元数据（版本、sha256、大小、构建时间）。
|
||
签名密钥 `android/app/dsh-release.jks` 首次构建自动生成（口令 `dshsync`）——
|
||
固定密钥的意义只是让后续版本能覆盖安装；这个包走内网分发，不进任何商店。
|
||
|
||
### 12.3 分发页面
|
||
|
||
`GET /apk` 是**免登录**的独立页面（和 `/app` 一样）：
|
||
|
||
| 端点 | 说明 |
|
||
|---|---|
|
||
| `GET /apk` | 安装页：下载按钮、版本/大小/sha256、安装步骤、下载页二维码 |
|
||
| `GET /apk/info` | 构建元数据；未构建时返回 `{"available": false, "build_hint": ...}` |
|
||
| `GET /apk/dsh-sync.apk` | 制品本体，未构建则 404（不是 500） |
|
||
| `GET /apk/qr?host=` | 指向 `/apk` 的二维码，手机扫码直接到安装页 |
|
||
|
||
页面在 APK 不存在时不会给死链：按钮变成"服务端尚未构建 APK"并显示构建命令。
|
||
|
||
### 12.4 安装路径
|
||
|
||
`/app` 登录页底部有"🤖 装安卓 App"入口。团队新人的最短路径是：
|
||
**扫码进 `/apk` → 下载安装 → 首启填服务器地址**，或直接扫设置页的连接二维码
|
||
（深链 `http://<ip>:8020/app#invite=<码>`）一步预填邀请码。
|
||
|
||
### 12.5 在 MuMu 模拟器里实测（2026-09-11）
|
||
|
||
`android/emulator.sh` 把整套驱动封起来了，MuMu 的两个特性是它存在的理由：
|
||
|
||
```bash
|
||
bash android/emulator.sh start # 启动 VM、等 adb、清残留代理
|
||
bash android/emulator.sh install # 构建 + 安装 + 启动
|
||
bash android/emulator.sh deeplink "http://192.168.5.2:8020/app#invite=<码>"
|
||
bash android/emulator.sh tap X Y # 坐标是 App 的 1080x1920 坐标系
|
||
bash android/emulator.sh ui # 直接 dump 页面文字（不需要截图）
|
||
bash android/emulator.sh status
|
||
```
|
||
|
||
**坑 1：每个 App 有独立的虚拟 display，且 id 每次开机都变。**
|
||
一次会话里见过 0 → 3 → 6 → 8 → 11。`adb shell input tap` 不带 `-d` 时默认打到
|
||
display 0（桌面），表现是"App 明明在屏幕上，点了没反应"。
|
||
`emulator.sh` 每次都从 `dumpsys window` 里按包名解析当前 display。
|
||
|
||
**坑 2：`screencap` 抓不了 App 的 display**，对 MuMu 的应用 display 直接返回
|
||
`Status: -2`。截图只能走宿主窗口（CUA）或 `screencap -a`，因此 `ui` 子命令用
|
||
uiautomator dump 读文本，比截图可靠。
|
||
|
||
**坑 3（最容易误判成 App bug）：模拟器里可能残留 HTTP 代理。**
|
||
本次实测时系统里配着 `http_proxy=127.0.0.1:8080` 而该端口无人监听 → WebView 全部
|
||
请求死在代理上，页面全黑。**但 `ping` 和 `nc` 是通的**（它们不走系统代理），
|
||
所以网络看起来完全正常。`start` 子命令会主动清掉这三个设置项。
|
||
|
||
模拟器实测通过的链路：
|
||
|
||
| 步骤 | 结果 |
|
||
|---|---|
|
||
| 安装 + 冷启动 | 无崩溃，WebView 110.0.5481.154 |
|
||
| 深链 `#invite=` | 地址/模式/邀请码三项自动预填 |
|
||
| 邀请码注册（member） | `POST /v1/tokens` → 主界面，无管理 Tab、无扫码卡片 |
|
||
| Token 登录（admin） | `admin · admin`，「📱 连接手机」卡片与🛡管理 Tab 出现 |
|
||
| 扫码卡片展开 | `GET /v1/connect/{info,qr}` 200，二维码真实渲染（1352px 高） |
|
||
| 设置/插件/我的 Tab | 插件列表含 sha256、下载链接；Token 列表可撤销 |
|
||
| `/apk` 页下载 | 文件落盘 `/sdcard/Download/dsh-sync.apk`，sha256 与服务端一致 |
|
||
|
||
### 12.6 已知边界
|
||
|
||
- 明文 HTTP：`usesCleartextTraffic="true"`，因为内网部署就是 HTTP。若对外暴露必须上 HTTPS。
|
||
- 自签名包：Android 会拦一次"未知来源"，安装步骤里写明了怎么放行。
|
||
- 深链匹配：intent-filter 只能匹配 scheme/host/path（Android 不匹配 fragment），
|
||
所以 `#invite=` 由 `MainActivity` 从原始 intent data 里读，不靠 pathPattern；
|
||
另外 Android 只把**带 host 的** http URL 交给浏览器候选，无 host 的深链必须
|
||
用显式 component 启动（`emulator.sh deeplink` 就是这么做的）。
|
||
- 未做：推送、离线缓存、原生手势返回（返回键已接 WebView history）。
|
||
|
||
### 12.7 实测中发现并修掉的两个 App 缺陷
|
||
|
||
1. **`/apk` 深链打不开安装页**：`navigate()` 无论输入什么路径都强制拼 `/app`。
|
||
改为保留调用方给的 path，且只在 `/app` 上附 `#invite=` fragment。
|
||
2. **App 内点"下载 APK"没反应**：WebView 字节拿到了（服务端 200）但没有
|
||
`DownloadListener`，没人把数据写盘。已接系统 `DownloadManager`，
|
||
并在 `/apk` 页对 `DshSyncApp/` UA 显示"你正在用 dsh App"提示卡。
|