@linkshell/gateway 0.5.3 → 0.6.1

package/Dockerfile

@@ -6,27 +6,18 @@ WORKDIR /app
 COPY package.json pnpm-workspace.yaml pnpm-lock.yaml ./
 # pnpm checks every patched dependency in the lockfile against its patch file.
 COPY patches/ patches/
-COPY packages/shared-protocol/package.json packages/shared-protocol/
 COPY packages/wire/package.json packages/wire/
-COPY packages/gateway-v2/package.json packages/gateway-v2/
 COPY packages/gateway/package.json packages/gateway/
-COPY apps/web-dashboard/package.json apps/web-dashboard/
 
-RUN pnpm install --frozen-lockfile --filter @linkshell/gateway --filter @linkshell/protocol --filter @linkshell/wire --filter @linkshell/gateway-v2 --filter @linkshell/web-dashboard
+RUN pnpm install --frozen-lockfile --filter @linkshell/gateway --filter @linkshell/wire
 
-COPY packages/shared-protocol/ packages/shared-protocol/
 COPY packages/wire/ packages/wire/
-COPY packages/gateway-v2/ packages/gateway-v2/
 COPY packages/gateway/ packages/gateway/
-COPY apps/web-dashboard/ apps/web-dashboard/
 COPY tsconfig.base.json ./
 
-# Libraries first (gateway + web depend on their built dist), then both apps.
-RUN pnpm --filter @linkshell/protocol build \
-  && pnpm --filter @linkshell/wire build \
-  && pnpm --filter @linkshell/gateway-v2 build \
-  && pnpm --filter @linkshell/gateway build \
-  && pnpm --filter @linkshell/web-dashboard build
+# The wire protocol first: the gateway runs against its built dist.
+RUN pnpm --filter @linkshell/wire build \
+  && pnpm --filter @linkshell/gateway build
 
 # Prune to production deps only (the app's patches don't apply to the gateway).
 RUN pnpm --filter @linkshell/gateway deploy --legacy --prod --config.allow-unused-patches=true /app/pruned
@@ -36,7 +27,7 @@ RUN pnpm --filter @linkshell/gateway deploy --legacy --prod --config.allow-unuse
 FROM node:22-alpine
 
 LABEL org.opencontainers.image.source="https://github.com/LiuTianjie/LinkShell"
-LABEL org.opencontainers.image.description="LinkShell Gateway — WebSocket relay for remote terminal sessions"
+LABEL org.opencontainers.image.description="LinkShell Gateway — relays end-to-end encrypted frames between computers and phones, and brokers pairing"
 
 RUN addgroup -S linkshell && adduser -S linkshell -G linkshell
 
@@ -44,27 +35,22 @@ WORKDIR /app
 
 # Copy pruned production node_modules + built dist
 COPY --from=builder /app/pruned/node_modules node_modules/
-COPY --from=builder /app/packages/shared-protocol/dist packages/shared-protocol/dist/
-COPY --from=builder /app/packages/shared-protocol/package.json packages/shared-protocol/
 COPY --from=builder /app/packages/gateway/dist packages/gateway/dist/
+# Also where /healthz reads the version from.
 COPY --from=builder /app/packages/gateway/package.json packages/gateway/
 
-# Built web UI — served same-origin by the gateway from WEB_DIST.
-COPY --from=builder /app/apps/web-dashboard/dist web/
-
 # Workspace root package.json needed for module resolution
 COPY --from=builder /app/package.json ./
 
-# The v2 relay keeps pairings and keys here: mount a persistent volume.
+# Pairings and keys are kept here: mount a persistent volume.
 RUN mkdir -p /data && chown -R linkshell:linkshell /app /data
 USER linkshell
 
 ENV NODE_ENV=production
 ENV PORT=8787
-ENV WEB_DIST=/app/web
 ENV RELAY_DATA_PATH=/data/relay.db
 # Collect garbage well inside a 768 MB container instead of growing into its limit.
 ENV NODE_OPTIONS=--max-old-space-size=512
 EXPOSE 8787
 
-CMD ["node", "packages/gateway/dist/gateway/src/index.js"]
+CMD ["node", "packages/gateway/dist/gateway/src/main.js"]

package/README.md

@@ -1,77 +1,135 @@
 # @linkshell/gateway
 
