From 1155c1b7a0f2da7713a05cf0676f0eb4c5e8db3a Mon Sep 17 00:00:00 2001 From: cnphpbb Date: Thu, 3 Sep 2026 22:23:45 +0800 Subject: [PATCH] =?UTF-8?q?feat(tokenhub):=20=E6=B7=BB=E5=8A=A0=E5=A4=8D?= =?UTF-8?q?=E7=94=A8=20prod-dbs=20=E7=9A=84=E9=83=A8=E7=BD=B2=E9=85=8D?= =?UTF-8?q?=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 单容器一体部署（后端 8080 + 管理后台 3000）join prod-dbs_default 直连 prod-postgres - env.cfg.example 模板与 readme（建库/登录/反向代理/升级备份说明） --- tokenhub/env.cfg.example | 85 +++++++++++++++++++++++++++++ tokenhub/readme.md | 91 +++++++++++++++++++++++++++++++ tokenhub/stack.host.yml | 112 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 288 insertions(+) create mode 100644 tokenhub/env.cfg.example create mode 100644 tokenhub/readme.md create mode 100644 tokenhub/stack.host.yml diff --git a/tokenhub/env.cfg.example b/tokenhub/env.cfg.example new file mode 100644 index 0000000..c695bba --- /dev/null +++ b/tokenhub/env.cfg.example @@ -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= +# 本机无 TLS 的 PG 用 disable +DB_SSLMODE=disable + +# ---------- TokenHub 应用 ---------- +# 运行环境（prod） +TOKENHUB_ENV=prod +# 初始 admin 密码：≥12 字节；留占位 change-me-* 则首次启动随机生成 +TOKENHUB_BOOTSTRAP_ADMIN_PASSWORD= +# Admin API 静态 Token：≥32 字节随机值（运维自动化用）；留空/占位则禁用该 Token +TOKENHUB_ADMIN_TOKEN= +# 加密根密钥：≥32 字节随机值；PG/已有库必填且不可变更 +TOKENHUB_SECRET_KEY= +# 展示给用户的后端访问地址（反向代理/域名场景填 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:///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= diff --git a/tokenhub/readme.md b/tokenhub/readme.md new file mode 100644 index 0000000..46187aa --- /dev/null +++ b/tokenhub/readme.md @@ -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 ''; +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://:`（默认 3000） +- 后端/网关：`http://:`（健康检查 `/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 不删除 +``` diff --git a/tokenhub/stack.host.yml b/tokenhub/stack.host.yml new file mode 100644 index 0000000..642fa66 --- /dev/null +++ b/tokenhub/stack.host.yml @@ -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