日志与常见问题 - MiCat-S/Mi302 GitHub Wiki

繁體中文 | 简体中文 | English

本页说明去哪里看 Mi302 的日志、详细模式怎么用，以及安装和使用时常见问题的解决方法。

管理页面和程序输出的信息都是繁体中文，下文引用时逐字转成简体，方便对照。

日志页

管理页面的“日志”页显示同步、刮削、扫描、播放和错误的记录，最新的在最上面。每一条有时间、级别、来源（例如“115 同步”“MoviePilot”“扫描”“播放”）和信息。

  • 级别：下拉菜单有“全部”“一般”“警告和错误”“只看错误”，默认是“一般”。“全部”会把详细级别的记录一起显示。
  • 搜索：输入片名、115、MoviePilot 等关键字，匹配信息和来源。
  • 自动更新：默认开启，每 2 秒显示新记录。
  • 条数：Mi302 在内存里保留最近 3000 条，日志页一次最多显示其中符合级别和搜索条件的最新 1000 条。内存里的记录在重启后清空，更早的记录请看日志文件。
  • 下载：点“下载日志档”下载当前的 mi302.log。轮换下来的旧文件列在页面最下方的“旧档：”后面，点文件名就能下载。

日志页上方会显示日志文件的完整路径。日志文件无法写入时，这里显示“（无法写入日志档，只保留在记忆体）”，“下载日志档”下载的是内存里的记录。

日志文件

完整记录写在文件夹 data/logs/ 里的 mi302.log：

安装方式 日志文件
一键安装（Linux） /opt/mi302/config/data/logs/mi302.log
一键安装（macOS） ~/Mi302/config/data/logs/mi302.log
手动用 Python 执行命令时所在文件夹的 data/logs/mi302.log
  • 满 5 MB 换新文件，旧文件依次改名为 mi302.log.1 到 mi302.log.5，保留 5 份。
  • 每一行的格式是“时间 级别 来源: 信息”，例如 2026-09-27 10:00:00,123 INFO embyserver.strm_sync: …。
  • 在终端里实时查看：mi302 logs，会先显示最后 100 行，再持续显示新内容（Ctrl+C 退出）。

同样的内容也会送到终端输出：

  • systemd（Linux 一键安装）：用 journalctl -u mi302 -f 查看。
  • launchd（macOS）和没有 systemd 时的后台运行：写到 config/data/logs/console.log。这个文件不会自动轮换。

Mi302 在读取配置文件之后才开始写 mi302.log。配置文件格式错误这类启动时的错误，只会出现在终端输出里。

详细模式

播放器连不上、播不了的时候，打开日志页下方的“详细模式”：

  • Mi302 会另外记录每个播放器请求：方法、网址、状态码、耗时、播放器的 User-Agent。找不到的网址会标上“未实作或找不到”。管理页面自己的请求不记录。
  • 打开时，级别下拉菜单会自动切到“全部”。
  • 这个开关就是配置文件的 server.log_level: debug，会写进 config.yaml，重启后仍然开着。详细模式的记录很多，找到原因后记得关掉。

也可以直接在 config.yaml 里设置 server.log_level: debug，关闭是 info。

隐藏凭证

写进日志文件、日志页和终端输出之前，网址参数里的凭证一律替换成 ***，不区分大小写：api_key、apikey、token、X-Emby-Token、X-MediaBrowser-Token、pw、password。第三方库打印的网址也一样。

日志里仍然有片名、文件路径和 IP 地址。公开分享日志前，先检查有没有不想公开的内容。

常见问题

其他设备连不上

  • 先执行 mi302 status，确认 Mi302 在运行，并看它打印的网址。

  • 确认防火墙放行了端口，例如：

    sudo ufw allow 8096/tcp
sudo firewall-cmd --permanent --add-port=8096/tcp && sudo firewall-cmd --reload

    一键安装脚本发现 ufw 或 firewalld 开着时，会打印这行命令提醒。

  • 用这台机器的局域网 IP 连接，不要用 localhost 或 127.0.0.1。机器有多块网卡时，安装脚本打印的 IP 不一定是你要的那个。

  • config.yaml 的 server.host 默认是 0.0.0.0（所有网络接口都接受连接）。改成 127.0.0.1 时只有本机能连。改完要重启。

  • 外网访问见播放与外网访问。

端口被占用

