Colyseus GeoIP 房间插件深度解析：三种数据库交付模式与 0.18.x 版本演进实录

• 后端
• 游戏开发

@colyseus/geoip是 Colyseus 官方仓库中面向房间（Room）的国家级 GeoIP 插件，它在鉴权阶段解析客户端 IP，并在onJoin执行前把国家信息挂载到client.geoip。本文以 packages/room-plugins/geoip/CHANGELOG.md 为骨架，逐一还原 0.18.2 → 0.18.3 → 0.18.4 三个版本的关键修复（失败重试、刷新告警、零配置下载、双构建统一），并对照 README 与源码把三种数据库交付模式、并发安全、许可与隐私讲透。读完你既能按三种模式落地部署，也能理解插件内部 reader 缓存、原子写入与刷新调度是如何工作的。

一、0.18.x 版本演进总览：CHANGELOG 里藏着哪些关键改动

CHANGELOG 只记录了三段历史，但每一段都对应一次真实的生产事故修复：

下文将按"插件核心机制 → 三种交付模式 → 三个版本修复的源码级解读 → 工程细节（共享 reader、并发安全、测试、许可）"的顺序展开，你可以把 0.18.3 一节当作升级到 0.18.4 的决策依据。

二、插件定位与核心机制：auth 阶段挂载client.geoip

插件是一个RoomPlugin子类，声明pluginName = 'geoip'，通过definePlugins挂到房间上（见 src/GeoIPPlugin.ts）：

