开源的「真实地址 + 合成测试资料」生成器（27 国）

做表单测试、软件 QA、注册流程压测时，最常缺的就是一批看起来真实、能过校验、但又不触碰真实个人隐私的地址与身份信息。传统的 faker 类库纯随机拼字符串，经常被地址校验（邮编-州不匹配、街道格式不对）拦下来。Real Address Generator 走了一条不同的路：它只输出有地理数据源背书的真实地址，并配套生成一套内聚的合成测试资料（姓名、邮箱、银行卡、工作、网络等）。本文带你完整了解这个开源工具。

一、它是什么？

Real Address Generator（项目名 Address）是一个自托管的「已验证住宅地址 + 合成测试档案」生成器，覆盖 27 个国家与地区。它的官方定位是：

「A self-hosted verified residential-address and synthetic test-profile generator for 27 countries and regions.」

项目开源在 GitHub（daimon3332/address），采用 MIT 许可证，基于 Node.js 24 + Astro 构建，在线演示地址为 address.333186.xyz。整站支持中文（简体/繁体）与英文双语界面。

它和普通「假地址生成器」最大的区别

普通地址生成器是「凭空编造」：随机拼一个街道名 + 随机邮编，很可能邮编和州对不上，一校验就露馅。Real Address Generator 的核心理念是「source-backed（数据源背书）」：

每个地址都来自真实地理数据源（OpenStreetMap / Overture Maps / 高德等），有真实坐标；
绝不臆造地址字段：没有门牌号、没有单元号、没有邮编，就留空，绝不编一个假值填补；
地址可被 Google 地图 / 高德地图精确定位（地图预览）；
同时生成与之内聚的合成测试档案（姓名、邮箱、测试用银行卡等），字段之间相互自洽。

官方在 README 里明确声明：「Generated records are test data. They do not prove deliverability, residency, identity, payment-account validity, or ownership.」（生成的记录仅作测试数据，不代表可投递性、居住真实性、身份有效性或支付账户有效性。）这说明它的设计目标是合规的测试/开发用途，而非伪造身份。

二、核心功能一览

27 国覆盖：支持按国家、地区（州/省）、城市、邮编逐级筛选。
位置筛选「精确或留空」：如果选了某个未被覆盖的地区，工具返回 NO_POOL_COVERAGE，而不是偷偷换成别的地方——保证「你要的就是要的」。
IP-地区模式：可输入 IP 做坐标定位，必须命中坐标或城市才生成，绝不退化为「全国范围随机地址」。
三语呈现：同一地址同时给出源语言、英文、简体中文三种写法（例如中文地址 ↔ 英文 postal 格式）。
组件全溯源：门牌、楼栋、单元、楼层、房间、邮编等缺失项一律留空，不编造。
合成测试档案：自动生成内聚的基础档案、沙箱测试卡（Stripe 测试卡）、就业、金融、网络等字段，适合直接塞进表单做端到端测试。
双地图预览：Google 地图与高德地图（仅中国）可独立开关；高德对中国坐标自动做 WGS-84 → GCJ-02 偏移转换。
黑/白名单热加载：可热更新自定义黑名单并保留证据与来源归属。
数据质量治理：支持断点续传的初始导入、每日国家轮换、质量门槛（quality gates）与存储上限。

三、支持的 27 个国家 / 地区

工具覆盖：美国、加拿大、墨西哥、英国、德国、法国、意大利、西班牙、荷兰、俄罗斯、中国、中国香港、中国台湾、日本、韩国、新加坡、越南、泰国、菲律宾、马来西亚、印度、澳大利亚、土耳其、沙特阿拉伯、巴西、尼日利亚、南非。

并且按国家标注了默认数据源与真实地址字段。以美国为例，默认源是 Overture Maps，真实字段含门牌号、街道、城市、州、ZIP 与源几何；中国则使用 AreaCity 行政区划 + 高德/百度/腾讯 POI，且社区名需至少两家地图厂商一致才发布。所有国家均声明：地址组件不合成，缺失值留空。

四、数据从哪来？字段溯源

