zijunchiang/opendance-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 17 Wiki Activity

17 Releases 17 Tags

RSS Feed
  • v0.7.1 3738bd91b9
    Compare

    OpenDance Studio Web 服务端 v0.7.1 Stable

    zijunchiang released this 2026-09-17 01:30:42 +08:00 | 15 commits to main since this release

    OpenDance Studio -- Web 管理服务端 v0.7.1

    契约补齐 + 文档补齐（《DSH 开发文档 v1.6》7.2）。本版不含运行时行为变更，
    GET /health 的 version 由 web-server/package.json 同源驱动，管理端左下角同步显示 v0.7.1。

    一、契约 websocket-keypoints 0.1.0 → 0.2.0（T-WEB-016）

    与 Android 端 T-AND-011「连接状态异常、频繁重连」的两端一起改配套。
    按文档 §7.2，契约先在 Web 端修改并提升版本，再向另两端建迁移任务。

    完全向后兼容：子协议名 opendance.pose.v1 与二进制帧 version = 0x01 均不变，
    只新增可选控制字段与一种新控制类型；仅实现 v0.1.0 的一端仍可互通。

    章节 新增 为什么必须写进契约
    1.1 保活 接收端必须声明 silentTimeoutMs 与 heartbeatIntervalMs，且心跳必须小于静默超时的一半 客户端原先只能用 OkHttp 的协议层 ping，而它由底层库自动应答、不暴露给应用层，接收端根本看不到，无法续命 —— 这是"画面里没人就掉线、然后疯狂重连"的根因
    3.1 hello.deviceId（该安装实例的稳定标识，不使用任何硬件序列号） 没有它，一次闪断重连会被接收端显示成两台设备
    3.2 / 3.3 welcome / config 携带上述保活字段 让客户端按服务端节奏保活，而不是各写一套魔数
    3.6 应用层 ping / pong（回显 sentAtMs，pong 另带 serverAtMs 供算 RTT） 协议层 ping 对应用层不可见，必须自定义
    5 设备去重：同一 deviceId 只保留最新连接，旧连接以 1000 关闭 用 1000 是刻意的：对端据 §7 不会重连，否则会形成"挤掉-重连-再挤掉"的循环
    7 关闭码与重连策略：1000 / 1001 / 1002 与主动停止不重连，其余重连 原实现"只要能重连就重连"，服务端重启或协议不匹配时也会疯狂重连
    7.1 退避参数冻结：min(500ms × 2^(n-1), 15000ms) + ±20% 抖动 避免同网段多台设备同时重连打尖峰
    8 连接状态机 idle → resolving → connecting → handshaking → streaming → degraded → reconnecting → stopped 两端同名，日志可直接对照

    contracts/VERSION 与 web-server/src/config/contract-versions.ts 同步到 0.2.0
    （npm run contracts:check 强制两者一致）。

    二、补齐 rest-api.yaml 里漏写的场景结构

    catalog/export 自 v0.7.0 起就返回 scenes[]，data-models.md §7 也已冻结，
    但 CatalogBundle 漏了这个字段、components 里也没有 Scene / SceneConfig 定义 ——
    属于"实现已发布、规格漏写"。只补规格，不改线格式，六个契约版本号均不变：

    • CatalogBundle 增加 scenes[]（标注 0.5.0 起下发）；
    • 新增 Scene / SceneConfig / Vec3 schemas（重力 ±200、风 0100 / 0.015Hz、
      摩擦 01、坡度 089°、出生点 ≤16、相机 follow|fixed|orbit 等边界全部写明）。

    规格缺失会让两端对字段边界的理解不一致（Windows 端 T-WIN-013 正是照这份结构生成的
    GDScript 类型）。

    三、deploy/proxy/README.md 新增第九节：Gitea 站点的附件上传上限

    与前八节的 Web 服务反代是两个不同站点 —— 托管 Gitea（源码 + Release 附件）的
    IIS 站点必须单独放开：

    上传体积 实测结果
    14 MB 通过（HTTP 201）
    30.5 MB 失败 HTTP 413
    40 MB 失败 HTTP 413

    根因是 IIS 默认的 maxAllowedContentLength = 30,000,000 字节（≈28.6 MiB）。
    这正是 Windows 客户端 v0.1.0 被拆成 zip.part0/1/2（用户拿到无法直接解压的碎片）的根因。

    文档给出放宽到 256 MB 的四处配置（IIS requestLimits + uploadReadAheadSize、
    ARR maxRequestBytes、Gitea app.ini 的 [attachment] MAX_SIZE、前置 nginx 的
    client_max_body_size）与 curl 复验命令。

    四、文档与脚本

    • 补齐 tasks/011 ~ tasks/016 与 project.yaml 条目：此前 T-WEB-011~015
      已在代码中落地却缺任务说明书（011 版本号展示 / 012 VRM 优先 / 013 动作标准与骨骼
      重绑定 / 014 动作预览 / 015 场景管理 / 016 本契约变更）；
    • project.yaml 的 contracts_version 由单个 0.4.0 改为六项字典
      （六项契约已各自独立递增）；
    • scripts/package-release.sh：版本号改为从 web-server/package.json 读取
      （与 GET /health 的 version、管理端左下角展示同源），并与 project.yaml
      交叉校验；同时补上 SHA256SUMS 与自校验（此前是手工生成的）。

    校验

    • npm run verify：contracts:check（六项一致 + 35 条路由一致）、tsc --noEmit、
      18 文件 / 246 项测试、nest build 全部通过；
    • opendance-web-v0.7.1.tar.gz sha256: 27f92cfb125bbcf29077d4ad90c44720cbca46d23ddef12cd7826d73bd8865e2

    部署

    curl -fLO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.7.1/opendance-web-v0.7.1.tar.gz
curl -fLO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.7.1/SHA256SUMS
sha256sum -c SHA256SUMS
tar -xzf opendance-web-v0.7.1.tar.gz && cd opendance-web-v0.7.1
bash deploy/install.sh

    本版不需要重新部署也能继续使用：运行时行为未变，只是 /health 报出的
    websocket-keypoints 契约版本从 0.1.0 变为 0.2.0，以及 contracts/ 快照更新。
    若要让 /health 与新快照一致，重新部署本版即可。

    Downloads