安裝 - MiCat-S/Mi302 GitHub Wiki

繁體中文 | 简体中文 | English

這頁說明怎麼安裝 Mi302：一鍵安裝腳本和它的選項、幾種特殊情況、mi302 管理指令、手動用 Python 執行，以及更新和移除。

選擇安裝方式

方式 適合 開機自動啟動
一鍵安裝腳本（建議） Linux、macOS 自動設定
手動用 Python 想自己控制每一步，或 Windows 自己設定

Mi302 需要 Python 3.10 以上，一鍵安裝腳本找不到時會自動安裝。Mi302 不提供 Docker 版；以前用 Docker 版的，見下面的「以前用 Docker 版」。

一鍵安裝腳本

在要執行 Mi302 的 Linux 機器上執行（macOS 不加 sudo，見下面的「macOS」）：

curl -fsSL https://raw.githubusercontent.com/MiCat-S/Mi302/main/install.sh | sudo bash

腳本依序做這些事：

  1. 下載程式到安裝位置（Linux 預設 /opt/mi302）。有 git 就用 git；沒有 git 時先試著用系統的套件管理員安裝，裝不起來就改下載壓縮檔。
  2. 問兩個問題：
    • 用哪個使用者執行 Mi302：預設是執行 sudo 的帳號。這個帳號要能讀寫媒體資料夾，115 同步產生的 strm 也是用它的身分寫入。
    • 埠號：預設 8096。已經有設定檔時不問，沿用設定檔裡的埠號。
  3. 找不到 Python 3.10 以上時安裝 Python，建立 Python 虛擬環境 .venv，安裝相依套件，並安裝 ffmpeg。ffmpeg 是媒體資訊探測用的，裝不起來只會提醒，不影響其他功能。
  4. 設定開機自動啟動（systemd 服務 mi302.service），啟動 Mi302，最多等 60 秒確認網頁有回應。
  5. 印出網址和管理指令。

系統套件用 apt-get、dnf、yum、apk、pacman 或 zypper 安裝，看機器上有哪一個。問題問完之後就不用守在螢幕前；只有埠號已經被別的程式佔用時，才會再問一次要不要繼續。

最後印出的內容像這樣（IP 是腳本找到的第一個區網位址）：

==> Mi302 已經在執行  版本 64a30e6（2026-09-27 10:00）

  管理網頁： http://192.168.1.20:8096/web
  播放器：   新增 Emby 伺服器，位址 http://192.168.1.20:8096
  設定檔：   /opt/mi302/config/config.yaml
  資料和日誌：/opt/mi302/config/data/

  管理指令： mi302 status | logs | restart | update | reset-password 帳號 密碼 | uninstall

打開「管理網頁」的網址，照首次設定做。ufw 或 firewalld 防火牆開著時，腳本會另外印出放行埠號的指令。

選項

選項 說明
--user 帳號 用哪個使用者執行（只用在 Linux），要能讀寫媒體資料夾。預設是執行 sudo 的帳號
--port 埠號 網頁和播放器用的埠號，1–65535。預設 8096
--dir 資料夾 安裝位置。Linux 預設 /opt/mi302，macOS 預設 ~/Mi302；在程式資料夾裡執行 install.sh 時，就裝在那個資料夾
--mirror pip 改用清華鏡像。連不上 PyPI 時會自動改用
--branch 分支 從哪個分支安裝，預設 main
-y、--yes 不詢問，沒給的選項都用預設值
-h、--help 顯示說明

不想一題一題回答，可以把選項一次給完：

# 以 cat 這個帳號執行，埠號 8097，其他用預設值
curl -fsSL https://raw.githubusercontent.com/MiCat-S/Mi302/main/install.sh | sudo bash -s -- --user cat --port 8097 -y

執行帳號、分支和 pip 鏡像記在安裝位置的 .env，埠號記在 config.yaml 的 server.port。之後重新執行腳本或更新時都會沿用，只要給想改的選項。

裝好的檔案

/opt/mi302/                 macOS 是 ~/Mi302
  config/                   設定和資料，更新時保留
    config.yaml             設定檔（網頁上的設定也寫在這裡）
    config.yaml.bak         上一版設定檔
    data/
      library.db            資料庫：帳號、觀看紀錄、115 登入狀態等
      backups/              每天的自動備份
      images/               上傳的圖片（例如媒體庫封面）
      logs/mi302.log        日誌
  .env                      安裝時選的選項
  .venv/                    Python 虛擬環境
  install.sh、embyserver/…  程式

