WuYongJie/flnxi-Wu
WuYongJie/flnxi-Wu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
flnxi-Wu/scripts/README.md
WuYongJie e839ef100a 完善升级恢复指引与镜像体积基线
2026-06-01 11:40:34 +08:00

5.5 KiB
Raw Blame History

脚本说明

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

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

migrate-template-data.ts

用途：

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

运行：

npm run migrate:template-data

verify-template-data.ts

用途：

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

运行：

npm run verify:template-data

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

构建相关

  • build-obfuscated.js 生产构建后的服务端混淆处理。客户交付镜像通过 Dockerfile 执行 npm run build:prod 时会自动调用；混淆依赖或配置缺失会直接失败，不能静默跳过。
  • docker-entrypoint.sh 主应用容器启动入口
  • smoke-install.ps1 客户首装后的基础验收脚本，可检查 Compose 配置、容器状态、运行镜像、版本文件、迁移状态、MinIO bucket 和 /api/health
  • 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 只给共享测试机或内部联调用，客户交付不要把它当安装器。

四、常见流程

模板数据修复

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

检查并修复模板缺失

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

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

.\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 不能默认当作当前可用入口。

客户首装基础验收

.\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。
  • 如果刚启动后数据库迁移还没完成，脚本会在健康接口处等待一段时间，失败时输出应用日志帮助排查。

客户备份、恢复和验收

.\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 指定现场已有镜像。

镜像体积和分层基线

.\scripts\measure-image-size.ps1 `
  -Image "registry.example.com/flnxi/material/flnxi-material:1.0.1" `
  -OutputPath ".\reports\image-size-1.0.1.md"

说明：

  • 该脚本只读取本地 Docker 镜像，不构建、不推送、不删除。
  • 报告会列出镜像总大小、RootFS 层数和最大的若干层。
  • 先有基线，再做 ffmpeg、字体、canvas、Prisma CLI 或生产依赖瘦身，避免凭感觉判断体积来源。

手工触发单个视频转码

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

五、相关文档

  • ../README.md
  • ../docs/README.md
  • ../docs/deployment/部署说明.md