安装 - 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 文件夹。

外网访问

要在家以外的地方看片，需要在前面加一层反向代理，并设置对外网址，见播放与外网访问。

遇到问题

其他设备连不上、端口被占用、权限、国内网络、忘记密码等，见日志与常见问题。