fix(deploy): .env 中带空格的值未加引号导致 install.sh 以 127 失败

现象：
  ./deploy/.env: line 53: Miku.pmx: command not found
  [install] 第 53 行执行失败（退出码 127）

根因：deploy/.env.example 的 MODEL_CONVERT_PMX=Hatsune Miku.pmx 值含空格
却没加引号，install.sh 用 `set -a; . deploy/.env` 载入时被切成
「赋值 + 命令」，Miku.pmx 被当成命令执行。

修复：
1. 模板改为 MODEL_CONVERT_PMX="Hatsune Miku.pmx"（占位符值同样加引号）；
2. 新增 deploy/env-lib.sh：.env 语法预检，install.sh / ctl.sh 在 source
   之前检查，报错给出「哪一行 / 原文 / 改法」， 与反引号建议单引号；
3. install.sh 的 ERR trap 补上出错文件名（lineno 属于被 source 的 .env，
   只报行号无法定位）；
4. 新增 test/env-file.spec.ts 12 项回归测试，锁住「模板可被 shell 原样载入」；
5. 版本升到 0.2.1，README(.md/.txt)/DSH.md 补 .env 写法约定、FAQ 与测试数量。

DSH.md

@@ -101,7 +101,7 @@ opendance-web/
 │   ├── admin/                   # React 管理端
 │   │   ├── src/components/ModelReviewPanel.tsx  # 模型审核面板 + 骨骼详细界面
 │   │   └── src/lib/bone-tree.ts                 # 骨骼树过滤（搜索保留祖先链）
-│   ├── test/                    # 单元测试 + 端到端冒烟（10 文件 / 168 项）
+│   ├── test/                    # 单元测试 + 端到端冒烟（11 文件 / 180 项）
 │   │                            #   mmd-vmd 31 / model-archive 24 / model-inspector 25
 │   │                            #   / model-thumbnail 8 / admin-bone-filter 8
 │   │                            #   / preprocess 25 / init-env 16 / admin-port 16
@@ -111,6 +111,7 @@ opendance-web/
 │                                #   / import-default-model.mjs（默认模型导入 / 补写源码）
 ├── deploy/                      # ★ 业务服务部署（不含 MySQL、不含反代）
 │   ├── init-env.sh              # ★ 首次启动的.env 交互引导（install.sh 缺.env 时调用）
+│   ├── env-lib.sh               # ★ deploy/.env 语法预检（被 install.sh / ctl.sh 引用）
 │   ├── install.sh               # 一键部署（systemd / OpenRC / SysVinit / 后台进程）
 │   ├── uninstall.sh
 │   ├── ctl.sh                   # 无 init 系统时的进程控制
@@ -333,12 +334,18 @@ POST /api/models ─┬─.glb /.vrm /.gltf ─▶ importModelFile()   直接导
   T-pose 角色图；真实 10MB VRM(83 关节、5307 顶点)单张耗时 60-121ms（中位 79ms）。
 - 管理端 3D 预览放开到 `vrm/glb/gltf`(`fbx` 仍提示"仅归档，请先转换为 GLB/VRM");
   列表页显示 40px 缩略图。
