@hyxf/pairdrop 0.1.2 → 0.1.4

package/README.md

@@ -1,105 +1,70 @@
 # PairDrop
 
-PairDrop 可在浏览器中帮助附近设备互相发送文件和文本。本仓库包含使用 React 和 TypeScript 编写的客户端，采用 Vite 和 Tailwind CSS 构建；还包含基于 TypeScript、Fastify 和 WebSocket 的服务端，用于设备发现与信令传输。
+PairDrop 让附近设备通过浏览器发送文件和文本。设备连接到同一个 PairDrop 服务后，可以发现彼此；完成配对后即可传输。桌面和移动设备均可使用，目前界面仅提供英文。
 
-## 功能
+本文面向安装和使用 PairDrop 的用户，介绍启动、配对、运行配置和常见连接问题。源码开发与实现细节见 [Web 客户端说明](apps/web/README.md) 和 [服务端说明](apps/server/README.md)。
 
-- 发现附近设备；配对后才能发送文件和文本。条件允许时使用 WebRTC，否则可通过 WebSocket 中继传输数据。
-- 配对设备以便之后互相发现。
-- 设置并保存设备显示名称；通过配对码、邀请链接或系统分享面板（浏览器支持时）分享邀请。
-- 保存接收的文件；浏览器支持文件分享时，也可通过系统分享面板分享文件。
-- 桌面和移动设备均可使用响应式界面。目前界面仅提供英文。
+## 安装与启动
 
-配对邀请支持 `?pair_key=` 链接。本 React 客户端尚未实现旧版 Web Share Target、文件处理器、加密 URL 载荷、按设备配置配对以及主题偏好设置界面。Web App Manifest 未注册分享目标。
-
-## 环境要求
-
-- Node.js 22 或更高版本（与 `package.json` 中的最低版本一致）。
-- Yarn Classic 1.22。
-
-根据锁文件安装依赖：
-
-```sh
-yarn install
-```
-
-在同一局域网内使用时，其他设备可以打开运行服务的电脑所提供的局域网地址。请确认操作系统防火墙允许访问服务端口。设备发现和配对需要连接到同一个 PairDrop 信令服务。
-
-## 本地开发
-
-分别在两个终端启动信令服务端和客户端：
-
-```sh
-yarn dev:s
-```
-
-```sh
-yarn dev:c
-```
-
-服务端默认监听 `3001` 端口，Vite 默认监听 `5173` 端口。请打开 Vite 输出的访问地址。Vite 会将 `/config` 和 WebSocket 路径 `/server` 代理到本地信令服务端。设置 `PORT` 可更改服务端端口；Vite 代理会使用相同端口。
-
-## 生产环境
+需要 Node.js 22 或更高版本。通过 npm 安装并启动：
 
 ```sh
-yarn build
-yarn start
+npm install -g @hyxf/pairdrop
+pairdrop
 ```
 
-`yarn build` 生成客户端和服务端 JavaScript；`yarn start` 只运行已构建的命令行工具，不会在每次启动时重新编译。默认监听 `3000` 端口，设置 `PORT` 可更改端口。服务端从 `dist/` 提供构建后的客户端文件。发布 npm 包时，`prepack` 会先生成构建产物。
+也可以使用简写命令 `pd`。服务启动后会打印 `http://localhost:3000` 和可用的局域网地址。在其他设备的浏览器中打开打印的局域网地址；这些设备需要能够访问运行 PairDrop 的电脑及其端口，操作系统防火墙也应允许该连接。服务默认监听所有 IPv4 网卡。
 
-也可以在构建后通过命令行启动：
+启动时可选择端口，或自动打开本机浏览器：
 
 ```sh
-yarn build
-yarn pairdrop
+pairdrop --port 4000 --open
 ```
 
-`pairdrop` CLI 默认只打印访问地址，不会打开浏览器。支持 `--port <端口>` 修改端口、`--open` 启动后打开浏览器，以及 `--help` 查看帮助；使用 `--open` 时可通过 `BROWSER` 指定浏览器可执行文件。CLI 会列出本机局域网 IPv4 地址，生产服务绑定所有 IPv4 网卡，局域网内的其他设备可通过这些地址访问。发布后的 npm 包会提供同名 `pairdrop` 命令；在本仓库使用时可运行 `yarn pairdrop`。CLI 使用构建后的 `dist/` 前端文件和 `dist-server/` 服务端 JavaScript，不会启动 Vite。
-
-本地开发流程保持不变：分别运行 `yarn dev:s` 和 `yarn dev:c`，并访问 Vite 提供的地址。
+使用 `pairdrop --help` 查看全部命令行选项。`PORT=4000 pairdrop` 也可设置端口；指定 `--open` 后，可通过 `BROWSER` 环境变量指定浏览器可执行文件。
 
