Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
93 lines (65 loc) · 3.89 KB

ARCHITECTURE.md

File metadata and controls

93 lines (65 loc) · 3.89 KB
Raw

MihomoSift 架构与开发备忘

数据流

Sub-Store 原 URL ──┐
                    ├─> 格式对齐 ─> 临时 Mihomo ─> 逐节点 delay API ─> 过滤原文档 ─> 原子发布
target=Mihomo URL ─┘                                        │
                                                               └─> Job 结果/日志

原 URL 用于保存输出格式，target=Mihomo 输出只用于得到 Mihomo 能解析的节点映射。名称映射失败必须终止本轮，不允许猜测对应关系。

Job 状态机

queued -> updating -> validating -> probing -> publishing -> completed
   |          |            |           |           |
   +----------+------------+-----------+-----------+-> failed/stopped
  • 任务创建时去重；已运行/排队的同订阅直接返回原 Job ID。
  • scheduler 每 10 秒扫描 NextRunAt，实际下次时间从上一轮完成/失败/停止时起算。
  • 任务停止后本轮结果作废，已发布输出不受影响。

测速语义

MihomoProcess.probeOnce 向临时内核控制器请求：

GET /proxies/{internal-name}/delay?url={probe-url}&timeout={milliseconds}
Authorization: Bearer {ephemeral-secret}

Mihomo 官方内部会建立选定节点连接，对 probe URL 发起 HTTPS HEAD。unified-delay 打开时再发起第二次请求并从第二次计时，用于减少 DNS、TCP/TLS 或 QUIC 首次握手对结果的影响。

API 的错误体常只有 Timeout 或 An error occurred in the delay test。详细连接原因只能从 debug 级别内核输出取得。

临时内核生命周期

  1. 将标准化节点写入 Job runtime 目录。
  2. 先对全配置执行 mihomo -t；失败时逐节点隔离不兼容项。
  3. 生成随机本地 controller 端口和临时 secret，内核仅在 Job 期间运行。
  4. 完成、失败或取消后终止进程组并删除 runtime 目录。

内核优先级：data/core/mihomo 管理版 > 镜像内 /usr/local/bin/mihomo 回退版。

持久化

data/
├── state.json          # 设置、订阅、Job 和内核状态，0600
├── outputs/{id}.sub    # 最后成功输出，0600
├── core/mihomo        # 自动更新的 Alpha
└── runtime/{job-id}/   # 临时配置，Job 后删除

Store 先克隆 State，在内存副本上执行更新，然后通过 .tmp + rename 原子写入。新字段或语义不兼容时必须同时规划 stateVersion 迁移，不得静默丢数据。

部署模式

GHCR 预构建镜像

cp .env.example .env
docker-compose -f docker-compose.yaml pull
docker-compose -f docker-compose.yaml up -d

本地源码构建

docker compose -f compose.yaml up --build -d

Dockerfile 每次构建从 metacubex/mihomo:Alpha 取得内核。Action 对 Docker build 设置 pull: true 和 no-cache: true，确保重新解析当时 Alpha。发布镜像为 ghcr.io/fatelightx/mihomosift:latest和 commit SHA 标签。

开发验证层级

  1. 静态：gofmt、go vet、Action YAML lint、Compose config。
  2. 单元：格式保真、State 原子更新、API CRUD、队列和 HY2 重试。
  3. race：go test -race ./...。
  4. 内核配置：用目标 Alpha 的 mihomo -t 校验生成 YAML。
  5. 镜像：GitHub Action 构建 linux/amd64 并发布 GHCR。
  6. 真实运行：只在明确要求后触发订阅任务；记录 Job ID、节点数、协议分布和错误分布。

已知边界

  • 自动 Alpha 更新资产解析只支持 linux/amd64。
  • macvlan 无法让容器直接访问宿主的 macvlan 父接口，所以额外的 host-access bridge 是刻意设计。
  • GET /api/state 返回完整 Job 结果/日志，节点数较多时响应会较大。如果未来做分页，必须保持现有前端和 SSE 兼容。
  • 当前内核 API 的通用失败消息无法区分 QUIC 证书、UDP 路由、MTU 和服务端拒绝；详细判断依赖 debug 日志。