設定檔怎麼運作見首次設定，備份見備份與還原。

特殊情況

macOS

不要加 sudo：

curl -fsSL https://raw.githubusercontent.com/MiCat-S/Mi302/main/install.sh | bash

  • 用 sudo 執行時，腳本會直接停下來。

  • 安裝位置是 ~/Mi302，以你自己的帳號執行，不會問執行帳號。

  • 需要安裝 Python 時用 Homebrew 安裝 [email protected]，ffmpeg 也用 Homebrew 安裝。需要 Python 卻沒有 Homebrew 時，腳本會停下來，請先安裝 Homebrew，或從 python.org 安裝 Python 3.12。

  • 自動啟動用 launchd（~/Library/LaunchAgents/com.mi302.server.plist）。Mi302 在你登入 macOS 後才啟動，不正常結束時會自動重新啟動。

  • 終端輸出寫到 ~/Mi302/config/data/logs/console.log。

  • mi302 指令要寫進 /usr/local/bin。這個資料夾不存在，或你的帳號沒有寫入權限（例如它屬於 root）時，腳本不會建立 mi302 指令，也不會另外提醒，只是最後印出的「管理指令」變成 bash /Users/<你>/Mi302/install.sh status | logs | …。這時把本頁的 mi302 都換成 bash ~/Mi302/install.sh：

    bash ~/Mi302/install.sh status
bash ~/Mi302/install.sh reset-password admin 新密碼

    一定要加上指令。不加指令等於重新安裝，會更新程式並重新啟動 Mi302。

已經自己 git clone 下來跑過

在那個資料夾裡執行（macOS 不加 sudo）：

sudo bash install.sh
  • 腳本裝在原地。原本的 config.yaml 和 data/ 留在原位照用，不會搬進 config/。
  • 先把手動開的 Mi302 關掉，不然埠號會被佔用。腳本發現埠號有程式在用時會提醒，並問「已經關掉了，繼續安裝？」。
  • 程式會更新到 main 分支的最新版。程式資料夾裡自己改過的檔案，會先備份成 local-changes-年月日-時分秒.patch，再還原成最新版。

以前用 Docker 版

這個版本不再提供 Docker，但 config/ 裡的設定和資料可以直接沿用：

  1. 先記下舊資料夾裡 .env 的 MI302_PORT（對外埠號）和 MI302_MEDIA（媒體資料夾）。重新安裝後 .env 會被改寫。

  2. 在舊資料夾執行 docker compose down 停掉容器。config/ 資料夾留著。

  3. 用上面的一行指令執行新版安裝腳本，--dir 指到舊資料夾。原本的對外埠號不是 8096 時，用 --port 帶上：

    # 舊資料夾是 /opt/mi302，原本的對外埠號是 8097
curl -fsSL https://raw.githubusercontent.com/MiCat-S/Mi302/main/install.sh | sudo bash -s -- --dir /opt/mi302 --port 8097

    不要直接執行舊資料夾裡的 install.sh：那是舊版腳本，還會照 Docker 的方式處理。新版腳本會提醒「偵測到舊的 Docker 安裝，改成直接用 Python 執行」，然後照一般方式安裝。

  4. 容器裡的媒體資料夾是 /media，現在 Mi302 直接看主機上的路徑。媒體庫的資料夾、同步任務的本機資料夾如果還是 /media/...，要在網頁上改成主機上的路徑（MI302_MEDIA 底下）。MoviePilot 的路徑對應也一樣。

  5. 容器以 root 身分寫檔，媒體資料夾裡既有的 strm、nfo 可能屬於 root。執行帳號改不動它們時，用 sudo chown -R 帳號 媒體資料夾 改擁有者。

舊的 --docker、--media 選項已經拿掉，加了會直接報錯。

沒有 systemd 的環境（例如 WSL）

沒有 systemd 時，腳本改成在背景執行 Mi302，並提醒重新開機後要自己執行 mi302 start。

  • 程序編號記在 config/mi302.pid，mi302 stop、mi302 restart 靠它找到 Mi302。
  • 終端輸出寫到 config/data/logs/console.log。
  • WSL 有開 systemd 時，照一般 Linux 設定成 systemd 服務。

mi302 管理指令

裝好之後用 mi302 指令管理：

