235 lines
7.4 KiB
Markdown
235 lines
7.4 KiB
Markdown
# 商业化首装演练记录 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 远端健康检查
|
||
|
||
远端本机访问：
|
||
|
||
```bash
|
||
curl http://127.0.0.1:4320/api/health
|
||
```
|
||
|
||
结果：返回 `status: ok`，启动检查执行成功。
|
||
|
||
登录页：
|
||
|
||
```bash
|
||
curl -I http://127.0.0.1:4320/login
|
||
```
|
||
|
||
结果：返回 `HTTP/1.1 200 OK`。
|
||
|
||
### 3.2 NAS / Linux 首装向导
|
||
|
||
已把本轮新增脚本复制到测试部署目录：
|
||
|
||
```bash
|
||
/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
|
||
bash /vol1/flnxi-customer-smoke/scripts/customer-install.sh \
|
||
--project-dir /vol1/flnxi-customer-smoke \
|
||
--plan-only
|
||
```
|
||
|
||
结果：通过，能按 4 步展示预检、启动方式、验收和结果说明。
|
||
|
||
安装前检查：
|
||
|
||
```bash
|
||
sudo bash /vol1/flnxi-customer-smoke/scripts/smoke-install.sh \
|
||
--project-dir /vol1/flnxi-customer-smoke \
|
||
--preflight-only
|
||
```
|
||
|
||
结果：通过。
|
||
|
||
只读验收：
|
||
|
||
```bash
|
||
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 备份验收
|
||
|
||
备份前健康验收：
|
||
|
||
```bash
|
||
sudo bash /vol1/flnxi-customer-smoke/scripts/backup-restore.sh \
|
||
--project-dir /vol1/flnxi-customer-smoke \
|
||
--action verify \
|
||
--health-timeout-seconds 60
|
||
```
|
||
|
||
结果：通过。
|
||
|
||
实际备份：
|
||
|
||
```bash
|
||
sudo bash /vol1/flnxi-customer-smoke/scripts/backup-restore.sh \
|
||
--project-dir /vol1/flnxi-customer-smoke \
|
||
--action backup \
|
||
--health-timeout-seconds 60
|
||
```
|
||
|
||
结果：备份成功，生成目录：
|
||
|
||
```text
|
||
/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`
|
||
|
||
补充修正脚本后再次备份，生成目录：
|
||
|
||
```text
|
||
/vol1/flnxi-customer-smoke/backups/flnxi-backup-20260601-150543
|
||
```
|
||
|
||
这次脚本在备份结束后自动等待健康检查，`/api/health` 再次返回 `status: ok`。
|
||
|
||
### 3.4 客户业务 smoke
|
||
|
||
本轮新增：
|
||
|
||
```bash
|
||
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 登录会提示：
|
||
|
||
```text
|
||
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 环境。
|