310 lines
9.9 KiB
Markdown
310 lines
9.9 KiB
Markdown
# 智念AIGC平台中文说明
|
||
|
||
智念AIGC平台是一个面向图片与视频创作的 Web 工作台。当前版本聚焦核心生产链路：提示词创作、素材上传、图片生成、视频生成、局部重绘、智能超清、历史资产管理和接口配置。
|
||
|
||
## 运维与对接文档
|
||
|
||
- [部署说明](./docs/DEPLOYMENT.md)
|
||
- [开放 API 对接说明](./docs/API.md)
|
||
- OpenAPI JSON：`GET /api/v1/openapi.json`
|
||
|
||
## 功能概览
|
||
|
||
- 统一创作入口：`/create`
|
||
- 结果资产管理：`/assets`
|
||
- 服务与引擎配置：`/settings`
|
||
- 后台日志管理：`/logs`
|
||
- 图片生成：即梦图片生成 4.6 或 EvoLink GPT Image 2
|
||
- 图片编辑：局部重绘、智能超清
|
||
- 视频生成：Seedance 2.0
|
||
- 素材引用：上传后可在提示词中使用 `@图片1`、`@视频1`、`@音频1`
|
||
- 本地开发兜底：未配置真实接口时，可使用 mock 流程完成产品验收
|
||
|
||
## 技术栈
|
||
|
||
- Next.js 15
|
||
- React 19
|
||
- TypeScript
|
||
- GSAP
|
||
- Supabase/Postgres 可选
|
||
- Aliyun OSS 可选
|
||
- Vitest
|
||
|
||
## 快速启动
|
||
|
||
开发环境：
|
||
|
||
```bash
|
||
npm install
|
||
cp .env.example .env.local
|
||
npm run dev -- --hostname 127.0.0.1 --port 3000
|
||
```
|
||
|
||
访问地址：
|
||
|
||
```text
|
||
http://127.0.0.1:3000
|
||
```
|
||
|
||
生产模式：
|
||
|
||
```bash
|
||
npm start
|
||
```
|
||
|
||
`npm start` 会先执行 `next build`，再启动 `127.0.0.1:3000`。
|
||
|
||
## 服务器一键部署
|
||
|
||
服务器推荐使用 Docker Compose：
|
||
|
||
```bash
|
||
git clone <你的仓库地址>
|
||
cd NianAIGC
|
||
bash scripts/deploy.sh
|
||
```
|
||
|
||
脚本会自动完成：
|
||
|
||
- 创建 `.env.local`
|
||
- 创建 `.runtime/data`、`.runtime/uploads`、`.runtime/generated-results`
|
||
- 创建 `.runtime/logs`
|
||
- 构建 Docker 镜像
|
||
- 使用 `docker compose up -d --build` 后台启动 Web 服务和 Worker 服务
|
||
|
||
默认访问：
|
||
|
||
```text
|
||
http://服务器IP:3000
|
||
```
|
||
|
||
如果要换端口，可以编辑 `.env.local`：
|
||
|
||
```env
|
||
APP_PORT=8080
|
||
NEXT_PUBLIC_APP_URL=http://你的服务器IP:8080
|
||
```
|
||
|
||
然后重新执行：
|
||
|
||
```bash
|
||
bash scripts/deploy.sh
|
||
```
|
||
|
||
常用 Docker 命令：
|
||
|
||
```bash
|
||
docker compose ps
|
||
docker compose logs -f zhinian-aigc
|
||
docker compose logs -f zhinian-worker
|
||
docker compose restart
|
||
docker compose down
|
||
```
|
||
|
||
如果服务器不用 Docker，也可以用 Node 直接部署：
|
||
|
||
```bash
|
||
npm ci
|
||
npm run build
|
||
npm run start:server
|
||
```
|
||
|
||
另开一个进程运行任务 Worker：
|
||
|
||
```bash
|
||
npm run worker
|
||
```
|
||
|
||
生产环境建议把 `NEXT_PUBLIC_APP_URL` 设置成真实域名或公网地址，配置 `ZHINIAN_INTERNAL_WORKER_TOKEN`，并把 `.runtime/` 做定期备份。
|
||
部署后如果页面或接口报错，登录后台访问 `/logs` 查看最近错误、请求路径、状态码和错误栈。日志文件默认在 `.runtime/logs/server-events.jsonl`。
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
npm run dev -- --hostname 127.0.0.1 --port 3000
|
||
npm test
|
||
npm run build
|
||
npm run health
|
||
npm run worker:once
|
||
npm run info
|
||
```
|
||
|
||
## 页面路由
|
||
|
||
| 路由 | 用途 |
|
||
|------|------|
|
||
| `/` | 自动跳转到 `/create` |
|
||
| `/create` | 统一创作入口 |
|
||
| `/create?mode=video` | 视频生成模式 |
|
||
| `/create?mode=inpaint` | 局部重绘模式 |
|
||
| `/create?mode=upscale` | 智能超清模式 |
|
||
| `/assets` | 历史任务与资产 |
|
||
| `/logs` | 后台日志管理 |
|
||
| `/settings` | 接口、引擎和服务配置 |
|
||
|
||
## 账户登录 / SSO
|
||
|
||
发布环境默认启用账户登录保护。Web 端支持 OAuth2 Authorization Code 和账号密码验证码两种登录方式：授权码模式会跳转认证中心，平台后端在 `/api/auth/callback` 用授权码换 token；账号密码方式会在本项目登录页提交账号、密码和图形验证码，由后端调用 `${AUTH_BASE}/oauth2/token` 的 password grant。两种方式都会通过 JWKS 本地验签 JWT，然后写入 HttpOnly 会话 cookie。
|
||
|
||
认证中心客户端需要配置回调地址：
|
||
|
||
```text
|
||
https://你的域名/api/auth/callback
|
||
```
|
||
|
||
核心配置：
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `ZHINIAN_AUTH_REQUIRED` | `auto` 默认策略；生产启用，本地可信开发可设 `0` |
|
||
| `ZHINIAN_AUTH_BASE_URL` | 认证服务网关地址，例如 `https://<gateway-domain>/auth` |
|
||
| `ZHINIAN_AUTH_CLIENT_ID` | OAuth2 客户端 ID，默认 `customPC` |
|
||
| `ZHINIAN_AUTH_CLIENT_SECRET` | OAuth2 客户端密钥，只能保存在服务端 |
|
||
| `ZHINIAN_AUTH_SCOPE` | 默认 `server` |
|
||
| `ZHINIAN_AUTH_ISSUER` | JWT issuer，默认 `https://pig4cloud.com` |
|
||
| `ZHINIAN_AUTH_PASSWORD_ENC_KEY` | 按 AgentBus 方式对 password grant 的密码做 AES-CFB 加密；留空则透传明文 |
|
||
| `ZHINIAN_AUTH_SESSION_SECRET` | 本地会话签名密钥，使用长随机字符串 |
|
||
|
||
受保护范围包括 `/create`、`/assets`、`/settings`、第一方生成/资产 API，以及本地 `/uploads/*` 和 `/generated-results/*` 文件。开放 `/api/v1/*` 仍使用 API Key，Worker 仍使用内部 token，不走浏览器 SSO。
|
||
|
||
如果认证中心客户端没有加入 `security.ignore-clients`，账号密码登录会要求图形验证码；验证码图片由 `/api/auth/captcha` 代理 `${AUTH_BASE}/code/image` 获取。
|
||
|
||
## 引擎说明
|
||
|
||
### 图片生成
|
||
|
||
图片生成可在设置页按能力切换：
|
||
|
||
- `jimeng`：火山 Visual 即梦能力
|
||
- `evolink`：EvoLink GPT Image 2 中转接口
|
||
|
||
### 图片编辑
|
||
|
||
- 局部重绘：即梦 inpainting 或 EvoLink inpaint
|
||
- 智能超清：即梦超清能力
|
||
|
||
### 视频生成
|
||
|
||
视频生成使用 Seedance 2.0。
|
||
|
||
当前参数限制已按官方接口收口：
|
||
|
||
- `duration`：`4` 到 `15` 的整数秒
|
||
- `duration=-1`：允许在环境变量或服务端归一化中表示模型自动选择
|
||
- `ratio`：`16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive`
|
||
- `resolution`：`480p`、`720p`、`1080p`
|
||
- Seedance 2.0 fast 不支持 `1080p`
|
||
|
||
## 任务管理与开放 API
|
||
|
||
平台现在支持服务端任务管理：页面和开放 API 提交任务后只写入 `queued`，由 Worker 统一提交供应商、轮询状态、导入资产、重试和触发 Webhook。这个实现不是 Redis/BullMQ 消息队列，而是基于 `generation_jobs` 的任务状态机、锁和调度字段。
|
||
|
||
开放 API 使用 API Key：
|
||
|
||
```env
|
||
ZHINIAN_API_KEYS=demo-agent:change-me-public-api-key
|
||
ZHINIAN_INTERNAL_WORKER_TOKEN=change-me-worker-token
|
||
```
|
||
|
||
调用示例：
|
||
|
||
```bash
|
||
curl -X POST http://127.0.0.1:3000/api/v1/jobs \
|
||
-H 'Authorization: Bearer change-me-public-api-key' \
|
||
-H 'Content-Type: application/json' \
|
||
-H 'Idempotency-Key: demo-job-001' \
|
||
-d '{"capability":"image.generate","prompt":"生成一张专业产品主图"}'
|
||
```
|
||
|
||
主要接口：
|
||
|
||
| 接口 | 说明 |
|
||
|------|------|
|
||
| `GET /api/v1/capabilities` | 查询图片、修图、超清、视频能力 |
|
||
| `POST /api/v1/assets` | 上传文件或注册外部素材 URL |
|
||
| `GET /api/v1/assets` | 查询素材 |
|
||
| `POST /api/v1/jobs` | 创建生成任务 |
|
||
| `GET /api/v1/jobs` | 按状态、能力、时间分页查询任务 |
|
||
| `GET /api/v1/jobs/:id` | 查询单个任务 |
|
||
| `POST /api/v1/jobs/:id/cancel` | 取消未完成任务 |
|
||
| `GET /api/v1/openapi.json` | OpenAPI 描述 |
|
||
|
||
幂等规则：同一 API Client 使用同一个 `Idempotency-Key` 重复提交相同请求时返回已有任务；请求内容不同会返回 `409`。
|
||
|
||
Webhook：创建任务时传 `webhookUrl`，任务进入 `succeeded`、`failed`、`cancelled` 或 `expired` 后会回调。配置 `ZHINIAN_WEBHOOK_SECRET` 后，请求头会带 `X-Zhinian-Signature: sha256=...`。
|
||
|
||
## 环境变量
|
||
|
||
复制 `.env.example` 后按需配置：
|
||
|
||
```bash
|
||
cp .env.example .env.local
|
||
```
|
||
|
||
核心变量：
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `APP_PORT` | Docker Compose 对外暴露端口，默认 `3000` |
|
||
| `NEXT_PUBLIC_APP_URL` | 对外访问地址，用于生成回调/本地文件 URL |
|
||
| `ZHINIAN_AUTH_REQUIRED` | 账户登录保护策略 |
|
||
| `ZHINIAN_AUTH_BASE_URL` | 统一认证中心地址 |
|
||
| `ZHINIAN_AUTH_CLIENT_ID` | OAuth2 客户端 ID |
|
||
| `ZHINIAN_AUTH_CLIENT_SECRET` | OAuth2 客户端密钥 |
|
||
| `ZHINIAN_AUTH_SESSION_SECRET` | 本地登录态签名密钥 |
|
||
| `ZHINIAN_API_KEYS` | 开放 API Key，格式 `clientId:key,clientId2:key2` |
|
||
| `ZHINIAN_INTERNAL_WORKER_TOKEN` | 内部 Worker tick 接口令牌 |
|
||
| `ZHINIAN_WEBHOOK_SECRET` | Webhook 签名密钥，可选 |
|
||
| `ZHINIAN_WORKER_*` | Worker 间隔、批量、锁超时、重试配置 |
|
||
| `IMAGE_GENERATE_ENGINE` | 图片生成引擎：`jimeng` 或 `evolink` |
|
||
| `IMAGE_INPAINT_ENGINE` | 局部重绘引擎：`jimeng` 或 `evolink` |
|
||
| `VOLCENGINE_ACCESS_KEY_ID` | 火山引擎 Access Key |
|
||
| `VOLCENGINE_SECRET_ACCESS_KEY` | 火山引擎 Secret Key |
|
||
| `EVOLINK_API_KEY` | EvoLink API Key |
|
||
| `SEEDANCE_API_KEY` | 火山方舟 Seedance API Key |
|
||
| `SEEDANCE_MODEL` | Seedance 模型 ID |
|
||
| `SEEDANCE_RATIO` | 默认视频比例 |
|
||
| `SEEDANCE_DURATION` | 默认视频秒数 |
|
||
| `SEEDANCE_RESOLUTION` | 默认视频分辨率 |
|
||
| `ALI_OSS_*` | 上传素材和生成结果转存配置 |
|
||
| `NEXT_PUBLIC_SUPABASE_URL` | Supabase URL |
|
||
| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Supabase 匿名 Key |
|
||
| `SUPABASE_SERVICE_ROLE_KEY` | Supabase 服务端 Key |
|
||
|
||
未配置 Supabase 时，应用会使用 `.runtime/data/web-app-state.json` 作为本地开发数据层。未配置 OSS 时，上传和生成结果会写入 `.runtime/uploads` 与 `.runtime/generated-results`。
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
app/ Next.js App Router 页面与 API
|
||
components/ 前端组件
|
||
lib/ 业务逻辑、服务端适配器、接口客户端
|
||
lib/ui/motion.ts GSAP 动效工具层
|
||
public/logo/ 品牌 Logo
|
||
scripts/ 启动、健康检查与信息脚本
|
||
supabase/schema.sql 数据库结构
|
||
tests/ Vitest 测试
|
||
Dockerfile Docker 镜像构建
|
||
docker-compose.yml 服务器部署编排
|
||
```
|
||
|
||
## 验证
|
||
|
||
推荐提交前执行：
|
||
|
||
```bash
|
||
npm test
|
||
npm run build
|
||
npm run health
|
||
npm run worker:once
|
||
```
|
||
|
||
如果本地 dev server 正在运行，建议先停止后再执行生产构建，避免 Next.js dev 缓存与生产构建互相影响。
|
||
|
||
## 注意事项
|
||
|
||
- `.env.local` 不应提交到仓库。
|
||
- `.next/`、`.runtime/`、`node_modules/` 不应提交到仓库。
|
||
- 当前主产品名为 `智念AIGC平台`。
|
||
- 顶部 Logo 使用 `public/logo/zhinian-logo.png`。
|