# 智念AIGC平台部署说明

本文面向运维部署。推荐使用 Docker Compose，同一套编排会启动 Web 服务和任务 Worker。

## 服务器要求

- Linux 服务器
- Docker
- Docker Compose v2（`docker compose`）或旧版 `docker-compose`
- 可访问外网供应商接口：火山 Visual、EvoLink、Seedance、OSS

## 一键部署

```bash
git clone <仓库地址>
cd NianAIGC
bash scripts/deploy.sh
```

脚本会自动：

- 从 `.env.example` 创建 `.env.local`（如果不存在）
- 创建 `.runtime/data`、`.runtime/uploads`、`.runtime/generated-results`
- 创建 `.runtime/logs`
- 构建镜像
- 启动 `zhinian-aigc` Web 服务
- 启动 `zhinian-worker` 任务 Worker
- 输出容器状态

默认访问：

```text
http://服务器IP:3000
```

## 必填生产配置

部署前编辑 `.env.local`：

```env
APP_PORT=3000
PORT=3000
HOSTNAME=0.0.0.0
NEXT_PUBLIC_APP_URL=https://你的域名

ZHINIAN_AUTH_REQUIRED=auto
ZHINIAN_AUTH_SESSION_SECRET=请替换为强随机会话密钥
NEXT_PUBLIC_SUPABASE_URL=https://你的项目.supabase.co
SUPABASE_SERVICE_ROLE_KEY=请替换为服务端密钥

ZHINIAN_API_KEYS=partner-a:请替换为强随机key
ZHINIAN_INTERNAL_WORKER_TOKEN=请替换为强随机token
ZHINIAN_WEBHOOK_SECRET=请替换为webhook签名密钥
```

`ZHINIAN_API_KEYS` 冒号前是开放 API 账号 ID。不同账号 ID 的任务、素材和幂等键会写入不同 owner 分区，例如 `api:partner-a`。

真实生成能力按需配置：

```env
IMAGE_GENERATE_ENGINE=evolink

EVOLINK_API_KEY=

VOLCENGINE_ACCESS_KEY_ID=
VOLCENGINE_SECRET_ACCESS_KEY=

SEEDANCE_API_KEY=

ALI_OSS_ENDPOINT=
ALI_OSS_BUCKET=
ALI_OSS_ACCESS_KEY_ID=
ALI_OSS_ACCESS_KEY_SECRET=
ALI_OSS_PUBLIC_BASE_URL=
```

如果不配置真实供应商密钥，mock 配置会保留本地验收能力，但生产对接应配置真实密钥。

平台账号部署说明：

```text
npm run bootstrap:admin -- --phone 13800138000 --password '请替换为强密码' --name '平台超级管理员'
```

生产部署前请在 Supabase SQL Editor 执行幂等脚本 [`supabase/schema.sql`](../supabase/schema.sql)，然后运行一次超级管理员初始化命令。旧账号使用 `npm run migrate:accounts -- path/to/legacy-accounts.json` 导入；迁移会保留用量并把历史素材、任务、项目和模板映射到本地账号。

## 旧版组织账号接口（已停用）

如需启用 `/accounts` 后台账号管理，按组织能力接口文档配置：

```env
ZHINIAN_ORG_API_BASE_URL=https://<gateway-domain>/hotelStaff
ZHINIAN_ORG_API_TOKEN=
ZHINIAN_STAFF_API_BASE_URL=https://<gateway-domain>/hotelStaff
ZHINIAN_STAFF_API_TOKEN=
ZHINIAN_ORG_TENANT_ID=
ZHINIAN_ORG_ID=
ZHINIAN_ORG_MEMBER_LIST_PATH=
```

平台后端会代理调用组织、部门、角色、成员和企业端用户接口；成员分页列表默认通过 `hotelStaff` 的 `/adminOrganization/organizationMember/organizationMemberList` 对外代理，只有直连基础组织服务内部 `/organizationMember/organizationMemberList` 时才需要 `from: Y`。如统一服务路径不同，可配置 `ZHINIAN_ORG_MEMBER_LIST_PATH` 覆盖。创建账号调用 `/adminOrganization/organizationMember/addOrganizationMemberAndCreatePlatformUser`，重置密码调用 `/adminPcUser/resetPlatformUserPassword`。这些接口默认转发当前登录管理员账号的 `access_token`，企业端用户接口会校验该 token 是否具备管理员角色 `1`；`ZHINIAN_ORG_API_TOKEN` / `ZHINIAN_STAFF_API_TOKEN` 只作为无登录 token 时的服务端兜底。

