zijunchiang/opendance-web
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 17 Wiki Activity
46 Commits 2 Branches 17 Tags
b7748a50eb47efed79bf47969678b50e4144575e
Commit Graph
46 Commits
This Branch
This Branch
All Branches
Author SHA1 Message Date
opendance b7748a50eb docs: web 端根说明补充 Markdown 版本 README.md 
仓库首页(Gitea/编辑器)以 .md 为准,windows/android 两端都已有
README.md + README.txt 两份,web 端此前只有 README.txt。
本次按同风格补齐 README.md:标题/状态/初次部署/环境变量/API/目录结构
等改为 Markdown 结构(标题层级、表格、带语言的代码块),内容与
README.txt 逐项等价;同时把 README.md 纳入发布包与关键文件校验。
v0.2.0 		2026-09-15 21:53:29 +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
opendance a34cca007c chore(probe): add ambiguous-unicode probes for Gitea highlighter 2026-09-15 21:40:52 +08:00
zijunchiang d61843d068 test: 二分探针 round1（8 段） 2026-09-15 21:38:37 +08:00
zijunchiang f61d40eafc test: 临时 Unicode 探针（用于测定 Gitea 混淆字符判定规则，随后删除） 2026-09-15 21:37:23 +08:00
zijunchiang 06c2fd688b docs: 全角 ｜ ／ ？ 改 ASCII（Gitea 混淆字符检测的剩余触发项） 2026-09-15 21:36:41 +08:00
zijunchiang 6913e181b5 docs: 其余易混淆字符改 ASCII（× − ≥ ≤ ≈ ✓ 等），消除 Gitea 告警 
实测确认 Gitea 的「模棱两可 Unicode」检测覆盖：— – … § → × − ≥ ≤ ≈ ✓。
三库 .md/.txt 全部替换为 x - >= <= ~ OK；contracts 三库同源保持一致。
重新打包 v0.2.0。
 2026-09-15 21:35:10 +08:00
zijunchiang 5de0891706 docs: 修回被误压空格的 ':=' 写法；契约与文档去真实 MariaDB 版本串 
- contracts/websocket-keypoints.md（三库同源）：把上一轮空格清理误伤的
  'var x:= ...' 修回 'var x := ...'，保持文档内代码样例可读
- contracts/rest-api.yaml（三库同源）：'如 MariaDB 10.11.19' -> '如 MariaDB 10.5+'
- DSH.md / tasks/001：去掉真实部署实例版本号，改为'由部署方确认'的表述
- 重新打包 v0.2.0

验证：契约 6 项一致（三库 md5 相同）、30 条路由一致。
 2026-09-15 21:33:20 +08:00
zijunchiang 8c2f2afaea docs: 三库文档规范化（去混淆字符 + 占位符）+ Web README 初次部署清单 
- 三库所有 .md/.txt 与配置样例中的 — – … § → 一律换成 ASCII（Gitea 的
  「模棱两可的 Unicode 字符」告警即由这几个字符触发；中文全角标点不受影响，
  实测 README.txt 修正后告警消失）
