装好应用，
管理自己的游戏库。

WINDOWS · MACOS · LINUX

01 普通电脑安装

1. 安装并启动 Docker

   Windows 或 macOS 安装 Docker Desktop，安装后打开应用，等待引擎启动。Mac 请按自己的 Apple 芯片或 Intel 芯片选择版本；Windows 按官方安装器要求启用 WSL 2 等组件。Linux 可安装 Docker Engine 与 Compose 插件。

   Docker 官方安装说明 ↗ · Windows ↗ · macOS ↗

   打开终端，Windows 可用 PowerShell，检查下面两条命令。第二条能显示服务端信息，才说明引擎已运行。

   docker compose version
   docker info

2. 下载并解压服务器 ZIP

   前往服务器端下载页，选择「普通电脑 · Docker Compose」。把 ZIP 完整解压到准备长期保留的文件夹，确认其中有 compose.yaml、Dockerfile、app 和 README.md，不要在压缩包内直接操作。

3. 创建资料库文件夹

   在 compose.yaml 同级创建名为 library 的文件夹。它将保存游戏包、BIOS 和封面。已有目录也可以使用：复制 .env.example 为 .env，把 FC_LIBRARY_HOST_PATH 改成该目录的绝对路径。Windows 使用类似 D:/Games/FCEmulatorLibrary 的路径。

   文件必须叫 .env，不要保存成 .env.txt。Docker Desktop 若询问是否允许访问此文件夹，请允许共享该目录。

4. 启动并打开管理页面

   Windows：在解压后的文件夹空白处右键，选择「在终端中打开」（也可使用 PowerShell）。Mac：打开「终端」，输入 cd 加一个空格，把解压后的文件夹拖进终端，再按回车。Linux：在文件管理器中选择「在终端打开」。确认当前目录中能找到 compose.yaml，然后运行：

   docker compose up -d --build
   docker compose ps

   首次构建需要联网获取基础镜像。看到 server 正在运行后，在同一台电脑浏览器打开 http://127.0.0.1:8282/，继续下方的目录配置。当前默认只允许本机访问，电视连接前还需要完成局域网设置。

SYNOLOGY DSM 7

02 群晖安装

1. 准备 Node.js 与公开 SPK

   在 DSM「套件中心」安装适用于本机的 Node.js 18 或更高版本；启动脚本支持查找 Node.js 18、20、22 套件。随后前往服务器端下载页下载群晖 SPK。公开包不附带 Node 运行时，标记为 noarch；仍需要 NAS 上可运行的 Node.js。

2. 手动安装套件

   在「套件中心 → 手动安装」选择下载的 SPK，核对套件名称 Retro Console Library 后按向导完成安装。正式版管理端口为 8282。

3. 创建资料库并授予权限

   通过 DSM「控制面板 → 共享文件夹」准备一个专门存放游戏资料库的共享文件夹，例如 FCEmulatorLibrary。进入该共享文件夹的「编辑 → 权限」，把用户类型切换为系统内部用户，给 FCEmulatorLibrary 账号勾选读取/写入并应用。

   这是套件账号，不是你登录 DSM 使用的管理员账号。若只授权共享文件夹中的某个子目录，还要让套件账号能够穿过上级目录；只给最深处的文件夹读写权限可能仍会报「拒绝访问」。优先使用独立共享文件夹，避免向无关目录授予权限。

4. 启动并打开管理页面

   在套件中心启动服务，点击「打开」，或在浏览器输入 http://你的群晖局域网IP:8282/。不要使用 DSM 的 5000 / 5001 端口代替服务器端口。若 DSM 开启了防火墙，允许受信任局域网访问 TCP 8282。

   进入网页「设置」后选择资料库的真实路径：可能是 /volume1/FCEmulatorLibrary，也可能是 /volume2/FCEmulatorLibrary，以 NAS 实际存储卷为准。不要把 Mac 上的 /Volumes/… 路径直接填到群晖中。

MAC APP · LOCAL OR SYNOLOGY

03 Mac 应用：自己管理游戏，也能连接群晖

