.
├── 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. 参考源码目录

当前实际存在的参考源码目录：

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 为主；NAS / Linux 现场优先用 scripts/customer-install.sh / scripts/smoke-install.sh 做检查和验收，Windows 实施机可用对应 .ps1 脚本。Agent 只在交付方案明确采用时启用。

6. 本地开发

安装依赖

npm install

配置环境变量

cp .env.example .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 中的项目配置一致。

付费模块采用“镜像站放模块核心本体，验证服务器发授权清单和实例凭证”的分工；部署 license-server 时还要确认 PREMIUM_MODULE_REGISTRY_BASE 和模块版本指向当前可用镜像站。

初始化 Prisma

npm run prisma:generate
npm run prisma:push

启动主应用

npm run dev

默认访问：

http://localhost:3000

7. 系统初始化

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

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

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. 常用命令

# 主应用
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. 部署入口

当前主应用生产编排：

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/customer-install.sh
scripts/smoke-install.sh
scripts/backup-restore.sh
scripts/customer-acceptance-smoke.mjs
scripts/customer-install.ps1
scripts/smoke-install.ps1
scripts/backup-restore.ps1
scripts/measure-image-size.ps1
deploy-new-fixed.ps1
发布管理.ps1
license-server/deploy.ps1

其中 scripts/customer-install.sh 是 NAS / Linux 客户首装分步骤入口，内部调用 scripts/smoke-install.sh 做预检、启动和验收；scripts/backup-restore.sh 用于 NAS / Linux 客户环境备份、恢复和恢复后验收；scripts/customer-acceptance-smoke.mjs 用于客户业务验收，可只读检查，也可用临时测试账号执行一次真实小素材上传；.ps1 版本用于 Windows 实施机或已安装 PowerShell 的现场；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

原则：

当前项目事实以当前代码、配置、部署文件和主入口文档为准。
阶段记录、旧排障报告、旧交接文档和历史总结不作为默认事实来源。
参考源码只用于查思路和做功能吸收判断，不直接参与当前项目运行链路。

Languages

TypeScript 87.3%

PowerShell 5.7%

JavaScript 3%

Go 2.2%

Shell 1.3%

Other 0.5%

README.md Unescape Escape

FLNXI 素材库

1. 项目定位

2. 仓库组成