跳转到内容
Halro Docsv0.9.1
v0.9.1正式版

v0.8.5 → v0.9.0 升级与 v0.9.1 补丁

从 v0.8.5 升级到 v0.9.0 的主要变化是：配置结构升级、账务与用量历史改为有界内存和磁盘索引、 按拒绝原因暂停路由、公开别名发现，以及 Chat/Embeddings 幂等保护。当前文档以 v0.9.1 为核对基线； 从 v0.8.5 直接升级到 v0.9.1，同样要完成下面的迁移。

升级步骤

Section titled “升级步骤”
  1. 使用 halro version 确认当前版本，保存 v0.8.5 二进制及配置。停止服务，确认数据目录锁已释放。
  2. 用 v0.8.5 创建并校验备份，按备份与恢复分开保存 .hmbk、 Backup Key 和 Master Key/KMS 恢复材料。
  3. 核验新版本下载的签名与校验和。以下 ./halro 指新二进制；把配置路径替换为该实例实际路径。
Terminal window
./halro version
./halro config migrate --config /etc/halro/config.yaml
./halro config migrate --config /etc/halro/config.yaml --write

第一条迁移命令只预览，不写文件。--write 应用编辑，并保留 /etc/halro/config.yaml.before-migrate。迁移会把 version: 1 改为 2，把退役字段移动到替代字段； 不会替你改掉已设置的值，不会自动在启动时执行。语义发生变化的老字段会被拒绝，需按提示人工处理。

  1. 显式检查 Ledger 封存与尝试预算。旧配置通常保留关闭的封存、8 GiB 阈值以及 3 / 2 的尝试预算， 迁移命令会保留这些值。按下面的表选择适合实例的设置，再执行校验：
Terminal window
./halro config check --config /etc/halro/config.yaml
  1. 启动一个新版本实例，检查 /health/live、/health/ready、日志和 Admin 系统状态。首次启动先从 Ledger 重建账务状态，再在后台建立用量索引。升级前运行新版本 doctor 看到 schema 38/41 不匹配 是因为它只读、不做迁移；应先完成首次启动，再停机运行离线检查。
  2. 在维护窗口停止服务，用新版本执行 halro doctor、halro ledger verify、halro audit verify 和 halro usage verify（都指定同一个 --config），然后重新启动。等待 Usage 索引追平； readiness 成功本身不证明历史索引已经完整。按实例验收流程检查调用、流式响应和费用结算， 真实 Provider 验收会产生调用和可能的费用。

参数变化

Section titled “参数变化”
参数变化
参数v0.8.5v0.9.0 / v0.9.1
version12；旧结构必须先迁移
circuit_breaker.consecutive_failures旧字段routing.availability_failures，默认 5
circuit_breaker.open_duration旧字段routing.suspend_for，默认 30s
circuit_breaker.half_open_max_requests旧字段routing.probe_requests，默认 1
routing.max_suspend_for无新增，默认 5m；不得短于 suspend_for
gateway.max_total_attempts默认 3默认 4
retry.max_attempts_per_target默认 2默认 1，包含第一次尝试
ledger.seal.enabled默认 false默认 true；旧文件需显式修改
ledger.seal.max_active_bytes默认 8589934592（8 GiB）默认 268435456（256 MiB）
ledger.max_hot_state_bytes无新增，默认 134217728（128 MiB），范围 16 MiB–4 GiB
usage.console_window_days内存历史窗口仅列表默认日期范围，默认 30，最小 7；缩短不删历史
provider_subscriptions.anthropic_claude无新增，默认 false；显式开放 Claude 订阅产品

退役的 providers 配置段也会被拒绝；连接信息归 Admin 管理的 Credential 所有。更早配置中的 elevation_window 不能直接继承到 admin.reauth_elevation_window，因为权限覆盖范围改变。 完整参数与重载边界见配置参考。

功能与调用变化

