146 lines
4.9 KiB
Markdown
146 lines
4.9 KiB
Markdown
# 脚本说明
|
||
|
||
`scripts/` 目录里既有当前仍在使用的脚本，也有历史遗留的人工运维脚本。这个文件只列“当前还应当优先关注”的入口。
|
||
|
||
## 一、通过 `package.json` 直接调用的脚本
|
||
|
||
### `migrate-template-data.ts`
|
||
|
||
用途：
|
||
|
||
- 修复历史模板数据
|
||
- 为素材补齐模板关联
|
||
- 做模板体系迁移后的收尾处理
|
||
|
||
运行：
|
||
|
||
```bash
|
||
npm run migrate:template-data
|
||
```
|
||
|
||
### `verify-template-data.ts`
|
||
|
||
用途：
|
||
|
||
- 校验模板、字段、素材之间的数据一致性
|
||
- 在部署后或修复后做确认
|
||
|
||
运行：
|
||
|
||
```bash
|
||
npm run verify:template-data
|
||
```
|
||
|
||
## 二、当前保留的手动脚本
|
||
|
||
### 构建相关
|
||
|
||
- `build-material-image.ps1`
|
||
构建主应用镜像。它属于历史/内部维护备用入口，保留旧的测试/正式分层规则，但仍带 Harbor / `latest` 旧口径；客户正式交付、升级、回滚优先用根目录的 `deploy-registry.ps1`，不要把它当成客户升级主线。若确需用它推送旧 Harbor，必须显式追加 `-AcknowledgeLegacyHarborPush`。
|
||
- `build-obfuscated.js`
|
||
生产构建后的服务端混淆处理。客户交付镜像通过 `Dockerfile` 执行 `npm run build:prod` 时会自动调用；混淆依赖或配置缺失会直接失败，不能静默跳过。
|
||
- `docker-entrypoint.sh`
|
||
主应用容器启动入口
|
||
- `generate-shared-test-env.ps1`
|
||
为共享测试机生成隔离后的 `.env`，避免容器名、卷名、网络名与其他项目冲突
|
||
- `smoke-install.ps1`
|
||
客户首装后的基础验收脚本，可检查 Compose 配置、容器状态、运行镜像、版本文件、迁移状态、MinIO bucket 和 `/api/health`
|
||
- `backup-restore.ps1`
|
||
客户环境备份、恢复和健康验收脚本；恢复必须显式输入确认短语，避免误覆盖客户数据
|
||
|
||
### 数据检查/修复相关
|
||
|
||
- `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. `build-material-image.ps1` 和 `generate-shared-test-env.ps1` 都偏内部维护，客户交付只在确实需要时使用。
|
||
5. 看到 Harbor、固定服务器、`latest` 的脚本，默认先当历史/内部入口处理，不要直接用于客户安装或升级。
|
||
|
||
## 四、常见流程
|
||
|
||
### 模板数据修复
|
||
|
||
```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` 不能默认当作当前可用入口。
|
||
|
||
### 客户首装基础验收
|
||
|
||
```powershell
|
||
.\scripts\smoke-install.ps1 -ProjectDir "D:\deploy\flnxi" -Start
|
||
```
|
||
|
||
说明：
|
||
|
||
- `-Start` 会执行 `docker compose up -d`；如果服务已经由 NAS 图形界面启动，可以不传，只做检查。
|
||
- 如果客户使用外部对象存储，可加 `-SkipObjectStorageCheck`。
|
||
- 如果刚启动后数据库迁移还没完成，脚本会在健康接口处等待一段时间，失败时输出应用日志帮助排查。
|
||
|
||
### 客户备份、恢复和验收
|
||
|
||
```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 文件、版本文件、镜像和容器状态。
|
||
- 外部数据库、外部对象存储由客户现场方案单独备份；脚本会写提示文件，不会假装自动覆盖。
|
||
- 对象存储备份/恢复使用 `busybox:1.36` 作为 helper 镜像；离线客户现场需要提前放入该镜像或通过 `-HelperImage` 指定现场已有镜像。
|
||
|
||
### 手工触发单个视频转码
|
||
|
||
```bash
|
||
npx tsx scripts/trigger-video-transcode.ts <素材ID>
|
||
```
|
||
|
||
## 五、相关文档
|
||
|
||
- `../README.md`
|
||
- `../docs/README.md`
|
||
- `../docs/deployment/部署说明.md`
|