只在 Mac 上玩，安装 Mac 应用就够了，无需群晖或 Docker。你可以直接管理自己的本地 ROM 资料库；已有群晖资料库时，也可以把 Mac 当作客户端连接它。下面先介绍本地用法，再介绍如何切换到群晖。

1. 安装 Mac 应用

   前往客户端下载区下载 macOS DMG。当前版本适用于 Apple 芯片 Mac，要求 macOS 14 Sonoma 或更高版本。打开 DMG，把应用拖到「应用程序」，再从「应用程序」打开。仅本地使用时，不必执行下面的 Docker 安装步骤。

2. 选择自己的 ROM 目录

   打开应用的「设置 → NAS / 远程资料库」，用服务器地址与本地目录之间的开关切到本地模式，再点击「选择目录…」。第一次使用可选一个新的空文件夹，例如自己创建的「Retro Console 游戏库」；应用会把空目录准备为可移植资料库。已有 ROM 文件夹也可以直接选择，文件按原位置读取；在访达里增删文件后，回到这里点击「刷新」。

   你选择的是公共 ROM 目录，不是 App 的私有索引位置。索引、缓存和游戏存档由 App 自己管理，无需另选路径。使用上述空目录建立的可移植资料库时，导入的游戏会整理并写入该目录；明确设置或补全封面时，封面也会按公共资料库格式写回。备份时请保留自己的 ROM 资料库；该目录并不等于 App 的全部设置与存档。

3. 在「ROM 管理」中导入和整理

   切到本地模式后，在游戏页打开「ROM 管理」，选择「导入 → ROM 文件…」，选中自己合法拥有或获得授权的 ROM。ZIP / 7z 中只放一个卡带文件时，可由导入器识别；已经整理好的通用游戏包用「游戏包 (.zip / 目录)…」，含根 library.json 的完整资料库用「整个资料库目录…」。不要把普通多游戏 ZIP 当作一个游戏包。

   导入后检查游戏列表和具体错误。可以搜索、收藏，点击「编辑」修改名称、分类和封面，或使用「补全缺失封面」搜索公开封面来源。游戏名称和你自己的文件名会保留；切换界面语言不会翻译或改写原始游戏资料。下方ROM 类型说明解释常见后缀和容器；其中格式表是服务器入口的清单，不能视作 Mac 对每款游戏的兼容保证。

4. 按游戏需要补 BIOS，再启动验证

   在「ROM 管理 → 导入」菜单选择对应的 BIOS 或固件入口，例如 FDS BIOS、PlayStation BIOS。只使用自己有权使用的文件，按BIOS 与固件说明准备正确的机型和地区；普通 NES 卡带不需要 FDS BIOS。不要把 BIOS 当作游戏卡带，也不要仅靠改名让文件通过校验。

   返回游戏页实际启动游戏。导入成功说明文件已加入资料库；能否正常进入游戏，还取决于 BIOS、卡带硬件以及当前内核的兼容性。

已经有群晖？Mac 也可以直接连接

1. 取得群晖资料库地址

   按群晖安装和资料库配置准备好 NAS，在管理网页复制「资料库地址」，形如 http://群晖的局域网IP:8282/library/。Mac 与群晖应在可互通的同一局域网。地址要带 /library/，不是 DSM 的登录地址。

2. 切到服务器模式并添加来源

   回到 Mac「设置 → NAS / 远程资料库」，把中间开关切回服务器模式，填写「服务器地址」。服务器设有访问令牌时，选择「Bearer Token」并填写同一 Token；先点「测试连接」，再点「添加资料库」。连接过程与其他客户端相同，不需要在 Mac 另装 Docker。

   本地目录和服务器是两种来源模式：使用本地目录时，服务器同步会暂停；切回服务器后再继续同步。切换模式不会把两边自动合并。已有来源可在「管理来源」中查看和同步。

FIRST SETUP

04 设置目录，上传游戏