指令 作用
mi302 或 mi302 status 是否在執行、管理網頁網址、版本
mi302 logs 顯示日誌檔最後 100 行並持續顯示新的（Ctrl+C 離開）
mi302 start、mi302 stop、mi302 restart 啟動、停止、重新啟動
mi302 update 更新到最新版並重新啟動，設定和資料不動
mi302 reset-password 帳號 新密碼 忘記密碼時重設；帳號不存在時建立成管理員
mi302 uninstall 移除開機自動啟動和 mi302 指令，程式、設定和資料留著
  • mi302 是 /usr/local/bin/mi302，它會執行安裝位置裡的 install.sh。所以 mi302 status 和 sudo bash /opt/mi302/install.sh status 是一樣的。
  • 在 Linux 上每個指令都需要 root，mi302 會自己用 sudo 重新執行，可能會要你輸入密碼。
  • Linux 上的服務是 systemd 的 mi302.service，也可以用 systemctl status mi302、journalctl -u mi302 -f 查看。macOS 上是 launchd 的 com.mi302.server。

換埠號或執行帳號

重新執行安裝腳本並加上新選項。已經裝好的部分會沿用，等於順便更新：

sudo bash /opt/mi302/install.sh --port 8097
sudo bash /opt/mi302/install.sh --user cat

只換埠號，也可以改 config.yaml 的 server.port，再執行 mi302 restart。換埠號之後，播放器裡的伺服器位址和防火牆規則也要跟著改。

手動用 Python

需要 Python 3.10 以上（用 python3 --version 查看）。Debian、Ubuntu 沒有 venv 模組時，先執行 sudo apt install python3-venv。

git clone https://github.com/MiCat-S/Mi302.git
cd Mi302
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python -m embyserver

然後開 http://<主機>:8096/web，照首次設定做。

  • 設定檔 config.yaml 和資料夾 data/ 放在執行指令時所在的資料夾，上面的例子就是 Mi302/。data_dir 的預設值 ./data 是相對於這個資料夾，不是相對於設定檔。
  • 媒體資訊探測要用 ffprobe，請自己安裝 ffmpeg，例如 sudo apt install ffmpeg 或 brew install ffmpeg。
  • 改埠號：改 config.yaml 的 server.port，再重新啟動。
  • 國內網路 pip 很慢時，加上 -i https://pypi.tuna.tsinghua.edu.cn/simple。
  • Windows：把指令裡的 .venv/bin/ 換成 .venv\Scripts\。一鍵安裝腳本不支援 Windows。

命令列選項

選項 作用
-c 路徑、--config 路徑 設定檔位置。沒給時看環境變數 EMBYSERVER_CONFIG，再沒有就用目前資料夾的 config.yaml
--reset-password 帳號 新密碼 重設密碼後結束。帳號不存在時建立成管理員
--scan 掃描所有媒體庫後結束
--sync-115 從 115 全量同步 strm，接著依設定掃描、送去刮削，然後結束。寫成 --sync-115 incremental 是增量同步

沒有 --reset-password、--scan、--sync-115 時就是啟動伺服器。

開機自動啟動（systemd）

把下面的 cat 和路徑換成你的，存成 /etc/systemd/system/mi302.service。WorkingDirectory 要是放 data/ 的那個資料夾：

[Unit]
Description=Mi302
Wants=network-online.target
After=network-online.target remote-fs.target

[Service]
User=cat
WorkingDirectory=/home/cat/Mi302
ExecStart=/home/cat/Mi302/.venv/bin/python -m embyserver -c /home/cat/Mi302/config.yaml
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

然後執行：

sudo systemctl daemon-reload
sudo systemctl enable --now mi302

也可以在程式資料夾裡執行 sudo bash install.sh，改成由一鍵安裝腳本管理（見上面的「已經自己 git clone 下來跑過」）。

更新

一鍵安裝的：

mi302 update

它會下載最新版（用 git；從 ZIP 解壓安裝的改下載壓縮檔）、更新相依套件、重寫自動啟動設定、重新啟動，最後印出網址。config/ 裡的設定和資料不動。程式資料夾裡自己改過的檔案，會先備份成 local-changes-*.patch 再還原成最新版。更新需要連得上 GitHub。重新執行一鍵安裝指令也會更新。

手動安裝的：

cd Mi302
git pull
.venv/bin/pip install -r requirements.txt

再重新啟動 Mi302。用上面的 systemd 設定時，執行 sudo systemctl restart mi302。

在網頁上更新和重新啟動

