# 商业化首装演练记录 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 环境。