## 常用运维命令

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

Web 后台可在登录后访问：

```text
https://你的域名/logs
https://你的域名/settings
https://你的域名/accounts
https://你的域名/usage
https://你的域名/billing
```

日志默认写入 `.runtime/logs/server-events.jsonl`，用于查看 API 500 错误、Worker 任务异常、错误栈和请求路径。可通过环境变量 `ZHINIAN_LOG_DIR` 调整目录，通过 `ZHINIAN_LOG_MAX_BYTES` 调整单文件轮转大小。

更新部署：

```bash
git pull
bash scripts/deploy.sh
```

健康检查：

```bash
curl -f http://127.0.0.1:${APP_PORT:-3000}/api/health
```

OpenAPI：

```bash
curl http://127.0.0.1:${APP_PORT:-3000}/api/v1/openapi.json
```

## 数据持久化

Docker Compose 会挂载：

```text
./.runtime:/app/.runtime
```

本地 JSON 数据层、上传文件和生成结果都会放在 `.runtime/` 下。生产环境如果未启用 Supabase/Postgres，请定期备份该目录。
服务端日志也会放在 `.runtime/logs/` 下，建议和运行时数据一起备份或接入服务器日志采集。

如果生产环境启用了 Supabase/Postgres，发布包含用量和计费管理的版本前，必须在 Supabase SQL Editor 重新执行仓库中的 `supabase/schema.sql`。脚本会幂等升级表结构、补充计费规则的模型变体、来源和参数档位字段、按 `job_id` 去重历史用量，并把计量记录调整为不随生成任务删除。首次打开 `/billing` 或提交真实任务时，系统会自动导入内置标准成本目录；平台参数档案会同步，已有倍率会保留，超级管理员只维护上浮倍率。

建议备份：

```bash
tar -czf zhinian-runtime-$(date +%Y%m%d%H%M%S).tar.gz .runtime
```

## 服务组成

- `zhinian-aigc`：Next.js Web/API 服务，默认容器端口 `3000`
- `zhinian-worker`：后台任务 Worker，负责提交供应商任务、轮询结果、导入资产和触发 Webhook

注意：只启动 Web 服务时，任务会停留在 `queued` 或 `running`，必须同时运行 Worker。

## 反向代理建议

Nginx 示例：

```nginx
server {
  listen 80;
  server_name your-domain.com;

  client_max_body_size 100m;

  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}
```

配置反向代理后，将 `.env.local` 里的 `NEXT_PUBLIC_APP_URL` 设置成公网 HTTPS 地址。

## 验收清单

部署后执行：

```bash
curl -f https://你的域名/api/health
curl -H "Authorization: Bearer <API_KEY>" https://你的域名/api/v1/capabilities
curl https://你的域名/api/v1/openapi.json
```

确认：

- 未登录访问 Web 页面会跳转到 `/auth/login`
- 普通用户登录后看到创作、账号和计费；账号页可修改自己的密码，任务详情、输入要素和结果下载均在创作页右侧任务模块完成，点击页头账号 ID 可查看自己的快捷周期用量
- 从管理员入口登录且命中管理员账号或专用角色白名单后，可访问 `/logs`、`/settings`、`/usage`，并在 `/accounts` 额外维护组织和成员；超级管理员还可配置 `/billing` 计费规则和组织余额
- `/usage` 可按日期、组织、账号、功能和服务商筛选，Mock 与开放 API 任务不计入
- `/billing` 可查看组织余额、成员消耗和账务流水；管理员通过“余额与上账”直接记入组织额度
- `/api/health` 返回 `ok: true`
- `/logs` 可查看后台错误日志
- `/api/v1/capabilities` 使用 API Key 可访问
- `zhinian-worker` 日志持续输出 `claimed=...`
- OSS、EvoLink、火山、Seedance 密钥按业务需要配置完成