WuYongJie/flnxi-Wu

Fork 0

WuYongJie d1c6efc79d

CI Check / check (push) Has been cancelled

Details

feat: NAS 部署与 Harbor 推送流程

2025-12-03 14:39:06 +08:00

12 KiB

Raw Blame History

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 或容器。

🚀 快速开始

安装依赖
```
npm install
```
复制环境模板并补齐配置
```
cp .env.example .env   # 若在 Windows，可手动复制
```
建议同步编辑 config-bianliang.env，以便后续迁移。

数据库初始化

npm run prisma:generate
npm run prisma:push          # 或 `npx prisma migrate deploy`

创建第一个账号
- 前台注册后，将该用户 role 更新为 ADMIN、isSuperAdmin = true。
- 或运行 node verify_first_user.js 检查首位用户权限是否正确。

可选自检

npm run check      # type-check + lint + prisma validate
npm run prisma:studio

启动开发服务
```
npm run dev
# http://localhost:3000
```

Docker 开发模式

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

12 KiB Raw Blame History Unescape Escape