Files
miaojingAI/README.md
2026-05-09 16:45:30 +08:00

614 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 妙境 AI 创作平台
妙境是一个面向个人创作者、内容团队和私有化部署场景的 AI 多模态创作平台。平台围绕“文生图、图生图、文生视频、图生视频、图片反推提示词”构建完整创作链路,提供用户体系、积分/会员、订单支付、作品历史、公开画廊、模型供应商管理、系统配置、数据备份和在线升级能力。
项目基于 Next.js App Router、React、PostgreSQL、本地文件存储和 PM2 运行,支持本地 PostgreSQL 部署,也兼容 Supabase 作为数据库/认证底座。AI 生成能力既支持系统默认供应商,也支持用户自定义 OpenAI/New API 兼容接口。
## 项目截图
以下截图来自开发服务器的真实页面,用于快速了解平台界面和核心工作流。
### 首页
![妙境首页](docs/images/home.png)
### 创作中心
![创作中心](docs/images/create.png)
### 作品画廊
![作品画廊](docs/images/gallery.png)
## 核心能力
### 创作能力
- 文生图:根据文本提示词生成图片,支持尺寸、比例、模型和提示词参数。
- 图生图:上传参考图后进行风格迁移、场景变换、细节重绘和创意延展。
- 文生视频:根据文字描述生成动态视频内容。
- 图生视频:基于静态图片生成动态视频。
- 图片反推提示词:从图片中提取提示词,支持普通提示词、复刻级像素提示词、像素级图生图、像素级文生图等模式。
- 生成任务队列:生成任务写入 `generation_jobs`,前端可轮询任务状态并从历史记录中查看结果。
- 作品管理:保存创作历史、生成参数、结果链接、尺寸、时长、消耗积分等信息。
- 画廊发布:用户可将作品公开到画廊,支持点赞、复制提示词、全屏预览和下载。
### 管理后台
管理后台入口为 `/console`,管理员登录后可进入仪表盘和各类管理模块。
- 仪表盘:统计用户、作品、任务、订单、供应商、公告、日志和系统健康状态。
- API 管理:配置系统供应商、模型推荐、系统 API、New API/OpenAI 兼容站点。
- 用户管理:管理用户资料、角色、会员、积分、账号状态。
- 价格设置:维护会员套餐、积分规则和付费能力。
- 订单管理:查看订单、支付状态和收入统计。
- 支付配置配置微信、支付宝、Stripe 等支付方式的展示和密钥。
- 公告管理:创建站点公告、弹窗公告、有效期和展示策略。
- 数据管理:导出/导入业务数据,适合迁移和人工备份。
- 系统升级:支持热更新和冷更新,自动备份、失败回滚、中文日志和历史记录。
- 系统日志:查看登录、安全、运行、管理操作等平台日志。
- 系统设置维护站点名称、Logo、页脚、邮箱、通知和站点政策内容。
### 运维能力
- 一键部署/升级脚本:`scripts/deploy-or-upgrade.sh`
- 构建脚本:`scripts/build.sh`
- 数据备份:`scripts/backup-create.sh`
- 数据恢复:`scripts/backup-restore.sh`
- 备份列表:`scripts/backup-list.sh`
- 数据库初始化:`scripts/init-database.sql`
- 数据库补丁:`scripts/apply-database-patch.sh`
- 管理后台在线升级 runner`scripts/admin-upgrade-runner.mjs`
- PM2 运行配置:`ecosystem.config.cjs`
## 技术栈
| 层级 | 技术 |
| --- | --- |
| 前端框架 | Next.js 16 App Router、React 19、TypeScript |
| UI 组件 | Radix UI、Tailwind CSS、lucide-react、sonner |
| 服务端 | Next.js Route Handlers、自定义 Node HTTP server、tsup |
| 数据库 | PostgreSQL 14+,可接 Supabase |
| 存储 | 本地文件存储,生产推荐 `LOCAL_STORAGE_DIR=/var/lib/miaojingAI/storage` |
| 认证 | 本地 auth schema + session/JWT兼容 Supabase 风格表结构 |
| AI 调用 | coze-coding-dev-sdk、用户自定义 API、系统 API、New API/OpenAI compatible |
| 进程管理 | PM2 |
| 构建工具 | pnpm、Turbopack、tsup、TypeScript |
## 系统架构
```text
┌─────────────────────────────────────────────────────────────┐
│ Browser │
│ 首页 / 创作中心 / 画廊 / 个人中心 / 管理后台 Console │
└──────────────────────────────┬──────────────────────────────┘
│ HTTP
┌──────────────────────────────▼──────────────────────────────┐
│ Next.js App Router │
│ app pages + route handlers + middleware + server components │
└───────────────┬──────────────────────┬──────────────────────┘
│ │
┌───────────────▼──────────────┐ │
│ API Route 层 │ │
│ /api/generate/image │ │
│ /api/generate/video │ │
│ /api/generation-jobs │ │
│ /api/admin/* │ │
│ /api/local-storage/* │ │
└───────────────┬──────────────┘ │
│ │
┌───────────────▼──────────────┐ │
│ 业务服务层 │ │
│ auth / model config / jobs │ │
│ credits / orders / storage │ │
│ platform logs / upgrade │ │
└───────┬──────────────┬───────┘ │
│ │ │
┌───────▼──────┐ ┌─────▼────────┐ ┌────▼──────────────────┐
│ PostgreSQL │ │ 本地文件存储 │ │ 上游 AI / New API 站点 │
│ profiles │ │ images/videos│ │ OpenAI compatible │
│ works │ │ avatars │ │ image/video providers │
│ jobs/orders │ │ backups │ │ │
└──────────────┘ └──────────────┘ └───────────────────────┘
```
## 目录结构
```text
.
├── assets/ # 项目内置图片资源
├── docs/images/ # README 使用的项目截图
├── public/ # favicon、logo、公开静态文件
├── scripts/
│ ├── admin-upgrade-runner.mjs # 管理后台热/冷更新执行器
│ ├── apply-database-patch.sh # 执行数据库补丁
│ ├── backup-create.sh # 创建数据库/存储/.env 备份
│ ├── backup-list.sh # 查看备份列表
│ ├── backup-restore.sh # 恢复备份
│ ├── build.sh # Next.js + server 构建
│ ├── deploy-or-upgrade.sh # 一键部署/升级
│ ├── dev.sh # 本地开发启动脚本
│ ├── init-database.sql # PostgreSQL 初始化脚本
│ └── start.sh # 生产启动脚本
├── src/
│ ├── app/ # Next.js App Router 页面与 API
│ ├── components/ # 页面组件、创作组件、管理后台组件、UI 组件
│ ├── hooks/ # 前端 hooks
│ ├── lib/ # 业务逻辑、认证、模型、存储、日志、支付等
│ ├── modules/ # api / console / web 模块入口
│ ├── server.ts # 自定义 Node HTTP server 入口
│ └── storage/ # 数据库客户端和存储适配
├── .env.example # 环境变量模板
├── ecosystem.config.cjs # PM2 配置
├── package.json
└── README.md
```
## 环境要求
### 基础环境
- Linux 服务器,推荐 Ubuntu 22.04+ / Debian 12+
- Node.js 22 或 24部署脚本默认安装/使用 Node.js 24 LTS
- pnpm 9+
- PostgreSQL 14+
- PM2
- curl、tar、rsync
- PostgreSQL 客户端工具:`psql``pg_dump``pg_restore`
### 推荐生产目录
```text
/opt/miaojingAI # 项目代码目录
/var/lib/miaojingAI/storage # 上传文件、生成结果、本地存储
/var/lib/miaojingAI/backups # 数据备份
/var/lib/miaojingAI/upgrade # 管理后台升级状态和升级包
/var/lib/miaojingAI/logs # 部署日志
```
## 环境变量
复制模板:
```bash
cp .env.example .env.local
```
常用变量:
| 变量 | 说明 |
| --- | --- |
| `LOCAL_DB_URL` | PostgreSQL 连接地址,例如 `postgresql://postgres:postgres@localhost:5432/miaojing` |
| `LOCAL_DB_ANON_KEY` | 本地模式 anon key可自定义 |
| `LOCAL_DB_SERVICE_ROLE_KEY` | 本地模式 service role key可自定义 |
| `DATA_ENCRYPTION_KEY` | 生产环境必填,用于加密 API Key 等敏感数据 |
| `JWT_SECRET` | 生产环境必填,用于会话/JWT 签名 |
| `GENERATION_INTERNAL_SECRET` | 生成任务内部密钥 |
| `LOCAL_STORAGE_DIR` | 本地文件存储路径 |
| `BACKUP_DIR` | 备份目录 |
| `DEPLOY_RUN_PORT` | 当前运行角色监听端口 |
| `MIAOJING_API_PORT` | 后端 API 内部端口 |
| `MIAOJING_CONSOLE_PORT` | 管理后台内部端口 |
| `NEXT_PUBLIC_APP_URL` | 前端公开访问地址 |
| `APP_BASE_URL` | 服务端使用的站点地址 |
| `ADMIN_INVITE_CODE` | 管理员邀请码 |
| `ENABLE_DANGER_ADMIN_CLEAR_USERS` | 危险清理功能开关,生产环境应保持 `false` |
| `UPGRADE_STATE_DIR` | 管理后台升级状态目录,默认基于存储目录推导 |
| `UPGRADE_HEALTH_URL` | 冷更新重启后的健康检查 URL |
| `UPGRADE_RESTART_COMMAND` | 冷更新使用的重启命令 |
生成生产密钥示例:
```bash
openssl rand -hex 32
```
## 本地开发
### 1. 安装依赖
```bash
corepack enable
corepack pnpm install --frozen-lockfile
```
### 2. 初始化数据库
创建数据库:
```bash
createdb miaojing
```
执行初始化脚本:
```bash
psql "postgresql://postgres:postgres@localhost:5432/miaojing" -f scripts/init-database.sql
```
### 3. 配置环境变量
```bash
cp .env.example .env.local
```
至少填写:
```env
LOCAL_DB_URL=postgresql://postgres:postgres@localhost:5432/miaojing
LOCAL_DB_ANON_KEY=local-anon-key
LOCAL_DB_SERVICE_ROLE_KEY=local-service-role-key
LOCAL_STORAGE_DIR=./local-storage
DATA_ENCRYPTION_KEY=替换为 openssl rand -hex 32 的结果
JWT_SECRET=替换为 openssl rand -hex 32 的结果
GENERATION_INTERNAL_SECRET=替换为 openssl rand -hex 32 的结果
```
### 4. 启动开发服务
```bash
corepack pnpm run dev
```
默认开发端口由 `scripts/dev.sh` 控制,可传入端口:
```bash
corepack pnpm run dev -- 5000
```
### 5. 常用开发命令
```bash
# TypeScript 检查
corepack pnpm run ts-check
# ESLint
corepack pnpm run lint
# 完整构建
corepack pnpm run build
# 边界检查
corepack pnpm run check:boundaries
```
## 生产部署
### 方式一:一键部署/升级脚本
推荐使用:
```bash
bash scripts/deploy-or-upgrade.sh
```
脚本会提示填写:
- 项目部署目录
- 数据存储目录
- 前端访问端口
- 后端 API 内部端口
- 管理后台内部端口
- 管理员账号/邮箱/密码
- PostgreSQL 连接地址
- 正式访问地址
首次部署时,脚本会:
1. 检查 tar、rsync、curl、psql、pg_dump 等依赖。
2. 自动安装或切换 Node.js 22/24。
3. 安装 pnpm 和 PM2。
4. 准备 `.env.local`
5. 初始化或检查数据库。
6. 构建 Next.js 和 Node server。
7. 写入 PM2 配置并启动服务。
8. 执行健康检查。
升级已有部署时,脚本会:
1. 检测已有部署目录。
2. 创建升级前备份。
3. 同步新代码。
4. 构建并重启服务。
5. 执行健康检查。
6. 失败时输出备份路径,方便手动恢复。
### 方式二:手动部署
安装依赖:
```bash
corepack enable
corepack pnpm install --frozen-lockfile --prod=false
```
构建:
```bash
corepack pnpm run build
```
启动 PM2
```bash
pm2 startOrReload ecosystem.config.cjs --update-env
pm2 save
```
健康检查:
```bash
curl http://127.0.0.1:5100/api/health
```
### PM2 服务说明
`ecosystem.config.cjs` 默认包含三个角色:
| PM2 名称 | 角色 | 默认端口 |
| --- | --- | --- |
| `miaojing-api` | 后端 API | `5100` |
| `miaojing-web` | 前端站点 | `5000` |
| `miaojing-console` | 管理后台 | `5200` |
在单进程开发部署中,也可以使用类似 `miaojing-dev` 的 PM2 进程直接运行完整服务。
## 数据库说明
数据库初始化脚本为:
```bash
scripts/init-database.sql
```
核心表包括:
| 表 | 说明 |
| --- | --- |
| `auth.users` | 本地认证用户 |
| `profiles` | 用户资料、角色、会员、积分 |
| `works` | 创作作品、提示词、结果 URL、尺寸、状态 |
| `generation_jobs` | 生成任务队列和进度 |
| `credit_transactions` | 积分流水 |
| `orders` | 订单和支付状态 |
| `user_api_keys` | 用户自定义 API 密钥 |
| `system_api_configs` | 系统默认 API 配置 |
| `api_providers` | 模型供应商 |
| `model_recommendations` | 模型推荐配置 |
| `announcements` | 公告 |
| `site_config` | 站点配置 |
| `platform_logs` | 平台日志 |
执行数据库补丁:
```bash
corepack pnpm run db:patch
```
## 备份与恢复
### 创建备份
```bash
corepack pnpm run backup:create
```
备份包包含:
- PostgreSQL dump`database.dump`
- 本地存储目录:`local-storage`
- 环境变量:`.env.local`
- `package.json`
- 备份 manifest
默认只保留最近 10 个备份。
### 查看备份
```bash
corepack pnpm run backup:list
```
### 恢复备份
```bash
corepack pnpm run backup:restore /path/to/miaojing-backup-YYYYMMDD-HHMMSS.tar.gz
```
恢复动作会:
1. 使用 `pg_restore --clean --if-exists --no-owner` 恢复数据库。
2. 替换本地存储目录。
3. 恢复 `.env.local`
生产环境恢复前建议先停服务,并额外复制当前数据目录。
## 管理后台在线升级
管理后台“系统升级”提供两类升级能力:
### 热更新
用于不影响运行时代码的小补丁,例如 `public/` 下的静态资源。
特点:
- 不重启平台。
- 升级前自动创建数据库/存储/环境备份。
- 升级前自动创建源码快照。
- 失败自动回滚。
- 升级界面实时显示中文日志。
### 冷更新
用于涉及源码、脚本、依赖、配置的大变更。
冷更新流程:
1. 上传升级包。
2. 校验升级包路径,拒绝 `.env``.git``node_modules``backups``local-storage` 等危险路径。
3. 创建数据库、存储、环境配置备份。
4. 创建源码快照。
5. 应用升级包文件。
6. 如依赖变化,执行 `pnpm install --frozen-lockfile --prod=false`
7. 执行 `pnpm run ts-check`
8. 执行 `pnpm run build`
9. 重启平台。
10. 调用 `/api/health` 做健康检查。
11. 失败时自动恢复源码和数据。
升级日志会写入磁盘状态文件。即使冷更新过程中平台重启,管理后台恢复后也能续上日志和状态。升级完成后,当前页面刷新或切换页面会默认收起实时日志,但历史升级记录中可随时查看完整升级内容和日志。
升级包格式:
```text
.tar
.tar.gz
.tgz
```
推荐升级包结构:
```text
upgrade-package/
├── manifest.json
├── src/...
├── public/...
├── scripts/...
├── package.json
└── pnpm-lock.yaml
```
手动运行升级 runner 示例:
```bash
UPGRADE_STATE_DIR=/var/lib/miaojingAI/upgrade \
corepack pnpm run upgrade:run -- \
--job-id manual-001 \
--mode cold \
--package /tmp/upgrade.tgz \
--package-name upgrade.tgz \
--project /opt/miaojingAI
```
## AI 模型与供应商
妙境支持多来源模型配置:
- 系统默认供应商。
- 用户自定义 API Key。
- New API / OpenAI-compatible API 站点。
- 图片模型、视频模型、文本模型分类型管理。
管理员可在管理后台配置供应商、默认模型、API 地址、模型推荐和启用状态。用户可在前端绑定自己的 API Key平台会使用加密存储和尾号预览保护密钥。
## 存储与下载
生成结果会持久化到本地存储目录或配置的存储服务。推荐生产环境把存储放在项目目录之外:
```env
LOCAL_STORAGE_DIR=/var/lib/miaojingAI/storage
```
下载链路通过 `/api/download` 或本地存储路由读取原始文件,不应对图片进行二次压缩。作品历史、生成结果、画廊、全屏预览和下载应始终使用原始结果链接或持久化文件路径。
## 健康检查与运维命令
健康检查:
```bash
curl http://127.0.0.1:5100/api/health
```
查看 PM2
```bash
pm2 list
pm2 logs miaojing-api --lines 100
pm2 logs miaojing-web --lines 100
pm2 logs miaojing-console --lines 100
```
重启服务:
```bash
corepack pnpm run pm2:restart
```
保存 PM2 开机配置:
```bash
corepack pnpm run pm2:save
```
## 安全建议
- 生产环境必须设置高强度 `DATA_ENCRYPTION_KEY``JWT_SECRET``GENERATION_INTERNAL_SECRET`
- `.env.local` 不应提交到 git。
- 生产环境不要开启 `ENABLE_DANGER_ADMIN_CLEAR_USERS`
- `LOCAL_STORAGE_DIR``BACKUP_DIR``UPGRADE_STATE_DIR` 建议放在项目目录外。
- 升级包不要包含 `.env`、数据库 dump、用户上传文件或备份目录。
- 对外暴露时建议在 Nginx/Caddy 后面启用 HTTPS。
- 管理后台账号应使用强密码,并限制管理员数量。
- 定期执行 `backup:create` 并把备份复制到异地。
## 常见问题
### 1. 构建时提示缺少 devDependencies
构建需要 devDependencies。部署或 CI 中不要只安装生产依赖,推荐:
```bash
corepack pnpm install --frozen-lockfile --prod=false
```
### 2. 管理后台修改后刷新丢失
优先检查对应接口是否成功写入数据库,再检查 `.env.local` 是否连接到了正确数据库。不要只看前端本地状态。
### 3. 图片下载尺寸不符合预期
排查顺序:
1. 检查上游请求参数是否为目标分辨率。
2. 检查生成任务结果中保存的原始文件尺寸。
3. 检查 `/api/download` 是否直接返回原始文件。
4. 检查前端是否使用缩略图地址下载。
### 4. 冷更新后页面仍是旧版本
检查:
```bash
pm2 list
pm2 describe miaojing-api
pm2 describe miaojing-web
pm2 describe miaojing-console
```
确认 PM2 的 `cwd` 是当前部署目录,并确认构建产物来自同一目录。
### 5. 数据恢复后作品图片丢失
确认备份包内是否包含 `local-storage`,并确认 `.env.local` 中的 `LOCAL_STORAGE_DIR` 指向恢复后的存储目录。
## 版本管理
推荐使用 `main` 作为稳定分支:
```bash
git clone http://172.16.10.127:3000/fenglee/miaojingAI.git
git checkout main
```
提交前建议执行:
```bash
corepack pnpm run ts-check
corepack pnpm run build
```
## License
当前项目为私有项目,未声明开源许可证。未经授权请勿公开分发、复制或商业使用。