开发文档

版本号	修改	修改时间	备注
v1.0.0	王小琱	2024.12.20	初次修订

1. 项目简介

• 服务名称：exchange-ip-location-backend
• 服务描述：本项目为交易所、金融等业务提供IP归属地查询、IP风控与合规能力，支持IP黑名单、国家黑名单、匿名代理识别等功能。
• 所属模块：基础服务组件。
• 负责人：王小琱（wang746277441@gmail.com）

2. 功能描述

• 查询任意IP的地理归属信息（国家、洲、注册地等）。
• 检查IP是否在黑名单、是否为匿名代理、VPN、Tor节点等。
• 检查IP所属国家是否在黑名单。
• 支持IP风控合规场景的快速接入。

3. 系统架构

3.1 主要技术栈

• 编程语言：[Go / Protocol Buffers v3]
• 服务框架：[Go Micro / GORM]
• 数据库：[MySQL]
• API接口：[gRPC]
• 监控：[Prometheus]
• 容器编排：[Docker]

备注：具体依赖版本详见go.mod文件。

3.2 架构图

3.3 架构概括

• 业务层（Business Layer）

  包含 Risk Service，负责业务风控逻辑，向内部服务提供风控能力。

• 基础服务层（Infrastructure Layer）

  包含 IP Location Service，专注于提供IP归属地、IP风控、合规等底层能力，供业务层调用。

3.4 业务流程

3.4.1 查询IP信息流程

3.4.2 检查IP风控流程

3.4.3 获取IP风控详情流程（GetIPInsights）

4. 依赖组件

组件	版本	说明
MySQL	8.x	关系型数据库
MaxMind	-	IP地理信息与风控服务

5. 接口设计

见接口文档

使用make doc可以重新生成接口文档。

6. 数据库设计

见数据库设计文档

7. 项目部署

见部署文档

8. 错误码定义

错误码	错误信息	说明
ErrCallMaxmind	请求失败	调用MaxMind失败
ErrSystem	内部错误	内部服务调用失败

9. FAQ

1. IP黑名单和国家黑名单的区别？

• IP黑名单针对单个IP或网段，国家黑名单针对整个IP所在的国家。

2. MaxMind账号和License如何获取？

• 需前往 MaxMind官网 注册并获取。

3. 查询返回空数据？

• 检查请求参数（IP地址）是否正确；
• 检查MaxMind服务配置和网络连通性。

4. 如何判定IP是代理、TOR、VPN呢？

系统会优先判断IP是否为内网地址，若不是，则通过 MaxMind Insights 接口获取IP的详细属性，根据上述字段综合判定该IP是否为代理、TOR、VPN或其他匿名访问类型。

• 代理（Proxy） 通过调用 MaxMind 的 Insights 接口，判断返回结果中的 IsAnonymousProxy、IsPublicProxy、IsResidentialProxy 字段。如果这些字段为 true，则说明该IP属于代理类型。

• TOR 节点（Tor Exit Node） 通过 MaxMind 返回的 IsTorExitNode 字段进行判断。如果该字段为 true，则该IP为Tor出口节点。

• VPN 通过 MaxMind 返回的 IsAnonymousVpn 字段进行判断。如果该字段为 true，则该IP为VPN节点。

• 用户类型（UserType） 还可以结合 UserType 字段（如 hosting），进一步辅助判断IP是否为数据中心、云主机等高风险类型。

5. 如何添加国家黑名单或IP黑/白名单呢？

• 添加国家列表黑名单

向 country_blacklist 表插入对应的国家 ISO 码及原因。例如：

INSERT INTO country_blacklist (iso_code, reason, created_at, updated_at)
VALUES ('US', '合规要求禁止美国访问', NOW(), NOW());

• 添加IP黑名单

  向 ip_limit 表插入需要限制的 IP 地址或网段，并将 is_active 设置为 DISABLE。例如：

INSERT INTO ip_limit (ip_address, reason, is_active, created_at, updated_at)
VALUES ('1.2.3.4', '恶意访问', 'DISABLE', NOW(), NOW());

• 添加IP白名单

向 ip_limit 表插入需要放行的 IP 地址或网段，并将 is_active 设置为 ENABLE。例如：

INSERT INTO ip_limit (ip_address, reason, is_active, created_at, updated_at)
VALUES ('5.6.7.8', '合作方白名单', 'ENABLE', NOW(), NOW());

注意：

• ip_limit 表的 is_active 字段为 ENABLE 时表示白名单，为 DISABLE 时表示黑名单。
• 支持单个IP和CIDR网段。
• 所有操作建议有审计记录，便于后续追溯。
• 所有直接对数据库的写操作，操作完成必须重启服务才能生效。

10. 参考资料

• MaxMind官方文档

11. 致谢

感谢 MaxMind 提供的 GeoIP2 服务。