-`yarn start` 和 `yarn pairdrop` 都会启动生产服务；启动前必须先运行 `yarn build`。若要将服务端口改为 `4000`，可使用 `PORT=4000 yarn start`。运行 `yarn pairdrop --help` 可查看 CLI 参数。
+## 配对与传输
 
-单次传输最多 100 个文件、总大小不超过 256 MiB；接收中的文件与尚未关闭的接收文件对话框合计不超过 512 MiB。发送端和接收端按文件计算 CRC32，接收端确认字节数与校验值一致后才回复完成。校验用于发现传输损坏，不用于验证发送者身份。连接服务端或 WebRTC 直连暂时失败时会重试；本地信令服务默认启用 WebSocket 中继，无需设置 `WS_FALLBACK=true`。局域网设备仍须能访问运行 CLI 的电脑及其监听端口；公司网络中的防火墙或网段隔离可能阻止访问。
+1. 在两台设备上打开同一个 PairDrop 服务的地址。附近设备会显示在页面上，但配对前不能发送内容。
+2. 在一台设备上打开配对窗口，使用另一台设备输入六位配对码，或扫描二维码、打开邀请链接。配对码有效期为五分钟。
+3. 配对成功后，选择目标设备发送文件或文本。桌面端也可以将文件拖到设备卡片上。
+4. 接收方确认文件请求后开始传输。传输完成时，请在接收设备上保存文件，或在浏览器支持时通过系统分享面板分享。
 
-本次传输协议升级后，使用旧页面的设备需要重新打开 PairDrop 页面，再与更新后的服务连接。服务端会拒绝旧协议连接，避免新旧页面对同一文件给出不一致的完成结果。
+配对信息和自定义设备名称保存在浏览器本地存储中。清除浏览器数据后需要重新配对；刷新页面前请保存已接收的文件。单次传输最多 100 个文件，总大小不超过 256 MiB。
 
