层级	技术
前端框架	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

环境变量

复制模板：

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 连接地址
正式访问地址

首次部署时，脚本会：

检查 tar、rsync、curl、psql、pg_dump 等依赖。
自动安装或切换 Node.js 22/24。
安装 pnpm 和 PM2。
准备 .env.local。
初始化或检查数据库。
构建 Next.js 和 Node server。
写入 PM2 配置并启动服务。
执行健康检查。

升级已有部署时，脚本会：

检测已有部署目录。
创建升级前备份。
同步新代码。
构建并重启服务。
执行健康检查。
失败时输出备份路径，方便手动恢复。

方式二：手动部署

安装依赖：

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

恢复动作会：

使用 pg_restore --clean --if-exists --no-owner 恢复数据库。
替换本地存储目录。
恢复 .env.local。

生产环境恢复前建议先停服务，并额外复制当前数据目录。

管理后台在线升级

管理后台“系统升级”提供两类升级能力：

热更新

用于不影响运行时代码的小补丁，例如 public/ 下的静态资源。

特点：

不重启平台。
升级前自动创建数据库/存储/环境备份。
升级前自动创建源码快照。
失败自动回滚。
升级界面实时显示中文日志。

冷更新

用于涉及源码、脚本、依赖、配置的大变更。

冷更新流程：

上传升级包。
校验升级包路径，拒绝 .env、.git、node_modules、backups、local-storage 等危险路径。
创建数据库、存储、环境配置备份。
创建源码快照。
应用升级包文件。
如依赖变化，执行 pnpm install --frozen-lockfile --prod=false。
执行 pnpm run ts-check。
执行 pnpm run build。
重启平台。
调用 /api/health 做健康检查。
失败时自动恢复源码和数据。

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

升级包格式：

.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. 图片下载尺寸不符合预期

排查顺序：

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

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

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

README.md Unescape Escape

妙境 AI 创作平台

项目截图

首页

创作中心

作品画廊

核心能力

创作能力

管理后台

运维能力

技术栈