- contracts/* 在三库保持逐字节一致（已校验 md5）
- 残留真实值清理：README.txt 建库 SQL 的 dpendance -> opendance/opendance_app，
  Android HostDiscovery.kt 注释示例 192.168.1.23 -> 192.0.2.23
- Web README.txt 新增「初次部署（从零跑起来）」8 步清单与「常见问题（初次部署）」
  7 条；去掉纯文本 README 里的 markdown 粗体标记；统一 '以 root 直接执行' 写法
- 重新打包 v0.2.0

验证：168 项单测通过；契约 6 项与 30 条路由一致。
 2026-09-15 21:28:12 +08:00
zijunchiang ebd871018f docs(readme): 新增初次部署清单与常见问题；统一 root 执行写法；清除 markdown 粗体标记与残留真实库名 2026-09-15 21:27:29 +08:00
zijunchiang 9c8379e5eb docs(readme): 破折号/箭头/省略号/节号改 ASCII，消除 Gitea 混淆字符告警 2026-09-15 21:25:56 +08:00
zijunchiang 9f08d316d0 docs: 清除文档中的真实部署信息与易混淆 Unicode 字符 
需求：公开仓库的说明文档不应暴露开发/部署期信息，且 Gitea 会对 README.txt
报"含模棱两可的 Unicode 字符"。

敏感信息（全部替换为占位符或文档示例值）：
- 真实数据库实例：DB_HOST=192.168.150.10 / DB_USER=dpendance / DB_NAME=dpendance
  → <数据库主机> / opendance_app / opendance（web-server/.env.example、
  deploy/.env.example、contracts/database.md ×3 库、project.yaml、README.txt
  的建库 SQL、tasks/001、tasks/002）
- 内网网段 192.168.150.0/24 / 192.168.150.20 / 192.168.1.10
  → RFC 5737 文档网段 192.0.2.0/24 等（含测试夹具，行为不变）
- 真实 Gitea 域名 → https://<Gitea 地址>/<owner>/<repo>（systemd 单元、
  Windows/Android README 的交叉链接）
- 测试夹具里的真实口令字面量 → 虚构口令（仍覆盖特殊字符场景）
- 保留 /opt/opendance、/var/lib/opendance 等产品默认安装路径（非敏感）

README.txt 易混淆字符：
- 全角拉丁字母（Ｉ/Ｋ 等）与全角 ASCII 标点（（），：；？）→ 半角 + 中文排版空格
- 正文里的乱码字节样例（模å…）→ 改为文字描述
- × → x，★ → *
- 注意：代码/测试/契约里的全角「ＩＫ」是 MMD 真实骨骼名，**必须保留**，
  已回滚误改（mmd-skeleton.ts、mmd-vmd.spec.ts、inspect-vmd.mjs、各契约）

验证：168 项单测通过（含 VMD 31 项，确认全角骨骼名未被破坏）。
 2026-09-15 21:25:25 +08:00
zijunchiang c342a804a1 feat(models): 新增历史模型回填（reanalyze）并修复存储去重的悬挂文件问题 
背景：升级到带 models.stats 的版本后，库里已有模型没有分析与缩略图，
审核界面会全部显示"未分析、无预览图"。E2E 验证时还发现一个真问题：
sha256 去重命中旧资产但文件不存在（换过 STORAGE_DIR、或只恢复数据库）时，
分析会静默产出"全 0 结果"。

- POST /api/models/:id/reanalyze：重新分析（面数/骨骼树/humanoid/可驱动性）
  并重建缩略图，只改 stats 与 thumbnailAssetId；文件在存储中不存在时返回 409，
  避免用空结果覆盖已有分析数据
- scripts/reanalyze-models.mjs：批量回填 CLI（--dry-run / --model-id / --force）
- StorageService.persistBuffer：去重命中但文件不存在时按原路径**自愈补写**
- 契约：rest-api 新增 /api/models/{id}/reanalyze（路由 29 → 30 条）
- 文档：README / tasks/005 / 发布说明补回填章节与升级步骤

实测：真实 21MB VRM（290 骨骼）回填出面数 53552 / 顶点 44662 / humanoid 7/22，
并重建 512×512 缩略图；文件缺失场景返回 409 且不覆盖既有数据。
测试 168 项通过；契约与 30 条路由一致。
 2026-09-15 21:18:15 +08:00
zijunchiang 53bf182476 feat(models): 发布 v0.2.0 —— GLB/VRM 主力格式、自动缩略图与分析、模型审核与骨骼预览 
需求 1：系统确定以 GLB / VRM 为模型主力格式
- 服务端新增支持库：
  - model-inspector.ts：解析 GLB/VRM 的面数、顶点、材质、贴图、形变目标、
    **骨骼树（名称/层级/是否蒙皮/humanoid 映射/子节点数）**、humanoid 覆盖率与可驱动性
  - model-thumbnail.ts：**纯 TS 软件光栅化**（z-buffer + Lambert + 完整蒙皮矩阵）
    生成 512×512 PNG 缩略图，零原生依赖、不装 headless-gl
  - vrm-writer.ts：GLB → VRM 1.0（写入 VRMC_vrm 扩展与 humanoid 映射）
  - gltf-packer.ts：glTF（.gltf + .bin + 贴图）→ 单文件 GLB
- humanoid 候选表与 Godot 客户端 humanoid_map.gd **逐字对齐**，并有单测断言两边一致
  （服务端判定的"可驱动" = 客户端实际能否驱动）

需求 2：模型管理
- .glb / .vrm / .gltf **直接导入**（不重编码，GLB 含 VRM 扩展会自动识别为 VRM）
- .pmx / .fbx 服务端转换：assimp → .glb →（失败）→ .gltf 后自行打包成 GLB
  →（MODEL_CONVERT_FORMAT=vrm 时）补 VRMC_vrm 产出 VRM 1.0；每步 assimp info 回读校验
- .zip **自动搜索包内可用模型**：.vrm → .glb → .gltf（直接导入）优先，
  其次 .pmx → .fbx（转换）；同优先级内按"指名字 → 目录最浅 → 文件最大"
- 入库后自动分析（models.stats）与生成缩略图（models.thumbnail_asset_id），
  失败均不阻断入库；管理端列表显示小缩略图、预览放开到 vrm/glb/gltf

需求 3：审核功能
- 上传的模型状态**一律 pending**（不再自动发布、不再自动设默认）
- 审核界面新增模型面板：体积、面数、顶点、材质、贴图、骨骼、形变目标等指标，
  humanoid 覆盖进度、可驱动性结论（缺哪些必需骨骼）、warnings，以及
  **骨骼详细预览**（层级缩进、蒙皮/Humanoid 徽章、子节点数、搜索保留祖先链、
  仅看蒙皮、限高滚动 + 只渲染前 400 行）
- 审核通过可带 setPrimary=true 一并设为默认模型（此时才写源码种子）；
  POST /api/models/:id/primary 仅允许 published（否则 409）
- scripts/import-default-model.mjs 改为"上传 → 审核通过 + 设默认"流程

其它：
- models 新增 stats 列（迁移 AddModelStats1789460000000，已在真实库执行）
- 契约升至 rest-api/data-models/model-formats 0.4.0、database 0.3.0（另两库已同步）
- 版本号 0.1.0 → 0.2.0（package.json ×2 + lockfile + project.yaml）
- 文档：README.txt / DSH.md / project.yaml / tasks 005·007·010 全面更新；
  顶层开发书更新为 v1.4

验证：168 项单测通过（10 文件）；契约 6 项与 29 条路由一致；typecheck/build 通过；
真实端到端：MMD 压缩包 → GLB + 分析(面数 9071/骨骼 238/humanoid 0-22) + 缩略图(15KB PNG)；
GLB 直接导入 sha256 与源文件一致；审核通过后 defaultModelId 由 VRM 变为该模型
 2026-09-15 20:37:53 +08:00
zijunchiang ccced34dd6 fix(models): 默认模型改用「压缩包 sha256」匹配（转换产物非字节级确定） 
实测发现：同一份 zip 连续转换三次得到三个不同的产物 sha256（大小都是 1,152,464
字节，差异集中在 BIN chunk 的十几字节），说明 Assimp 的 GLB 导出不是字节级确定的。
因此原先把「转换产物 sha256」当作默认模型匹配键的设计是错的——换一次转换就失效。

- default-model.ts / default-model-source.ts：种子拆成 sourceSha256（上传压缩包的
  sha256，稳定，主匹配键）与 fileSha256（产物 sha256，仅作记录）
- models.service.ts：resolveDefaultModelId 依次按 压缩包 sha256 → 产物 sha256 →
  名称 匹配，都落空才回落到 VRM 优先规则并告警
- ModelDto 增加 sourceSha256（非压缩包上传为 null）
- scripts/import-default-model.mjs：写种子时用 sourceSha256；顺带修掉位置参数解析
  （文件当第一个参数时识别不出，会打印用法）
- 契约与文档同步：data-models §4.1、model-formats §1.1 记录该确定性结论；
  README / DSH / tasks/005 的「按产物 sha256 匹配」表述已更正

另附：把模型格式能力的实测矩阵写进 Release 说明（原生只支持 glTF 系；
PMX→FBX 失败；VRM→GLB 丢 VRM 扩展；humanoid 骨骼命名覆盖率）。

验证：125 项单测通过；清理掉两个"文件只在本机临时目录"的模型（避免 sha256 去重
导致后续上传不落盘）；种子按压缩包 sha256 命中后 defaultModelId 正确解析。
 2026-09-15 19:36:37 +08:00
zijunchiang e4351c5062 feat(models): 模型压缩包自动转换 + 默认模型写进源码；首次启动 .env 引导；HOST 默认 0.0.0.0 
需求 1：模型上传支持压缩包（MMD 模型包）
- common/zip-reader.ts：纯 TS 极简 ZIP 读取器（EOCD/中央目录、STORE+DEFLATE、
  ZIP64 大小字段、Shift-JIS/GBK 文件名回退、拒绝 zip-slip 与加密条目）
- models/model-convert.ts：解压 → 选主模型（指名字/最浅/最大）→ Assimp 导出 FBX
  → **assimp info 回读校验**（Assimp 对带蒙皮大骨架模型会写出损坏文件：
  实测 714 骨骼 PMX 导出退出码 11、产物回读报 FBX-DOM no Objects dictionary found）
  → 失败自动回退 GLB；两种都失败则 422
- models/glb-textures.ts：把 Assimp 写成外部 URI 的贴图内嵌进 GLB 的 BIN chunk，
  保证模型库里单文件即可加载（否则是白模）
- 溯源：压缩包原件存为 model-archive 资产；models 新增 source_asset_id /
  conversion_note（迁移 1789450000000-AddModelConversionFields，已在真实库上
  验证 up/down 可逆）
- 默认模型：转换成功且 autoDefault 不为 false → is_primary=1 + published，
  并把身份（名称/格式/产物 sha256）写进源码 src/config/default-model.ts；
  resolveDefaultModelId 增加 DEFAULT_MODEL_ID 与源码种子两步（按 sha256 匹配，
  换库仍有效），实测库中有 2 个 VRM 时默认模型仍解析为该 GLB
- scripts/import-default-model.mjs：运维 CLI（上传 zip 并写源码 / --write-source-only）
- 修复 multipart 中文文件名乱码（upload.util.decodeUploadName）
- DTO/契约新增 conversionNote、fileSha256；管理端 accept 增加 .zip 并展示转换来源

需求 2：首次启动 .env 引导
- deploy/init-env.sh：交互式逐项填写 8 个键（回车保留默认、口令不回显不加引号、
  端口校验、mysql2 连通性自检且口令只经环境变量传递、只改这 8 个键并保留模板注释、
  chmod 600、结尾打码摘要）；--force/--check/-y/-i/--skip-db-check 等开关；
  非交互（-y、OPENDANCE_NONINTERACTIVE、stdin 关闭）绝不提问、读取带超时
- install.sh 缺 .env 时改为调用引导，失败才 die

需求 3：默认监听 0.0.0.0
- 代码默认值、两份 .env 模板、install.sh、init-env.sh 五处一致，并新增测试守护
  （未设置 HOST 时为 0.0.0.0；两份模板都写着 HOST=0.0.0.0）

契约：rest-api / data-models / model-formats → 0.3.0，database → 0.2.0（另两库已同步）

验证：125 项单测通过（7 文件）；契约 6 项与 29 条路由一致；typecheck/build 通过；
真实包端到端 HTTP 201 / 0.89s / format=glb / isPrimary=true / published；
GLB 1,152,464 字节、1 mesh / 240 nodes / 1 skin(238 joints) / 2 张内嵌贴图；
迁移 revert→run 实测可逆且数据无损恢复
 2026-09-15 13:55:54 +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 76725e5ce3 feat(log): 启动日志打印真实可访问地址，回环绑定时显式告警 
绑定 0.0.0.0 时日志直接拼 http://0.0.0.0:3000——浏览器打不开，
排障时只会看到"已启动"却不知道访问哪个 IP。

- 新增 src/config/access-hint.ts：describeAccess() 把绑定地址翻译成
  监听描述 + 可访问地址（回环 / 具体网卡 / 通配取真实网卡 IPv4）；
  独立成模块是为了可测——main.ts 顶层会执行 bootstrap()，不能被 import
- main.ts：启动日志改为「监听 …（全部网卡，外部可访问）」+ 真实访问地址；
  HOST=127.0.0.1 时用 warn 明确提示"只能本机访问"并给出修复方法
- 新增 test/access-log.spec.ts（4 项）覆盖三种绑定模式，
  断言通配模式绝不出现 0.0.0.0 形式的 URL

实测三种模式日志输出正确；单测 35/35、契约与 29 条路由校验通过。
 2026-09-15 02:04:51 +08:00
zijunchiang 44451028dd fix(deploy): 安装脚本按真实 HOST 报告监听地址，并主动提示外部不可达 
背景：旧版 .env.example 的 HOST=127.0.0.1 会让服务只监听回环，
本机 curl 一切正常、安装日志毫无异常，但外部永远连不上。

install.sh 修复：
- 不再写死 API_HOST=127.0.0.1：从 deploy/.env 读 HOST 得到 BIND_HOST，
  绑定具体网卡时用该地址做健康检查（原来用回环会误判启动失败）
- 汇总输出改为真实监听地址 + 按三种绑定模式给出正确 URL
  （回环写 127.0.0.1、具体网卡写该地址、通配写探测到的对外 IP）
- 新增安装期外部可达性自测：用对外 IP 请求 /health，
  只监听回环 → 打印改 HOST 与重启命令；
  监听正常但自测失败 → 打印防火墙 / 云安全组放行步骤
- 反代提示里回显当前 HOST 实际值，避免照抄"建议 127.0.0.1"改坏配置

README.txt 同步说明。验证：用真实脚本片段 + 打桩跑四种场景
（回环 / 通配可达 / 通配被防火墙拦 / 指定网卡），输出逐一核对。
 2026-09-15 01:48:04 +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 321ab1f584 docs(web): 清理 Docker/nginx 残留引用，反代职责边界写进任务书与契约 
- tasks/010-deploy.md: 按"仅业务服务、不部署反代、服务自托管管理端"重写，
  补充四层进程降级、无 sudo 降权、上传上限两侧一致等实现说明与验收表
- deploy/uninstall.sh: 删除 nginx 站点清理逻辑（本项目从未安装过反代，
  也不应改动运维侧的 nginx / IIS 配置）
- scripts/package-release.sh: 修正产物结构注释，去掉已删除的
  web-server/admin/nginx.conf 拷贝与 deploy/nginx 备份清理
- web-server/.env.example: 修正"容器内路径 / docker-compose 挂载"过时注释
- contracts/rest-api.yaml: 服务地址描述改为业务服务部署语义
 2026-09-15 01:27:47 +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
zijunchiang 653d9d168c feat(deploy): 缺少 deploy/.env 时复用安装目录中的历史配置 
用户在重新解压发布包后再次执行 install.sh，因缺少 deploy/.env 被拦下。
按文档流程每次升级都要重新解压，若每次都要求重填数据库口令，既繁琐
又容易出错（口令含 * 等特殊字符）。

- 优先使用当前目录的 deploy/.env
- 其次复用 $APP_DIR/deploy/.env（上次安装留下的配置）
- 两处都没有才报错，且错误信息列出需要填写的五个字段及注意事项

实测三种情形：
  全新安装（两处都无）→ 报错并给出字段说明，退出码 1
  安装目录有历史配置   → 自动复用，退出码 0
  当前目录已有 .env    → 直接使用，不覆盖
 2026-09-15 01:03:20 +08:00
zijunchiang 87a1ded2d2 fix(deploy): install.sh 复制时同样误排除了 storage 目录 
用户重装后仍报同一错误，且日志显示「复制 web-server … 174 个文件」。
经复现：发布包内 web-server 有 180 个文件（含 src/storage 2 个、
dist/storage 4 个），但 install.sh 复制后只剩 174 个——storage 被剔除了。

根因：上一轮只修了 package-release.sh，install.sh 里**还有一份独立的
copy_tree() 排除规则**，其中 'storage' 同样未锚定。install.sh 的
COPY_EXCLUDES 与 tar 回退分支都把 'storage' 当作任意层级模式，
于是 src/storage 与 dist/storage 在复制进 /opt/opendance 时被剔除。

这是同一类错误在本项目的第三次（.gitignore → package-release.sh →
install.sh）。因此这次不再只改模式，而是把语义显式化并加硬校验：

- 排除规则拆成三类常量，语义明确：
    TOP_DIRS  仅顶层：storage data tmp dist-release   → 必须锚定
    ANY_DIRS  任意层级：node_modules .git coverage .gradle
    TOP_FILES 仅顶层文件：.env .env.local
- rsync 用前导 '/' 锚定；tar 对 TOP_* 只给 './x'（绝不给 '*/storage'），
  对 ANY_* 才给 './x' + '*/x'