-- 测试：`npx vitest run` -> **10 个文件 / 168 项通过**
+- 测试：`npx vitest run` -> **11 个文件 / 180 项通过**
   (`model-inspector` 25、`model-thumbnail` 8、`admin-bone-filter` 8、
   `model-archive` 24、`mmd-vmd` 31、`preprocess` 25、`init-env` 16、
   `admin-port` 16、`access-log` 9、`vrm-inspector` 6）。
 
-## 12. 首次启动的.env 引导（deploy/init-env.sh）与监听地址
+## 12. 首次启动的.env 引导（deploy/init-env.sh）、.env 预检与监听地址
+
+- `deploy/env-lib.sh`: `.env` 语法预检。`install.sh` / `ctl.sh` 用
+  `set -a; . deploy/.env` 载入配置时 shell 会真的执行该文件，值含空格却未加引号
+  会被切成「赋值 + 命令」（实测报 `line 53: Miku.pmx: command not found`，退出码 127）。
+  两个脚本在 source 之前调用预检，输出「哪一行、原文、改法」；
+  模板中带空格的值统一写成 `MODEL_CONVERT_PMX="Hatsune Miku.pmx"`。
 
 - `deploy/init-env.sh`：交互式逐项询问 `DB_HOST / DB_PORT / DB_USER / DB_PASS /
   DB_NAME / PORT / ADMIN_PORT / HOST`，回车保留默认；口令 `read -rs` 不回显、

README.md

@@ -10,7 +10,14 @@ OpenDance Studio **阶段一**: Web 管理服务端(NestJS + TypeORM + 现有 My
 
 ## 状态
 
-**阶段一已完成**: T-WEB-001 -> T-WEB-010 全部落地,当前版本 **v0.2.0**(契约 `rest-api / data-models / model-formats 0.4.0`、`database 0.3.0`)。
+**阶段一已完成**: T-WEB-001 -> T-WEB-010 全部落地,当前版本 **v0.2.1**(契约 `rest-api / data-models / model-formats 0.4.0`、`database 0.3.0`)。
+
+v0.2.1 修订:
+
+1. **修复部署失败**:`deploy/.env.example` 里 `MODEL_CONVERT_PMX=Hatsune Miku.pmx` 的值含空格却没加引号,`install.sh` 用 `set -a; . deploy/.env` 载入时把 `Miku.pmx` 当命令执行,报 `command not found`(退出码 127);模板改为带引号写法;
+2. **新增 `.env` 语法预检**(`deploy/env-lib.sh`):`install.sh` 与 `ctl.sh` 在 source 之前先检查,直接给出哪一行、原文、改法,不再出现看不懂的 127 报错;
+3. 安装失败提示带上出错文件名(`.env` 被 source 时行号属于 `.env`,只报行号无法定位);
+4. 新增 12 项回归测试(`test/env-file.spec.ts`),锁住「模板可被 shell 原样载入」这条线。
 
 v0.2.0 主要变更:
 
@@ -35,18 +42,18 @@ v0.2.0 主要变更:
 2. 准备一个现有的 MySQL / MariaDB 实例,并建好库与账号(见下方[前置要求](#前置要求))
    本项目**不会创建数据库本身**
 
-3. 取得发布包并校验(地址用你们自己的制品库替换)
+3. 取得发布包并校验(地址用你们自己的制品库替换; 下面是本仓库的发布地址)
 
    ```bash
-   curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.2.0/opendance-web-v0.2.0.tar.gz
-   curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.2.0/SHA256SUMS
+   curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.2.1/opendance-web-v0.2.1.tar.gz
+   curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.2.1/SHA256SUMS
    sha256sum -c SHA256SUMS      # 期望输出 "OK"
    ```
 
 4. 解压并生成配置(交互式引导,逐项问答,口令不回显)
 
    ```bash
-   tar -xzf opendance-web-v0.2.0.tar.gz && cd opendance-web-v0.2.0
+   tar -xzf opendance-web-v0.2.1.tar.gz && cd opendance-web-v0.2.1
    bash deploy/init-env.sh
    ```
 
@@ -113,8 +120,8 @@ FLUSH PRIVILEGES;
 ### 5. 部署步骤
 
 ```bash
-tar -xzf opendance-web-v0.2.0.tar.gz
-cd opendance-web-v0.2.0
+tar -xzf opendance-web-v0.2.1.tar.gz
+cd opendance-web-v0.2.1
 bash deploy/init-env.sh         # 首次启动引导: 逐项问答生成 deploy/.env(见下)
 bash deploy/install.sh          # 已以 root 登录, 不需要 sudo
 ```
@@ -255,6 +262,7 @@ bash /opt/opendance/deploy/ctl.sh status | restart | logs
 | 服务本机 curl 通、外部访问不了 | `bash deploy/check-access.sh` 一次定位:打印 `HOST`/`PORT`、实际监听地址、对外 IP 自测、80/443 有无反代、防火墙放行情况,并给出修复命令 |
 | 管理页面打开是 404 | 说明访问的是软件 API 端口(默认 3000);管理页面在管理端端口(默认 3001) |
 | 上传 `.zip` 模型包报 422 且提示 Assimp 不可用 | PMX/FBX 转换依赖 Assimp:`apt-get install -y assimp-utils libassimp6`;只上传 `.glb` / `.vrm` 则不需要它 |
+| 安装时报 `command not found` / 退出码 127,且提示指向 `deploy/.env` 某一行 | 该行的值含空格或 shell 元字符却没加引号,被 shell 当成命令执行了。按预检提示给这个值加引号(如 `MODEL_CONVERT_PMX="Hatsune Miku.pmx"`)后重跑;`deploy/env-lib.sh` 会提前拦住并给出行号 |
 | 模型审核界面显示"未分析 / 无预览图" | 该模型是升级前入库的:调 `POST /api/models/<id>/reanalyze`,或批量跑 `node scripts/reanalyze-models.mjs --url http://127.0.0.1:3000` |
 
 ## 本地开发
@@ -283,10 +291,10 @@ npm run dev             # http://localhost:5173(/api 与 /health 代理到 3000)
 cd web-server
 npm run contracts:check   # 契约版本一致性
 npm run typecheck         # TypeScript 严格检查
-npm run test              # 168 项单元测试 / 10 个文件(VMD 31、模型压缩包 24、
+npm run test              # 180 项单元测试 / 11 个文件(VMD 31、模型压缩包 24、
                           #   模型检查器 25、缩略图 8、骨骼过滤 8、
                           #   预处理 25、init-env 16、admin-port 16、
-                          #   access-log 9、VRM 检查器 6)
+                          #   access-log 9、VRM 检查器 6、.env 预检 12)
 npm run build             # 生产构建
 npm run start:prod &      # 启动
 npm run test:smoke        # 57 项端到端冒烟(需要数据库可连通)
@@ -310,13 +318,21 @@ cd ../admin && npm run build   # 管理端构建
 | `UPLOAD_MAX_BYTES` | `536870912`(512 MiB) | 单文件上限。反向代理层的同名限制必须不小于此值,否则大模型上传会在代理层被拒(nginx `client_max_body_size` / IIS `requestLimits`),详见 `deploy/proxy/README.md` |
 | `ASSIMP_BIN` | - | 可选:Assimp 可执行文件。FBX/glTF 动作预处理需要;上传 `.zip` 模型包、或 `.pmx/.fbx` 单文件模型时必须能调用到,否则转换失败(422) |
 | `MODEL_CONVERT_FORMAT` | `glb` | 需要转换的模型(PMX/FBX)的交付格式:`glb`(两个客户端都原生加载)或 `vrm`。`vrm` = 在 GLB 之上补 `VRMC_vrm` 扩展(humanoid 骨骼 / 表情语义),humanoid 骨骼映射不全时自动回退交付 GLB 并写进 `conversion_note`。产物一律用 `assimp info` 回读校验 |
-| `MODEL_CONVERT_PMX` | `Hatsune Miku.pmx` | 压缩包内优先选用的 PMX 文件名(大小写不敏感);找不到时按「格式优先级 -> 目录最浅 -> 文件最大」挑选 |
+| `MODEL_CONVERT_PMX` | `"Hatsune Miku.pmx"` | 压缩包内优先选用的 PMX 文件名(大小写不敏感);找不到时按「格式优先级 -> 目录最浅 -> 文件最大」挑选 |
 | `MODEL_CONVERT_TIMEOUT_MS` | `180000` | 单次转换超时(毫秒) |
 | `DEFAULT_MODEL_ID` | - | 可选:显式指定默认模型 id;不设置时按源码种子 `src/config/default-model.ts` 匹配,再回落到 VRM 优先规则 |
 | `CONTRACTS_DIR` | - | 可选:契约目录,设置后 `/health` 反映实时契约版本(原生部署默认指向 `/opt/opendance/contracts`) |
 
 端口配置非法(非 1..65535 整数)时,生产环境启动会直接中止;`ADMIN_PORT` 设为与 `PORT` 相同只打印提示,不中止。
 
+**`.env` 写法约定**:`install.sh` / `ctl.sh` 用 `set -a; . deploy/.env` 载入配置,shell 会**真的执行**这个文件,因此
+
+- 普通值不加引号:`PORT=3000`、`DB_HOST=127.0.0.1`;
+- 值里含**空格或 shell 元字符**(`& | ; $ \` < > ( )` 等)时**必须加引号**,例如 `MODEL_CONVERT_PMX="Hatsune Miku.pmx"`;
+- 双引号内不要用 `$(...)` 或反引号(会被真的执行),需要字面量时用单引号:`KEY='a b'`。
+
+两个脚本在 source 之前都会先跑 `deploy/env-lib.sh` 的语法预检,不安全写法会直接指出行号、原文与改法。
+
 ## 主要 API
 
 | 方法 | 路径 | 说明 |

README.txt

@@ -1,5 +1,5 @@
 ================================================================
-OpenDance Studio -- Web 管理服务端 v0.2.0  使用说明
+OpenDance Studio -- Web 管理服务端 v0.2.1  使用说明
 ================================================================
 
 本服务端是 OpenDance Studio 三端中的第一端, 负责管理歌曲、VRM 模型与
@@ -8,6 +8,16 @@ OpenDance Studio -- Web 管理服务端 v0.2.0  使用说明
 重要: 本服务端 不部署、不管理 MySQL。数据库为部署方提供的现有实例,
 连接信息通过 .env 注入。
 
+v0.2.1 修订
+  1. 修复部署失败: 模板里的 MODEL_CONVERT_PMX=Hatsune Miku.pmx 值含空格却
+     没加引号, install.sh 用 `set -a; . deploy/.env` 载入时把 Miku.pmx 当命令
+     执行, 报 command not found(退出码 127); 模板已改为带引号写法。
+  2. 新增 .env 语法预检(deploy/env-lib.sh): install.sh 与 ctl.sh 在 source 之前
+     先检查, 直接给出哪一行、原文与改法, 不再出现看不懂的 127。
+  3. 失败提示带上出错文件名(.env 被 source 时行号属于 .env)。
+  4. 新增 12 项回归测试(web-server/test/env-file.spec.ts)。
+  约定: 值里含空格或 shell 元字符时必须加引号(双引号内不要用 $( ) 或反引号)。
+
 --
 一、部署到 Linux 服务器(业务服务, 不含反向代理)
 --
@@ -20,11 +30,11 @@ OpenDance Studio -- Web 管理服务端 v0.2.0  使用说明
    2. 准备一个现有的 MySQL / MariaDB 实例, 并建好库与账号(见下方"前置要求")
         本项目不会创建数据库本身
    3. 取得发布包并校验(地址用你们自己的制品库替换)
-        curl -LO https://<制品库地址>/opendance-web-v0.2.0.tar.gz
+        curl -LO https://<制品库地址>/opendance-web-v0.2.1.tar.gz
         curl -LO https://<制品库地址>/SHA256SUMS
         sha256sum -c SHA256SUMS      # 期望输出 "OK"
    4. 解压并生成配置(交互式引导, 逐项问答, 口令不回显)
-        tar -xzf opendance-web-v0.2.0.tar.gz && cd opendance-web-v0.2.0
+        tar -xzf opendance-web-v0.2.1.tar.gz && cd opendance-web-v0.2.1
         bash deploy/init-env.sh
    5. 安装(建用户与目录 -> 装依赖 -> 迁移 -> 注册系统服务 -> 等健康检查)
         bash deploy/install.sh
@@ -79,8 +89,8 @@ OpenDance Studio -- Web 管理服务端 v0.2.0  使用说明
   (本项目不会创建数据库本身, 也不需要 GRANT OPTION / FILE / SUPER 等管理权限)
 
 部署步骤
-  tar -xzf opendance-web-v0.2.0.tar.gz
-  cd opendance-web-v0.2.0
+  tar -xzf opendance-web-v0.2.1.tar.gz
+  cd opendance-web-v0.2.1
   bash deploy/init-env.sh         # 首次启动引导: 逐项问答生成 deploy/.env(见下)
   bash deploy/install.sh          # 已以 root 登录, 不需要 sudo
 
@@ -209,7 +219,10 @@ deploy/.env 初始化引导(deploy/init-env.sh)
  - 上传 .zip 模型包报 422 且提示 Assimp 不可用
      PMX/FBX 转换依赖 Assimp: apt-get install -y assimp-utils libassimp6;
      只上传 .glb / .vrm 则不需要它。
- - 模型审核界面显示"未分析 / 无预览图"
+ - 安装时报 command not found / 退出码 127, 且提示指向 deploy/.env 某一行
+      该行的值含空格或 shell 元字符却没加引号, 被 shell 当成命令执行了。按预检
+      提示给这个值加引号(如 MODEL_CONVERT_PMX="Hatsune Miku.pmx")后重跑。
+  - 模型审核界面显示"未分析 / 无预览图"
      该模型是升级前入库的: 调 POST /api/models/<id>/reanalyze, 或批量跑
      node scripts/reanalyze-models.mjs --url http://127.0.0.1:3000。
 
@@ -236,10 +249,10 @@ deploy/.env 初始化引导(deploy/init-env.sh)
   cd web-server
   npm run contracts:check   # 契约版本一致性
   npm run typecheck         # TypeScript 严格检查
-  npm run test              # 168 项单元测试 / 10 个文件(VMD 31、模型压缩包 24、
+  npm run test              # 180 项单元测试 / 11 个文件(VMD 31、模型压缩包 24、
                             #   模型检查器 25、缩略图 8、骨骼过滤 8、
                             #   预处理 25、init-env 16、admin-port 16、
-                            #   access-log 9、VRM 检查器 6)
+                            #   access-log 9、VRM 检查器 6、.env 预检 12)
   npm run build             # 生产构建
   npm run start:prod &      # 启动
   npm run test:smoke        # 57 项端到端冒烟(需要数据库可连通)
@@ -270,6 +283,13 @@ deploy/.env 初始化引导(deploy/init-env.sh)
   ADMIN_HOST            管理端监听地址(可选, 默认跟随 HOST;HOST 未设置时同样
                         回落 0.0.0.0)。需要接口对外、管理端只对本机时设为
                         127.0.0.1
+  .env 写法约定: install.sh / ctl.sh 用 `set -a; . deploy/.env` 载入配置, shell 会
+  真的执行这个文件, 因此普通值不加引号(PORT=3000), 值里含空格或 shell 元字符
+  (& | ; $ ` < > ( ) 等)时必须加引号, 例如 MODEL_CONVERT_PMX="Hatsune Miku.pmx";
+  双引号内不要用 $( ) 或反引号(会被真的执行), 需要字面量时用单引号 KEY='a b'。
+  两个脚本在 source 之前都会先跑 deploy/env-lib.sh 的语法预检, 不安全写法会直接
+  指出行号、原文与改法。
+
   端口配置非法(非 1..65535 整数)时, 生产环境启动会直接中止;
   ADMIN_PORT 设为与 PORT 相同只打印提示, 不中止。
   ADMIN_DIR             管理端静态站点目录(默认 ../admin, 即 /opt/opendance/admin)
@@ -286,7 +306,7 @@ deploy/.env 初始化引导(deploy/init-env.sh)
                         vrm = 在 GLB 之上补 VRMC_vrm 扩展(humanoid 骨骼 / 表情语义),
                         humanoid 骨骼映射不全时自动回退交付 GLB 并写进 conversion_note。
                         产物一律用 `assimp info` 回读校验
-  MODEL_CONVERT_PMX     压缩包内优先选用的 PMX 文件名(默认 Hatsune Miku.pmx,
+  MODEL_CONVERT_PMX     压缩包内优先选用的 PMX 文件名(默认 "Hatsune Miku.pmx",
                         大小写不敏感); 找不到时按「格式优先级 -> 目录最浅 ->
                         文件最大」挑选
   MODEL_CONVERT_TIMEOUT_MS

deploy/.env.example

@@ -24,10 +24,10 @@ HOST=0.0.0.0
 ADMIN_DIR=/opt/opendance/admin
 
 # ---- 现有 MySQL / MariaDB 实例（本项目不安装、不管理数据库）----
-DB_HOST=<existing-mysql-host>
+DB_HOST='<existing-mysql-host>'
 DB_PORT=3306
 DB_USER=opendance_app
-DB_PASS=<数据库口令>
+DB_PASS='<数据库口令>'
 DB_NAME=opendance
 # 生产环境必须为 false，表结构一律走 TypeORM migration
 DB_SYNCHRONIZE=false
@@ -50,7 +50,9 @@ ASSIMP_BIN=assimp
 #        humanoid 骨骼名映射不全时会自动回退交付 GLB 并写进 conversion_note
 MODEL_CONVERT_FORMAT=glb
 # 压缩包里优先选用的 PMX 文件名（大小写不敏感）；找不到时按"格式优先级 -> 目录最浅 -> 文件最大"挑
-MODEL_CONVERT_PMX=Hatsune Miku.pmx
+# 值里含空格或 shell 元字符时必须用引号包起来（install.sh 会用
+# `set -a; . deploy/.env` 真的执行本文件；不加引号会把 "Miku.pmx" 当命令）
+MODEL_CONVERT_PMX="Hatsune Miku.pmx"
 # 单次转换超时（毫秒）
 MODEL_CONVERT_TIMEOUT_MS=180000
 

deploy/ctl.sh

@@ -13,6 +13,7 @@
 # ============================================================
 set -uo pipefail
 
+SCRIPT_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
 APP_DIR="${APP_DIR:-/opt/opendance}"
 SERVICE_USER="${SERVICE_USER:-opendance}"
 LOG_FILE="${LOG_FILE:-/var/log/opendance-api.log}"
@@ -95,8 +96,14 @@ start() {
     return 0
   fi
 
-  # 载入部署环境变量
+  # 载入部署环境变量（先做语法预检：.env 会被 shell 真的执行）
   if [ -f "$APP_DIR/deploy/.env" ]; then
+    if [ -f "$SCRIPT_DIR/env-lib.sh" ]; then
+      # shellcheck source=deploy/env-lib.sh
+      . "$SCRIPT_DIR/env-lib.sh"
+      opendance_validate_env_file "$APP_DIR/deploy/.env" \
+        || die "$APP_DIR/deploy/.env 语法预检未通过（见上）：给对应行的值加上引号后重试。"
+    fi
     set -a; . "$APP_DIR/deploy/.env"; set +a
   else
     die "缺少 $APP_DIR/deploy/.env"

deploy/env-lib.sh

@@ -0,0 +1,126 @@
+#!/bin/bash
+# ============================================================
+# OpenDance Studio Web API —— deploy/.env 语法预检
+#
+# 本文件被 install.sh 与 ctl.sh 引用（不要单独执行）。
+#
+# 为什么需要：
+#   两个脚本都用 `set -a; . deploy/.env` 载入配置，shell 会**真的执行**
+#   这个文件。若某个值含空格或 shell 元字符却没加引号，这一行会被切成
+#   「赋值 + 命令」，报错形如：
+#       ./deploy/.env: line 53: Miku.pmx: command not found
+#   退出码 127，而且提示里看不出是哪个文件、哪一行、该怎么改。
+#   载入前先做一次静态检查，给出带行号与修复建议的中文提示。
+#
+# 约定（与 init-env.sh 一致）：
+#   普通值不加引号（如 PORT=3000）；值里含空格或 shell 元字符时用引号包起来，
+#   例如 MODEL_CONVERT_PMX="Hatsune Miku.pmx"。双引号内不要用 $(...) 或反引号
+#   —— 它们在载入时会被真正执行。单引号是字面量，最安全。
+# ============================================================
+
+# 裸值（未加引号）是否可以被 `set -a; . file` 安全载入
+#   赋值语句里的裸值不会做通配展开，所以 * ? [ ] { } ! % + , - . : / @ = 都安全；
+#   真正会破坏解析的是：空白、& | ; $ ` < > ( ) \ 以及引号本身、行首的 ~
+opendance_env_value_is_safe_unquoted() {
+  local v="${1:-}"
+  [ -z "$v" ] && return 0
+  case "$v" in
+    *[[:space:]]*|*'&'*|*'|'*|*';'*|*'$'*|*'`'*|*'<'*|*'>'*|*'('*|*')'*|*'\'*|*'"'*|*"'"*) return 1 ;;
+    '~'*) return 1 ;;
+  esac
+  return 0
+}
+
+# 值本身是否是安全的写法（空值 / 加引号 / 裸值但字符安全）
+# 允许「引号 + 行尾注释」的写法，例如 DB_HOST="127.0.0.1"   # 本机
+opendance_env_value_is_safe() {
+  local v="${1:-}" inner="" rest=""
+  case "$v" in
+    '') return 0 ;;
+    \"*)
+      case "$v" in *\"*) ;; *) return 1 ;; esac          # 结束引号必须在
+      inner="${v#\"}"; inner="${inner%%\"*}"             # 引号内的内容
+      case "$inner" in *'$('*|*'`'*) return 1 ;; esac     # 双引号内会真的执行
+      rest="${v#\"}"; rest="${rest#*\"}"                 # 结束引号之后的内容
+      case "$rest" in
+        ''|[[:space:]]|[[:space:]]*|[[:space:]]*'#'*) return 0 ;;
+        *) return 1 ;;
+      esac ;;
+    \'*)
+      case "$v" in *\'*) ;; *) return 1 ;; esac
+      rest="${v#\'}"; rest="${rest#*\'}"
+      case "$rest" in
+        ''|[[:space:]]|[[:space:]]*|[[:space:]]*'#'*) return 0 ;;
+        *) return 1 ;;
+      esac ;;
+    *) opendance_env_value_is_safe_unquoted "$v" ;;
+  esac
+}
+
+# 校验一个 .env 文件：opendance_validate_env_file <文件路径>
+#   通过返回 0；发现不安全写法返回 1（问题行与其改法已打印到 stderr)
+opendance_validate_env_file() {
+  local file="${1:-}" lineno=0 bad=0 line key value reason inner
+  if [ ! -f "$file" ]; then
+    printf '[env] 找不到配置文件：%s\n' "$file" >&2
+    return 1
+  fi
+  while IFS= read -r line || [ -n "$line" ]; do
+    lineno=$((lineno + 1))
+    line="${line%$'\r'}"                     # 兼容 CRLF
+    case "$line" in ''|'#'*) continue ;; esac
+    reason=""
+    case "$line" in
+      [A-Za-z_]*=*) ;;
+      *) reason="不是「键=值」形式（载入时会被当成命令执行）" ;;
+    esac
+    if [ -z "$reason" ]; then
+      key="${line%%=*}"
+      value="${line#*=}"
+      case "$key" in
+        *[!A-Za-z0-9_]*) reason="键名含非法字符" ;;
+      esac
+    fi
+    if [ -z "$reason" ] && ! opendance_env_value_is_safe "$value"; then
+      case "$value" in
+        \"*)
+          inner="${value#\"}"
+          case "$inner" in
+            *\"*) reason="引号写法不安全：引号后有其它内容，或引号内用了 \$( ) / 反引号（载入时会真的执行）" ;;
+            *)    reason="双引号未闭合" ;;
+          esac ;;
+        \'*)
+          inner="${value#\'}"
+          case "$inner" in
+            *\'*) reason="单引号后还有其它内容，请把整个值放进引号" ;;
+            *)    reason="单引号未闭合" ;;
+          esac ;;
+        *)   reason="值含空格或 shell 元字符，却未加引号" ;;
+      esac
+    fi
+    if [ -n "$reason" ]; then
+      bad=$((bad + 1))
+      printf '\033[1;31m[env]\033[0m %s 第 %d 行写法不安全：%s\n' "$file" "$lineno" "$reason" >&2
+      printf '      %d | %s\n' "$lineno" "$line" >&2
+      case "$line" in
+        *'='*)
+          key="${line%%=*}"; value="${line#*=}"
+          case "$value" in
+            \"*|\'*)
+              printf '      提示: 引号请成对、且把整个值包住; 单引号是字面量, 最安全。\n' >&2 ;;
+            *"'"*)
+              printf '      提示: 值里同时有单引号与特殊字符, 请手工调整 - 单引号内不能再出现单引号。\n' >&2 ;;
+            *'$'*|*'`'*)
+              printf "      改法: %s='%s'  注意: 双引号里的 \$( ) 与反引号会被真的执行, 单引号才是字面量。\n" "$key" "$value" >&2 ;;
+            *)
+              printf '      改法: %s="%s"\n' "$key" "$value" >&2 ;;
+          esac ;;
+      esac
+    fi
+  done < "$file"
+  if [ "$bad" -gt 0 ]; then
+    printf '\033[1;31m[env]\033[0m %s 语法预检未通过：%d 行需要加引号（见上）。\n' "$file" "$bad" >&2
+    return 1
+  fi
+  return 0
+}

