wangxuming/NianAIGC
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9a3070c74907fa8c2c7b70e6b8e6d2d8f6aa3dd1
NianAIGC/docs/DEPLOYMENT.md
brother7 9a3070c749 修复登录报错问题
2026-07-06 16:31:11 +08:00

6.6 KiB
Raw Blame History

智念AIGC平台部署说明

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

服务器要求

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

一键部署

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
  • 输出容器状态

默认访问：

http://服务器IP:3000

必填生产配置

部署前编辑 .env.local：

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。

真实生成能力按需配置：

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 配置会保留本地验收能力，但生产对接应配置真实密钥。

认证中心客户端需要允许回调地址：

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 后台账号管理，按组织能力接口文档配置：

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 时的服务端兜底。

常用运维命令

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

Web 后台可在登录后访问：

https://你的域名/logs
https://你的域名/settings
https://你的域名/accounts

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

更新部署：

git pull
bash scripts/deploy.sh

健康检查：

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

OpenAPI：

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

数据持久化

Docker Compose 会挂载：

./.runtime:/app/.runtime

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

建议备份：

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 示例：

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 地址。

验收清单

部署后执行：

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 密钥按业务需要配置完成