- 复制后硬校验关键产物（dist/main.js、dist/storage/storage.module.js、
  dist/app.module.js、admin/index.html），缺失即 die 并指出是排除规则问题

实测：
- rsync 路径：180 文件，src/storage 与 dist/storage 均在，
  运行时 storage 与 .env 未带入，.env.example 保留
- tar 回退路径（隔离 PATH 屏蔽 rsync 后真跑）：同样 180 文件，存储目录完整
- git 检出布局：214 文件，嵌套 admin/node_modules 未带入，本地 .env 未带入
- 对照实验：把锚定改回未锚定 → 复制剩 174 文件 → 守卫立刻报
  「缺少关键文件 dist/storage/storage.module.js」并终止，不再拖到启动才炸
 2026-09-15 01:00:58 +08:00
zijunchiang caca7672cb fix(release): 修复发布包缺失 storage 模块，并加入产物完整性校验 
用户实测：用发布包部署后启动报 MODULE_NOT_FOUND
  at dist/models/models.module.js:13  require('../storage/storage.module')

根因：package-release.sh 的 rsync 用了 --exclude 'storage'。该模式匹配
**任意层级**的同名目录，把源码目录 src/storage/ 与编译产物 dist/storage/
一并排除——发布包里完全没有 storage 模块，服务必然起不来。
这与第一阶段 .gitignore 里 'storage/' 误伤 src/storage/ 是同一类错误，
本项目第二次踩到。

