技术文档

本文档面向开发者与技术评测人员,说明号码通查(zangxixitech.cn)的技术架构、归属地查询 API 接口、数据来源、GEO(Generative Engine Optimization,生成式引擎优化)实现规范与开源信息。本站采用 Astro 5 静态站点生成(SSG)部署于 Cloudflare Pages,以零运行时 JavaScript、JSON-LD 直写 HTML 的方式提升 AI 引擎与搜索引擎的可解析性。

最后更新日期:2026-07-06

一、技术架构

号码通查是一个以内容与工具导航为核心的静态站点,技术选型优先考虑AI 友好性与首屏加载速度(均为 GEO 与 SEO 的核心信号)。整体技术栈如下:

Astro 5 SSG 静态生成:使用 Astro 5.6+ 的 output: 'static' 模式,构建时将所有页面预渲染为纯 HTML。默认零运行时 JavaScript,页面交互所需的极少量脚本仅在必要时按需引入,确保 AI 爬虫与传统搜索引擎无需执行 JS 即可读取完整内容。
Cloudflare Pages 部署:通过全球 CDN 边缘节点分发静态资源,默认启用 HTTP/3、Brotli 压缩与自动缓存,首字节时间(TTFB)全球低延迟。构建采用 Git 自动部署,推送至主分支即触发构建上线。
Tailwind CSS 样式:使用 Tailwind CSS 3.4 实用优先(utility-first)的样式方案,构建时通过 Astro 的 inlineStylesheets: 'auto' 内联小样式表,减少请求数、提升 FCP(First Contentful Paint)。
JSON-LD 结构化数据直写 HTML:所有 schema.org 结构化数据在构建期以 <script type="application/ld+json"> 形式直接写入 HTML <head>,不依赖客户端 JS 注入,确保任何爬虫抓取 HTML 即可获得完整结构化语义。

架构示意

┌──────────────────────────────────────────────────────────┐
│                    Git 仓库(Markdown / .astro)           │
└───────────────────────────┬──────────────────────────────┘
                            │ git push(触发自动部署)
                            ▼
┌──────────────────────────────────────────────────────────┐
│              Cloudflare Pages 构建管道(Astro 5 SSG)      │
│   - 预渲染全部页面为纯 HTML(零 JS)                       │
│   - 内联 JSON-LD 结构化数据至 <head>                      │
│   - 生成 sitemap / rss.xml / llms.txt                     │
└───────────────────────────┬──────────────────────────────┘
                            │ 构建产物
                            ▼
