370 lines
17 KiB
Markdown
370 lines
17 KiB
Markdown
# 智念AIGC平台中文说明
|
||
|
||
阿里云 ACK 生产部署使用直连 RDS PostgreSQL。配置、迁移和发布步骤见
|
||
[`docs/DEPLOYMENT.md`](./docs/DEPLOYMENT.md) 与 [`deploy/ack`](./deploy/ack) 模板。
|
||
`/api/health` 仅检查进程存活，`/api/ready` 检查数据库就绪状态。
|
||
|
||
智念AIGC平台是一个面向图片与视频创作的 Web 工作台。当前版本聚焦核心生产链路：提示词创作、素材上传、图片生成、视频生成、任务详情与结果下载和接口配置。
|
||
|
||
## 运维与对接文档
|
||
|
||
- [部署说明](./docs/DEPLOYMENT.md)
|
||
- [开放 API 对接说明](./docs/API.md)
|
||
- OpenAPI JSON：`GET /api/v1/openapi.json`
|
||
|
||
## 功能概览
|
||
|
||
- 统一创作入口：`/create`
|
||
- 任务管理：在 `/create` 右侧任务模块查看详情、提示词、输入要素和生成结果
|
||
- 服务与引擎配置：`/settings`，管理员可见
|
||
- 后台日志管理：`/logs`，管理员可见
|
||
- 账户与成员：`/accounts`，登录用户可修改自己的密码，管理员额外管理组织和成员
|
||
- 个人用量：点击页头账号 ID 查看真实任务次数
|
||
- 用量管理：`/usage`，管理员可见
|
||
- 计费中心：`/billing`，所有组织成员可见，超级管理员负责规则、组织余额与直接上账
|
||
- 图片生成：即梦图片生成 4.6 或 EvoLink GPT Image 2
|
||
- 视频生成：Seedance 2.0
|
||
- 素材引用：上传后可在提示词中使用 `@图片1`、`@视频1`、`@音频1`
|
||
- 本地开发兜底：未配置真实接口时，可使用 mock 流程完成产品验收
|
||
|
||
## 技术栈
|
||
|
||
- Next.js 15(前端:页面、静态资源、SSR)
|
||
- Go 1.21(生产后端:独占 `/api`、`/uploads`、`/generated-results`,内嵌 WorkerLoop,见 `backend/` 与 [`docs/DEPLOYMENT.md`](./docs/DEPLOYMENT.md))
|
||
- React 19
|
||
- TypeScript
|
||
- GSAP
|
||
- PostgreSQL(生产)/本地 JSON(开发)
|
||
- 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` | 视频生成模式 |
|
||
| `/logs` | 后台日志管理 |
|
||
| `/settings` | 接口、引擎和服务配置 |
|
||
| `/accounts` | 账户安全、组织和成员账号管理 |
|
||
| `/usage` | 平台账号与组织用量管理（管理员） |
|
||
| `/billing` | 组织余额、成员消耗、账务流水与组织上账 |
|
||
|
||
## 平台账号体系
|
||
|
||
平台不再依赖外部 OAuth2/SSO。所有浏览器用户统一使用手机号和密码登录，账号数据由平台自己管理：生产环境直连 PostgreSQL，本地开发使用 `.runtime/data/platform-accounts.json`。
|
||
|
||
角色分为超级管理员、组织管理员和普通用户。组织管理员只能管理本组织普通用户和查看组织汇总用量，不能查看日志、系统配置或管理组织生命周期；普通用户只能访问自己的创作、素材、任务和账户安全。
|
||
|
||
核心配置：
|
||
|
||
| 变量 | 说明 |
|
||
|------|------|
|
||
| `ZHINIAN_AUTH_REQUIRED` | `auto` 默认策略；生产启用，本地可信开发可设 `0` |
|
||
| `ZHINIAN_AUTH_SESSION_SECRET` | 长随机字符串，用于签名 HttpOnly 会话 Cookie |
|
||
| `ZHINIAN_BILLING_REQUIRED` | 真实任务计费开关，默认启用；停用时真实任务免计费 |
|
||
| `ZHINIAN_BILLING_ACCOUNT_*` | 成员线下转账时展示的对公账户名称、开户行、银行账号和对接信息 |
|
||
| `ZHINIAN_DATA_BACKEND` | 生产设为 `postgres`，开发可设为 `local` |
|
||
| `DATABASE_URL` | 仅服务端使用的 PostgreSQL 连接串 |
|
||
| `ZHINIAN_DATA_DIR` | 本地账号 JSON 数据目录，可选 |
|
||
|
||
首次部署时执行一次：
|
||
|
||
```bash
|
||
npm run bootstrap:admin -- --phone 13800138000 --password '请替换为强密码' --name '平台超级管理员'
|
||
```
|
||
|
||
管理员创建账号时设置初始密码；所有登录用户可以在“账号”中自行修改密码。登录失败 5 次会锁定 15 分钟，同时启用 IP 限流。停用账号不能登录，彻底删除账号时用量记录保留，素材和任务会转入组织归档账号。
|
||
|
||
旧账号迁移使用 `npm run migrate:accounts -- path/to/legacy-accounts.json`。迁移文件需要提供旧 owner ID、手机号、显示名称、所属组织和管理员设置的新密码；迁移会更新历史素材、任务、项目、模板和用量的账号归属，并写入映射记录。
|
||
|
||
开放 `/api/v1/*` 仍使用 API Key，Worker 仍使用内部 token，不走浏览器账号登录。
|
||
|
||
## 组织账号管理
|
||
|
||
组织、账号、角色、停用、密码重置和归档均由平台本地接口处理，不再调用外部组织服务。生产部署前由部署负责人手工执行 [`database/migrations`](./database/migrations) 中的版本化 SQL 文件（先 0001 后 0002）及角色授权语句完成建库建表，不部署迁移 Job Pod；超级管理员由 Go 后端首次启动时通过 `ZHINIAN_BOOTSTRAP_ADMIN_*` 环境变量自动创建一次。
|
||
|
||
## 账号、组织用量与计费
|
||
|
||
- 仅统计平台内登录用户调用真实服务商后成功完成的任务。
|
||
- 成功任务会进入用量记录；一次返回多张图片的计费数量以超级管理员配置的标准计费单位为准。
|
||
- 失败、取消、过期、Mock 和开放 API 客户端任务不计入。
|
||
- 任务创建时会快照账号、租户和组织归属；无法匹配的记录进入“未归属组织”。
|
||
- 用户删除任务、素材或账号不会删除计量记录；用量明细不保存或展示提示词、素材与生成结果。
|
||
- 统计日和自然月统一使用 `Asia/Shanghai`。
|
||
|
||
普通用户点击页头账号 ID，可切换今天、近 7 天、近 30 天和本月，并查看最近 5 条记录。管理员通过 `/usage` 按日期、组织、账号、功能类型和服务商查看汇总、趋势及明细；所有组织成员可在 `/billing` 查看组织余额和自己的净消耗。
|
||
|
||
超级管理员在 `/billing` 配置各接口来源的标准单价与上浮倍率。真实生成任务按“标准计费单位 × 数量 × 上浮倍率”在提交时从组织余额冻结，并在任务中保存计费快照；失败、取消、过期任务会在最终终态退款。普通用户余额不足时会被拒绝提交并提示“余额不足，请先充值”，不会提交服务商；超级管理员仍计算并记录生成费用，但不检查或扣减组织额度，也不产生钱包扣费、退款流水。Seedance 成功后按上游返回的 `usage.completion_tokens` 重新结算，多退少补；上游没有返回用量时保留冻结金额。当前充值和人工余额调整由超级管理员在“余额与上账”中直接记入组织额度，不设置个人上账归属；未来接入用户自主支付时，支付成功回调将自动入账，不进入人工审核队列。未绑定组织的开放 API 任务暂保持兼容，不纳入组织余额扣费。
|
||
|
||
首次打开超管计费中心或提交真实任务时，系统会自动补齐以下平台标准成本目录（不会覆盖已有目录）。默认上浮倍率为 `1.2×`，最终用户价按整数分计算并向上取整：
|
||
|
||
| 渠道/模型 | 变体 | 基础价 | 计费单位 |
|
||
| --- | --- | ---: | --- |
|
||
| 百炼 `wan2.7-image-pro` | — | ¥0.50 | 每张 |
|
||
| 百炼 `wan2.7-i2v-2026-04-25` | 720P | ¥0.60 | 每秒 |
|
||
| 百炼 `wan2.7-i2v-2026-04-25` | 1080P | ¥1.00 | 每秒 |
|
||
| 火山方舟 `doubao-seedance-2-0-260128` | 480P | ¥0.46 | 每秒 |
|
||
| 火山方舟 `doubao-seedance-2-0-260128` | 720P | ¥0.99 | 每秒 |
|
||
| 火山方舟 `doubao-seedance-2-0-260128` | 1080P | ¥2.48 | 每秒 |
|
||
| 火山方舟 `doubao-seedance-2-0-260128` | 4K | ¥5.05 | 每秒 |
|
||
| EvoLink `gpt-image-2` | medium / 1K / 1:1 / 无参考图基础估算 | ¥0.34 | 每张 |
|
||
| 即梦 `jimeng_seedream46_cvtob` | 公开资源包折算参考 | ¥0.20 | 每张 |
|
||
|
||
其中 EvoLink 按固定 `1 USD = 7.20 CNY` 换算，并在价格目录中列出质量、分辨率、画面比例和参考图数量档位；参数化报价按基础成本乘以所选档位系数，组合倍率取所选档位中的最高倍率。即梦 4.6 官方计费说明要求以控制台实时价格为准，因此该条目是平台维护的参考基准。超管只在价格目录中调整上浮倍率，标准成本、参数档案和规则状态由平台维护；来源链接和定价口径会随规则保留。
|
||
|
||
使用 PostgreSQL 时，首次部署和每次 schema 变更均按 `database/migrations/*.sql` 中的版本化 SQL 文件手工执行（拒绝已应用脚本被静默改写），执行完成后再滚动工作负载。`local` 模式下，本地 JSON 数据会在读取时按相同口径兼容旧记录。
|
||
|
||
## 引擎说明
|
||
|
||
### 图片生成
|
||
|
||
图片生成可在设置页按能力切换：
|
||
|
||
- `jimeng`：火山 Visual 即梦能力
|
||
- `evolink`：EvoLink GPT Image 2 中转接口
|
||
- `bailian`：阿里云百炼万相 2.7，支持文生图、最多 9 张参考图生图，以及 1–2 张首尾帧图生视频
|
||
|
||
### 视频生成
|
||
|
||
视频生成使用 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`、`4k`
|
||
- 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
|
||
```
|
||
|
||
`ZHINIAN_API_KEYS` 冒号前的值是账号 ID，开放 API 任务和资产会按该账号 ID 写入独立 owner 分区，例如 `api:demo-agent`。
|
||
|
||
调用示例：
|
||
|
||
```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_ADMIN_AUTH_CLIENT_ID` | 管理员登录入口 OAuth2 客户端 ID |
|
||
| `ZHINIAN_ADMIN_AUTH_CLIENT_SECRET` | 管理员登录入口 OAuth2 客户端密钥 |
|
||
| `ZHINIAN_AUTH_TENANT_ID` | 普通账号 password grant 租户 ID；为空时复用 `ZHINIAN_ORG_TENANT_ID` |
|
||
| `ZHINIAN_ADMIN_AUTH_TENANT_ID` | 管理员 password grant 租户 ID，通常留空 |
|
||
| `ZHINIAN_AUTH_SESSION_SECRET` | 本地登录态签名密钥 |
|
||
| `ZHINIAN_ADMIN_AUTHORITIES` | 专用管理员角色精确白名单 |
|
||
| `ZHINIAN_ADMIN_USERS` | 管理员账号白名单，默认 `ceshiop` |
|
||
| `ZHINIAN_ORG_API_BASE_URL` | 组织账号接口 Base URL |
|
||
| `ZHINIAN_ORG_API_TOKEN` | 组织账号接口备用 Bearer Token |
|
||
| `ZHINIAN_STAFF_API_BASE_URL` | 企业端用户接口 Base URL |
|
||
| `ZHINIAN_STAFF_API_TOKEN` | 企业端用户接口备用 Bearer Token，可为空 |
|
||
| `ZHINIAN_ORG_TENANT_ID` | 组织接口租户 ID |
|
||
| `ZHINIAN_ORG_ID` | 默认组织 ID |
|
||
| `ZHINIAN_API_KEYS` | 开放 API Key，格式 `账号ID:key,账号ID2:key2`；任务和资产按账号 ID 写入独立 owner 分区 |
|
||
| `ZHINIAN_INTERNAL_WORKER_TOKEN` | 内部 Worker tick 接口令牌 |
|
||
| `ZHINIAN_WEBHOOK_SECRET` | Webhook 签名密钥，可选 |
|
||
| `ZHINIAN_WORKER_*` | Worker 间隔、批量、锁超时、重试配置 |
|
||
| `IMAGE_GENERATE_ENGINE` | 图片生成引擎：`jimeng` 或 `evolink` |
|
||
| `BAILIAN_API_KEY` | 阿里云百炼 API Key |
|
||
| `BAILIAN_BASE_URL` | 百炼业务空间兼容地址；系统自动派生原生异步接口 |
|
||
| `BAILIAN_IMAGE_MODEL` | 图片模型，默认 `wan2.7-image-pro` |
|
||
| `BAILIAN_VIDEO_MODEL` | 视频模型，默认 `wan2.7-i2v-2026-04-25` |
|
||
| `VIDEO_GENERATE_ENGINE` | 视频生成引擎：`seedance` 或 `bailian` |
|
||
| `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_*` | 上传素材和生成结果转存配置 |
|
||
| `ZHINIAN_DATA_BACKEND` | `postgres` 或 `local` |
|
||
| `DATABASE_URL` | PostgreSQL 连接串（仅放 Secret） |
|
||
| `DATABASE_SSL_MODE` / `DATABASE_CA_CERT_PATH` | RDS TLS 验证配置 |
|
||
|
||
`ZHINIAN_DATA_BACKEND=local` 时，应用使用 `.runtime/data/web-app-state.json` 作为单实例开发数据层；生产 `postgres` 模式配置错误会直接失败。未配置 OSS 时，上传和生成结果会写入 `.runtime/uploads` 与 `.runtime/generated-results`。
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
app/ Next.js App Router 页面与 API
|
||
components/ 前端组件
|
||
lib/ 业务逻辑、服务端适配器、接口客户端
|
||
lib/ui/motion.ts GSAP 动效工具层
|
||
public/logo/ 品牌 Logo
|
||
scripts/ 启动、健康检查与信息脚本
|
||
database/migrations/ 版本化 PostgreSQL 迁移
|
||
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`。
|