一鍵安裝（或自己 git clone）的，不用開終端機：網頁左側欄最下面有版本卡片，底下是「重新啟動」和「登出」。版本卡片平常打勾顯示「已是最新版」和目前的版本（例如 0.1.0・472298c）；有新版時變成藍色的「有新版本（N）」並多一個小點；檢查或更新中會轉圈，檢查失敗會寫「檢查更新失敗」，還沒檢查過只顯示版本。上次檢查的結果重新啟動後還在。窄螢幕上它們在頂端那一列，只剩圖示。按版本卡片打開「版本與更新」：

  • 目前的版本：版本號、提交編號、時間和這一版的標題。
  • 「檢查更新」：馬上向 GitHub 查。開著「自動檢查更新」（預設開，設定檔 server.update_check）時，Mi302 啟動一分鐘後查一次，之後每 6 小時一次。
  • 有新版時，每一頁上方都會出現提示，版本卡片變成「有新版本（N）」並多一個小點；打開後列出每一個更新的標題。提示上的「先不要」只讓這一版不再提示，下一版還是會。
  • 「更新到最新版」（或提示上的「立即更新」）：和 mi302 update 一樣下載新版；requirements.txt 有變就安裝相依套件；再先試著載入一次新版。任何一步失敗就退回原本的版本、不重新啟動，網頁照常可用，並寫出原因。都沒問題就自動重新啟動，網頁等它回來後自己重新載入，大約 10 秒到 1 分鐘。程式資料夾裡自己改過的檔案，一樣先備份成 local-changes-*.patch。
  • 「重新啟動」（側欄或「版本與更新」裡）：只重新啟動，大約 5 到 10 秒。正在進行的 115 同步、掃描、刮削、整理會中斷，確認框會列出來。播放中的影片可能會斷一下。
  • 「連不上 GitHub：代理、GitHub 加速」：國內網路檢查更新失敗時（錯誤訊息會提示），填一個就好，按「儲存並檢查更新」馬上試。用法和 MoviePilot 的「網路代理」「GitHub 加速代理」一樣：
    • 代理（server.update_proxy）：http:// 或 socks5://，例如 Clash、v2rayN 開的本機埠 http://127.0.0.1:7890。git 下載新版和安裝相依套件都走它；安裝相依套件用 socks5 時要另外裝 PySocks，建議用 http。
    • GitHub 加速網址（server.update_github_proxy）：例如 https://ghfast.top/，下載新版時接在 GitHub 網址前面。加速站偶爾會失效，換一個就好。
    • 只用在檢查更新和更新，播放、115、MoviePilot 不經過這裡。安裝相依套件時照樣用安裝腳本記下的 pip 鏡像（--mirror）。

網頁上的更新只換程式和相依套件。安裝腳本管的東西（systemd、launchd 的服務設定、ffprobe、Python 版本）還是要在終端機執行 mi302 update。以下情況「版本與更新」裡會寫原因，請改用 mi302 update：

  • 從 ZIP 解壓安裝的（程式資料夾不是 git）。
  • 這台機器沒有 git。
  • Mi302 的執行帳號沒有權限改程式資料夾或 .venv（例如用 --user 指定了別的帳號，程式資料夾卻屬於 root）。

重新啟動是 Mi302 自己停下再用同一個指令啟動，程序編號不變，所以 systemd、launchd 或沒有 systemd 時的背景執行都適用。三分鐘都沒回來時，網頁會提示到伺服器上用 mi302 status、mi302 logs 看原因。

移除

mi302 uninstall

確認之後，它會停止 Mi302，移除開機自動啟動（systemd 服務、launchd 設定或背景程序）和 mi302 指令。程式、設定和資料都留著，之後重新執行安裝腳本就能恢復。

要全部刪掉，再刪除安裝資料夾。這會一起刪掉設定、資料庫、備份和日誌，需要的話先備份：

sudo rm -rf /opt/mi302    # macOS：rm -rf ~/Mi302

媒體資料夾裡產生的 strm 和刮削資料不在安裝資料夾裡，不會被刪。

手動安裝的：停掉 Mi302。有設定 systemd 的，執行 sudo systemctl disable --now mi302，並刪掉 /etc/systemd/system/mi302.service。最後刪掉 Mi302 資料夾。

從外網連線

要在家以外的地方看片，在前面加一層反向代理，並設定對外網址，見播放與外網連線。

遇到問題

其他裝置連不上、埠號被佔用、權限、國內網路、忘記密碼等，見日誌與常見問題。