From ea58520fc228c75ca4011cdd1705dab03f123afd Mon Sep 17 00:00:00 2001 From: opendance Date: Tue, 15 Sep 2026 22:26:33 +0800 Subject: [PATCH] =?UTF-8?q?fix(deploy):=20.env=20=E4=B8=AD=E5=B8=A6?= =?UTF-8?q?=E7=A9=BA=E6=A0=BC=E7=9A=84=E5=80=BC=E6=9C=AA=E5=8A=A0=E5=BC=95?= =?UTF-8?q?=E5=8F=B7=E5=AF=BC=E8=87=B4=20install.sh=20=E4=BB=A5=20127=20?= =?UTF-8?q?=E5=A4=B1=E8=B4=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 现象： ./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 | 13 ++- README.md | 36 ++++-- README.txt | 38 +++++-- deploy/.env.example | 8 +- deploy/ctl.sh | 9 +- deploy/env-lib.sh | 126 +++++++++++++++++++++ deploy/install.sh | 12 +- project.yaml | 4 +- scripts/package-release.sh | 2 + tasks/005-model-upload.md | 2 +- tasks/007-upload-review.md | 2 +- web-server/admin/package.json | 2 +- web-server/package.json | 2 +- web-server/test/env-file.spec.ts | 189 +++++++++++++++++++++++++++++++ 14 files changed, 412 insertions(+), 33 deletions(-) create mode 100644 deploy/env-lib.sh create mode 100644 web-server/test/env-file.spec.ts diff --git a/DSH.md b/DSH.md index d70048b..069e0b9 100644 --- a/DSH.md +++ b/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` 不回显、 diff --git a/README.md b/README.md index c9f00f6..9a72d0b 100644 --- a/README.md +++ b/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//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 | 方法 | 路径 | 说明 | diff --git a/README.txt b/README.txt index d967d3a..748bae8 100644 --- a/README.txt +++ b/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//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 diff --git a/deploy/.env.example b/deploy/.env.example index 883d4cf..b483c17 100644 --- a/deploy/.env.example +++ b/deploy/.env.example @@ -24,10 +24,10 @@ HOST=0.0.0.0 ADMIN_DIR=/opt/opendance/admin # ---- 现有 MySQL / MariaDB 实例（本项目不安装、不管理数据库）---- -DB_HOST= +DB_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 diff --git a/deploy/ctl.sh b/deploy/ctl.sh index 9d9fa03..5c3c883 100755 --- a/deploy/ctl.sh +++ b/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" diff --git a/deploy/env-lib.sh b/deploy/env-lib.sh new file mode 100644 index 0000000..48e9203 --- /dev/null +++ b/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 +} diff --git a/deploy/install.sh b/deploy/install.sh index bf8d592..77bc9bd 100755 --- a/deploy/install.sh +++ b/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 \ diff --git a/project.yaml b/project.yaml index 0de6a03..b6e27fd 100644 --- a/project.yaml +++ b/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 读取与模型压缩包转换） diff --git a/scripts/package-release.sh b/scripts/package-release.sh index fc35c2b..b484a67 100755 --- a/scripts/package-release.sh +++ b/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" \ diff --git a/tasks/005-model-upload.md b/tasks/005-model-upload.md index 5f8c274..ff54c30 100644 --- a/tasks/005-model-upload.md +++ b/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] 段落 ``` diff --git a/tasks/007-upload-review.md b/tasks/007-upload-review.md index 2b77d62..9473473 100644 --- a/tasks/007-upload-review.md +++ b/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 ``` diff --git a/web-server/admin/package.json b/web-server/admin/package.json index fafe0f0..ca7faf9 100644 --- a/web-server/admin/package.json +++ b/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": { diff --git a/web-server/package.json b/web-server/package.json index 16d4578..d493765 100644 --- a/web-server/package.json +++ b/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, diff --git a/web-server/test/env-file.spec.ts b/web-server/test/env-file.spec.ts new file mode 100644 index 0000000..da629f1 --- /dev/null +++ b/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(''); + 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); + }); +});