deploy/install.sh

@@ -21,11 +21,18 @@
 # ============================================================
 set -euo pipefail
 # 失败时打印出错行号，避免只看到半截输出
-trap 'printf "\033[1;31m[install]\033[0m 第 %d 行执行失败（退出码 %d）\n" "$LINENO" "$?" >&2' ERR
+trap 'printf "\033[1;31m[install]\033[0m %s 第 %d 行执行失败（退出码 %d）\n" "${BASH_SOURCE[0]}" "$LINENO" "$?" >&2' ERR
 
 SRC_DIR="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$SRC_DIR"
 
+# .env 语法预检（deploy/env-lib.sh）：.env 是被 shell 真正 source 的文件，
+# 未加引号且含空格的值会被当成命令执行，报错形如
+#   ./deploy/.env: line 53: Miku.pmx: command not found
+# 载入前先查一遍，给出带行号与改法的中文提示。
+# shellcheck source=deploy/env-lib.sh
+. "$SRC_DIR/deploy/env-lib.sh"
+
 APP_DIR="${APP_DIR:-/opt/opendance}"
 SERVICE_USER="${SERVICE_USER:-opendance}"
 STORAGE_DIR="${STORAGE_DIR:-/var/lib/opendance/storage}"
@@ -125,6 +132,8 @@ if [ ! -f deploy/.env ]; then
   fi
 fi
 
