# 智念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`。