flnxi-Wu/docs/初次部署与出厂设置指南.md

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

本指南只覆盖 NAS/内网环境从零安装后的初始化流程，以及测试/演示环境的“出厂重置”收口。正式客户首装和版本化发布请优先看 docs/deployment/部署说明.md 与 deploy-registry.ps1，不要把本文件当成客户交付主线。

1. 环境准备

• 服务器/NAS：4C8G 以上、100GB 可用空间，建议启用 SSD/NVMe。
• 系统：Ubuntu 22.04 LTS 或群晖 DSM（需支持 Docker / Podman）。
• 依赖：Docker 24+、Docker Compose V2；Node.js 20 仅本地调试需要，主应用生产镜像当前基于 node:18-alpine。
• 包管理：当前仓库使用 package-lock.json，本地开发以 npm 为准。
• 网络：可访问对象存储（MinIO/S3），按实际部署放通 80/443、默认应用端口 4320、数据库和对象存储端口等。
• 证书：准备好公网域名和 TLS 证书（可选，由 Nginx / Traefik 等反向代理层处理）。

2. 拉取代码与依赖

git clone https://your.repo/flnxi_sucai.git
cd flnxi_sucai
cp .env.example .env
npm install

• 如现场已有 config-bianliang.env，可作为现场补充变量文件；正式新装优先按 .env.example 和部署说明填写 .env，保证 DATABASE_URL、S3、域名、NEXTAUTH_SECRET 等关键变量存在。
• 当前仓库没有 pnpm-lock.yaml，不要把 pnpm 当作默认安装方式。
• 不要把 config-bianliang.env 当成通用必填项；现场没有它时，直接按 .env.example 和部署文档要求的 .env 走。
• 如果启用许可证服务，必须同时填写 LICENSE_SERVER_URL 和 LICENSE_PROJECT_CODE，且 LICENSE_PROJECT_CODE 必须和 license-server 项目编码一致。
• NAS 环境若使用外置 Postgres/MinIO，可在 .env 中直接指向局域网地址。

3. 数据库初始化

主应用容器启动后会自动执行迁移。正式新装通常不需要手工 reset，除非你是在测试/演示环境里故意清空数据。

• 如果只是正常首装，继续看后面的启动服务步骤即可。
• 如果要清空测试库，请跳到文末的“测试/演示环境恢复出厂”。

4. 生成 Prisma Client

npx prisma generate

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

5. 启动服务

# 开发 / 单机调试
npm run dev

# 生产部署（请先看部署说明中的版本化 Registry 发布链路）
docker compose -f docker-compose.prod.yml up -d

• 当前 docker-compose.prod.yml 会启动主应用、PostgreSQL、MinIO 和 MinIO 初始化容器；不会直接启动 Nginx / Traefik。若已有外部 Postgres / MinIO，可按现场调整编排与 .env。
• 如果是正式客户交付，先完成镜像发布和版本 tag 确认，再在目标机器执行部署说明里的启动命令。

6. 系统初始化接口

常规许可证激活流程会自动完成系统初始化。

如果需要在“尚未有管理员账号”的环境里手动初始化，必须先配置 SYSTEM_INIT_TOKEN，再调用：

curl -X POST https://your-domain.com/api/system/init \
  -H "x-system-init-token: your-init-token"

返回值中会带出本次创建的初始管理员信息；如果没有预先配置 INIT_ADMIN_PASSWORD，系统会生成一次性初始密码并只在初始化响应/激活成功页展示一次。

• 首次登录后会被强制修改密码，可在“个人中心 → 修改密码”完成。

7. 首次登录与检查

1. 访问 https://your-domain.com/login，使用初始化返回的初始管理员账号登录。
2. 进入主应用后台 /admin；项目选择页属于独立 license-server 后台，不是主应用后台流程。
3. 打开“系统设置”，填写对象存储、LOGO、前端域名等信息。
4. 上传一份素材，验证转码、归属（ownerType/ownerId）、预览、下载链路是否正常。

如果涉及许可证服务联调，建议继续按 docs/许可证服务接入说明.md 检查项目编码和公开接口路径。

8. 测试/演示环境恢复出厂（高风险）

⚠️ 会删除所有数据。只适合测试/演示环境，不适合客户正式库。

若需要再次“清空一切”并保留最新 schema，可直接执行：

npx prisma migrate reset --force --skip-seed
curl -X POST https://your-domain.com/api/system/init \
  -H "x-system-init-token: your-init-token"

可将上述两条命令收录到自定义脚本，例如 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，并查看 docker logs flnxi-material。如容器名通过 .env 覆盖，以实际 APP_CONTAINER_NAME 为准。

10. 下一步

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