+opendance_validate_env_file "./deploy/.env" || die "deploy/.env 语法预检未通过（见上）：按提示给对应行的值加上引号后重新执行。"
+
 set -a
 # shellcheck disable=SC1091
 . ./deploy/.env
@@ -320,6 +329,7 @@ fi
 
 # ---------- 3. 数据库迁移 ----------
 log "执行 TypeORM 迁移（不使用 DB_SYNCHRONIZE）"
+opendance_validate_env_file "$APP_DIR/deploy/.env" || die "$APP_DIR/deploy/.env 语法预检未通过（见上）"
 set -a; . "$APP_DIR/deploy/.env"; set +a
 cd "$APP_DIR/web-server"
 as_service_user env \

project.yaml

@@ -1,5 +1,5 @@
 project: opendance-web-server
-version: 0.2.0
+version: 0.2.1
 repository: opendance-web
 default_branch: main
 contracts_version: 0.4.0
@@ -60,7 +60,7 @@ tasks:
     status: done
 
 deliverable:
-  artifact: opendance-web-v0.2.0.tar.gz
+  artifact: opendance-web-v0.2.1.tar.gz
   packaging: Linux 业务服务（系统服务托管，双端口：软件 API + 管理端，不含 MySQL、不含反向代理、不使用 Docker）
   includes:
     - web-server/          # NestJS 源码 + 构建产物（含 BVH / VMD 内置解析、ZIP 读取与模型压缩包转换）

