feat(tokenhub): 添加复用 prod-dbs 的部署配置

- 单容器一体部署（后端 8080 + 管理后台 3000）join prod-dbs_default 直连 prod-postgres - env.cfg.example 模板与 readme（建库/登录/反向代理/升级备份说明）
2026-09-03 22:23:45 +08:00
parent 9b823ba34e
commit 1155c1b7a0
3 changed files with 288 additions and 0 deletions
@@ -0,0 +1,85 @@
+# ============================================================
+# TokenHub 部署 — 环境变量模板（不含敏感信息）
+# 复制为 env.cfg 后填入真实值，env.cfg 已在 .gitignore 中忽略
+# ============================================================
+#
+# 使用方式（在 deploy.stack 仓库根目录执行，需先 up prod-dbs）：
+#   cp tokenhub/env.cfg.example tokenhub/env.cfg
+#   $EDITOR tokenhub/env.cfg                     # 填入密码/密钥后保存
+#   docker compose -p tokenhub-host --env-file ./tokenhub/env.cfg -f ./tokenhub/stack.host.yml up -d
+#
+# 官方镜像：ghcr.io/astaxie/tokenhub-backend（无 Docker Hub 镜像），
+# 单镜像内含 Go 后端(:8080) + Next.js 管理后台(:3000)。
+# 版本 tag 为纯数字（0.7.0 / 0.7 / latest），建议固定完整版本。
+#
+# 本方案复用 prod-dbs 的 PostgreSQL（不启动 SQLite 数据卷业务库），
+# 需先在 prod-postgres 建库建号（SQL 模板见 tokenhub/readme.md）。
+#
+# 注意：
+# - PostgreSQL 场景 TOKENHUB_SECRET_KEY 必须 ≥32 字节的稳定值，且不可变更；
+# - 生产（prod）环境已知占位值（change-me-*）会被按未配置处理；
+# - 与 newapi/mixapi 同机时 3000/8080 默认端口会冲突，改下面端口即可。
+
+# ---------- 端口 ----------
+# 管理后台宿主机端口（默认 3000，与 newapi/mixapi 冲突）
+TOKENHUB_FRONTEND_PORT=3000
+# 后端/网关宿主机端口（默认 8080，与同机其他 8080 服务冲突时改）
+TOKENHUB_BACKEND_PORT=8080
+
+# ---------- 镜像 ----------
+# TokenHub 版本（ghcr.io/astaxie/tokenhub-backend 的纯数字 tag，如 0.7.0/0.7/latest）
+TOKENHUB_IMAGE_TAG=0.7.0
+
+# ---------- 数据卷 ----------
+# 宿主机持久化目录：/data 为应用数据（SQLite 回退/备份/图片），
+# releases 为版本面板在线更新与模型目录
+# 部署前手动创建：mkdir -pv /data/volumes/tokenhub/{data,releases}
+Volumes_Path=/data/volumes/tokenhub
+
+# ---------- 数据库（复用 prod-dbs PostgreSQL）----------
+# 通过外部网络 prod-dbs_default 以 service 名 postgres 访问
+DB_HOST=postgres
+DB_PORT=5432
+DB_NAME=tokenhub
+DB_USER=tokenhub
+DB_PASSWORD=<your-strong-password>
+# 本机无 TLS 的 PG 用 disable
+DB_SSLMODE=disable
+
+# ---------- TokenHub 应用 ----------
+# 运行环境（prod）
+TOKENHUB_ENV=prod
+# 初始 admin 密码：≥12 字节；留占位 change-me-* 则首次启动随机生成
+TOKENHUB_BOOTSTRAP_ADMIN_PASSWORD=<your-admin-password>
+# Admin API 静态 Token：≥32 字节随机值（运维自动化用）；留空/占位则禁用该 Token
+TOKENHUB_ADMIN_TOKEN=
+# 加密根密钥：≥32 字节随机值；PG/已有库必填且不可变更
+TOKENHUB_SECRET_KEY=<your-32-byte-random-secret>
+# 展示给用户的后端访问地址（反向代理/域名场景填 https://xxx，docs 里 server URL 用它）
+TOKENHUB_PUBLIC_BASE_URL=http://localhost:8080
+# 管理后台调用后端的地址（与后台页面不同源时按浏览器可访问地址设置）
+TOKENHUB_API_BASE_URL=http://localhost:8080
+# 允许调用后端的精确浏览器 Origin，逗号分隔（跨源时填写，生产勿用通配符）
+TOKENHUB_CORS_ALLOWED_ORIGINS=http://localhost:3000
+# 可信反向代理 CIDR（透传 X-Forwarded-* 时填写，逗号分隔）
+TOKENHUB_TRUSTED_PROXY_CIDRS=
+# 是否写入演示数据
+TOKENHUB_SEED_DEMO=false
+
+# ---------- 可选高级项（不填用镜像默认值，见官方 docs/zh-CN/deployment.md）----------
+# 内网模型服务放行私网 CIDR（RFC1918/ULA，逗号分隔）
+# TOKENHUB_PROVIDER_UPSTREAM_ALLOWED_CIDRS=172.22.10.0/24
+# 本地 Ollama/LM Studio 放行 loopback（生产勿开）
+# TOKENHUB_PROVIDER_UPSTREAM_ALLOW_LOOPBACK=true
+# Prometheus 指标
+# TOKENHUB_METRICS_ENABLED=true
+# TOKENHUB_METRICS_TOKEN=
+# OpenTelemetry tracing（Langfuse 等）
+# TOKENHUB_TRACING_ENABLED=true
+# TOKENHUB_TRACING_ENDPOINT=https://<langfuse>/api/public/otel/v1/traces
+# 高并发计费准入 Redis（可复用 dbSer Dev-Redis 172.22.10.205）
+# TOKENHUB_BILLING_REDIS_URL=redis://172.22.10.205:6379/0
+# 出站统一代理（Provider 通道）
+# HTTP_PROXY=
+# HTTPS_PROXY=
+# NO_PROXY=
@@ -0,0 +1,91 @@
+# tokenhub
+
+TokenHub（https://github.com/astaxie/TokenHub）企业级 Token Governance 网关部署。
+Go 后端 + Next.js 管理后台，OpenAI / Anthropic 兼容网关（`/v1/*`、`/v1beta/*`），
+提供模型路由、项目级 Key 管理、配额与成本归因、Provider 对账等能力。
+
+官方部署形态：SQLite（默认单容器）或 PostgreSQL（生产/多实例）。本目录按
+`../newapi` / `../mixapi` 的 host 复用惯例，只提供 **复用 prod-dbs PostgreSQL**
+的单容器变体（对应上游 `docker-compose.remote-postgres.yml` 的单实例简化版；
+官方多实例 Nginx + 副本方案见 https://github.com/astaxie/TokenHub/blob/main/docs/zh-CN/deployment.md）。
+
+## 结构
+
+- `stack.host.yml` — 单容器（`tokenhub-host` 项目）：镜像内一体运行
+  后端(:8080) 与 管理后台(:3000)，加入外部网络 `prod-dbs_default` 直连 prod-postgres
+- `env.cfg.example` — 环境变量模板（TOKENHUB_* 官方变量 + DB_* / Volumes_Path 结构变量）
+
+## 前置条件
+
+1. `prod-dbs` 已启动，`docker network ls` 能看到 `prod-dbs_default`；
+2. 在 prod-postgres 上为 tokenhub 建库建号（账号密码与 `env.cfg` 一致）：
+
+```sql
+CREATE USER tokenhub WITH PASSWORD '<strong-password>';
+CREATE DATABASE tokenhub OWNER tokenhub;
+```
+
+## 部署
+
+```bash
+mkdir -pv /data/volumes/tokenhub/{data,releases}
+cp tokenhub/env.cfg.example tokenhub/env.cfg && vim tokenhub/env.cfg
+docker compose -p tokenhub-host --env-file ./tokenhub/env.cfg -f ./tokenhub/stack.host.yml up -d
+docker compose -p tokenhub-host -f ./tokenhub/stack.host.yml ps
+docker compose -p tokenhub-host -f ./tokenhub/stack.host.yml logs -f tokenhub
+```
+
+> `env.cfg` 中 `DB_HOST=postgres` 指 prod-dbs 网络里的 postgres service；
+> 使用其他 PostgreSQL 时改为可达的 host/IP，并把 `DB_SSLMODE` 调整为 `require` 等。
+
+## 首次登录
+
+- 管理后台：`http://<host>:<TOKENHUB_FRONTEND_PORT>`（默认 3000）
+- 后端/网关：`http://<host>:<TOKENHUB_BACKEND_PORT>`（健康检查 `/healthz`、`/livez`、`/readyz`）
+- 用户名：`admin`
+- 密码：`env.cfg` 的 `TOKENHUB_BOOTSTRAP_ADMIN_PASSWORD`；
+  未设置（占位 change-me-*）时自动生成，用下面命令获取（首次登录后即不可再查）：
+
+```bash
+docker compose -p tokenhub-host --env-file ./tokenhub/env.cfg -f ./tokenhub/stack.host.yml \
+  exec tokenhub /opt/tokenhub/current/bin/tokenhub initial-admin-password
+```
+
+登录后应立即修改密码，并在「系统设置」中配置 Provider 渠道、模型目录与路由。
+
+## 关键变量
+
+| 变量 | 默认 | 说明 |
+|------|------|------|
+| `TOKENHUB_IMAGE_TAG` | `0.7.0` | ghcr 镜像纯数字 tag（`0.7`/`latest` 亦可） |
+| `TOKENHUB_FRONTEND_PORT` / `TOKENHUB_BACKEND_PORT` | `3000` / `8080` | 宿主机映射端口，冲突时修改 |
+| `DB_HOST`/`DB_USER`/`DB_PASSWORD`/`DB_NAME`/`DB_SSLMODE` | `postgres`/`tokenhub`/…/`disable` | 拼装 `TOKENHUB_DATABASE_URL` |
+| `TOKENHUB_SECRET_KEY` | — | 加密根密钥，**≥32 字节、不可变更** |
+| `TOKENHUB_ADMIN_TOKEN` | 空 | Admin API 静态 Token（可选，≥32 字节） |
+| `TOKENHUB_PUBLIC_BASE_URL` / `TOKENHUB_API_BASE_URL` | `http://localhost:8080` | 域名/反代场景填浏览器可访问 origin |
+| `TOKENHUB_CORS_ALLOWED_ORIGINS` | `http://localhost:3000` | 精确跨源 Origin 白名单 |
+
+完整变量表与说明见官方部署文档（docs/zh-CN/deployment.md「后端环境变量」一节）。
+
+## 反向代理要点
+
+生产建议 HTTPS，前端流量到 3000，`/api/*`、`/v1/*`、`/v1beta/*`、`/docs`、
+`/openapi.json`、`/openapi.yaml`、`/livez`、`/readyz`、`/healthz` 到 8080；
+长文本/流式响应注意 `client_max_body_size`（≥ `TOKENHUB_MAX_MULTIMODAL_REQUEST_BYTES`）
+与超时设置；代理透传 X-Forwarded-* 时在 `TOKENHUB_TRUSTED_PROXY_CIDRS` 填代理 CIDR。
+
+## 升级与备份
+
+- 版本面板：后台可直接检查并「立即更新/回退」Release（数据入 `releases` 卷，
+  普通重启不丢）；跨大版本先备份数据库，确认目标版本兼容当前库演进；
+- 手工升级：改 `TOKENHUB_IMAGE_TAG` → `docker compose ... up -d`；
+- 备份：prod-postgres 的 `tokenhub` 库（pg_dump）+ `/data/volumes/tokenhub/data`。
+- 本机横向扩容需要多实例（frontend/backend 分容器 + Nginx），请改用官方
+  `docker-compose.remote-postgres.yml`（见官方部署文档），勿多开本单容器副本共享同一后端。
+
+## 停止
+
+```bash
+docker compose -p tokenhub-host -f ./tokenhub/stack.host.yml down
+# 数据在 prod-postgres 与 /data/volumes/tokenhub，down 不删除
+```
@@ -0,0 +1,112 @@
+# path:: mkdir -pv /data/volumes/tokenhub/{data,releases}
+# pull:: docker compose -p tokenhub-host --env-file ./tokenhub/env.cfg -f ./tokenhub/stack.host.yml pull
+# run::  docker compose -p tokenhub-host --env-file ./tokenhub/env.cfg -f ./tokenhub/stack.host.yml up -d
+# disc:: TokenHub（ghcr.io/astaxie/tokenhub-backend）单容器一体部署：
+#        镜像内同时跑 Go 后端(:8080) 与 Next.js 管理后台(:3000)，上游 RUN_MODE=all
+# disc:: 复用 prod-dbs 项目的 prod-postgres（join 外部网络 prod-dbs_default，service 名 postgres）
+# disc:: 需先在 prod-postgres 上建好 tokenhub 库与账号（SQL 模板见 tokenhub/readme.md）
+# disc:: 项目名 tokenhub-host；启动前先 up prod-dbs（确保 prod-dbs_default 网络存在）
+# disc:: 使用 PostgreSQL 时必须设置 TOKENHUB_SECRET_KEY（≥32 字节稳定值，勿变更）
+# disc:: 首次登录 admin：密码为 TOKENHUB_BOOTSTRAP_ADMIN_PASSWORD 或 exec 命令获取（见 readme）
+# disc:: 注意：与 newapi/mixapi 同机时 3000/8080 默认端口会冲突，改 env.cfg 端口即可
+
+services:
+  tokenhub:
+    image: ghcr.io/astaxie/tokenhub-backend:${TOKENHUB_IMAGE_TAG:-latest}
+    container_name: tokenhub_host_app
+    restart: unless-stopped   # 上游约定：版本面板“立即重启”依赖 restart: unless-stopped
+    ports:
+      - "${TOKENHUB_BACKEND_PORT:-8080}:8080"
+      - "${TOKENHUB_FRONTEND_PORT:-3000}:3000"
+    networks:
+      - prod-dbs_default   # 加入 prod-dbs 默认网络，用 service 名 postgres 解析 prod-postgres
+    volumes:
+      - ${Volumes_Path:-/data/volumes/tokenhub}/data:/app/data          # SQLite/备份/生成图片（此处实际存 PG，备 SQLite 回退）
+      - ${Volumes_Path:-/data/volumes/tokenhub}/releases:/opt/tokenhub  # 版本面板在线更新/回退的 Release 与模型目录
+      - /etc/timezone:/etc/timezone:ro
+      - /etc/localtime:/etc/localtime:ro
+    environment:
+      TOKENHUB_ENV: ${TOKENHUB_ENV:-prod}
+      TOKENHUB_DEPLOYMENT_TYPE: container
+      TOKENHUB_MANAGED_UPDATES: "true"
+      TOKENHUB_INSTALL_ROOT: /opt/tokenhub
+      TOKENHUB_RUN_MODE: all
+      TOKENHUB_HTTP_ADDR: :8080
+      TZ: Asia/Shanghai
+      # 复用 prod-postgres：URL 由 DB_* 组装（密码含 @ : / # % 时需 URL 转义；
+      # 后端也支持 TOKENHUB_DB_HOST/DB_USER/DB_PASSWORD/DB_NAME/DB_SSLMODE 拆分字段，可改用之）
+      TOKENHUB_DATABASE_URL: postgresql://${DB_USER:-tokenhub}:${DB_PASSWORD}@${DB_HOST:-postgres}:${DB_PORT:-5432}/${DB_NAME:-tokenhub}?sslmode=${DB_SSLMODE:-disable}
+      TOKENHUB_SQLITE_BACKUP_DIR: /app/data/backups
+      TOKENHUB_MODEL_CATALOG_FILE: /opt/tokenhub/current/catalog/model-catalog.yaml
+      TOKENHUB_PROVIDER_CATALOG_FILE: /opt/tokenhub/current/catalog/provider-catalog.json
+      TOKENHUB_PUBLIC_BASE_URL: ${TOKENHUB_PUBLIC_BASE_URL:-http://localhost:8080}
+      TOKENHUB_API_BASE_URL: ${TOKENHUB_API_BASE_URL:-http://localhost:8080}
+      TOKENHUB_RELEASE_REPOSITORY: ${TOKENHUB_RELEASE_REPOSITORY:-astaxie/TokenHub}
+      TOKENHUB_TRUSTED_PROXY_CIDRS: ${TOKENHUB_TRUSTED_PROXY_CIDRS:-}
+      TOKENHUB_PROVIDER_UPSTREAM_ALLOWED_CIDRS: ${TOKENHUB_PROVIDER_UPSTREAM_ALLOWED_CIDRS:-}
+      TOKENHUB_PROVIDER_UPSTREAM_NAT64_PREFIX: ${TOKENHUB_PROVIDER_UPSTREAM_NAT64_PREFIX:-}
+      TOKENHUB_PROVIDER_UPSTREAM_ALLOW_LOOPBACK: ${TOKENHUB_PROVIDER_UPSTREAM_ALLOW_LOOPBACK:-false}
+      HTTP_PROXY: ${HTTP_PROXY:-}
+      HTTPS_PROXY: ${HTTPS_PROXY:-}
+      NO_PROXY: ${NO_PROXY:-}
+      TOKENHUB_CORS_ALLOWED_ORIGINS: ${TOKENHUB_CORS_ALLOWED_ORIGINS:-http://localhost:3000}
+      TOKENHUB_ADMIN_TOKEN: ${TOKENHUB_ADMIN_TOKEN:-change-me-tokenhub-admin-token}
+      TOKENHUB_BOOTSTRAP_ADMIN_PASSWORD: ${TOKENHUB_BOOTSTRAP_ADMIN_PASSWORD:-change-me-tokenhub-admin-password}
+      TOKENHUB_SECRET_KEY: ${TOKENHUB_SECRET_KEY:-change-me-tokenhub-secret-key}
+      TOKENHUB_SEED_DEMO: ${TOKENHUB_SEED_DEMO:-false}
+      TOKENHUB_RESOURCE_FAILURE_THRESHOLD: ${TOKENHUB_RESOURCE_FAILURE_THRESHOLD:-3}
+      TOKENHUB_RESOURCE_COOLDOWN_SECONDS: ${TOKENHUB_RESOURCE_COOLDOWN_SECONDS:-300}
+      TOKENHUB_RESOURCE_COOLDOWN_MAX_SECONDS: ${TOKENHUB_RESOURCE_COOLDOWN_MAX_SECONDS:-3600}
+      TOKENHUB_METRICS_ENABLED: ${TOKENHUB_METRICS_ENABLED:-false}
+      TOKENHUB_METRICS_TOKEN: ${TOKENHUB_METRICS_TOKEN:-}
+      TOKENHUB_METRICS_PROJECT_LABEL: ${TOKENHUB_METRICS_PROJECT_LABEL:-false}
+      TOKENHUB_TRACING_ENABLED: ${TOKENHUB_TRACING_ENABLED:-false}
+      TOKENHUB_TRACING_ENDPOINT: ${TOKENHUB_TRACING_ENDPOINT:-}
+      TOKENHUB_TRACING_HEADERS: ${TOKENHUB_TRACING_HEADERS:-}
+      TOKENHUB_TRACING_CAPTURE_PAYLOADS: ${TOKENHUB_TRACING_CAPTURE_PAYLOADS:-false}
+      TOKENHUB_TRACING_SAMPLE_RATIO: ${TOKENHUB_TRACING_SAMPLE_RATIO:-1}
+      TOKENHUB_TRACING_TIMEOUT_SECONDS: ${TOKENHUB_TRACING_TIMEOUT_SECONDS:-10}
+      TOKENHUB_TRACING_QUEUE_SIZE: ${TOKENHUB_TRACING_QUEUE_SIZE:-2048}
+      TOKENHUB_UPSTREAM_NON_STREAM_TIMEOUT_SECONDS: ${TOKENHUB_UPSTREAM_NON_STREAM_TIMEOUT_SECONDS:-120}
+      TOKENHUB_UPSTREAM_STREAM_IDLE_TIMEOUT_SECONDS: ${TOKENHUB_UPSTREAM_STREAM_IDLE_TIMEOUT_SECONDS:-300}
+      TOKENHUB_MAX_JSON_REQUEST_BYTES: ${TOKENHUB_MAX_JSON_REQUEST_BYTES:-8388608}
+      TOKENHUB_MAX_MULTIMODAL_REQUEST_BYTES: ${TOKENHUB_MAX_MULTIMODAL_REQUEST_BYTES:-33554432}
+      TOKENHUB_IN_FLIGHT_LEASE_TTL_SECONDS: ${TOKENHUB_IN_FLIGHT_LEASE_TTL_SECONDS:-300}
+      TOKENHUB_CLUSTER_LOCK_TTL_SECONDS: ${TOKENHUB_CLUSTER_LOCK_TTL_SECONDS:-180}
+      # 可选 Redis 计费准入（高并发），复用 dbSer Dev-Redis（172.22.10.205，无密码）示例：
+      # TOKENHUB_BILLING_REDIS_URL: redis://172.22.10.205:6379/0
+      TOKENHUB_BILLING_REDIS_URL: ${TOKENHUB_BILLING_REDIS_URL:-}
+      TOKENHUB_GRACEFUL_SHUTDOWN_SECONDS: ${TOKENHUB_GRACEFUL_SHUTDOWN_SECONDS:-150}
+      TOKENHUB_IMAGE_WORKER_CONCURRENCY: ${TOKENHUB_IMAGE_WORKER_CONCURRENCY:-2}
+      TOKENHUB_RESPONSE_WORKER_CONCURRENCY: ${TOKENHUB_RESPONSE_WORKER_CONCURRENCY:-2}
+      TOKENHUB_RESPONSE_POLL_INTERVAL_MILLIS: ${TOKENHUB_RESPONSE_POLL_INTERVAL_MILLIS:-250}
+      TOKENHUB_RESPONSE_JOB_TIMEOUT_SECONDS: ${TOKENHUB_RESPONSE_JOB_TIMEOUT_SECONDS:-300}
+      TOKENHUB_RESPONSE_LEASE_TTL_SECONDS: ${TOKENHUB_RESPONSE_LEASE_TTL_SECONDS:-30}
+      TOKENHUB_RESPONSE_RESULT_TTL_SECONDS: ${TOKENHUB_RESPONSE_RESULT_TTL_SECONDS:-3600}
+      TOKENHUB_RESPONSE_MAX_QUEUED_JOBS: ${TOKENHUB_RESPONSE_MAX_QUEUED_JOBS:-1000}
+      TOKENHUB_CACHE_AFFINITY_ENABLED: ${TOKENHUB_CACHE_AFFINITY_ENABLED:-false}
+      TOKENHUB_CACHE_AFFINITY_MODELS: ${TOKENHUB_CACHE_AFFINITY_MODELS:-}
+      TOKENHUB_CACHE_AFFINITY_ALLOW_USER_SCOPE: ${TOKENHUB_CACHE_AFFINITY_ALLOW_USER_SCOPE:-false}
+      TOKENHUB_GUARDRAIL_MODEL_URL: ${TOKENHUB_GUARDRAIL_MODEL_URL:-}
+      TOKENHUB_GUARDRAIL_MODEL_API_KEY: ${TOKENHUB_GUARDRAIL_MODEL_API_KEY:-}
+      TOKENHUB_GUARDRAIL_MODEL_NAME: ${TOKENHUB_GUARDRAIL_MODEL_NAME:-Qwen/Qwen3Guard-Gen-0.6B}
+      TOKENHUB_GUARDRAIL_MODEL_TIMEOUT_SECONDS: ${TOKENHUB_GUARDRAIL_MODEL_TIMEOUT_SECONDS:-10}
+      TOKENHUB_FRONTEND_HOST: 0.0.0.0
+      TOKENHUB_FRONTEND_PORT: 3000
+    healthcheck:
+      test:
+        - CMD
+        - node
+        - -e
+        - Promise.all([fetch('http://127.0.0.1:8080/healthz'),fetch('http://127.0.0.1:3000')]).then(rs=>process.exit(rs.every(r=>r.ok)?0:1)).catch(()=>process.exit(1))
+      interval: 10s
+      timeout: 5s
+      retries: 12
+      start_period: 20s
+    stop_grace_period: ${TOKENHUB_STOP_GRACE_PERIOD:-180s}
+
+networks:
+  prod-dbs_default:
+    # 引用 prod-dbs 项目自动创建的默认网络，不归本 compose 管
+    external: true
+    name: prod-dbs_default