flnxi-Wu/安装与出厂设置指南.md

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

本指南覆盖 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. 拉取代码与依赖

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. 数据库初始化 / 恢复出厂

⚠️ 会删除所有数据。 确认已备份再执行。

npx prisma migrate reset --force --skip-seed

• 该命令会串行应用 prisma/migrations 下的所有迁移，包括最新的素材归属字段。
• 如果在容器内执行，确保 DATABASE_URL 已指向真实数据库。

4. 生成 Prisma Client

npx prisma generate

• Docker 镜像构建过程会自动执行；裸机调试时建议显式运行，避免 TS/构建期间的类型缺失。

5. 启动服务

# 开发 / 单机调试
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 即可创建默认资源：

curl -X POST https://your-domain.com/api/system/init

返回值示例：

{
  "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，可直接执行：

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 flnxi-material 查看。

10. 下一步

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