WuYongJie/flnxi-Wu
WuYongJie/flnxi-Wu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
flnxi-Wu/docs/商业化首装演练记录_20260601.md
WuYongJie 3256524271 补齐 NAS 客户首装备份验收脚本
2026-06-01 15:26:33 +08:00

7.4 KiB
Raw Blame History

商业化首装演练记录 2026-06-01

本文记录本轮在本机飞牛 fnOS 虚拟机上的客户首装验收情况。只沉淀环境事实、验证结果和后续坑位，不记录 SSH 密码、许可证密钥、对象存储密钥或其它敏感信息。

1. 演练结论

  • 飞牛 fnOS 虚拟机可以作为当前商业化首装/验收测试环境。
  • 当前已有一套 flnxi-fnos-smoke 环境运行正常，未覆盖、未删除。
  • 新增的 NAS / Linux 首装验收脚本 scripts/customer-install.sh 和 scripts/smoke-install.sh 已在飞牛 VM 上通过只读验收。
  • 客户首装的真实主入口仍是 docker-compose.prod.yml + .env；脚本只是预检、启动和验收包装。

2. 环境现场

  • 虚拟机地址：192.168.116.128
  • 系统：Linux / fnOS，内核 6.18.18-trim
  • Docker Server：28.5.2
  • 可用磁盘：/vol1 约 35G
  • 飞牛 Web 管理端：5666
  • 当前测试部署目录：/vol1/flnxi-customer-smoke

当前运行中的 FLNXI 容器：

  • flnxi-fnos-smoke-app
  • flnxi-fnos-smoke-postgres
  • flnxi-fnos-smoke-minio

当前测试端口：

  • 应用：4320 -> 3000
  • MinIO API：39200 -> 9000
  • MinIO Console：39201 -> 9001

3. 已验证内容

3.1 远端健康检查

远端本机访问：

curl http://127.0.0.1:4320/api/health

结果：返回 status: ok，启动检查执行成功。

登录页：

curl -I http://127.0.0.1:4320/login

结果：返回 HTTP/1.1 200 OK。

3.2 NAS / Linux 首装向导

已把本轮新增脚本复制到测试部署目录：

/vol1/flnxi-customer-smoke/scripts/customer-install.sh
/vol1/flnxi-customer-smoke/scripts/smoke-install.sh
/vol1/flnxi-customer-smoke/scripts/backup-restore.sh
/vol1/flnxi-customer-smoke/scripts/customer-acceptance-smoke.mjs

只看步骤：

bash /vol1/flnxi-customer-smoke/scripts/customer-install.sh \
  --project-dir /vol1/flnxi-customer-smoke \
  --plan-only

结果：通过，能按 4 步展示预检、启动方式、验收和结果说明。

安装前检查：

sudo bash /vol1/flnxi-customer-smoke/scripts/smoke-install.sh \
  --project-dir /vol1/flnxi-customer-smoke \
  --preflight-only

结果：通过。

只读验收：

sudo bash /vol1/flnxi-customer-smoke/scripts/smoke-install.sh \
  --project-dir /vol1/flnxi-customer-smoke \
  --health-timeout-seconds 60

结果：通过。

脚本已验证：

  • Compose 配置有效
  • 三个容器运行正常
  • 应用镜像为 flnxi-material:customer-smoke-20260530
  • 镜像内 VERSION.txt 为 1.0.0
  • /api/health 正常
  • Prisma 迁移状态为最新
  • MinIO bucket 存在

3.3 NAS / Linux 备份验收

备份前健康验收：

sudo bash /vol1/flnxi-customer-smoke/scripts/backup-restore.sh \
  --project-dir /vol1/flnxi-customer-smoke \
  --action verify \
  --health-timeout-seconds 60

结果：通过。

实际备份：

sudo bash /vol1/flnxi-customer-smoke/scripts/backup-restore.sh \
  --project-dir /vol1/flnxi-customer-smoke \
  --action backup \
  --health-timeout-seconds 60

结果：备份成功，生成目录：

/vol1/flnxi-customer-smoke/backups/flnxi-backup-20260601-150351

备份内容包括：

  • .env
  • docker-compose.prod.yml
  • compose-config.txt
  • compose-ps.txt
  • docker-images.txt
  • postgres.sql
  • minio-data.tar.gz
  • data.tar.gz
  • uploads.tar.gz
  • manifest.json
  • README-SENSITIVE.txt

