# 脚本说明

`scripts/` 目录里既有当前仍在使用的脚本，也有历史遗留的人工运维脚本。这个文件只列“当前还应当优先关注”的入口。

## 一、通过 `package.json` 直接调用的脚本

### `migrate-template-data.ts`

用途：

- 修复历史模板数据
- 为素材补齐模板关联
- 做模板体系迁移后的收尾处理

运行：

```bash
npm run migrate:template-data
```

### `verify-template-data.ts`

用途：

- 校验模板、字段、素材之间的数据一致性
- 在部署后或修复后做确认

运行：

```bash
npm run verify:template-data
```

## 二、当前客户/实施可用脚本

### 构建相关

- `build-obfuscated.js`
  生产构建后的服务端混淆处理。客户交付镜像通过 `Dockerfile` 执行 `npm run build:prod` 时会自动调用；混淆依赖或配置缺失会直接失败，不能静默跳过。
- `docker-entrypoint.sh`
  主应用容器启动入口
- `customer-install.sh`
  NAS / Linux 客户首装向导入口，按步骤调用 `smoke-install.sh` 做预检、启动和验收；不替代生产 Compose，也不依赖 Agent
- `smoke-install.sh`
  NAS / Linux 客户首装后的基础验收脚本，可检查 Compose 配置、容器状态、运行镜像、版本文件、迁移状态、MinIO bucket 和 `/api/health`
- `backup-restore.sh`
  NAS / Linux 客户环境备份、恢复和健康验收脚本；恢复必须显式输入确认短语，避免误覆盖客户数据
- `customer-acceptance-smoke.mjs`
  客户业务验收脚本，可只读检查健康、初始化、登录页和权限拦截，也可登录后验模板、后台接口和真实小素材上传
- `customer-install.ps1`
  Windows / PowerShell 版客户首装向导入口，逻辑对应 `customer-install.sh`
- `smoke-install.ps1`
  Windows / PowerShell 版客户首装后的基础验收脚本，逻辑对应 `smoke-install.sh`
- `backup-restore.ps1`
  客户环境备份、恢复和健康验收脚本；恢复必须显式输入确认短语，避免误覆盖客户数据
- `measure-image-size.ps1`
  发布前读取主应用镜像体积和分层，记录后续瘦身基线；只读检查，不修改镜像
- `generate-shared-test-env.ps1`
  为共享测试机生成隔离后的 `.env`，避免容器名、卷名、网络名与其他项目冲突；这是内部测试脚本，不是客户安装器

### 数据检查/修复相关

- `check-templates.ts`
  检查模板缺失或异常
- `fix-missing-templates.ts`
  修复缺失模板
- `update-audio-template-fields.ts`
  更新音频模板字段
- `migrate-ai-to-other-template.ts`
  处理 AI 模板迁移
- `trigger-video-transcode.ts`
  手工触发视频转码

## 三、使用原则

1. 能通过 `package.json` 跑的，优先不要手敲文件路径。
2. 手动脚本通常带环境假设，执行前先读内容。
3. 带固定服务器地址、固定账号、一次性交付信息的脚本，不应继续当成通用入口。
4. 看到 Harbor、固定服务器、`latest` 的脚本，默认先当历史/内部入口处理，不要直接用于客户安装或升级。
5. `generate-shared-test-env.ps1` 只给共享测试机或内部联调用，客户交付不要把它当安装器。

## 四、常见流程

### 模板数据修复

```bash
npm run prisma:generate
npm run migrate:template-data
npm run verify:template-data
```

### 检查并修复模板缺失

```bash
npx tsx scripts/check-templates.ts
npx tsx scripts/fix-missing-templates.ts
```

### 为共享测试机生成环境文件

```powershell
.\scripts\generate-shared-test-env.ps1 `
  -OutputPath "$env:TEMP\flnxi_sucai-test.env" `
  -AppImage "registry.example.com/flnxi/material/flnxi-material:1.0.1" `
  -LicenseServerUrl "https://your-license-server.example.com"
```

说明：

- `LicenseServerUrl` 不再内置默认值，必须显式传入。
- `AppImage` 不再内置默认值，测试环境也必须固定完整镜像版本。
- 示例地址只是占位，执行前必须替换为当前真实可用的许可证服务地址。
- `https://license.flnxi.com` 不能默认当作当前可用入口。

### 客户首装基础验收

NAS / Linux 客户现场优先用 `.sh` 入口；当前账号没有 Docker 权限时，用 `sudo bash ...`：

```bash
bash scripts/customer-install.sh --project-dir /opt/flnxi --plan-only
sudo bash scripts/customer-install.sh --project-dir /opt/flnxi --prepare-directories --start
```

说明：

- `--plan-only` 只打印四步流程，不启动容器。
- `--prepare-directories` 会创建并测试 `uploads/` 和 `data/`；sudo/root 运行时会调整目录为应用容器 UID `1001` 可写。
- `--start` 会执行 `docker compose up -d`；如果已经由 NAS 图形界面启动，可以不传。
- 这个脚本内部仍调用 `smoke-install.sh`，不引入第二套安装逻辑。

```bash
bash scripts/smoke-install.sh --project-dir /opt/flnxi --preflight-only
bash scripts/smoke-install.sh --project-dir /opt/flnxi
```

