云端中转使用指南

板板和电脑在同一个 Wi-Fi 下时，局域网会自动连上，什么都不用做。 不在同一个网络时（公司电脑 + 家里的板板、电脑用手机热点、以后的 4G 版），就要用云端中转：电脑和板板都连到中转服务器，由它在你自己的账号里转发审批和通知。

 拍板 Hub（公司电脑）──wss──▶ 云端中转 ◀──wss── 板板（家里）
                                 ▲
                   拍板小程序（微信登录 = 账号）

需要的版本

一、登录电脑（每台电脑一次）

1. 电脑端打开 账号 → 登录，会出现二维码和 8 位配对码（5 分钟有效）。
2. 手机打开「拍板」小程序 → 我的 → 电脑与云端中转 → 扫码绑定电脑（或者输入配对码）。
3. 小程序显示电脑的名字，确认后电脑自动登录，账号页显示「××的账号 · 中转在线」。

登录信息用系统加密保存（Windows 是 DPAPI），重启电脑不用再登录。

二、把板板绑定到账号（每台板板一次）

两种方式，任选一种。都要在板板上按一下确认：屏幕上会出现「确认绑定账号」，单击 BOOT 或向右倾斜 = 同意，双击或向左倾斜 = 拒绝。

• 在电脑上：板板和这台电脑在同一个 Wi-Fi 时，电脑端 账号 → 局域网里还没绑定的板板 → 绑定到账号。
• 在小程序里：配完 Wi-Fi 后小程序会问要不要绑定；之后也可以在 设置 → 云端中转 里绑定。

绑定好以后，板板的「设备」页会显示 云端中转：电脑在线。

三、日常使用

什么都不用管：

• 同一个 Wi-Fi：走局域网（最快）。
• 不在同一个网络：自动走中转。
• 同一台板板两边都连着时只走局域网，审批不会弹两次；局域网断了会自动切到中转。

登出 / 解绑

板板送人：先解绑。忘了解绑也没关系，新主人在板板上按确认就能绑到自己的账号（中转凭板板里的 claim key 判断「设备在谁手里」）。

安全吗

• 账号隔离：每个令牌只属于一个账号，中转只在同一个账号的电脑和板板之间转发；消息的 from 由服务器填写，伪造不了。
• 账号就是微信：「这台电脑 / 板板属于谁」只能经小程序的云函数确认，openid 由微信给出，前端改不了。
• 抢不走设备：别人知道你的设备 ID 也没用，绑定必须拿到板板里的 claim key，而板板只有在你按了确认之后才会交出来。
• 配对码防猜：8 位、5 分钟过期、只能用一次；一个账号 10 分钟内输错 10 次就锁住。电脑登录后会显示是谁的账号，不是你的就立刻登出。
• 传输加密：全程 TLS（Let's Encrypt 证书），服务器只存令牌的哈希，不存 openid（只存它的 HMAC）。
• 还没做的：消息在服务器上是明文转发的（服务器能看到审批内容）。下一步做端到端加密，让中转既看不到内容，也伪造不了审批。

常见问题

电脑端显示「这台电脑的登录已失效」：在小程序里被解绑了，或者换了中转服务器地址。重新登录即可。

板板「云端中转：连接中…」一直不变：中转要先对好时间（NTP）才能校验证书，确认板板能上外网；固件低于 0.5.0 不支持。

小程序提示「云函数还没配置中转密钥」：见下面的「部署和管理」。

部署和管理（项目维护者看）

中转服务器在哪

Azure 东亚（香港）的一个 AKS 集群（Kubernetes，免费档控制面），地址 https://paiban-relay.eastasia.cloudapp.azure.com。代码在 relay/，基础设施在 infra/aks/。

            Azure 负载均衡（公网 IP + DNS 名）
                       │
          Traefik ×2（HTTPS，Let's Encrypt 证书由 cert-manager 自动续）
                       │
            relay ×2（分在两台节点上，任何一个都能接任何连接）
                       │  LISTEN / NOTIFY：副本之间互相转消息
                  PostgreSQL（8 GiB 磁盘，每天备份到 Blob，留 30 天）

