- 🚀 项目是干嘛的?
- ✨ 主要功能
- 🧠 工作原理
- 🛠️ 网页部署指南(纯小白教程)
- 🧑💻 开发者模式(CLI 本地调试 / 部署)
- 📡 API 接口文档
- 🗄️ 数据表结构
- 🔒 安全机制
- ❓ 常见问题(FAQ)
- 🩺 故障排查
- ⬆️ 升级须知
⚠️ 重要声明
简单来说,这个项目能让你直接克隆任何一个优选好的域名(比如别人花时间筛选的 CDN 加速域名),并把它所有的 DNS 解析记录实时同步到你自己的域名上。
- 🎯 核心用途: 域名克隆,实现白嫖。 看到了好的优选域名?直接输入,一键克隆,别人的优选成果就变成了你的。
- 📦 额外福利: 自建 IP 库。 自动从网上抓取各种优选 IP,并存到你自己的 GitHub 仓库里,形成一个私有的、随时可用的 IP Hub。
所有操作都在 Cloudflare 上完成,免费、高效且稳定。
| 功能点 | 图标 | 描述 |
|---|---|---|
| 一键域名克隆 (核心) | 🔄 | 深度克隆 CNAME 记录找到最终 IP,并实时同步源站变化,实现全自动“白嫖”。 |
| 聚合 IP 到 GitHub | 📦 | 自动化从多个公开源抓取最新 IP 列表,并自动推送到你自己的 GitHub 仓库。 |
| 三网优选 IP(内置) | 🇨🇳 | 内置移动 / 电信 / 联通三网优选 IP 源(hostmonit),一键生成 yd/dx/lt 三条子域名记录,无需手动维护。 |
| 订阅器友好代理 | 📡 | 直接访问同步到 GitHub 的 IP 文件。格式为 你的 Worker 首页 URL / GitHub 文件路径,可直接用于各种订阅器,并自带 5 分钟边缘缓存。 |
| 精美的管理后台 | 🎨 | 简单易用的密码保护后台,所有配置点点鼠标即可完成,无需懂代码。 |
| 公开展示页 | 🌐 | 一个简洁漂亮的首页,展示你克隆的所有域名和 IP 库地址,方便分享和使用。 |
┌─────────────────────────────────────────────────────────────────┐
│ Cloudflare Worker(入口) │
│ src/index.ts (fetch + scheduled) │
└─────────────────────────────────────────────────────────────────┘
│
┌─────────────────────┼─────────────────────┐
▼ ▼ ▼
┌────────────────┐ ┌────────────────┐ ┌──────────────────┐
│ /api/* │ │ /、/login、 │ │ /<github_path> │
│ API 路由层 │ │ /admin │ │ GitHub 文件代理 │
│ routes/api.ts │ │ routes/ui.ts │ │ routes/github- │
│ │ │ │ │ proxy.ts │
└───────┬────────┘ └────────┬───────┘ └────────┬─────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ sync 同步层(src/sync/) │
│ domains.ts ip-sources.ts github.ts │
│ ─ 域名克隆 ─ IP 抓取 ─ GitHub API 封装 │
└───────────────────────────┬─────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────────┐
│ 数据层(src/db/) │
│ client.ts(D1 封装)+ migrations.ts(幂等建表) │
│ ↓ D1 绑定名:WUYA │
└─────────────────────────────────────────────────────────────────┘
sync/domains.ts 中 resolveRecordsForDomain 按「IP 输入类型 → 内置源前缀 → 深度开关」的顺序分流:
| 模式 | 触发条件 | 行为 |
|---|---|---|
| URL 输入 | source_type = 'url' |
抓取 source_url,按解析模式取出 IP,写 A/AAAA 记录(单类型上限见下) |
| 系统内置三网 | source_domain 以 internal:hostmonit: 开头 |
从 hostmonit 等 HTML 表格源抓取移动/电信/联通 IP,直接写 A 记录 |
| 深度解析 | is_deep_resolve = 1 |
递归追踪 CNAME 链(最多 10 层),直到取出最终 IPv4/IPv6,写 A/AAAA 记录 |
| 浅层克隆 | is_deep_resolve = 0 |
直接克隆源域名的 CNAME 记录(源必须是 CNAME) |
克隆目标有两种 IP 输入类型,由 domains.source_type 决定(NULL 按 domain 处理,存量数据无需回填):
domain(域名,默认):原来的行为,深度开关可自由切换。url(URL):填一个http(s)地址,系统抓取后解析出 IP 写 A/AAAA。URL 的 hostname 会派生为source_domain,用于在 Cloudflare 上定位同名记录。URL 类型固定关闭深度解析——深度解析追踪的是 CNAME 链,对「抓一个 IP 列表接口」没有意义,所以保存时is_deep_resolve被强制置 0。
url 类型由 domains.parse_mode 与 domains.parse_param 描述怎么从响应正文里取 IP(ip_sources 用同名两列,语义一致):
| 解析模式 | parse_param |
行为 |
|---|---|---|
auto(默认) |
不需要 | 全文提取,兼容 HTML 表格、JSON 与纯文本 |
lines |
不需要 | 按行与逗号 / 空白切分 token,逐 token 严格校验 |
json_path |
JSON 点路径,最长 512 字符 | 支持数组索引,取出字符串或字符串数组,例如 data.list.ips |
custom_regex |
正则,最长 200 字符 | 取命名组 ip,没有则取捕获组 1(不拿整段匹配兜底) |
几条运行期约定:
- 解析模式写
NULL、空串或未知值一律按auto读取,因此旧数据与新数据走同一条路径。 custom_regex在保存 / 探测时做静态拦截(嵌套量词、分支重叠等高风险形态),作为 ReDoS 兜底。- 解析前统一把正文截断到 512 KB(四种模式都生效,是入口处的兜底),避免超大响应拖垮 worker。
- 抓取失败时保留上次成功写入的记录,本轮记
failed;抓取成功但解析出 0 条时,如果目标原本有记录则记failed,原本就没有记录则记no_change。 - 同一批同步里同一个 URL + 解析配置只抓一次,多个目标共享结果。
不管 IP 来自哪种模式,写入 DNS 前都会按记录类型分别截断:A 最多 N 条、AAAA 最多 N 条,CNAME 不截断。
| 项 | 取值 |
|---|---|
| 默认值 | 20 |
| 可设范围 | 1–200 的整数 |
| 配置入口 | 后台 系统设置 → DNS 记录设置 → 单类型记录上限 (MAX_IPS_PER_TYPE) |
| 留空含义 | 显式清除自定义值,回落默认 20(与「清除自定义 hostmonit key」同属清除语义) |
⚠️ 上限对存量域名同样生效:某个目标的源站单类型原本超过 20 条时,下一次同步会把超出部分的记录删掉。这是统一上限的既定行为,升级前请确认可以接受(见 ⬆️ 升级须知)。
IP 源同步到 GitHub 时,主文件恒为 IPv4 列表(每行一个,保持存量格式不变),IPv6 写到由主文件路径派生出的伴生文件:
主文件 github_path |
伴生文件路径 | 派生规则 |
|---|---|---|
IP/Cloudflare.txt |
IP/Cloudflare-v6.txt |
以 .txt 结尾:去掉 .txt 再加 -v6.txt |
IP/list |
IP/list-v6 |
其他情况:直接追加 -v6 |
- IPv6 列表非空 → 写入 / 更新伴生文件;为空 → 删除远端伴生文件(远端本来就没有则静默跳过)。
- 内容比对按
trim后的结果进行:主文件内容与远端一致时不发 PUT,所以「没有解析出 IPv6」的存量源主文件逐字节不变。 - 主文件与伴生文件共用同一份 Git 路径命名空间,两者不得互相占用;保存 IP 源时双向校验,冲突返回 409。
Cron 0,30 * * * *(每 30 分钟)触发 scheduled handler,通过 settings.next_sync_task 在两种批任务间轮转:
第 N 次触发:next_sync_task = 'domains' → 同步 BATCH_SIZE=10 条域名(失败优先)
执行完毕后翻转:next_sync_task = 'ip_sources'
第 N+1 次触发:next_sync_task = 'ip_sources' → 同步 BATCH_SIZE=10 条 IP 源(失败优先)
执行完毕后翻转:next_sync_task = 'domains'
触发频率由部署配置决定,与轮转逻辑无关:仓库内
wrangler.toml的[triggers] crons = ["0,30 * * * *"]即每 30 分钟一次。改频率只需改这一处,scheduledhandler 照旧每轮只跑一个批任务。
关键设计: 无论本轮任务成功或失败,状态都会翻转,避免单点失败永久卡死。每批按
last_sync_status='failed'优先、last_synced_time升序选择目标。
整个部署过程都在 Cloudflare 网站上完成,不需要任何命令行工具。请严格按照以下流程操作:
① 创建 Worker ➡️ ② 创建并绑定 D1 ➡️ ③ 初始化并配置 ➡️ ④ 设置定时器 (关键!)
-
登录 Cloudflare 控制台,进入左侧菜单的 Workers & Pages。
-
点击 创建应用程序 (Create Application) > 创建 Worker (Create Worker)。
-
为你的 Worker 取一个名字(例如
cf-dns-clon),然后点击 部署 (Deploy)。 -
部署成功后,点击 编辑代码 (Edit code)。
-
获取 Worker 代码——任选以下两种方式之一:
方式 A:下载打包好的单文件(推荐,零依赖)
在本仓库的 Releases 页面 下载最新版的
worker.bundle.js(构建产物,由scripts/build-single-file.mjs通过 esbuild 从src/index.ts打包生成),用任意文本编辑器打开,复制全部内容。方式 B:本地构建生成单文件(需要 Node.js)
# 1. 克隆仓库 git clone https://github.com/free5394/dns-clone.git cd dns-clone # 2. 安装依赖(需要 Node.js ≥ 22 + pnpm ≥ 11) pnpm install # 3. 构建单文件 bundle pnpm build:single # 4. 复制 dist/worker.bundle.js 的全部内容
-
将复制到的代码完整地粘贴到 Cloudflare 代码编辑器中,覆盖掉原有的示例代码。
-
点击右上角的 部署 (Deploy) 按钮。
💡 为什么不能直接复制
src/index.ts? 项目已模块化为多个.ts文件(详见 工作原理),Cloudflare Dashboard 编辑器只接受单文件入口。build:single会用 esbuild 把所有模块打包成一个可直接运行的worker.bundle.js。
- 在左侧菜单中,找到并进入 D1。
- 点击 创建数据库 (Create database),填写数据库名称(例如
wuya-db),然后点击 创建 (Create)。 - 返回到你的 Worker,进入 设置 (Settings) > 变量 (Variables)。
- 找到 D1 数据库绑定 (D1 Database Bindings),点击 添加绑定 (Add binding)。
- 变量名称 (Variable name) 必须填写
WUYA(全大写)。 - 在 D1 数据库 (D1 Database) 下拉列表中,选择你刚刚创建的
wuya-db。 - 点击 保存并部署 (Save and deploy)。
⚠️ 绑定名必须是WUYA。Worker 启动时会检查env.WUYA,缺失会直接返回 500 错误。表结构会在首次访问时由initializeAndMigrateDatabase自动幂等创建,无需手动执行 SQL。
-
设置管理员密码
- 访问你的 Worker URL (例如
https://cf-dns-clon.your-username.workers.dev)。 - 页面会引导你设置一个安全的管理员密码(长度 8–1024 字符,使用 PBKDF2 哈希存储)。
- 访问你的 Worker URL (例如
-
获取 API 密钥
- Cloudflare API (Zone ID 和 API Token):
- 区域 ID (Zone ID): 在 Cloudflare 域名概述页的右下角复制。
- API 令牌 (API Token): 前往 API 令牌 页面,使用 “编辑区域 DNS” 模板为你的域名创建一个新令牌。(注意:令牌只显示一次,请妥善保管)
- GitHub Token:
- 登录 GitHub,点击 Generate new token (classic)。
- 勾选
repo权限(用于自动创建私有仓库 + 推送 IP 文件 + 订阅代理读取),建议设置永不过期,然后生成并复制令牌。(同样,只显示一次)
- Cloudflare API (Zone ID 和 API Token):
-
登录后台进行最终配置
- 访问你的 Worker URL 并在后面加上
/admin(例如https://.../admin),使用你的密码登录。 - 进入 系统设置 页面,将上面获取到的所有信息填入对应的输入框中。
- 点击 保存设置。系统会自动验证 Cloudflare 凭据,并为你的域名初始化 8 个内置 IP 源 + 10 个内置域名(含三网优选)。
- 三网优选 IP 的 hostmonit key(可选):内置三网源通过 hostmonit 的公开接口取 IP,默认使用内置 key。若日志出现
HostMonit API HTTP 4xx/5xx(实际串形如HostMonit API HTTP 429)或返回 0 个 IP(对方轮换 key / 限流),到 系统设置 → IP 源抓取设置 填入新 key 并保存即可,下一次同步立即生效。该输入框「留空」的含义取决于是否配置过自定义 key:- 从未配置过:留空保存即继续使用内置默认 key。
- 已配置过自定义 key:留空保存表示保持当前 key 不变,不会回退到内置默认;要恢复内置默认,请勾选下方的「清除自定义 Key(恢复内置默认)」再保存。清除与留空是两个不同动作,只有勾选清除才会删掉已保存的 key。
- 只输入空白字符等同留空;key 属敏感字段,页面只显示「是否已配置」,不回显原文。
- 访问你的 Worker URL 并在后面加上
- 返回到你的 Worker,进入 设置 (Settings) > 触发器 (Triggers)。
- 在 Cron 触发器 (Cron Triggers) 部分,点击 添加 Cron 触发器 (Add Cron Trigger)。
- Cron 表达式 选择 每 30 分钟 (
0,30 * * * *),可直接粘贴到自定义表达式输入框。- 点击 添加触发器 (Add trigger) 保存。
💡 每 30 分钟一次够不够及时、会不会触发限流? 够。每次只跑一个批任务(域名 ↔ IP 源轮转),每批最多
BATCH_SIZE=10条,且BATCH_SIZE可在后台 settings 表里调整;一天 48 次触发,远低于 Cloudflare Workers 免费版每天 10 万次请求额度。想更快可把表达式改小(例如*/5 * * * *每 5 分钟),代价是提前消耗额度。
以下内容仅供开发者使用。普通用户按上面的 4 步网页部署流程即可,无需安装任何工具。
| 工具 | 版本要求 | 说明 |
|---|---|---|
| Node.js | ≥ 22.12(推荐 24,见 .nvmrc) |
项目要求 engines.node >= 22.12:下限来自 vitest 的 engines(当前 5.1.0 为 ^22.12.0 || ^24.0.0 || >=26.0.0,不含 23/25,本仓库未额外排除);wrangler 4.158.0 只要求 ≥ 22.0 |
| pnpm | ≥ 11 | 直接安装(或 corepack enable 后使用) |
| Cloudflare 账号 | —— | 需要 API Token("编辑区域 DNS"模板) |
Windows 11 原生支持,无需 WSL。
# 1. 安装 Node 24(推荐用 nvm / fnm)
nvm install 24 && nvm use
# 2. 启用 pnpm(如已安装可跳过)
corepack enable
# 3. 安装依赖(首次)
pnpm install
# 4. 启动本地 workerd 调试环境
pnpm dev- 访问
http://localhost:8787即可进入后台。 - 本地 D1 数据存放在
.wrangler/state/v3/d1/miniflare-D1DatabaseObject/*.sqlite,与线上数据库隔离。 - 所有配置(含 Token)仍在后台设置页面填写并存入本地 D1,无需
.dev.vars。 - 登录限流按
CF-Connecting-IP分桶,该请求头由 Cloudflare 边缘提供。生产环境务必通过 Worker 正常入口访问;若在本地或自建反代后出现「多人共用一个限流桶」,属缺少该头导致的归并,等待会话窗口结束即可,不要为此伪造该头。
库里的 ADMIN_PASSWORD_HASH 是 PBKDF2-HMAC-SHA256 不可逆哈希,原密码找不回来,只能重置:
# 方式 A(默认):删掉密码两行,刷新页面回到初始化页重设
pnpm reset:local-admin
# 方式 B:直接写入新密码(8–1024 字符),刷新即可登录
pnpm reset:local-admin --password 'your-new-password'- 脚本只改
.wrangler/state/v3/d1下的本地库,写前默认备份到.scratch/backup/(--no-backup跳过)。 - 它会清空
sessions与login_attempts:旧登录态失效,也避免刚重置就被自己的重试挡在限流外。 - 报
SQLITE_BUSY说明本地库被pnpm dev占用——先停掉 dev server 再跑。 - 线上实例请按 Q8 处理;也可以给 Worker 配
RECOVERY_TOKEN,用POST /api/recover换密码(见公开端点)。 - 本地想试恢复入口:
pnpm exec wrangler dev --var RECOVERY_TOKEN:local-test-token(--var只影响本次进程,不会写进仓库或.dev.vars),随后带同样的值POST /api/recover。
应急旁路(仅排障用):不重置也能临时进后台——
sessions表里未过期的token直接当 Cookie 用(Cookie: session=<token>)。它只借用一条已有登录态,不解决「密码不知道」本身,token 过期或被清空即失效。
| 命令 | 作用 |
|---|---|
pnpm dev |
启动本地 workerd 调试环境(默认 8787 端口) |
pnpm reset:local-admin |
重置本地库管理员密码(默认删行回初始化页,--password 直接写入;写前备份) |
pnpm test |
两个项目依次跑:workerd 内测试套件 + test/node/ 的 Node 环境用例 |
pnpm test:coverage |
两个项目依次跑,覆盖率报告(istanbul 插桩)只统计 workerd 项目的 src/**(不含 src/ui/** 与 src/index.js) |
pnpm test:node |
只跑 Node 环境用例:scripts/ 下部署脚本的进程级接线(参数剥接、退出码) |
pnpm test:watch:node |
热跑 Node 环境用例(改 scripts/ 或 test/node/ 时用;pnpm test:watch 只覆盖 workerd 项目) |
pnpm check |
静态门禁:typecheck、测试类型检查、语言、UTF-8、lint、格式(pre-commit 跑的这条) |
pnpm verify |
pnpm check + 全量测试,想一次跑完时用 |
pnpm check:dashboard |
渲染仪表盘并解析注入的客户端脚本(Node 侧语法闸门,不进 CI) |
pnpm typecheck |
TypeScript 严格模式检查(tsc --noEmit) |
pnpm typecheck:test |
测试目录类型检查(tsc --noEmit -p tsconfig.test.json) |
pnpm build:single |
用 esbuild 打包 src/index.ts → dist/worker.bundle.js |
pnpm run deploy |
CLI 部署(自动注入 .env 中的 CLOUDFLARE_API_TOKEN;--env <name> 可切换 .env.<name> + wrangler.<name>.toml) |
pnpm run deploy:prod |
生产部署:等价 deploy --env prod,需本机 .env.prod 与 wrangler.prod.toml(均不入库) |
pnpm run deploy --print-args |
干跑:只回显 wrangler 会收到的参数后退出,不触网、不需要 Token;但与 --env <name> 同用时仍要求 .env.<name> 与 wrangler.<name>.toml 就位(DEPLOY_ROOT 生效时会先往 stderr 多打一行告警) |
pnpm cf-typegen |
重新生成 worker-configuration.d.ts(gitignore) |
先用
wrangler d1 create创建生产 D1 数据库,拿到真实 UUID。
仓库配置与线上配置故意不同:提交态的
wrangler.toml是模板(database_id为哨兵值),维护者的线上部署走本机wrangler.prod.toml+.env.prod(pnpm run deploy:prod)。两条路径的分工见 🧑💻 开发者模式 的部署脚本说明。
# 1. 创建生产 D1 数据库(记下输出的 database_id)
pnpm dlx wrangler d1 create wuya-db
# 2. 把 database_id 填入 wrangler.toml(替换哨兵值 REPLACE_WITH_YOUR_D1_ID)
# (自助部署建议同时把 name 改成你自己的 Worker 名)
# 3. 复制 .env.example 为 .env,填入账号级 Token(用于 wrangler CLI 认证)
# cp .env.example .env 然后改 CLOUDFLARE_API_TOKEN
# (获取:CF Dashboard → 我的个人资料 → API Tokens → Edit Cloudflare Workers)
# 4. 发布前干跑:确认参数真的到得了 wrangler(不触网、不需要 Token)
pnpm run deploy --print-args
# 4b. 只打包不上传,产物落到 .wrangler/dry-run/
pnpm run deploy -- --dry-run --outdir .wrangler/dry-run
# 5. 部署到 Cloudflare(显式调用 package.json 的 deploy 脚本;
# database_id 未替换时由 wrangler / Cloudflare 在部署期报错)
pnpm run deploy别省掉干跑:pnpm 会把
--分隔符一起放进 argv,而 wrangler 遇到--就停止选项解析, 其后的--dry-run会退化成位置参数被忽略 —— 命令变成真实发布(2026-11-16 实测推上过生产)。 部署脚本现在会剥掉裸--并回显实际执行的参数,但发布前跑一次--print-args仍是成本最低的确认。
注意:
wrangler.toml已配置keep_vars: true,不会覆盖你在 Dashboard 里手动配置的 Variables / Bindings。CLI 部署与网页部署两条路径可混用。
.
├── README.md # 本文档
├── CLAUDE.md # 给 AI 助手的代码事实摘要
├── package.json # 脚本:dev / test / typecheck / deploy / cf-typegen
├── wrangler.toml # Worker 配置,兼自助部署模板(compatibility_date 2026-05-20,keep_vars;database_id 为哨兵值)
├── tsconfig.json # TypeScript strict 配置
├── vitest.config.ts # @cloudflare/vitest-plugin 测试配置(workerd 内跑)
├── vitest.node.config.ts # Node 环境用例配置(test/node/,跑 scripts/ 的子进程接线)
├── scripts/
│ ├── build-single-file.mjs # esbuild 打包 → dist/worker.bundle.js
│ ├── load-deploy-env.mjs # pnpm run deploy 前置:解析 --env、注入 .env / .env.<env> 并选择 wrangler 配置(DEPLOY_ROOT 仅供测试指夹具目录,生效时会打告警)
│ └── lib/deploy-argv.mjs # 上面那份参数解析的纯函数实现(被 test/deploy-argv.test.ts 覆盖)
├── docs/ # 文档(ip-fetch-unification-plan.md:IP 抓取统一化方案;agents/:协作约定)
├── src/
│ ├── index.ts # Worker 入口(fetch + scheduled 组装,约 80 行)
│ ├── db/ # client.ts(D1 封装)+ migrations.ts(幂等建表)+ migrations/*.sql(测试用)
│ ├── routes/ # api.ts / ui.ts / github-proxy.ts
│ ├── sync/ # domains.ts / ip-sources.ts / github.ts
│ ├── ui/ # templates.js(UI 模板,纯 JS,tsc 不参与)
│ └── util/ # auth / http / log / sse / fetch / cf / url-safety / http-error / run-with-log
├── test/ # workerd 内测试(33 文件)+ test/node/(Node 环境,跑部署脚本子进程)
└── img/ # README 截图
所有 /api/* 端点返回 JSON。除 /api/status、/api/setup、/api/login、/api/recover 外,均需在 Cookie 中携带有效 session(登录后自动设置,24h 有效)。
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/api/status |
查询系统是否已初始化(是否设置了管理员密码) |
POST |
/api/setup |
首次设置管理员密码(密码 8–1024 字符;已初始化后 403) |
POST |
/api/login |
密码登录(5 分钟内失败 ≥ 5 次会 429 限流) |
POST |
/api/recover |
凭恢复令牌换一个新管理员密码(可选能力:Worker 未配 RECOVERY_TOKEN 时该路径不存在) |
POST /api/recover 请求体:
{ "token": "<RECOVERY_TOKEN 的值>", "password": "<新密码,8–1024 字符>" }成功返回 { "success": true },同一批次内替换密码哈希与盐、清空全部会话与失败记录(旧 Cookie 立即失效)。令牌错误按登录失败计入同一限流桶,5 分钟内 5 次即 429。配置方式:wrangler secret put RECOVERY_TOKEN 或 Dashboard 的 Secrets。
未配置 RECOVERY_TOKEN 时这条路由根本不注册:请求与任意未知路径走同一条路径(未登录一律 401,已登录一律 404 且响应体相同),因此「有没有开恢复入口」在两种状态下都探测不出来。
| 方法 | 路径 | 说明 |
|---|---|---|
POST |
/api/logout |
注销当前会话 |
GET |
/api/settings |
读取安全设置(已剔除 Token/密码哈希等敏感字段) |
POST |
/api/settings |
保存设置(白名单见下方;CF 与 GitHub 凭据均强制配对校验,非白名单字段一律忽略) |
POST /api/settings的写入白名单(9 个 key):CF_API_TOKEN/CF_ZONE_ID/GITHUB_TOKEN/GITHUB_OWNER/GITHUB_REPO/HOSTMONIT_API_KEY/THREE_NETWORK_SOURCE/BATCH_SIZE/MAX_IPS_PER_TYPE。传null表示显式清除;空字符串对 Secret 键表示「保持不变」、对其它键表示清除。MAX_IPS_PER_TYPE与BATCH_SIZE走同一套整数校验:写入侧越界或非整数会让整批写入被拒绝(返回 400),不会只丢这一个键;读取侧缺失或存了脏值时才回落默认(MAX_IPS_PER_TYPE20、BATCH_SIZE10)。
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/api/domains |
列出所有域名(系统域名排前) |
POST |
/api/domains |
添加克隆目标(domain 或 url 输入类型) |
PUT |
/api/domains/{id} |
更新目标(系统域名的 source 不可改) |
DELETE |
/api/domains/{id} |
删除目标(系统预设禁止删除) |
GET |
/api/domains/{id}/records |
查询该目标在 Cloudflare 上的当前 DNS 记录 |
POST |
/api/domains/{id}/sync |
立即同步单个目标(返回 SSE 日志流) |
POST |
/api/sync |
批量同步所有已启用目标(返回 SSE 日志流) |
POST |
/api/domains/sync_system |
仅同步系统预设域名(返回 SSE 日志流) |
目标对象里的这几个字段与 URL 输入相关:
source_type(domain/url,NULL 按domain)、source_url(url类型必填,http(s),≤2048 字符)、parse_mode/parse_param(见 IP 输入类型与解析模式)、fetch_strategy(url类型的历史抓取策略,URL 变化时自动丢弃)。系统预设域名不允许切换输入类型,source也不可改。
| 方法 | 路径 | 说明 |
|---|---|---|
GET |
/api/ip_sources |
列出所有 IP 源 |
POST |
/api/ip_sources |
添加 IP 源(URL 先经 SSRF 校验;可带解析模式) |
PUT |
/api/ip_sources/{id} |
更新 IP 源 |
DELETE |
/api/ip_sources/{id} |
删除 IP 源 |
POST |
/api/ip_sources/probe |
探测 URL:按给定解析模式试抓取策略,回 v4/v6 计数与样例 |
POST |
/api/ip_sources/{id}/sync |
立即同步单个 IP 源到 GitHub(返回 SSE 日志流) |
POST |
/api/ip_sources/sync_all |
批量同步所有已启用 IP 源(返回 SSE 日志流) |
访问 https://<your-worker>/<github_path>(例如 https://cf-dns-clon.xxx.workers.dev/CloudFlareYes.txt)会代理到 GitHub 仓库对应文件,并自带 5 分钟边缘缓存(Cache-Control: public, max-age=60, s-maxage=300)。
- 主文件与伴生文件都可读:IPv6 伴生文件(
CloudFlareYes-v6.txt)与主文件共享同一套读取行为、Content-Type 与缓存策略,但缓存键彼此独立。派生规则见 IPv6 伴生文件。 - 白名单是「已登记路径的正推结果」:只放行
ip_sources表里登记过的github_path及其唯一派生出的伴生路径。任意-v6形态不能借白名单放行;未登记路径(含未登记的伴生形态)一律 404,且不向上游发请求。
D1 数据库(绑定名 WUYA)共 5 张表,由 initializeAndMigrateDatabase 在首次请求时幂等创建并补齐缺失列;迁移版本未变时 24 小时内不会重复执行 DDL。
迁移是幂等的:用
PRAGMA table_info对比期望列,缺哪列补哪列(ALTER TABLE ... ADD COLUMN)。当前迁移版本为2026-11-10-ip-fetch-unification,新增列全部可空、无需回填;已部署实例在版本号变化后的首次请求即执行,不受 24 小时门控影响。回滚只需回退代码,多余列对旧代码无影响。
| 字段 | 类型 | 说明 |
|---|---|---|
key |
TEXT PRIMARY KEY | 配置项名(如 CF_API_TOKEN、BATCH_SIZE) |
value |
TEXT NOT NULL | 配置值 |
已知键:
ADMIN_PASSWORD_HASH、PASSWORD_SALT、CF_API_TOKEN、CF_ZONE_ID、CF_ZONE_NAME、GITHUB_TOKEN、GITHUB_OWNER、GITHUB_REPO、HOSTMONIT_API_KEY(可选;留空与清除的语义见步骤 ③ 的「三网优选 IP 的 hostmonit key」)、THREE_NETWORK_SOURCE、BATCH_SIZE(默认 10)、MAX_IPS_PER_TYPE(单类型记录上限,默认 20,1–200)、next_sync_task、last_migrated_at
| 字段 | 类型 | 说明 |
|---|---|---|
id |
INTEGER PK | 自增主键 |
source_domain |
TEXT | 源域名(或 internal:hostmonit:yd/dx/lt 内置源) |
target_domain |
TEXT UNIQUE | 目标域名(自动拼接 前缀.你的域名) |
zone_id |
TEXT | Cloudflare Zone ID |
is_deep_resolve |
INTEGER | 1=深度解析 CNAME 链;0=浅层克隆 CNAME |
ttl |
INTEGER | DNS 记录 TTL(默认 60) |
notes |
TEXT | 备注 |
last_synced_records |
TEXT | 上次同步的记录 JSON(用于变化检测) |
last_synced_time |
TIMESTAMP | 上次同步时间 |
last_sync_status |
TEXT | success / no_change / failed / pending |
last_sync_error |
TEXT | 上次失败原因 |
is_enabled |
INTEGER | 1=启用;0=禁用 |
is_system |
INTEGER | 1=系统预设(不可删,source 不可改);0=用户添加 |
source_type |
TEXT | IP 输入类型 domain / url(NULL 按 domain) |
source_url |
TEXT | url 类型的抓取地址(http(s),≤2048 字符) |
parse_mode |
TEXT | 解析模式(NULL / 未知值按 auto) |
parse_param |
TEXT | 解析参数(json_path / custom_regex 使用) |
fetch_strategy |
TEXT | url 类型的历史抓取策略(URL 变化时丢弃) |
| 字段 | 类型 | 说明 |
|---|---|---|
id |
INTEGER PK | 自增主键 |
url |
TEXT UNIQUE | 抓取地址 |
github_path |
TEXT UNIQUE | 推送到 GitHub 仓库的文件路径 |
commit_message |
TEXT | Git 提交信息 |
fetch_strategy |
TEXT | 抓取策略缓存(direct_regex / phantomjs_cloud / proxy_codetabs / jina_reader / hostmonit_api);由同步实测结果写入,API 不接收该字段;URL 变更即置 NULL |
parse_mode |
TEXT | 解析模式(同 domains.parse_mode,NULL 按 auto) |
parse_param |
TEXT | 解析参数(同 domains.parse_param) |
last_synced_time |
TIMESTAMP | 上次同步时间 |
last_sync_status |
TEXT | 同上 |
last_sync_error |
TEXT | 上次失败原因 |
is_enabled |
INTEGER | 1=启用;0=禁用 |
| 字段 | 类型 | 说明 |
|---|---|---|
token |
TEXT PK | 会话 Token(UUID) |
expires_at |
TIMESTAMP | 过期时间(登录后 24h) |
| 字段 | 类型 | 说明 |
|---|---|---|
ip |
TEXT | 客户端 IP(来自 CF-Connecting-IP) |
attempted_at |
TIMESTAMP | 尝试时间 |
success |
INTEGER | 1=成功;0=失败 |
已建索引
idx_login_attempts_ip_time;超过 1 小时的记录会在迁移时自动清理。
本项目在多个层面内置了安全防护:
| 维度 | 机制 |
|---|---|
| 密码存储 | PBKDF2-HMAC-SHA256,100,000 次迭代 + 随机盐;登录时恒定时间比对(timingSafeHexEqual) |
| 密码兼容 | 旧版本单轮 SHA-256 哈希在登录成功后自动升级为 PBKDF2,无需用户改密码 |
| 登录限流 | 同一 IP 5 分钟内失败 ≥ 5 次返回 429;成功后清空失败记录 |
| 会话安全 | Cookie 设置 HttpOnly + Secure + SameSite=Strict;服务端校验过期;登出立即删除 |
| 密码强度 | 后台设置接口校验密码长度 8–1024 字符(上限防 DoS) |
| SSRF 防护 | assertSafeHttpUrl 阻止访问内网/回环/链路本地/CGNAT/云元数据地址(含十进制、十六进制、IPv4-mapped IPv6 等绕过形式) |
| XSS 防护 | UI 模板所有用户可控字段(notes、target_domain 等)经 escapeHtml 转义 |
| 凭据隔离 | getSafeSettings 在返回前端前剔除 ADMIN_PASSWORD_HASH / PASSWORD_SALT / CF_API_TOKEN / GITHUB_TOKEN |
| 错误脱敏 | 非 API 路径的全局兜底返回固定文案,杜绝 stack / 凭据泄露;API 路径仅返回 message,不含 stack |
| 写入白名单 | 设置接口仅允许写入预定义的 9 个 key,忽略任意其他字段 |
| 配对校验 | CF Token + Zone ID 必须同时提供;GitHub Token + Owner + Repo 必须同时提供 |
| 网络超时 | 所有外部 fetch 经 fetchWithTimeout(默认 10s)+ 指数退避重试,杜绝无界等待 |
| 恢复入口 | POST /api/recover 仅在部署方显式配置 RECOVERY_TOKEN 时注册(未配置与未知路径无差别:未登录 401 / 已登录 404,开关不可探测);令牌经 SHA-256 归一再恒定时间比对;成功后清空全部会话 |
| 迁移门控 | last_migrated_at 24h 门控,避免每请求执行整套 DDL |
Q1:为什么必须把 D1 绑定名设为 WUYA?
Worker 代码通过 env.WUYA 访问 D1 数据库。绑定名不符会在启动时抛错并返回 500。这个名字源自上游项目,为保持向后兼容不再变更。
Q2:每 30 分钟跑一次 Cron 会不会浪费免费额度?
默认 0,30 * * * * 每天 48 次定时调用,加上每次同步内部的 D1 + Cloudflare API + GitHub API 调用,总计约几百次/天,远低于 Cloudflare Workers 免费版的 100,000 次/天额度。如果担心,可在 settings 表中调大 BATCH_SIZE 进一步减少每轮的目标数;把 Cron 改到 * * * * *(每分钟)则会提高同步及时性、同时更快消耗额度。
Q3:GitHub Token 为什么需要 repo 权限?
Worker 会自动:① 创建私有仓库(如不存在);② 推送 IP 文件到仓库;③ 通过 GitHub API 读取文件供订阅器代理使用。这三步都属 repo scope。建议创建一个专用 Token,不要用主账号 Token。
Q4:三网优选 IP 是什么?怎么用?
系统初始化时会自动添加 3 条系统域名:yd.你的域名 / dx.你的域名 / lt.你的域名,分别对应移动/电信/联通优选 IP。这些域名会从 hostmonit 等源实时抓取三网 IP 并写 A 记录,用户可直接用作分流。可在后台设置页切换 THREE_NETWORK_SOURCE(CloudFlareYes / api.uouin.com / wetest.vip)。
Q5:深度解析和浅层克隆有什么区别?
- 深度解析(默认):递归追踪源域名的 CNAME 链直到拿到最终 IP,写 A/AAAA 记录。适合源域名背后是 CDN 的情况。
- 浅层克隆:直接复制源域名的 CNAME 记录。源必须是 CNAME,否则同步失败。适合源域名本身就是另一条 CNAME 的情况。
添加/编辑域名时可在后台切换。
Q6:订阅器如何使用?
假设你在后台添加了一个 IP 源,github_path 为 CloudFlareYes.txt,那么订阅器直接填:
https://<your-worker>.workers.dev/CloudFlareYes.txt
Worker 会代理到你的 GitHub 仓库对应文件,并自带 5 分钟边缘缓存,无需直连 GitHub。
Q7:为什么我粘贴了 src/index.ts 进 Dashboard 报错?
src/index.ts 是模块化源码入口,依赖十几个 .ts 文件,Dashboard 编辑器无法解析。请按 网页部署指南第 ① 步 下载 Releases 中的 worker.bundle.js 或本地 pnpm build:single 后粘贴 dist/worker.bundle.js。
Q8:忘记管理员密码怎么办?
线上实例:进 Cloudflare D1 控制台执行:
DELETE FROM settings WHERE key = 'ADMIN_PASSWORD_HASH';
DELETE FROM settings WHERE key = 'PASSWORD_SALT';
-- 顺手清掉旧会话:否则重置前签发的 Cookie 在重建密码后仍然有效
DELETE FROM sessions;然后重新访问 Worker 首页,会引导你设置新密码。若之前给 Worker 配过 RECOVERY_TOKEN,也可以直接 POST /api/recover(带令牌与新密码),无需进控制台。
本地实例(pnpm dev):跑 pnpm reset:local-admin(删行回初始化页)或 pnpm reset:local-admin --password '<新密码>'(直接写入),细节见本地开发 → 忘记本地管理员密码。
Q9:可以同时用网页部署和 CLI 部署吗?
可以。wrangler.toml 已配置 keep_vars: true,CLI 部署不会覆盖你在 Dashboard 手动配置的 Variables / Bindings。但 D1 数据库需要先在 Dashboard 创建好并把 database_id 填入 wrangler.toml。
- 在后台域名/IP 源列表查看
last_sync_error字段。 - 常见原因:
Cloudflare API 未配置→ 进设置页补全CF_API_TOKEN+CF_ZONE_ID。GitHub API设置不完整→ 进设置页补全GITHUB_TOKEN+GITHUB_OWNER+GITHUB_REPO。所有抓取策略均未能从该URL获取到IP→ 源站可能改版或下线,点"探测"重新选择策略,或换源。在浅层克隆模式下,源域名必须是一个CNAME记录→ 改用深度解析,或换一个 CNAME 源。Cloudflare API 失败: 403 ...→ Token 权限不足,确认是"编辑区域 DNS"模板。解析深度超过 10 层,可能存在CNAME循环→ 源域名异常,换源。
5 分钟内失败 ≥ 5 次触发限流。等待 5 分钟,或去 D1 控制台执行:
DELETE FROM login_attempts WHERE ip = '你的IP';几乎一定是 D1 绑定问题:
- 确认 Workers & Pages → 你的 Worker → 设置 → 变量 → D1 数据库绑定中变量名为
WUYA(全大写)。 - 确认数据库已选中并保存部署。
- 仍未解决,查看 Worker 日志(Cloudflare Dashboard → 你的 Worker → Logs),寻找
数据库初始化失败字样。
旧版本存在初始化自举缺陷:全新空库上,首次访问在读取迁移门控时就会因 settings 表不存在而失败,导致每个请求 500,且无法自愈。更新到最新代码后,首次访问会自动建表(幂等 DDL),无需手动干预。仍停留在旧版本的话,可临时在 D1 控制台执行仓库内 src/db/migrations/0001_initial.sql 完成建表。
wrangler.toml 中 database_id 没替换。先运行 pnpm dlx wrangler d1 create wuya-db 拿到真实 UUID,填入后重新 pnpm deploy。
- 确认 Cron 表达式是
0,30 * * * *(每 30 分钟),与wrangler.toml的[triggers] crons一致。 - Cloudflare Dashboard → 你的 Worker → Triggers → Cron Triggers 中能看到该触发器。
- 查看实时日志,每次触发应出现
定时任务开始:正在初始化...。 - 若日志显示
Cannot run scheduled ... settings are missing,说明 CF 或 GitHub 凭据未配置。
访问的路径不在白名单中。白名单由 ip_sources.github_path 已登记路径及其派生伴生路径组成:在后台 IP 源管理页确认路径拼写完全一致(区分大小写);想读 IPv6 伴生文件,请用派生路径(IP/x.txt → IP/x-v6.txt),不要自己拼其它 -v6 形态。若源从未解析出 IPv6,说明远端伴生文件被删除了,404 属正常。
单类型记录上限(MAX_IPS_PER_TYPE,默认 20)对所有来源统一生效,超出的 A/AAAA 记录会在同步时被删除(CNAME 不截断)。这是既定行为,不是数据丢失;需要更多记录就把上限调到最大 200,见 单类型记录上限。
升级到这个版本后,有两处行为变化会在下一次同步时自动生效,升级前请确认可以接受:
- 存量域名可能被裁减记录。 单类型记录上限(
MAX_IPS_PER_TYPE,默认 20)不再只作用于新来源,而是对所有 IP 来源统一生效。某个目标的源站单类型原本超过 20 条时,下一轮同步会删除超出部分的 A/AAAA 记录(CNAME 不截断)。需要保留更多记录,请先把上限调到 200 再同步。 - 存量 IP 源可能新增伴生文件。 默认解析模式
auto会同时识别 IPv4 与 IPv6。若某个存量源实际上能解析出 IPv6,它的 GitHub 仓库里会出现派生的-v6伴生文件。主文件内容不受影响——主文件恒为 IPv4 列表,且内容与远端一致时不发 PUT(逐字节不变)。
- 迁移随代码升级自动执行:
MIGRATION_VERSION变化后,已部署实例的首次请求就会补齐缺失列,不受 24 小时门控影响,无需手动执行 SQL。 - 新增列全部可空(
domains.source_type/source_url/parse_mode/parse_param/fetch_strategy,ip_sources.parse_mode/parse_param),NULL即默认语义,存量数据不需要回填。 - 迁移幂等:重复执行不报错;同一份库再跑一次不会产生副作用。
- 回滚只需回退代码:多余列对旧代码无影响(列表接口用显式列投影,同步路径
SELECT *对多余列无感知)。
想先观察再放开的话,按这个顺序:
- 升级代码(迁移自动完成)。
- 到 系统设置 → DNS 记录设置 把「单类型记录上限」先调到一个不低于你现有最大记录数的值(最大 200)。
- 跑一轮手动同步,确认没有非预期的记录删除。
- 再把上限逐步收敛到目标值。
本项目/本教程中的所有代码和信息仅供学习和研究之用。
- 请勿用于商业或非法目的,否则后果自负。
- 代码来源于互联网,如有侵权请联系删除。
- 项目作者不对任何因使用本项目代码而导致的任何损失或法律纠纷承担责任。
- 使用本项目代码即表示您同意并接受本声明。
请在遵守您当地法律法规的前提下使用。

