
图:Address 生成器主页,可按国家地区与当前 IP 区域生成真实街道地址(2026-11 截图)
定位与基本信息
Address 是一个开源的测试资料生成器,仓库在 GitHub 的 daimon3332/address,MIT 许可证,配套公开演示站即本站链接的 address.333186.xyz。它解决的是开发测试中的一个具体麻烦:填表单、测结账流程、验证地址格式时,需要「看起来真实、结构也真实」的地址,而随手编的街道和邮编往往对不上行政区划。它的做法不是随机拼字,而是从官方地址登记、开放地图数据里取真实存在的街道与门牌记录,生成带来源标注、精度标注和经纬度坐标的地址条目。覆盖 27 个国家和地区,支持 10 种显示语言,可在线用演示站,也可整套自托管部署。截至 2026 年 11 月快照,仓库约 2,297 个星标、338 个 fork,2026 年 7 月创建,11 月当日仍有代码推送,是活跃维护中的项目。
平台背景
这是一个个人开源项目,技术栈写得很明白:前端 Astro 加 React,接口用 Hono,数据库 PostgreSQL 16,运行时 Node.js 24,靠一个同步服务持续从官方登记库、OpenStreetMap、Overture 等开放数据源增量导入。作者在文档里立了个规矩:地址库的每条记录必须能溯源,缺失的字段宁可留空也不编造——这也是它区别于网上那些「随机地址生成器」的根本点,后者多是把街道名、门牌号、邮编随机组合,生成根本不存在的地址。它明确把用途定位在开发测试:表单与结账测试、地址格式验证、物流演示。演示站页面底部也标注了数据版权:地址数据来自 OpenStreetMap 贡献者及所列公开来源,遵循 ODbL 许可。

图:演示站的地址数量监控页,公开各国家地区的覆盖数据(2026-11 截图)
核心服务与功能
- 27 国地址生成:北美(美国、加拿大、墨西哥)、欧洲(英国、德国、法国、意大利、西班牙、荷兰、俄罗斯)、东亚(中国、香港、台湾、日本、韩国)、东南亚(新加坡、马来西亚、泰国、菲律宾、越南)、南亚(印度)、大洋洲(澳大利亚)、中东(土耳其、沙特)、南美(巴西)、非洲(尼日利亚、南非)。
- 按真实行政层级筛选:可按国家、城市、区县、邮编逐级过滤,层级跟随各国真实行政区划;某个筛选条件下没有数据时直接返回错误,而不是悄悄换个地区糊弄。
- 精度与来源标注:每条结果标注精度等级(街道级、门牌级、单元级)和物业类型,中国地址以住宅小区为主,其他国家多为门牌与街道级记录,有独立居住证据时才标为住宅。
- IP 附近生成:演示站可按访问者当前 IP 所在区域就近生成地址,测试地域相关功能时很顺手。
- 多语言与地图预览:结果可按本地语言、英文、简繁中文、日语、韩语、德语、法语、西班牙语、葡萄牙语显示,并可一键在 Google 地图或高德地图打开核对位置。
- 覆盖监控:演示站公开了各国地址数量监控页,数据家底摆在明面上。
- 开放 API:自托管实例提供 Bearer 令牌鉴权的 JSON API,支持单条与批量生成、地点搜索、覆盖查询和地址翻译,附 OpenAPI 3.1 文档。
生成结果的字段结构以仓库给出的 API 示例为准:包含格式化后的完整地址字符串、精度等级(matchLevel,分为街道、门牌、单元三档)、物业类型(有独立居住证据时才标 residential)和经纬度坐标;筛选条件没命中时会明确标注匹配层级,而不是默默放宽。自托管实例还带一个功能完整的管理后台:数据看板、各国工作区、同步历史、快捷地点、服务商密钥、翻译路由、访问控制和 API 令牌都在里面,演示站的监控页就是这个后台公开出来的一部分。
使用方式
轻量用法是直接打开演示站:选国家(或点按 IP 区域生成),需要时再细选州省、城市,点生成即可,结果能复制、导出或收藏;页面还贴心地列了美国无州销售税的五个州和热门城市的快捷入口,这正是电商结账测试的高频需求。正式用法是自托管:服务器需 Linux、Docker 24 以上和 Docker Compose v2,内存 4GB 起步(首次导入大国数据建议 8GB),拉取仓库的 docker-compose.yml 一条命令启动,应用、数据库、迁移和同步服务会一起拉起,初始管理员密码登录后必须修改,之后在管理后台决定公开生成页是否也要密码、并签发 API 令牌。系统默认只监听本机 8787 端口,对外提供服务需自己加 HTTPS 反向代理。
它的同步机制决定了数据的「新鲜度口径」:同步服务对每个数据源做增量导入,失败有次数上限的重试和指数退避,配额耗尽会等待,某个数据源被证实没有新数据后,该国会标记为「来源已达上限」并停止反复入队。一个国家在库里算「完整」,要同时满足三个条件:有效地址总量达标、最低层级行政区覆盖达标、每一级节点数量达标。这些规则都写在仓库文档里,选型时可以据此判断它和「抓一把随机数据塞进数据库」的同类小工具不是一回事。
适用人群
适合跨境电商、独立站开发者测试结账与税务逻辑(不同州省的地址格式与税区差异最容易在测试阶段漏掉),适合做表单与地址校验的程序员,适合物流、地图类产品的演示与联调,也适合本地化团队核对各国地址书写格式。不适合的场景同样明确:它不是「虚拟身份」工具,生成资料的正当用途到测试为止,下一节会专门说明边界。

