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
parent bba5bcf59e
commit e4351c5062
34 changed files with 3204 additions and 65 deletions
@@ -23,12 +23,21 @@ Web 服务端以**一个 Linux 业务服务**的形式部署运行：Node 进程
 >    只给客户端调接口（`/api`、`/health`、`/static`、`/contracts`，`/` 等返回 404），
 >    管理端端口给浏览器（管理页面 + 全部接口）。`ADMIN_PORT === PORT` 保留为
 >    单端口兼容模式，只 warn 不中止。install.sh 的汇总与反代说明改为两个端口。
+> 4. 本次追加两项：
+>    a) **首次启动的 .env 引导**：新增 `deploy/init-env.sh`（交互式逐项询问数据库
+>       与端口，写盘前校验必填项/端口范围，可用 Node + mysql2 做连通性自检）；
+>       `install.sh` 在缺 `deploy/.env` 时先调用它，失败才 die（安装目录已有上次
+>       安装留下的 .env 则直接复用，保持原语义）。
+>    b) **默认监听 0.0.0.0 固化**：确认 `configuration.ts` 的
+>       `bindHost = process.env.HOST ?? '0.0.0.0'`、`adminHost` 默认跟随 HOST，
+>       两个 `.env.example` 与 `init-env.sh` 的 HOST 默认值均为 `0.0.0.0`。

 ## load

 ```
 DSH.md
 contracts/database.md
+deploy/init-env.sh
 deploy/install.sh
 deploy/uninstall.sh
 deploy/.env.example
@@ -66,7 +75,8 @@ Windows/Godot 客户端、Android App ─▶ 软件 API 端口 :3000（只提供

 | 文件 | 说明 |
 |---|---|
-| `deploy/install.sh` | 一键部署：前置检查 → 建用户/目录 → 复制并校验文件 → 装依赖 → 迁移 → 注册系统服务 → 健康检查；汇总打印两个端口与防火墙放行提示 |
+| `deploy/install.sh` | 一键部署：前置检查 → 建用户/目录 → 复制并校验文件 → 装依赖 → 迁移 → 注册系统服务 → 健康检查；汇总打印两个端口与防火墙放行提示；缺 `deploy/.env` 时先调用 `init-env.sh` 引导 |
+| `deploy/init-env.sh` | **首次启动的 `.env` 交互引导**：逐项询问 8 个键、写盘前校验必填项与端口范围、可选数据库连通性自检；只替换/追加这 8 个键并保留模板注释，写完 `chmod 600` 并回读；`--check` / `-y` 等非交互模式下绝不阻塞 |
 | `deploy/uninstall.sh` | 卸载；默认保留上传数据，`--purge` 才删除 |
 | `deploy/.env.example` | 部署环境变量样例（`PORT` / `ADMIN_PORT` / `ADMIN_HOST` / `HOST` 说明与上传上限告警） |
 | `deploy/systemd/opendance-api.service` | systemd 单元，含 `ProtectSystem=strict` 等安全加固 |
@@ -77,6 +87,53 @@ Windows/Godot 客户端、Android App ─▶ 软件 API 端口 :3000（只提供
 | `deploy/proxy/nginx.conf.example` | nginx 配置样例（上传上限、超时、keepalive、可选 HTTPS） |
 | `deploy/proxy/web.config.example` | IIS 配置样例（需 ARR + URL Rewrite 模块） |

+## deploy/.env 初始化引导（init-env.sh）
+
+首次部署不再要求手工 `cp deploy/.env.example deploy/.env && vi deploy/.env`：
+
+```
+install.sh 检测到缺 deploy/.env
+   ├── $APP_DIR/deploy/.env 存在 → 直接复用（上次安装留下的配置，原语义保留）
+   └── 否则调用 deploy/init-env.sh
+         ├── 缺 .env → 从 .env.example 复制，chmod 600
+         ├── 交互（TTY / 管道）→ 逐项询问并写回
+         └── 非交互（CI、</dev/null、-y）→ 只校验，绝不阻塞；失败则 install.sh die
+```
+
+逐项询问 `DB_HOST / DB_PORT / DB_USER / DB_PASS / DB_NAME / PORT / ADMIN_PORT / HOST`
+共 8 个键，回车保留默认；`DB_PASS` 用 `read -rs` 不回显、按约定写盘**不加引号**；
+校验必填项与端口范围；可用 Node + mysql2 做连通性自检（口令只经环境变量传给子进程，
+失败仅告警）；只替换/追加这 8 个键、保留模板注释，写完 `chmod 600` 并回读校验；
+结尾打印摘要（口令 `***`）与本次变更列表。
+
+| 开关 | 说明 |
+|---|---|
+| （无） | 交互引导；`.env` 已存在且必填项齐全时跳过询问 |
+| `--force` | 已有 `.env` 也重新逐项询问 |
+| `--check` | 只校验，不修改文件、不提问 |
+| `-y` / `--yes` / `--non-interactive` | 非交互：只校验缺字段与端口，绝不提问 |
+| `-i` / `--interactive` | 即使 stdin 不是 TTY 也强制提问（读取超时仍生效） |
+| `--skip-db-check` | 跳过数据库连通性自检 |
+| `--dir DIR` | 等价于 `--env-file DIR/.env --example DIR/.env.example` |
+| `--env-file PATH` / `--example PATH` | 指定 `.env` / 模板路径 |
+| `--timeout SECONDS` | 非 TTY 下每次读取超时秒数（默认 10） |
+| `-h` / `--help` | 显示帮助 |
+
+环境变量：`OPENDANCE_NONINTERACTIVE` / `OPENDANCE_INTERACTIVE` /
+`OPENDANCE_SKIP_DB_CHECK` / `OPENDANCE_ENV_FILE` / `OPENDANCE_ENV_EXAMPLE` /
+`OPENDANCE_PROMPT_TIMEOUT`。
+
+**非交互绝不挂住**：stdin 非 TTY 且是 `</dev/null` 或已关闭，或带 `-y` 等开关 →
+只校验不提问；所有 read 带超时，EOF/超时立即 `exit 1`。
+
+**默认监听 0.0.0.0**：`configuration.ts` 的
+`bindHost = process.env.HOST ?? '0.0.0.0'`，`adminHost` 默认跟随 `HOST`
+（HOST 未设置时同样回落 `0.0.0.0`）；`deploy/.env.example` 与
+`web-server/.env.example` 均写 `HOST=0.0.0.0`；`install.sh` 的
+`BIND_HOST="${HOST:-0.0.0.0}"`；`init-env.sh` 的 HOST 默认值也是 `0.0.0.0`。
+注意 `install.sh` 里的 `HEALTH_HOST` / `API_HOST` 用的是**回环地址**做本机健康检查，
+与对外监听的默认值无关。
+
 ## 进程管理：四层降级

 "运行在 Linux 上"不应等于"必须有 systemd"。安装时按以下顺序探测并选择：
@@ -110,6 +167,9 @@ Windows/Godot 客户端、Android App ─▶ 软件 API 端口 :3000（只提供
 - **`HOST` / `ADMIN_HOST` 绑定地址**：同机反代建议 `127.0.0.1`，异机反代用
  `0.0.0.0` + 防火墙；`ADMIN_HOST` 可选（默认跟随 `HOST`），可单独把管理端限制在
  本机或内网；`HOST` 默认取 `0.0.0.0` 以保证开箱可用
+- **首次部署的 .env 由引导生成**：`install.sh` 缺 `deploy/.env` 时先调用
+  `deploy/init-env.sh`（安装目录已有上次安装的 `.env` 则直接复用）；引导脚本在
+  非交互环境下只校验、绝不阻塞，校验失败时 install.sh 才 die
 - **端口校验**：`PORT` / `ADMIN_PORT` 必须是 1..65535 的整数；非法值在生产环境
  启动时快速失败（`validateEnv` 的 errors），`ADMIN_PORT === PORT` 只 warn
 - **install.sh 汇总与反代说明**：结尾分别打印两个端口的访问地址、监听配置与
@@ -130,7 +190,7 @@ Windows/Godot 客户端、Android App ─▶ 软件 API 端口 :3000（只提供
 ## 验收

 ```bash
