One IP 是一个集 IP 查询、网络诊断、浏览器检测和 AI 服务状态于一体的工具箱

📋 项目简介

One IP 是一个集 IP 查询、网络诊断、浏览器检测和 AI 服务状态于一体的工具箱。它的最大特点是统一部署：前端静态文件与 API 由同一个 Cloudflare Worker 提供，无需单独部署 Node 服务或 Docker 容器。

主要功能模块：

模块	功能
首页	IPv4/IPv6 出口、分流汇总、网络连通性、浏览器指纹、WebRTC、AI 访问与服务状态
IP 信息	公网 IP 归属地、运营商、ASN、地图、多源对比及可选风险信息
WHOIS	域名、IP、ASN 的 RDAP 注册信息
网络诊断	网站分流、HTTP 连通性、全球 ICMP Ping、DNS 出口和 CDN 命中节点
浏览器检测	环境信息、指纹、环境一致性、自动化特征、权限隐私与验证码体验
AI 平台	ChatGPT、Claude、Gemini、DeepSeek、Grok、Perplexity、通义千问和 Kimi 的访问检测
服务状态	聚合官方数据，按分类展示运行情况

🎯 部署方式概览

One IP 提供两种部署方式：

GitHub Actions 自动部署（推荐）——推送代码后自动构建并部署到 Cloudflare Workers
本地命令部署——在自己电脑上手动执行部署命令

⚠️ 重要说明：虽然工作流文件名为 pages.yml，但实际部署目标是 Cloudflare Workers + Static Assets，不是 GitHub Pages 或 Cloudflare Pages。

一、前置准备

1.1 注册 Cloudflare 账号

如果你还没有 Cloudflare 账号，请先前往 cloudflare.com 注册。

1.2 获取 Cloudflare Account ID

登录 Cloudflare Dashboard
进入 Workers & Pages 页面
在右侧边栏可以看到 Account ID，复制保存备用

1.3 创建 Cloudflare API Token

登录 Cloudflare Dashboard
点击右上角头像 → My Profile → API Tokens
点击 Create Token
选择 Edit Cloudflare Workers 模板（或自定义模板，确保具备 Workers 编辑权限）
配置权限：
- Account → Workers Scripts → Edit
- Account → Workers KV Storage → Edit（如需）
- Zone → Workers Routes → Edit（如需自定义域名）
创建后立即复制 Token（只显示一次），妥善保存

二、方式一：GitHub Actions 自动部署（推荐）

2.1 Fork 或导入项目

方式 A：Fork 仓库

打开 https://github.com/zhihui-hu/one-ip
点击右上角 Fork 按钮
选择你的 GitHub 账号，等待 Fork 完成

方式 B：导入为私有仓库

在 GitHub 点击 New repository
选择 Import a repository
填入源地址 https://github.com/zhihui-hu/one-ip
设置仓库名称（如 one-ip），选择公开或私有
点击 Begin import

💡 提示：默认部署分支为 main，请确保你的仓库主分支名为 main。

2.2 配置 GitHub Secrets

进入你 Fork/导入的仓库
点击 Settings → Secrets and variables → Actions
点击 New repository secret，依次添加以下两个 Secret：

Secret 名称	用途	获取方式
`CLOUDFLARE_API_TOKEN`	Cloudflare Workers 部署凭证，需具备 Workers 编辑权限	见 1.3 节
`CLOUDFLARE_ACCOUNT_ID`	目标 Cloudflare 账户 ID	见 1.2 节

添加步骤：

点击 New repository secret
Name 填入 CLOUDFLARE_API_TOKEN
Secret 粘贴你的 API Token
点击 Add secret
重复以上步骤添加 CLOUDFLARE_ACCOUNT_ID

2.3 触发部署

方式 A：推送触发

对 main 分支进行任意推送（如修改 README），工作流会自动触发：

git clone https://github.com/你的用户名/one-ip.git
cd one-ip
# 做一些修改，例如更新 README
git commit -am "trigger deploy"
git push origin main

方式 B：手动触发

进入仓库的 Actions 标签页
左侧选择 Build and deploy one-ip 工作流
点击右侧 Run workflow → 选择 main 分支 → Run workflow

2.4 查看部署结果

工作流会依次执行以下步骤：

✅ 安装依赖（pnpm install --frozen-lockfile）
✅ 构建（make build）
✅ 测试（make test）
✅ 部署到 Cloudflare Workers

获取部署地址：