修复：
- 排除模式全部锚定到 web-server 根：'/storage/'、'/data/'、'/tmp/'、
  '/.env'、'/admin/'，不再匹配嵌套同名目录
- 新增产物完整性校验（打包后自动执行，失败即删除压缩包）：
  src 下每个 .ts 必须有对应 dist/*.js；关键文件清单齐全；
  不得混入 node_modules / 真实 .env / 运行时存储 / keystore
- ctl.sh 补上缺失的 warn 函数（line 120: warn: command not found）

实测：
- 对照实验：排除模式改回 'storage' 后校验准确报出缺少
  dist/storage/storage.module.js 并删除压缩包，退出码 1
- 新包端到端：解压 → npm ci --omit=dev（213 包）→ 启动 → /health 200、
  MariaDB 已连接、迁移 0、catalog/songs/models/motions 全部 200
 2026-09-15 00:54:22 +08:00
zijunchiang f6fe9af0a2 fix(deploy): 修复 NODE_ENV 污染导致管理端构建失败（tsc: not found） 
用户实测：部署时构建管理端报 `sh: 1: tsc: not found`，且 npm 只装了 23 个包。

根因：脚本开头用 `set -a; . deploy/.env; set +a` 载入 .env，其中的
NODE_ENV=production 被导出到脚本自身环境；npm 见到它便会跳过
devDependencies，于是 typescript / vite / nest 等构建工具全部缺失。
本地实测完全复现：
  NODE_ENV=production npm ci          → added 23 package，无 tsc
  env -u NODE_ENV npm ci --include=dev → added 53 package，tsc/vite 齐备

修复：
- 新增 npm_install_with_dev()：统一用 `env -u NODE_ENV npm ... --include=dev`
- 管理端构建改用它；**API 构建回退路径存在同一隐患，一并修复**
- 管理端改为在 $APP_DIR/web-server/admin 内构建（不再污染源码树、
  也不要求源码目录可写），构建完删除该处 node_modules 释放磁盘
- 构建失败时给出可操作提示（改用发布包）

另修复一处静默的信息泄露：
- 复制源码树时未排除 .env，本地开发用的 web-server/.env（含真实数据库
  口令）会被复制进 /opt/opendance/web-server/.env；deploy/.env 才是权威配置，
  多一个 dotenv 配置源只会造成排障困惑。已把 .env / .env.local 加入排除，
  并验证 .env.example 不受影响（209 → 208 个文件）

实测：
  旧行为 tsc 缺失、构建报 tsc: not found（与用户报错一致）
  新行为 tsc/vite 齐备，vite build 成功产出 dist/index.html + 3 个 assets
  复制排除：.env 不复制、.env.example 保留、node_modules 无泄漏
 2026-09-15 00:44:54 +08:00
zijunchiang c092b833fb fix(deploy): 支持无 systemd 的环境，并修复降级路径的两个真实缺陷 
用户实测：服务器没有 systemctl，install.sh 直接报错退出。

原错误信息本身也是错的（建议 SKIP_NGINX=1，但那只跳过 nginx，仍走 systemctl）。

进程管理改为四层降级：
  systemd → OpenRC → SysVinit → nohup 后台进程（deploy/ctl.sh）
- 新增 deploy/ctl.sh：start/stop/restart/status/logs，PID 文件 + 进程名双重判定
- 新增 deploy/openrc/opendance-api、deploy/initd/opendance-api
- 无 init 系统时写 crontab @reboot 实现开机自启
- uninstall.sh 同步支持四种模式清理（原先只处理 systemd，会留下运行中的进程）
- 汇总输出按实际初始化系统给出对应运维命令

测试中发现并修复降级路径的两个真实缺陷：

1. nohup 无法调用 shell 函数
    实测退出码 127 且什么都不执行
   （nohup 是外部命令，只能执行可执行文件）。
   这会让无 systemd 的降级路径完全失效——服务根本起不来。
   改为按 runuser / setpriv / su 显式拼接成外部命令后再 nohup。
   另加启动后 1 秒存活检测，失败立即打印日志，不再白等 30 秒。

2. find_pids 在无进程时返回一个空格
    在空输入下仍会执行一次 echo，输出空行，
   最终得到 " "；调用方 [ -n ... ] 会判为「有进程」，
   导致 start 直接跳过、status 谎报运行中。改为纯 bash 拼接，空时返回空串。

实测（真实 API 进程，端口 3100）：
  start → 健康检查 200，PID 正确
  重复 start → 识别已在运行，进程数保持 1
  status → 运行中
  restart → 新 PID，健康检查 200
  stop → 无残留进程，端口释放
  无 process 时 find_pids 返回空串，is_running=false
 2026-09-15 00:34:52 +08:00
zijunchiang 1ffe3059af fix(deploy): install.sh 不再依赖 sudo 
用户实测报错：deploy/install.sh: line 173: sudo: command not found

本脚本已经强制要求 root 权限，用 sudo 降权到服务用户本就多余，
且部分服务器（尤其精简系统/容器）根本没有安装 sudo。

- 新增 as_service_user()：runuser → setpriv → su 依次回退，
  并在三者都不可用时给出明确错误
- 替换全部 sudo -u 调用（npm ci / npm install / npm run build / 迁移）
- 新增 http_get() / http_ok()：curl → wget → node fetch 依次回退，
  健康检查不再强依赖 curl
- 启动前检查 systemctl（本部署依赖 systemd），缺失时给出可操作提示
- 修正 install.sh / uninstall.sh 中所有「用 sudo 执行」的提示文案

实测（桩替换 runuser 验证分派与参数传递）：
  有 runuser：runuser -u opendance -- npm ci --omit=dev --loglevel=error
  仅 su：正确回退到 su
  HTTP：curl 路径与 node fetch 回退路径返回一致
 2026-09-15 00:27:27 +08:00
zijunchiang 7cd607ecde fix(deploy): 修复 install.sh 同步文件时的长时间卡死 
用户实测：执行到「同步程序文件到 /opt/opendance」后卡死。

根因：在源码检出目录执行时，web-server/ 下有 node_modules（236MB /
27359 个文件，admin 下还有 122MB），原实现用 cp -r 全量复制，
随后又对整个目录 chown -R，处理三万个文件表现为卡死。

修复：
- 复制改用 copy_tree()，排除 node_modules/.git/storage/dist-release 等
  运行期可再生目录；有 rsync 用 rsync -a --delete，否则用 tar 管道回退
- tar 回退的排除模式同时给出 './x' 与 '*/x'：只写 './x' 无法匹配嵌套的
  './admin/node_modules'（实测会漏掉 122MB，等于没修）
