Skip to content

TokenRouter 0.6.3

Choose a tag to compare

View all tags
@github-actions github-actions released this 05 Nov 10:00
· 43 commits to main since this release
v0.6.3
597b46d

TokenRouter 0.6.3 introduces versioned configuration with automatic migration and personal balance recharge rates; review the configuration and payment rollback requirements before upgrading.

Upgrade notes

  • Upgrade the frontend and backend together after backing up the database and configuration and verifying recovery. Migration 308 adds the nullable users.balance_recharge_multiplier column. Existing users retain NULL and continue using the global recharge rate. After personal rates are configured, stop recharge entry points and reconcile the displayed terms before rolling back: older binaries ignore these overrides and use the global rate for new orders. Keep the added column and existing order data.
  • Configuration now uses config_version: 2. Files without a version are treated as v1 and upgraded on first startup. The migration imports the environment visible at that time, renames and groups settings by module, converts units, and removes obsolete or previously ignored keys. Run this first migration with the original deployment environment before replacing Compose or Apple Container launch templates, or use the offline command with that environment. The new templates no longer forward most legacy application variables.
  • Existing configuration is backed up byte for byte as config.yaml.v1.bak, with a UTC timestamp when that name already exists. Backups use mode 0600; the upgraded file keeps its permissions. Current v2 files are not rewritten. Read-only legacy mounts require ./tokenrouter -migrate-config -config /path/config.yaml -out /writable/config.v2.yaml, followed by replacing the mounted file. -out - writes to stdout. Before reverting the binary, stop the new process and restore the original configuration and deployment environment: old binaries do not understand v2 keys or ${VAR} references.
  • Normal v2 loading uses YAML values over code defaults. Environment values participate only through explicit ${NAME} references; ${NAME:-default} supplies a fallback and $${ escapes a literal opening. Keep every referenced variable available, including imported OAuth secrets, signing keys, updater tokens and proxy credentials. Custom references need explicit container forwarding. Unreferenced legacy application variables produce a warning naming the variables. Paths, setup inputs and standard runtime variables retain their documented roles; timezone controls the application's timezone after installation.
  • Unknown, retired or misspelled v2 keys and unsupported future configuration versions stop startup. Old aliases are handled only during v1 migration. Important paths include auth.jwt, auth.oauth, security.secret_encryption_key, server.client_ip, gateway.openai, scheduling, provider, usage, model_catalog and storage.dir. Scheduling durations become whole seconds, rounded upward when needed; JWT hours and minute overrides become auth.jwt.access_token_ttl_minutes, and the OpenAI proxy circuit uses an enabled flag. See the v2 example and configuration migration guide.
  • Automatic discovery no longer accepts /etc/sub2api/config.yaml by itself. Move it to /etc/tokenrouter/config.yaml or select the original path explicitly with CONFIG_FILE.
  • Fresh Compose installations use code defaults of 256 maximum database connections, 128 idle database connections and 128 minimum idle Redis connections. The global OpenAI compact-model override is empty instead of the old template's gpt-5.4. Existing values are imported when present during the first migration. Development Compose also stops supplying a fixed Vertex project and bucket; configure your own under batch_image.vertex when needed.
  • ALIPAY_MOBILE_PRECREATE_DEEP_LINK no longer overrides the saved payment setting; review that setting in the administrator interface. The ineffective GEMINI_CLI_OAUTH_CLIENT_SECRET override is removed. The retired security.proxy_probe.insecure_skip_verify option is removed during migration; setting it to true previously prevented probes, and probes now use certificate verification.
  • If an earlier source build already produced a v2 file, compare server.mode and WeChat login choices with its v1 backup where legacy null values or numeric flags were involved. For Apple Container, check that database.host and redis.host use ${DATABASE_HOST} and ${REDIS_HOST} when dependency addresses can change. Existing v2 files with literal addresses need a manual edit after backup.

New features

  • Administrators can set a finite positive personal balance recharge multiplier in the user editor or through the administrator API and MCP users.update. The value replaces the global multiplier for new balance orders, including values below or equal to the global rate. Omitting the update field preserves it; sending null restores inheritance. Ordinary profile updates cannot change it.
  • The administrator user table includes a personal recharge-rate column with numeric sorting before pagination; unset values stay last in either direction. Checkout reports the global, personal and effective rates and displays the credited amount even for a personal rate of 1. A different global rate is crossed out beside the personal rate; equal values are not repeated. Fees, principal limits, subscriptions, redemption codes and manual adjustments keep their existing rules. Orders retain their credited-amount snapshot for fulfillment and proportional refunds after rates change.
  • Versioned YAML supports automatic upgrades with preserved setting comments, explicit environment references and an offline migration command. Legacy aliases, null defaults, literal dotted keys, YAML merge precedence, OIDC security flags, WeChat credential modes and historical catalog paths are handled during migration. Required missing variables and invalid current-schema input return configuration errors without printing resolved reference values. Writable single-file mounts have an in-place write fallback; configuration symlinks remain intact, and stale temporary files from an interrupted process do not block another attempt.

Improvements

  • New setup writes v2 configuration and persists a generated encryption key when none is supplied, so later starts reuse the installation's key. Automatic setup keeps supplied credentials and nonempty database/Redis hosts as environment references; recreated dependency containers can provide their new addresses. Manual setup preserves literal input, including text that resembles reference syntax.
  • Provider CLI identities, Grok OAuth endpoints and CAPTCHA credentials, Antigravity endpoint selection and cooldown, updater authentication, payment resume signing, request diagnostics and Ops WebSocket policy now use explicit process configuration. They take effect at startup; existing database settings retain their separate runtime override rules.
  • Compose application health checks use a 120-second startup grace period. Bundled PostgreSQL variants require both pg_isready and a successful SQL query, with a 60-second grace period and 18 retries, giving database recovery and application initialization time to finish.
  • Release archives carry an explicit set of deployment files and exclude development Compose, build helpers, the container entrypoint and test fixtures. The redundant deploy/Dockerfile and the already-retired data-management daemon's installer and service template are removed. Source builds use the repository-root Dockerfile; legacy daemon deployments can consult the retirement notes.
  • Linux installer prompts and messages now use English without a language-selection step. Deployment documentation and script comments use English, and deploy/README.md lists the supported deployment entry points.

Bug fixes

  • Checkout rejects unsupported order types before saving an order or creating a channel payment. Only balance and subscription are accepted; omitted or empty types default to balance. Invalid values return HTTP 400 with INVALID_CHECKOUT_ORDER_TYPE.
  • Balance orders reject credited amounts that round to zero, are nonfinite or reach 1,000,000,000,000 before persistence or payment creation. Valid rounded credits must be at least 0.01 and below that ceiling. The API returns HTTP 400 with INVALID_CREDITED_AMOUNT, and the recharge page disables payment submission for these previews.
  • Recharge previews use decimal multiplication and half-up rounding to two places, matching backend calculations at half-cent boundaries instead of understating credits because of binary floating-point multiplication.
  • Setup recognizes the same explicit and conventional configuration paths as normal startup, preventing an existing configuration outside the data directory from reopening the installation wizard.
  • Ops WebSocket connection limits are validated before conversion to 32-bit counters, preventing large positive values from wrapping into nonpositive limits. Invalid proxy addresses and origin policies are rejected during startup.

📥 Installation

Docker:

# GitHub Container Registry
docker pull ghcr.io/tokenflux/tokenrouter:0.6.3

One-line install (Linux):

curl -sSL https://raw.githubusercontent.com/TokenFlux/TokenRouter/main/deploy/install.sh | sudo bash

Manual download:
Download the appropriate archive for your platform from the assets below.

📚 Documentation

中文翻译

TokenRouter 0.6.3 引入支持自动迁移的版本化配置和用户专属余额充值倍率；升级前请阅读配置及支付回退要求。

升级说明

  • 备份数据库和配置并验证恢复后，同步升级前后端。迁移 308 增加可空的 users.balance_recharge_multiplier 列。现有用户保留 NULL，继续使用全局充值倍率。设置专属倍率后，如需回退，请先停止充值入口并核对展示条款：旧二进制会忽略这些覆盖值，新订单采用全局倍率。保留新增列和原有订单数据。
  • 配置现在使用 config_version: 2。没有版本号的文件视为 v1，在首次启动时升级。迁移会导入当时可见的环境变量，按模块重命名和归并设置、转换单位，并移除失效或此前被忽略的键。请保留原部署环境完成首次迁移，再替换 Compose 或 Apple Container 启动模板；也可以在原环境下使用离线命令。新模板不再传递大多数旧应用变量。
  • 原配置会逐字节备份为 config.yaml.v1.bak；同名备份已存在时使用带 UTC 时间戳的名称。备份权限为 0600，升级后的文件保留原权限。已有 v2 文件不会重写。只读的旧配置挂载需先执行 ./tokenrouter -migrate-config -config /path/config.yaml -out /writable/config.v2.yaml，再替换挂载文件。-out - 输出到 stdout。回退二进制前，停止新进程并恢复原配置及部署环境；旧二进制不认识 v2 键名和 ${VAR} 引用。
  • v2 常规加载以 YAML 值优先于代码默认值。环境变量仅通过显式 ${NAME} 引用参与加载；${NAME:-default} 提供默认文本，$${ 转义为字面量开头。请保留所有被引用的变量，包括迁移导入的 OAuth secret、签名密钥、更新令牌和代理凭据。自定义引用需要在容器中显式传递。未被引用的旧应用变量会触发仅列出变量名的警告。路径、安装输入和标准运行时变量继续承担文档规定的用途；安装后应用时区由 timezone 控制。
  • v2 中的未知键、失效键、拼写错误，以及不受支持的未来配置版本都会阻止启动。旧别名仅在 v1 迁移期间处理。主要路径包括 auth.jwt、auth.oauth、security.secret_encryption_key、server.client_ip、gateway.openai、scheduling、provider、usage、model_catalog 和 storage.dir。调度时长改为整秒，必要时向上取整；JWT 的小时值及分钟覆盖值合并为 auth.jwt.access_token_ttl_minutes；OpenAI 代理熔断器改用 enabled 开关。详见 v2 配置示例和配置迁移指南。
  • 自动查找不再单独接受 /etc/sub2api/config.yaml。请将其移至 /etc/tokenrouter/config.yaml，或通过 CONFIG_FILE 明确指定原路径。
  • 全新 Compose 安装采用代码默认值：数据库最大连接数 256、空闲连接数 128、Redis 最小空闲连接数 128。全局 OpenAI compact-model 覆盖为空，不再使用旧模板中的 gpt-5.4。首次迁移时存在的旧值会被导入。开发 Compose 也不再提供固定的 Vertex 项目和存储桶；需要时请在 batch_image.vertex 下配置自己的资源。
  • ALIPAY_MOBILE_PRECREATE_DEEP_LINK 不再覆盖已保存的支付设置，请在管理界面核对该设置。移除原本无效的 GEMINI_CLI_OAUTH_CLIENT_SECRET 覆盖。迁移会移除已停用的 security.proxy_probe.insecure_skip_verify 选项；此前将它设为 true 会导致探测失败，现在探测使用证书验证。
  • 如果此前的源码构建已经生成 v2 文件，且旧配置涉及空值或数字开关，请对照 v1 备份核对 server.mode 和微信登录渠道。Apple Container 的依赖地址可能变化时，请检查 database.host 和 redis.host 是否使用 ${DATABASE_HOST}、${REDIS_HOST}。已有 v2 文件中的字面量地址需在备份后手动修改。

新功能

  • 管理员可在用户编辑器中，或通过管理员 API、MCP users.update 设置大于零的有限专属余额充值倍率。该值替代新余额订单使用的全局倍率，允许低于或等于全局值。更新时省略字段保留原值，发送 null 恢复继承。普通用户资料更新不能修改该字段。
  • 管理员用户表增加专属充值倍率列，支持在分页前按数值排序；两个排序方向均将未设置值放在末尾。充值页返回全局、专属和实际倍率，即使专属倍率为 1 也显示到账金额。全局值不同时，在专属倍率旁以删除线展示全局值；相同值不重复显示。手续费、本金限额、订阅、兑换码和人工调账保留原规则。倍率变化后，订单仍使用已保存的到账金额快照进行履约和按比例退款。
  • 版本化 YAML 支持保留设置注释的自动升级、显式环境引用及离线迁移命令。迁移会处理旧别名、空值默认行为、字面点分键、YAML 合并优先级、OIDC 安全开关、微信凭据渠道和历史模型目录路径。缺失必要变量或当前配置结构无效时会返回配置错误，不打印引用解析后的值。可写的单文件挂载支持原地写入回退；配置符号链接保持不变，进程中断遗留的临时文件不会阻止下一次尝试。

改进

  • 新安装写入 v2 配置，未提供加密密钥时生成并持久保存密钥，后续启动沿用安装时的值。自动安装将提供的凭据以及非空的数据库、Redis 主机地址保留为环境引用，依赖容器重建后可提供新地址。手动安装保留字面量输入，包括类似引用语法的文本。
  • 提供商 CLI 身份、Grok OAuth 端点及验证码凭据、Antigravity 端点选择和冷却时间、更新认证、支付续接签名、请求诊断及 Ops WebSocket 策略现在使用显式进程配置，在启动时生效；现有数据库设置保留各自的运行时覆盖规则。
  • Compose 应用健康检查采用 120 秒启动宽限期。内置 PostgreSQL 的编排同时要求 pg_isready 和 SQL 查询成功，并采用 60 秒宽限期、18 次重试，为数据库恢复和应用初始化留出时间。
  • 发布归档按明确清单包含部署文件，排除开发 Compose、构建辅助脚本、容器入口和测试夹具。移除重复的 deploy/Dockerfile，以及此前已停用的数据管理守护进程的安装脚本和服务模板。源码构建使用仓库根目录的 Dockerfile；遗留守护进程部署可参考停用说明。
  • Linux 安装器的提示和消息统一使用英文，移除语言选择步骤。部署文档和脚本注释使用英文，deploy/README.md 列出支持的部署入口。

问题修复

  • 下单在保存订单或创建渠道支付前拒绝不支持的订单类型。仅接受 balance 和 subscription；省略或空类型默认使用 balance。无效值返回 HTTP 400 和 INVALID_CHECKOUT_ORDER_TYPE。
  • 余额订单在持久化或创建支付前，拒绝舍入为零、非有限值或达到 1,000,000,000,000 的到账金额。有效的舍入结果必须至少为 0.01，且低于该上限。API 返回 HTTP 400 和 INVALID_CREDITED_AMOUNT，充值页也会禁止提交这类预览对应的支付。
  • 充值预览采用十进制乘法并四舍五入到两位小数，在半分边界与后端计算一致，避免二进制浮点乘法导致预览到账金额偏低。
  • 安装流程与正常启动采用相同的显式及约定配置路径，避免数据目录之外已存在配置时重新开放安装向导。
  • Ops WebSocket 连接数限制在转换为 32 位计数器前校验，避免较大的正数溢出为非正数限制。无效的代理地址和 Origin 策略在启动时拒绝。

📥 安装

Docker：

# GitHub Container Registry
docker pull ghcr.io/tokenflux/tokenrouter:0.6.3

一键安装（Linux）：

curl -sSL https://raw.githubusercontent.com/TokenFlux/TokenRouter/main/deploy/install.sh | sudo bash

手动下载：
从下方附件中下载适合当前平台的归档。

📚 文档

Assets 8
Loading