aether-hub/README.md

# aether-hub

`aether-hub` 是 Tunnel Hub 服务，负责在 proxy 与 worker 之间路由帧。

已集成在Docker镜像中, 无需单独部署。

## 部署端指定 Hub 版本并构建

```bash
cd /path/to/Aether
./deploy.sh --hub-tag hub-v0.1.0
```

不指定 `--hub-tag` 时，`./deploy.sh` 会自动解析最新 `hub-v*` release，并在构建 app 镜像时从 GitHub Release 下载对应架构的 Hub 二进制。

## build.sh 模式说明

- 默认是 `binary` 模式（`cross` 构建二进制）。
- `--upload <hub-vX.Y.Z>` 会把构建产物上传到 GitHub Release。
- 加 `--image` 后进入镜像模式（`docker buildx`，可选）。

常用参数：

- `--tag <tag>`: 镜像 tag
- `--image-name <name>`: 镜像名（默认 `ghcr.io/fawney19/aether-hub`）
- `--platforms <list>`: 例如 `linux/amd64,linux/arm64`
- `--push`: 推送镜像
- `--load`: 加载到本地 Docker（单平台）
- `--latest`: 额外打 `latest` tag

## 运行时参数

- `TUNNEL_HUB_WORKER_IDLE_TIMEOUT`：worker 心跳空闲超时，默认 `60` 秒
- `TUNNEL_HUB_OUTBOUND_QUEUE_CAPACITY`：单连接出站队列容量，默认 `128`；队列打满时会把连接视为拥塞并主动关闭，避免 Hub 内存无限增长

## 与部署脚本关系

- `./deploy.sh`: 本地构建部署（会本地构建 app/base，并在构建 app 时从 GitHub Release 下载 Hub，可用 `--hub-tag` 固定版本）。
-												refactor: Hub二进制改为Docker构建时下载，优化部署流程与worker初始化

- Dockerfile: 移除COPY预编译二进制，改为构建时通过HUB_TAG从GitHub Release下载
- CI: 移除artifact上传/下载步骤，通过build-args传递Hub tag
- deploy.sh: 重构参数解析，支持--hub-tag指定版本，跟踪tag变化触发重建
- build.sh: 新增--image模式支持构建并推送Hub Docker镜像
- hub.rs: worker连接时同步所有节点在线状态，避免状态不一致
- proxy_nodes: 启动时主动建立Hub worker连接，消除懒连接窗口期
- docker-compose.yml: app镜像支持APP_IMAGE环境变量配置
- README: 更新部署文档，推荐本地构建方式

											
										
										
											2026-03-02 11:24:14 +08:00
+								# aether-hub
 								`aether-hub` 是 Tunnel Hub 服务，负责在 proxy 与 worker 之间路由帧。
-												feat(test,quota,failover): 模型并发测试、统一配额读取器与故障转移取消支持

- 新增 QuotaReader 抽象层，统一 Codex/Kiro/Antigravity 配额解析逻辑，
  替换 pool/routes.py 中分散的配额构建函数
- 模型测试支持并发执行多候选，前端新增 useModelTest composable 统一
  ModelsTab 和 ModelMappingTab 的测试逻辑
- ModelTestDialog 增加结果概览摘要、超长结果折叠、端点列和新状态支持，
  删除已合并的 TestResultDialog
- FailoverEngine 新增客户端断开检测，支持取消剩余候选并标记记录
- 刷新配额改为分批执行，直连测试候选按可用性排序
- 修复 error 判断从 "error" in dict 改为 dict.get("error") 避免误判

											
										
										
											2026-03-07 02:16:03 +08:00
+								已集成在Docker镜像中, 无需单独部署。
-												refactor: Hub二进制改为Docker构建时下载，优化部署流程与worker初始化

- Dockerfile: 移除COPY预编译二进制，改为构建时通过HUB_TAG从GitHub Release下载
- CI: 移除artifact上传/下载步骤，通过build-args传递Hub tag
- deploy.sh: 重构参数解析，支持--hub-tag指定版本，跟踪tag变化触发重建
- build.sh: 新增--image模式支持构建并推送Hub Docker镜像
- hub.rs: worker连接时同步所有节点在线状态，避免状态不一致
- proxy_nodes: 启动时主动建立Hub worker连接，消除懒连接窗口期
- docker-compose.yml: app镜像支持APP_IMAGE环境变量配置
- README: 更新部署文档，推荐本地构建方式

											
										
										
											2026-03-02 11:24:14 +08:00
-												feat(test,quota,failover): 模型并发测试、统一配额读取器与故障转移取消支持

- 新增 QuotaReader 抽象层，统一 Codex/Kiro/Antigravity 配额解析逻辑，
  替换 pool/routes.py 中分散的配额构建函数
- 模型测试支持并发执行多候选，前端新增 useModelTest composable 统一
  ModelsTab 和 ModelMappingTab 的测试逻辑
