forked from DevOps/deploy.stack
cnphpbb
1155c1b7a0
- 单容器一体部署（后端 8080 + 管理后台 3000）join prod-dbs_default 直连 prod-postgres - env.cfg.example 模板与 readme（建库/登录/反向代理/升级备份说明）
92 lines
4.5 KiB
Markdown
92 lines
4.5 KiB
Markdown
# 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 不删除
|
||
```
|