deploy.stack/tokenhub/readme.md

# 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 不删除
```