常见问题

遇到问题时，先查看对应页面的任务详情或提示信息，再按下面的方法处理。

先找到发生问题的那一段记录

能打开页面时，先看原任务的详情、运行记录或文件操作记录，记下发生时间和任务编号。系统日志用于补充查看服务运行过程，不能代替逐文件结果。

实例管理者可打开“系统 → 系统日志”：

1. 先选“最近 1 小时”或“最近 24 小时”，再按出问题的模块筛选；不确定模块时保留“全部”。
2. 先看错误和警告，再用任务编号或错误中的关键词搜索，避免只截到最后一行而漏掉前因。
3. 查旧问题时选自定义时间，按页面标明的时区填写；单次范围最长 14 天，超出时分段查询。
4. 直接查看记录中的错误说明和错误码，选中并复制相关文字，补充镜像版本和复现步骤。分享前仍检查真实路径和账号信息。

“清空显示”只清当前列表，不会删除已保存日志；可用“恢复历史”重新查看。筛选调试级别不会替系统开启调试日志。提示仅内存保存、日志过载或记录被截断时，这一份日志可能不完整，先保留当前内容，再补看 Docker 日志。若服务还未成功启动、无法进入页面，直接看下面的容器日志。

页面打不开

确认浏览器使用的是：

http://安装机器的内网IP:3000

同时确认安装机器和浏览器在同一局域网，且 Docker 正在运行。重启后仍打不开时，检查防火墙是否拦截了 3000 端口。

容器反复退出或日志提示 EACCES

Mediora 的应用进程默认以 UID/GID 1000:1000 运行，也可通过安装页的 UID/GID 环境变量指定。先查看日志：

docker compose logs --tail=100 mediora

上面是 Compose 方式；命令方式使用 docker logs --tail=100 mediora，绿联手动容器从“Docker → 容器 → mediora → 日志”查看。

如果出现 EACCES、permission denied、数据库无法创建或密钥无法写入，请检查宿主机挂载目录是否允许所选 UID/GID 按实际功能读取或写入。

在宿主机确认实际要使用的非 root UID/GID，核对容器的 PUID / PGID：Compose 在 environment 填写，命令方式通过 -e 指定，绿联手动界面在“环境变量”中设置。修改后按原安装方式应用或重建，单纯重启不会增加新参数。

已有数据目录中的数据库和密钥也必须允许新身份访问。先停止容器并备份，只对专用数据目录修正权限，不递归改共享媒体库属主。UID/GID 的查询与修改方法见安装页的权限问题说明。

不同 Linux、NAS 和网络挂载的权限设置方式不同，请沿用原有用户组或 ACL，只开放实际需要的目录。不要把容器改回 root 来绕过权限问题，也不要使用 chmod 777。

登录或验证码有问题

• 检查邮箱地址是否填写正确，并查看垃圾邮件。
• 使用登录页的重新发送按钮。
• 保持安装机器可以正常访问互联网。

注册邮件验证后会尝试自动登录；未成功时按页面提示手动登录，不必重复注册。反向代理后出现登录即退出时，检查可信代理、外部协议和 Cookie，见公网访问与安全。账户修改密码或恢复数据库后，重新登录并重新授权智能体属于预期行为。

数据库启动门禁未通过

先停止反复重启，保留完整原数据目录和日志。常见原因包括另一个实例已占用目录、身份或密钥缺失、数据库结构不匹配，或升级副本校验失败。

不要只删除数据库、复制其他安装的密钥，或改版本标记。本版只识别指定的已发布结构进行升级；未知开发库不会自动修复。按备份与恢复核对版本与成对材料，回退同时恢复旧镜像和完整目录。

本地媒体目录为空

页面里的本地目录来自 Docker 已挂载的容器路径，不一定从 /medias 开始。检查 Compose 的 volumes、命令中的 -v 或绿联“存储空间”：实际来源文件夹是否正确、容器内路径是否一致。还要确认容器对每一级父目录有读取和进入权限，修改后按原方式应用或重建。页面中应选择映射后的容器路径，不能填写宿主机原始路径。

115 或 OpenList 无法使用

• 115：重新扫码登录，再打开一次目录。
• OpenList：确认地址、令牌和账号权限正确。
• 任务正在等待或结果不清楚时，先到存储中查看实际文件，不要反复提交同一任务。

115 明确提示“账号需要验证”时，先在官方客户端完成验证，再回到存储“测试连接”；重启和删除重加不会清除阻断。限频冷却、账号验证、容量不足是不同原因，应按各自提示处理，不要一律重新扫码。

