## 初次部署与“出厂设置”指南

本指南覆盖 NAS/内网环境从零安装的完整流程，亦可用于将现有测试环境**一键恢复到出厂状态**。建议严格按顺序执行，并在自述中记录执行时间，便于后续追溯。

### 1. 环境准备
- 服务器/NAS：4C8G 以上、100GB 可用空间，建议启用 SSD/NVMe。
- 系统：Ubuntu 22.04 LTS 或群晖 DSM（需支持 Docker / Podman）。
- 依赖：Docker 24+、Docker Compose V2、Node.js 20（仅本地调试需要）、pnpm 或 npm。
- 网络：可访问对象存储（MinIO/S3），放通 80/443/3000/5432/9000 等常用端口。
- 证书：准备好公网域名和 TLS 证书（可选，Nginx/Traefik 层处理）。

### 2. 拉取代码与依赖
```bash
git clone https://your.repo/flnxi_sucai.git
cd flnxi_sucai
cp .env.example .env
npm install   # 或 pnpm install
```
- 将 `config-bianliang.env` 与 `.env` 一并填写，保证 `DATABASE_URL`、S3、域名、NEXTAUTH_SECRET 等关键变量存在。
- NAS 环境若使用外置 Postgres/MinIO，可在 `.env` 中直接指向局域网地址。

### 3. 数据库初始化 / 恢复出厂
> **⚠️ 会删除所有数据。** 确认已备份再执行。
```bash
npx prisma migrate reset --force --skip-seed
```
- 该命令会串行应用 `prisma/migrations` 下的所有迁移，包括最新的素材归属字段。
- 如果在容器内执行，确保 `DATABASE_URL` 已指向真实数据库。

### 4. 生成 Prisma Client
```bash
npx prisma generate
```
- Docker 镜像构建过程会自动执行；裸机调试时建议显式运行，避免 TS/构建期间的类型缺失。

### 5. 启动服务
```bash
# 开发 / 单机调试
npm run dev

# 生产部署（推荐）
docker compose -f docker-compose.prod.yml up -d --build
```
- Compose 会启动 Next.js、Nginx、Postgres、MinIO 等组件。若已有外部 Postgres/MinIO，可注释对应服务并调整 `.env`。

### 6. 系统初始化接口
部署启动后，调用一次 `POST /api/system/init` 即可创建默认资源：
```bash
curl -X POST https://your-domain.com/api/system/init
```
返回值示例：
```json
{
  "success": true,
  "message": "系统初始化成功",
  "data": {
    "admin": { "email": "admin", "username": "admin", "password": "88888888" },
    "defaultDepartment": "默认部门",
    "defaultCategory": "默认店铺",
    "defaultScene": "默认场景"
  }
}
```
- 首次登录后务必修改管理员密码，可在“个人中心 → 修改密码”完成。

### 7. 首次登录与检查
1. 访问 `https://your-domain.com/login`，使用 `admin / 88888888` 登录。
2. 进入后台 `/admin`，确认仪表盘可正常加载。
3. 打开“系统设置”，填写对象存储、LOGO、前端域名等信息。
4. 上传一份素材，验证转码、归属（`ownerType/ownerId`）、预览、下载链路是否正常。

### 8. 恢复为干净环境的快速指令
若需要再次“清空一切”并保留最新 schema，可直接执行：
```bash
npx prisma migrate reset --force --skip-seed
curl -X POST https://your-domain.com/api/system/init
```
可将上述两条命令收录到自定义脚本，例如 `scripts/reset-to-factory.ps1/.sh`，方便演示或客户验收前重置。

### 9. 常见问题
- **`prisma migrate reset` 卡在输入确认**：加上 `--force --skip-generate`/`--skip-seed` 使其无交互运行。
- **`postgres connection refused`**：确认容器/服务已启动，或在 `.env` 中关闭 TLS（`?sslmode=disable`）。
- **MinIO/S3 访问失败**：在 System Settings 中补齐 `s3Endpoint/s3Bucket/s3PublicUrl`，并确保对象存储已创建对应桶。
- **视频转码异常**：检查服务器是否已安装 `ffmpeg`，或在 Dockerfile 中启用 `apt install ffmpeg`。日志可在容器内 `/root/.pm2/logs` 或 `docker logs youyidian-3d-material` 查看。

### 10. 下一步
- 按照 `docs/USER_ONBOARDING_GUIDE.md` 给团队成员做首登引导。
- 开启钉钉登录、AI 改图、内网穿透等可选模块前，建议先在测试环境演练一遍整套流程。