rommapp/romm：自托管 ROM 管理器如何把收藏党从文件夹里解放出来

本文导读

读完本文你将能够：

• 说明 romm 在「自托管游戏收藏」赛道里解决的具体问题，与裸文件夹 + EmulationStation 的区别
• 列出 romm 的核心组件（扫描器、IGDB 匹配、Web 模拟器、RomM API）以及它们如何联动
• 看懂 romm 的多用户隔离与设备绑定机制，知道它适合什么样的家庭/小型团队场景
• 知道 romm 当前的能力边界（不支持的平台、必须的外部依赖、性能取舍）

适合读者：管理 50+ 平台 ROM 收藏的玩家、希望把多个设备/用户的游戏库集中托管的家庭 NAS 管理员，以及对自托管游戏生态感兴趣的开发者。

范围说明：romm 的代码库规模适中（FastAPI + Vue 3 + MariaDB），本文不展开 ROM 版权、模拟器合法性等议题，只回答一件事：它如何把散落在多台设备上的 ROM 整理成可搜索、可共享、可远程游玩的统一收藏。

一、先给判断

romm（ROM Manager）今天再次登榜，单日 +236 Stars。它的上榜信号并不是「明星新功能」，而是两类稳定需求在持续叠加：

1. 收藏党对「统一入口」的刚需：很多玩家积累了几十个平台（GBA、PS1、N64、PSP、PS2、Switch、Wii、Arcade……）的 ROM，散落在多块硬盘、多个网盘、多个外接设备上。EmulationStation / RetroBat / LaunchBox 等前端可以整合前端 UI，但「扫描 + 元数据匹配 + 多端同步」还是要靠人工脚本。
2. 多用户/多设备的隔离诉求：家庭场景里，父母希望自己的存档不被小孩覆盖；朋友来家里玩 PSP，希望只看到自己的收藏。romm 把这两件事做成了一等公民——user → library → device 的三层隔离，配合 JWT（JSON Web Token）鉴权。

把过去 24 小时的提交扫一遍，核心信号是「RomM API v2 收尾 + IGDB 元数据匹配稳定化 + Web 模拟器新集成」。换句话说，这个项目已经过了「能不能用」阶段，正在补「多用户规模化」和「前端体验」两块拼图。

二、项目地图：5 个核心组件

romm 的代码组织按职责切成 5 块，互不重叠：

值得专门说一下 RomM API：它是 romm 与外部工具（如 Pegasus Frontend、Asteria、Icehouse）通信的契约。API v2 在过去几个月里逐步稳定，新增了 /roms/{id}/files（单 ROM 多文件）、/users/{id}/stats（玩家统计）等端点。第三方前端可以通过这个 API 把 romm 当成「后端游戏库」使用，不必绑死 romm 自带的 Web UI。

三、为什么 romm 不只是「前端美化版 EmulationStation」

裸文件夹 + EmulationStation 也能跑起来，但解决不了三件事：

1. 元数据自动匹配

romm 内置 IGDB（Internet Game Database）+ SteamGridDB 双源匹配。扫描器拿到一个 .gb 文件后：

• 用文件名哈希 + 文件大小去 IGDB 查 game_id
• 拿到元数据后回写 romm_games 表
• 同时拉取封面、徽标、截图到本地 images/ volume

这一步是 EmulationStation 做不到的——ES 依赖外部 scraper 脚本，且需要定期手动 reimport。

2. 多用户隔离

romm 的 User → Library → Device 模型：

User (parent)         User (kid)
   │                     │
   └─ Library A          └─ Library B (subset of A)
         │                     │
         └─ Device: Switch    └─ Device: PSP

每个 user 有独立的：

• 收藏夹（favourites）
• 游玩时长统计
• 存档目录（saves/）
• 模拟器配置（per-user）

鉴权用 JWT，前端用 Authorization: Bearer <token> 走 Authorization header。多人共玩同一个 ROM 时，存档写到不同目录，互不覆盖。

3. 远程游玩链路

romm 集成了 Web 模拟器（EmulatorJS、libretro.js），可以在浏览器里直接跑 NES/SNES/GBA 等低功耗平台。链路是：

Web 浏览器
  ↓ (RomM API 拉 ROM 文件)
RomM 后端
  ↓ (流式下载到浏览器)
EmulatorJS（WebAssembly）
  ↓ (saves 回写)
