241 lines
7.8 KiB
Markdown
241 lines
7.8 KiB
Markdown
# FLNXI 素材库
|
||
|
||
本仓库是 `FLNXI 素材库` 的当前主项目，不是旧版素材站，也不是单独的模板系统示例。项目目标是面向企业/团队做私有化交付，默认部署在 NAS 或 Linux 服务器上，通过浏览器给普通用户使用。
|
||
|
||
## 1. 项目定位
|
||
|
||
当前项目核心目标：
|
||
|
||
- 素材上传、检索、预览、下载、分享
|
||
- 模板化元数据和动态筛选
|
||
- 用户、部门、邀请和后台管理
|
||
- 许可证激活、校验、免费版 / 付费版限制
|
||
- 系统初始化、外观设置、对象存储配置
|
||
- Docker / NAS / Linux 私有化交付
|
||
|
||
一句话：这是一个可安装、可授权、可交付、可维护的私有化素材管理产品。
|
||
|
||
## 2. 仓库组成
|
||
|
||
```text
|
||
.
|
||
├── app/ # 主应用页面和 API（Next.js App Router）
|
||
├── components/ # 主应用 React 组件
|
||
├── hooks/ # 主应用前端 Hook
|
||
├── lib/ # 主应用核心逻辑、授权、S3、认证、模板等
|
||
├── prisma/ # 主应用 Prisma schema 与 seed
|
||
├── public/ # 主应用静态资源
|
||
├── scripts/ # 构建、迁移、修复、部署辅助脚本
|
||
├── docs/ # 当前项目文档入口
|
||
├── license-server/ # 独立许可证服务
|
||
├── flnxi-agent/ # Node 版安装与运维 Agent
|
||
└── flnxi-agent-go/ # Go 版安装与运维 Agent
|
||
```
|
||
|
||
当前主应用是核心产品；`license-server/` 和两个 Agent 是私有化交付链路的一部分，不属于普通用户日常使用入口。
|
||
|
||
## 3. 当前主应用能力
|
||
|
||
已在当前项目中存在的能力：
|
||
|
||
- 素材上传、搜索、预览、下载、分享、收藏、点赞
|
||
- 上传模板、字段配置、字段池、首页动态筛选
|
||
- 用户注册、登录、个人资料、个人素材、浏览历史
|
||
- 部门、邀请、角色、管理员后台
|
||
- 授权激活、许可证校验、心跳、免费版限制
|
||
- 系统初始化、系统设置、Logo / 外观设置、完整性检查
|
||
- 图片、PSD、音频、视频相关处理能力
|
||
- 钉钉登录、AI 聊天 / AI 编辑相关接口
|
||
|
||
注意：钉钉、AI、许可证服务等能力依赖环境变量和外部服务配置；代码存在不等于部署后默认可用。
|
||
|
||
## 4. 参考源码目录
|
||
|
||
当前实际存在的参考源码目录：
|
||
|
||
```text
|
||
gongxiangp2-source-reference-old-style-20260513-132942/
|
||
```
|
||
|
||
它是其他版本素材库源码，只用于查实现和做功能对比，不属于当前主项目，不参与构建、测试和提交。
|
||
|
||
历史上出现过的参考目录名也保留在排除配置中，避免后续重新放回时被工具链误扫：
|
||
|
||
- `gongxiangp2-source-reference-20260309-202917/`
|
||
- `gongxiangp2-source-reference-20260413-172354/`
|
||
- `gongxiangp2-source-reference-old-style-20260513-132942/`
|
||
|
||
参考源码的当前功能吸收结论见：
|
||
|
||
- `docs/参考源码功能吸收整理_20260513.md`
|
||
|
||
## 5. 技术栈
|
||
|
||
主应用：
|
||
|
||
- Next.js 14
|
||
- React 18
|
||
- TypeScript
|
||
- Prisma 5
|
||
- PostgreSQL
|
||
- MinIO / S3 兼容对象存储
|
||
- NextAuth
|
||
- Tailwind CSS
|
||
- Jest + React Testing Library
|
||
|
||
许可证服务：
|
||
|
||
- Next.js 14
|
||
- Prisma
|
||
- PostgreSQL
|
||
|
||
安装 Agent：
|
||
|
||
- `flnxi-agent/`：Node.js / Express / Socket.IO
|
||
- `flnxi-agent-go/`：Go / Gin / Docker SDK
|
||
|
||
Agent 是实施和运维编排工具，不是普通客户日常入口，也不是当前唯一正式安装器。正式客户首装仍以 `docker-compose.prod.yml + .env + scripts/smoke-install.ps1` 为主，Agent 只在交付方案明确采用时启用。
|
||
|
||
## 6. 本地开发
|
||
|
||
### 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
### 配置环境变量
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
至少需要确认。下面只表示变量形状，不要把示例占位值用于客户环境：
|
||
|
||
```env
|
||
NEXTAUTH_SECRET=<generate-a-strong-random-secret>
|
||
APP_PUBLIC_URL=http://localhost:3000
|
||
NEXTAUTH_URL=http://localhost:3000
|
||
S3_ENDPOINT=http://localhost:9000
|
||
S3_BUCKET=flnxi-materials
|
||
S3_ACCESS_KEY_ID=<object-storage-access-key>
|
||
S3_SECRET_ACCESS_KEY=<object-storage-secret-key>
|
||
LICENSE_SERVER_URL=https://your-license-server.example.com
|
||
LICENSE_PROJECT_CODE=flnxi-sucai
|
||
LICENSE_REQUEST_SIGNING_SECRET=<same-secret-as-license-server>
|
||
LICENSE_PUBLIC_KEY=<license-server-rsa-public-key>
|
||
LOCAL_ENCRYPTION_KEY=<generate-a-32-char-or-longer-local-key>
|
||
```
|
||
|
||
内置 PostgreSQL 部署时 `DATABASE_URL` 留空，由 Compose 自动指向内置数据库；只有外部 PostgreSQL 才填写真实连接串。`LICENSE_PROJECT_CODE` 和 `LICENSE_REQUEST_SIGNING_SECRET` 必须和 `license-server` 中的项目配置一致。
|
||
|
||
### 初始化 Prisma
|
||
|
||
```bash
|
||
npm run prisma:generate
|
||
npm run prisma:push
|
||
```
|
||
|
||
### 启动主应用
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
默认访问：
|
||
|
||
```text
|
||
http://localhost:3000
|
||
```
|
||
|
||
## 7. 系统初始化
|
||
|
||
常规激活流程会自动完成系统初始化。
|
||
|
||
如果是在尚未有管理员账号的环境里手动初始化，需要先配置 `SYSTEM_INIT_TOKEN`，再调用：
|
||
|
||
```bash
|
||
curl -X POST http://localhost:3000/api/system/init \
|
||
-H "x-system-init-token: your-init-token"
|
||
```
|
||
|
||
如果没有提供 `INIT_ADMIN_PASSWORD`，系统会生成一次性初始密码，并且首次登录后强制修改。项目不再内置固定的 `admin@flnxi.com / 88888888`。
|
||
|
||
## 8. 常用命令
|
||
|
||
```bash
|
||
# 主应用
|
||
npm run dev
|
||
npm run build
|
||
npm start
|
||
npm run lint
|
||
npm run type-check
|
||
npm test
|
||
|
||
# Prisma
|
||
npm run prisma:generate
|
||
npm run prisma:push
|
||
npm run prisma:validate
|
||
npm run prisma:studio
|
||
|
||
# 模板数据迁移 / 校验
|
||
npm run migrate:template-data
|
||
npm run verify:template-data
|
||
```
|
||
|
||
## 9. 部署入口
|
||
|
||
当前主应用生产编排：
|
||
|
||
```bash
|
||
docker compose -f docker-compose.prod.yml up -d
|
||
```
|
||
|
||
`docker-compose.prod.yml` 当前会拉起：
|
||
|
||
- PostgreSQL
|
||
- MinIO
|
||
- MinIO 初始化容器
|
||
- 主应用容器
|
||
|
||
主应用镜像通过当前 Registry 发布流程生成和推送，镜像名、容器名、卷名、网络名和端口可通过 `.env` 覆盖，例如 `APP_IMAGE`、`APP_PORT`、`APP_CONTAINER_NAME`。
|
||
|
||
它不会直接拉起 Nginx / Traefik、独立许可证服务或 Agent。不同 NAS / Linux 现场的反向代理、域名、证书、许可证服务地址，需要按部署文档和实际环境配置。
|
||
|
||
内部维护环境仍保留：
|
||
|
||
- `deploy-registry.ps1`
|
||
- `scripts/smoke-install.ps1`
|
||
- `scripts/backup-restore.ps1`
|
||
- `scripts/measure-image-size.ps1`
|
||
- `deploy-new-fixed.ps1`
|
||
- `发布管理.ps1`
|
||
- `license-server/deploy.ps1`
|
||
|
||
其中 `scripts/smoke-install.ps1` 用于首装后的基础验收，`scripts/backup-restore.ps1` 用于客户环境备份、恢复和恢复后验收，`scripts/measure-image-size.ps1` 用于发布前记录镜像体积和分层。其它脚本执行前必须先读内容和参数，不应把内部固定服务器或固定镜像仓库当成客户默认交付配置。客户交付时要显式写入版本化 `APP_IMAGE` / `IMAGE_TAG`，`latest` 只保留给内部测试或兼容场景。当前新 Registry 发布脚本是主线，旧远程部署脚本只作历史或内部维护参考。AI、钉钉、内网穿透等可选能力依赖真实外部服务和密钥，不能只凭页面入口当成客户验收已完成。
|
||
|
||
## 10. 文档入口
|
||
|
||
主入口优先看：
|
||
|
||
- `docs/README.md`
|
||
- `docs/deployment/部署说明.md`
|
||
- `docs/deployment/多品牌 NAS 与 Linux 交付差异清单.md`
|
||
- `docs/初次部署与出厂设置指南.md`
|
||
- `docs/许可证服务接入说明.md`
|
||
- `docs/参考源码功能吸收整理_20260513.md`
|
||
- `scripts/README.md`
|
||
|
||
需要追排障、历史收口或版本差异时，再看：
|
||
|
||
- `docs/客户首装升级坑位排查_20260530.md`
|
||
- `docs/商业化地基8项收口记录_20260530.md`
|
||
- `docs/商业化地基排查问题清单_20260524.md`
|
||
- `docs/许可证链路安全评估_20260312.md`
|
||
|
||
原则：
|
||
|
||
- 当前项目事实以当前代码、配置、部署文件和主入口文档为准。
|
||
- 阶段记录、旧排障报告、旧交接文档和历史总结不作为默认事实来源。
|
||
- 参考源码只用于查思路和做功能吸收判断，不直接参与当前项目运行链路。
|