查看 Actions 日志中输出的部署 URL
或登录 Cloudflare Dashboard → Workers & Pages → 找到名为 one-ip 的 Worker → 查看其 *.workers.dev 域名

2.5 部署行为说明

场景	行为
首次部署	自动创建名为 `one-ip` 的 Worker
后续推送	更新同名 Worker
Pull Request	只构建和测试，不部署
构建/测试失败	不进入部署步骤

三、方式二：本地命令部署

适合需要精细控制、或不想使用 GitHub Actions 的用户。

3.1 环境要求

依赖	版本要求	说明
Node.js	24	必须为 24.x
pnpm	10.32.1	与 CI 保持一致
Make	最新版	Windows 用户建议使用 WSL 或 Git Bash

安装 Node.js 24：

推荐使用 nvm 或 fnm：

# 使用 nvm
nvm install 24
nvm use 24

# 或使用 fnm
fnm install 24
fnm use 24

安装 pnpm 10.32.1：

1	npm install -g pnpm@10.32.1

验证版本：

1 2	node -v # 应输出 v24.x.x pnpm -v # 应输出 10.32.1

3.2 克隆项目

1 2	git clone https://github.com/zhihui-hu/one-ip.git cd one-ip

3.3 安装依赖

1	pnpm install --frozen-lockfile

3.4 登录 Cloudflare

1	pnpm exec wrangler login

执行后会：

自动打开浏览器
跳转到 Cloudflare 授权页面
点击 Allow 授权 Wrangler 访问你的账号
终端显示登录成功

验证登录状态：

1	pnpm exec wrangler whoami

3.5 部署到生产环境

1	make deploy

该命令会：

按上海时间更新版本号
构建项目（make build）
部署到 Cloudflare Workers（Worker 名称：one-ip）

3.6 本地开发调试

1	make worker-dev

启动后访问 http://127.0.0.1:8787/

该命令同时启动：

Vite 开发服务器（端口 5137）：处理页面和 HMR WebSocket 热更新
Worker（端口 8787）：处理 API 请求

💡 修改前端代码即可热更新，无需提前构建。

不使用 Make 的替代命令：

1 2	pnpm worker:dev # 同时启动前端与 Worker pnpm dev # 仅启动前端（API 仍需本地 Worker）

3.7 常用命令速查

命令	说明
`make worker-dev`	同时启动前端与 Worker
`make build`	TypeScript 检查与生产构建，输出到 `dist`
`make test`	Worker dry-run 与自动化测试（需先构建）
`make deploy`	构建并部署到生产环境
`pnpm lint`	静态代码检查
`pnpm preview`	预览前端构建产物（不启动 Worker API）
`pnpm worker:types`	生成 Worker 环境类型
`pnpm browser:build`	重建本地浏览器深度检测脚本

完整检查流程：

1
2
3

make build
make test
pnpm lint

四、配置说明

4.1 基础配置（无需密钥）

基础查询和公开数据源通常无需配置密钥。以下功能开箱即用：

IP 归属地查询（浏览器直连 IP.SB / IPWhois）
WHOIS / RDAP 查询
网络诊断（Ping、DNS、CDN）
浏览器指纹检测
AI 平台访问探测
服务状态聚合

4.2 高级配置（可选）

高级风险查询、验证码体验等功能需要按需启用。

4.2.1 本地开发配置

复制示例文件：

1	cp .dev.vars.example .dev.vars

编辑 .dev.vars，填入配置：

配置项	用途
`TURNSTILE_SITE_KEY` / `TURNSTILE_SECRET`	Cloudflare Turnstile 站点密钥与服务端密钥
`TURNSTILE_HOSTNAMES`	Turnstile 允许的 hostname，逗号分隔
`RECAPTCHA_SITE_KEY` / `RECAPTCHA_SECRET`	Google reCAPTCHA v3 评分型密钥
`RECAPTCHA_HOSTNAMES`	reCAPTCHA 允许的 hostname，逗号分隔
`VITE_API_BASE_URL`	前端 API 地址，默认 `/api`

⚠️ 注意事项：

hostname 只填主机名，不含协议或端口，需与验证码服务商后台配置一致

TURNSTILE_SITE_KEY、RECAPTCHA_SITE_KEY 可留空；未填写时显示未配置提示

填写 Site Key 后，如服务端 Secret 缺失或 hostname 不匹配，组件会显示不可用

4.2.2 生产环境配置

