EdgeSieve

简体中文 | English

EdgeSieve 是一个自托管的 Cloudflare Edge IP 筛选与 Mihomo/Clash 订阅生成工具。

它会从远程 IP:port#country 数据源下载候选节点，在部署它的服务器上执行测速，保存历史测量结果到 SQLite，按国家筛选优质 endpoint，并生成可直接使用的 Mihomo YAML 订阅。

项目状态：v1 稳定版。面向单管理员自托管场景，仍建议公网暴露前配置认证和订阅 token。

功能

• 多配置档管理：维护不同的源、国家、端口和代理模板。
• 手动运行测速：下载候选、测速、筛选并生成订阅，运行中可查看 batch 级进度并取消。
• 测速模式：默认 latency 只测延迟，避免全量下载测速拖慢任务；full 速度测试需要切到 legacy cloudflare runner。
• 入选节点表和运行历史：支持搜索、筛选、排序、分页、CSV 导出，以及历史 run 的事件和测速明细查看。
• Mihomo YAML 预览：可复制、下载或重新生成订阅。
• 在线更新：Compose 部署可在 Web UI 右上角检查正式版 Release，并由当前容器下载新版本程序后一键重启。
• SQLite 持久化：保存配置、运行记录、候选和测量结果。
• Docker 部署：镜像构建时固定下载 mihomo，保留 CloudflareSpeedTest legacy runner，并支持 amd64/arm64 镜像发布。

工作流

remote all.txt
  -> parse candidates
  -> run speed tests on this server
  -> persist measurements in SQLite
  -> select top N endpoints per country
  -> generate Mihomo/Clash YAML
  -> serve /sub.yaml and /sub/{id}.yaml

快速开始

Docker Compose

cp docker-compose.example.yml docker-compose.yml
# 默认端口是 127.0.0.1:18080，只发布到服务器本机。
docker compose pull
docker compose up -d
docker compose exec edge-sieve edge-sieve admin-token

复制出的 docker-compose.yml 默认拉取 ghcr.io/novcky/edge-sieve:latest，只长期运行一个 edge-sieve 容器，并使用 Docker named volume 保存 /data。首次启动会自动生成管理 token 到 /data/admin-token；上面的 admin-token 命令用于打印登录 token。

默认 Compose 不需要 .env、Docker socket 或项目目录挂载。Web UI 右上角的一键在线更新会从 GitHub Release 获取当前平台的 edge-sieve 程序和 SHA256SUMS，校验后安装到 /data/runtime/releases/<version>-*/edge-sieve，更新前备份 SQLite 数据库到 /data/backups/update-*，然后由容器内 supervisor 重启服务并等待 /healthz 确认。若新程序无法启动或版本不匹配，会自动回到上一可用版本；没有上一可用版本时使用镜像内置程序。如果你通过 Compose 重建或回滚镜像，新容器会优先使用镜像内置程序。

Compose 默认使用 127.0.0.1:18080:18080，只把服务发布到服务器本机；容器内部监听固定为 0.0.0.0:18080，这是 Docker 端口映射所需的内部设置，普通部署无需修改。

默认 Compose 部署不需要手动调整宿主机 data/ 目录权限，因为数据保存在 named volume 中。若改成 bind mount、只读挂载、自定义用户或特殊存储，请确保容器可以写入 /data。

GitHub Actions 会在推送 v* 标签时发布容器镜像：

docker pull ghcr.io/novcky/edge-sieve:<version>

示例 Compose 使用 latest，即：

docker pull ghcr.io/novcky/edge-sieve:latest

默认服务监听 127.0.0.1:18080：

http://127.0.0.1:18080

远程服务器测试时推荐保持默认 127.0.0.1:18080 端口映射，并用 SSH 隧道访问：

ssh -L 18080:127.0.0.1:18080 user@server

Web UI 会先显示管理登录页；登录成功后会用 HttpOnly cookie 保持会话。

首次使用需要在 Web UI 中填写：

• 远程源 URL
• Host
• SNI（可选，留空使用 Host）
• UUID
• WS Path

然后点击 立即运行 生成订阅。

不使用 Docker 本地运行

Windows PowerShell：

.\scripts\run-local.ps1

macOS / Linux：

./scripts/run-local.sh

脚本会安装前端依赖、构建前端、构建 Go 二进制，并在 http://127.0.0.1:18080 启动完整 Web UI。 如果未设置 ADMIN_TOKEN，脚本会使用开发默认值 dev-admin-token。 默认使用 mihomo runner；脚本会自动下载固定版本的 mihomo 到 bin/ 并设置 MIHOMO_PATH。显式设置 SPEEDTEST_RUNNER=cloudflare 时，如果未配置 CLOUDFLARESPEEDTEST_PATH，脚本会自动下载固定版本的 CloudflareSpeedTest 到 bin/。

本地开发

同时启动后端和 Vite dev server：

.\scripts\dev.ps1

./scripts/dev.sh

前端开发服务监听 http://127.0.0.1:5173，API 会代理到后端 127.0.0.1:18080。 默认测速 runner 为 mihomo，开发脚本会自动准备 mihomo；只调 UI 时可设置 SPEEDTEST_RUNNER=fake 使用模拟测速。显式使用 SPEEDTEST_RUNNER=cloudflare 时，开发脚本会自动准备 CloudflareSpeedTest。 如果未设置 ADMIN_TOKEN，开发脚本会使用 dev-admin-token。

