zijunchiang/opendance-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 17 Wiki Activity
76 Commits 2 Branches 17 Tags
main
Commit Graph
10 Commits
Author SHA1 Message Date
zijunchiang 74332e20d8 docs(proxy): 更正「Gitea 附件通道坏了/磁盘写满」的误判 —— 实际是上传字段名写错 
排查 Windows 整包上传时的 500 曾被判成"Gitea 宿主机磁盘写满"。**这个结论是错的**，
本次用对照实验确认并更正：Gitea 的 Release 附件接口 multipart 字段名是
**`attachment`**，用 `file=` 会得到

  HTTP 500 {"message":"","url":"https://gitea.kasugano.cn/api/swagger"}

空消息，极易误判成服务器故障。同一 1 KB 文件、同一 Release 的实测对照：
  -F "attachment=@probe.bin"                      → 201
  --data-binary @probe.bin (+?name=)              → 201
  -F "file=@probe.bin"                            → 500（空消息）

**仍然真实存在、且是唯一限制的是 IIS `maxAllowedContentLength`（默认 30,000,000 字节）**：
927 KB / 14 MB / 16,372,427 B 通过；30.5 MB / 38,245,602 B / 40 MB 一律 HTTP 413。

文档更正：
- deploy/proxy/README.md 第九节重写 9.1（含"误判更正"小节）与 9.3（复验命令改用
  正确字段名），并给出两种可直接照抄的上传写法；
- DSH 开发文档 v1.6 §5.7 的"阶段二"表格改为"误判更正"记录；
- opendance-windows/tasks/014-full-package.md 同步更正并附正确上传命令；
- 本仓库 README.md/.txt 的 v0.7.3 说明补第 6 条。

验证：npm run verify 通过（22 文件 / 281 项测试 + 启动冒烟）；重新打包
opendance-web-v0.7.3.tar.gz（sha256 见 dist-release/SHA256SUMS）。
 2026-09-17 03:39:36 +08:00
zijunchiang 2224195d05 docs: 补齐部署必需的 Gitea 域名与属主（不再脱敏成占位符） 
域名与仓库属主属于「部署必需且非隐私」的信息，此前写成 `<Gitea 地址>` / `<owner>`
会让文档无法照做（照抄的 clone / 下载命令直接失败）。本次把它们补成真实值：
gitea.kasugano.cn / zijunchiang。口令、访问令牌、数据库口令等**秘密项**继续用占位符。

改动：
- README.md / README.txt：发布包下载地址补成真实 Release 地址
  （https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/vX.Y.Z/…），
  并写明域名与属主是部署必需信息、不是隐私项；
- README.md / README.txt：说明 `<服务器地址>` 是**部署方自己的**服务端地址
  （部署方决定），不是被脱敏的信息，避免与「被隐藏的域名」混淆；
- deploy/proxy/README.md：第九节的附件接口复验 curl 补成真实 Gitea 域名与属主；
  自检清单里 `<反代地址>` 加一行说明（你们自己的反代域名或 IP）；
- deploy/systemd/opendance-api.service：`Documentation=` 补成真实仓库地址。
 2026-09-17 03:07:23 +08:00
zijunchiang 7037abf066 docs(proxy): 修正 Gitea 附件上传失败的结论——与体积无关，指向宿主机磁盘 
上一版把失败记成「两阶段 + 约 16.4 MB 边界」，那是**误判**：
当时磁盘正在被失败的请求逐步填满，所以看起来像有个体积阈值。补做与体积、
与仓库都无关的隔离测试后，结论要改：

- 1 KB 与 100 KB 也失败，且**瞬间**失败（0.14~0.3 s，不是读完请求体才判断）
  -> 不是 [attachment] MAX_SIZE 这类体积上限；
- opendance-web / opendance-windows / opendance-android 三个 Release 的资产
  上传接口**同样**失败 -> 与仓库无关；
- 创建 Release、PATCH Release 说明（纯 JSON）都成功 -> 只有「附件文件落盘」
  这条通道坏掉；
- 全部失败期间仍有 927 KB 的附件成功上传过一次 -> 间歇性。

最可能的原因：**Gitea 宿主机磁盘（或上传临时目录所在分区/tmpfs）几乎写满**
（Gitea 先把请求体写入数据目录的临时目录，空间不足时返回 500 而非 413）。

同时确认：IIS 那一关**已经放开且生效**（38,245,661 字节的请求体被完整接收，
不再 413），因此若仍失败应直接排查 Gitea 宿主机，而不是继续改 IIS。

