Whosee.me 域名信息查询服务

项目概述

Whosee.me 是一个高性能的域名信息查询和分析服务，提供快速、可靠的域名WHOIS信息查询、DNS记录查询、网站截图和性能测试功能。该服务集成了多个数据提供商API，实现了负载均衡、故障转移和智能缓存，并采用高并发优化架构，确保查询服务的高可用性和响应速度。

前端仓库：https://github.com/AsisYu/whosee-whois
Docker镜像：hansomeyu/whosee-server

主要特性

基础功能

多提供商支持: 集成RDAP、WhoisXML和WhoisFreaks等多个WHOIS数据提供商，提高数据准确性和服务可用性
智能缓存系统: 基于Redis的缓存系统，根据域名到期时间动态调整缓存时长
负载均衡: 智能选择最佳数据提供商，平衡API调用次数
故障转移: 自动检测API故障并切换到备用提供商

高级特性

全面的健康检查系统: 提供统一的健康检查API，监控多种服务状态，支持日志分离和详细统计
健康检查日志分离: 支持将健康检查日志独立存储，便于日志管理和分析，可配置静默模式
智能Chrome管理: 支持冷启动、热启动、智能混合三种模式，自动下载和平台检测
重构截图服务 :
- 统一服务架构，支持所有截图类型（基础、元素、ITDog系列）
- 性能提升50%，智能并发控制（最大3个槽位）
- 熔断器保护和自动恢复机制
- 安全增强（输入验证、安全文件操作、错误脱敏）
- 完整向后兼容，平滑迁移
高并发优化架构: 全面优化的高并发处理能力
完善的错误处理: 统一的API响应格式和详细的错误分类
安全防护: 包含CORS、请求验证等安全措施

技术架构

核心组件

Web框架: 基于Gin构建的高性能Web服务
缓存系统: 使用Redis进行数据缓存和分布式限流
服务管理: 服务容器模式管理多个服务组件
重构截图系统 :
- 统一截图服务: 单一接口支持所有截图类型
- Chrome管理器: 智能并发控制、熔断器保护、性能统计
- 安全增强: 域名验证、安全文件操作、错误脱敏
- Chrome实例池: 统一资源管理，复用率提升50%
智能Chrome工具: 支持智能混合模式，自动平台检测和资源优化
智能工作池: 基于CPU核心数的动态工作池，高效处理并发请求
熔断保护: 防止系统在故障条件下过载的熔断器模式
中间件: 认证、日志、限流、错误处理等中间件

目录结构

.
├── handlers/                            # 请求处理器和异步处理函数
│   ├── screenshot_new.go                # 重构后的统一截图处理器
│   └── screenshot.go                    # 原有截图处理器（兼容保留）
├── middleware/                          # 中间件组件
├── providers/                           # WHOIS数据提供商实现
├── services/                            # 核心业务逻辑和服务组件
│   ├── screenshot_service.go            # 统一截图服务
│   ├── chrome_manager.go                # 重构Chrome管理器
│   ├── whois_manager.go                 # 🔧 P1并发安全修复
│   └── ...                              # 其他服务组件
├── routes/                              # API路由定义
│   └── screenshot_routes.go             # 截图服务路由
├── types/                               # 数据类型定义
├── utils/                               # 辅助函数和工具
│   └── domain.go                        # 增强的安全工具
├── tests/                               # 测试脚本和工具
│   ├── README.md                        # 测试文档索引
│   ├── test_runtime.sh                  # 旧版运行时测试
│   └── test_runtime_v2.sh               # P0修复运行时测试（推荐）
├── docs/                                # 文档目录
│   ├── reports/                         # 项目报告
│   │   ├── README.md                    # 报告索引
│   │   ├── PROJECT_HEALTH_REPORT.md     # 项目健康检查报告
│   │   ├── P0_FIX_REVIEW.md             # P0安全修复审查
│   │   └── RUNTIME_TEST_REPORT.md       # 运行时测试报告
│   ├── architecture/                    # 架构文档
│   │   └── README.md                    # 架构文档索引
│   ├── BACKEND_AUTHENTICATION_FLOW.md   # 后端认证流程详细文档
│   ├── AUTHENTICATION_EXAMPLES.md       # 认证示例集合文档
│   ├── ALL_JSON.md                      # API响应格式文档
│   └── SCREENSHOT_REFACTOR.md           # 截图服务重构指南
├── logs/                                # 日志文件
├── static/                              # 静态资源（截图等）
├── CLAUDE.md                            # Claude Code开发指南
├── .env                                 # 环境变量配置
└── main.go                              # 应用入口

安装指南

前置条件

Go 1.24+
Redis 6.0+
WHOIS API账号（WhoisXML和/或WhoisFreaks）
Chrome/Chromium (用于网站截图功能，支持自动下载和智能平台检测)