-使用 WebRTC 和移动端分享 API 等依赖浏览器能力的功能时，请通过 HTTPS 提供服务。部分网络环境可能需要在 `RTC_CONFIG` 中配置合适的 TURN 服务器才能建立 WebRTC 连接。默认配置仅包含 Google 公共 STUN 服务器。
+设备优先通过 WebRTC 直连；直连不可用时，本地信令服务默认使用 WebSocket 中继。WebRTC、剪贴板和移动端系统分享等功能受浏览器安全要求限制，建议通过 HTTPS 访问。某些网络环境需要配置 TURN 服务器才能建立 WebRTC 连接。客户端的传输与浏览器能力边界见 [Web 客户端说明](apps/web/README.md#功能与边界)。
 
-## 配置
+## 运行配置
 
-启动服务端前，可通过环境变量进行配置：
+启动前可设置以下环境变量：
 
-| 变量                | 说明                                                                                                                                                                                     |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `PORT`              | 监听端口。开发环境默认为 `3001`，生产环境默认为 `3000`。                                                                                                                                 |
-| `RTC_CONFIG`        | WebRTC `RTCConfiguration` JSON 文件的路径（包括 `iceServers`）。未设置时，使用 Google STUN 服务器。                                                                                      |
-| `WS_FALLBACK`       | 本地信令服务默认启用 WebSocket 中继，WebRTC 直连不可用时用于传输；设置为 `false` 可关闭。                                                                                                |
-| `SIGNALING_SERVER`  | 指定要使用的其他信令服务器，填写不含协议前缀的主机名及可选路径，例如 `pairdrop.example.com`。此模式不能与 `RTC_CONFIG`、`WS_FALLBACK` 或 `IPV6_LOCALIZE` 同时使用。                      |
-| `IPV6_LOCALIZE`     | 使用缩短后的 IPv6 前缀对客户端分组，取值为 `1` 至 `7` 个网段。                                                                                                                           |
-| `RATE_LIMIT`        | 设置为 `true` 时启用 HTTP 速率限制，默认为 `false`。仅接受 `true` 或 `false`；代理地址通过 `TRUSTED_PROXY_IPS` 配置。                                                                    |
-| `LOG_LEVEL`         | 设置服务端日志级别。默认为生产环境 `warn`、开发环境 `info`；可设为 `silent` 关闭日志，或设为 `info` 显示请求日志。                                                                       |
-| `TRUSTED_PROXY_IPS` | HTTP 和 WebSocket 共用的受信任反向代理 IP，多个 IP 用逗号分隔，如 `127.0.0.1`。未设置时不信任转发请求头。代理应覆盖或正确追加 `X-Forwarded-For`，并清理客户端提供的 `CF-Connecting-IP`。 |
-| `DEBUG_MODE`        | 设置为 `true` 时输出诊断日志。日志可能暴露配置信息，请勿在生产环境中启用。                                                                                                               |
+| 变量                | 说明                                                                                                                                                  |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PORT`              | 监听端口，默认为 `3000`；也可使用 `--port`。                                                                                                          |
+| `RTC_CONFIG`        | WebRTC `RTCConfiguration` JSON 文件路径，可在其中配置 TURN 服务器；默认使用 Google 公共 STUN 服务器。                                                 |
+| `WS_FALLBACK`       | 本地信令服务默认启用 WebSocket 中继；设为 `false` 可关闭。                                                                                            |
+| `SIGNALING_SERVER`  | 使用其他信令服务器，填写不含协议前缀的主机名及可选路径，例如 `pairdrop.example.com`。不能与 `RTC_CONFIG`、`WS_FALLBACK` 或 `IPV6_LOCALIZE` 同时使用。 |
+| `IPV6_LOCALIZE`     | 按缩短后的 IPv6 前缀对客户端分组，取值为 `1` 至 `7` 个网段。                                                                                          |
+| `RATE_LIMIT`        | 设为 `true` 启用 HTTP 速率限制，默认为 `false`。                                                                                                      |
+| `TRUSTED_PROXY_IPS` | 受信任反向代理的 IP，多个 IP 用逗号分隔；未设置时不信任转发请求头。                                                                                   |
+| `LOG_LEVEL`         | 服务端日志级别；生产环境默认为 `warn`，可设为 `info` 或 `silent`。                                                                                    |
+| `DEBUG_MODE`        | 设为 `true` 输出诊断日志；日志可能包含配置信息。                                                                                                      |
 
-例如，使用自定义 RTC 配置并在端口 `4000` 启动：
+例如，使用自定义 RTC 配置并监听 `4000` 端口：
 
 ```sh
-PORT=4000 RTC_CONFIG=./rtc-config.json yarn start
+PORT=4000 RTC_CONFIG=./rtc-config.json pairdrop
 ```
 
-`RTC_CONFIG` 指向 JSON 文件，文件内容应符合浏览器的 WebRTC `RTCConfiguration` 格式。配置中可包含 TURN 服务器；请妥善保护 TURN 凭据。若设置 `SIGNALING_SERVER`，配对信令由指定服务器提供，相关 RTC 和 WebSocket 中继配置应在该信令服务器上设置。
+`RTC_CONFIG` 文件应符合浏览器的 WebRTC `RTCConfiguration` 格式。请妥善保管其中的 TURN 凭据。使用反向代理时，应由代理正确设置 `X-Forwarded-For`，并清理客户端提供的 `CF-Connecting-IP`。
 
-服务端还会读取 `DONATION_BUTTON_*`、`TWITTER_BUTTON_*`、`MASTODON_BUTTON_*`、`BLUESKY_BUTTON_*`、`CUSTOM_BUTTON_*` 和 `PRIVACYPOLICY_BUTTON_*` 环境变量来配置页脚链接。目前的 React 客户端不会显示这些按钮。
+## 连接问题排查
 
-## 检查
+- 看不到其他设备时，确认两台设备打开的是同一个 PairDrop 服务，并检查局域网连通性、防火墙与监听端口。
+- 页面更新后无法连接时，重新打开所有设备上的 PairDrop 页面，避免旧页面继续使用不兼容的传输协议。
+- WebRTC 无法直连时，可保持默认启用的 WebSocket 中继；跨网络使用时，可通过 `RTC_CONFIG` 配置 TURN 服务器，并通过 HTTPS 提供页面。
 
-```sh
-yarn typecheck
-yarn lint
-yarn format:check
-yarn build
-```
+## 源码开发
 
-GitHub Actions 会在推送版本标签（名称以 `v` 开头）时运行上述检查，使用 Node.js 22 和 Yarn Classic。`yarn build` 会生成前后端构建产物。目前尚未配置自动化测试。
+- [Web 客户端说明](apps/web/README.md)：前端结构、功能边界、本地开发和构建。
+- [服务端说明](apps/server/README.md)：服务端模块、状态归属、协议和发布流程。

package/bin/pairdrop.js

@@ -113,7 +113,7 @@ function waitUntilReady(child) {
 async function startPairDrop({ port, open }) {
   if (!existsSync(distPath) || !existsSync(serverEntry))
     throw new Error(
-      'Built PairDrop files were not found. Run `yarn build` before starting PairDrop.',
+      'Built PairDrop files were not found. Run `pnpm build` before starting PairDrop.',
     )
 
   const child = spawn(process.execPath, [serverEntry], {