- ModelTestDialog 增加结果概览摘要、超长结果折叠、端点列和新状态支持，
  删除已合并的 TestResultDialog
- FailoverEngine 新增客户端断开检测，支持取消剩余候选并标记记录
- 刷新配额改为分批执行，直连测试候选按可用性排序
- 修复 error 判断从 "error" in dict 改为 dict.get("error") 避免误判

											
										
										
											2026-03-07 02:16:03 +08:00
+								## 部署端指定 Hub 版本并构建
-												refactor: Hub二进制改为Docker构建时下载，优化部署流程与worker初始化

- Dockerfile: 移除COPY预编译二进制，改为构建时通过HUB_TAG从GitHub Release下载
- CI: 移除artifact上传/下载步骤，通过build-args传递Hub tag
- deploy.sh: 重构参数解析，支持--hub-tag指定版本，跟踪tag变化触发重建
- build.sh: 新增--image模式支持构建并推送Hub Docker镜像
- hub.rs: worker连接时同步所有节点在线状态，避免状态不一致
- proxy_nodes: 启动时主动建立Hub worker连接，消除懒连接窗口期
- docker-compose.yml: app镜像支持APP_IMAGE环境变量配置
- README: 更新部署文档，推荐本地构建方式

											
										
										
											2026-03-02 11:24:14 +08:00
 								```bash
 								cd /path/to/Aether
 								./deploy.sh --hub-tag hub-v0.1.0
 								```
 								不指定 `--hub-tag` 时，`./deploy.sh` 会自动解析最新 `hub-v*` release，并在构建 app 镜像时从 GitHub Release 下载对应架构的 Hub 二进制。
 								## build.sh 模式说明
 								- 默认是 `binary` 模式（`cross` 构建二进制）。
 								- `--upload <hub-vX.Y.Z>` 会把构建产物上传到 GitHub Release。
 								- 加 `--image` 后进入镜像模式（`docker buildx`，可选）。
 								常用参数：
 								- `--tag <tag>`: 镜像 tag
 								- `--image-name <name>`: 镜像名（默认 `ghcr.io/fawney19/aether-hub`）
 								- `--platforms <list>`: 例如 `linux/amd64,linux/arm64`
 								- `--push`: 推送镜像
 								- `--load`: 加载到本地 Docker（单平台）
 								- `--latest`: 额外打 `latest` tag
-												feat(hub,stability): bounded outbound queue、worker liveness 检测、事件循环 watchdog 及 DB 操作异步化

- aether-hub: unbounded channel 改为 bounded channel (BoundedOutbound)，队列满时标记拥塞并主动关闭连接，防止内存无限增长
- aether-hub: worker idle timeout 从命令行参数改为基于心跳的 liveness 检测，默认 60 秒
- aether-hub: 新增 ConnConfig 统一管理连接配置，新增 outbound_queue_capacity 参数
- hub_transport: 新增事件循环 watchdog，检测 lag 超过阈值时临时降级暂停新流
- gunicorn_conf: 启用 faulthandler，worker abort 时自动 dump 全部线程栈用于诊断
- health/endpoint_checker/recording: 同步 DB 操作移至 asyncio.to_thread，避免阻塞事件循环
- Dockerfile: 移除 --worker-idle-timeout 0 命令行参数，改由环境变量和默认值控制

											
										
										
											2026-03-12 12:19:04 +08:00
+								## 运行时参数
 								- `TUNNEL_HUB_WORKER_IDLE_TIMEOUT`：worker 心跳空闲超时，默认 `60` 秒
 								- `TUNNEL_HUB_OUTBOUND_QUEUE_CAPACITY`：单连接出站队列容量，默认 `128`；队列打满时会把连接视为拥塞并主动关闭，避免 Hub 内存无限增长
-												refactor: Hub二进制改为Docker构建时下载，优化部署流程与worker初始化

- Dockerfile: 移除COPY预编译二进制，改为构建时通过HUB_TAG从GitHub Release下载
- CI: 移除artifact上传/下载步骤，通过build-args传递Hub tag
- deploy.sh: 重构参数解析，支持--hub-tag指定版本，跟踪tag变化触发重建
- build.sh: 新增--image模式支持构建并推送Hub Docker镜像
- hub.rs: worker连接时同步所有节点在线状态，避免状态不一致
- proxy_nodes: 启动时主动建立Hub worker连接，消除懒连接窗口期
- docker-compose.yml: app镜像支持APP_IMAGE环境变量配置
- README: 更新部署文档，推荐本地构建方式

											
										
										
											2026-03-02 11:24:14 +08:00
+								## 与部署脚本关系
 								- `./deploy.sh`: 本地构建部署（会本地构建 app/base，并在构建 app 时从 GitHub Release 下载 Hub，可用 `--hub-tag` 固定版本）。