WuYongJie/flnxi-Wu
WuYongJie/flnxi-Wu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
flnxi-Wu/README.md
WuYongJie 80ad51e3dd 调整付费模块镜像站分发链路
2026-06-01 14:21:32 +08:00

8.2 KiB
Raw Blame History

FLNXI 素材库

本仓库是 FLNXI 素材库 的当前主项目，不是旧版素材站，也不是单独的模板系统示例。项目目标是面向企业/团队做私有化交付，默认部署在 NAS 或 Linux 服务器上，通过浏览器给普通用户使用。

1. 项目定位

当前项目核心目标：

  • 素材上传、检索、预览、下载、分享
  • 模板化元数据和动态筛选
  • 用户、部门、邀请和后台管理
  • 许可证激活、校验、免费版 / 付费版限制
  • 系统初始化、外观设置、对象存储配置
  • Docker / NAS / Linux 私有化交付

一句话：这是一个可安装、可授权、可交付、可维护的私有化素材管理产品。

2. 仓库组成

.
├── 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 + scripts/smoke-install.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.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.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

原则：

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