为什么不会掉线： - 中转有两个副本，分在两台节点上。电脑和板板可以连在不同的副本上，副本之间通过 PostgreSQL 的 LISTEN/NOTIFY 互相转发。 - 升级时先起新副本、确认就绪，再停旧副本。旧副本先摘掉流量，再用关闭码 1012 通知客户端「服务重启」。 - 客户端收到 1012 会马上重连到另一个副本。服务器把它的在线状态保留 20 秒，对面不会看到它下线。 - 切换期间发给它的消息先放进「信箱」，重连后补发。电脑端和板板自己要发的消息也会排队，重连后再发。 - Azure 每周日凌晨 3–7 点（香港时间）给节点打补丁，一次只换一台，PodDisruptionBudget 保证至少一个副本在跑。 - 每次部署都会自动跑一次「滚动重启 + 持续审批」的检查：250 条审批往返、零丢失、双方都没看到掉线才算部署成功。

怎么更新（GitHub Actions）

改了 relay/ 或 infra/aks/ 推到 main，Deploy relay (AKS) 会自动跑，也可以在 Actions 页面手动 Run workflow：

1. 起一个临时 PostgreSQL，跑完整测试（两个副本、滚动重启都在里面），打包成一个 server.js。
2. 用 OIDC 登录 Azure（不存任何 Azure 密码；Azure 只信任这个仓库 main 分支发来的令牌）。
3. 跑 Bicep：集群、备份存储已经存在就不改。
4. 装 / 升级 Traefik 和 cert-manager；第一次部署时在集群里生成密钥（RELAY_SECRET、ACCOUNT_SALT、数据库密码），之后一直沿用，从不打印。
5. 新的 server.js 放进 ConfigMap，触发滚动更新（不需要构建镜像，也不需要镜像仓库）。
6. 通过 HTTPS 检查 /healthz，再跑上面说的不掉线检查。结果显示在运行摘要里。

改自己的域名：在 infra/aks/config.env 的 EXTRA_HOSTS 里加上（比如 relay.example.com），把它 CNAME 到 paiban-relay.eastasia.cloudapp.azure.com，推上去就会自动签证书。

第一次：让小程序的云函数能调中转

云函数用一个管理密钥 RELAY_SECRET 调中转的管理接口（确认配对、登记设备）。同一个值要放两处：

1. 生成：在 Azure Cloud Shell 或任何终端里运行 openssl rand -hex 32。
2. GitHub 仓库 Settings → Secrets and variables → Actions → New repository secret：名字 RELAY_SECRET，值填上面那串。然后在 Actions 里手动跑一次 Deploy relay (AKS)，集群里的密钥就换成它了。
3. 微信云开发控制台 → 云函数 → paiban → 配置 → 环境变量：RELAY_SECRET = 同一串；RELAY_URL 可以不填（默认就是上面的地址）。

不用小程序也能测试

仓库公开后，Actions 的运行记录（包括手动运行时填的参数）谁都能看到。Relay admin 会遮住参数、只显示电脑名的前两个字，但不要在这里填真实用户的 openid：真实账号的操作走小程序；需要排查时在 Azure Cloud Shell 里运行 az aks get-credentials -g paiban-rg -n paiban-aks --admin && kubectl -n paiban exec deploy/relay -- node --no-warnings /app/server.js admin list <openid>，结果只有你看得到。

Actions → Relay admin → Run workflow，输入命令，结果显示在运行摘要里：

例如：电脑端点登录 → 在 Relay admin 里跑 pair-confirm 配对码 test-user → 电脑自动登录 → 在电脑端账号页把局域网里的板板绑定进来。之后小程序开通后，用微信登录的账号是另一个 openid，需要重新绑定。