6a7b3a85bb
Verification: FOLLOW-1 P5: following unit tests pass, leanback Java compile passes, Deno/Cloudflare/Vercel relay node --check passes, all five serverless normalizers preserve follow, git diff --check passes Task-Guard: FOLLOW-1-P5 |
History
|
|
|---|---|---|
| .. | ||
| .cargo | ||
| dist | ||
| src | ||
| .gitignore | ||
| Cargo.lock | ||
| Cargo.toml | ||
| README.md | ||
WebHTV Rust Remote Relay
Rust 版远程托管中转服务，兼容现有 HTTP relay API，并支持 WebSocket 实时命令通道。
运行
已编译好的 Linux 二进制在：
dist/webhtv-remote-rust-linux-amd64
dist/webhtv-remote-rust-linux-arm64
直接运行：
chmod +x dist/webhtv-remote-rust-linux-amd64
WEBHTV_REMOTE_ADDR=0.0.0.0:8787 ./dist/webhtv-remote-rust-linux-amd64
也可以从源码运行：
cd serverless/webhtv-remote-rust
cargo run --release
默认监听 0.0.0.0:8787，可通过环境变量覆盖：
WEBHTV_REMOTE_ADDR=127.0.0.1:8787 cargo run --release
观影记录默认保存到当前工作目录的 webhtv-playback.json。生产环境建议使用绝对路径：
WEBHTV_REMOTE_ADDR=0.0.0.0:8787 \
WEBHTV_PLAYBACK_DATA=/var/lib/webhtv/webhtv-playback.json \
cargo run --release
仅测试协议、不落盘时可设置 WEBHTV_PLAYBACK_DATA=:memory:。
验证：
curl http://127.0.0.1:8787/api/server/capabilities
正常会返回 serverMode=rust、relayMode=rust-memory-websocket 和 webSocket=true。
能力
- 兼容现有接口：设备注册、绑定码、设备列表、命令、同步分片。
- WebSocket：
/api/device/ws，App 会优先使用；连接失败时自动回退 HTTP 轮询。 - 内存状态：绑定码、在线快照、命令队列和同步分片保存在进程内。
- 观影记录同步：使用独立本地 JSON 文件持久保存进度、游标和删除墓碑。
- 单文件部署：适合自建 VPS、NAS、软路由、容器或反向代理后运行。
观影记录同步
在 App 的“远端同步”和“Webhook 上报”中填写同一个地址与 token：
https://<你的服务域名>/api/playback/sync
也兼容 /playback/sync。POST 接收进度、完播和删除事件，GET 按 X-WebHTV-Since 返回增量，GET /api/playback/sync/status 返回记录数和最新游标。请求必须携带 X-WebHTV-Token 与 X-WebHTV-Config-Key，持久文件中只保存它们的 SHA-256 分区键。
文件通过临时文件、fsync 和原子 rename 更新，Unix 权限为 0600。请定期备份 WEBHTV_PLAYBACK_DATA 指向的文件；同一文件只应由一个 Rust 服务进程写入，不要让多个副本或容器共享写入。请求体最多 128 KiB，单批最多 100 条，单次拉取最多 1000 条；删除墓碑和幂等事件保留 90 天。
反向代理
如果部署在 Nginx/Caddy/Traefik 后面，需要透传 WebSocket。新版 App 会自动发送 X-WebHTV-Origin，服务端优先使用该值作为 serverOrigin；没有该头时才回退到 X-Forwarded-Host / Host。因此新版 App 通常不需要额外配置，反向代理仍建议正确透传外部访问 origin，兼容旧客户端和手动调试请求。
Nginx 示例：
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
限制
当前版本的远程托管 relay 仍是内存状态，进程重启后绑定码、未投递命令、同步临时文件会丢失；观影记录同步文件不受该限制。同一个域名/origin 下，App 本地保存的 deviceToken/groupToken 可以在下一次 register/poll 时恢复设备和设备组。需要持久命令历史、备份中心或文件管理时，仍需扩展 SQLite/对象存储版本。