安装脚本发现端口已经有程序在用时，会提示“先把它关掉，不然 Mi302 会启动失败”，并问“已经关掉了，继续安装？”。

  • 多半是之前手动启动的 Mi302 还在运行。Emby、Jellyfin 默认也用 8096。
  • 查是谁在用：Linux 用 sudo ss -ltnp | grep 8096，macOS 用 lsof -nP -iTCP:8096 -sTCP:LISTEN。
  • 关掉那个程序，或换一个端口：重新执行安装脚本加上 --port 8097，或改 config.yaml 的 server.port 后执行 mi302 restart。

装完之后没有响应、起不来

安装脚本最多等 60 秒。Mi302 还没响应时，会提示“Mi302 还没有回应；看日志找原因：mi302 logs”。

  1. 执行 mi302 logs 查看日志文件。
  2. 日志文件没有内容或不存在时，看终端输出：Linux 用 journalctl -u mi302 -n 50，macOS 或没有 systemd 时看 config/data/logs/console.log。
  3. 常见原因是配置文件格式错误（信息是“设定档 … 格式错误”）和端口被占用。配置文件改坏时，改正它或用 config.yaml.bak 还原，再执行 mi302 restart。

网络硬盘开机后才挂载

NAS 的 NFS、SMB 共享文件夹，或 Parallels 的 /media/psf/... 这类文件夹，可能在 Mi302 启动之后才挂载。

Mi302 发现媒体库文件夹不存在、读不到或是空的，会保留原来的项目和观看记录，不会当成视频全被删了。日志会出现“媒体库路径不存在或是空的：…（没挂载好？）；保留原本的 N 个项目”。

挂载好之后，在“媒体库”页点“全部重新扫描”即可。一键安装的 systemd 服务会等网络和 remote-fs.target 准备好才启动，写在 /etc/fstab 里的网络硬盘通常来得及挂载。

strm 写不进去、扫描不到视频

多半是运行 Mi302 的账号没有媒体文件夹的权限。

  • 在 Linux 上，运行账号是安装时选的那个，记在安装位置 .env 的 MI302_USER。macOS 上就是你自己的账号。

  • 用这个账号测试读写：

    sudo -u 账号 ls /媒体/文件夹
sudo -u 账号 touch /媒体/文件夹/测试 && sudo -u 账号 rm /媒体/文件夹/测试

  • 解决方法：重新执行安装脚本并用 --user 换成有权限的账号，或让这个账号获得文件夹的权限。

  • 以前用 Docker 版的，已有的 strm、nfo 可能属于 root，见安装的“以前用 Docker 版”。

国内网络

  • pip：一键安装脚本连不上 PyPI 时，会自动改用清华镜像，并记下来供之后更新使用。也可以加上 --mirror 直接指定。手动安装的在 pip 命令后加 -i https://pypi.tuna.tsinghua.edu.cn/simple。
  • GitHub：raw.githubusercontent.com 连不上时，到 GitHub 的项目网页点“Code → Download ZIP”下载，解压后在文件夹里执行 sudo bash install.sh（macOS 不加 sudo）。解压出来的文件夹就是安装位置，所以先把它移到想放的地方再执行。之后的 mi302 update 仍然需要连上 GitHub。

忘记管理员密码

一键安装的：

mi302 reset-password admin 新密码

macOS 没有 mi302 命令时，改用 bash ~/Mi302/install.sh reset-password admin 新密码。

手动安装的，在放 data/ 的那个文件夹（上面的例子是 Mi302/）执行：

.venv/bin/python -m embyserver -c config.yaml --reset-password admin 新密码
  • 成功时会打印“已重设 admin 的密码”。不用先停止 Mi302。
  • 账号不存在时，会用这组账号密码创建一个新的管理员。

播放器播不了

  1. 在“115 网盘”页确认 115 还处于登录状态，没有因为限流或登录失效被暂停。详见115 网盘与同步。
  2. 在日志页搜索片名：
    • 有“播放 … 302 到 …”：Mi302 已经把 115 直链交给播放器，问题在播放器连接 115 那一段。
    • 有“播放 … 失败”：向 115 获取直链失败，信息里会写原因。
    • 什么都没有：播放请求没有走到这一步。打开“详细模式”再播一次，看播放器请求的状态码。
  3. 播放网址返回 401：播放器没有带登录信息。“设定”→“播放”的“播放网址要求登入”默认开启，某个播放器因此播不了时再关。
  4. 下载返回 403：“设定”→“播放”的“允许播放器下载影片”被关掉了。

播放流程、登录要求和外网访问的细节见播放与外网访问。