RomM 自托管 ROM 管理教程Docker 部署、多平台游戏库扫描与浏览器内游玩【免费下载链接】rommA beautiful, powerful, self-hosted ROM manager and player.项目地址: https://gitcode.com/GitHub_Trending/rom/romm你的 Game Boy、Snes、PS1 游戏 ROM 散落在不同的硬盘里命名五花八门想找某个游戏封面还得手动搜图——这种情况靠再买一块硬盘或再写一遍文件夹整理脚本都解决不了需要的是一个专门的自托管系统。RomM 就是这样一款 ROM 管理器兼播放器一个 Docker 镜像把扫描、元数据、浏览和浏览器内游玩全部打包给你。读完本文你能解决这些问题✅ 15 分钟内用 Docker 跑起完整的 RomM 服务含数据库✅ 按正确规则组织多平台游戏库目录让 RomM 自动识别 400 平台✅ 完成首次扫描并逐项验证封面、描述、标签是否解析到位✅ 配置浏览器内游玩EmulatorJS与跨设备存档同步✅ 掌握定时重扫、文件监控等增强项和常见故障的自检方法RomM 的 Docker 部署步骤先让服务跑起来前置条件与准备清单开始前确认三件事系统已安装 Docker 和 Docker Compose你有一块存 ROM 的目录本教程假设为./library你能生成一串会话密钥。✅ 密钥只需生成一次之后所有登录的会话都靠它加密生成命令是openssl rand -hex 32。创建 .env 文件必填字段只有 5 个在部署目录如romm-setup下创建.env完整变量清单见 env.template每个变量都有中文注释这里只给最小可运行版本# 应用会话密钥必填openssl rand -hex 32 生成 ROMM_AUTH_SECRET_KEY这里粘贴64位十六进制字符串 # 数据库配置必须与下方 mariadb 容器保持一致 DB_HOSTromm-db DB_NAMEromm DB_USERromm-user DB_PASSWD你的数据库密码 DB_ROOT_PASSWD数据库root密码⚠️ 注意DB_NAME、DB_USER、DB_PASSWD必须与 compose 文件里 MariaDB 的MARIADB_DATABASE、MARIADB_USER、MARIADB_PASSWORD完全对应这是新手部署失败的第一大原因。编写 docker-compose.yml 并验证容器健康参考官方模板 examples/docker-compose.example.yml最小版本如下services: romm: image: rommapp/romm:latest container_name: romm restart: unless-stopped env_file: .env environment: - DB_HOSTromm-db - DB_NAMEromm - DB_USERromm-user - DB_PASSWD${DB_PASSWD} volumes: - ./resources:/romm/resources # RomM 下载的封面、截图等资源 - ./library:/romm/library # 你的游戏库核心目录 - ./assets:/romm/assets # 存档、金手指、截图等上传内容 - redis_data:/redis-data # 后台任务缓存 ports: - 8080:8080 # 对外访问端口 depends_on: romm-db: condition: service_healthy # 等数据库健康检查通过再启动 romm-db: image: mariadb:latest container_name: romm-db restart: unless-stopped environment: - MARIADB_ROOT_PASSWORD${DB_ROOT_PASSWD} - MARIADB_DATABASEromm - MARIADB_USERromm-user - MARIADB_PASSWORD${DB_PASSWD} volumes: - mysql_data:/var/lib/mysql healthcheck: test: [CMD, healthcheck.sh, --connect, --innodb_initialized] start_period: 30s interval: 10s retries: 5 volumes: mysql_data: redis_data:执行启动并验证docker compose up -d # 后台启动全部服务 docker compose ps # 判断成功romm 与 romm-db 均显示 Up (healthy) docker compose logs -f romm # 观察日志确认出现数据库连接成功、服务监听 8080 的记录 最终判定标准浏览器访问http://localhost:8080能看到登录页首次会自动进入初始化向导说明 Web 层、数据库、缓存三者已打通。游戏库目录结构配置让 RomM 自动识别平台单文件与多光盘的两级规则RomM 靠文件夹层级判断平台、靠子文件夹判断多文件游戏。核心规则只有两条文件直接放在平台目录下 单文件游戏平台目录下的每个子文件夹 一个游戏。典型结构library/ ├── roms/ │ ├── snes/ │ │ ├── Super Mario World.sfc # 单文件游戏 │ │ └── Final Fantasy VI/ # 多光盘一个文件夹一个游戏 │ │ ├── disc1.smc │ │ └── disc2.smc │ └── ps1/ │ └── Final Fantasy VII/ │ ├── disc1.iso │ ├── disc2.iso │ └── disc3.iso └── bios/ └── ps1/ └── scph1001.bin # BIOS 按平台目录存放⚠️ 文件名建议保留(USA)、(J)、(Rev 1)这类标签RomM 扫描时会解析它们来区分区域和修订版多光盘文件夹里混入的data.xml等无关文件不会干扰识别。平台文件夹别名文件夹名对不上时怎么办平台目录名必须能被映射到 RomM 内置的平台列表400 平台。如果你的文件夹叫ps1而平台名是psx不要改文件夹用配置文件做别名映射即可。把 examples/config.example.yml 复制到部署目录的config/config.yml并增加挂载- ./config:/romm/config然后system: platforms: ps1: psx super_nintendo: snes重启容器生效。Batocera、RetroArch 的 ROM 目录结构则无需额外配置RomM 已内置识别。BIOS 文件放哪里BIOS 统一放在library/bios/{平台}/下如bios/ps1/scph1001.bin扫描后 RomM 会自动识别为固件并展示验证状态。这一步先放着第四章讲浏览器游玩时会用到。首次登录、创建账号与第一次游戏库扫描首启设置向导与管理员账号由于系统里还没有任何管理员首次访问http://localhost:8080会直接进入设置向导。 按提示创建管理员账号用户名 密码这是整个流程中唯一一次必须人工介入的环节——向导出现的判定逻辑就在 backend/endpoints/heartbeat.py没有管理员且未禁用向导时才会显示。触发扫描并观察实时进度登录后进入平台列表页对目标平台或全部平台触发扫描。扫描是后台任务通过 WebSocket 实时推送进度你在任务管理器里能看到当前处理到哪个文件、剩余多少——大库扫描耗时较长耐心等它跑完即可。验证扫描结果的三个检查点扫描完成后按下面三点逐项确认全部通过才算成功封面平台页出现游戏封面墙而不是统一的占位图详情点开任意游戏能看到描述文本、发行年份、类型标签解析多光盘游戏被合并为一个条目(USA)等区域标签出现在详情页如果第 1、2 项失败见名知游戏却无封面多半是元数据源密钥没配置跳到 5.2 节处理。浏览器内游玩配置EmulatorJS、BIOS 与存档同步让游戏在浏览器里直接可玩RomM 内置 EmulatorJS无需任何额外安装。对 EmulatorJS 支持该平台核心的游戏详情页会出现 Play 按钮点击即在浏览器里加载游戏。前提确认两件事ROM 文件本身合法可运行该平台所需 BIOS 已按 2.3 节放置缺 BIOS 的游戏能打开页面但启动即报错。⚠️ 想关闭某个浏览器端能力如 EmulatorJS、Flash 播放在.env里设DISABLE_EMULATOR_JStrue等变量即可全部可选项见 env.template 的 Emulation 段。存档与金手指的跨设备同步在浏览器里按保存并退出后存档文件会自动上传到/romm/assets目录已挂载到宿主机所以重启容器不会丢。下次在任意设备打开同一游戏时RomM 会拉取最新存档并处理冲突。 验证方法玩几分钟、存档退出再到宿主机assets/目录下能看到新产生的存档文件即同步链路正常。增强配置定时重扫、文件监控与元数据源打开文件监控与定时重扫想让库目录有变化就自动重扫或者每天凌晨扫一次只需在.env加两行# 文件系统变化 5 分钟后自动重扫 ENABLE_RESCAN_ON_FILESYSTEM_CHANGEtrue RESCAN_ON_FILESYSTEM_CHANGE_DELAY5 # 每天凌晨 3 点定时全库重扫 ENABLE_SCHEDULED_RESCANtrue SCHEDULED_RESCAN_CRON0 3 * * *所有定时任务含清理孤儿资源、图片转 WebP 等的开关与 cron 表达式都集中在 env.template 的 Scans Tasks 段按需开启即可。元数据源密钥与优先级RomM 默认走 IGDB免费密钥即可想要更好的封面和截图可在后台配置页补上 Screenscraper、SteamGridDB、RetroAchievements 等密钥对应.env里的SCREENSCRAPER_USER、STEAMGRIDDB_API_KEY等字段到各自官网注册免费开发者账号后填入。多个源的字段冲突时按优先级取用默认顺序为 IGDB MobyGames Screenscraper ……想调整时在config.yml的scan.priority.metadata和scan.priority.artwork里重排列表。调整扫描并发大库扫描慢时把SCAN_WORKERS4调高如 8可并行处理更多 ROM反之下限硬件如树莓派可以调低并在config.yml的filesystem.skip_hash_calculation中跳过哈希计算。改完docker compose restart romm生效。常见问题与自检容器起不来或数据库反复重连先跑docker compose ps看哪个服务不健康再docker compose logs -f romm-db查数据库日志。90% 的情况是.env与 compose 里的账号密码不一致1.2 节强调过或mysql_data卷里残留旧库导致新密码不生效——确认无需保留数据时重建卷再启动即可。判定成功两个容器均Up (healthy)romm 日志出现监听 8080 的记录。平台识别不到、封面缺失平台没识别核对文件夹名能否映射到内置平台不能就按 2.2 节加别名扫描后平台页出现灰色未匹配平台即为识别成功待处理状态封面缺失确认元数据源密钥有效个别游戏无封面属正常不代表故障备份与安全三样东西必须备份✅ 需要定期备份的只有三处mysql_data卷数据库核心、assets/你的存档与上传内容、config/config.yml。数据库备份一条命令docker exec romm-db mysqldump -u romm-user -p romm romm-backup.sql。安全侧再提醒两点上线公网务必套 HTTPS 反向代理并开启ROMM_SESSION_SECURE_COOKIEtrue默认管理员密码立即改掉。到这里你的 RomM 已经能扫描、浏览、在浏览器里玩、跨设备同步存档了。接下来三件事可以让它真正长在你工作流里今晚给最常用的 2~3 个平台触发一次扫描抽查 5 个游戏的封面和区域标签是否正确本周在assets/之外再给mysql_data卷建一个定时备份任务跑通导出→恢复一次再放心本月把 Screenscraper 密钥配上重扫一次封面墙和纯 IGDB 的效果对比一下再决定是否调整元数据优先级ROM 只是文件库才是收藏——现在它终于有了一个像样的展厅剩下的时间就该留给游戏本身了。【免费下载链接】rommA beautiful, powerful, self-hosted ROM manager and player.项目地址: https://gitcode.com/GitHub_Trending/rom/romm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 RomM 自托管 ROM 管理教程：Docker 部署、多平台游戏库扫描与浏览器内游玩
RomM 自托管 ROM 管理教程Docker 部署、多平台游戏库扫描与浏览器内游玩【免费下载链接】rommA beautiful, powerful, self-hosted ROM manager and player.项目地址: https://gitcode.com/GitHub_Trending/rom/romm你的 Game Boy、Snes、PS1 游戏 ROM 散落在不同的硬盘里命名五花八门想找某个游戏封面还得手动搜图——这种情况靠再买一块硬盘或再写一遍文件夹整理脚本都解决不了需要的是一个专门的自托管系统。RomM 就是这样一款 ROM 管理器兼播放器一个 Docker 镜像把扫描、元数据、浏览和浏览器内游玩全部打包给你。读完本文你能解决这些问题✅ 15 分钟内用 Docker 跑起完整的 RomM 服务含数据库✅ 按正确规则组织多平台游戏库目录让 RomM 自动识别 400 平台✅ 完成首次扫描并逐项验证封面、描述、标签是否解析到位✅ 配置浏览器内游玩EmulatorJS与跨设备存档同步✅ 掌握定时重扫、文件监控等增强项和常见故障的自检方法RomM 的 Docker 部署步骤先让服务跑起来前置条件与准备清单开始前确认三件事系统已安装 Docker 和 Docker Compose你有一块存 ROM 的目录本教程假设为./library你能生成一串会话密钥。✅ 密钥只需生成一次之后所有登录的会话都靠它加密生成命令是openssl rand -hex 32。创建 .env 文件必填字段只有 5 个在部署目录如romm-setup下创建.env完整变量清单见 env.template每个变量都有中文注释这里只给最小可运行版本# 应用会话密钥必填openssl rand -hex 32 生成 ROMM_AUTH_SECRET_KEY这里粘贴64位十六进制字符串 # 数据库配置必须与下方 mariadb 容器保持一致 DB_HOSTromm-db DB_NAMEromm DB_USERromm-user DB_PASSWD你的数据库密码 DB_ROOT_PASSWD数据库root密码⚠️ 注意DB_NAME、DB_USER、DB_PASSWD必须与 compose 文件里 MariaDB 的MARIADB_DATABASE、MARIADB_USER、MARIADB_PASSWORD完全对应这是新手部署失败的第一大原因。编写 docker-compose.yml 并验证容器健康参考官方模板 examples/docker-compose.example.yml最小版本如下services: romm: image: rommapp/romm:latest container_name: romm restart: unless-stopped env_file: .env environment: - DB_HOSTromm-db - DB_NAMEromm - DB_USERromm-user - DB_PASSWD${DB_PASSWD} volumes: - ./resources:/romm/resources # RomM 下载的封面、截图等资源 - ./library:/romm/library # 你的游戏库核心目录 - ./assets:/romm/assets # 存档、金手指、截图等上传内容 - redis_data:/redis-data # 后台任务缓存 ports: - 8080:8080 # 对外访问端口 depends_on: romm-db: condition: service_healthy # 等数据库健康检查通过再启动 romm-db: image: mariadb:latest container_name: romm-db restart: unless-stopped environment: - MARIADB_ROOT_PASSWORD${DB_ROOT_PASSWD} - MARIADB_DATABASEromm - MARIADB_USERromm-user - MARIADB_PASSWORD${DB_PASSWD} volumes: - mysql_data:/var/lib/mysql healthcheck: test: [CMD, healthcheck.sh, --connect, --innodb_initialized] start_period: 30s interval: 10s retries: 5 volumes: mysql_data: redis_data:执行启动并验证docker compose up -d # 后台启动全部服务 docker compose ps # 判断成功romm 与 romm-db 均显示 Up (healthy) docker compose logs -f romm # 观察日志确认出现数据库连接成功、服务监听 8080 的记录 最终判定标准浏览器访问http://localhost:8080能看到登录页首次会自动进入初始化向导说明 Web 层、数据库、缓存三者已打通。游戏库目录结构配置让 RomM 自动识别平台单文件与多光盘的两级规则RomM 靠文件夹层级判断平台、靠子文件夹判断多文件游戏。核心规则只有两条文件直接放在平台目录下 单文件游戏平台目录下的每个子文件夹 一个游戏。典型结构library/ ├── roms/ │ ├── snes/ │ │ ├── Super Mario World.sfc # 单文件游戏 │ │ └── Final Fantasy VI/ # 多光盘一个文件夹一个游戏 │ │ ├── disc1.smc │ │ └── disc2.smc │ └── ps1/ │ └── Final Fantasy VII/ │ ├── disc1.iso │ ├── disc2.iso │ └── disc3.iso └── bios/ └── ps1/ └── scph1001.bin # BIOS 按平台目录存放⚠️ 文件名建议保留(USA)、(J)、(Rev 1)这类标签RomM 扫描时会解析它们来区分区域和修订版多光盘文件夹里混入的data.xml等无关文件不会干扰识别。平台文件夹别名文件夹名对不上时怎么办平台目录名必须能被映射到 RomM 内置的平台列表400 平台。如果你的文件夹叫ps1而平台名是psx不要改文件夹用配置文件做别名映射即可。把 examples/config.example.yml 复制到部署目录的config/config.yml并增加挂载- ./config:/romm/config然后system: platforms: ps1: psx super_nintendo: snes重启容器生效。Batocera、RetroArch 的 ROM 目录结构则无需额外配置RomM 已内置识别。BIOS 文件放哪里BIOS 统一放在library/bios/{平台}/下如bios/ps1/scph1001.bin扫描后 RomM 会自动识别为固件并展示验证状态。这一步先放着第四章讲浏览器游玩时会用到。首次登录、创建账号与第一次游戏库扫描首启设置向导与管理员账号由于系统里还没有任何管理员首次访问http://localhost:8080会直接进入设置向导。 按提示创建管理员账号用户名 密码这是整个流程中唯一一次必须人工介入的环节——向导出现的判定逻辑就在 backend/endpoints/heartbeat.py没有管理员且未禁用向导时才会显示。触发扫描并观察实时进度登录后进入平台列表页对目标平台或全部平台触发扫描。扫描是后台任务通过 WebSocket 实时推送进度你在任务管理器里能看到当前处理到哪个文件、剩余多少——大库扫描耗时较长耐心等它跑完即可。验证扫描结果的三个检查点扫描完成后按下面三点逐项确认全部通过才算成功封面平台页出现游戏封面墙而不是统一的占位图详情点开任意游戏能看到描述文本、发行年份、类型标签解析多光盘游戏被合并为一个条目(USA)等区域标签出现在详情页如果第 1、2 项失败见名知游戏却无封面多半是元数据源密钥没配置跳到 5.2 节处理。浏览器内游玩配置EmulatorJS、BIOS 与存档同步让游戏在浏览器里直接可玩RomM 内置 EmulatorJS无需任何额外安装。对 EmulatorJS 支持该平台核心的游戏详情页会出现 Play 按钮点击即在浏览器里加载游戏。前提确认两件事ROM 文件本身合法可运行该平台所需 BIOS 已按 2.3 节放置缺 BIOS 的游戏能打开页面但启动即报错。⚠️ 想关闭某个浏览器端能力如 EmulatorJS、Flash 播放在.env里设DISABLE_EMULATOR_JStrue等变量即可全部可选项见 env.template 的 Emulation 段。存档与金手指的跨设备同步在浏览器里按保存并退出后存档文件会自动上传到/romm/assets目录已挂载到宿主机所以重启容器不会丢。下次在任意设备打开同一游戏时RomM 会拉取最新存档并处理冲突。 验证方法玩几分钟、存档退出再到宿主机assets/目录下能看到新产生的存档文件即同步链路正常。增强配置定时重扫、文件监控与元数据源打开文件监控与定时重扫想让库目录有变化就自动重扫或者每天凌晨扫一次只需在.env加两行# 文件系统变化 5 分钟后自动重扫 ENABLE_RESCAN_ON_FILESYSTEM_CHANGEtrue RESCAN_ON_FILESYSTEM_CHANGE_DELAY5 # 每天凌晨 3 点定时全库重扫 ENABLE_SCHEDULED_RESCANtrue SCHEDULED_RESCAN_CRON0 3 * * *所有定时任务含清理孤儿资源、图片转 WebP 等的开关与 cron 表达式都集中在 env.template 的 Scans Tasks 段按需开启即可。元数据源密钥与优先级RomM 默认走 IGDB免费密钥即可想要更好的封面和截图可在后台配置页补上 Screenscraper、SteamGridDB、RetroAchievements 等密钥对应.env里的SCREENSCRAPER_USER、STEAMGRIDDB_API_KEY等字段到各自官网注册免费开发者账号后填入。多个源的字段冲突时按优先级取用默认顺序为 IGDB MobyGames Screenscraper ……想调整时在config.yml的scan.priority.metadata和scan.priority.artwork里重排列表。调整扫描并发大库扫描慢时把SCAN_WORKERS4调高如 8可并行处理更多 ROM反之下限硬件如树莓派可以调低并在config.yml的filesystem.skip_hash_calculation中跳过哈希计算。改完docker compose restart romm生效。常见问题与自检容器起不来或数据库反复重连先跑docker compose ps看哪个服务不健康再docker compose logs -f romm-db查数据库日志。90% 的情况是.env与 compose 里的账号密码不一致1.2 节强调过或mysql_data卷里残留旧库导致新密码不生效——确认无需保留数据时重建卷再启动即可。判定成功两个容器均Up (healthy)romm 日志出现监听 8080 的记录。平台识别不到、封面缺失平台没识别核对文件夹名能否映射到内置平台不能就按 2.2 节加别名扫描后平台页出现灰色未匹配平台即为识别成功待处理状态封面缺失确认元数据源密钥有效个别游戏无封面属正常不代表故障备份与安全三样东西必须备份✅ 需要定期备份的只有三处mysql_data卷数据库核心、assets/你的存档与上传内容、config/config.yml。数据库备份一条命令docker exec romm-db mysqldump -u romm-user -p romm romm-backup.sql。安全侧再提醒两点上线公网务必套 HTTPS 反向代理并开启ROMM_SESSION_SECURE_COOKIEtrue默认管理员密码立即改掉。到这里你的 RomM 已经能扫描、浏览、在浏览器里玩、跨设备同步存档了。接下来三件事可以让它真正长在你工作流里今晚给最常用的 2~3 个平台触发一次扫描抽查 5 个游戏的封面和区域标签是否正确本周在assets/之外再给mysql_data卷建一个定时备份任务跑通导出→恢复一次再放心本月把 Screenscraper 密钥配上重扫一次封面墙和纯 IGDB 的效果对比一下再决定是否调整元数据优先级ROM 只是文件库才是收藏——现在它终于有了一个像样的展厅剩下的时间就该留给游戏本身了。【免费下载链接】rommA beautiful, powerful, self-hosted ROM manager and player.项目地址: https://gitcode.com/GitHub_Trending/rom/romm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考