feat: add task workflow and asset downloads
This commit is contained in:
inman
267
README.zh-CN.md
Normal file
267
README.zh-CN.md
Normal file
@@ -0,0 +1,267 @@
|
||||
# 智念AIGC平台中文说明
|
||||
|
||||
智念AIGC平台是一个面向图片与视频创作的 Web 工作台。当前版本聚焦核心生产链路：提示词创作、素材上传、图片生成、视频生成、局部重绘、智能超清、历史资产管理和接口配置。
|
||||
|
||||
## 功能概览
|
||||
|
||||
- 统一创作入口：`/create`
|
||||
- 结果资产管理：`/assets`
|
||||
- 服务与引擎配置：`/settings`
|
||||
- 图片生成：即梦图片生成 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`
|
||||
- 构建 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/` 做定期备份。
|
||||
|
||||
## 常用命令
|
||||
|
||||
```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` | 历史任务与资产 |
|
||||
| `/settings` | 接口、引擎和服务配置 |
|
||||
|
||||
## 引擎说明
|
||||
|
||||
### 图片生成
|
||||
|
||||
图片生成可在设置页按能力切换：
|
||||
|
||||
- `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_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`。
|
||||
Reference in New Issue
Block a user