智念AIGC平台

完整中文说明

这是 智念AIGC平台 的 Web 极简 MVP。当前产品只保留核心闭环：统一创作图片/视频、查看结果、局部重绘、智能超清和必要设置。

运维部署与 API 对接：

• 部署说明
• 开放 API 对接说明
• OpenAPI：GET /api/v1/openapi.json

启动

服务器一键部署：

bash scripts/deploy.sh

开发环境：

cd /Users/inmanx/Documents/zhinian-creation-assistant
npm install
npm run dev -- --hostname 127.0.0.1 --port 3000

默认访问：

http://127.0.0.1:3000

常用命令：

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。

需要在认证中心客户端配置中加入回调地址：

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 成品，方便先验收工作流。

环境变量

复制配置样例：

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 表结构在：

supabase/schema.sql

当前仍保留必要数据表，供上传、生成任务和用量记录使用：

• assets
• generation_jobs
• usage_events

任务管理与开放 API

平台支持服务端任务管理：页面和 /api/v1 创建任务后只入队，Worker 统一提交供应商、轮询、转存结果、失败重试和 Webhook 回调。生产部署建议配置 Supabase/Postgres；本地开发可继续使用 .runtime/data/web-app-state.json。

开放 API 使用 API Key：

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 生产构建

npm test
npm run build
npm run health