deploy.stack/tokenhub

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 一致）：

CREATE USER tokenhub WITH PASSWORD '<strong-password>';
CREATE DATABASE tokenhub OWNER tokenhub;

部署

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-*）时自动生成，用下面命令获取（首次登录后即不可再查）：

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（见官方部署文档），勿多开本单容器副本共享同一后端。

停止

docker compose -p tokenhub-host -f ./tokenhub/stack.host.yml down
# 数据在 prod-postgres 与 /data/volumes/tokenhub，down 不删除