218 lines
6.3 KiB
Markdown
218 lines
6.3 KiB
Markdown
# 由壹点3D素材
|
||
|
||
一个现代化的3D素材分享平台，采用苹果官方UI设计规范。
|
||
|
||
> ⚠️ 强烈建议：可迁移化部署时只需编辑根目录的 `config-bianliang.env`
|
||
>
|
||
> - 将你的域名、内网地址、图片域名白名单、CORS 白名单、钉钉回调、对象存储等统一填在该文件中
|
||
> - 系统启动会自动读取该文件：仅在变量“未设置”时注入，不会覆盖系统环境或 `.env/.env.local`
|
||
> - 修改后重启服务生效（重启 Node 或对应容器）
|
||
> - 前端可读变量以 `NEXT_PUBLIC_` 开头，服务端变量无需此前缀
|
||
|
||
## 🎯 项目目标
|
||
|
||
**让其他公司能够一键部署或一条命令从Docker部署到自己的NAS或服务器上**
|
||
|
||
### 核心设计原则
|
||
- **性能开销优先** - 最小化资源消耗，确保在低配置设备上也能稳定运行
|
||
- **稳定性优先** - 确保长期稳定运行，减少崩溃和错误
|
||
- **易于部署** - 零配置或最小配置即可运行
|
||
|
||
详细规范请参考：[架构设计与编码规范](./架构设计与编码规范.md)
|
||
|
||
## 一键式可迁移配置（推荐）
|
||
|
||
不想到处找变量？只需编辑根目录的 `config-bianliang.env`，填好注释中的值并重启服务即可。
|
||
系统在启动时会自动读取该文件，只有当某个变量"未设置"时才会注入，绝不会覆盖你在系统环境或 `.env/.env.local` 中已设置的值。
|
||
|
||
适合场景：不同公司、不同域名、NAS/内外网混合环境的快速切换与迁移。
|
||
|
||
**快速部署指南**：[一键部署快速指南](./一键部署快速指南.md)
|
||
|
||
包含的关键项（全部已带中文注释）：
|
||
- 站点/域名：`APP_PUBLIC_URL`, `NEXTAUTH_URL`, `PUBLIC_DOMAINS`, `NEXT_PUBLIC_PUBLIC_DOMAINS`, `NEXT_PUBLIC_PORTAL_BASE_URL`, `NEXT_PUBLIC_INTRANET_URL`
|
||
- 默认 LOGO：`NEXT_PUBLIC_DEFAULT_HEADER_LOGO_URL`, `NEXT_PUBLIC_DEFAULT_LOGIN_LOGO_URL`
|
||
- 钉钉回调：`NEXT_PUBLIC_DINGTALK_CALLBACK_URL`
|
||
- 图片域名白名单（Next/Image）：`IMAGE_REMOTE_HOSTS`
|
||
- CORS 白名单：`ALLOWED_ORIGINS`
|
||
- 数据恢复/对象存储：`RESTORE_S3_BUCKET_URL`, `RESTORE_S3_PUBLIC_URL`
|
||
|
||
提示：前端需要读取的变量以 `NEXT_PUBLIC_` 开头；服务端专用变量不需要此前缀。
|
||
|
||
## 技术栈
|
||
|
||
- **前端**: Next.js 14 + React 18 + TypeScript + TailwindCSS
|
||
- **认证**: NextAuth.js
|
||
- **数据库**: PostgreSQL + Prisma ORM
|
||
- **存储**: MinIO S3 (预览图) + 本地存储 (压缩包)
|
||
|
||
## 功能特性
|
||
|
||
- ✅ 用户注册/登录系统
|
||
- ✅ 素材上传（预览图 + 压缩包）
|
||
- ✅ 素材浏览与下载
|
||
- ✅ 管理员后台管理
|
||
- ✅ 用户管理
|
||
- ✅ 苹果风格UI设计
|
||
|
||
## 快速开始
|
||
|
||
### 1. 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
### 2. 配置环境变量
|
||
|
||
复制 `.env.example` 为 `.env` 并按需填写；部署时可结合 `config-bianliang.env` 管理差异化配置。
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
- 如需在同一存储桶隔离测试与生产数据，可以设置 `S3_ENV_PREFIX`（例如 `testing/`），系统会自动在上传路径前添加该命名空间。
|
||
|
||
### 3. 初始化数据库
|
||
|
||
```bash
|
||
# 生成 Prisma Client
|
||
npm run prisma:generate
|
||
|
||
# 推送数据库模式
|
||
npm run prisma:push
|
||
```
|
||
|
||
### 4. 创建管理员账号
|
||
|
||
首次运行后，注册一个账号，然后在数据库中手动将该用户的 `role` 字段设置为 `ADMIN`。
|
||
|
||
```sql
|
||
UPDATE users SET role = 'ADMIN' WHERE email = 'your@email.com';
|
||
```
|
||
|
||
### 4. 快速自检（可选）
|
||
|
||
```bash
|
||
npm run check
|
||
```
|
||
|
||
### 5. 启动开发服务器（Node 环境）
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
访问 http://localhost:3000
|
||
|
||
## 🚀 部署到服务器
|
||
|
||
### 安全部署流程
|
||
|
||
**重要：** 使用安全部署工具，确保不影响正式服务器的正常使用。
|
||
|
||
> 可移植生产部署请优先参考：
|
||
> - [可移植部署与生产规范（权威版）](./docs/PORTABLE_DEPLOYMENT_GUIDE.md)
|
||
|
||
**快速部署：**
|
||
|
||
1. **本地测试**
|
||
```bash
|
||
npm run dev
|
||
# 测试所有功能正常
|
||
```
|
||
|
||
2. **部署前检查**
|
||
```bash
|
||
# Windows
|
||
.\部署前检查清单.bat
|
||
```
|
||
|
||
3. **执行部署**
|
||
```bash
|
||
# Windows PowerShell
|
||
.\scripts\deploy\安全部署.ps1
|
||
|
||
# Linux/Mac
|
||
bash scripts/deploy/安全部署.sh
|
||
```
|
||
|
||
**详细部署指南：**
|
||
- [安全部署流程](./docs/guides/安全部署流程.md)
|
||
- [安全部署说明](./docs/guides/安全部署说明.md)
|
||
- [安全部署指南](./docs/guides/安全部署指南.md)
|
||
|
||
**部署检查清单：**
|
||
- [部署前检查清单](./部署前检查清单.bat)
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
gongxiangp2/
|
||
├── app/ # Next.js App Router
|
||
│ ├── api/ # API 路由
|
||
│ │ ├── auth/ # 认证相关
|
||
│ │ ├── materials/ # 素材相关
|
||
│ │ └── admin/ # 管理员相关
|
||
│ ├── login/ # 登录页面
|
||
│ ├── register/ # 注册页面
|
||
│ ├── admin/ # 管理员页面
|
||
│ └── page.tsx # 首页
|
||
├── components/ # React 组件
|
||
│ ├── Header.tsx
|
||
│ └── UploadModal.tsx
|
||
├── lib/ # 工具库
|
||
│ ├── prisma.ts # Prisma 客户端
|
||
│ ├── auth.ts # NextAuth 配置
|
||
│ └── s3.ts # S3 存储服务
|
||
├── prisma/ # Prisma 配置
|
||
│ └── schema.prisma # 数据库模式
|
||
└── uploads/ # 本地上传文件存储
|
||
```
|
||
|
||
## 数据库模型
|
||
|
||
### User (用户)
|
||
- id: UUID
|
||
- email: 邮箱
|
||
- username: 用户名
|
||
- password: 密码 (加密)
|
||
- role: 角色 (USER/ADMIN)
|
||
|
||
### Material (素材)
|
||
- id: UUID
|
||
- previewUrl: 预览图URL (S3)
|
||
- productModel: 商品型号
|
||
- sceneName: 场景名称
|
||
- authorName: 作者花名
|
||
- zipFileName: 压缩包文件名
|
||
- zipFilePath: 压缩包本地路径
|
||
- userId: 用户ID (外键)
|
||
|
||
## 部署
|
||
|
||
### 开发环境（Docker）
|
||
|
||
```bash
|
||
docker compose -f docker-compose.dev.yml up --build
|
||
```
|
||
|
||
### 生产环境构建
|
||
|
||
```bash
|
||
docker compose build
|
||
docker compose up -d
|
||
```
|
||
|
||
### 环境变量
|
||
|
||
确保在生产环境中设置所有必要的环境变量，特别是：
|
||
- `NEXTAUTH_SECRET`: 使用强随机字符串
|
||
- `NEXTAUTH_URL`: 设置为生产域名
|
||
- `APP_PUBLIC_URL`：可选，按公司部署时的对外访问地址（如 `https://corp.example.com`）。若不设置，系统会自动从请求头推断；该变量优先用于生成邀请链接等需要完整站点URL的功能。
|
||
|
||
## License
|
||
|
||
MIT
|
||
|