91 lines
4.0 KiB
Markdown
91 lines
4.0 KiB
Markdown
## 初次部署与“出厂设置”指南
|
||
|
||
本指南覆盖 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 改图、内网穿透等可选模块前，建议先在测试环境演练一遍整套流程。
|
||
|
||
|