FOFA 共享资产测绘网关
Base URL: https://fofa.suuu.de5.net · 账号池共享自动轮询 · 独立 Key 配额隔离
鉴权方式（三选一）
所有检索请求需携带由管理员签发的 Key（形如 fkey_xxxx...）：
| 方式 | 写法 |
|---|
| 请求头（推荐） | X-API-Key: *** |
| 查询参数 | ?api_key=fkey_..…y 也可 |
Key 由管理员统一签发（POST /api/keys/generate，可指定 name / daily_quota / days），可单独启停与吊销（/api/keys/:token/toggle、DELETE /api/keys/:token），各 Key 独立日配额、互不影响。
核心接口 · POST /api/search 与 GET /api/search
| 参数 | 类型 | 说明 |
|---|
| query / q | string | 检索语法（必填）。支持 app="nginx"、title="..."、country="US"、ip=、port=、&&、|| 等标准 FOFA 语法 |
| page | int | 页码，默认 1 |
| size | int | 每页条数 2~50，默认 10 |
| fields | string | 可选，指定返回字段（逗号分隔），默认返回全字段 |
方式一 · Python（requests）
方式二 · Node.js（axios）
方式三 · Go（net/http）
方式四 · curl（POST 标准检索 / GET 快速检索）
成功响应结构（四种方式通用）
其他接口
| 路径 | 方法 | 鉴权 | 说明 |
|---|
| /health | GET | 无 | 服务状态、池水位、版本（本页顶部徽章即实时拉取此接口） |
| /api/keys/generate | POST | 管理员 Key | 生成子 Key，body: {"name":"user1","daily_quota":1000,"days":30} |
| /api/keys | GET | 管理员 Key | 查看全部 Key 与用量 |
| /api/keys/:token/toggle | POST | 管理员 Key | 启用/停用某 Key |
| /api/keys/:token | DELETE | 管理员 Key | 吊销某 Key |
| /api/pool/status | GET | 管理员 Key | 账号池与封禁水位 |
错误码与限流
| code | 含义 | 处置 |
|---|
| 400 | 缺少 query 或格式非法 | 检查参数名（query 或 q） |
| 401 | 令牌缺失 / 无效或已禁用 | 核对 X-API-Key，联系管理员 |
| 403 | 令牌已过期 / 今日配额耗尽 | 联系管理员续期或次日自动重置 |
| 429 | 触发 QPS 限流 | 退避 ≥1s 后重试，检索类任务建议串行 |
| 502 | 上游数据源暂不可用 | 稍后重试；持续出现请联系管理员 |
Agent 集成要点：响应 code==0 即成功；remaining_today 为本 Key 当日剩余额度，可用于自主节流；assets[] 已含 ip/port/host/title/country 等 14 字段，直接消费，无需二次 fields 调用。