115 反复要求验证或限频时

不推荐把 115 直连作为主力存储，相关接口也不保证后续长期支持。先按提示完成官方验证或等待冷却，不要反复重试。如果长期无法满足使用需求，可以评估已有的其他接入方式；这些方式仍受网盘规则和服务状态影响，不能保证免于验证或限频：

你的情况	改用
绿联 NAS 用户	绿联NAS网络文件夹挂载，网盘由 NAS 挂载
有多个网盘	CloudDrive2，由 CD2 承接账号和挂载
主要的影片	按空间与备份计划保留本地副本，减少对远端连接的依赖

完整风险说明见云盘管理。

CloudDrive2 连不上或目录为空

先确认 CD2 服务本身在运行，再从 Mediora 容器内请求一次 CD2 地址——浏览器能打开不代表容器能连上。能连上但目录为空时，检查令牌权限和“允许访问的目录”是否覆盖目标路径。逐步排查见CD2 配置指南。

绿联NAS网络文件夹挂载没有目录或写入失败

分三层排查，不要跳着查：绿联云客户端里网络文件夹能否打开真实文件 → Docker 里 /mnt/@remote 到 /ugreen 的映射是否带 rslave → Mediora 里 能否在“网盘与账号”中发现该挂载。再检查 UGREEN_REMOTE_ROOT 和实际 UID/GID 权限。Docker Desktop 不能验证 NAS 子挂载传播；普通空目录也不能替代挂载。完整步骤见挂载指南。

文件关闭后不见了或出现 ENOTSUP，先检查容量、文件名、零字节支持和 NAS 后台上传状态。不同网络文件夹挂载的限制不同，不要把某个挂载的故障套到其他账号。完整说明见绿联NAS网络文件夹挂载。

文件传完了，为什么还在核实

浏览器或传输进度只表示字节送达，随后还需要关闭、发布和核对真实结果。远端新文件可能延迟可读，完整内容核对也会花费时间并增加读取流量。

出现“结果待核对”或“有写入结果需要核实”时，先停止原任务并等待在途操作结束，从原记录读取证据；不要反复覆盖或手动删保护记录。具体入口和“结束并保留文件”的含义见结果核对指南。

整理、刮削或 STRM 没有结果

打开任务详情，确认任务已经运行而不是只保存了设置。再检查来源目录、目标目录和文件名是否正确。需要改规则时，先暂停自动运行，改好后重新执行。

扫描数一直增加或暂时没有输出

任务会分别显示扫描发现与实际处理进度，扫描结束前总数会变化。版本比较、作品确认、共享资料或存储额度都会等待。查看阶段和等待原因；“就绪即处理”也要先满足核实条件，不保证立即处理第一项。

部分文件成功，但整轮失败

后续扫描失败或共享资料失败时，已经写出的文件会保留。先查看失败行和发现是否完整，再按原历史重试，不能把失败理解为这轮完全没改文件。

移动后来源文件夹不见了

实际移动成功后，系统会清理所选来源范围内确认无内容的空目录，选中的来源目录也可能被删除；不会向上删除存储根或越过所选来源。有残留字幕、NFO 或读取不确定时会保留目录，见移动清理说明。

找错作品或海报一直缺失

找错作品时先在历史确认候选与适用文件，或重新刮削选择正确作品；只缺图片时使用“补齐缺失图片”。自定义季名尚未用于刮削，修改只读项不会改变 NFO。多个作品混放导致共享资料冲突时，先分目录。

同步提示大量删除

不要立即运行同步。回到同步预演，确认来源和目标没有选反，并检查来源目录是否完整可见。

下载任务失败或取消后仍在下载

打开下载详情查看失败原因。取消后，部分网盘可能已经开始处理；到网盘中确认文件和下载状态，再决定是否重新添加。

媒体代理不能播放

检查媒体代理是否已启用、端口是否已按部署方式开放，以及 Emby 或 Jellyfin 是否已连接到正确的代理实例。再确认 STRM 对应的存储仍能打开文件。

Docker bridge 网络下，页面可访问只说明 3000 端口可用。还需要映射你在媒体代理实例中自行填写的“代理端口”。 在 Compose 或容器管理面板中增加对应的 TCP 映射，建议宿主机端口和容器端口都使用你填写的值，再重新创建容器；单纯重启不会应用新增映射。多个实例需要分别映射各自填写的端口。