安装步骤

克隆仓库

git clone https://github.com/AsisYu/whosee-server.git
cd whosee-server

安装依赖

go mod download

配置环境变量

cp .env.example .env
# 编辑.env文件，填入API密钥和Redis配置

运行服务

go run main.go

部署指南

使用Docker部署（推荐）

快速开始

使用预构建的Docker Hub镜像：

# 拉取最新镜像
docker pull hansomeyu/whosee-server:latest

# 运行容器
docker run -d -p 3900:3900 --name whosee-server \
  -e WHOISFREAKS_API_KEY=your_api_key \
  -e WHOISXML_API_KEY=your_api_key \
  -e JWT_SECRET=your_jwt_secret \
  -e API_KEY=your_api_key \
  -e REDIS_ADDR=redis:6379 \
  --restart unless-stopped \
  hansomeyu/whosee-server:latest

使用docker-compose（推荐生产环境）

创建 docker-compose.yml：

version: '3.8'

services:
  whosee-server:
    image: hansomeyu/whosee-server:latest
    container_name: whosee-server
    ports:
      - "3900:3900"
    environment:
      - JWT_SECRET=${JWT_SECRET}
      - API_KEY=${API_KEY}
      - WHOISFREAKS_API_KEY=${WHOISFREAKS_API_KEY}
      - WHOISXML_API_KEY=${WHOISXML_API_KEY}
      - REDIS_ADDR=redis:6379
      - CHROME_MODE=auto
      - GIN_MODE=release
    depends_on:
      - redis
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3900/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

  redis:
    image: redis:7-alpine
    container_name: whosee-redis
    restart: unless-stopped
    volumes:
      - redis-data:/data

volumes:
  redis-data:

启动服务：

docker-compose up -d

从源码构建（可选）

如果需要自定义构建：

# 克隆仓库
git clone https://github.com/AsisYu/whosee-server.git
cd whosee-server

# 构建镜像
docker build -t whosee-server .

# 运行容器
docker run -d -p 3900:3900 --name whosee-server \
  -e WHOISFREAKS_API_KEY=your_api_key \
  -e WHOISXML_API_KEY=your_api_key \
  -e JWT_SECRET=your_jwt_secret \
  -e API_KEY=your_api_key \
  --restart unless-stopped \
  whosee-server

多平台支持

Docker镜像支持以下平台：

linux/amd64 (x86_64)
linux/arm64 (ARM64/Apple Silicon)

指定平台拉取：

docker pull --platform linux/amd64 hansomeyu/whosee-server:latest
docker pull --platform linux/arm64 hansomeyu/whosee-server:latest

详细配置请参考：Docker自动构建与发布指南

使用PM2部署（生产环境）

安装PM2

npm install -g pm2

编译Go应用

go build -o whosee-server main.go

创建PM2配置文件 ecosystem.config.js

module.exports = {
  apps: [{
    name: "whosee-server",
    script: "./whosee-server",
    env: {
      NODE_ENV: "production",
      PORT: 3900
    },
    log_date_format: "YYYY-MM-DD HH:mm:ss",
    out_file: "./logs/pm2_out.log",
    error_file: "./logs/pm2_error.log"
  }]
}

启动服务

pm2 start ecosystem.config.js

设置开机自启

pm2 startup
pm2 save

API接口说明

主要API端点

端点	方法	说明	参数
`/api/health`	GET	健康检查API，返回所有服务的健康状态	`detailed=true/false`: 是否返回详细状态
`/api/v1/whois`	GET	WHOIS信息查询（通过查询参数）	`domain`: 要查询的域名
`/api/v1/whois/:domain`	GET	WHOIS信息查询（通过路径参数）	`:domain`: 路径中的域名
`/api/v1/rdap`	GET	RDAP协议查询（通过查询参数）	`domain`: 要查询的域名
`/api/v1/rdap/:domain`	GET	RDAP协议查询（通过路径参数）	`:domain`: 路径中的域名
`/api/v1/dns`	GET	DNS记录查询（通过查询参数）	`domain`: 要查询的域名
`/api/v1/dns/:domain`	GET	DNS记录查询（通过路径参数）	`:domain`: 路径中的域名

截图服务API

新版统一接口（推荐）

端点	方法	说明	参数
`/api/v1/screenshot/`	POST/GET	统一截图接口，支持所有截图类型	JSON请求体或查询参数
`/api/v1/screenshot/chrome/status`	GET	Chrome状态检查和性能统计	无
`/api/v1/screenshot/chrome/restart`	POST	Chrome重启	无

统一截图接口请求示例：

{
  "type": "basic|element|itdog_map|itdog_table|itdog_ip|itdog_resolve",
  "domain": "example.com",
  "url": "https://example.com",        // 可选，优先级高于domain
  "selector": ".main-content",         // 元素截图必需
  "format": "file|base64",
  "timeout": 60,                       // 秒
  "wait_time": 3,                      // 秒
  "cache_expire": 24                   // 小时
}

