# 妙境 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

当前项目为私有项目，未声明开源许可证。未经授权请勿公开分发、复制或商业使用。