Section titled “功能与调用变化”
功能与调用变化
变化应用或管理员需要做什么
模型发现（experimental）GET /v1/models 和 GET /v1/models/{id} 返回当前 Project 可见的公开别名；Key 需同时有 inference、discovery
Chat / Embeddings 幂等Idempotency-Key 防止重复调用上游，但不重放响应；重复返回 409，记录保留 24 小时
路由准入与暂停识别失效凭据、额度等拒绝，符合条件时回退；长期暂停跨重启保存，可审计清除
固定的本地请求限流发现与资源接口受每 Key 600 次/分钟、每 Project 5,000 次/分钟限制，不能用 Project RPM=0 关闭
Provider 产品隔离Kimi Code 与 Claude 订阅使用各自的 Offering、Profile 和 Credential；不会因共享协议自动混用余额
Admin Advisor在线诊断与离线 doctor 检查超时、尝试预算、fallback 扇出与暂停；离线无法读取的运行态标记 unknown
Console 操作路由按公开别名分组，可复制并带入工作台；工作台显示费用和 Project，Providers 页面显示拒绝原因与凭据修订

已有 Key 不会自动获得 discovery；CLI halro key create 仍签发仅有 inference 的 Key。 首次初始化的 bootstrap Key 显式带 discovery。管理员可在 Key 对话框或 Admin API 中选择 Scope。

详细任务说明见模型发现、重试与幂等、 路由暂停与恢复和Provider 产品与订阅边界。

存储、内存与监控

Section titled “存储、内存与监控”

已结算的账务状态不再永久留在内存；启动可使用绑定 Ledger 链头的认证快照，快照不匹配时从 WAL 重建。 已结束 Work Unit、Run 和 Outcome 进入 data/history/archive.db，用量明细进入 data/history/history.db。两者是可从权威 Ledger / Governance journal 重建的派生索引。

ledger.max_hot_state_bytes 限制的是账务热状态估计值。达到上限时，新请求、Work Unit 和 Run 返回 503 accounting_capacity_exhausted 与 Retry-After，已准入工作继续结算；被该限制挡住的 后台 Response 回队列等待。它不是进程内存上限：快照写入在发布测量中达到约 6.2 倍状态大小， 默认设置约需 800 MiB 堆内存余量，还需为进程其他部分与容器开销留空间。

磁盘需求反而增加：发布测量中 history.db 约 5.75 KB/请求，实际容量取决于工作负载。 目前没有自动过期历史行；usage.retention_days 仅限制分析导出分区，不删除 Ledger 或 history.db。不要通过缩短控制台窗口期待释放磁盘。

监控需要迁移：

  • halro_usage_window_*、halro_usage_checkpoint_* 改为 halro_usage_history_*，监控构建状态、 水位、待写记录和失败；每小时对超过 48 小时且无 open lease 的记账日做 Ledger 对账。
  • 新增热状态容量、路由暂停与上游拒绝原因信号；新增 Project/Run 预算拒绝、Provider spend 缺失、 Admin Audit intent 积压与投递故障告警。
  • 流式首响应字节时间与总延迟分开统计。HALRO_PPROF_LISTEN=127.0.0.1:6060 可显式开启本机 Go profile 监听；默认关闭，不可监听非回环地址。

错误处理新增 all_candidates_suspended（503）、accounting_capacity_exhausted（503）与幂等 409。 上游响应头超时现在返回 504 provider_timeout。失效凭据暂停不带 Retry-After，需要管理员修复。 见错误码和日常运维。

同期行为修复

Section titled “同期行为修复”

慢磁盘写入和并发价格选择不再被误判为时钟回退而隔离 Deployment；真实时钟异常仍会保护性拒绝。 已经进入 wall_clock_* 定价隔离的旧 Deployment 不会由本次升级自动恢复，此版本没有解除该类隔离的 管理动作，需要替换 Deployment；恢复确认只处理 restored_* 隔离。

后台 Response 在 Project 限流/并发或热状态容量处、写入 Ledger 之前被拒绝并回队列时，撤回本次 Token Guard 准入及相应 TPM 占用，避免多次出队重复消耗额度。它不改变已经触达上游的失败结算语义。

v0.9.1 补丁边界

Section titled “v0.9.1 补丁边界”

v0.9.1 不再升级配置或磁盘格式。它在每小时维护时、没有读写事务占用文件的情况下重新打开 history.db 和 archive.db，回收 bbolt freelist 累积的内存。重新打开失败会记录错误，历史写入 暂停，按分钟重试；成功后从 Ledger 追平。该补丁不提供历史清理或通用的进程内存上限。

从 v0.9.0 升级只需按正常备份与验证流程进行；从 v0.8.5 升级仍必须完成本页迁移。 发布依据：v0.9.0 变更记录、 v0.9.1 发布说明。