Address数据同步机制拆解增量导入、有界重试与配额轮换完全解读【免费下载链接】addressA self-hosted address and synthetic test-profile generator for 27 countries and regions, built from real open-data streets, administrative areas, coordinates, and postcodes. Supports multilingual output, IP-nearby generation, map previews, and API access. 基于真实开放数据的自托管地址与合成测试资料生成器覆盖 27 个国家和地区支持多语言地址、IP 附近生成、地图预览与 API 调用项目地址: https://gitcode.com/gh_mirrors/address4/addressAddress 是一个基于真实开放数据街道、行政区、坐标、邮编的自托管地址与合成测试资料生成器覆盖 27 个国家和地区。它的核心难题在于如何低成本、可恢复地把 OSM、Overture、Geofabrik 等海量上游数据同步进本地数据库。这篇文章拆解 Address 同步引擎的三大核心机制——增量导入、有界重试与配额轮换帮助你理解它何时同步、如何重试、怎样省额度。一、架构总览独立进程 国家级事务同步服务是一套独立运行的 ETL 管道源码位于 server/sync/与主 API 共享同一个 PostgreSQL 数据库并以国家为单位组织事务入口与调度address-etl.mjs 负责执行单次同步index.mjs 启动管理 API 并在开启SYNC_SCHEDULER_ENABLED时自动补跑未完成的初始化。任务协调coordinator.mjs 中的SyncCoordinator用文件锁保证同一时刻只有一个同步任务在跑并默认设置 5 分钟锁超时、90 分钟任务超时防止进程卡死后永远占用锁。发布原则每个国家的数据在单个事务中发布失败不会替换现有 active dataset线上服务始终能用上一份好数据。管理接口默认仅监听127.0.0.1:8791并要求BearerToken 认证详见 server/sync/README.md。二、增量导入只同步到期的国家27 个国家不可能每天都全量重导。Address 的增量决策分三层1. 到期检查country duecountry-plan.mjs 的isCountryDue是核心闸门距上次成功同步不足intervalDays的国家直接跳过但未达到目标数量的国家会自动降为每天重试加速追赶目标。排序规则 planCountryShards 则让失败国家优先、最久未成功的国家靠前。2. 输入指纹去重address-etl.mjs 会为每个分片计算指纹签名包含来源适配器、上游数据版本、导入修订号、国家级策略参数等。相同指纹且已完成或已耗尽的国家不会重复导入只有上游版本更新、新来源接入或提取能力变化后才会重新获得执行资格——这就是相同输入指纹已经完成或耗尽时不重复导入的实现。3. Checkpoint 续跑长任务如日本实测峰值约 6.5 GB 内存中途失败时进度以checkpointStage/checkpointToken记录在任务状态中见 address-etl.mjs额度、冷却或 checkpoint 到期后自动从断点续跑而非从零开始。三、有界重试三层防线绝不无限循环有界是这套同步系统最显眼的特征——每一层重试都有明确次数上限和退避策略层级位置策略HTTP 请求级source-adapters.mjs默认 3 次尝试仅对 408 / 429 / 5xx 等可重试状态码生效退避间隔按250ms × 2^(n-1)指数递增下载传输级source-adapters.mjsGeofabrik 大文件下载走curl --retry 3 --retry-all-errors重试耗尽后校验和仍不符则判定失败一天内已完整下载的旧版本可复用避免跨日重复下载每日任务级scheduler.mjstriggerDailySync默认maxAttempts 3失败后重试延迟60s × 2^(n-1)且封顶 1 小时当日 3 次耗尽后记录attempts-exhausted并等待次日任务级重试的状态lastAttemptDate、attemptCount、nextRetryAt通过临时文件原子写入持久化进程重启后依然记得今天重试了几次——这意味着重试预算是按自然日计的不会因服务重启而无限消耗上游。四、配额轮换凭据池 冷却窗口需要同据如韩国的GEOAPIFY_API_KEY的同步任务凭据管理交给 provider-credential-pool.mjs 中的ProviderCredentialPool它实现了教科书式的配额轮换取用顺序公平acquire按last_used_at升序取最久未使用的凭据并按qps_limit判断是否仍在 QPS 窗口内天然形成轮换而非打爆单个 Key。多维配额窗口quotaAvailable同时检查按天、按月可带时区偏移的配额窗口还会读取上游返回的观察值实际额度与重置时间修正本地计数防止本地以为没超、上游早已限额。失败冷却凭据失败后进入cooldown/quota_exhausted状态冷却时间来自上游的Retry-At缺省规则为配额耗尽冷却 24 小时、普通错误冷却 5 秒到期的凭据会在下次取用时自动恢复为healthy并清空上报的额度快照。安全存储凭据使用 AES-256-GCM 加密落库主密钥来自CONFIG_MASTER_KEY解密失败的凭据会被标记needs_review而不是反复尝试。配合 geoapify-credential-bridge.mjs 等桥接器同一提供商配置多个 Key 时即可一个 Key 限流自动切下一个。五、存储预算同步目录的安全带同步过程会产生大量下载残片与中间产物Address 用两道预算管住磁盘storage-budget.mjs同步目录达到40 GB后停止 shadow 扩容预计达到45 GB时直接中止写入。清理策略也很克制只在队列空闲时清理 staging 临时产物启动时立即检查一次此后默认每 15 分钟一次死亡 PID 的临时文件立即回收无主下载残片默认保留 6 小时——避免误删正在下载中的文件。此外run-address-sync在可用内存低于 2 GiB 时拒绝启动见 run-address-sync.mjs。六、如何观察同步状态 不用读日志也能掌握全局公共监控页展示各国初始化进度与覆盖率前端实现见 src/components/PublicMonitor.tsx管理后台在/admin/可查看各国策略目标、凭据配置与同步任务相关界面组件位于 src/components/admin/。总结三句话记住这套机制增量指纹去重 到期检查 checkpoint 续跑相同输入绝不重复导入失败任务从断点继续有界HTTP 3 次指数退避、每日 3 次重试封顶 1 小时每一层重试都有预算轮换凭据池按最久未用公平取用配额耗尽自动冷却 24 小时Key 之间无缝轮转。这套设计让自托管的 Address 在数据要新和别把上游打挂之间取得了很好的平衡——这也是它敢覆盖 27 个国家地区的底气所在。【免费下载链接】addressA self-hosted address and synthetic test-profile generator for 27 countries and regions, built from real open-data streets, administrative areas, coordinates, and postcodes. Supports multilingual output, IP-nearby generation, map previews, and API access. 基于真实开放数据的自托管地址与合成测试资料生成器覆盖 27 个国家和地区支持多语言地址、IP 附近生成、地图预览与 API 调用项目地址: https://gitcode.com/gh_mirrors/address4/address创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考