- 增加目录安全检查：安装目录与源目录相同、或二者互相包含时直接报错退出，
  避免 rm -rf 删掉源文件 / cp 无限递归
- 支持两种目录布局：发布包 admin/ 在根目录，源码检出在
  web-server/admin/dist（缺失则现场构建），此前从源码目录执行必然在
  「缺少 admin/ 目录」处失败
- 每个目录打印复制结果与文件数，npm 安装前给出预计耗时提示，
  不再有长时间无输出的「假卡死」
- 失败时 trap 打印行号

实测（用脚本中真实代码块驱动的用例）：
  源码检出目录 → /tmp：rsync 路径 1 秒 / 209 文件；tar 回退路径同样 209 文件
  发布包解压目录 → /tmp：0 秒，admin 与 dist/main.js 均正确
  同目录 / 嵌套目录两种危险布局：均被拒绝并给出可操作提示
  两条路径均无 node_modules 泄漏
 2026-09-15 00:14:06 +08:00
zijunchiang 32525dd59a docs(web): 清理残留的 Docker 引用（admin README / project.yaml / 注释） 2026-09-14 22:47:47 +08:00
zijunchiang 07ee30d704 docs(web): 开发环境样例补充 HOST 说明 2026-09-14 22:45:31 +08:00
zijunchiang 75498db1c0 feat(web): 部署方式由 Docker 改为 Linux 原生站点（nginx + systemd） 
需求变更：Web 服务端不再使用 Docker，改为直接运行在 Linux 上的网站。