-LinkShell Gateway — WebSocket 消息中转服务，连接 CLI 和手机 App。
+LinkShell 网关：手机和电脑之间的中继。它用密钥认证两端，在允许互相访问的手机和电脑之间转发**端到端加密**的数据帧（网关读不了内容），并负责配对（二维码或 6 位配对码）。
 
-Gateway 不运行任何终端进程，只负责配对、会话管理和消息路由。
+官方网关（`gateway.itool.tech`）和自建网关运行的是同一份代码。区别只在配置：自建网关没有账号，靠配对；官方网关另外校验账号和 Pro 订阅。
 
-## 部署
+需要 Node.js 22.13 或更新版本（数据用 Node 自带的 SQLite 保存）。完整的自建步骤（HTTPS、反向代理、连接手机）见[部署指南](https://github.com/LiuTianjie/LinkShell/blob/main/docs/deploy.md)。
 
-### Docker（推荐）
+## 运行
+
+### 用 CLI
+
+```bash
+npm i -g linkshell-cli
+linkshell gateway --port 8787 --daemon
+linkshell gateway status
+linkshell gateway stop
+```
+
+数据保存在 `~/.linkshell/relay.db`，日志在 `~/.linkshell/gateway.log`。
+
+### 用 Docker
 
 ```bash
-docker compose up -d
+docker run -d --name linkshell-gateway --restart unless-stopped \
+  -p 8787:8787 -v linkshell-gateway:/data \
+  nickname4th/linkshell-gateway:latest
 ```
 
-### 直接运行
+数据在容器里的 `/data/relay.db`，所以要挂载卷。镜像目前只有 `linux/amd64`。
+
+从源码构建镜像：在仓库根目录运行 `docker compose up -d`。
+
+### 从源码
 
 ```bash
 pnpm install
+pnpm --filter @linkshell/wire build
 pnpm --filter @linkshell/gateway build
-PORT=8787 node packages/gateway/dist/gateway/src/index.js
+PORT=8787 RELAY_DATA_PATH=./data/relay.db node packages/gateway/dist/gateway/src/main.js
+
+pnpm dev:gateway     # 开发：tsx 直接运行 src/main.ts
+```
+
+### 作为库
+
+```ts
+import { startGateway } from "@linkshell/gateway";
+
+const gateway = await startGateway({ port: 8787, databasePath: "./relay.db" });
+// gateway.port；结束时 await gateway.close()
 ```
 
+`linkshell gateway` 就是这样启动它的。
+
 ## 环境变量
 
 | 变量 | 默认值 | 说明 |
 |------|--------|------|
 | `PORT` | `8787` | 监听端口 |
 | `LOG_LEVEL` | `info` | 日志级别：debug / info / warn / error |
-| `AUTH_REQUIRED` | `false` | 设为 `true` 后要求 Supabase JWT 并校验订阅 |
-| `SUPABASE_URL` | - | Supabase 项目 URL |
-| `SUPABASE_ANON_KEY` | - | Supabase anon key |
-| `SUPABASE_SERVICE_ROLE_KEY` | - | 服务端订阅检查和 Gateway 状态持久化使用 |
-| `SUPABASE_GATEWAY_TOKEN_TABLE` | `linkshell_gateway_tokens` | 设备 token 持久化表 |
-| `SUPABASE_GATEWAY_PAIRING_TABLE` | `linkshell_gateway_pairings` | 配对状态持久化表 |
-| `PAIRING_TTL_MS` | `600000` | 配对码有效期，默认 10 分钟 |
+| `RELAY_DATA_PATH` | `./data/relay.db` | 数据文件（SQLite）。Docker 镜像里是 `/data/relay.db` |
+| `TRUSTED_PROXIES` | 空 | 反向代理的 IP（网关看到的来源地址），逗号分隔；IPv4 可以写成网段，如 `172.16.0.0/12`。只有连接来自这些地址时才采信 `X-Forwarded-For`；留空则一律按直接连接的地址计算限流 |
+| `WS_CONNECT_RATE_LIMIT_MAX` | `20` | 每个 IP 在一个时间窗口内允许的连接次数（本机回环地址不限） |
+| `WS_CONNECT_RATE_LIMIT_WINDOW_MS` | `60000` | 上面的时间窗口 |
+| `SUPABASE_URL`、`SUPABASE_ANON_KEY` | - | 两个都设置后启用账号：校验账号令牌，同一账号下的手机和电脑不用配对就能互相访问 |
+| `AUTH_REQUIRED` | `false` | 设为 `true`：电脑必须登录账号并且订阅有效才能接入（手机不受影响） |
+| `SUPABASE_SERVICE_ROLE_KEY` | - | `AUTH_REQUIRED=true` 时用它查询订阅 |
+
+自建网关一般只需要 `PORT` 和 `RELAY_DATA_PATH`。网关前面有反向代理时要留意连接限流按谁的地址算：
+
+- 没有设置 `TRUSTED_PROXIES`：所有连接都算作来自代理的地址。代理在另一台机器或另一个容器里时，所有用户共用一份限额（每分钟 20 次连接）；代理在本机（`127.0.0.1`）时则完全不限流。
+- 设置为代理的地址（代理在本机时是 `127.0.0.1,::1`）：按 `X-Forwarded-For` 里每个用户自己的地址分别限流。
+- 代理在容器网络里、地址每次部署都会变：写成它所在的网段（如 `172.16.0.0/12`）。
+- 前面有多层代理（CDN 再到 nginx）：每一层都要列出来。用户的地址取的是 `X-Forwarded-For` 里**从右往左第一个不属于代理的地址**：最左边那一段是调用方自己写的，不能信。
+- 不确定代理的地址是什么：先不设置，看网关日志。收到带 `X-Forwarded-For` 却不在名单里的连接时，日志会写出它的地址（每个地址只说一次）。
 
-启用官方服务版部署时，先在 Supabase 执行 `docs/supabase-gateway-state.sql`。表不存在时 Gateway 会退回内存态，但 Docker 重启后设备 token 和未过期配对状态不会恢复。
+### 带账号和订阅校验的部署
 
-## API
+官方网关是这样配置的（见仓库根目录的 `luma-gateway.yml`）：
 
-| 方法 | 路径 | 说明 |
+```bash
+AUTH_REQUIRED=true
+SUPABASE_URL=https://<project>.supabase.co
+SUPABASE_ANON_KEY=...
+SUPABASE_SERVICE_ROLE_KEY=...
+```
+
+- 账号令牌通过 `${SUPABASE_URL}/auth/v1/user` 校验。
+- 订阅查的是 `profiles` 表：`plan` 为 `pro` 且 `plan_expires_at` 晚于当前时间才算有效。
+- 只在电脑连接时检查一次；查询本身失败（网络、配置问题）时放行，不会因为一次查询失败把用户挡在外面。
+
+## 接口
+
+| | 路径 | 说明 |
 |------|------|------|
+| `WS` | `/v2/connect` | 电脑（host）和手机 App 的连接 |
 | `GET` | `/healthz` | 健康检查 |
-| `POST` | `/pairings` | 创建配对（返回 6 位 code，默认 10 分钟有效） |
-| `POST` | `/pairings/claim` | 用 code 换取 sessionId |
-| `GET` | `/pairings/:code/status` | 查询配对状态 |
-| `GET` | `/sessions` | 列出活跃会话 |
-| `GET` | `/sessions/:id` | 会话详情 |
-| `WS` | `/ws?sessionId=&role=` | 实时连接（role=host 或 client） |
-| `GET/POST` | `/tunnel/:sessionId/:port/**` | HTTP 端口转发 |
-| `WS` | `/tunnel/:sessionId/:port/**` | WebSocket 端口转发（HMR） |
-
-## 特性
-
-- 内存态会话管理，可选 Supabase 持久化设备 token 和配对状态
-- ACK 追踪 + 输出缓存（最近 200 条，client 重连时快速重放）
-- 单设备控制权管理（claim/grant/reject/release）
-- Agent Workspace v2 envelope 透传，支持 capabilities、snapshot、event、permission 和 structured input
-- Tunnel proxy 支持 HTTP 与 WebSocket，移动端可预览本地 dev server
-- 心跳 ping/pong 检测死连接（20s 间隔）
-- 会话 TTL（host 断开保留 60s，空闲 30min 清理）
-- IP 限流（配对 30 req/min，WebSocket 20 conn/min）
-- CORS 支持
-- 协议版本协商
-- 优雅关闭（SIGINT/SIGTERM）
+
+其他路径一律返回 404。
+
+```bash
+curl http://localhost:8787/healthz
+# {"ok":true,"version":"0.6.0","relay":2,"memoryMb":61}
+```
+
+`relay` 是当前在线的连接数（电脑加手机），`memoryMb` 是进程占用的内存。
+
+## 数据文件
+
+全部数据就是一个 SQLite 文件：每台电脑、每台手机的公钥、名称和所属账号，以及哪台手机和哪台电脑配对。没有任何会话内容。
+
+**这个文件丢了，所有手机都要重新配对。** 迁移或升级时带上它（Docker 就是保留那个卷）；备份时连同旁边的 `-wal`、`-shm` 文件一起，或者先停掉网关。
+
+## 从 0.5.x 升级
+
+0.6.0 去掉了 1.x 的那一半，只保留中继：
+
+- 1.x 的接口没有了：`/ws`、`/pairings*`、`/sessions*`、`/tunnel/*`，以及根路径上的网页控制台。1.x 的 App 和 `linkshell start` 不能再连接这个网关。
+- 这些环境变量不再读取，可以删掉：`PAIRING_TTL_MS`、`PAIRING_RATE_LIMIT_*`、`CLAIM_FAILURE_RATE_LIMIT_*`、`SUPABASE_GATEWAY_TOKEN_TABLE`、`SUPABASE_GATEWAY_PAIRING_TABLE`、`SUPABASE_STATE_TIMEOUT_MS`、`WEB_DIST`。
+- 数据文件和格式没有变：沿用原来的 `relay.db`（Docker 沿用原来的卷），已配对的手机不用重新配对。2.x 的 CLI 和 App 不需要任何改动。
+- 作为库使用时：`@linkshell/gateway/embedded` 的 `startEmbeddedGateway` 换成 `startGateway`；`@linkshell/gateway-v2` 已并入本包，不再单独发布。
 
 ## 代码入口
 
-如果要继续改 Gateway，优先从这几个文件进入：
+1. `src/relay.ts`：`Gateway`，认证、路由、配对、背压
+2. `src/store.ts`：SQLite 里的两张表（`peers`、`links`）
+3. `src/serve.ts`：`startGateway`，HTTP 服务、`/healthz`、连接限流
+4. `src/main.ts`：可执行入口，读环境变量后调用 `startGateway`
+5. `src/accounts.ts`、`src/subscription.ts`：账号令牌和订阅
 
-1. src/index.ts
-2. src/pairings.ts
-3. src/sessions.ts
-4. src/relay.ts
+`/v2/connect` 这个路径和 `store.ts` 里的表结构不能改：已安装的每一台电脑和手机都依赖它们。
 
 ## License
 

package/dist/gateway/src/accounts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accounts.js","sourceRoot":"","sources":["../../../src/accounts.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,sDAAsD;AAStD,MAAM,UAAU,gBAAgB,CAAC,GAAW,EAAE,OAAe;IAC3D,MAAM,KAAK,GAAG,IAAI,GAAG,EAA+C,CAAC;IACrE,OAAO,KAAK,EAAE,KAAK,EAAE,EAAE;QACrB,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC7B,IAAI,GAAG,IAAI,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE;YAAE,OAAO,GAAG,CAAC,OAAO,CAAC;QACtD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,GAAG,eAAe,EAAE;gBAClD,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE;gBAC9D,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC;aAClC,CAAC,CAAC;YACH,IAAI,CAAC,QAAQ,CAAC,EAAE;gBAAE,OAAO,SAAS,CAAC;YACnC,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAoC,CAAC;YACxE,IAAI,CAAC,IAAI,CAAC,EAAE;gBAAE,OAAO,SAAS,CAAC;YAC/B,MAAM,OAAO,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;YACvD,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;YAC1D,IAAI,KAAK,CAAC,IAAI,GAAG,IAAI;gBAAE,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,KAAK;oBAAE,IAAI,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE;wBAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzG,OAAO,OAAO,CAAC;QACjB,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/gateway/src/index.d.ts

@@ -1 +1,4 @@
-export {};
+export { Gateway, type GatewayOptions } from "./relay.js";
+export { GatewayStore } from "./store.js";
+export { supabaseVerifier, type Account, type VerifyToken } from "./accounts.js";
+export { startGateway, type RunningGateway, type StartGatewayOptions } from "./serve.js";