Windows 实施机或已安装 PowerShell 的现场，可以用 `.ps1` 入口：

```powershell
.\scripts\customer-install.ps1 -ProjectDir "D:\deploy\flnxi" -PlanOnly
.\scripts\customer-install.ps1 -ProjectDir "D:\deploy\flnxi" -PrepareDirectories -Start
```

说明：

- `-PlanOnly` 只打印四步流程，不启动容器。
- `-PrepareDirectories` 会创建并测试 `uploads/` 和 `data/`。
- `-Start` 会执行 `docker compose up -d`；如果已经由 NAS 图形界面启动，可以不传。
- 这个脚本内部仍调用 `smoke-install.ps1`，不引入第二套安装逻辑。

```powershell
.\scripts\smoke-install.ps1 -ProjectDir "D:\deploy\flnxi" -PreflightOnly
.\scripts\smoke-install.ps1 -ProjectDir "D:\deploy\flnxi" -Start
```

说明：

- `-PreflightOnly` 只做安装前检查，不启动容器；会拦截 `.env` 示例值、`latest` 镜像、缺失数据目录等常见坑。
- 新目录可加 `-PrepareDirectories`，让脚本创建 `uploads/` 和 `data/` 并做写入测试。
- `-Start` 会执行 `docker compose up -d`；如果服务已经由 NAS 图形界面启动，可以不传，只做检查。
- 如果客户使用外部对象存储，可加 `-SkipObjectStorageCheck`。
- 如果刚启动后数据库迁移还没完成，脚本会在健康接口处等待一段时间，失败时输出应用日志帮助排查。

### 客户备份、恢复和验收

NAS / Linux：

```bash
sudo bash scripts/backup-restore.sh --project-dir /opt/flnxi --action backup
bash scripts/backup-restore.sh --project-dir /opt/flnxi --action verify
sudo bash scripts/backup-restore.sh \
  --project-dir /opt/flnxi \
  --action restore \
  --backup-path /opt/flnxi/backups/flnxi-backup-YYYYMMDD-HHMMSS \
  --confirm-restore RESTORE_FLNXI_DATA
```

Windows / PowerShell：

```powershell
.\scripts\backup-restore.ps1 -ProjectDir "D:\deploy\flnxi" -Action Backup
.\scripts\backup-restore.ps1 -ProjectDir "D:\deploy\flnxi" -Action Verify
.\scripts\backup-restore.ps1 `
  -ProjectDir "D:\deploy\flnxi" `
  -Action Restore `
  -BackupPath "D:\deploy\flnxi\backups\flnxi-backup-YYYYMMDD-HHMMSS" `
  -ConfirmRestore RESTORE_FLNXI_DATA
```

说明：

- 默认备份 Compose 管理的 PostgreSQL、内置 MinIO 数据卷、`.env`、Compose 文件、版本文件、镜像和容器状态。
- 备份包会包含客户素材、数据库和 `.env` 密钥，必须限权或加密保存，不能提交到 Git。
- 外部数据库、外部对象存储由客户现场方案单独备份；脚本会写提示文件，不会假装自动覆盖。
- 对象存储备份/恢复使用 `busybox:1.36` 作为 helper 镜像；离线客户现场需要提前放入该镜像或通过 `-HelperImage` 指定现场已有镜像。

### 客户业务验收

只读检查：

```bash
npm run smoke:customer -- --base-url http://127.0.0.1:4320
```

登录后检查模板、后台和用户状态接口：

```bash
npm run smoke:customer -- \
  --base-url http://127.0.0.1:4320 \
  --email <smoke-admin-email> \
  --password <smoke-admin-password>
```

真实写入验收：

```bash
npm run smoke:customer -- \
  --base-url http://127.0.0.1:4320 \
  --email <smoke-admin-email> \
  --password <smoke-admin-password> \
  --write
```

说明：

- `--write` 会创建一条小素材记录，用来验证数据库和 MinIO/S3 确实可写。
- 验收账号建议使用临时测试账号；脚本不会主动打印密码，但命令历史和 `.env.smoke` 也要按敏感信息处理。
- 没有最高权限的账号可加 `--no-expect-admin`，避免把正常的后台 403 误判成失败。

### 镜像体积和分层基线

```powershell
.\scripts\measure-image-size.ps1 `
  -Image "registry.example.com/flnxi/material/flnxi-material:1.0.1" `
  -OutputPath ".\reports\image-size-1.0.1.md" `
  -MaxImageSizeMB 650 `
  -MaxLayerCount 80 `
  -MaxLargestLayerMB 250
```

说明：

- 该脚本只读取本地 Docker 镜像，不构建、不推送、不删除。
- 报告会列出镜像总大小、RootFS 层数和最大的若干层。
- 传入体积或分层阈值后，超限会以非 0 退出，适合发布前阻止镜像明显变胖。
- 先有基线，再做 `ffmpeg`、字体、`canvas`、Prisma CLI 或生产依赖瘦身，避免凭感觉判断体积来源。

### 手工触发单个视频转码

```bash
npx tsx scripts/trigger-video-transcode.ts <素材ID>
```

## 五、相关文档

- `../README.md`
- `../docs/README.md`
- `../docs/deployment/部署说明.md`