deploy/proxy/README.md 第九节的 9.1 重写为上述隔离结论，并给出运维排查顺序
（df -h / Gitea 日志里的真实错误 / 清理临时文件 / 最后再改 MAX_SIZE）。

Windows 端 tasks/014-full-package.md 同步修正（原先的「16.4 MB 边界」表述作废）。
 2026-09-17 01:51:32 +08:00
zijunchiang 698d60bb65 docs(proxy): 记录 Gitea 附件上传上限的两阶段实测（IIS 放开后仍是 500） 
按文档 §5.7 硬性要求 4「若用 A 方案，先在发布文档里记录实测上限」，把这次
Windows v0.2.0 整包（38,245,661 字节）发布的实测结果写进 deploy/proxy/README.md
第九节，并修正第九节里「只改 IIS 就够」的隐含假设：

第一阶段（IIS 未放开）：14 MB 通过；30.5 / 40 MB 返回 HTTP 413。
第二阶段（IIS 已放开）：38,245,661 字节的请求体被**完整接收**（115 s），
不再有 413 —— 说明 maxAllowedContentLength 已经够用；但随后 **Gitea 自己返回
HTTP 500**（响应体是 Gitea 的 API 错误信封，message 为空），瓶颈转移到了 Gitea 侧。

同接口边界测量：914 KB 与 16,372,427 B 通过；16,400,000 B 及以上失败；
且**在若干次大包失败之后，连 100 KB 都会在 0.3 秒内 500** ——
这不符合「上传体积上限」的特征（体积判断会先读完请求体），
更像上传临时目录 / 数据盘写满（Gitea 先写 data/tmp）。

因此文档明确要求运维按顺序查两件事：①Gitea 数据盘剩余空间（含 data/tmp，
以及它是否在小容量 tmpfs 上）并清理失败上传的残留临时文件；
②app.ini 的 [attachment] MAX_SIZE。并在 IIS 配置小节加醒目提示：
若放开 requestLimits 后仍为 500 而非 413，说明请求体已到达 Gitea，
要按上述两件事继续排查。
 2026-09-17 01:40:27 +08:00
zijunchiang 50073b97cf docs(contracts): 补齐 rest-api 里 CatalogBundle.scenes[] 与 Scene/SceneConfig 结构 
`catalog/export` 自 v0.7.0 起就返回 `scenes[]`（catalog.service.ts 已实现，
data-models.md §7 也已冻结），但 rest-api.yaml 的 CatalogBundle 漏了这个字段，
且 components 里没有 Scene / SceneConfig 定义 —— 属于"实现已发布、规格漏写"。

本次只补规格，不改线格式，因此六个契约版本号均不变（rest-api 仍为 0.5.0，
与文档 v1.6 §5.6「客户端契约升级到 rest-api 0.5.0」一致）：
- CatalogBundle 增加 scenes[]（标注 0.5.0 起下发）
- 新增 Scene（含 glbUrl/thumbnailUrl/config/stats/来源五元组/status）
- 新增 SceneConfig（physics.gravity/wind/ground/colliders、environment、
  spawnPoints<=16、camera）与复用的 Vec3

注入依赖：Windows 端 T-WIN-013 需要按这份结构生成 GDScript 类型，
规格缺失会导致两端对字段边界（如 0~1、±200）的理解不一致。

同时补 deploy/proxy/README.md 第九节：托管 Gitea 的 IIS 站点
附件上传上限（与一~五节的 Web 服务反代是两个不同站点）。
实测 30.5 MB / 40 MB 上传返回 HTTP 413，根因是 IIS 默认
maxAllowedContentLength = 30,000,000 字节；给出放宽到 256 MB 的
IIS / ARR / Gitea app.ini / nginx 四处配置与复验命令。
这解释了 Windows 端 v0.1.0 为何被拆成 zip.part0/1/2（交付缺陷）。
 2026-09-17 00:46:35 +08:00
opendance 60c182f1b2 docs: 消除 Gitea 模棱两可 Unicode 告警（全角标点紧邻 ASCII 时改为半角） 
依据 Gitea v1.27.3 modules/charset/escape_stream.go 的判定规则
（analyzeDetectResults：仅当左右相邻字符都不是非 ASCII 时才标记，
且 _common 表恒定生效），把说明文档中会被标记的全角标点
（，：；？！（） 等）改为半角，并保证成对括号宽度一致。
中文语境中的全角标点（左右均为中文）保持原样，不动代码与契约语义。

同时删除临时探针目录 _probe/（仅用于确认 Gitea 判定规则）。
 2026-09-15 21:45:51 +08:00
