# dsh-remote-link **Repository Path**: bamboo-qiqing/dsh-remote-link ## Basic Information - **Project Name**: dsh-remote-link - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-20 - **Last Updated**: 2026-11-15 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # dsh-remote-link **把任何一台机器上的 DeepSeek Harness 搬到手边。** 浏览器、手机、平板都能直接操作, 设备端不需要开放任何端口,也不依赖任何应用商店或云服务。 > 自用项目:一个中继 + 每台设备一个 agent + 桌面一个 DSH 插件。 --- ## 为什么是它 - **设备零入站端口**:agent 主动向外拨 WebSocket,NAT、容器、公司网络都能用。 - **不是投屏,是那台设备自己的 DSH**:切换设备 = 整页加载目标机器的 DSH,侧栏、会话、主题都是它自己的。 - **远端页面功能完整**:同源代理 + 启动引导,API、WebSocket、文件浏览与终端都走真实链路。 - **切换是秒级**:跨设备共享资源缓存(内存 + 磁盘)、页面缓存、本机直连,一次冷载之后基本秒开。 - **多开**:一个窗口看一台设备,不用来回切。 - **全局活动看板**:任何设备、手机上都能看到所有设备的会话"进行中 / 已完成",完成时推送通知。 - **在线升级**:网页端打开即最新;安卓薄壳内置 APK 更新,不经过商店。 --- ## 架构 ``` 手机 PWA / 安卓薄壳 ─┐ ├── HTTPS / WSS ──▶ 中继(Spring Boot) 桌面 DSH + 插件 ─────┘ │ │ 设备主动外拨的 WebSocket ▼ 设备 Agent(Node) │ HTTP ▼ 设备上的 DSH Web ``` - **中继**:账号、设备注册、隧道代理、会话活动总线、Web Push、备份。 - **Agent**:每台设备一个,外拨长连接,把字节搬进搬出;本机 agent 由插件托管。 - **插件**:活在本机 DSH 里,负责设备切换界面、`/remote//` 同源代理、共享缓存、多开窗口。 - **PWA / 安卓壳**:手机入口;壳只提供前台连接和 APK 更新,界面仍然是网页。 --- ## 快速开始 ### 1. 启动中继 ```bash cd server mvn package -DskipTests cd .. DSHLINK_DB=./.run/relay-dev/dshlink.db \ java -jar server/target/dsh-remote-link-server-1.0.0.jar ``` 打开 `http://127.0.0.1:8420/`,注册一个账号。 > 想让手机在外面访问,就把 8420 暴露成 HTTPS(nginx + 证书,或 cloudflared 隧道)。 > 生产部署见下面的 [部署](#部署)。 ### 2. 装桌面插件 ```bash # 发布版(npm) dsh plugin --profile desktop add "dsh-remote-link@latest" # 或者本地开发版 dsh plugin --profile desktop add "file:$PWD/plugin" ``` 升级用同一条命令把 `@latest` 换成新版本(或继续用 `@latest`),然后重启 DSH: ```bash dsh plugin --profile desktop add "dsh-remote-link@latest" ``` 重启 DSH,侧栏底部会出现 **远程访问**: 1. 点开 → **登录中继**,填中继地址、账号和密码; 2. 登录成功后隧道自动连上,这台电脑就出现在中继的设备列表里; 3. 和登录网站一样,账号页显示当前账号与连接状态,**退出**即可下线。 ### 3. 手机打开 用手机浏览器打开中继地址 → **添加到主屏幕**。之后就是全屏 App 的体验; 在设置里打开通知,会话完成时会收到系统推送。 --- ## 手机安装 ### 网页版(PWA,推荐先用这个) 手机浏览器打开中继地址 → 菜单「添加到主屏幕」。没有安装包,更新在打开时自动完成。 ### 安卓 APK(自用,不上架) `android/` 是一个很薄的 WebView 壳,界面仍然来自中继,壳只补两件事: **前台常驻的会话通知** 和 **内置 APK 更新**。 ```bash cd android gradle wrapper --gradle-version 8.7 # 首次 ./gradlew assembleRelease # 需要 Android SDK 34 # 产物:android/app/build/outputs/apk/release/app-release.apk ``` 发布有两种方式,选一种即可(**以下命令在仓库根目录执行**): ```bash APK=android/app/build/outputs/apk/release/app-release.apk # A. 中继自己托管(局域网/隧道可用时) node deploy/publish-android.mjs "$APK" 1.0.0 1 # B. Gitee 托管(国内下载快,推荐) cd deploy && npm install GITEE_TOKEN=*** GITEE_OWNER=你 GITEE_REPO=仓库 GITEE_DIR=release/android \ node publish-gitee.mjs "../$APK" 1.0.0 1 v1.0.0 "首个版本" ``` - **A**:打开 `http://<中继>/app`,页面上有二维码,手机扫码即下载; 用本机地址打开时会自动换成局域网地址。 - **B**:产物写到仓库的 `release/android/`(二维码、更新清单、版本记录); 在 Gitee 上浏览该目录就是扫码下载页,「发行版」标签页是版本历史。 装好之后 App 自己检查更新;第一次安装需要允许「安装未知应用」。 把发布脚本打印的 `manifest` 地址填进 `android/app/build.gradle.kts` 的 `UPDATE_MANIFEST`, 更新就完全走你的仓库。 --- ## 日常使用 三端看到的是同一个界面,只是外壳不同: | 打开方式 | 看到什么 | |---|---| | 桌面 DSH | 本机 DSH + 侧栏「远程访问」(含「本机」一项) | | 浏览器打开中继 | 直接是最近活跃设备的 DSH,顶部一条中继细栏(设备名 + 「设备」返回列表),另有同一个「远程访问」菜单(没有「本机」) | | 中继上还没有设备 | 一张「这个账号还没有设备」的空态页,说明在电脑端登录同一个账号 | | 安卓 APK | 同浏览器,额外有前台通知与内置更新(部署不带域名/HTTPS,所以手机用 APK 而不是 PWA) | | 场景 | 怎么做 | |---|---| | 切到另一台设备 | 侧栏「远程访问」→ 点设备(整页切换),或顶部中继栏「设备」回列表 | | 从设备页回设备列表 | 顶部中继栏右侧「设备」 | | 同时看多台 | 桌面端菜单里打开 **多开模式**,之后点设备会新开窗口 | | 看所有设备在跑什么 | 同一菜单里的 **会话活动**;手机在设备页底部 | | 会话完成提醒 | 桌面看板 / 手机推送(PWA 通知或安卓前台服务) | | 回到本机(仅桌面) | 菜单第一项「本机」 | | 改中继地址(APK) | 设置 → 「更改中继地址」 | 中继不跑 DSH 实例:它的页面就是把某台设备的 DSH 代理过来。因此账号、设备、隧道、 推送、更新这些控制面能力仍然只在 Java 中继里,而 UI 只有 DSH 一份。设备页顶部那条 中继细栏是唯一常驻的中继 DOM,只负责显示设备名和回到设备列表,不参与 DSH 的布局与 状态;它通过给 `body` 预留高度来避免压住 DSH 自己的标题栏。 ### 部署形态:只有 IP 和端口 这个产品**不打算有域名和 HTTPS**。中继就是 `http://:`,所以有几件事是有意这样设计的: - **手机装 APK,不用浏览器 PWA**。浏览器只在安全上下文(HTTPS 或 localhost)里提供 Service Worker 和 Web Push,纯 HTTP 下两者都不存在:装不到桌面、也收不到浏览器推送。 这些代码都有特性判断,不会报错,只是不生效。 - **通知走安卓壳自己的前台服务**:它轮询中继的活动接口,会话完成时发本地通知, 不依赖 Web Push。 - **中继地址可以改**:IP 会变(换机器、换线路),所以设置页里有一个「更改中继地址」 (只在 APK 里出现),不用清数据。输入框不写协议时默认补 `http://`。 - **安装包内置了当前地址**,第一次打开不用手输。 ### 手机上的三个细节 - **旧 WebView 兼容**:DSH 客户端用了 `AbortSignal.any`、`Promise.withResolvers` 这些较新的 API。WebView 低于 116/119 时(很多手机不更新 WebView),中继注入的 启动 shim 会补上这两个函数——否则客户端每条连接都会立刻中止并无限重连。 - **加载骨架**:设备页的脚本有好几 MB,首次加载要几十秒。壳在页面一开始加载时就 盖上「正在加载设备界面…」加计时,DSH 真正挂载后自动撤掉,避免白屏看起来像卡死。 - **接口来源**:设备页里的 `dshlink-api` 由中继回答(账号下的设备、会话活动), 而不是被代理到设备自己的本机 agent。 ### 性能 - 中继缓存设备资源:`/assets/` 和带 `rev=` 的 `plugins/` 请求按内容寻址缓存到磁盘 (默认 512MB,LRU),第一次过隧道、之后走本地磁盘。实测同一份 4MB 插件包 69s → 0.17s,313KB 脚本 6.8s → 24ms。 - 缓存命中时中继回 `Cache-Control: immutable`,浏览器自己也会缓存,第二次打开 连中继都不用问。 - 设备页面本身不缓存(中继要往里注 shim)。 - 桌面端:每台设备的页面和静态资源都会缓存;同一构建的设备之间共享一份。 磁盘缓存位于 `~/.dshlink/asset-cache`(上限 96MB),重启不丢。 - 本机设备走 loopback,不经过中继和隧道。 - 中继侧目前不缓存静态资源:手机每次冷启动都要重新过隧道下载,这是下一步要补的。 --- ## 部署 **Docker Compose(推荐)** ```bash cp .env.example .env # 至少设置 DSHLINK_SESSION_SECRET docker compose up -d ``` 需要 HTTPS/域名时: ```bash docker compose --profile tls up -d --build ``` 常用环境变量: | 变量 | 说明 | |---|---| | `DSHLINK_DB` | SQLite 路径(默认 `./data/dshlink.db`) | | `DSHLINK_SESSION_SECRET` | 会话签名密钥,不设会在每次启动后失效 | | `DSHLINK_VAPID_PRIVATE_KEY` / `_PUBLIC_KEY` | 不固定则每次重启推送订阅失效 | | `DSHLINK_ADMIN_SECRET` | 保护 `POST /api/admin/backup` | | `DSHLINK_APK_DIR` | 安卓 APK 与 `version.json` 所在目录(默认 `./deploy/android`) | | `DSHLINK_ASSET_CACHE_DIR` | 设备资源缓存目录(容器内默认 `/data/asset-cache`) | | `DSHLINK_ASSET_CACHE_MB` | 缓存上限,默认 512;设 0 关闭 | 备份默认开启,落在 `DSHLINK_BACKUP_DIR`,按 `DSHLINK_BACKUP_RETAIN`(默认 14)保留。 --- ## 目录结构 ``` dsh-remote-link/ ├── server/ 中继:账号、设备、隧道、活动、推送、备份 ├── device/ 设备 Agent:注册、外拨 WS、本地代理 ├── plugin/ DSH 插件:面板、/remote 代理、共享缓存、多开 ├── mobile/public/ 手机 PWA(登录、设备列表、会话活动、推送) ├── android/ 安卓薄壳(WebView + 前台通知 + 内置更新) ├── release/android/ 手机端发布产物(扫码页、清单、版本记录) ├── deploy/ 发布脚本、Docker、TLS ├── scripts/ 验证套件与演练脚本 └── docs/ 工程笔记(历史设计、验证记录) ``` --- ## 开发与验证 ```bash scripts/verify-all.ps1 # 服务端、设备、插件、PWA、隧道、推送等套件 ``` 详细的协议、设计取舍和逐项验证记录在: - [`PROTOCOL.md`](PROTOCOL.md) — 帧协议与代理设计 - [`docs/engineering-notes.md`](docs/engineering-notes.md) — 历史工程笔记与验证明细 --- ## 安全模型 - 设备令牌 32 字节随机值,只存 SHA-256; - 账号密码 PBKDF2-HMAC-SHA256(210k 迭代),会话是 HMAC 签名 Cookie; - 设备只通过账号密码登录后加入账号,没有匿名注册、没有配对码; - 设备、活动、推送订阅都按账号隔离,跨账号查询返回 404; - DSH 启动 token 中继从不接触,由设备 agent 在本地完成交换; - 推送内容只含标题/计数/链接。 **中继是信任边界**:每个账号只能看到并操作自己名下的设备。请把它部署在 自己控制的机器上,并强制 HTTPS。 --- ## 已知限制 - iOS 未验证(Web Push / WebView 策略不同); - 安卓 APK 需要自备 Android SDK 构建;仓库只提供壳和发布流程; - 设备之间的文件互传尚未实现(活动看板已就绪,会复用同一条通道); - cloudflared quick tunnel 每次重启会换地址;长期使用建议命名隧道或自己的域名。