多端使用与运行指南
平时写代码，最舒服的方式莫过于直接在主力机上双击桌面包开箱使用。如果你有一台性能强劲的台式机或常开的软路由/NAS，也可以将它作为常驻后台，出门在外用笔记本或平板随时连回继续工作。
本文档为你介绍桌面一体包安装、手机扫码接入、远程与公网访问，以及二次开发指引。
1. 客户端形式一览
| 客户端形式 | 适用场景 | 亮点体验 |
|---|---|---|
| macOS 一体包 | Mac 笔记本 / 主力机 | 双击即跑，免配环境，Apple Silicon 极致流畅 |
| Windows 一体包 | PC 台式机 / 笔记本 | 双击运行，开箱即用，自动拉起核心服务 |
| Web 远程端 | 平板 / 任意浏览器 | 自适应宽屏布局，结合组网随时随地远程接续 |
| iOS 移动端 | iPhone / 随身查看 | 出门在外随手查看长程任务执行进度与报错 |
2. 桌面一体包快速安装 (开箱即用)
TIP
现已开放专属 全平台客户端下载中心，包含 macOS、Windows 最新安装包、系统版本限制明细与 iOS 移动伴侣研发动态。
对于绝大多数日常使用者，直接下载安装包是最舒服的选择：
- 前往 全平台客户端下载中心 或 GitHub Releases 页面；
- 下载对应系统的安装包：
- macOS 用户：点击 下载 DMG 镜像（暂时只支持 M 系列芯片），双击拖入 Applications 文件夹；
- Windows 用户：点击 下载安装包 (.exe)，双击安装。
3. 手机扫码接入
桌面一体包自带手机接入，默认开启、无需任何配置：电脑上的 Piwin 开着，手机扫一次码就能随时查看和操作会话。
3.1 在家：手机和电脑连同一个 Wi‑Fi
- 打开桌面端 设置 → 通用与外观 → 手机接入，「允许手机接入」默认已开，页面直接显示二维码；
- 手机打开 Piwin App，选择 「扫码连接」，扫描这个二维码；
- 完成配对。之后只要电脑上的 Piwin 开着、两台设备在同一网络，手机会自动重连，不需要再扫。
第一次使用时可能出现两个系统弹窗，都请点 允许：
- iPhone：询问是否允许 Piwin 访问本地网络；
- Mac（开启了防火墙时）：询问是否允许 Piwin 接受传入的网络连接。
3.2 出门在外：用 Tailscale（推荐）
- 在 Mac 和手机上都安装 Tailscale，登录同一个账号；
- 在「手机连接地址」下拉框中选择 Tailscale 那一项（
100.开头的地址），二维码会自动刷新； - 用手机扫描新的二维码。
Tailscale 地址在家里和外面都能连，而且全程加密。
TIP
如果你会在外面使用，建议一开始就用 Tailscale 地址配对。用局域网 IP 配对的手机离开家里 Wi‑Fi 后会连不上，需要换成 Tailscale 地址重新扫码。
3.3 说明
| 项目 | 说明 |
|---|---|
| 连接地址 | 默认自动选择本机局域网 IP；也可在「手机连接地址」中选择其它网卡地址，或「自定义…」填写 ws:// / wss:// 地址 |
| 端口 | 默认 8790，被占用时自动顺延；选定的端口会被记住，已配对的手机不会因重启失效 |
| 二维码 | 一次性使用，约 10 分钟有效；过期、被使用或地址变化后会自动换新 |
| 安全 | 只有扫码配对过的设备才能连接；局域网连接不加密（ws://），请只在自己信任的网络中使用 |
| 关闭 | 关掉「允许手机接入」开关即可，开关状态会被记住；已配对设备可在同一页面「撤销」 |
3.4 连不上时逐项检查
- 是否在同一网络：访客 Wi‑Fi、公司网络常开启「设备隔离」，设备之间无法互访，请改用 Tailscale；
- 电脑是否在线：电脑上的 Piwin 需要开着，电脑睡眠时手机也连不上；
- 设置页是否有报错：例如「没有检测到局域网地址」（电脑没联网）或端口全部被占用；
- 二维码是否失效：重新打开设置页或点「刷新二维码」后再扫；
- 系统权限：检查 iPhone「设置 → 隐私与安全性 → 本地网络」中 Piwin 是否已开启。
4. 远程访问方案 (Tailscale + 家用台式机/NAS)
如果你想把计算跑在家里配置更高的台式机上，用轻薄本或者平板随时随地连回：
4.1 连接步骤
- 免费组网：在台式机和笔记本上同时安装并登录 Tailscale，加入同一网络；
- 启动服务：在台式机上直接启动 Piwin；
- 远程输入：在远端设备的浏览器或客户端中填入台式机的 Tailscale 内网 IP，即可丝滑接入，进度完全同步。
4.2 公网部署（独立 Host）
如果想把 Host 跑在云服务器或家里的常开机器上、通过公网域名访问，请使用独立 Host，并遵守两条规则：
- 一定要加 TLS：Host 本身只提供明文 WebSocket，必须在前面用 Caddy / nginx 等反向代理提供
wss://域名，不要把端口直接暴露到公网； - 一定要设 Token：只要设置了对外地址
PIWIN_HOST_ADVERTISED_URL，就必须同时设置PIWIN_HOST_TOKEN，否则 Host 会拒绝启动。
bash
PIWIN_HOST_BIND=127.0.0.1 PIWIN_HOST_PORT=8787 \
PIWIN_HOST_TOKEN="$(openssl rand -hex 32)" \
PIWIN_HOST_ADVERTISED_URL=wss://host.example.com \
pnpm --dir apps/host dev以 Caddy 为例，把域名转发到 Host 的本机端口：
text
host.example.com {
reverse_proxy 127.0.0.1:8787
}然后：
- 桌面端在 设置 → 通用与外观 → 远程 Host 中填入
wss://host.example.com和同一个 Token 连接； - 在「手机接入」中打开开关，手机扫码配对即可。手机不需要 Token。
WARNING
经过反向代理的连接一律需要 Token 或已配对设备的凭证。使用 frp、ngrok tcp 等 TCP 转发同样要设置 PIWIN_HOST_TOKEN。
5. 开发者二次开发与本地构建
如果你需要自行定制功能或基于源码进行编译：
5.1 环境要求
- Node.js：
>= 22.0.0 - pnpm：
>= 9.0.0 - Rust：
>= 1.75.0(用于编译 Tauri 2 桌面端)
5.2 常用开发指令
bash
# 1. 克隆代码仓库
git clone https://github.com/mimimaster/piwin.git
cd piwin
# 2. 安装全部依赖
pnpm install
# 3. 运行全量类型检查与单元测试
pnpm typecheck
pnpm test
# 4. 启动桌面端开发调试模式
pnpm dev:desktop
# 5. 启动 CLI 命令行开发模式
pnpm dev:cli
# 6. 本地打包生成 macOS 完整安装包 (.dmg)
pnpm package:desktop