fenglee/miaojingAI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
miaojingAI/README.md
fenglee 1a0607fe8d docs: add detailed project readme
2026-05-09 16:45:30 +08:00

19 KiB
Raw Permalink Blame History

妙境 AI 创作平台

妙境是一个面向个人创作者、内容团队和私有化部署场景的 AI 多模态创作平台。平台围绕“文生图、图生图、文生视频、图生视频、图片反推提示词”构建完整创作链路，提供用户体系、积分/会员、订单支付、作品历史、公开画廊、模型供应商管理、系统配置、数据备份和在线升级能力。

项目基于 Next.js App Router、React、PostgreSQL、本地文件存储和 PM2 运行，支持本地 PostgreSQL 部署，也兼容 Supabase 作为数据库/认证底座。AI 生成能力既支持系统默认供应商，也支持用户自定义 OpenAI/New API 兼容接口。

项目截图

以下截图来自开发服务器的真实页面，用于快速了解平台界面和核心工作流。

首页

妙境首页

创作中心

创作中心

作品画廊

作品画廊

核心能力

创作能力

  • 文生图：根据文本提示词生成图片，支持尺寸、比例、模型和提示词参数。
  • 图生图：上传参考图后进行风格迁移、场景变换、细节重绘和创意延展。
  • 文生视频：根据文字描述生成动态视频内容。
  • 图生视频：基于静态图片生成动态视频。
  • 图片反推提示词：从图片中提取提示词，支持普通提示词、复刻级像素提示词、像素级图生图、像素级文生图等模式。
  • 生成任务队列：生成任务写入 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

系统架构

┌─────────────────────────────────────────────────────────────┐
│                         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      │ │                      │
└──────────────┘ └──────────────┘ └───────────────────────┘

目录结构

.
├── 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

推荐生产目录

/opt/miaojingAI                 # 项目代码目录
/var/lib/miaojingAI/storage     # 上传文件、生成结果、本地存储
/var/lib/miaojingAI/backups     # 数据备份
/var/lib/miaojingAI/upgrade     # 管理后台升级状态和升级包
/var/lib/miaojingAI/logs        # 部署日志

环境变量

复制模板：

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 冷更新使用的重启命令

生成生产密钥示例：

openssl rand -hex 32

本地开发

1. 安装依赖

corepack enable
corepack pnpm install --frozen-lockfile

2. 初始化数据库

创建数据库：

createdb miaojing

执行初始化脚本：

psql "postgresql://postgres:postgres@localhost:5432/miaojing" -f scripts/init-database.sql

3. 配置环境变量

cp .env.example .env.local

至少填写：

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. 启动开发服务

corepack pnpm run dev

默认开发端口由 scripts/dev.sh 控制，可传入端口：

corepack pnpm run dev -- 5000

5. 常用开发命令

# TypeScript 检查
corepack pnpm run ts-check

# ESLint
corepack pnpm run lint

# 完整构建
corepack pnpm run build

# 边界检查
corepack pnpm run check:boundaries

生产部署

方式一：一键部署/升级脚本

推荐使用：

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. 失败时输出备份路径，方便手动恢复。

方式二：手动部署

安装依赖：

corepack enable
corepack pnpm install --frozen-lockfile --prod=false

构建：

corepack pnpm run build

启动 PM2：

pm2 startOrReload ecosystem.config.cjs --update-env
pm2 save

健康检查：

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 进程直接运行完整服务。

数据库说明

数据库初始化脚本为：

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 平台日志

执行数据库补丁：

corepack pnpm run db:patch

备份与恢复

创建备份

corepack pnpm run backup:create

备份包包含：

  • PostgreSQL dump：database.dump
  • 本地存储目录：local-storage
  • 环境变量：.env.local
  • package.json
  • 备份 manifest

默认只保留最近 10 个备份。

查看备份

corepack pnpm run backup:list

恢复备份

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. 失败时自动恢复源码和数据。

升级日志会写入磁盘状态文件。即使冷更新过程中平台重启，管理后台恢复后也能续上日志和状态。升级完成后，当前页面刷新或切换页面会默认收起实时日志，但历史升级记录中可随时查看完整升级内容和日志。

升级包格式：

.tar
.tar.gz
.tgz

推荐升级包结构：

upgrade-package/
├── manifest.json
├── src/...
├── public/...
├── scripts/...
├── package.json
└── pnpm-lock.yaml

手动运行升级 runner 示例：

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，平台会使用加密存储和尾号预览保护密钥。

存储与下载

生成结果会持久化到本地存储目录或配置的存储服务。推荐生产环境把存储放在项目目录之外：

LOCAL_STORAGE_DIR=/var/lib/miaojingAI/storage

下载链路通过 /api/download 或本地存储路由读取原始文件，不应对图片进行二次压缩。作品历史、生成结果、画廊、全屏预览和下载应始终使用原始结果链接或持久化文件路径。

健康检查与运维命令

健康检查：

curl http://127.0.0.1:5100/api/health

查看 PM2：

pm2 list
pm2 logs miaojing-api --lines 100
pm2 logs miaojing-web --lines 100
pm2 logs miaojing-console --lines 100

重启服务：

corepack pnpm run pm2:restart

保存 PM2 开机配置：

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 中不要只安装生产依赖，推荐：

corepack pnpm install --frozen-lockfile --prod=false

2. 管理后台修改后刷新丢失

优先检查对应接口是否成功写入数据库，再检查 .env.local 是否连接到了正确数据库。不要只看前端本地状态。

3. 图片下载尺寸不符合预期

排查顺序：

  1. 检查上游请求参数是否为目标分辨率。
  2. 检查生成任务结果中保存的原始文件尺寸。
  3. 检查 /api/download 是否直接返回原始文件。
  4. 检查前端是否使用缩略图地址下载。

4. 冷更新后页面仍是旧版本

检查：

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 作为稳定分支：

git clone http://172.16.10.127:3000/fenglee/miaojingAI.git
git checkout main

提交前建议执行：

corepack pnpm run ts-check
corepack pnpm run build

License

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

Reference in New Issue View Git Blame Copy Permalink