zijunchiang ebd871018f docs(readme): 新增初次部署清单与常见问题；统一 root 执行写法；清除 markdown 粗体标记与残留真实库名 2026-09-15 21:27:29 +08:00
zijunchiang bba5bcf59e feat(web): 端口分离 + VMD 动作支持；契约升至 0.2.0 
需求 1：管理端端口与软件 API 端口分离
- 软件 API 端口 PORT（默认 3000）只提供 /api、/health、/static、/contracts，
  不提供管理页面（未命中路径 404）；管理端端口 ADMIN_PORT（默认 3001）
  提供管理页面与全部接口；ADMIN_HOST 可单独限制管理端来源
- main.ts 同进程监听两个端口，用 req.socket.localPort 区分端口行为；
  ADMIN_PORT=PORT 为单端口兼容模式（只创建一个 server，无 EADDRINUSE）
- 端口非法在生产环境中止启动；ADMIN_PORT=PORT 只 warn
- 启动日志分别打印两个端口的访问地址

需求 2：动作数据支持 VMD（MikuMikuDance）
- vmd-parser.ts：二进制解析（30 字节头 + Shift-JIS 模型名 + 111 字节/条骨骼
  关键帧 + morph 段）、MMD 贝塞尔插值、GBK 模型名回退、固定 30fps
- mmd-skeleton.ts：标准 MMD 骨架；静止比例从参考 PMX 骨骼段实测得到
  （足首 1.43 / 膝 6.57 / 髋 11.50 / 首 16.21 / 頭 17.16，腿长 10.09）
- mmd-pose.ts：FK + 两骨骼解析腿部 IK（膝盖朝正面，不可达收敛为伸直）
  + 左手系→右手系 Z 镜像（由真实数据对照实验确定：94.1% vs 5.9%）
- retarget.ts：抽出 worldFramesToKeypointFrames()，BVH 与 VMD 共用重定向
- MotionFormat 增 vmd、扩展名映射增 .vmd；管理端上传支持 .vmd
- scripts/inspect-vmd.mjs：上传前自查工具

契约：rest-api / data-models / model-formats → 0.2.0（另两库已同步逐字节一致）

验证：85 项单测通过（VMD 31 项）；契约与 29 条路由一致；typecheck/build 通过；
真实样本经 HTTP 端到端：霜雪千年 2901 帧（IK 腿）、恋爱循环 4604 帧（FK 腿）
均 preprocessState=done、0 NaN、0 越界（测试数据已从数据库清理）。
 2026-09-15 08:47:37 +08:00
zijunchiang 34c5040e6b feat(deploy): 新增外部访问诊断脚本 check-access.sh 
"服务已启动但外部访问不了"时一次性定位原因，只读诊断、不改配置：
- 读出 .env 的 HOST/PORT，并对 127.0.0.1 这种只监听回环的配置直接报错
- 检查实际监听地址（ss/netstat），区分通配与仅回环
- 回环 + 对外 IP 两次 /health 自测（用 ip route get 取真实出口 IP）
- 检查 80/443 上有没有反向代理，并说明本项目不部署反代
- 检查 firewalld / ufw / iptables 对端口的放行情况，给出修复命令
- 结尾按"直连后端"与"经反代"两条路径给出结论

同时更新 README.txt、deploy/proxy/README.md（新增第八节：还没有反代时
如何直连后端）与打包校验清单。
 2026-09-15 01:43:35 +08:00
zijunchiang 8c76b0a599 feat(web): 移除 Docker 与反代部署，改为 Linux 业务服务并自带管理端托管 
需求变更：Web 端只保留业务需求，反向代理交由另外的服务处理，
本项目仅提供 IIS / nginx 反代说明文档，不部署反代。

主要改动：
- web-server: 新增管理端静态托管（ADMIN_DIR、SPA 深链接回退），
  反代因此只需一条全匹配转发规则；新增 adminDir 配置项
- deploy/install.sh: 删除 nginx 安装与站点配置逻辑，改为原生 Linux
  服务部署（systemd → OpenRC → SysVinit → 后台进程四级降级），
  打印反代交接指引
- deploy/ctl.sh: 启停/状态/日志脚本
- deploy/proxy/: 新增反代说明文档（README.md、nginx.conf.example、
  web.config.example），标注上传上限与超时必须同步调整
- 删除 deploy/nginx/、web-server/admin/nginx.conf、Dockerfile、
  docker-compose.yml、.dockerignore
- scripts/package-release.sh: 锚定排除规则 + 产物完整性校验
- 文档同步：README.txt、DSH.md、project.yaml、tasks/008、tasks/010
 2026-09-15 01:25:19 +08:00