1.3.4 起，管理页面右上角可选择「中文 / English」。首次打开会按浏览器语言显示，之后记住你的选择。切换会刷新当前页面；请先完成上传或保存，并关闭打开的弹窗。

1. 选择服务器能看见的目录

   打开管理网页右上角「设置」，在「资料库目录（服务器绝对路径）」中填写或浏览选择目录。Docker 填 /library，这是容器内的路径；电脑上的真实目录由 .env 的 FC_LIBRARY_HOST_PATH 决定。群晖填上一步确认的 /volume…/共享文件夹 路径。

   设置「资料库名称」，保存并等待页面刷新。首次使用建议先选择一个空目录。已有可移植资料库请选择包含根 library.json 的目录；目录里的旧文件请先备份。

2. 设置管理 Token

   仍在「设置」中，为「管理 Token」填写自己生成的至少 16 个字符的访问令牌，然后保存。保存后，上传、删除和修改设置等管理操作需要该 Token；换浏览器访问时，按页面提示输入同一 Token。它不是 DSM 密码，也不是 DeepSeek API Key。

   不使用联网资料补全时，无需填写 DeepSeek API Key。公开包没有预置任何人的密钥或账号。

3. 上传一款自己的 ROM

   回到「游戏」页，点击「上传 ROM」选择文件，或拖入上传区域。ZIP / 7z 会按内部内容识别系统，不能仅凭文件名认定主机。街机驱动包应保留原名；需要声明的 Atari 卡带会弹出制式、板卡或控制器选择，按真实卡带填写。

   上传结束后查看结果和游戏列表。出现「已加入」或「已存在」代表入库或去重成功；若还有启动依赖提示，请继续处理BIOS 与固件，不要把上传成功等同于已经验证游戏能运行。

BIOS & FIRMWARE

05 补齐启动所需文件

公开安装包不含 ROM 或主机 BIOS。打开管理网页「BIOS 与固件」，按对应卡片选择自己拥有的文件；页面会校验内容身份，错误文件会显示原因，不会覆盖原来已经验证的合法文件。

ROM 上传后若缺少依赖，页面会保留「ROM 已入库」的启动依赖提示，后续其他文件上传成功不会把它盖掉。点击「前往 BIOS 与固件」补齐文件，再重新上传该 ROM 确认；原有提示是上传当时的记录，可以手动关闭。CPS2 游戏还需匹配的 .key，可随自己的 ROM ZIP 提供。

LOCAL NETWORK

06 允许局域网设备访问

先完成管理 Token 设置，再开放给电视或其他设备。让服务器与客户端处在同一个可互通的局域网；访客 Wi-Fi 或路由器的设备隔离可能阻止连接。

1. Docker：绑定电脑的局域网地址

   在系统网络设置里查看电脑的局域网 IPv4 地址。编辑解压目录中的 .env，把 FC_LIBRARY_BIND_IP=127.0.0.1 的地址部分换成这台电脑的实际局域网地址，端口保留 FC_LIBRARY_PORT=8282。随后在同一目录运行：

   docker compose up -d

   如果改用现有资料库，FC_LIBRARY_HOST_PATH 仍指向原来的宿主机目录。不要删掉该配置。绑定局域网地址后，请在浏览器改用 http://电脑的局域网IP:8282/；只绑定该地址时，原来的 127.0.0.1 地址可能不再可用。

2. 群晖：确认端口与防火墙

   原生 SPK 启动后使用 NAS 的 8282 端口，通常无需 Docker 的绑定设置。若有 DSM 防火墙规则，仅对受信任局域网放行 TCP 8282。不要向互联网做端口转发。

3. 先用另一台设备验证

   在同一网络另一台电脑或手机浏览器输入服务器的局域网地址与 8282 端口。能打开管理页面后，再配置客户端。客户端里的 127.0.0.1 指它自己，不能用来连接另一台电脑或 NAS。

ANDROID TV · APPLE TV · MACOS

07 连接客户端资料库

1. 取得资料库根地址

   通过服务器局域网地址打开管理网页，点击右上角「资料库地址」。客户端使用的地址形如 http://服务器的局域网IP:8282/library/。这与浏览器管理页的根地址不同，末尾要保留 /library/，无需手工追加 library.json。

