安装前准备
Mediora 使用 Docker 运行。安装前先备齐必备项目，再根据需要使用的功能补充可选项目。
必备项目
| 准备内容 | 说明 |
|---|---|
| Docker 运行环境 | 安装在电脑、服务器或 NAS 上，用于启动和运行 Mediora |
| Mediora 数据目录 | 长期保存登录状态、设置和任务记录 |
| 安装机器的局域网地址 | 让家里的电脑、电视或手机访问 Mediora 页面 |
只安装和打开 Mediora 页面，不需要先安装媒体服务器或填写 TMDB。数据目录应放在长期保留的位置，不要使用会被自动清理的临时目录。
可选项目
以下项目按使用需求准备，无需全部配置。
只管理文件时，先准备一个可访问的媒体来源；需要识别、整理或刮削时再配置 TMDB，需要播放时再接入媒体服务器。
| 准备内容 | 说明 |
|---|---|
| 绿联NAS网络文件夹挂载 | 绿联 NAS 用户的推荐方式。 先在绿联云客户端的“文件管理 → ＋ → 连接网络文件夹”完成授权，再为 Mediora 配置发现目录和挂载传播，见下方场景四与挂载指南 |
| CloudDrive2 服务地址、访问令牌 | 用 CD2 聚合多个网盘时使用；先在 CD2 中完成挂载和令牌，见CD2 配置指南 |
| OpenList 访问地址、登录令牌 | 通过 OpenList 接入存储时使用 |
| 115 网盘账号 | 不推荐作为主力。 可能遇到账号验证、限频或接口变化，Mediora 会限制请求频率，后续也不保证长期支持；仅作临时补充时按需准备，见云盘管理 |
| STRM 输出目录 | 使用 STRM 播放时，需要让 Emby 或 Jellyfin 读取此目录 |
| TMDB 访问配置 | 使用媒体识别、整理和刮削时准备，用于查询片名、简介和海报等资料 |
| Emby 或 Jellyfin 访问地址、API 密钥 | 需要媒体库播放、媒体代理或影音优化时准备，见首次设置；只管理文件时可以暂不配置 |
| 通知渠道账号与配置 | 启用消息通知时，按页面提示准备对应渠道的账号和连接配置 |
| 外网访问 代理地址与端口 | 仅在 TMDB、网盘等服务访问受限时配置外网代理；浏览器能访问不代表容器也可以，应在 Mediora 页面完成连接测试 |
运行平台限制
当前发布流程提供 linux/amd64（x86_64）与 linux/arm64（ARM64）镜像，Docker 按安装机器架构选择对应变体。使用历史版本或自行构建的镜像时，应另行核对实际架构。
数据目录应放在支持正常文件锁和 SQLite 写入的可靠磁盘上，不要放进网盘网络文件夹。为数据库快照、升级副本、下载暂存和日志保留空间；来源媒体在远端并不意味着本机不需要可用空间。
推荐的目录安排
以下路径都只是示例，请按自己的磁盘、共享文件夹和权限调整。 本节用 /mnt/volume1/docker/mediora 保存 Mediora 的配置、数据及下载文件，用 /mnt/volume1/medias 表示媒体库；无需为了照抄示例而搬动已有媒体。
表格左侧是宿主机（电脑、服务器或 NAS）的实际目录，右侧是挂载后 Mediora 能看到的容器内路径。在 Mediora 页面选择目录时，使用右侧路径。
使用 Compose 时，可将配置文件保存为 /mnt/volume1/docker/mediora/compose.yaml；命令和手动界面方式无需创建这个文件。下面四种场景可以按需组合，数据目录只需挂载一次。
场景一：媒体库和其他本地目录
已有本地媒体库，同时需要读取其他本地目录时，可以这样安排：
| 宿主机目录（示例） | 容器内路径 | 用途 |
|---|---|---|
/mnt/volume1/medias | /medias | 已有媒体库，或整理、刮削后的保存位置 |
/mnt/volume1/docker/mediora/imports | /imports | 其他待处理文件，例如准备整理入库的影片 |
在“云盘管理”添加本地存储时，选择 /medias 或 /imports。已有目录可直接挂载，无需先复制到 Mediora 的数据目录。只供读取的目录可以只读挂载；需要移动、刮削或写入的目录应允许对应操作。
场景二：使用网盘中的媒体
通过网盘账号、OpenList 或 CD2 接入媒体时，网盘中的来源目录由存储连接访问，不需要先下载到本地或额外创建一个“网盘目录”。
| 宿主机目录（示例） | 容器内路径 | 用途 |
|---|---|---|
/mnt/volume1/medias | /medias | 按需保存本地 STRM 或其他输出 |
安装后在云盘管理添加对应存储，再选择网盘内的媒体目录。需要将 STRM 输出到本地时，可使用 /medias/strm，并让 Emby 或 Jellyfin 能读取同一份输出；不需要本地输出时，可以不挂载 /medias。
来源选择提醒： 优先考虑已有的本地存储、OpenList 或 CD2；绿联NAS用户可使用下方场景四。115 直连不推荐作为主力。更换接入方式仍需遵守网盘规则，不能据此保证免于账号验证或限频。
场景三：使用本地下载目录
使用 qBittorrent 或 Transmission 下载，再交给 Mediora 处理时，将下载目录和媒体库分开：
| 宿主机目录（示例） | 容器内路径 | 用途 |
|---|---|---|
/mnt/volume1/docker/mediora/downloads | /downloads | 本地下载器保存文件的位置 |
/mnt/volume1/medias | /medias | 下载完成后整理、刮削的目标媒体库 |
Mediora 和下载器必须看到相同的下载路径。 下载器也运行在容器中时，将同一个 /mnt/volume1/docker/mediora/downloads 同样挂载为 /downloads。例如下载器报告文件保存在 /downloads/complete，Mediora 也应能从这个路径读取。
安装后先将 /downloads 添加为本地存储，再按下载助手配置下载目录；需要下载后自动处理时，再配置工作流。
场景四：绿联NAS网络文件夹挂载
使用绿联NAS网络文件夹挂载访问媒体时，Mediora 需要读取相应的发现目录：
| NAS 目录 | 容器内路径 | 用途 |
|---|---|---|
/mnt/@remote | /ugreen | 绿联NAS网络文件夹挂载的发现目录；映射整个目录，并启用 rslave 挂载传播 |
/mnt/volume1/medias（示例） | /medias | 按需保存本地 STRM 或其他输出，无本地输出时可不挂载 |
先在绿联NAS的“文件管理 → ＋ → 连接网络文件夹”完成授权与挂载，确认 NAS 能打开目标目录，再按安装指南同时启用绿联NAS网络文件夹挂载的目录映射和 UGREEN_REMOTE_ROOT=/ugreen。/mnt/@remote 由 NAS 的真实挂载提供，不要手动创建空目录来替代。
安装后添加绿联NAS网络文件夹挂载存储，选择发现的挂载与业务目录。挂载步骤、读写权限和重连检查见绿联NAS网络文件夹挂载。
准备好后，继续阅读安装 Mediora。
容易搞错的地方
| 容易搞错 | 实际情况 |
|---|---|
| 认为影片在远端，本机就不需要空间 | 数据库、备份、临时转存和影音优化都可能占用本机资源，要为实际任务留出空间。 |
| 把 Docker Desktop 当作 NAS 挂载验收 | 路径、权限和挂载传播不同；绿联NAS网络文件夹挂载要在真实 NAS 上验证。 |
忽略 PUID / PGID | 它们决定应用以谁的身份读写文件，数据目录和媒体目录都要核对权限。 |
没有确认 /app/data 的宿主机位置 | 删除或重建容器后，未持久保存的数据可能无法继续使用；安装后先确认该挂载。 |
| 认为有 ARM 镜像就等于所有设备性能相同 | 架构匹配只是运行前提；并发、媒体探测和转码仍受设备资源限制，转码主要由媒体服务器承担。 |
最佳实践
以“下载到 NAS，再整理进媒体库”为例，可以这样分开目录：
| 用途 | 示例容器路径 | 什么时候写入 |
|---|---|---|
| 应用数据 | /app/data | 登录、保存配置、运行任务和备份时 |
| 下载暂存 | /downloads | 下载器接收文件时 |
| 正式媒体库 | /medias | 整理和刮削确认结果后 |
目录分开后，下载器不会直接把未完成文件写进正式媒体库，备份时也容易分清应用数据和影片。它们可以位于同一设备，不必为了照抄示例重新购买硬盘。
空间按操作估算。例如复制一部 20 GB 的影片时，目标至少要容纳这一份影片，还需给备份、暂存及其他任务留余量；不能只凭“还有 10% 空间”判断一定够用。第一次先处理少量文件，观察容器的内存和磁盘占用，再扩大并发。
新机器接入顺序： 先确认 Docker 可用 → 再挂载目录 → 再装 Mediora → 最后在页面里添加存储。顺序反了就会出现“容器起来了但完全看不到文件”。