scripts/package-release.sh

@@ -6,6 +6,7 @@
 #   web-server/      NestJS 源码 + 构建产物
 #   admin/           React 管理端构建产物
 #   deploy/          install.sh / ctl.sh / uninstall.sh / .env.example
+#                    env-lib.sh (.env 语法预检) / init-env.sh (.env 引导)
 #                    systemd|openrc|initd / proxy（反代说明文档，仅文档不部署）
 #   contracts/       当前版本契约快照
 #   THIRD_PARTY.md   开源项目声明
@@ -130,6 +131,7 @@ for required in \
   "opendance-web-v${VERSION}/web-server/dist/models/vrm-writer.js" \
   "opendance-web-v${VERSION}/web-server/dist/models/gltf-packer.js" \
   "opendance-web-v${VERSION}/deploy/init-env.sh" \
+  "opendance-web-v${VERSION}/deploy/env-lib.sh" \
   "opendance-web-v${VERSION}/deploy/proxy/README.md" \
   "opendance-web-v${VERSION}/deploy/proxy/nginx.conf.example" \
   "opendance-web-v${VERSION}/deploy/proxy/web.config.example" \

tasks/005-model-upload.md

@@ -160,7 +160,7 @@ node scripts/import-default-model.mjs --write-source-only --model-id 22 --dry-ru
 
 ```bash
 cd web-server
-npx vitest run        # 10 个文件 / 168 项通过
+npx vitest run        # 11 个文件 / 180 项通过
 npm run test:smoke    # 冒烟 [4] 段落
 ```
 