2. 在客户端填写地址与认证

   在 Android TV、Apple TV 或 macOS 客户端打开「设置 → NAS / 远程资料库」，填写「服务器地址」。服务器启用了 Token 时，认证方式选择「Bearer Token」，填入与管理网页相同的访问令牌。不要把 DSM 用户名密码填成 Token。

   macOS 若提示正在使用本地 ROM 目录、服务器同步已暂停，先切回远程资料库模式再继续。

3. 测试并添加资料库

   先使用「测试连接」检查地址和认证，再使用「添加资料库」完成同步。已添加的来源可在「资料库来源」中测试或同步。完成后回到游戏页，检查游戏能否下载，再实际启动一局；个别内核的兼容性与 BIOS 是否齐全仍需以实际游戏表现为准。

HELP · ROM FORMATS

08 服务器支持哪些 ROM？

ROM 是你导出的游戏文件；ZIP / 7z 是把文件装在一起的压缩容器。下面列的是 1.3.4 服务器上传入口实际接受的类型，不等同于每款游戏都能运行，也不把客户端单独支持的格式算进来。先在「设置」中选好资料库目录，再上传。

卡带与磁碟游戏

下表的「单文件 ZIP / 7z」指压缩包内只放一个对应格式的游戏文件。封面、说明文档和其他游戏请不要混在同一压缩包内；系统会按成员内容校验，不会把所有 ZIP 都当作街机。文件可在子目录内；常见系统元数据会忽略，危险路径或损坏压缩包会拒绝。

Atari 的 .bin 有额外限制：只有文件内容指纹匹配已知卡带表时，网页才会自动判定它属于哪台 Atari。未知 .bin 不能仅凭名字确定系统，且与 Mega Drive 的扩展名冲突；请使用可明确主机的正确卡带格式，按页面填写真实制式、板卡和控制器信息。选择一个猜测的板型不能让不支持的卡带变成可运行。

光盘游戏

.cue 是轨道目录，不是游戏数据本身。请把它与所引用的全部 BIN 按原相对路径装进同一个 ZIP / 7z，不要只上传 CUE，也不要把裸 BIN 当作光盘上传。同一游戏的多张盘可在一个包内，每盘一份 CUE / CHD / CCD；不要混用这几种布局，也不要把不同游戏混成一个包。.fcps1 / .fcmcd / .fcpcecd 是本项目的光盘包格式，不能靠修改扩展名生成。

街机、Neo Geo 与 PGM

使用完整驱动集 .zip / .7z，保留原始驱动文件名和内部芯片文件，服务器会核对内容。这里是一个游戏含多块芯片的集合，不适用上面的「仅一个 ROM 成员」规则。Neo Geo 需另备 neogeo.zip，PGM 需 pgm.zip；CPS2 还需匹配的 .key。

拆分子集可能缺少母集芯片或设备 ROM；缺这些文件时不能运行。部分 ZIP 子集可从已经入库的匹配母集补全；若报缺母集，请先上传正确完整母集，不能靠改名或只上传子集解决。并非任何 MAME 驱动或任意来源 ROM 集都受当前内核支持。

CPS3 使用独立「CPS3 街机」区域：上传 MAME 游戏集 ZIP（含卡带 BIOS）和对应 CloneCD 光盘 .img，服务端再安装为游戏。这个裸 IMG 入口专用于 CPS3，不是 PlayStation 的通用裸 IMG 入口。已有本项目 .fcc3 安装游戏包可由服务器导入，但必须先配置资料库目录；改名的文件不算有效安装包。

没有在本表列出的类型，请勿仅凭客户端菜单或扩展名猜测服务器能上传。例如服务器内部有 Nintendo 64 清单校验代码，并不代表本版网页已开放 .z64 / .v64 / .n64 上传入口。

TROUBLESHOOTING & UPDATE

09 常见故障与升级

docker compose build --pull
docker compose up -d