公开配置（放在 wrangler.toml 的 [vars] 中）：

[vars]
TURNSTILE_SITE_KEY = "你的站点密钥"
TURNSTILE_HOSTNAMES = "your-domain.com"
RECAPTCHA_SITE_KEY = "你的站点密钥"
RECAPTCHA_HOSTNAMES = "your-domain.com"

敏感密钥（使用 Worker Secrets）：

1 2	pnpm exec wrangler secret put TURNSTILE_SECRET --env="" pnpm exec wrangler secret put RECAPTCHA_SECRET --env=""

⚠️ 重要：

仅设置实际使用的密钥

生产 hostname 不应包含 localhost 或 127.0.0.1

不要将密钥放入 VITE_*，这些值会进入前端产物

4.2.3 项目内管理正式环境密钥（本地部署）

复制示例文件：

1	cp .secrets.example .secrets.production.env

填入对应环境的 Secret（这些文件已被 Git 忽略）
make deploy 会自动：
- 先检查本地配置
- 构建部署后通过标准输入上传非空密钥
- 不在日志中显示密钥值
- 不删除已有的其他 Secret

仅检查、不上传：

1	node scripts/sync-worker-secrets.mjs production --check

单独重试密钥同步：

1	node scripts/sync-worker-secrets.mjs production

⚠️ 说明：

部署与 Secrets 同步是两个步骤；同步失败会报错，已部署的代码不会自动回滚

这里只接入本地 Make 部署；GitHub Actions 不会读取未提交的文件

CI 部署需要单独使用 GitHub Secrets，或保留已上传的 Worker Secrets

4.2.4 reCAPTCHA v3 特别说明

Google 验证体验使用 reCAPTCHA v3：

前端执行 browser_check action
服务端校验 hostname、action 和 0–1 范围的 score
当前体验通过阈值为 0.5
必须使用配套的 v3 Site Key 与 Secret

五、自定义域名配置

默认部署后，Worker 会分配一个 *.workers.dev 子域名。如需使用自定义域名：

5.1 前提条件

域名已添加到 Cloudflare（NS 已指向 Cloudflare）
域名处于 Active 状态

5.2 配置步骤

登录 Cloudflare Dashboard
进入 Workers & Pages → 选择 one-ip Worker
点击 Settings → Triggers → Custom Domains
点击 Add Custom Domain
输入你的域名（如 ip.example.com）
点击 Add Custom Domain，Cloudflare 会自动配置 DNS 和证书

⚠️ 注意：从旧 Worker 更名到 one-ip 不会迁移其密钥和域名，也不会删除旧项目。

六、验证码服务商配置

6.1 Cloudflare Turnstile

登录 Cloudflare Dashboard
进入 Turnstile 页面
点击 Add Site
填写：
- Site name：任意名称
- Domain：你的域名（如 ip.example.com）
- Widget Mode：选择 Managed 或 Non-Interactive
创建后获得 Site Key 和 Secret Key
将 Site Key 填入 wrangler.toml 的 TURNSTILE_SITE_KEY
将 Secret 通过 wrangler secret put TURNSTILE_SECRET 上传

6.2 Google reCAPTCHA v3

访问 Google reCAPTCHA 管理后台
点击 + 创建新站点
填写：
- Label：任意名称
- reCAPTCHA type：选择 reCAPTCHA v3
- Domains：你的域名
提交后获得 Site Key 和 Secret Key
将 Site Key 填入 wrangler.toml 的 RECAPTCHA_SITE_KEY
将 Secret 通过 wrangler secret put RECAPTCHA_SECRET 上传

⚠️ 重要：reCAPTCHA v3 与 v2 不兼容，必须使用 v3 的密钥。

七、常见问题排查

7.1 部署失败

问题：Actions 报错 CLOUDFLARE_API_TOKEN not found

检查 GitHub Secrets 是否正确添加
Secret 名称必须完全匹配：CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID

问题：API Token 权限不足

重新创建 Token，确保包含：
- Account → Workers Scripts → Edit
- Account → Workers KV Storage → Edit
- Zone → Workers Routes → Edit

7.2 本地开发问题

问题：pnpm install --frozen-lockfile 失败

检查 Node.js 版本是否为 24.x
检查 pnpm 版本是否为 10.32.1
删除 node_modules 和 pnpm-lock.yaml 后重试

问题：make worker-dev 后访问 8787 无响应

检查端口 8787 和 5137 是否被占用
确认 Worker 已成功启动（查看终端日志）