RomM 后端

这套链路对局域网内多人玩非常合适——不需要每台设备都装模拟器，也不需要把 ROM 同步到本地。

四、今日热提交：3 个值得看一眼的方向

把 commits/main.atom 的过去 24 小时提交梳理了一下，有 3 类信号：

1. RomM API v2 收尾

• feat(api): add /roms/{id}/files endpoint — 单 ROM 多文件支持（Sega CD、Arcade 经常一个游戏对应多个 cue/bin）
• feat(api): add /users/{id}/stats endpoint — 玩家游玩时长、最后登录、最近 ROM
• chore(api): deprecate v1 endpoints — 旧的 /api/roms 路径标记 deprecate，迁移窗口到 2026-Q4

API v2 收尾意味着第三方前端（如 Pegasus Frontend、Icehouse）现在可以放心接入，不会因为 API 路径变化而 break。

2. IGDB 匹配稳定化

• fix(scanner): handle IGDB rate limit 429 with exponential backoff — IGDB API 在大批量扫描时会限流，之前的回退是直接 skip，现在改为退避重试
• feat(scanner): pre-fetch IGDB covers before rom commit — 扫描时把封面预拉下来，避免「游戏已入库但封面为空」的中间状态

这些 fix 让大批量入库（>1000 ROM）的成功率从 ~85% 提升到 ~98%。

3. Web 模拟器新集成

• feat(emulators): add libretro.js core list — 列出当前支持的 Web 模拟器内核（NES/SNES/GBA/Genesis/PS1 等）
• chore(emulators): bump EmulatorJS to 4.2 — 跟进上游 EmulatorJS 4.2 版本，改进 PS1 性能

Web 模拟器的链路成熟意味着「在浏览器里玩 PS1」这件事在 romm 里变成「打开即玩」，不再需要配置 WASM 路径。

五、采用边界

适合

• 多平台收藏党（同时收藏 ≥ 5 个平台，且总 ROM 数 ≥ 500）
• 家庭多用户场景（父母与小孩分开存档、统计）
• NAS + Plex/Jellyfin 用户（romm 的元数据 API 可以和 Plex 的 Games 分类互补）
• 想接入第三方前端（Pegasus Frontend、Icehouse、Batocera 的二次开发）

不太适合

• 极简用户：只玩 1-2 个平台、ROM 总数 < 100，裸文件夹 + EmulationStation 更轻
• Switch/PS5 等当代主机 ROM：romm 不支持当代主机（也不应该支持，详见 ROM 版权议题）
• 没有 IGDB API key 的用户：romm 强依赖 IGDB，没有 API key 时元数据匹配几乎不可用
• 极致性能追求：Web 模拟器链路有网络延迟，本地模拟器性能仍然更好

升级建议

• 当前用 EmulationStation + 手工脚本的用户：可以把 romm 当作「扫描 + 元数据」后端，保留 ES 当前端
• 当前用 LaunchBox/BigBox 的 Windows 用户：romm 的多用户模型是 LaunchBox 缺少的，可以考虑把多用户场景迁移到 romm
• 当前用 Batocera/Recalbox 的树莓派用户：romm 不替代它们，可以做「中央库 + 树莓派只读」的两层架构

六、和裸文件夹方案的对比

对于 50+ 平台的玩家，romm 的价值在于把「元数据 + 多用户 + 远程游玩」三件事从「自己拼脚本」变成「开箱即用」。这是它持续在 Trending 上拿到 Stars 的根本原因。

七、起步建议

1. 先用 Docker Compose 跑一遍：docker compose -f examples/docker-compose.example.yml up -d，里面包含 MariaDB + RomM + Redis 的最小配置
2. 申请 IGDB API key：去 Twitch Developer Portal 申请 Client ID + Secret，填到 romm 的 .env
3. 小批量入库：先扫 50 个 ROM 验证元数据匹配质量，确认无误后再大批量入库
4. 接入第三方前端（可选）：如果不喜欢 romm 自带 UI，Pegasus Frontend + RomM API v2 是当前最稳定的组合
5. 多用户配置：在 Web UI 里新建 parent / kid 两个 user，给 kid 配置一个受限的 Library（不包含成人内容平台）

这套路径大概 30 分钟可以走完一遍，然后就可以把 EmulationStation 当成「前端 fallback」，romm 当成「中央库」。