- 移除 deploy/docker-compose.yml、web-server/Dockerfile、
  web-server/admin/Dockerfile、web-server/.dockerignore
- 新增 deploy/install.sh：建服务用户与目录 → 装运行期依赖 → 迁移
  → 注册 systemd 服务 → 配置 nginx 站点 → 健康检查，一键完成
- 新增 deploy/systemd/opendance-api.service：ProtectSystem=strict 等
  安全加固，ReadWritePaths 限定为上传目录
- 新增 deploy/nginx/opendance.conf：同站点托管管理端静态资源 +
  反代 /api /health /static，client_max_body_size 512m，SPA 回退
- 新增 deploy/uninstall.sh：默认保留数据，--purge 才删除
- 新增配置项 HOST（AppConfig.bindHost）：原生部署下 Node 只监听
  127.0.0.1，不直接对外暴露，实测外部 IP 不可达
- 同步更新 contracts/rest-api.yaml、DSH.md、project.yaml、README.txt、
  tasks/008、tasks/010 与发布打包脚本
 2026-09-14 22:42:56 +08:00
zijunchiang 0c133986b4 test(web): 新增演示数据播种脚本（供管理端与客户端联调） 2026-09-14 20:08:20 +08:00
zijunchiang dbd9155b40 fix(release): 打包清单读取避免 SIGPIPE 误报 v0.1.0 2026-09-14 19:01:58 +08:00
zijunchiang b9215d4190 docs(web): 任务说明、DSH 约束与交付文档 2026-09-14 19:00:55 +08:00
zijunchiang 5a8b77b0a4 feat(web): T-WEB-010 部署脚本（Docker Compose，不含 MySQL） 2026-09-14 19:00:55 +08:00
zijunchiang 640736c77b feat(web): T-WEB-008/009 管理端界面（歌曲/模型/动作/审核 + VRM 预览） 2026-09-14 19:00:55 +08:00
zijunchiang 0f66b53480 feat(web): 客户端目录导出 /api/catalog/export 与版本指纹 2026-09-14 19:00:55 +08:00
zijunchiang 7ff3f1598d feat(web): T-WEB-007 上传审核流程（状态机 + 审核流水） 2026-09-14 19:00:55 +08:00
zijunchiang a2e3282603 feat(web): T-WEB-006 BVH/FBX → MediaPipe33 关键点预处理 2026-09-14 19:00:55 +08:00
zijunchiang 73e793318e feat(web): T-WEB-005 模型上传 + VRM 优先 + 版本识别 2026-09-14 19:00:55 +08:00
zijunchiang ff8c4dd26a feat(web): T-WEB-004 动作数据上传 + 来源五元组校验 2026-09-14 19:00:55 +08:00
zijunchiang d9614aadb0 feat(web): T-WEB-003 /api/songs CRUD + 音频上传 2026-09-14 19:00:55 +08:00
zijunchiang 6714b1e67c feat(web): T-WEB-002 TypeORM 迁移生成表结构（5 表，可逆） 2026-09-14 19:00:55 +08:00
zijunchiang bd6cb9fa90 feat(web): T-WEB-001 NestJS 骨架 + 连接现有 MySQL 实例 2026-09-14 19:00:55 +08:00
zijunchiang 9b8fc6be96 chore(contracts): 冻结 v0.1.0 跨端契约（REST/WebSocket/数据模型/拓扑/格式/数据库） 2026-09-14 19:00:55 +08:00