兼容旧版接口

端点	方法	说明	参数
`/api/v1/screenshot`	GET	网站截图服务（通过查询参数）	`domain`: 要截图的域名
`/api/v1/screenshot/:domain`	GET	网站截图服务（通过路径参数）	`:domain`: 路径中的域名
`/api/v1/screenshot/base64/:domain`	GET	返回Base64编码的网站截图	`:domain`: 路径中的域名
`/api/v1/itdog/:domain`	GET	ITDog网站性能测试截图	`:domain`: 路径中的域名
`/api/v1/itdog/base64/:domain`	GET	返回Base64编码的ITDog测试结果	`:domain`: 路径中的域名
`/api/auth/token`	POST	获取安全访问令牌	无需参数，根据客户端IP发放短期令牌

安全认证

API采用多层安全验证机制，包括IP白名单、API密钥验证和JWT令牌认证。详细的验证流程请参考后端认证流程文档。

安全配置

生产环境推荐配置:

DISABLE_API_SECURITY=false
IP_WHITELIST_STRICT_MODE=false  # 允许所有ip通过API密钥访问
API_DEV_MODE=false
API_KEY=your_strong_api_key
JWT_SECRET=your_strong_jwt_secret

注意:

JWT令牌有效期为30秒，每个令牌只能使用一次
API密钥可重复使用，适合程序化访问
非严格模式下，IP白名单或API密钥验证任一通过即可访问
请求频率限制为每IP每分钟30个令牌

常见错误代码

错误代码	HTTP状态码	描述
`MISSING_PARAMETER`	400	缺少必要的参数
`INVALID_DOMAIN`	400	无效的域名格式
`INVALID_URL`	400	不安全的URL
`INVALID_SELECTOR`	400	无效的CSS选择器
`RATE_LIMITED`	429	请求频率超过限制
`SERVICE_BUSY`	503	服务忙碌（熔断器开启）
`TIMEOUT`	504	请求处理超时
`QUERY_ERROR`	500	查询过程中发生错误
`SCREENSHOT_ERROR`	500	截图过程中发生错误
`CHROME_ERROR`	500	Chrome实例错误
`ELEMENT_NOT_FOUND`	500	页面元素未找到
`BROWSER_ERROR`	500	浏览器执行错误
`ITDOG_ERROR`	500	ITDog测试过程中发生错误

截图技术架构

核心组件

ScreenshotService: 统一截图服务，支持基础、元素、ITDog等所有类型
ChromeManager: Chrome实例管理器，智能并发控制和资源复用
熔断器模式: 自动故障恢复，确保服务稳定性
安全工具: 域名验证、文件名清理、URL安全检查

API设计

新版统一接口: POST /api/v1/screenshot/ 支持所有截图类型
Chrome管理API: 状态检查、重启等管理功能
兼容旧版接口: 保持现有客户端无需修改

详细的重构说明和迁移指南请参考截图服务重构文档。

Chrome智能管理

三种运行模式

集成了智能Chrome管理系统，特别适合WHOIS服务（主要功能）+ 偶尔截图的使用场景：

模式	启动方式	资源占用	响应速度	适用场景	空闲管理
冷启动	每次重新启动	最低	慢(2-3秒)	极少使用截图	用完即关
热启动	预热保持运行	较高	最快(<100ms)	频繁使用截图	10分钟自动关闭
智能混合	按需+智能复用	中等	适中	WHOIS主业务+偶尔截图	智能调整(1.5-6分钟)

智能混合模式

默认采用智能混合模式，具有以下特性:

智能启动策略: 首次使用快速启动，频繁使用自动切换为热启动策略
智能空闲管理: 根据使用频率动态调整空闲超时时间（1.5-6分钟）
实例复用: 健康的Chrome实例直接复用，避免重复启动开销
自动下载: 智能检测平台并自动下载Chrome，支持中国镜像源
并发控制: 最大3个并发操作，避免资源竞争

Chrome配置

可通过环境变量 CHROME_MODE 配置运行模式:

# 设置Chrome运行模式
export CHROME_MODE=auto    # 智能混合模式（推荐）
export CHROME_MODE=cold    # 冷启动模式
export CHROME_MODE=warm    # 热启动模式

也可以在代码中动态设置:

// 设置全局Chrome模式
utils.SetGlobalChromeMode("auto")

配置说明

健康检查日志分离

支持将健康检查日志分离到独立文件，便于日志管理和分析：

功能特性

独立日志文件: 健康检查日志写入 logs/health_YYYY-MM-DD.log 文件
主日志静默: 可配置在主服务器日志中静默健康检查信息
详细统计: 提供健康检查总结，包含服务状态统计和耗时信息
向后兼容: 默认关闭，不影响现有部署

