Address 是一个基于 PostgreSQL 的自托管真实住宅地址生成器，源码以 MIT 许可证开源。它只有一条核心承诺：发布池中的住宅基础地址来自官方开放数据、国家或地区地址登记、地图登记建筑及具有明确住宅用途证据的开放地图数据，不使用随机街道、门牌或邮编冒充真实地址。
适合两类用户：需要批量构造格式合法测试资料的开发与测试人员，以及希望把数据留在自己服务器上的用户——同类自托管项目并不少见，把数据来源讲得如此透明的并不多。官方提供在线演示，仓库描述中还提到 IP 附近生成与地图预览能力。正文按核心功能、安装与使用、使用感受的顺序展开，文末给出项目地址与仓库统计。
场景痛点
造测试地址是一件不起眼却反复消耗时间的事。手写随机字符串过不了表单校验；用通用假数据工具生成的「123 Fake Street」在地图上搜不到，邮编和行政区划也对不上号。测试跨国业务时问题更明显：各国地址层级、邮编规则差异很大，缺一份覆盖面广、结构真实的地址数据，用例就得逐国手工拼，这类环节正是效率工具该接手的地方。
另一个极端是直接拿真实个人的地址填进测试库，这会带来隐私与合规风险。Address 的思路是把「真实结构」与「非冒用」分开——也是这次软件发现里最值得记下的设计：地址字段全部来自公开登记与开放地图数据，并通过住宅证据门禁筛选，坐标可回溯到来源。
核心功能
真实数据来源与发布门禁
项目覆盖 27 个国家和地区，横跨北美、欧洲、东亚、东南亚、南亚、大洋洲、中东、南美与非洲。数据源按国家组合：美国用 Overture Maps 与 Geofabrik OSM 州级分片，加拿大用 Statistics Canada 全国地址登记，西班牙用 Catastro INSPIRE 数据，荷兰用 Kadaster BAG，日本用数字厅 ABR 与日本邮便，韩国用 K-apt，新加坡用 HDB 楼栋数据，中国来自行政区划数据与主流地图平台的住宅小区 POI。
筛选标准写得明确：除中国室内字段（栋、单元、楼层、室号，标记 synthetic）外不随机补造任何组件；必填字段缺失、行政区冲突、坐标越界或住宅证据不足的记录不进发布池。每条记录保留来源坐标，可在 Google Maps、高德地图等覆盖相应地区的地图服务中定位。
生成、筛选与多语言
- 配置 27 个国家和地区，按各国实际行政结构提供州省、城市、区县和邮编筛选。
- 严格筛选语义：所选范围没有合格记录时返回错误，不会悄悄切换到其他地区。
- 从当前筛选范围的全部合格地址中快速随机选择，不会反复读取数据库前几条。
- 支持原文、英文、简体中文、繁体中文、日语、韩语、德语、法语、西班牙语和葡萄牙语展示路径。
- 地址语言和资料语言分别记忆；浏览器首次打开默认 English，生成和切换国家不会重置选择。
- 每个国家可配置热门行政区、热门城市和特殊区域；美国包含无州级销售税州。
收藏与后台管理
地址收藏保存在浏览器本地，支持按大洲或国家分组与筛选、拖动或序号排序、复制、删除，以及跳转 Google Maps 或高德地图。后台提供公开覆盖监控，以及管理员仪表盘、地址数据规则、同步队列与同步历史、快捷区域、平台凭据、访问控制、黑名单和 API Token 页面。
JSON API 与自动同步
JSON API 覆盖健康检查、国家、可用性、地区选项、搜索、地址与资料生成、批量生成和监控接口，并附 Python、cURL 和 JavaScript 示例——官方文档写得足够细，可以直接当使用教程用，也适合把批量处理接进现有测试流水线。运行时完全使用 PostgreSQL 数据库，包含连接池、事务发布、地区索引和预构建随机地址索引。
数据同步全自动：一个国家只有在合格地址总量、最低行政层覆盖率、一二级行政区数量等启用规则全部满足时才算完成，仅达到国家总量不能标记完成。队列内置有限重试、指数退避、额度冷却恢复、可续跑 checkpoint、无增长锁存和连续失败暂停机制，不会对没有变化的数据源无限循环。
安装与使用
前置条件
- 一台可运行 Docker 的服务器。
- 平台密钥默认可选，只有所选同步策略需要时才必须配置。
安装
日常使用
- 在管理员后台设置前端密码、管理员密码与 API Token。
- 按需配置平台密钥；多个 Key 独立轮换，当前 Key 失败时先冷却再尝试其他 Key，全部不可用时等待最早恢复时间。
- 在生成界面选择国家与行政区筛选，生成地址或测试资料；批量需求走 JSON API。
| 场景 | 推荐方式 | 说明 |
| 手工挑选少量地址 | 生成界面加收藏 | 收藏存浏览器本地，可分组排序 |
| 批量构造测试资料 | JSON API 批量生成 | 附 Python、cURL、JavaScript 示例 |
| 长期数据维护 | 管理员同步队列 | 自动同步、覆盖监控与同步历史 |
我的使用感受
这个项目最打动人的地方是「诚实」：不宣称造出真地址，而是把来源、证据和边界摊开——哪些字段来自真实登记、哪些是标记过的合成字段、什么样的记录会被拒之门外，文档里写得清清楚楚。它介于实用软件与有趣软件之间，在线演示本身也算一个有趣的网站；作为工具推荐，它解决的正是「测试数据要像真的」这个不大不小的痛点，值得在 GitHub精选 清单里记上一笔。
官方网站
项目仓库：https://github.com/daimon3332/address
在线演示：https://address.333186.xyz/
下载地址
https://pan.quark.cn/s/e1f69ee3e03d