也可以手动分别运行：

后端：

ADMIN_TOKEN=dev-admin-token APP_ADDR=127.0.0.1:18080 DATA_DIR=./data go run ./cmd/edgesieve

前端：

cd web/frontend
npm ci
npm run dev

配置

常用环境变量：

变量	默认值	说明
APP_ADDR	127.0.0.1:18080	直接运行二进制时的 HTTP 监听地址；Compose 内部固定为 0.0.0.0:18080
DATA_DIR	./data	数据目录
DB_PATH	从 DATA_DIR 派生	SQLite 数据库路径
SUB_PATH	从 DATA_DIR 派生	default profile 的订阅输出路径
LOG_LEVEL	info	日志级别
ADMIN_TOKEN	自动生成到 DATA_DIR/admin-token	Web UI/API 管理 token；设置环境变量时会覆盖 token 文件
SPEEDTEST_RUNNER	mihomo	测速 runner，支持 mihomo、cloudflare 或 fake
MIHOMO_PATH	mihomo	mihomo 二进制路径；脚本和 Docker 会自动设置
CLOUDFLARESPEEDTEST_PATH	CloudflareSpeedTest	legacy 测速二进制路径
WEB_DIST_DIR	自动探测	前端静态文件目录
BLOCK_PRIVATE_SOURCE_URL	false	禁止源 URL 解析到私网、回环、链路本地等地址
MAX_SOURCE_BYTES	52428800	远程源最大字节数，必须为正整数
REQUIRE_SUBSCRIPTION_TOKEN	false	为 true 时，未设置 profile 订阅 token 的订阅端点会返回 403
UPDATE_CHECK_ENABLED	true	是否检查 GitHub 最新正式版 Release
UPDATE_REPOSITORY	novcky/edge-sieve	更新检查使用的 GitHub 仓库
UPDATE_CHECK_INTERVAL_SECONDS	43200	更新检查缓存时间
UPDATE_DOWNLOAD_PROXY_PREFIXES	空	一键更新下载失败后的可选代理前缀，多个用英文逗号分隔
SELF_UPDATE_ENABLED	false，官方 Docker 镜像为 true	是否允许官方 Docker supervisor 运行环境执行 Web UI 一键更新

UPDATE_DOWNLOAD_PROXY_PREFIXES 使用字面前缀拼接原始下载 URL，不会自动补 / 或 URL encode。前缀必须是拼接后仍为合法 URL 的完整字符串，例如 https://gh-proxy.example.com/ 会重试请求 https://gh-proxy.example.com/https://github.com/...。

DB_PATH 和 SUB_PATH 留空时分别使用 DATA_DIR/edgesieve.db 和 DATA_DIR/sub.yaml。只有需要把数据库或 default profile 订阅文件放到独立位置时，才需要单独设置它们。其他 profile 的订阅文件会写入 DATA_DIR/profiles/{id}/sub.yaml，HTTP 访问路径是 /sub/{id}.yaml。

当前默认 mihomo runner 只支持 latency 模式。需要 full 下载测速时，请显式设置 SPEEDTEST_RUNNER=cloudflare 使用 legacy CloudflareSpeedTest runner。

默认 max_latency_ms 为 3000，因为 mihomo runner 测的是完整代理访问健康检查 URL 的真实延迟；如果你只想要更激进的节点池，可以在 Web UI 中调低该阈值。

完整配置见 Configuration Reference。

安全提示

• 生成的订阅 YAML 包含 UUID 和完整节点池，应视为敏感文件。
• 管理 token 默认自动生成到 DATA_DIR/admin-token；不要在 issue、日志或截图中公开它。
• 不建议直接把 /sub.yaml 或 /sub/{id}.yaml 暴露到公网；如需暴露，请配置订阅 token，并建议设置 REQUIRE_SUBSCRIPTION_TOKEN=true 或使用反向代理认证。
• 如果源 URL 来自不完全可信的输入，建议设置 BLOCK_PRIVATE_SOURCE_URL=true，阻止抓取私网、回环和链路本地地址。
• 一键在线更新只在官方 Docker supervisor 运行环境中可用，会下载并执行 GitHub Release 中的 edge-sieve 二进制；请保护管理 token，只允许可信管理员使用更新入口。
• 不要在 issue、日志或截图中公开真实 UUID、token 或订阅内容。

更多内容见 Security And Operations 和 SECURITY.md。

开发命令

make build
make test
make lint

常用单项命令：

go test -count=1 ./cmd/... ./internal/...
cd web/frontend && npm run lint
cd web/frontend && npm run test:ci
cd web/frontend && npm run build

如需 race detector：

make test-go-race

文档

• Product Requirements
• Architecture
• Data Model
• Speed Test And Selection
• Subscription Generation
• Web UI And API
• Docker And Deployment
• Security And Operations
• Configuration Reference
• Development Workflow
• V1 Roadmap
• V1 Release Checklist
• V1 Release Notes
• V1 Compatibility Expectations
• ADRs

许可证

MIT