Emby / Jellyfin 客户端要用代理实例地址登录，而非原媒体服务器端口。Mediora 的服务设置里仍填真实上游服务器地址，避免代理指回自身。本地来源还需确认 Mediora 能访问文件；已有旧路径 STRM 的转换方法见统一播放入口。

启用实例后，从媒体服务器或播放客户端所在机器访问健康检查地址，地址中的端口也使用自己填写的值。例如你填写 8090 时，访问 http://安装机器的内网IP:8090/media-proxy/health；8090 仅为示例。正常应返回 {"success":true}。无法连接时，检查映射、实例状态和宿主机防火墙；连接正常但仍不能播放时，再检查媒体服务器设置与来源文件。完整配置见媒体代理的 bridge 网络设置。

恢复后设置不见了

确认恢复的是完整的 data 目录，并且恢复前已经停止 Mediora。只恢复单个文件可能无法带回全部设置；恢复后还要确认容器可以读写该目录。

影音优化完成，但服务器仍未采用

“已优化”表示 Mediora 已准备结果，“服务器已使用”才表示采用成功；两台服务器的结果也分别记录。查看助手连接、管理员权限和格式提示，先尝试“重新同步”，它不重新读取影片。

助手保护状态或服务器连接变化后，需要重新检测、核对媒体库并保存范围，单纯等待重试不会批准新状态。标准读取达到预算时，可在提供入口的视频上主动确认深入读取，仍不保证取得完整资料。参见影音优化与助手安装。

通知能发，但私聊指令无效

测试消息验证的是出站发送。还要在下载助手绑定已启用入口、配置可达回调，并核对允许的私聊发送者。企业微信验证前先保存并启用 Token 与 EncodingAESKey；Telegram 私聊应使用允许的个人账号，不能把群组或频道接收者直接当作私聊身份。PushPlus 只发通知，不接收指令。

提供排查信息

保留镜像版本、发生时间、具体入口、本轮或操作标识、来源 / 目标类型、错误原文，以及少量相关日志。说明是否发生过挂载重连、换账号、改目录或重启。发出前遮盖真实路径中的隐私和账号、令牌、Cookie、API Key；不要上传 .env、完整数据目录或密钥文件。

排障的四条通用规律

Mediora 的绝大多数问题都落在下面四类里，按顺序自查通常能省掉一圈往返：

1. 看不到目录 / 看不到文件 → 先查挂载和路径：宿主机目录没挂进容器、页面填了宿主机路径、改了编排只重启没重建。
2. 连不上服务 → 优先使用 Mediora 的连接测试或常规设置里的网络测试。浏览器可达不能代替应用可达，必要时再请维护者从容器网络排查。
3. 任务跑完了但什么也没做 → 看逐文件的成功、跳过和失败原因，再查覆盖规则、排除范围和目标目录。尚无运行记录时，再查是否只保存了手动任务或未启用计划。
4. 能跑但结果不对 → 看作品识别是否找错、目标目录层级是否多套了一层、媒体服务器是否已刷新媒体库。

常见组合症状速查

症状	先查这个
绿联NAS网络文件夹挂载列表为空	先查 NAS 真实挂载，再查容器映射、rslave 传播和发现根变量
任务结束但文件没变	看实际是否都被跳过，核对覆盖规则、扫描范围及真正的输出目录
文件名带额外后缀或多出一层目录	查该入口的冲突处理、命名规则与目标层级；不能仅凭后缀断定覆盖选项填错
刮削写了 NFO 但 Emby 没海报	没在媒体服务器里刷新媒体库，或 NFO 写在了服务器扫描范围外
STRM 能生成但播放 401 / 404	媒体代理未启用、端口未映射、来源存储不可读
下载完成但没自动整理	工作流触发目录与下载器保存目录不一致

最佳实践

排障时只改一个变量。 一次只调挂载、或只调路径、或只调覆盖模式，改完立刻验证。同时改三处，成功也不知道是哪处生效的。

先做最小复现： 用 1 个文件、1 个目录、1 个任务复现问题，比在整库上试更省时间。

留好现场： 出现“结果待核对”时，先保存日志原文和相关路径，再动手处理。反复重试只会让证据更难对账。

向他人求助时的固定模板：

镜像版本：
发生时间：
操作入口（哪个页面、哪个任务）：
来源 / 目标（类型 + 容器内路径）：
错误原文：
最近做过什么改动（挂载重连 / 换账号 / 改目录 / 重启）：