# 自建 LinkShell 网关 网关让手机在任何网络下都能连到你的电脑。它只做两件事:转发手机和电脑之间**端到端加密**的数据,以及在配对时让两边碰头。网关看不到你的代码和对话,也不需要多少资源。 自建网关和官方网关是同一个程序,只是没有账号:不用登录,每台手机和电脑配对一次(扫码或输入 6 位配对码)。 > 不想自己部署?iTool 会员提供官方网关:电脑上 `linkshell login`,App 里登录同一账号即可。 ## 1. 运行网关 ### 用 CLI 启动网关 ```bash npm i -g linkshell-cli # 需要 Node.js 22.13+ linkshell gateway --port 8787 --daemon linkshell gateway status tail -f ~/.linkshell/gateway.log linkshell gateway stop ``` 配对关系保存在 `~/.linkshell/relay.db`,重启网关后依然有效。 ### 用 Docker ```bash docker run -d --name linkshell-gateway --restart unless-stopped \ -p 8787:8787 -v linkshell-gateway:/data \ nickname4th/linkshell-gateway:latest ``` - 配对关系保存在 `/data/relay.db`,请挂载卷(上面的 `-v`),否则重建容器后需要重新配对。 - 镜像目前是 `linux/amd64`。在 arm64 主机上加 `--platform linux/amd64`。 - 更新:`docker pull nickname4th/linkshell-gateway:latest`,然后删掉旧容器、用同样的命令重新运行。只要卷还在,手机不用重新配对。 - 可以用 `-e` 传入的环境变量(端口、日志级别、反向代理地址、连接限流)见 [`packages/gateway/README.md`](../packages/gateway/README.md)。自建网关一般一个都不用设。 从源码构建:`git clone https://github.com/LiuTianjie/LinkShell && cd LinkShell && docker compose up -d`。 ## 2. 加上 HTTPS 在公网上请用 HTTPS 反向代理,让电脑和手机通过 `wss://` 连接。 ### Caddy(自动申请证书) ```caddyfile gw.example.com { reverse_proxy 127.0.0.1:8787 } ``` ### Nginx ```nginx server { listen 443 ssl; server_name gw.example.com; ssl_certificate /etc/letsencrypt/live/gw.example.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/gw.example.com/privkey.pem; location / { proxy_pass http://127.0.0.1:8787; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_read_timeout 86400s; proxy_send_timeout 86400s; } } ``` `Upgrade` / `Connection` 头是 WebSocket 必需的;较长的 `proxy_read_timeout` 防止空闲连接被断开。证书可以用 `certbot --nginx -d gw.example.com` 免费申请。 ### 让连接限流按用户计算 网关限制每个地址每分钟的连接次数。前面有反向代理时,网关看到的来源都是代理,所以要告诉它哪些地址是代理,它才会采信 `X-Forwarded-For`: ```bash # 用 CLI 运行,代理在同一台机器上 TRUSTED_PROXIES=127.0.0.1,::1 linkshell gateway --port 8787 --daemon # 用 Docker 运行,代理在宿主机上:容器看到的是 Docker 网桥的地址 docker run -d ... -e TRUSTED_PROXIES=172.16.0.0/12 nickname4th/linkshell-gateway:latest ``` 不设置也能用,只是限流不准:代理在本机时完全不限流,在别处时所有用户共用一份限额。细节见 [`packages/gateway/README.md`](../packages/gateway/README.md)。 ## 3. 连接电脑和手机 在电脑上: ```bash linkshell host --gateway wss://gw.example.com --daemon # 地址会被记住 linkshell pair ``` 终端里会出现二维码和 6 位配对码。在 App 的「电脑 → 添加电脑」里扫码或输入配对码。配对一次长期有效,电脑重启不需要重新配对。 - 换网关:`linkshell host stop && linkshell host --gateway wss://另一个地址 --daemon`,然后重新配对。 - 关闭网关连接:`linkshell host --gateway off`。 ### 只在家里用 网关可以直接跑在这台电脑上,不需要服务器和证书: ```bash linkshell gateway --daemon linkshell host --gateway ws://192.168.1.20:8787 --daemon # 换成电脑的局域网 IP linkshell pair ``` 手机需要和电脑在同一个局域网里。 ## 防火墙与健康检查 网关服务只需要开放其 TCP 端口(8787),或反向代理的 443: ```bash ufw allow 443/tcp # 使用 HTTPS 反代时 ufw allow 8787/tcp # 直接暴露网关时 ``` ```bash curl http://localhost:8787/healthz # {"ok":true,"version":"0.6.0","relay":2,"memoryMb":61} ``` `relay` 是当前在线的连接数(电脑加手机),`version` 是网关的版本。 ## 屏幕直连与回退 Mac 屏幕的媒体连接在 LinkShell.app 与手机/浏览器之间,另有 Node Host 与客户端之间的通用数据连接。两者使用 WebRTC,但独立协商。直连需要两端网络允许相应 ICE/STUN 流量;网关的 TCP 443 可达不代表视频 UDP 路径可达,也不需要把 Host 的回环观看端口暴露到公网。 视频按这个顺序找路:先直连(局域网、穿透 NAT),直连不通再走网关借出的 TURN 中继,视频轨道仍然连不上时,才经网关加密 RPC 接收兼容 H.264 字节流(iOS 会先试网页视频,最后为该屏幕禁用通用数据直连再走 RPC)。网关只转发密文,不承担解码/转码;TURN 只转发 DTLS-SRTP 加密的媒体包。 ### TURN 中继(可选) 网关设置了 `TURN_SECRET` 和 `TURN_URLS` 时,会给登录的电脑签发临时凭证(coturn 的 `use-auth-secret` 方案:用户名是“过期时间:电脑”,密码是它在共享密钥下的 HMAC-SHA1)。电脑登录网关时取一次,用到有效期过半再换,开屏幕时不等网关。 | 变量 | 默认 | 说明 | |---|---|---| | `TURN_SECRET` | 空 | 与 coturn 的 `static-auth-secret` 相同 | | `TURN_URLS` | 空 | 逗号分隔的 `stun:`、`turn:`、`turns:` 地址,例如 `stun:1.2.3.4:3478,turn:1.2.3.4:3478?transport=udp,turn:1.2.3.4:3478?transport=tcp` | | `TURN_TTL_SECONDS` | `28800` | 凭证有效期 | | `TURN_MAX_KBPS` | `3000` | 经中继的画面码率上限,电脑端按它限制编码 | coturn 用 `deploy/turn/` 下的 compose 文件部署(host 网络,节点要有自己的公网地址):云服务器的安全组放行 UDP 3478、TCP 3478 和 UDP 49160–49359,把 `luma.compose.yml` 的 `node` 改成这台机器,用 `luma secret set --scope linkshell-turn` 设好 `TURN_SECRET`、`TURN_PUBLIC_IP`、`TURN_PRIVATE_IP` 后 `luma compose deploy deploy/turn/luma.compose.yml`。官方网关的 coturn 在腾讯云节点 `tecent`;网关的 `TURN_SECRET`、`TURN_URLS` 和 `SUPABASE_*` 一样是 Luma 的全局密钥:网关一旦有了自己作用域的密钥,Luma 就不再给它填全局的值。配置里屏蔽了转发到私网地址,单会话限 4 Mbit/s,整机限 100 Mbit/s。 能直连时几乎不经过中继:中继候选的优先级最低,只有在直连全部失败时才会被选中;没被选中时,中继上只有少量保活包。 **流量与空闲断开。** 经 TURN 中继或经网关 RPC 回退的画面,3 分钟没有任何操作(触摸、点击、滚动、按键、缩放)会自动断开,提示“长时间没有操作,画面已断开”,不会自动换另一条路径。重新连接直接回到上次成功的那条路径。直连的画面不受这个限制。Host 上 `LINKSHELL_SCREEN_IDLE_SECONDS` 改时长(`0` 关闭),`LINKSHELL_TURN=off` 让这台电脑不用 TURN。 自建网关不设这两个变量时没有 TURN,行为和以前相同。没更新的客户端(旧版 App、旧版桌面端)连到新版电脑时也和以前一样:不用 TURN,也不会因为空闲被断开。 Host 的 `LINKSHELL_ICE_SERVERS` 设置 STUN 列表;`off` 禁用通用 DataChannel 并给屏幕会话空 STUN 列表,视频仍可尝试局域网候选。需要禁用视频轨道对照时使用 `LINKSHELL_SCREEN_VIDEO=off`。配置在 Host 上,不是 Gateway 环境变量。路径、参数和验收口径见[远程桌面架构](v2/screen-realtime.md)。 ## 数据与备份 网关保存的全部数据是一个 SQLite 文件:每台电脑、每台手机的公钥和名称,以及谁和谁配对。没有任何会话内容。用 CLI 时是 `~/.linkshell/relay.db`,Docker 里是卷中的 `/data/relay.db`。迁移服务器时带上它(连同旁边的 `-wal`、`-shm` 文件,或者先停掉网关),手机就不用重新配对。 ## 资源 网关只转发数据,资源需求取决于连接数和实际中继流量。视频和端口预览直连成功时不占画面/预览的网关带宽;兼容屏幕经 RPC 回退后会持续消耗中继带宽。手机低流量档的 900 Kbps 是 H.264 编码目标,另有封装、加密等开销;当前浏览器入口未自动选择该档。按同时观看数、路径和持续流量评估服务器与带宽,不能由单连接健康检查推定容量。 ## 从旧版本升级 网关 0.6(CLI 0.10)起只服务 2.x 的 App 和 `linkshell host`;1.x 的 App、`linkshell start` 和网页控制台不再支持。数据文件没有变:升级后沿用原来的 `relay.db`(Docker 沿用原来的卷),已配对的手机不受影响。 ## 网页客户端 同一个网关镜像在根路径提供新版网页,官方入口为 `https://gateway.itool.tech`。自托管无需 Supabase,打开自己的网关域名即可使用设备配对。账号入口由网关的公开 Supabase 配置决定。端口预览需要独立来源,可将另一个域名路由到同一容器并设置 `WEB_PREVIEW_ORIGIN=https://preview.example.net`;主网页与预览不能同源。 启用网页账号登录时,在 Supabase Authentication → URL Configuration 中追加工作台的固定 OAuth 回调:官方为 `https://gateway.itool.tech/?linkshell-auth-callback=1`,其他部署替换为自己的工作台来源。不要修改 Site URL 或删除已有网站、CLI、手机回调,也无需通配整个工作台域名。Google/GitHub 在独立窗口登录,原工作台持有 PKCE verifier 并交换回调 code;回调窗口不启动电脑连接。开发环境 `127.0.0.1` 使用已有的 `http://127.0.0.1:*/linkshell/callback` 白名单。 ## 独立 Mac App 连接自建网关 独立 App 已内置 CLI。可在设置安装可选命令入口,再按本文运行 `linkshell host --gateway wss://你的网关 --daemon` 与 `linkshell pair`。自建网关不要求官方网关的 iTool 会员。独立 App 的更新只更新本机配套运行环境,不修改远端网关容器或数据库;详见[桌面版说明](mac-desktop.md)。