1d03717ff9
- docker-compose.prod.yml: runtime镜像改为从flnxi-public拉取 - 发布管理.ps1: Agent推送到flnxi-public公开项目 - Runtime镜像同步到flnxi-public项目 - 素材系统保持在flnxi私有项目
FLNXI素材库
一个遵循苹果设计语言的 3D 素材协作平台，专注企业/团队的私有化部署场景，内置 AI 辅助、部门权限、模板化元数据与可移植部署工具链。
🎯 项目概览
- 目标：让团队能"一键部署 + 秒级迁移"，快速落地到自有 NAS、IDC 或混合网络环境
- 定位：设计/电商团队素材仓库 + 管理驾驶舱 + AI 实验场
- 原则：性能优先、稳定性优先、易部署
🌟 核心功能
素材管理
- 智能搜索：多维度筛选（品牌/系列/SKU/渲染参数）
- 模板系统：自定义字段、拖拽排序、动态表单
- 批量操作：上传、下载、分享、标签管理
- 版本控制：并发冲突检测、自动版本递增
权限管理
- 部门体系：树状组织结构、部门管理员
- 角色权限：超级管理员、管理员、普通用户
- 邀请系统：邀请链接、多次使用、过期控制
AI 功能
- 智能对话：Gemini 多模态对话
- 图像生成：自动生成风格稿
- 智能标签：自动提取素材信息
系统特性
- 健康检查：
/api/health端点 - 系统监控：资源使用、性能指标
- 数据恢复：S3 桶扫描、批量导入
- 网络自识别：内外网自动切换
🧱 技术栈
- 前端：Next.js 14 App Router、React 18、TypeScript、TailwindCSS
- 认证：NextAuth.js + 邮箱密码 + 钉钉 OAuth
- 数据库：Prisma 5.22 + PostgreSQL
- 存储：MinIO / S3 兼容对象存储
- AI：Google Gemini API
- 测试：Jest + React Testing Library（118个单元测试）
🚀 快速开始
1. 安装依赖
npm install
2. 配置环境变量
cp .env.example .env
编辑 .env 文件，配置必要的环境变量：
# 数据库
DATABASE_URL=postgresql://user:password@localhost:5432/flnxi_material
# 认证
NEXTAUTH_SECRET=your-secret-key
NEXTAUTH_URL=http://localhost:3000
# S3存储
S3_ENDPOINT=https://s3.example.com
S3_BUCKET=your-bucket
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
3. 初始化数据库
npm run prisma:generate
npm run prisma:push
4. 启动开发服务
npm run dev
# 访问 http://localhost:3000
5. 创建管理员账号
首次注册的用户会自动成为超级管理员。
🔧 开发命令
# 开发
npm run dev # 启动开发服务器
npm run build # 构建生产版本
npm start # 启动生产服务器
# 测试
npm test # 运行测试
npm run test:watch # 监听模式
npm run test:coverage # 生成覆盖率报告
# 代码质量
npm run lint # ESLint检查
npm run type-check # TypeScript类型检查
npm run check # 完整检查（类型+lint+prisma）
# 数据库
npm run prisma:generate # 生成Prisma客户端
npm run prisma:push # 推送schema到数据库
npm run prisma:studio # 打开Prisma Studio
npm run prisma:validate # 验证schema
# 数据迁移
npm run migrate:template-data # 迁移模板数据
npm run verify:template-data # 验证数据完整性
📦 生产部署
使用Harbor部署（推荐）
# 1. 本地构建并推送到Harbor
.\deploy-new-fixed.ps1 -Registry harbor
# 2. SSH到服务器执行数据迁移
ssh root@your-server
cd /root/deploy
docker exec flnxi-material npx prisma migrate deploy
docker exec flnxi-material npm run migrate:template-data
docker exec flnxi-material npm run verify:template-data
# 3. 验证部署
# 访问 http://your-server:4320
Docker Compose部署
# 生产环境
docker-compose -f docker-compose.prod.yml up -d
# 开发环境
docker-compose -f docker-compose.dev.yml up -d
详细部署文档：
🗂️ 项目结构
.
├── app/ # Next.js App Router
│ ├── page.tsx # 首页
│ ├── admin/ # 管理后台
│ └── api/ # API路由
├── components/ # React组件
├── lib/ # 工具库
│ ├── template-validator.ts # 模板验证器
│ ├── field-pool.ts # 字段池管理
│ └── hooks/ # 自定义Hooks
├── prisma/ # 数据库
│ ├── schema.prisma # 数据模型
│ └── migrations/ # 迁移文件
├── scripts/ # 脚本工具
│ ├── migrate-template-data.ts # 数据迁移
│ └── verify-template-data.ts # 数据验证
├── docs/ # 文档
│ ├── api/ # API文档
│ ├── deployment/ # 部署文档
│ └── user-guide/ # 用户手册
└── tests/ # 测试文件
📚 文档
用户文档
开发文档
部署文档
🧪 测试
项目包含118个单元测试，覆盖核心功能：
- 模板验证器（25个测试）
- 字段池管理器（34个测试）
- 模板CRUD API（13个测试）
- 防抖Hooks（17个测试）
- UI组件（29个测试）
# 运行所有测试
npm test
# 查看覆盖率
npm run test:coverage
核心模块覆盖率：
- template-validator.ts: 92.62%
- useDebounce.ts: 100%
- upload-templates API: 85.88%
🔐 环境变量
必需变量
| 变量 | 说明 |
|---|---|
DATABASE_URL |
PostgreSQL连接字符串 |
NEXTAUTH_SECRET |
NextAuth加密密钥 |
NEXTAUTH_URL |
应用URL |
S3_ENDPOINT |
S3端点 |
S3_BUCKET |
S3桶名称 |
S3_ACCESS_KEY_ID |
S3访问密钥 |
S3_SECRET_ACCESS_KEY |
S3密钥 |
可选变量
| 变量 | 说明 |
|---|---|
GEMINI_API_KEY |
Gemini AI密钥 |
DINGTALK_CLIENT_ID |
钉钉客户端ID |
DINGTALK_CLIENT_SECRET |
钉钉客户端密钥 |
完整配置说明请参考 .env.example
🆘 故障排除
常见问题
Q: Docker构建失败？
A: 检查 .env.production 文件是否存在，或使用 -EnvFile 参数指定环境变量文件。
Q: 数据库连接失败？
A: 确认 DATABASE_URL 配置正确，数据库服务正在运行。
Q: S3上传失败？
A: 检查S3配置和网络连接，查看错误日志。
Q: 测试失败？
A: 运行 npm run prisma:generate 重新生成Prisma客户端。
更多问题请查看：
📈 性能指标
| 操作 | 目标时间 | 实际时间 |
|---|---|---|
| 模板列表加载 | < 500ms | ~300ms |
| 素材上传验证 | < 100ms | ~50ms |
| 字段池同步 | < 1s | ~500ms |
| 首页Tag响应 | < 100ms | ~50ms |
🤝 贡献
欢迎提交Issue和Pull Request！
📝 License
MIT
📞 联系方式
最后更新: 2025年12月13日
版本: 1.0.0