-cp deploy/.env.example deploy/.env   # 填写 DB_*
+bash deploy/init-env.sh              # 或手工 cp deploy/.env.example deploy/.env 后填写 DB_*
 bash deploy/install.sh               # 需 root（不需要 sudo）
 curl -fsS http://localhost:3000/health
 curl -fsS http://localhost:3001/health
@@ -152,6 +212,9 @@ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3001/   # 期望 200
 | 不部署、不管理 MySQL | ✅ 部署脚本不含任何数据库安装/建库操作 |
 | 不使用 Docker | ✅ 仓库内已无 Dockerfile / docker-compose / Docker 引用 |
 | 不部署反向代理 | ✅ 仅交付 `deploy/proxy/` 文档，install.sh 中无任何反代安装动作 |
+| 缺 `deploy/.env` 时由 `init-env.sh` 引导 | ✅ 交互逐项询问 8 个键；只改这 8 个键、保留模板注释、`chmod 600`、回读校验；安装目录已有 `.env` 时直接复用 |
+| `init-env.sh --check` / 非交互不阻塞 | ✅ `test/init-env.spec.ts`（16 项）覆盖 `--check`、`-y`、EOF/超时立即退出、口令不加引号写盘 |
+| `HOST` 默认 `0.0.0.0` | ✅ `configuration.ts`、`deploy/.env.example`、`web-server/.env.example`、`install.sh`、`init-env.sh` 五处一致 |

 > **环境限制说明**：本次执行环境**无 root 权限**，且**未安装 nginx**（按需求也不应安装）。
 > 因此 `deploy/install.sh` 的服务注册链路（systemd / OpenRC / SysVinit / crontab）
@@ -163,6 +226,8 @@ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3001/   # 期望 200
 > - `npm run migration:run` 走编译产物成功
 > - 端到端冒烟 57 项全通过
 > - `install.sh` / `uninstall.sh` / `ctl.sh` 通过 `bash -n` 语法校验
+> - `init-env.sh` 通过 `bash -n`，并由 `test/init-env.spec.ts`（16 项）覆盖
+>   交互写回 / `--check` / 非交互 / 超时 / 幂等 / 口令不加引号
 > - 反代文档中的占位符与后端实际行为逐条对照（两个端口、路径、上传上限、健康检查）
 >
 > 需在一台有 root 的 Linux 服务器上补做一次 `install.sh` 实机验收。