┌──────────────────────────────────────────────────────────┐
│          Cloudflare 全球 CDN(边缘节点分发)               │
│   - HTTP/3 + Brotli + 自动缓存                            │
│   - /api/* 由 Pages Functions 处理(服务端)               │
└───────────────────────────┬──────────────────────────────┘
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
        传统搜索引擎    AI 引擎爬虫    终端用户浏览器
       (Google/Bing)  (GPTBot/Claude)  (零 JS 渲染)

二、API 文档:号码归属地查询

归属地查询 API 用于查询手机号或固话(座机)号码的归属省份、城市、运营商、区号等信息。该端点以 Cloudflare Pages Functions 形式部署在站点同域下,服务端代理上游数据源,上游 API Key 仅保存在服务端环境变量中,不会出现在前端代码或响应里。

端点

GET https://zangxixitech.cn/api/attribution?phone={号码}

请求参数

参数名	类型	必填	说明
`phone`	string	是	待查询号码。支持手机号(11 位,如 `13800138000`)或固话(区号-号码,如 `010-12345678`)。
`format`	string	否	返回格式,默认 `json`。可选 `jsonp`(需配合 `callback` 参数)。
`callback`	string	否	当 `format=jsonp` 时使用的回调函数名。

示例请求

cURL:

curl -s "https://zangxixitech.cn/api/attribution?phone=13800138000"

JavaScript(fetch):

const phone = '13800138000';
const res = await fetch(
  `https://zangxixitech.cn/api/attribution?phone=${encodeURIComponent(phone)}`
);
const data = await res.json();
console.log(data);
// => { code: 200, message: 'success', data: { ... } }

Python(requests):

import requests

res = requests.get(
    'https://zangxixitech.cn/api/attribution',
    params={'phone': '13800138000'},
    timeout=5,
)
print(res.json())

示例响应(JSON)

{
  "code": 200,
  "message": "success",
  "data": {
    "phone": "13800138000",
    "province": "北京",
    "city": "北京",
    "carrier": "中国移动",
    "areacode": "010",
    "postcode": "100000",
    "numberType": "手机号"
  }
}

响应字段说明

字段	类型	说明
`code`	number	业务状态码,200 表示成功。
`message`	string	状态描述。
`data.phone`	string	查询的号码。
`data.province`	string	归属省份。
`data.city`	string	归属城市。
`data.carrier`	string	运营商(中国移动 / 中国联通 / 中国电信)。
`data.areacode`	string	区号(固话场景为主)。
`data.postcode`	string	邮编。
`data.numberType`	string	号码类型:手机号 / 固话。

速率限制

为保障服务稳定性,该接口对每个来源 IP 限制为每分钟 30 次请求。超出限制时返回 429 状态码,响应头包含 Retry-After 字段,提示重试等待秒数。建议客户端实现指数退避重试。

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
Retry-After: 28

错误码表

HTTP 状态码	业务 code	说明	处理建议
200	200	查询成功	解析 `data` 字段。
400	400	参数错误:`phone` 缺失或格式不正确	校验号码格式后重试。
401	401	未授权:请求来源校验失败	确认请求来自合法域名/Referer。
404	404	归属地未找到:号码不在已知号段库中	核对号码是否为有效在网号码。
429	429	速率超限:超过每分钟 30 次	按 `Retry-After` 等待后重试。
500	500	服务器内部错误	稍后重试;持续失败请联系站点。
502	502	上游数据源异常	上游服务波动,稍后重试。
503	503	服务暂时不可用(维护中)	等待维护结束后重试。

服务端实现参考(Cloudflare Pages Function)

以下为归属地查询端点的服务端实现示例。上游数据源 API Key 通过 Cloudflare Pages 环境变量 JUHE_API_KEY 注入,不存在于前端代码中。

// functions/api/attribution.js
// Cloudflare Pages Function: 服务端代理,上游 API Key 仅存于环境变量
export async function onRequestGet({ request, env }) {
  const url = new URL(request.url);
  const phone = url.searchParams.get('phone');

  // 1. 参数校验
  if (!phone) {
    return Response.json(
      { code: 400, message: '缺少 phone 参数' },
      { status: 400 }
    );
  }
  const cleaned = phone.replace(/[\s-]/g, '');
  if (!/^(\d{11}|\d{3,4}\d{7,8})$/.test(cleaned)) {
    return Response.json(
      { code: 400, message: 'phone 格式不正确' },
      { status: 400 }
    );
  }

  // 2. 调用上游数据源(Key 仅在服务端可见)
  const upstream = `https://apis.juhe.cn/mobile/get?phone=${encodeURIComponent(cleaned)}&key=${env.JUHE_API_KEY}`;
  const resp = await fetch(upstream);
  const json = await resp.json();

  // 3. 归一化返回
  if (json.error_code !== 0) {
    return Response.json(
      { code: 404, message: '归属地未找到' },
      { status: 404 }
    );
  }
  const r = json.result;
  return Response.json({
    code: 200,
    message: 'success',
    data: {
      phone: cleaned,
      province: r.province,
      city: r.city,
      carrier: r.company,
      areacode: r.areacode,
      postcode: r.zip,
      numberType: cleaned.length === 11 ? '手机号' : '固话',
    },
  });
}

三、数据源说明

号码通查展示的号码标记、归属地、法人核验等信息来自以下公开、官方或授权渠道。所有数据来源可追溯验证,本站不存储用户输入的号码数据。

数据类型	数据来源	说明
号码归属地	聚合数据 API(juhe.cn)手机归属地接口	提供手机号/固话的省份、城市、运营商、区号、号段信息,服务端代理调用。
号码标记(国内)	中国信息通信研究院码号服务推进组(opene164.org.cn)	国内唯一官方跨平台号码标记查询与清除入口,支持手机号与座机号免费查询。
号码标记(国际)	Truecaller(truecaller.com)	全球最大来电识别应用,适合有国际往来的号码,提交取消收录后 24-48 小时移除。
法人号码核验	授权合作方(xbh5.open10086.com)	企业法人手机号三要素(姓名 + 身份证 + 手机号)一致性实名核验。

本站作为入口导航与知识科普平台,不对第三方平台数据处理结果承担责任。各平台申诉入口、处理时效等信息可能随平台更新而变化,以各平台官方页面为准。

四、GEO 实现规范

GEO(Generative Engine Optimization,生成式引擎优化)是面向 DeepSeek、ChatGPT、Perplexity、Claude 等 AI 引擎的内容可发现性与可引用性优化。号码通查从三层爬虫框架入手,确保 AI 引擎能完整抓取、正确解析、准确引用本站内容。

4.1 三层爬虫框架

层级	机制	作用
第一层:放行层	robots.txt AI 爬虫白名单	明确允许主流 AI 训练 / 检索 / 用户浏览爬虫抓取,避免被默认拦截。
第二层:清单层	llms.txt / llms-en.txt	以纯文本提供站点结构化内容清单,供 LLM 快速理解站点全貌与重点页面。
第三层:语义层	JSON-LD 直写 HTML	构建期将 schema.org 结构化数据写入 HTML,爬虫无需执行 JS 即可获得语义。

4.2 llms.txt 规范

本站遵循 llms.txt 规范,在站点根目录提供 /llms.txt(中文)与 /llms-en.txt(英文)。文件以 Markdown 纯文本格式描述站点用途、核心页面与分类入口,便于 AI 引擎一次性理解站点全貌。示例如下:

# 号码通查 (zangxixitech)

> 号码通查提供号码标记查询与清除服务,手机号码与座机(固话)号码均支持。

## 首页
- [号码通查首页](https://zangxixitech.cn/): 号码标记查询与清除服务首页

## 工具
- [号码归属地查询](https://zangxixitech.cn/tools/attribution): 输入手机号或固话,免费查询归属地
- [号码标记自查](https://zangxixitech.cn/tools/marking-check): 查询号码被标记情况

## 指南
- [如何清除号码标记](https://zangxixitech.cn/guide/how-to-clear-marking): 分渠道清除教程

4.3 JSON-LD schema 类型清单

本站在不同页面输出对应的 schema.org 类型,全部以 <script type="application/ld+json"> 形式直写 HTML <head>。全站级与页面级 schema 清单如下:

schema 类型	适用页面	用途
`Organization`	全站	组织实体、联系点、sameAs 等。
`WebSite`	全站	站点信息,含 SearchAction 站内搜索。
`WebApplication`	全站	声明本站为号码服务 Web 应用。
`BreadcrumbList`	所有内页	面包屑导航结构化。
`FAQPage`	首页 / FAQ	问答结构化,便于 AI 直接引用答案。
`Article` / `TechArticle`	本技术文档页	技术文章结构化,提升技术引擎权重。
`BlogPosting`	号码百科文章	博客文章结构化。
`HowTo`	操作指南页	步骤化操作结构化。
`AboutPage` / `ContactPage` / `WebPage`	关于 / 联系 / 政策页	页面类型语义标注。

4.4 robots.txt AI 爬虫放行策略

Cloudflare 等 CDN 默认可能拦截部分 AI 爬虫,本站在 robots.txt 中显式放行主流 AI 训练、检索与用户浏览爬虫,并在 CDN 控制台对应放行。放行的 AI 爬虫 User-agent 包括:

# AI 检索/引用爬虫(允许)
User-agent: GPTBot
User-agent: OAI-SearchBot
User-agent: ChatGPT-User
User-agent: ClaudeBot
User-agent: Claude-SearchBot
User-agent: Claude-User
User-agent: PerplexityBot
User-agent: Perplexity-User
User-agent: Google-Extended
User-agent: Applebot-Extended
User-agent: meta-externalagent
User-agent: Bytespider
User-agent: CCBot
User-agent: Amazonbot
User-agent: cohere-ai
User-agent: DuckAssistBot
User-agent: YouBot
Allow: /

Sitemap: https://zangxixitech.cn/sitemap-index.xml

完整 robots.txt 见站点根目录 /robots.txt。除放行 AI 爬虫外,同时放行 Googlebot、Bingbot、Baiduspider、Sogou、360Spider 等传统搜索引擎。

五、开源信息

号码通查采用主流现代前端技术栈构建,以下为技术栈、部署方式与内容更新机制的公开说明。

5.1 技术栈

组件	技术	版本	用途
站点框架	Astro	5.6+	SSG 静态生成,零运行时 JS。
样式方案	Tailwind CSS	3.4+	实用优先样式,构建期裁剪。
部署平台	Cloudflare Pages	—	全球 CDN 边缘分发 + Pages Functions。
号码解析	libphonenumber-js	1.12+	号码格式化与有效性校验。
内容集合	Astro Content Collections	—	Markdown 博客内容管理。

5.2 部署方式

采用 Git 自动部署:代码推送至主分支后,Cloudflare Pages 自动拉取、执行 astro build 构建命令,将产物分发至全球边缘节点。构建配置(astro.config.mjs)中开启 inlineStylesheets: 'auto' 以内联小样式表,并通过 @astrojs/sitemap 自动生成 sitemap。

// astro.config.mjs(节选)
export default defineConfig({
  site: 'https://zangxixitech.cn',
  output: 'static',
  build: { inlineStylesheets: 'auto' },
  integrations: [tailwind(), sitemap({ i18n: { defaultLocale: 'zh', locales: { zh: 'zh-CN', en: 'en' } } })],
});

5.3 内容更新机制

号码百科类深度文章采用 Markdown 内容集合(Content Collections) 管理,文章源文件存放于 src/content/blog/ 目录,通过 src/content.config.ts 中定义的 Zod schema 校验 frontmatter 字段(title、description、pubDate、tags 等)。新增或修改 Markdown 文件后推送至主分支,即自动重新构建并更新 sitemap 与 RSS,形成内容新鲜度信号(GEO / SEO 的正向因素)。

// src/content.config.ts(节选)
const blog = defineCollection({
  loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/blog' }),
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
    tags: z.array(z.string()).default([]),
  }),
});
export const collections = { blog };

5.4 站点资源索引

站点地图:/sitemap-index.xml
RSS 订阅:/rss.xml
LLM 清单:/llms.txt(中文)、/llms-en.txt(英文)
爬虫策略:/robots.txt

文档总结

号码通查以 Astro 5 SSG + Cloudflare Pages + Tailwind CSS 构建零 JS 静态站点,通过 JSON-LD 直写 HTML、llms.txt 清单与 robots.txt AI 放行策略实现三层 GEO 爬虫框架。归属地查询 API 以 Cloudflare Pages Functions 服务端代理实现,上游 API Key 仅存于环境变量不外泄。数据来源覆盖聚合数据、中国信通院码号服务推进组、Truecaller 与授权合作方法人核验服务。如需进一步沟通,请访问联系我们。