tasks/007-upload-review.md

@@ -86,7 +86,7 @@ draft ──submit──▶ pending ──approve──▶ published
 
 ```bash
 cd web-server
-npx vitest run        # 10 个文件 / 168 项通过（含 admin-bone-filter 8 项）
+npx vitest run        # 11 个文件 / 180 项通过（含 admin-bone-filter 8 项、.env 预检 12 项）
 npm run test:smoke
 ```
 

web-server/admin/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opendance-admin",
   "private": true,
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "OpenDance Studio 管理端（React + TypeScript + Vite）",
   "scripts": {

web-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opendance-web-server",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "OpenDance Studio Web 管理服务端（NestJS + TypeORM + 现有 MySQL 实例）",
   "license": "MIT",
   "private": true,

web-server/test/env-file.spec.ts

@@ -0,0 +1,189 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+
+/**
+ * deploy/.env 的「可被 shell 安全载入」保证。
+ *
+ * 背景（真实故障）：install.sh 用 `set -a; . deploy/.env` 载入配置，而模板里
+ *   MODEL_CONVERT_PMX=Hatsune Miku.pmx
+ * 的值含空格却没加引号，这一行被切成「赋值 + 命令」，安装直接失败：
+ *   ./deploy/.env: line 53: Miku.pmx: command not found
+ *   [install] 第 53 行执行失败(退出码 127)
+ *
+ * 因此这里锁两条线：
+ *   1. deploy/.env.example 必须能被 `set -a; .` 原样载入（回归用例）；
+ *   2. deploy/env-lib.sh 的预检能在载入前拦住不安全写法，并给出行号与改法。
+ */
+
+function findDeployFile(name: string): string {
+  const candidates = [
+    resolve(process.cwd(), '..', 'deploy', name), // 从 web-server/ 运行（vitest 默认）
+    resolve(process.cwd(), 'deploy', name), // 从仓库根运行
+    resolve(process.cwd(), '..', '..', 'deploy', name),
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  throw new Error(`找不到 deploy/${name}，候选路径：\n${candidates.join('\n')}`);
+}
+
+const EXAMPLE = findDeployFile('.env.example');
+const ENV_LIB = findDeployFile('env-lib.sh');
+const INSTALL_SH = findDeployFile('install.sh');
+const CTL_SH = findDeployFile('ctl.sh');
+
+const dirs: string[] = [];
+function makeDir(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'opendance-env-'));
+  dirs.push(dir);
+  return dir;
+}
+afterEach(() => {
+  while (dirs.length) rmSync(dirs.pop()!, { recursive: true, force: true });
+});
+
+/** 用真实 shell 载入一个 .env（与 install.sh 的做法一致） */
+function sourceEnv(file: string) {
+  return spawnSync(
+    'bash',
+    [
+      '-c',
+      'set -a; . "$1"; set +a; printf "%s\\n" "${MODEL_CONVERT_PMX:-}" "${DB_HOST:-}" "${DB_PASS:-}" "${UPLOAD_MAX_BYTES:-}"',
+      '_',
+      file,
+    ],
+    { encoding: 'utf8', timeout: 15000 },
+  );
+}
+
+/** 调用 deploy/env-lib.sh 的预检函数 */
+function validate(file: string) {
+  return spawnSync('bash', ['-c', '. "$1"; opendance_validate_env_file "$2"', '_', ENV_LIB, file], {
+    encoding: 'utf8',
+    timeout: 15000,
+  });
+}
+
+function writeEnv(content: string): string {
+  const file = join(makeDir(), '.env');
+  writeFileSync(file, content);
+  return file;
+}
+
+describe('deploy/.env.example：必须能被 shell 原样载入', () => {
+  it('`set -a; . .env.example` 成功, 且带空格的值读回完整 (回归: 修复前此处退出码 127)', () => {
+    const result = sourceEnv(EXAMPLE);
+
+    expect(result.stderr).not.toContain('command not found');
+    expect(result.status).toBe(0);
+    const [pmx, host, pass, uploadMax] = result.stdout.trimEnd().split('\n');
+    expect(pmx).toBe('Hatsune Miku.pmx');
+    expect(host).toBe('<existing-mysql-host>');
+    expect(pass).toBe('<数据库口令>');
+    expect(uploadMax).toBe('536870912');
+  });
+
+  it('模板整体通过语法预检', () => {
+    const result = validate(EXAMPLE);
+    expect(result.status).toBe(0);
+    expect(result.stderr).toBe('');
+  });
+
+  it('模板里每个赋值行都通过预检（逐行定位，便于以后加字段时发现问题）', () => {
+    const lines = readFileSync(EXAMPLE, 'utf8').split('\n');
+    const assigns = lines.filter((l) => /^[A-Za-z_][A-Za-z0-9_]*=/.test(l));
+    expect(assigns.length).toBeGreaterThan(10); // 模板字段数量下限，防止误删
+    for (const line of assigns) {
+      expect(validate(writeEnv(`${line}\n`)).status, `模板行应通过预检：${line}`).toBe(0);
+    }
+  });
+});
+
+describe('deploy/env-lib.sh：载入前的语法预检', () => {
+  it('拦住「值含空格却未加引号」，并给出行号、原文与改法（本次故障的原始写法）', () => {
+    const result = validate(writeEnv('NODE_ENV=production\nMODEL_CONVERT_PMX=Hatsune Miku.pmx\n'));
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain('第 2 行');
+    expect(result.stderr).toContain('MODEL_CONVERT_PMX=Hatsune Miku.pmx');
+    expect(result.stderr).toContain('MODEL_CONVERT_PMX="Hatsune Miku.pmx"');
+  });
+
+  it('拦住 shell 元字符，且对 $( ) 建议单引号（双引号仍会执行）', () => {
+    const result = validate(writeEnv('A=x&y\nB=$(id)\n'));
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain('第 1 行');
+    expect(result.stderr).toContain('第 2 行');
+    expect(result.stderr).toContain("B='$(id)'");
+  });
+
+  it('拦住未闭合引号', () => {
+    const result = validate(writeEnv('A="unclosed\n'));
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain('双引号未闭合');
+  });
+
+  it('不误伤合法写法：* % 口令、IPv4、路径、空值、单引号、引号 + 行尾注释', () => {
+    const result = validate(
+      writeEnv(
+        [
+          'DB_PASS=S3cr3t*Pwd%1',
+          'DB_HOST=127.0.0.1',
+          'DB_PORT=3306',
+          'STORAGE_DIR=/var/lib/opendance/storage',
+          'EMPTY=',
+          "WITH_SPACE='a b c'",
+          'QUOTED_COMMENT="x y"  # 行尾注释',
+          'MODEL_CONVERT_PMX="Hatsune Miku.pmx"',
+          '# 注释与空行也必须放过',
+          '',
+        ].join('\n'),
+      ),
+    );
+    expect(result.stderr).toBe('');
+    expect(result.status).toBe(0);
+  });
+
+  it('拦住非「键=值」的行号并指出原因', () => {
+    const result = validate(writeEnv('A=1\n这一行不是赋值\n'));
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain('第 2 行');
+    expect(result.stderr).toContain('不是「键=值」形式');
+  });
+
+  it('文件不存在时返回 1（而不是静默通过）', () => {
+    const result = validate(join(makeDir(), 'missing.env'));
+    expect(result.status).toBe(1);
+    expect(result.stderr).toContain('找不到配置文件');
+  });
+});
+
+describe('载入顺序：install.sh / ctl.sh 必须先预检再 source', () => {
+  it('install.sh 在 `. ./deploy/.env` 之前调用预检', () => {
+    const text = readFileSync(INSTALL_SH, 'utf8');
+    const check = text.indexOf('opendance_validate_env_file "./deploy/.env"');
+    const source = text.indexOf('. ./deploy/.env');
+    expect(check).toBeGreaterThan(-1);
+    expect(source).toBeGreaterThan(-1);
+    expect(check).toBeLessThan(source);
+    // .env 被 source 时 LINENO 指向 .env 的行号，报错必须带上文件名才定位得到
+    expect(text).toContain('${BASH_SOURCE[0]}');
+  });
+
+  it('install.sh 在迁移前再次预检安装目录里的 .env', () => {
+    const text = readFileSync(INSTALL_SH, 'utf8');
+    expect(text).toContain('opendance_validate_env_file "$APP_DIR/deploy/.env"');
+  });
+
+  it('ctl.sh 载入 .env 前调用预检，且引用同目录的 env-lib.sh', () => {
+    const text = readFileSync(CTL_SH, 'utf8');
+    expect(text).toContain('"$SCRIPT_DIR/env-lib.sh"');
+    const check = text.indexOf('opendance_validate_env_file "$APP_DIR/deploy/.env"');
+    const source = text.indexOf('. "$APP_DIR/deploy/.env"');
+    expect(check).toBeGreaterThan(-1);
+    expect(source).toBeGreaterThan(-1);
+    expect(check).toBeLessThan(source);
+  });
+});