import { Room, definePlugins } from "@colyseus/core"; import { GeoIPPlugin } from "@colyseus/geoip"; class MyRoom extends Room { plugins = definePlugins([ new GeoIPPlugin({ dbPath: "./GeoLite2-Country.mmdb" }), ]); async onJoin(client) { console.log(client.geoip); // { isoCode: "BR", name: "Brazil", continent: "SA", isInEU: false } } }

生命周期有两步（源码 src/GeoIPPlugin.ts）：

1. onCreate：按配置加载数据库 reader（三种模式见下节），加载过程被模块级readerCache缓存；
2. onAuth：从AuthContext.ip取 IP（支持x-forwarded-for逗号链，取最左侧第一个），调用lookup(ip)得到GeoIPData后写入client.geoip。

挂载的数据结构定义在 src/types.ts：

export interface GeoIPData { isoCode: string; // ISO 3166-1 alpha-2 国家码，如 "BR"、"US" name: string; // 英文国家名，如 "Brazil" continent?: string; // ISO 3166-1 大洲码：AF、AN、AS、EU、NA、OC、SA isInEU?: boolean; // 是否欧盟成员国，MaxMind country 记录带有该字段，适合 GDPR 路由 }

几个关键行为（均有测试佐证，见 test/GeoIPPlugin.test.ts）：

• 解析失败（loopback、RFC1918 私网、IPv6 link-local、数据库缺失、IP 畸形）时client.geoip保持undefined，绝不阻塞加入流程——lookup()内部捕获一切异常返回undefined（src/GeoIPPlugin.ts）；
• 插件默认在房间自身onAuth之前执行，测试runs before the room's own onAuth验证了这一点；
• this.plugins.geoip.lookup(ip)可随时从房间代码调用，用于重连时重新解析、反欺诈启发式或给分析事件打国家标签（测试exposes lookup() via this.plugins.geoip from inside the room覆盖）。

类型层面，src/index.ts 对@colyseus/core的Client做了模块扩充，声明了可选的geoip?: GeoIPData字段，因此client.geoip在 TS 下也有完整类型提示。

三、三种数据库交付模式：一份插件，三种取数方式

插件读取的是 MMDB 二进制格式（MaxMind GeoLite2 与 DB-IP Lite 共用该格式），构造函数的三种变体对应三种数据来源（src/GeoIPPlugin.ts）：

export type GeoIPPluginOptions = | { dbPath: string } | (AutoDownloaderOptions & { refreshIntervalMs?: number }) | (DBIPDownloaderOptions & { refreshIntervalMs?: number });

模式一：dbPath—— 自带文件，自己维护

new GeoIPPlugin({ dbPath: "/var/lib/geoip/GeoLite2-Country.mmdb" })

适合已有 MaxMindgeoipupdatecron、自定义拉取 DB-IP 的构建步骤，或任何现成的工作流。此模式不会注册刷新定时器——文件的所有权在运维方手里（src/GeoIPPlugin.ts），插件只是同步读入内存：

const buffer = fs.readFileSync(dbPath); this.reader = new Reader<CountryResponse>(buffer);

模式二：accountId+licenseKey—— 从 MaxMind 自动拉取

new GeoIPPlugin({ accountId: process.env.MAXMIND_ACCOUNT_ID, licenseKey: process.env.MAXMIND_LICENSE_KEY, cacheDir: "/var/cache/colyseus-geoip", // 可选，默认 <os.tmpdir()>/colyseus-geoip refreshIntervalMs: 7 * 24 * 60 * 60 * 1000, // 可选，默认每周 })

底层由 AutoDownloader 实现：

• 使用 MaxMind 官方 permalink 端点download.maxmind.com/app/geoip_download，以 Basic Auth 携带accountId:licenseKey，请求edition_id=GeoLite2-Country&suffix=tar.gz；
• 返回的是 gzip 压缩的 tar 包，代码手工解析 POSIX-ustar 头（目录 + .mmdb + COPYRIGHT + LICENSE 的固定结构）提取唯一一个.mmdb条目，避免引入 tar 依赖（src/readers/AutoDownloader.ts）；
• 文件先写 PID 作用域的临时路径，再renameSync原子改名落位（见下节"并发安全"）；
• 默认刷新周期是每周一次（MAXMIND_REFRESH_MS = 7 * 24 * HOUR，因为 GeoLite2 每周重建），可用refreshIntervalMs覆盖。

注意：MaxMind 许可要求每个账号自行下载、不得转分发，因此插件不会把 MaxMind 数据打包进 npm 包，只在你自己的机器上落地一份。

模式三：零配置 DB-IP Lite —— 0.18.3 引入的默认模式

new GeoIPPlugin() // 可选： new GeoIPPlugin({ cacheDir: "/var/cache/colyseus-geoip" })

不传任何参数即进入此模式，由 DBIPDownloader 实现：

• 首次启动从 db-ip.com 的免费目录下载dbip-country-lite-YYYY-MM.mmdb.gz（gzip 直接解压到磁盘，无中间文件）；
• 文件名按月打戳，DB-IP 每月 1 号发布新快照。fetch()的"是否最新"就是一次existsSync，当月文件已存在则零网络请求直接复用（src/readers/DBIPDownloader.ts）；
• 新月份快照还没发布时自动回退到上个月的文件；下载失败时若上月文件存在则静默使用上月版本（月初的例行现象，不打扰日志）；
• 每次成功确认某月文件后调用keepOnly，清掉目录里其他月份的快照——每份约 8 MB，避免逐月堆积；
• 默认刷新周期为每天一次（DBIP_REFRESH_MS = 24 * HOUR），只为捕捉月初的版本切换。

体积账（README 原话）：DB-IP 数据走网络拉取而非随包分发，包体保持约 100 KB，每次下载约 4 MB 传输、8 MB 落盘，且只有使用该模式的人才付出这份流量。离线（air-gapped）环境请用模式一自己放文件。

四、0.18.3 三个关键修复的源码级解读

1. 加载失败自动重试：失败的 promise 不再被永久缓存

0.18.3 之前，onCreate加载数据库失败会把失败的 promise 留在模块级readerCache里，此后每创建一个房间都会复现同一个异常，除非重启进程才能恢复。

现在的实现（src/GeoIPPlugin.ts）：

let pending = readerCache.get(this.cacheKey); if (pending === undefined) { pending = loadReader(this.opts).catch((e) => { // 只有当前条目仍是自己时才驱逐，避免误删刷新期间落位的新条目 if (readerCache.get(this.cacheKey) === pending) { readerCache.delete(this.cacheKey); } throw e; }); readerCache.set(this.cacheKey, pending); scheduleRefreshIfApplicable(this.cacheKey, this.opts); } this.reader = await pending;

失败时以"当前缓存条目仍是自己"为条件的驱逐逻辑很关键：如果某次刷新恰好同时成功写入了新 reader，旧失败不会把新条目顶掉。测试retries a failed database load and continues sharing a successful reader完整复现了这个场景（test/GeoIPPlugin.test.ts）：第一次onCreate因文件缺失抛ENOENT，随后把 fixture 文件复制到位，再建一个新房间就能成功加载，且成功后的 reader 会持续共享（即使磁盘文件后来被删除，内存中的 reader 依然可查）。感谢社区贡献者 @fatihcvs 的 PR。

2. 刷新失败输出告警：过期 license 不再静默失效

0.18.3 之前，定时刷新失败完全静默。最典型的事故是：MaxMind license key 过期后，进程一直端着启动时加载的旧数据库为用户服务，几个月无人察觉。

现在的刷新循环（src/GeoIPPlugin.ts）把异常交给logger.warn：

} catch (e: any) { logger.warn(`@colyseus/geoip: database refresh failed, still serving the one loaded earlier — ${e.message}`); }

行为语义是"继续服务旧数据 + 下一个 tick 重试"：刷新失败不会杀掉进程，也不会清空当前 reader，但一定会打一条带原因（如401、403）的告警日志，让你能及时续期。

3. 零配置模式修复：从"必然 ENOENT"到"首启即下载"

0.18.3 之前，new GeoIPPlugin()读的是一个本应随发布捆绑、却从未真正打进包的数据库路径，结果每次创建房间都抛ENOENT——零配置模式形同虚设。

修复后，无参数构造进入 DB-IP 模式（src/GeoIPPlugin.ts）：

// Default mode — DB-IP Lite Country, fetched from db-ip.com on first // boot and reused from the on-disk cache afterwards. return new MMDBReader(await new DBIPDownloader(opts).fetch());

首次启动需要外网访问，之后全部走本地缓存。这也带来一个版本升级提示：如果你当前跑在 0.18.3 之前的零配置模式上，升级后首次启动会真正发生一次下载，请确认出网策略与磁盘空间。

五、0.18.4：require()与import双构建统一

0.18.4 修复了 #979 描述的问题：此前require()和import各自解析到不同构建产物，同一进程两种加载方式并存时会出现两份插件副本（两份模块级readerCache、两份刷新定时器），既浪费内存又可能造成行为不一致。

0.18.4 之后，require()解析到与import相同的 ESM 构建。这一点直接体现在 package.json 的exports映射上：

"exports": { ".": { "@source": "./src/index.ts", "types": "./build/index.d.ts", "module-sync": "./build/index.mjs", "import": "./build/index.mjs", "require": "./build/index.cjs" }, "./*": { ... } }

双构建场景下，模块级readerCache（Map<string, Promise<GeoIPReader>>）与refreshTimers（Map<string, NodeJS.Timeout>）只需一份，跨房间共享 reader 与刷新调度的语义才成立。该版本同时要求 Node.js >= 22（见 package.json 的engines字段）。

六、0.18.2：内置数据库路径通过import.meta.dirname解析

0.18.2 是内部修复：随包数据库路径改为基于import.meta.dirname解析。import.meta.dirname是 Node.js 22 提供的、面向 ESM 的"当前模块目录"语法，取代基于__dirname的兼容写法。在"type": "module"的包结构下（见 package.json），这能保证路径计算在任意安装位置都正确。该版本已从编译产物路径正确性上为 0.18.3 的"零配置下载 + 磁盘缓存"铺路——因为默认模式不再依赖随包文件，路径解析问题的历史包袱也随之消失。

七、共享 reader 与内存控制：多房间只加载一份数据库

插件把 reader 缓存在模块级Map，key 由配置计算（src/GeoIPPlugin.ts）：

• dbPath模式：path:<dbPath>；
• MaxMind 模式：mm:<accountId>:<edition>（edition 默认GeoLite2-Country）；
• DB-IP 模式：dbip:<cacheDir>。

同一 key 的所有房间共享同一个 reader 实例，内存保持平摊——即使开了 N 个房间也只加载一份数据库。刷新落地新文件时（如 MaxMind 每周重建后重开 reader、DB-IP 换月后重开 reader），代码用readerCache.set(key, Promise.resolve(new MMDBReader(...)))替换旧条目，旧实例交给 GC 回收（src/GeoIPPlugin.ts）。

Reader 本身是同步 MMDB reader：MMDBReader构造时把整个文件读入内存（fs.readFileSync），lookup()在微秒级完成（src/readers/MMDBReader.ts）。它把 MaxMind 与 DB-IP 共同暴露的country/continent记录结构映射为统一的GeoIPData；is_in_european_union只取country记录上的标记（测试说明：fixture 中英国范围只在registered_country层级有该标记，reader 按设计忽略，因此isInEU为undefined）。

八、并发安全：PID 作用域临时路径 + 改名前的二次检查

两种自动下载器都针对"多进程共享同一cacheDir"做了并发防护（这是分布式/PM2 多实例部署的常见场景）：

1. PID 作用域临时路径：下载先写到${dbPath}.${process.pid}.${Date.now()}.tmp，任何时刻共享目录里只存在一个原子renameSync，这是 POSIX 上唯一共享写操作；
2. 改名前的二次检查：AutoDownloader.fetch()在提交前重新existsSync(dbPath)——如果竞争进程已经先落地了完整文件，本进程直接丢弃自己的副本（src/readers/AutoDownloader.ts）；
3. finally中safeUnlink兜底清理临时文件，异常路径不留垃圾。

验证方式见下一节的--concurrent模式：fork N 个子进程对同一缓存目录并发fetch()，断言所有子进程最终拿到字节级一致的 sha256。

九、手动验证自动下载器：scripts/test-autodownloader.ts

AutoDownloader需要真实 MaxMind 凭证与外网，因此不在 mocha 套件内，而是独立脚本（scripts/test-autodownloader.ts）：

MAXMIND_ACCOUNT_ID=... MAXMIND_LICENSE_KEY=... \ pnpm tsx scripts/test-autodownloader.ts # 验证跨进程竞态修复：fork N 个并发 fetch 的 peer MAXMIND_ACCOUNT_ID=... MAXMIND_LICENSE_KEY=... \ pnpm tsx scripts/test-autodownloader.ts --force --concurrent 4

支持的参数：--cache-dir <path>（覆盖默认 tmp 缓存目录）、--force（忽略已有缓存强制重下）、--concurrent <N>（fork N 个子进程同时fetch()同一目录，父进程收集每个子进程打印的sha256，断言集合大小为 1——即所有人收敛到同一份完整、一致的 .mmdb）。脚本跑通后还会用MMDBReader对8.8.8.8、1.1.1.1、81.2.69.142、IPv6 地址做 sanity lookup。免费凭证在 MaxMind 官网的 GeoLite2 注册页获取。

十、测试覆盖：两层套件如何背书这些行为

test/GeoIPPlugin.test.ts 明确分成两层：

1. GeoIPPlugin单元层：用MockReader隔离驱动onAuth热路径，覆盖：auth 阶段挂载、不可解析 IP 保持undefined、x-forwarded-for逗号链取最左、reader 抛异常不阻塞加入、插件先于房间自身onAuth执行；
2. MMDBReader集成层：用 MaxMind 官方提供的测试 fixture GeoLite2-Country-Test.mmdb（Apache-2.0，见 NOTICE.md）覆盖真实 MMDB 解码与字段映射：IPv4、IPv6、数据库缺失返回undefined、畸形 IP 不抛异常、this.plugins.geoip.lookup()房间内调用、端到端onCreate → onAuth流程，以及上文提到的"失败后重试成功并持续共享 reader"。

DBIPDownloader的离线测试则不触网：利用月戳文件名，把 fixture 复制成当月快照放进临时缓存目录，验证零配置模式直接从缓存加载、并且只保留当前月份文件。运行方式见 package.json：mocha test/**.test.ts --exit --timeout 15000。

十一、许可与隐私：按模式区分你的义务

插件会读取两种独立许可的数据库，义务随模式不同：

• MaxMind GeoLite2（模式一、二）：受 GeoLite2 EULA 约束。免费供账号持有者商用；禁止转分发，每个使用者必须用自己的凭证下载，因此插件不捆绑 MaxMind 数据；不可用于 FCRA 管制决策（信贷、保险、雇佣、政府福利）；若对外展示数据需注明"本产品包含 MaxMind 创建的 GeoLite2 数据"。
• DB-IP Lite（模式三）：采用 CC BY 4.0。本包不转分发（文件从 db-ip.com 直接下载到你的机器），署名义务属于作为运营方的你，建议文案如 "IP-to-country data from DB-IP.com, available under CC BY 4.0"。若游戏界面向玩家展示国家信息，DB-IP 建议附上其链接信用（如<a href="https://db-ip.com">IP Geolocation by DB-IP</a>）。

隐私：插件从客户端 IP 推导国家。IP 本就对服务器可见，推导出的国家属于同类个人数据，应同等对待（GDPR/CCPA 等）。如果要把client.geoip持久化到会话之外，需在隐私政策中披露。

十二、升级建议与总结

• 0.18.2 → 0.18.3：核心收益是"零配置模式可用 + 加载失败可自愈 + 刷新失败可观测"。若你一直在零配置模式却从没真正拿到过数据（旧版本ENOENT），这次升级会首次触发下载，确认出网与cacheDir（默认系统 tmp 目录）可写。
• 0.18.3 → 0.18.4：收益是双构建统一，杜绝require/import混用时的双副本。注意 Node.js 版本要求为 >= 22（import.meta.dirname、fetch等均依赖新运行时）。
• 离线部署：任何模式都要求首次启动有出网能力；无法出网时请使用模式一，自行把 .mmdb 文件放到dbPath。

从 CHANGELOG 的三行记录出发，可以还原出一条完整的设计主线：默认零配置（DB-IP）降低上手门槛，MaxMind 模式满足合规与定制，dbPath 模式兜底离线与既有运维；而 reader 缓存、失败驱逐、刷新告警与原子落位四件事，共同保证了插件在长期运行、多房间、多进程的真实生产环境下"不会悄悄坏掉"。

深入阅读路径

• 变更记录：packages/room-plugins/geoip/CHANGELOG.md
• 完整使用文档：packages/room-plugins/geoip/README.md
• 插件主实现：packages/room-plugins/geoip/src/GeoIPPlugin.ts
• 类型与模块扩充：packages/room-plugins/geoip/src/types.ts、packages/room-plugins/geoip/src/index.ts
• 三个 reader：MMDBReader / AutoDownloader / DBIPDownloader（src/readers/）
• 测试与手动脚本：test/GeoIPPlugin.test.ts、scripts/test-autodownloader.ts
• 包元信息与导出映射：package.json

• 后端
• 游戏开发