281 lines
11 KiB
Markdown
281 lines
11 KiB
Markdown
# 智念AIGC平台
|
||
|
||
[完整中文说明](./README.zh-CN.md)
|
||
|
||
这是 `智念AIGC平台` 的 Web 极简 MVP。当前产品只保留核心闭环：统一创作图片/视频、查看结果、局部重绘、智能超清和必要设置。
|
||
|
||
运维部署与 API 对接：
|
||
|
||
- [部署说明](./docs/DEPLOYMENT.md)
|
||
- [开放 API 对接说明](./docs/API.md)
|
||
- OpenAPI：`GET /api/v1/openapi.json`
|
||
|
||
## 启动
|
||
|
||
服务器一键部署：
|
||
|
||
```bash
|
||
bash scripts/deploy.sh
|
||
```
|
||
|
||
开发环境：
|
||
|
||
```bash
|
||
cd /Users/inmanx/Documents/zhinian-creation-assistant
|
||
npm install
|
||
npm run dev -- --hostname 127.0.0.1 --port 3000
|
||
```
|
||
|
||
默认访问：
|
||
|
||
```text
|
||
http://127.0.0.1:3000
|
||
```
|
||
|
||
常用命令：
|
||
|
||
```bash
|
||
npm start
|
||
npm run start:server
|
||
npm run worker
|
||
npm run build
|
||
npm test
|
||
npm run health
|
||
npm run info
|
||
```
|
||
|
||
`npm start` 会自动先执行一次生产构建，再启动 `http://127.0.0.1:3000`；开发调试建议继续使用 `npm run dev`。
|
||
|
||
Docker 部署默认使用 `docker-compose.yml` 同时启动 Web 服务和 `zhinian-worker` 任务 Worker，访问 `http://服务器IP:3000`。如需修改端口，调整 `.env.local` 中的 `APP_PORT` 和 `NEXT_PUBLIC_APP_URL` 后重新执行 `bash scripts/deploy.sh`。
|
||
|
||
## Web MVP 信息架构
|
||
|
||
- `/` 自动跳转到 `/create`
|
||
- `/create` 创作，合并图片、视频、局部重绘、智能超清
|
||
- `/assets` 结果，保留历史资产和历史生成任务
|
||
- `/image-edit` 兼容旧入口，自动跳转到创作页的局部重绘
|
||
- `/logs` 日志，管理员可见
|
||
- `/settings` 设置，管理员可见
|
||
- `/accounts` 账号管理，管理员可见
|
||
|
||
普通用户主导航只显示创作和结果；管理员会额外看到日志、设置和账号管理。不包含工作台、项目、模板中心、Billing 或桌面端入口。
|
||
|
||
## 账户登录 / SSO
|
||
|
||
发布环境默认要求账户登录。Web 登录支持两种方式：一是 OAuth2 Authorization Code，用户跳转到认证中心登录，本服务在 `/api/auth/callback` 后端换 token；二是在本项目登录页直接输入账号、密码和图形验证码，由本服务后端调用 `${AUTH_BASE}/oauth2/token` 的 password grant。两种方式都会通过 `${AUTH_BASE}/oauth2/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=app`
|
||
- `ZHINIAN_AUTH_CLIENT_SECRET=app`
|
||
- `ZHINIAN_AUTH_SCOPE=server`
|
||
- `ZHINIAN_AUTH_ISSUER=https://pig4cloud.com`
|
||
- `ZHINIAN_AUTH_PASSWORD_ENC_KEY=thanks,pig4cloud`：按认证中心 `security.encode-key` 对 password grant 的密码做 AES-CFB 加密
|
||
- `ZHINIAN_AUTH_SESSION_SECRET`：长随机字符串，用于签名本地登录态
|
||
- `ZHINIAN_ADMIN_AUTHORITIES`：逗号分隔的管理员权限码；命中后可访问 `/logs`、`/settings`、`/accounts`
|
||
- `ZHINIAN_ADMIN_USERS=ceshiop`：逗号分隔的管理员账号；默认 `ceshiop` 是管理员
|
||
|
||
`/create`、`/assets`、`/settings`、`/logs`、`/accounts`、第一方生成/资产 API、以及本地上传和生成结果文件都会受登录态保护。`/logs`、`/settings`、`/accounts` 和 `/api/admin/*` 需要管理员权限。`/api/v1/*` 继续使用 `ZHINIAN_API_KEYS`，不走浏览器 SSO。
|
||
|
||
如果认证中心客户端未加入 `security.ignore-clients`，`/oauth2/token` 可能返回“验证码不能为空”。当前推荐使用运维分配的 `app/app` 客户端；如改用 `customPC` 登录平台用户，需要认证中心把该 clientId 加入 `security.ignore-clients`。
|
||
|
||
## 组织账号管理
|
||
|
||
后台账号管理通过组织模块接口维护成员、角色、部门绑定和成员状态，并通过企业端用户接口创建用户、重置密码。按运维提供的组织能力接口文档，需要在服务端配置：
|
||
|
||
- `ZHINIAN_ORG_API_BASE_URL`：组织能力网关或统一服务前缀，例如 `https://<gateway-domain>/hotelStaff`
|
||
- `ZHINIAN_ORG_API_TOKEN`：备用 Bearer Token；默认优先转发当前登录管理员的 `access_token`
|
||
- `ZHINIAN_STAFF_API_BASE_URL`：企业端用户服务网关或统一服务前缀，例如 `https://<gateway-domain>/hotelStaff`
|
||
- `ZHINIAN_STAFF_API_TOKEN`：备用 Bearer Token，可为空，默认优先转发当前登录管理员的 `access_token`
|
||
- `ZHINIAN_ORG_TENANT_ID`：需要多租户 Header 时填写
|
||
- `ZHINIAN_ORG_ID`：默认组织 ID，可为空，系统会优先使用组织列表第一项
|
||
- `ZHINIAN_ORG_MEMBER_LIST_PATH`：可选，成员查询路径覆盖；默认 `/adminOrganization/organizationMember/organizationMemberList`
|
||
|
||
成员分页列表通过 `hotelStaff` 的 `/adminOrganization/organizationMember/organizationMemberList` 对外代理；只有直连基础组织服务内部 `/organizationMember/organizationMemberList` 时才需要 `from: Y`。创建账号会优先调用 `/adminOrganization/organizationMember/addOrganizationMemberAndCreatePlatformUser`，密码重置调用 `/adminPcUser/resetPlatformUserPassword`；这些接口默认使用当前登录账号的 token，要求该账号具备管理员角色 `1`。
|
||
|
||
## 图片创作引擎
|
||
|
||
图片生成和局部重绘支持在设置页「状态」里按功能切换创作引擎：
|
||
|
||
- `jimeng`：默认引擎，走火山 Visual 即梦能力。
|
||
- `evolink`：走 EvoLink GPT Image 2 中转站，提交任务后轮询 EvoLink task 结果。
|
||
|
||
智能超清仍走即梦超清能力。
|
||
|
||
## 即梦图片能力
|
||
|
||
V1 接入三类能力：
|
||
|
||
- `image.generate`：即梦图片生成 4.6，默认 `req_key=jimeng_seedream46_cvtob`
|
||
- `image.inpaint`：交互编辑 inpainting，默认 `req_key=jimeng_image2image_dream_inpaint`
|
||
- `image.upscale`：智能超清，默认 `req_key=jimeng_i2i_seed3_tilesr_cvtob`
|
||
|
||
后端统一走火山 Visual 异步任务：
|
||
|
||
- 提交：`CVSync2AsyncSubmitTask`
|
||
- 查询：`CVSync2AsyncGetResult`
|
||
|
||
未配置火山密钥时，`JIMENG_VISUAL_MOCK=auto` 会自动使用 mock 图，方便先跑通产品流。
|
||
|
||
## EvoLink 图片能力
|
||
|
||
设置 `IMAGE_GENERATE_ENGINE=evolink` 或 `IMAGE_INPAINT_ENGINE=evolink` 后，对应功能会使用 EvoLink：
|
||
|
||
- 提交：`POST /v1/images/generations`
|
||
- 查询：`GET /v1/tasks/{task_id}`
|
||
- 默认模型：`gpt-image-2`
|
||
|
||
未配置 `EVOLINK_API_KEY` 且 `EVOLINK_MOCK=auto` 时，会自动使用 mock 图。
|
||
|
||
## AI 生成台与提示词编排
|
||
|
||
`/create` 是新的统一生成入口，按即梦“图片/视频能力在同一个创作产品内切换”的方式组织：
|
||
|
||
- 一个提示词框：图片和视频都在同一创作面板内编辑最终提示词。
|
||
- 模式切换：图片模式走即梦图片生成 4.6；视频模式走 Seedance 视频生成。
|
||
- 素材统一上传：一个入口上传图片、视频或音频，不再拆分参考图、主体、分镜等栏目。
|
||
- `@素材` 引用：上传后自动绑定为 `@图片1`、`@视频1`、`@音频1`，chip 和 @ 候选项都显示缩略图。
|
||
- 提示词校验：通过 `/api/prompt/assemble` 检查提示词中引用的素材是否已绑定。
|
||
- 工作台只负责生成输入和提交，不展示任务列表或最近结果。
|
||
- 结果保存：图片和视频生成结果会写入资产记录，并在 `/assets` 保留历史任务与历史资产。
|
||
|
||
未配置 `SEEDANCE_API_KEY` 时，`SEEDANCE_MOCK=auto` 会自动使用旧模板样片作为 mock 成品，方便先验收工作流。
|
||
|
||
## 环境变量
|
||
|
||
复制配置样例：
|
||
|
||
```bash
|
||
cp .env.example .env.local
|
||
```
|
||
|
||
核心配置：
|
||
|
||
- `ZHINIAN_AUTH_REQUIRED=auto`
|
||
- `ZHINIAN_AUTH_BASE_URL`
|
||
- `ZHINIAN_AUTH_CLIENT_ID=app`
|
||
- `ZHINIAN_AUTH_CLIENT_SECRET`
|
||
- `ZHINIAN_AUTH_SCOPE=server`
|
||
- `ZHINIAN_AUTH_ISSUER=https://pig4cloud.com`
|
||
- `ZHINIAN_AUTH_SESSION_SECRET`
|
||
- `ZHINIAN_ADMIN_AUTHORITIES`
|
||
- `ZHINIAN_ADMIN_USERS`
|
||
- `ZHINIAN_ORG_API_BASE_URL`
|
||
- `ZHINIAN_ORG_API_TOKEN`
|
||
- `ZHINIAN_STAFF_API_BASE_URL`
|
||
- `ZHINIAN_STAFF_API_TOKEN`
|
||
- `ZHINIAN_ORG_TENANT_ID`
|
||
- `ZHINIAN_ORG_ID`
|
||
- `IMAGE_GENERATE_ENGINE=jimeng` 或 `evolink`
|
||
- `IMAGE_INPAINT_ENGINE=jimeng` 或 `evolink`
|
||
- `VOLCENGINE_ACCESS_KEY_ID`
|
||
- `VOLCENGINE_SECRET_ACCESS_KEY`
|
||
- `VOLCENGINE_REGION=cn-north-1`
|
||
- `VOLCENGINE_SERVICE=cv`
|
||
- `VOLCENGINE_VISUAL_ENDPOINT=https://visual.volcengineapi.com`
|
||
- `EVOLINK_API_KEY`
|
||
- `EVOLINK_BASE_URL=https://api.evolink.ai`
|
||
- `EVOLINK_IMAGE_MODEL=gpt-image-2`
|
||
- `EVOLINK_IMAGE_QUALITY=medium`
|
||
- `EVOLINK_IMAGE_RESOLUTION=2K`
|
||
- `EVOLINK_MOCK=auto`
|
||
- `SEEDANCE_API_KEY`
|
||
- `SEEDANCE_BASE_URL`
|
||
- `SEEDANCE_MODEL`
|
||
- `SEEDANCE_RATIO`：支持 `16:9`、`4:3`、`1:1`、`3:4`、`9:16`、`21:9`、`adaptive`
|
||
- `SEEDANCE_DURATION`：Seedance 2.0 支持 `4` 到 `15` 的整数秒，或 `-1` 让模型自动选择
|
||
- `SEEDANCE_RESOLUTION`：支持 `480p`、`720p`、`1080p`；Seedance 2.0 fast 不支持 `1080p`
|
||
- `SEEDANCE_MOCK`
|
||
- `ALI_OSS_*`：用于上传素材和生成结果转存
|
||
- `NEXT_PUBLIC_SUPABASE_URL`
|
||
- `NEXT_PUBLIC_SUPABASE_ANON_KEY`
|
||
- `SUPABASE_SERVICE_ROLE_KEY`
|
||
|
||
如果 Supabase 未配置，应用会使用 `.runtime/data/web-app-state.json` 做本地开发数据层。如果 OSS 未配置，上传和 mock 结果会保存到 `.runtime/uploads` 和 `.runtime/generated-results`，并通过 Web 路由提供访问。
|
||
|
||
## 数据库
|
||
|
||
Supabase/Postgres 表结构在：
|
||
|
||
```text
|
||
supabase/schema.sql
|
||
```
|
||
|
||
当前仍保留必要数据表，供上传、生成任务和用量记录使用：
|
||
|
||
- `assets`
|
||
- `generation_jobs`
|
||
- `usage_events`
|
||
|
||
## 任务管理与开放 API
|
||
|
||
平台支持服务端任务管理：页面和 `/api/v1` 创建任务后只入队，Worker 统一提交供应商、轮询、转存结果、失败重试和 Webhook 回调。生产部署建议配置 Supabase/Postgres；本地开发可继续使用 `.runtime/data/web-app-state.json`。
|
||
|
||
开放 API 使用 API Key：
|
||
|
||
```env
|
||
ZHINIAN_API_KEYS=demo-agent:change-me-public-api-key
|
||
ZHINIAN_INTERNAL_WORKER_TOKEN=change-me-worker-token
|
||
```
|
||
|
||
`ZHINIAN_API_KEYS` 冒号前的值是账号 ID，开放 API 任务和资产会按该账号 ID 写入独立 owner 分区，例如 `api:demo-agent`。
|
||
|
||
主要接口：
|
||
|
||
- `GET /api/v1/capabilities`
|
||
- `POST /api/v1/assets`
|
||
- `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`
|
||
|
||
任务创建支持 `Idempotency-Key` 幂等键和 `webhookUrl` 完成回调。Worker 可用 `npm run worker` 常驻运行，或 `npm run worker:once` 单次处理。
|
||
|
||
## API
|
||
|
||
核心图片 API：
|
||
|
||
- `POST /api/generations/image`
|
||
- `GET /api/generations/image`
|
||
- `GET /api/generations/image/[id]`
|
||
- `POST /api/generations/image/[id]/retry`
|
||
- `POST /api/assets/[id]/inpaint`
|
||
- `POST /api/assets/[id]/upscale`
|
||
- `POST /api/generations/video`
|
||
- `GET /api/generations/video`
|
||
- `GET /api/generations/video/[id]`
|
||
- `POST /api/prompt/assemble`
|
||
- `GET /api/assets`
|
||
- `POST /api/assets`
|
||
- `POST /api/assets/upload`
|
||
|
||
健康检查：
|
||
|
||
- `GET /api/health`
|
||
|
||
## 验证
|
||
|
||
当前已覆盖：
|
||
|
||
- 即梦能力矩阵：4.6/inpainting/upscale 启用
|
||
- 即梦请求参数构造
|
||
- 分镜提示词与 `@素材` 引用编排
|
||
- 火山 Visual 签名 canonical request
|
||
- Next.js 生产构建
|
||
|
||
```bash
|
||
npm test
|
||
npm run build
|
||
npm run health
|
||
```
|