地址并非随机生成，而是经过「存在性 + 住宅用途」双闸门校验。主要数据源分两类：

Overture Maps：美、加、墨、德、法、意、西、荷、日、台、澳等多数国家；
Geofabrik OSM：英、俄、港、韩、新、越、泰、菲、马、印、土、沙、巴、尼、南非等；
中国专用：AreaCity 行政区划 + 高德/百度/腾讯 POI，并做多源一致性校验。

各字段的「出处」也被明确标注：

国家 / 地区 / 城市 / 街道：同源地址记录或精确行政关系归一化而来，冲突即校验失败；
门牌号：只保留源/厂商登记值，没有就留空；
邮编：只保留有效的源值或权威行政关系，无效/缺失留空；
坐标：直接复制自源几何（可能是地址点、建筑点或 OSM 道路中心点）；
楼栋/社区：只用绑定的源值；中国的社区需两源以上一致才发布；
姓名、电话、邮箱、就业、金融、网络、测试卡：合成测试数据。

五、两种生成模式

1. 住宅模式（residential，默认）

从已同步的 SQLite 地址池中按筛选条件（国家、地区、城市、邮编）抽取一条真实地址，全程不做实时地理编码或翻译调用，速度快、可离线。住宅模式要求独立的「住宅用途证据」。

2. IP-地区模式（ip-region）

传入一个 IP，先做实时坐标定位，再依次回退到「邻近池 → 城市池 → 地区池 → 国家池」。只有精确命中坐标或城市时才返回，绝不退化为「全国随便给一个」，保证地理一致性。

六、Web 界面怎么用？

在线演示的 WebUI 交互很直观，中文界面完整：

选国家与位置：先选国家，再逐级选地区 / 城市 / 邮编（支持搜索，地区与邮编分页，城市一次最多 2 万条）；
生成地址与测试档案：点击生成，得到一张「已验证住宅地址 + 合成测试档案」；
多语言切换：每个地址块支持 native / en / zh-CN 三种语言标签页，逐字段展示；
逐字段复制：每个字段都有单独的复制按钮，也可整块导出；
地图预览：内嵌 Google / 高德地图钉点，确认地址真实可定位；
快捷入口（shortcuts）：常用国家/地区一键直达。

界面顶部还有「API 文档」入口和 GitHub 链接，底部标注数据来自 OpenStreetMap 贡献者与公开数据源、地图由 Google 提供。

七、API 与自托管

API 文档

站点提供完整的 /en/api/ 文档（v1），主要端点：

GET /api/v1/countries：国家、分组、能力、计数与快捷方式；
GET /api/v1/locations/search?country=US&field=city&regionId=...：按父级加载城市（地区/邮编分页）；
GET /api/v1/generate?country=US&residential=true：生成一条随机地址；
GET /api/v1/generate?mode=ip-region&ip=...：按 IP 实时定位生成；
GET /api/v1/data-health：各国数据健康度。

生成参数支持：country（ISO 3166-1 alpha-2，默认 US）、residential、region/regionId、city/cityId、postcode、seed（可复现随机种子）、requestId 等。

鉴权

除健康检查外，所有外部接口都需要 Bearer Token（在 /admin/ 后台创建）。Token 支持作用域（scopes）、每分钟限流、过期时间、查看/编辑/吊销等管理能力。无效或过期 Token 返回 401，限流触发返回 429（含 Retry-After: 60）。

响应结构示例

一次 generate 调用返回：请求上下文（requestId / mode / country / residential）、尝试过的数据源（sourcesTried）、地址三语格式（native / en / zh-CN 的 postalLines 与 singleLine）、合成档案（姓名、邮箱）、沙箱测试卡（如 Stripe 4242 4242 4242 4242，标注 sandboxOnly），以及 Google 地图嵌入链接。

自托管

项目为 MIT 开源，可一键自托管，依赖 Node.js 24。高德相关功能需要自行配置三组密钥（服务端 AMAP_API_KEY、浏览器端受限的 AMAP_JS_API_KEY、服务端 AES-GCM 加密的 AMAP_JS_SECURITY_CODE），官方示例均为占位符，不内置任何真实密钥。