问题：Windows 上 make 命令不可用

使用 WSL（Windows Subsystem for Linux）
或使用 Git Bash 并安装 make
或直接使用 pnpm worker:dev 替代

7.3 验证码不工作

问题：Turnstile 组件显示“未配置”

检查 TURNSTILE_SITE_KEY 是否填入 wrangler.toml
检查 TURNSTILE_SECRET 是否通过 wrangler secret put 上传

问题：Turnstile 显示不可用

检查 hostname 是否匹配（不含协议和端口）
检查验证码服务商后台是否允许该域名
检查 Secret 是否正确上传

问题：reCAPTCHA v3 评分过低

确保使用 v3 密钥（非 v2）
确保 hostname 与后台配置一致
当前阈值为 0.5，低于此值会验证失败

7.4 自定义域名问题

问题：添加自定义域名失败

确认域名已添加到 Cloudflare 且状态为 Active
确认域名 NS 已指向 Cloudflare
检查 Worker 是否有权限使用该域名

八、使用说明

8.1 功能入口

一级入口	页面与路由
概览	`/`：当前网络与浏览器概览
网络检测	`/network/ip`、`/network/whois`、`/network/connectivity`、`/network/ping`、`/network/dns`、`/network/cdn`
浏览器检测	`/browser/environment`、`/browser/fingerprint`、`/browser/consistency`、`/browser/automation`、`/browser/privacy`、`/browser/challenges`
AI 检测	`/ai/gpt`、`/ai/claude`、`/ai/gemini`、`/ai/deepseek`、`/ai/grok`、`/ai/perplexity`、`/ai/qwen`、`/ai/kimi`
服务状态	`/status`，OpenAI / Claude 详情为 `/status/openai`、`/status/claude`

兼容性：旧的 /ip、/query/*、/webrtc、/gpt、/claude 等入口会自动跳转，保留查询参数与锚点。

8.2 探测方式说明

首页和 AI 详情使用同一套探测逻辑，从访问者浏览器直接请求目标域名：

平台	探测资源	结果含义
Claude、Perplexity	各自域名的 `/cdn-cgi/trace`	读取并校验边缘网络响应，不证明源站、登录或对话可用
Gemini	`gemini.google.com/robots.txt`	检测同域资源响应，避免使用返回 404 的图标地址
其他平台	当前配置域名的 `/favicon.ico`	检测资源响应；不等同于账号或模型权限检查

单次等待上限 6 秒，失败后再试一次
探测失败显示“未确认”，不会直接判定网站打不开
跨域不透明响应也不能用于判断 HTTP 状态码

8.3 结果解读要点

HTTP 耗时不等于 ICMP 延迟。收到响应也不代表登录、对话或模型 API 可用。
未知不等于故障。跨域策略、网络超时、未公开的响应头和数据源限制都可能导致未知。
地理位置是估计值。IP 数据库可能有更新延迟，不能据此确定设备精确位置。
DNS 出口不等于设备配置地址。安全 DNS、代理远程解析及系统设置都会影响结果。
浏览器信号不是身份或风险结论。指纹 ID、自动化信号和一致性结果不能独立证明真人、机器人或验证码通过率。

九、数据与隐私

本地存储：IP / WHOIS 历史、主题和说明关闭状态保存在当前浏览器，清除站点数据可移除
网络检测：会访问相应的第三方站点
IP 查询：首页和分流的归属查询由浏览器直连 IP.SB（api.ip.sb），失败后使用 IPWhois（ipwho.is）
Worker 请求：IP 详情的多源查询、RDAP、Globalping 和官方状态等 API 由 Worker 请求对应服务
指纹计算：FingerprintJS 在浏览器本地计算，不向业务后端上传指纹
验证码：脚本在用户点击体验后加载，凭证由 Worker 提交给服务商校验

十、项目结构参考

text

src/
  components/          通用 UI、响应式弹窗、底部玻璃导航、表格与动画
  hooks/               检测与本地历史逻辑
  layout/              导航与路由分组
  views/               首页、网络、浏览器、AI 与服务状态
public/worker/         Cloudflare Worker API
vendor/browser-diagnostics/  浏览器深度检测来源与许可证
scripts/               开发服务与资源构建脚本
tests/                 自动化测试
make/                  开发、版本和部署命令
.github/workflows/     CI 与 Worker 部署
wrangler.toml          Worker 与静态资源配置