Mihomo Sift

Mihomo Sift 从 Sub-Store 订阅中取出节点，使用本地 Mihomo 内核实测延迟，并将通过阈值的节点重新发布为订阅。管理页、API 和任务队列都由一个 Go 进程提供。

开发和 AI 维护请先阅读 AGENTS.md 和 docs/ARCHITECTURE.md。

工作方式

1. 同时请求原始 Sub-Store URL 和带 target=Mihomo 的标准化输出。
2. 将 Mihomo 可执行节点映射回原订阅，隔离不兼容的节点。
3. 普通节点按全局设置测试；Hysteria2 自动使用最多 3 次、至少 2 次成功的中位数，并将 UDP/QUIC 测试并发限制为 3。
4. 仅保留延迟不高于阈值的节点，并尽量保持 YAML、URI 列表或 Base64 URI 列表的原始格式。
5. 成功后原子替换发布文件；抓取、校验或测试失败时继续提供上一个成功版本。

Docker 运行

直接使用 GitHub Actions 发布的镜像部署：

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

需要在本地从源码重新构建时，使用 compose.yaml：

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

Docker Compose 默认通过 macvlan 使用独立局域网 IP 10.0.0.20，监听 6333 端口，并将状态和输出保存到当前目录的 ./data：

docker compose up --build -d

如果 Docker 只安装了独立 Compose，将上述命令中的 docker compose 换成 docker-compose。

局域网设备打开 http://10.0.0.20:6333。如需换端口：

PORT=9080 docker compose up --build -d

macvlan 默认参数：

MIHOMO_SIFT_IP=10.0.0.20
MACVLAN_PARENT=eth0
MACVLAN_SUBNET=10.0.0.0/24
MACVLAN_GATEWAY=10.0.0.1

如果 Docker 宿主的局域网网卡不是 eth0，或者局域网不是 10.0.0.0/24，请在 .env 中覆盖上述值。MIHOMO_SIFT_IP 必须是未被占用的局域网 IP，建议在 DHCP 地址池中排除或保留该地址。

macvlan 需要 Linux Docker 宿主和可用的局域网网卡；Docker Desktop for macOS/Windows 不能把 macvlan 容器直接暴露到物理局域网。macvlan 默认不允许容器通过宿主的局域网 IP 访问宿主。Compose 因此同时连接了 Docker bridge 网络，宿主上的订阅服务应使用 host.docker.internal 访问。

macvlan 端点已开启 IPv6 SLAAC。只要 OpenWrt 在 LAN 上发送 IPv6 Router Advertisement，容器会直接获得路由器分配的 IPv6 地址和默认路由，不需要在 Compose 中写死动态 IPv6 前缀。

例如，宿主 10.0.0.5:3001 上的 Sub-Store 订阅在 Mihomo Sift 中填写为：

http://host.docker.internal:3001/ss/download/collection/Sub%20Store?target=ClashMeta

Sub-Store 的 3001 端口需监听 0.0.0.0，或 Docker 端口发布使用 3001:3001，不要只绑定 10.0.0.5:3001。

容器会先修正 ./data 的所有权，再降权启动主程序。Linux 上可通过 .env 指定宿主用户 UID/GID：

PUID=1000
PGID=1000

容器构建时会主动拉取 metacubex/mihomo:Alpha 最新镜像，并取出 Mihomo 作为内置回退内核。运行期间还会按设置默认每 24 小时检查 Alpha 更新。

GitHub Actions 会在 main 推送、版本标签和手动触发时构建 linux/amd64 镜像，并发布到：

ghcr.io/fatelightx/mihomosift:latest

Compose 默认使用 macvlan，容器作为独立的局域网设备运行，避免 bridge NAT 对 UDP/QUIC 节点和延迟测量造成额外差异。如果网关运行 MihomoX，应在“局域网代理 → 访问控制”中为容器 IP 单独关闭“代理”和“DNS”，避免测速流量再被透明代理或获得 Fake-IP。Mihomo 路由中也可保留：

- SRC-IP-CIDR,10.0.0.20/32,DIRECT

仅有 Mihomo 的 SRC-IP-CIDR 规则不会阻止防火墙 TProxy 拦截，因此不能替代局域网访问控制。上述设置不会影响宿主 10.0.0.5 或其他局域网设备。

当前内核自动更新器只匹配 Linux amd64 Alpha 资源，因此 compose.yaml 固定为 linux/amd64。其他架构可以构建和运行，但应先在设置中关闭内核自动更新。

本地运行

需要 Go 1.24 或更高版本，以及一个可执行的 Mihomo 内核：

go build -o ./bin/mihomo-sift .
./bin/mihomo-sift \
  -listen 127.0.0.1:8080 \
  -data ./data \
  -mihomo /path/to/mihomo

可用环境变量与命令行参数：

环境变量	命令行	默认值	用途
LISTEN_ADDR	-listen	:8080	HTTP 监听地址
DATA_DIR	-data	./data	持久化状态、任务目录和输出
MIHOMO_BIN	-mihomo	/usr/local/bin/mihomo	内置回退 Mihomo 路径

节点连接问题排查时，可在 .env 中临时设置 MIHOMO_LOG_LEVEL=debug。Mihomo 输出会记入对应任务的“运行日志”，排查完成后建议恢复为 warning。

命令行参数的优先级高于环境变量。成功下载的 Alpha 内核位于 DATA_DIR/core/mihomo，其优先级高于 MIHOMO_BIN。

API

方法	路径	用途
GET	/api/health	存活检查
GET	/api/state	当前设置、订阅、任务和内核状态
GET	/api/events	状态变化 SSE 通知
PUT	/api/settings	更新全局设置
POST	/api/subscriptions	新建订阅
PATCH	/api/subscriptions/{id}	更新订阅
DELETE	/api/subscriptions/{id}	删除订阅及其任务与输出
POST	/api/subscriptions/{id}/run	立即排队测试
POST	/api/subscriptions/{id}/stop	停止排队或运行中的测试
POST	/api/core/update	检查并安装 Mihomo Alpha
GET	/sub/{源名称}	按自定义源名称获取最后一个成功的筛选订阅

数据与安全

• 服务本身不包含身份验证，默认供可信局域网使用；不要直接暴露到公网。需要跨网络访问时，应在反向代理层增加认证和 TLS。
• 订阅请求头会以明文保存在 DATA_DIR/state.json 中；API 返回时会遮罩 Authorization、Proxy-Authorization 和 Cookie。请保护数据目录和备份。
• 订阅 URL 由服务端请求。不要将管理 API 暴露给不可信用户。
• 删除命名卷会永久删除状态：docker compose down -v。

验证

go test ./...
go test -race ./...
go vet ./...
go build ./...

测试使用临时数据目录和本地 HTTP 服务器，不需要真实订阅或 Mihomo 进程。

许可证

本项目代码使用 MIT License。容器中的 Mihomo 和 Go 依赖保留各自的许可条款，详见 THIRD_PARTY_NOTICES.md。