图:演示站的 API 文档页(2026-11 截图)
免费与付费对照
| 项目 | 说明 |
|---|---|
| 代码 | MIT 开源,免费自托管;官方 Docker 镜像公开提供 |
| 公开演示站 | 免费使用,未见收费说明;长期可用性以站方为准 |
| 自托管成本 | 自己的服务器费用;基础数据源免授权使用,部分国家数据与在线翻译可选用自备的地图/翻译服务密钥增强 |
| 数据许可 | 上游数据集保留各自许可,OpenStreetMap 数据须按 ODbL 署名要求使用 |
优缺点
优点
- 数据真实可溯源:地址来自官方登记与开放数据,带精度和坐标,不是随机拼凑,拿去测结账和物流不容易被格式校验打回来。
- 筛选诚实:没数据就报错,不偷偷换地区,这对测试数据的可信度是关键品质。
- 自托管门槛低:一个 Compose 文件拉起全套,密钥自动生成持久化,文档里部署、升级、备份恢复都写全了。
- 维护活跃:2026 年 7 月发布后持续更新,抓取当日仍有推送(2026-11 快照)。
缺点
- 覆盖不均:27 国的数据深度差别很大,小国可能只有主要城市,自托管首次导入大国数据也吃内存和时间。
- 演示站是个人项目,稳定性和速率没有承诺,正式业务联调建议自托管。
- 中国地址以小区级为主、其他国家精度口径不一,拿结果做统计或训练数据前要先理解各国的精度标注。
- 「真实地址」是双刃剑:记录对应真实存在的街道门牌,使用边界必须守住,见下一节。
同类竞品对比
| 维度 | Address | Free Public APIs | Cloudflare AI Web |
|---|---|---|---|
| 定位 | 专门的测试地址生成器 | 免费公共 API 目录 | AI 网页与接口工具集合 |
| 数据方式 | 真实开放数据加自托管同步 | 收录第三方现成接口 | 在线工具即开即用 |
| 可自托管 | 支持,Docker 一键部署 | 不适用(目录站) | 不支持 |
| 适合 | 需要成体系测试数据的开发团队 | 找练手 API 的开发者 | 零散的网页端小需求 |
Free Public APIs 里也能找到随机用户、地址类的练习接口,但那类接口的数据多为虚构拼凑且服务稳定性看第三方脸色;Address 的差异在于数据真实性和可自托管,代价是要自己运维一套服务。
注意事项与风险
- 用途边界(重要):本站与原项目都把定位写得很清楚——这是开发测试工具。生成结果是合成测试资料,只能用于表单测试、结账联调、格式验证、物流演示等开发场景,不得用于实名注册、冒充他人身份、绕过平台风控、欺诈交易等违法违规用途,这类行为与使用者自行承担全部法律责任。
- 地址记录对应真实地理位置,可能涉及真实住户:禁止用于邮寄骚扰、线下滋扰或任何形式的精准投送。
- 拿生成资料注册的测试账号不要混入生产环境;测试数据与真实用户数据混杂会给后续合规审计埋雷。
- 自托管时务必修改默认管理员密码并给公开生成页设置访问控制,避免自己的实例被他人滥用为批量生成入口。
- 商用引用其数据时保留上游署名:OpenStreetMap 等数据源遵循 ODbL 等许可,署名义务不因工具开源而免除。
