wangxuming/NianAIGC

Fork 0

Files

inman 0648874801 Add authenticated login and SSO protection

2026-05-29 15:54:13 +08:00

9.5 KiB

Raw Blame History

智念AIGC平台中文说明

智念AIGC平台是一个面向图片与视频创作的 Web 工作台。当前版本聚焦核心生产链路：提示词创作、素材上传、图片生成、视频生成、局部重绘、智能超清、历史资产管理和接口配置。

运维与对接文档

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

功能概览

统一创作入口：/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

快速启动

开发环境：

npm install
cp .env.example .env.local
npm run dev -- --hostname 127.0.0.1 --port 3000

访问地址：

http://127.0.0.1:3000

生产模式：

npm start

npm start 会先执行 next build，再启动 127.0.0.1:3000。

服务器一键部署

服务器推荐使用 Docker Compose：

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 服务

默认访问：

http://服务器IP:3000

如果要换端口，可以编辑 .env.local：

APP_PORT=8080
NEXT_PUBLIC_APP_URL=http://你的服务器IP:8080

然后重新执行：

bash scripts/deploy.sh

常用 Docker 命令：

docker compose ps
docker compose logs -f zhinian-aigc
docker compose logs -f zhinian-worker
docker compose restart
docker compose down

如果服务器不用 Docker，也可以用 Node 直接部署：

npm ci
npm run build
npm run start:server

另开一个进程运行任务 Worker：

npm run worker

生产环境建议把 NEXT_PUBLIC_APP_URL 设置成真实域名或公网地址，配置 ZHINIAN_INTERNAL_WORKER_TOKEN，并把 .runtime/ 做定期备份。

常用命令

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`	接口、引擎和服务配置

账户登录 / SSO

发布环境默认启用账户登录保护。Web 端支持 OAuth2 Authorization Code 和账号密码验证码两种登录方式：授权码模式会跳转认证中心，平台后端在 /api/auth/callback 用授权码换 token；账号密码方式会在本项目登录页提交账号、密码和图形验证码，由后端调用 ${AUTH_BASE}/oauth2/token 的 password grant。两种方式都会通过 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`	OAuth2 客户端 ID，默认 `customPC`
`ZHINIAN_AUTH_CLIENT_SECRET`	OAuth2 客户端密钥，只能保存在服务端
`ZHINIAN_AUTH_SCOPE`	默认 `server`
`ZHINIAN_AUTH_ISSUER`	JWT issuer，默认 `https://pig4cloud.com`
`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：

ZHINIAN_API_KEYS=demo-agent:change-me-public-api-key
ZHINIAN_INTERNAL_WORKER_TOKEN=change-me-worker-token

调用示例：

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 后按需配置：

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。

项目结构

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           服务器部署编排

验证

推荐提交前执行：

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。

9.5 KiB Raw Blame History Unescape Escape