配置方式

# 启用健康检查日志分离
HEALTH_LOG_SEPARATE=true

# 启用主日志静默模式（推荐与日志分离一起使用）
HEALTH_LOG_SILENT=true

日志文件结构

启用后将生成以下日志文件：

logs/health_YYYY-MM-DD.log: 健康检查详细日志
logs/server.log: 主服务器日志（不含健康检查信息）

目录功能概览

每个目录都包含详细的README文档，包括功能说明、使用示例和最佳实践：

handlers/ - HTTP请求处理器，包含重构后的统一截图处理器
services/ - 核心业务逻辑，包含Chrome管理器和截图服务
routes/ - API路由定义，包含新版截图路由配置
middleware/ - 中间件组件，包含安全、性能和监控中间件
utils/ - 工具函数，包含增强的安全工具和Chrome管理
providers/ - WHOIS数据提供商实现
types/ - 数据类型定义

环境变量

变量名	说明	示例值
`WHOISXML_API_KEY`	WhoisXML API密钥	`your_api_key`
`WHOISFREAKS_API_KEY`	WhoisFreaks API密钥	`your_api_key`
`REDIS_ADDR`	Redis服务器地址	`localhost:6379`
`REDIS_PASSWORD`	Redis密码	`your_password`
`PORT`	服务监听端口	`3900`
`GIN_MODE`	Gin运行模式	`release`
`HEALTH_CHECK_INTERVAL_DAYS`	健康检查间隔天数	`1`
`HEALTH_LOG_SEPARATE`	是否将健康检查日志分离到独立文件	`false`
`HEALTH_LOG_SILENT`	是否在主日志中静默健康检查信息	`false`
`CHROME_MODE`	Chrome运行模式	`auto` (可选: `cold`, `warm`, `auto`)
`DISABLE_API_SECURITY`	是否禁用API安全验证	`false`
`IP_WHITELIST_STRICT_MODE`	IP白名单严格模式	`true`
`API_DEV_MODE`	API开发模式	`false`
`TRUSTED_IPS`	受信任的IP列表	空

文档说明

核心文档

后端认证流程文档: 详细说明API安全认证机制，包括JWT令牌、API密钥验证和IP白名单的完整流程，含Mermaid流程图
认证示例集合文档: 提供各种认证场景的实用示例，包括curl命令、多语言客户端代码、错误处理和调试技巧
API响应格式文档: 所有API端点的响应格式和数据结构说明
截图服务重构文档 : 详细的重构说明、迁移指南和性能对比

验证流程概述

后端采用多层安全验证机制:

安全开关检查: 通过 DISABLE_API_SECURITY 控制是否启用安全验证
IP白名单验证: 支持Redis缓存，可配置严格/非严格模式
API密钥验证: 支持请求头和查询参数两种方式
JWT令牌认证: 短期有效的访问令牌机制
其他安全中间件: CORS、安全头部、限流等

详细的认证流程图和配置说明请参考后端认证流程文档，实用的认证示例请参考认证示例集合文档。

开发工具

本项目采用现代化开发工具链，包括 AI 辅助开发工具（Trae、Cursor/Claude code）进行代码生成、架构设计和开发优化，显著提升开发效率和代码质量。

Name		Name	Last commit message	Last commit date
Latest commit History 46 Commits
.cursor/rules		.cursor/rules
.github/workflows		.github/workflows
docs		docs
handlers		handlers
k8s		k8s
middleware		middleware
nginx		nginx
pkg/logger		pkg/logger
providers		providers
routes		routes
services		services
tests		tests
types		types
utils		utils
.env.docker		.env.docker
.env.example		.env.example
.gitignore		.gitignore
.nancy-ignore		.nancy-ignore
CLAUDE.md		CLAUDE.md
DOCKER_HUB_README.md		DOCKER_HUB_README.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum
main.go		main.go

Folders and files

Latest commit

History

Repository files navigation

Whosee.me 域名信息查询服务

项目概述

主要特性

基础功能

高级特性

技术架构

核心组件

目录结构

安装指南

前置条件

安装步骤

部署指南

使用Docker部署（推荐）

快速开始

使用docker-compose（推荐生产环境）

从源码构建（可选）

多平台支持

使用PM2部署（生产环境）

API接口说明

主要API端点

截图服务API

新版统一接口（推荐）

兼容旧版接口

安全认证

安全配置

常见错误代码

截图技术架构

核心组件

API设计

Chrome智能管理

三种运行模式

智能混合模式

Chrome配置

配置说明

健康检查日志分离

功能特性

配置方式

日志文件结构

目录功能概览

环境变量

文档说明

核心文档

验证流程概述

开发工具

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages