# DNS工具 **Repository Path**: zhuxbo/dns-tools ## Basic Information - **Project Name**: DNS工具 - **Description**: 用于ssl证书验证的dns工具 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-07-12 - **Last Updated**: 2025-11-06 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # DNS Tools 一个简单高效的 DNS 工具集，提供域名验证、DNS 查询、WHOIS 查询和链接内容获取功能。 ## 功能特性 - **域名验证**: CAA 记录验证，支持多个证书品牌 - **DNSSEC 检测**: 自动检测域名的 DNSSEC 状态，提供安全风险提示 - 使用 Google Public DNS (8.8.8.8/8.8.4.4) 作为解析器 - 支持 UDP/TCP 自动切换（TC=1 回退） - 对比 CD=0/CD=1 查询判定 DNSSEC 状态（Secure/Insecure/Bogus/Indeterminate） - 仅作提示不阻止验证（符合当前 CA 行业现状） - **DNS 查询**: 支持 A、AAAA、CNAME、MX、TXT、NS、CAA 记录查询 - **WHOIS 查询**: 域名注册信息查询，支持 EPP 状态码标准化和中英文显示 - **链接查询**: 获取网站内容，同时测试 HTTP 和 HTTPS 协议 - **批量 DCV 验证**: 支持 DNS TXT/CNAME、HTTP/HTTPS、FILE 多种验证方式 - **多区域部署**: 支持部署到多个地理区域，自动识别当前区域 - **响应式设计**: 支持桌面和移动设备访问 ### 规则与兼容 - **CAA 检测规则**： - **普通域名**：始终检查"被检测域名的根域"（无论是否存在 CNAME 链） - 例如：`abc.cde.com` → 检查 `abc.cde.com` 和 `cde.com` - 例如：`abc.cde.com` CNAME 到 `target.other.com` → 检查 `abc.cde.com`、`cde.com`、`target.other.com`（不检查 `other.com`） - **通配符域名**： - 根域名通配符（如 `*.example.com`）：只检查 `example.com`，优先匹配 `issuewild`，回退 `issue` - 子域名通配符（如 `*.sub.example.com`）：检查 `sub.example.com`（`issuewild`/`issue`）和 `example.com`（`issue`） - **CAA 标签优先级**： - 普通域名：仅检查 `issue` 标签 - 通配符域名：优先检查 `issuewild`，不存在时回退检查 `issue` - **支持的 CA 品牌及 CAA 值**： - `certum`: `certum.pl`, `certum.eu` - `sectigo`: `sectigo.com`, `comodoca.com`, `comodo.com`（Sectigo 前身为 Comodo CA） - `digicert`: `digicert.com` - `globalsign`: `globalsign.com` - `sheca`: `sheca.com` - **域名输入清洗**：后端会自动清洗输入（去空格/控制字符、中文标点 → 英文、从 URL 提取域名、去端口、保留 IDN、保留开头通配符等）。 ## 快速开始 ### 使用 Docker 运行（推荐） 1. 复制环境变量配置文件（可选）： ```bash cp .env.example .env ``` 2. 根据需要修改 `.env` 文件，**特别是在国内网络环境下**： ```bash # 国内用户强烈建议设置为 true 以加速构建 USE_CN_PROXY=true ``` > 💡 **国内用户注意：** > > - 设置 `USE_CN_PROXY=true` 会自动使用： > - 阿里云 Alpine 镜像源（加速系统包下载） > - 国内 Go 代理（加速 Go 依赖下载） > - 首次构建时间从 10+ 分钟降至 3-5 分钟 > - 如需进一步加速 Docker 镜像下载，建议配置 Docker 镜像加速器（见下方） 3. 构建并启动服务： ```bash # 构建镜像并启动服务，监听 18000 端口 docker-compose up --build -d # 健康检查（返回 code=1） curl -s http://localhost:18000/api/health | jq . # 查看日志 docker-compose logs -f # 停止服务 docker-compose down ``` #### 国内环境额外优化（可选） 为了进一步加速 Docker 镜像下载，建议配置 Docker 镜像加速器： ```bash # Linux 系统 sudo tee /etc/docker/daemon.json < Settings -> Docker Engine 中添加上述配置 ``` ### 直接运行（Go 本地构建） ```bash # 构建（Linux/macOS） # 说明：以 cmd/server 为入口构建 server 可执行文件 go build -o server ./cmd/server # 运行（默认端口 18000，使用 Google Public DNS） ./server -port 18000 # 使用不同的 DNS 服务器 DNS_PROVIDER=cloudflare ./server -port 18000 # Cloudflare DNS DNS_PROVIDER=alidns ./server -port 18000 # 阿里 DNS（中国推荐） DNS_SERVERS=1.1.1.1,1.0.0.1 ./server # 自定义 DNS ``` ## 访问地址 - Web 界面: - API 接口: ## API 文档 更多细节与完整示例见：docs/api_responses.md ### 返回格式 - 统一约定： - 成功（HTTP 200）满足其一： - 验证类接口“全部通过”； - 查询类接口“结果不为空”。 - 失败（HTTP 200，code=0）满足其一： - 验证类“全部未通过或部分未通过”； - 查询失败或结果为空。 示例： ```json // 成功 { "code": 1, "data": { /* ... */ } } // 失败（HTTP 200；可选 errors 携带详细项） { "code": 0, "msg": "错误信息总结", "errors": [ /* optional */ ] } ``` ### 主要接口 - `GET /api/health` - 健康检查 - `POST /api/dns/query` - DNS 查询（使用 Google Public DNS 8.8.8.8/8.8.4.4） - 请求：`{"domain":"example.com","type":"A|AAAA|CNAME|MX|TXT|NS|CAA|ALL"}` - 响应（成功）：`{"code":1,"data":{"domain":"example.com","type":"A","records":[...]}}` #### DNS 结果规范化（/api/dns/query） ```text - TXT：按段去首尾引号，并解析反斜杠转义（\"、\\、\DDD 十进制）；多段直接拼接，不额外插入空格。 - CNAME/MX/NS：仅去除末尾点（example.net. → example.net）。 ``` 请求示例： ```bash # 查询 TXT（example）——演示去引号、拼接 curl -s -X POST http://localhost:18000/api/dns/query \ -H 'Content-Type: application/json' \ -d '{"domain":"apple.com","type":"TXT"}' | jq '.data.records[0:3]' # 查询 CNAME（example）——演示去末尾点 curl -s -X POST http://localhost:18000/api/dns/query \ -H 'Content-Type: application/json' \ -d '{"domain":"www.apple.com","type":"CNAME"}' | jq '.data.records' ``` 响应片段示例（节选）： ```json { "code": 1, "data": { "domain": "apple.com", "type": "TXT", "records": [{ "name": "apple.com", "type": "TXT", "ttl": 300, "value": "v=spf1 include:_spf.apple.com ~all" }], "dns_servers": ["8.8.8.8:53", "8.8.4.4:53"] } } ``` 注意：`dns_servers` 字段显示实际使用的 DNS 服务器地址，根据配置动态变化。 - `POST /api/domain/issue-verify` - 签发验证（多域名英文逗号分隔，单个域名也可传） - 请求：`{"brand":"certum","domains":"a.example.com,b.example.com,c.example.com"}` - 成功（全部通过）：`{"code":1,"data":{"brand":"certum","domains":[...],"results":[...],"all_valid":true}}` - 失败（部分/全部未通过）：HTTP 200 + `{"code":0,"msg":"验证失败：x/y 域名未通过","errors":[ /* 每个域的详细结果 */ ]}` - `POST /api/dcv/verify` - 批量 DCV 校验（多方法） - 请求： ```json [ { "domain": "m.pnchwl.cn", "method": "txt", "host": "_certum", "value": "token" }, { "domain": "m.pnchwl.cn", "method": "cname", "host": "_certum", "value": "dst.example.net." }, { "domain": "test5.pzo.cn", "method": "file", "link": "//test5.pzo.cn/.well-known/pki-validation/certum.txt", "name": "certum.txt", "content": "..." } ] ``` - 响应： ```json { "code": 1, "data": { "results": { "m.pnchwl.cn": { "value": "...", "matched": "true" }, "test5.pzo.cn": { "content": "...", "matched": "false" } }, "total": 3, "success": 2, "failed": 1, "duration": 12345, "timestamp": "..." } } ``` - 规则与返回字段： - 通用：比较均忽略大小写（TXT/CNAME/HTTP/HTTPS/FILE）。`results` 的 key 与 `query` 中的域名使用原始输入（不转码）。 - TXT/CNAME： - host 可传 "@"（表示空 host）。 - 子域回落（排除 www）：先查 `host+根域`，不命中再查 `host+子域`；命中其一即 `matched=true`。 - 特例：当 `host` 自身包含点（例如 `_dnsauth.test`，表示已带域名前缀）时，跳过子域回落，仅检查 `host+根域`。 - TXT 去除查询值两侧引号再比较；CNAME 去除最右边的点。 - 返回：`matched`，`value`（实际命中值），`query`（命中的查询名）；失败时还返回 `query_sub`、`value_sub` 便于排查。 - HTTP/HTTPS：返回 `matched` 与 `content`，不返回 `link`。 - FILE： - 成功：返回 `matched`、`content`、`link`（带协议，优先 https）。 - 失败：返回 `matched`、`content`，以及 `link_https` 与 `link_http`（不返回 `link`）。 - 链接类方法在失败时的 `content` 统一按 1000 字符截断（成功不截断）。 - DNS 查询使用 Google Public DNS（8.8.8.8/8.8.4.4），不使用本机 DNS；HTTPS 在 FILE/HTTPS 校验中允许宽松 TLS（忽略证书错误）。 - `POST /api/link/query` - 链接查询（自动适配 http/https 与 // 无协议） - `POST /api/whois/query` - WHOIS 查询 > 详见 docs/api_responses.md，包含成功/失败判定与示例响应（带 dnssec）。 （已移除兼容接口，统一使用 /api/\*\*） ## URL 参数支持 支持通过 URL 参数直接访问特定功能： ```bash # DNS查询 http://localhost:18000/?domain=example.com&type=A&tab=dns # 域名验证 http://localhost:18000/?domain=example.com&brand=digicert&tab=verify # 链接查询 http://localhost:18000/?url=https://example.com&tab=link # WHOIS查询 http://localhost:18000/?domain=example.com&tab=whois ``` - ## 技术栈 - 后端: Go 1.23（入口：`cmd/server`） - 前端: 原生 HTML/CSS/JavaScript（静态页位于 `static/`） - 容器: Docker + Alpine Linux（`Dockerfile`，健康检查见 compose） - 工具: whois（WHOIS 查询，API 优先，命令行回落）、wget（健康检查） ## 环境变量配置 主要环境变量说明（详见 `.env.example`）： ### Docker 构建时变量（仅影响构建过程） | 变量名 | 说明 | 默认值 | 使用场景 | | -------------- | -------------------------------------------------- | ------- | ----------- | | `USE_CN_PROXY` | Docker 构建时是否使用国内镜像（包括 Alpine 和 Go） | `false` | Docker 构建 | | `GOPROXY` | 自定义 Go 代理地址 | - | Docker 构建 | ### 运行时变量（影响服务运行） | 变量名 | 说明 | 默认值 | 使用场景 | | -------------- | ----------------------------------------- | -------- | --------------- | | `HOST_PORT` | 主机端口 | `18000` | Docker 端口映射 | | `PORT` | 容器内部端口 | `18000` | 服务监听端口 | | `LOG_LEVEL` | 日志级别 (debug/info/warn/error) | `info` | 日志输出 | | `DNS_PROVIDER` | DNS 服务商 (google/cloudflare/alidns/dnspod/quad9) | `google` | DNS 查询 | | `DNS_SERVERS` | 自定义 DNS 服务器 (primary,secondary) | - | DNS 查询 | #### DNS 配置说明 支持三种配置方式（**优先级：DNS_SERVERS > DNS_PROVIDER > 默认值**）： **方式 1：使用预设服务商（推荐）** ```bash DNS_PROVIDER=google # Google Public DNS (8.8.8.8/8.8.4.4) - 默认 DNS_PROVIDER=cloudflare # Cloudflare DNS (1.1.1.1/1.0.0.1) DNS_PROVIDER=alidns # 阿里 DNS (223.5.5.5/223.6.6.6) - 中国推荐 DNS_PROVIDER=dnspod # 腾讯 DNSPod (119.29.29.29/182.254.116.116) DNS_PROVIDER=quad9 # Quad9 DNS (9.9.9.9/149.112.112.112) ``` **方式 2：自定义 DNS 服务器** ```bash DNS_SERVERS=1.1.1.1,1.0.0.1 # 主备服务器 DNS_SERVERS=8.8.8.8 # 单个服务器（主备相同） DNS_SERVERS=192.168.1.53,192.168.1.54 # 企业内网 DNS ``` **方式 3：使用默认配置** ```bash # 不设置任何变量，默认使用 Google Public DNS (8.8.8.8/8.8.4.4) ``` **使用场景推荐：** - 🌍 **国际用户**：`DNS_PROVIDER=cloudflare`（速度快、隐私保护） - 🇨🇳 **中国用户**：`DNS_PROVIDER=alidns` 或 `dnspod`（国内访问快） - 🏢 **企业内网**：`DNS_SERVERS=内网IP` （使用内部 DNS） - 🔒 **隐私优先**：`DNS_PROVIDER=quad9`（阻止恶意域名） **验证配置：** ```bash # 启动时会输出使用的 DNS 配置 docker-compose logs | grep -i dns # 或 ./server 2>&1 | grep -i dns ``` ### 配置方式 **Docker 部署：** ```bash # 1. 复制并编辑 .env 文件 cp .env.example .env vim .env # 2. docker-compose 会自动读取 .env 文件 docker-compose up -d ``` **本地直接运行：** ```bash # 1. 复制并编辑 .env 文件 cp .env.example .env vim .env # 2. 程序会自动加载 .env 文件（使用 godotenv） go build -o server ./cmd/server ./server # 或者通过命令行参数指定端口 ./server -port 8080 ``` ## 多区域部署 系统支持部署到多个地理区域，通过 `regions.json` 配置： ```json { "regions": [ { "id": "us", "name": "美国", "url": "https://dns-tools-us.cnssl.com", "default": true }, { "id": "cn", "name": "中国", "url": "https://dns-tools-cn.cnssl.com" } ] } ``` 服务会根据访问域名自动识别当前区域，并在页面右上角显示区域切换器。 ## 生产环境部署（重要） ### Nginx 反向代理配置 **⚠️ 重要：本服务要求所有查询返回实时数据，必须禁用所有缓存。** 生产环境使用 Nginx 反向代理时，必须添加以下配置以确保无缓存： ```nginx server { listen 80; listen 443 ssl http2; server_name your-domain.com; # SSL 配置 # ssl_certificate /path/to/cert.pem; # ssl_certificate_key /path/to/key.pem; location / { proxy_pass http://127.0.0.1:18000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # ===== 关键：禁用所有缓存 ===== proxy_cache off; proxy_buffering off; proxy_no_cache 1; proxy_cache_bypass 1; # 强制添加无缓存头 add_header Cache-Control "no-cache, no-store, must-revalidate" always; add_header Pragma "no-cache" always; add_header Expires "0" always; # ================================ # 超时设置 proxy_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 60s; } # API 路径专门配置（更严格的缓存控制） location /api/ { proxy_pass http://127.0.0.1:18000/api/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; # API 必须禁用所有缓存 proxy_cache off; proxy_no_cache 1; proxy_cache_bypass 1; expires -1; # 强制无缓存响应头 add_header Cache-Control "no-cache, no-store, must-revalidate, private" always; add_header Pragma "no-cache" always; add_header Expires "0" always; } } ``` #### 验证配置 ```bash # 测试 Nginx 配置 nginx -t # 重载配置 nginx -s reload # 验证响应头 curl -I https://your-domain.com/api/health # 应该看到： # Cache-Control: no-cache, no-store, must-revalidate # Pragma: no-cache # Expires: 0 ``` #### CDN 配置（如 CloudFlare） 如果使用 CDN，需要额外配置： 1. 创建页面规则：`*your-domain.com/api/*` 2. 设置缓存级别：**Bypass（绕过）** 3. 或设置 Edge Cache TTL：**0 秒** #### 为什么必须禁用缓存？ - **DNS 查询**：需要获取最新的 DNS 记录 - **证书验证**：DCV 验证必须是实时的 - **WHOIS 查询**：域名状态可能随时变化 - **链接检查**：网站内容和可用性需要实时检测 任何形式的缓存都可能导致验证失败或返回过期数据。 ## 构建说明 - 二进制文件不会提交到仓库（`server`、`dns-tools` 均已加入 `.gitignore`） - Dockerfile 采用多阶段构建，支持通过环境变量控制代理设置 - 使用 `docker-compose.yml` 进行部署，支持健康检查和日志管理 ## 安全与兼容 - 默认 API 均使用"严格 TLS 与有限重定向"。 - 为兼容旧版 `/get` 与批量 `FILE` 验证：在 HTTPS 场景可选择忽略证书，且 `//path` 将按 https→http 顺序尝试。 - DNS 查询使用 Google Public DNS (8.8.8.8/8.8.4.4) 进行解析，确保结果的一致性和可靠性。 - 所有 POST 接口请求体大小限制：200KB（超出将返回 400）。 ## 许可证 MIT License