补充修正脚本后再次备份，生成目录：

/vol1/flnxi-customer-smoke/backups/flnxi-backup-20260601-150543

这次脚本在备份结束后自动等待健康检查，/api/health 再次返回 status: ok。

3.4 客户业务 smoke

本轮新增：

npm run smoke:customer -- --base-url http://<SERVER_IP>:4320

该脚本用于补足“容器活着但业务不一定可用”的空白：

  • 只读模式检查 /api/health、/api/system/init、/login 和未登录后台拦截。
  • 提供临时验收账号后，检查登录、上传模板、内置模板、默认密码检查和后台用户接口。
  • 加 --write 后，执行一次真实小素材上传，验证数据库和 MinIO/S3 写入。

本轮在飞牛 VM 上已验证：

  • 只读模式通过。
  • 使用临时 smoke 管理员登录后，模板接口、默认密码检查和后台用户接口通过。
  • --write 上传被许可证拦截，返回：当前许可证最多支持 0 个素材，当前已有 0 个素材。请联系管理员处理授权。 这说明当前 VM 的许可证状态不允许素材写入；脚本能正确把这类业务验收失败暴露出来。后续要验证真实上传，需要先给测试环境配置允许上传的许可证或换到已授权环境。
  • 临时 smoke 管理员已在验证结束后删除，未作为长期账号保留。

4. 已发现和处理的坑

4.1 不能只提供 PowerShell 首装脚本

目标客户环境是 NAS / Linux，不能默认现场有 PowerShell。已新增：

  • scripts/customer-install.sh
  • scripts/smoke-install.sh
  • scripts/backup-restore.sh
  • scripts/customer-acceptance-smoke.mjs

文档已同步说明：NAS / Linux 优先 .sh，Windows 实施机或已安装 PowerShell 的现场可用 .ps1。

4.2 只换目录不够，必须换容器名/卷名/端口

飞牛 VM 上已经有一套 flnxi-fnos-smoke。后续如果做全新目录演练，必须在 .env 里同时修改：

  • COMPOSE_PROJECT_NAME
  • APP_CONTAINER_NAME
  • POSTGRES_CONTAINER_NAME
  • MINIO_CONTAINER_NAME
  • MINIO_INIT_CONTAINER_NAME
  • POSTGRES_VOLUME_NAME
  • MINIO_VOLUME_NAME
  • APP_NETWORK_NAME
  • APP_PORT
  • MINIO_API_PORT
  • MINIO_CONSOLE_PORT

否则可能撞旧容器、旧卷、旧网络或端口。

4.3 fnOS 上 Docker 需要 sudo

当前 admin 用户不能直接访问 Docker daemon，脚本需要用 sudo bash ... 执行，或把实施账号加入合适的 Docker 权限组。

4.4 admin 家目录提示不阻断

SSH 登录会提示：

Could not chdir to home directory /home/admin: No such file or directory

这不影响命令执行，但如果后续做长期自动化，建议在飞牛系统里补齐该用户家目录或换成更标准的实施账号。

4.5 备份后必须等待应用健康

第一次跑 backup-restore.sh --action backup 时，备份本身成功，脚本也重新启动了 app，但外部立刻请求 /api/health 会遇到应用刚启动的短暂窗口期。已修正脚本：如果备份前停止过 app，备份结束后会自动执行健康验收，避免实施人员误以为恢复启动失败。

4.6 业务 smoke 能暴露许可证限制

当前飞牛 VM 的许可证允许素材数为 0，所以真实上传 smoke 会失败。这不是脚本失败，而是业务前置条件没有满足。第一版商业化验收时，必须把“许可证是否允许上传”放进验收清单，否则系统容器正常也可能无法交付使用。

5. 下一步建议

  1. 新建独立目录做一次真正“空目录首装”，不要覆盖 /vol1/flnxi-customer-smoke。
  2. 目录建议：/vol1/flnxi-commercial-rehearsal-20260601。
  3. 新 .env 必须使用独立容器名、卷名、网络名和端口，例如应用端口可用 4322。
  4. 首装通过后，再做上传、模板、备份、升级和回滚演练。
  5. 当前 Linux 版已覆盖首装、容器验收、备份和客户业务 smoke；真实上传验收还需要一份允许上传的测试许可证；恢复演练需要在单独演练环境执行，不能覆盖已有 smoke 环境。