日誌與常見問題 - MiCat-S/Mi302 GitHub Wiki

這頁說明去哪裡看 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」。

執行 mi302 logs 看日誌檔。
日誌檔沒有東西或沒有這個檔時，看終端輸出：Linux 用 journalctl -u mi302 -n 50，macOS 或沒有 systemd 時看 config/data/logs/console.log。
常見原因是設定檔格式錯誤（訊息是「設定檔 … 格式錯誤」）和埠號被佔用。設定檔改壞時，修正它或用 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。
帳號不存在時，會用這組帳號密碼建立一個新的管理員。

播放器播不了

在「115 網盤」頁確認 115 還登入著，沒有因為限流或登入失效被暫停。詳情見115 網盤與同步。
在日誌頁搜尋片名：
- 有「播放 … 302 到 …」：Mi302 已經把 115 直鏈交給播放器，問題在播放器連 115 那一段。
- 有「播放 … 失敗」：向 115 取直鏈失敗，訊息會寫原因。
- 什麼都沒有：播放請求沒有到這一步。打開「詳細模式」再播一次，看播放器請求的狀態碼。
播放網址回 401：播放器沒有帶登入資訊。「設定」→「播放」的「播放網址要求登入」預設開啟，某個播放器因此播不了時再關。
下載回 403：「設定」→「播放」的「允許播放器下載影片」被關掉了。

播放流程、登入要求和外網連線的細節見播放與外網連線。