194 lines
12 KiB
Markdown
194 lines
12 KiB
Markdown
# FLNXI素材库
|
||
|
||
一个遵循苹果设计语言的 3D 素材协作平台，聚焦企业/团队的私有化部署场景，内置 AI 辅助、部门权限、模板化元数据与可移植部署工具链。
|
||
|
||
> ⚠️ 建议先阅读根目录 `config-bianliang.env`，将域名、白名单、S3、钉钉等变量集中管理。系统启动时只会补充“未设置”的变量，不会覆盖已有的系统环境或 `.env/.env.local`。
|
||
|
||
## 🎯 项目概览
|
||
- **目标**：让其他团队能“一键部署 + 秒级迁移”，快速落地到自有 NAS、IDC 或混合网络环境。
|
||
- **当前定位**：设计/电商团队素材仓库 + 管理驾驶舱 + AI 实验场。
|
||
- **关键原则**：
|
||
- 性能开销优先：组件懒加载、API 分页、S3 断点重试，保证低配服务器也能跑。
|
||
- 稳定性优先：健康检查 `/api/health`、系统仪表盘 `/api/admin/system-status`、部署脚本全程日志。
|
||
- 易部署：配置集中化、Docker Compose 套件、PowerShell/Bash 安全部署脚本、环境备份。
|
||
|
||
更多编码规范与约束可参考 `./架构设计与编码规范.md`、`./docs/PORTABLE_DEPLOYMENT_GUIDE.md`。
|
||
|
||
## 🌟 功能亮点（2025/11 最新版）
|
||
|
||
### 面向素材使用者
|
||
- **门户体验**：首页卡片流展示、支持品牌/系列/SKU/渲染参数的多维搜索与筛选，附带点赞、下载、分享、榜单。
|
||
- **AI 智能体**：`components/AIChatWidget.tsx` 绑定 Gemini，多模态对话、最多 5 张参考图上传、自动生成 4 张风格稿。
|
||
- **实时互动**：`DanmakuWidget` 支持匿名弹幕；`RankingPanel` 展示贡献/下载/点赞排行榜，可拖拽定位。
|
||
- **分享场景**：`/share/[id]` 公开链接可曝光素材详情（脱敏流量）；`/complete-profile` 协助钉钉首次登录用户补全部门信息。
|
||
- **网络自识别**：`/api/network-status` 根据 IP & 域名判断当前处于内/公网，自动提示内网地址。
|
||
|
||
### 面向管理员
|
||
- **驾驶舱首页**：`/admin` 默认进入“监控仪表板”，展示 30 天新增、部门/角色分布、活跃度、最近上传等。
|
||
- **权限与部门**：支持“部门管理员”操控子部门、折叠/搜索组织树、邀请链接 (`/api/invitations`) 与首位用户自动超级管理员 (`verify_first_user.js`)。
|
||
- **模板/字段体系**：`TemplateManager` 内置多套电商模板，字段支持拖拽排序、可见性、下拉选项（单行文本规则），并与上传页/筛选器联动。拖拽交互流畅，松开鼠标后立即更新布局。
|
||
- **分类配置**：分类/场景/平台均支持自定义下拉列表，后台统一管理（`/api/categories|scenes|platforms`）。
|
||
- **素材深度信息**：`Material` 模型新增品牌、系列、SKU、材质、渲染耗时、输出分辨率、色彩模式等字段，全流程读写。
|
||
- **系统设置**：LOGO、S3、注册/激活、AI 改图、内网穿透等开关存储于 `SystemSettings`，与 `config-bianliang.env` 协同。
|
||
- **数据恢复**：`/api/restore-data` 可结合 S3 桶与本地 `uploads/` 批量匹配预览/压缩包并导入数据库（含管理员账号回填）。
|
||
- **Ops 工具**：内置 `/api/tunnel/*` 占位接口用于 FRP/ZeroTier 控制，配合 `featureFlags.tunnelEnabled` 与 SystemSettings。
|
||
|
||
### 运维、部署与生态
|
||
- `config-bianliang.env`：将域名、白名单、S3、钉钉、内外网地址、RESTORE 桶等集中管理，实现“拷贝项目即可部署”。
|
||
- `scripts/deploy/`：包含 `安全部署.ps1/.sh`、`deploy-new-fixed.ps1`（阶段化进度）、`deploy-new.ps1`、`local-build-and-upload.ps1` 等脚本。
|
||
- Docker 套件：`docker-compose.dev.yml`（带热更新）、`docker-compose.prod.yml`、`docker-compose.standard.yml`、`docker-compose-registry.yml` 等。
|
||
- 诊断资源：`docs/guides/`、`docs/reports/`、`env-backups/`、`deploy-artifacts/`、`deploy-log.txt`、`temp_stdout/stderr`，便于回溯问题。
|
||
|
||
## 🧱 技术栈
|
||
- **应用层**：Next.js 14 App Router、React 18、TypeScript、TailwindCSS。
|
||
- **认证**：NextAuth.js + 邮箱密码 + 钉钉 OAuth。
|
||
- **数据访问**：Prisma 5.22 + PostgreSQL（dev 默认 `prisma/dev.db` SQLite，生产建议 Postgres 15+）。
|
||
- **存储**：MinIO / S3 兼容对象存储（预览图）+ 本地/NAS `uploads/`（压缩包）。
|
||
- **AI 服务**：Google Gemini API（`GEMINI_API_KEY`），`/api/ai-chat`、`/api/ai/edit`。
|
||
- **其他**：Next Middleware CORS、防火墙探测、bcrypt、AWS SDK v3、Formidable 上传、clsx/date-fns/zod。
|
||
|
||
## 🗂️ 项目结构速览
|
||
|
||
```
|
||
.
|
||
├── app/
|
||
│ ├── page.tsx # 门户首页
|
||
│ ├── login|register|complete-profile
|
||
│ ├── share/[id]/ # 公开分享页
|
||
│ ├── dingtalk-callback/ # 钉钉扫码落地页
|
||
│ ├── admin/
|
||
│ │ ├── page.tsx # 后台入口 + 标签页
|
||
│ │ ├── monitor/ # 仪表盘视图
|
||
│ │ ├── settings/ # 系统设置
|
||
│ │ └── _components/TemplateManager.tsx 等
|
||
│ └── api/
|
||
│ ├── materials|categories|scenes|platforms|rankings
|
||
│ ├── admin/… # 权限、系统状态、用户
|
||
│ ├── dingtalk/… # 钉钉登录 & 资料完善
|
||
│ ├── ai-chat/ | ai/edit/ # Gemini 对话/改图
|
||
│ ├── invitations|departments|tunnel|restore-data
|
||
│ ├── danmaku|network-status|health
|
||
│ └── …（详见 `app/api`）
|
||
├── components/ # UploadModal、EditMaterialModal、AIChatWidget、DanmakuWidget、RankingPanel…
|
||
├── lib/ # `auth.ts`、`prisma.ts`、`s3.ts`、`config.ts`、`network.ts`
|
||
├── prisma/ # schema、migrations、dev.db
|
||
├── scripts/ # deploy、tools、server、update-file-sizes…
|
||
├── docs/ # guides、reports、chats、WORKFLOW
|
||
├── config-bianliang.env # 可迁移化配置示例
|
||
├── docker-compose*.yml / Dockerfile
|
||
├── deploy-*.ps1 # 部署脚本
|
||
├── env-backups/ / deploy-artifacts/ # 产物与环境备份
|
||
└── uploads/ # 本地压缩包目录
|
||
```
|
||
|
||
## ⚙️ 环境变量与配置
|
||
|
||
### 基础必填
|
||
| 变量 | 用途 |
|
||
| --- | --- |
|
||
| `DATABASE_URL` | 指向 PostgreSQL 或 SQLite（开发）连接串 |
|
||
| `NEXTAUTH_SECRET` | NextAuth 加密密钥 |
|
||
| `NEXTAUTH_URL` / `APP_PUBLIC_URL` | 生成绝对链接、OAuth 回调、邀请链接 |
|
||
| `S3_ENDPOINT` / `S3_BUCKET` / `S3_PUBLIC_DOMAIN` / `S3_ACCESS_KEY_ID` / `S3_SECRET_ACCESS_KEY` / `S3_REGION` | MinIO/S3 上传、预览图读取 |
|
||
| `S3_ENV_PREFIX` / `S3_FILE_PATH` | 同桶多环境隔离，前缀自动拼接 |
|
||
| `ALLOWED_ORIGINS` | CORS 白名单（逗号分隔） |
|
||
| `IMAGE_REMOTE_HOSTS` | Next/Image 远程域名（逗号分隔） |
|
||
| `PUBLIC_DOMAINS` / `NEXT_PUBLIC_PUBLIC_DOMAINS` | 公网域名识别（含前端版本） |
|
||
| `NEXT_PUBLIC_PORTAL_BASE_URL` / `NEXT_PUBLIC_INTRANET_URL` | 分享 & 网络状态提示 |
|
||
| `NEXT_PUBLIC_DEFAULT_HEADER_LOGO_URL` / `NEXT_PUBLIC_DEFAULT_LOGIN_LOGO_URL` | 默认 LOGO |
|
||
|
||
### 可选增强
|
||
| 变量 | 说明 |
|
||
| --- | --- |
|
||
| `GEMINI_API_KEY` / `GEMINI_API_BASE_URL` / `GEMINI_MODEL` | AI 聊天/生成配置 |
|
||
| `DINGTALK_CLIENT_ID` / `DINGTALK_CLIENT_SECRET` | 钉钉扫码登录 |
|
||
| `NEXT_PUBLIC_DINGTALK_CALLBACK_URL` | 前端跳转地址 |
|
||
| `RESTORE_S3_BUCKET_URL` / `RESTORE_S3_PUBLIC_URL` | `/api/restore-data` 用于扫描历史素材 |
|
||
| `AI_EDIT_ENABLED` / `TUNNEL_ENABLED` | Feature Flag（也可在 SystemSettings 开启） |
|
||
| `APP_PUBLIC_URL` | 优先用于邀请链接、分享、邮件通知 |
|
||
|
||
### config-bianliang.env
|
||
- 位置：项目根目录。
|
||
- 适用：NAS、客户现场多域名切换、Batch 部署。
|
||
- 生效顺序：`系统环境 > .env(.local) > config-bianliang.env`。
|
||
- 修改后需重启 Node 或容器。
|
||
|
||
## 🚀 快速开始
|
||
1. **安装依赖**
|
||
```bash
|
||
npm install
|
||
```
|
||
2. **复制环境模板并补齐配置**
|
||
```bash
|
||
cp .env.example .env # 若在 Windows，可手动复制
|
||
```
|
||
> 建议同步编辑 `config-bianliang.env`，以便后续迁移。
|
||
3. **数据库初始化**
|
||
```bash
|
||
npm run prisma:generate
|
||
npm run prisma:push # 或 `npx prisma migrate deploy`
|
||
```
|
||
4. **创建第一个账号**
|
||
- 前台注册后，将该用户 `role` 更新为 `ADMIN`、`isSuperAdmin = true`。
|
||
- 或运行 `node verify_first_user.js` 检查首位用户权限是否正确。
|
||
5. **可选自检**
|
||
```bash
|
||
npm run check # type-check + lint + prisma validate
|
||
npm run prisma:studio
|
||
```
|
||
6. **启动开发服务**
|
||
```bash
|
||
npm run dev
|
||
# http://localhost:3000
|
||
```
|
||
7. **Docker 开发模式**
|
||
```bash
|
||
docker compose -f docker-compose.dev.yml up --build
|
||
```
|
||
|
||
## 🔧 常用脚本 & 工具
|
||
- `npm run build`：自动执行 `prisma generate` 后构建 Next。
|
||
- `npm run lint` / `npm run type-check`。
|
||
- `npm run prisma:studio`、`npm run prisma:push`。
|
||
- `node fix_user_permissions.js` / `update-file-sizes*.js` 等工具脚本。
|
||
- `scripts/deploy/安全部署.ps1|.sh`：标准部署入口。
|
||
- `deploy-new-fixed.ps1`：阶段化本地打包 -> 镜像 -> 推送 -> 远程 compose，自动轮询 `/api/health`。
|
||
- `scripts/tools/quick-start.sh`：常用容器编排。
|
||
|
||
## 🗄️ 数据模型速览
|
||
- **User**：`role`, `managedDepartment`, `isSuperAdmin`, `loginType`, `dingtalkUserId`, `canDownload`, `isActive`。
|
||
- **Material**：`brandName`, `seriesName`, `skuCode`, `materialTexture`, `platformName`, `renderTime`, `imageResolution`, `colorMode`, `displayImages`, `templateId`。
|
||
- **UploadTemplate / UploadField**：模板字段、布局、校验、下拉配置。
|
||
- **Category / Scene / Platform**：支持 `options`（文本每行一个值）。
|
||
- **Department**：树状管理（`parentId` 在 User 中维护）。
|
||
- **Invitation**：多次/过期控制，生成邀请码链接。
|
||
- **Danmaku / MaterialLike / FilterItem / SystemSettings**：互动、个性化和系统开关。
|
||
|
||
完整定义见 `prisma/schema.prisma`。
|
||
|
||
## 📦 部署与运维
|
||
- **一键部署**：`./一键部署快速指南.md`、`./一键部署完整指南.md`、`./docs/guides/安全部署指南.md`。
|
||
- **Docker**：`docker-compose.yml`（默认生产）、`docker-compose.prod.yml`（显式生产）、`docker-compose.standard.yml`（多服务）、`docker-compose-registry.yml`（私有镜像仓库）。
|
||
- **PowerShell**：`deploy-fixed.ps1`、`deploy-new-fixed.ps1`（推荐）、`deploy-new.ps1`（实验版）。
|
||
- **健康检查**：脚本完成后会轮询 `GET /api/health`，也可由外部监控使用 `HEAD /api/health`。
|
||
- **日志与产物**：`deploy-log.txt`、`deploy-artifacts/*.tar`、`env-backups/*.env`。
|
||
- **网络与安全**：`secure_ssh.ps1`、`scripts/server/*.sh`、`docs/guides/SSH安全评估报告.md`。
|
||
|
||
## 🆘 自检 & 排障
|
||
- 前端浮动面板内含“网络检测”“AI 聊天”“弹幕”；后台仪表盘提供系统状态。
|
||
- `logs/` 与 `temp_stdout|stderr.txt` 保存最近脚本输出。
|
||
- `docs/guides/上传问题完整解决方案.md`、`docs/guides/FRP服务器诊断修复报告.md` 提供针对性排障。
|
||
- `/api/admin/system-status` 若返回 403，检查是否使用管理员或超级管理员登录。
|
||
- S3 上传失败将尝试 10 次自动重试（`lib/s3.ts`），最终报错请检查存储桶权限与 `S3_PUBLIC_DOMAIN`。
|
||
|
||
## 📚 文档入口
|
||
- 开发流程：`docs/WORKFLOW.md`
|
||
- 部署规范：`docs/PORTABLE_DEPLOYMENT_GUIDE.md`、`docs/guides/安全部署说明.md`
|
||
- 需求实现记录：`docs/FEATURE_REQUESTS_IMPLEMENTATION.md`
|
||
- 变更日志：`CHANGELOG.md`（示例：2025-11「权限进化 & 电商加成」版本）
|
||
- 历史问题：`docs/reports/*`、`.specstory/history/*`
|
||
|
||
## 📝 License
|
||
|
||
MIT
|