219 lines
6.6 KiB
Markdown
219 lines
6.6 KiB
Markdown
# 智念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_BASE_URL=https://<gateway-domain>/auth
|
||
ZHINIAN_AUTH_CLIENT_ID=custom
|
||
ZHINIAN_AUTH_CLIENT_SECRET=custom
|
||
ZHINIAN_ADMIN_AUTH_CLIENT_ID=app
|
||
ZHINIAN_ADMIN_AUTH_CLIENT_SECRET=app
|
||
ZHINIAN_AUTH_TENANT_ID=
|
||
ZHINIAN_ADMIN_AUTH_TENANT_ID=
|
||
ZHINIAN_AUTH_SCOPE=server
|
||
ZHINIAN_AUTH_ISSUER=https://pig4cloud.com
|
||
ZHINIAN_AUTH_PASSWORD_ENC_KEY=thanks,pig4cloud
|
||
ZHINIAN_AUTH_SESSION_SECRET=请替换为强随机会话密钥
|
||
ZHINIAN_ADMIN_AUTHORITIES=ROLE_ADMIN,sys_user_view,sys_log_view,sys_config_view
|
||
ZHINIAN_ADMIN_USERS=ceshiop
|
||
|
||
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
|
||
IMAGE_INPAINT_ENGINE=jimeng
|
||
|
||
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
|
||
https://你的域名/api/auth/callback
|
||
```
|
||
|
||
如果使用登录页内的账号密码方式，需要确认客户端支持 `password` 和 `refresh_token` grant，并已加入认证中心配置 `security.ignore-clients`。普通账号登录使用 `ZHINIAN_AUTH_CLIENT_ID` / `ZHINIAN_AUTH_CLIENT_SECRET`，默认 `custom/custom`，并会把 `ZHINIAN_AUTH_TENANT_ID` 作为 `tenantId` 传给认证中心；`ZHINIAN_AUTH_TENANT_ID` 为空时复用 `ZHINIAN_ORG_TENANT_ID`。登录页里的“管理员登录”入口使用 `ZHINIAN_ADMIN_AUTH_CLIENT_ID` / `ZHINIAN_ADMIN_AUTH_CLIENT_SECRET`，默认 `app/app`；管理员租户只在显式配置 `ZHINIAN_ADMIN_AUTH_TENANT_ID` 时传递。
|
||
|
||
## 组织账号接口
|
||
|
||
如需启用 `/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
|
||
```
|
||
|
||
日志默认写入 `.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/` 下，建议和运行时数据一起备份或接入服务器日志采集。
|
||
|
||
建议备份：
|
||
|
||
```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`
|
||
- 普通用户登录后只看到创作和结果
|
||
- 管理员登录后可访问 `/logs`、`/settings`、`/accounts`
|
||
- `/api/health` 返回 `ok: true`
|
||
- `/logs` 可查看后台错误日志
|
||
- `/api/v1/capabilities` 使用 API Key 可访问
|
||
- `zhinian-worker` 日志持续输出 `claimed=...`
|
||
- OSS、EvoLink、火山、Seedance 密钥按业务需要配置完成
|