Motrix 服务器版（Docker）

Motrix Server 把 Motrix 下载内核和 aria2 打包成非 root、多架构的容器镜像，适合 NAS 与家庭服务器。它用的是与桌面版完全相同的下载引擎、任务模型和设置项，只是去掉了 Electron 外壳——你通过浏览器访问它。

带 tag 的正式发布会把同一个镜像推送到两个 registry：

Docker Hub——docker.io/motrixapp/motrix-server
GitHub Container Registry——ghcr.io/agalwood/motrix-server

每个发布镜像都同时包含 linux/amd64 和 linux/arm64，Docker 会自动选择匹配的 manifest。不支持 32 位 ARM。

容器对外提供什么

服务器模式在两个端口上提供两项彼此独立的服务。两者都是 HTTP，但用途不能互换。

地址	提供的服务
`http://NAS_HOST:8080`	Web 界面、operator API，以及公开的 `GET /healthz` 探针
`http://NAS_HOST:16801`	MDXP endpoint——单次调用 `POST /mdxp`、事件流 `GET /mdxp/events`，以及命令行工具和 AI agent 的 device-code 配对

开始之前

一台 64 位主机(amd64 或 arm64)，装好 Docker 和 Compose 插件。
在持久化存储上准备两个目录：一个存状态，一个存下载文件，分别挂载到 /data 和 /downloads。
两个目录的 owner 必须是容器运行时使用的数字 UID/GID——不做覆盖时是 1000:1000。

Warning

/data 里存放 SQLite 数据库、设置、aria2 session 与 DHT 状态、种子元数据、operator token 和已安装的插件。重建容器时如果少了这个挂载，这些数据全部丢失。/data 必须备份；/downloads 按你自己的数据策略决定。

用 Docker Compose 快速开始

直接使用仓库自带的 compose.yaml：

name: motrix

services:
  server:
    image: "${MOTRIX_IMAGE:-motrixapp/motrix-server:latest}"
    init: true
    read_only: true
    user: "${MOTRIX_UID:-1000}:${MOTRIX_GID:-1000}"
    security_opt:
      - no-new-privileges:true
    restart: unless-stopped
    stop_grace_period: 2m
    tmpfs:
      - /tmp:rw,noexec,nosuid,size=64m,mode=1777
    environment:
      MOTRIX_DATA_DIR: /data
      MOTRIX_TEMP_DIR: /data/tmp
      MOTRIX_PLUGIN_DIR: /data/plugins
      MOTRIX_DEFAULT_SAVE_DIR: /downloads
      MOTRIX_ALLOWED_SAVE_DIRS: /downloads
      MOTRIX_MDXP_HOST: 0.0.0.0
      MOTRIX_MDXP_PORT: 16801
      MOTRIX_PUBLIC_URL: "${MOTRIX_PUBLIC_URL:-}"
    ports:
      - "${MOTRIX_WEB_BIND_IP:-${MOTRIX_BIND_IP:-0.0.0.0}}:${MOTRIX_HTTP_PORT:-8080}:8080"
      - "${MOTRIX_MDXP_BIND_IP:-${MOTRIX_BIND_IP:-0.0.0.0}}:${MOTRIX_MDXP_PUBLIC_PORT:-16801}:16801"
    volumes:
      - ./motrix-data:/data
      - ./downloads:/downloads

然后创建目录并启动服务：

mkdir -p motrix-data downloads

# 使用专用非 root 账户;以下命令使用当前账户。
export MOTRIX_UID="$(id -u)"
export MOTRIX_GID="$(id -g)"
chown "$MOTRIX_UID:$MOTRIX_GID" motrix-data downloads

export MOTRIX_PUBLIC_URL='http://nas.example.lan:8080'
docker compose pull server
docker compose up -d --wait
docker compose ps

不改 Compose 文件也能用 MOTRIX_IMAGE 选择 registry、tag 或 digest，例如 ghcr.io/agalwood/motrix-server:2.0.0，或者用 @sha256: digest 得到完全可复现的部署。:latest 这类 floating tag 在 NAS 上最省事；需要受控升级和回滚时，请用不可变的 SemVer tag 或 digest。

Caution

不要为了绕过挂载权限错误就把 runtime UID 设为 0 或开启 privileged 模式，请去修正那两个目录的 owner。启动过程会对每个需要的路径做实际写入测试，出错时会带着确切的绝对路径失败。

等价的 `docker run` 写法

docker run -d \
  --name motrix-server \
  --init \
  --restart unless-stopped \
  --stop-timeout 120 \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=64m,mode=1777 \
  --security-opt no-new-privileges:true \
  --user "$(id -u):$(id -g)" \
  -e MOTRIX_PUBLIC_URL='http://nas.example.lan:8080' \
  -e MOTRIX_MDXP_HOST=0.0.0.0 \
  -p 8080:8080 \
  -p 16801:16801 \
  -v "$PWD/motrix-data:/data" \
  -v "$PWD/downloads:/downloads" \
  motrixapp/motrix-server:latest

镜像本身已经定义了 healthcheck、非 root 用户、数据路径和优雅的 SIGTERM 处理。MOTRIX_MDXP_HOST=0.0.0.0 控制的是容器内的 listener，而两个 -p 选项才决定宿主上哪些接口能访问它。

首次登录：operator token

首次启动时，Motrix 会以 0600 权限在 /data/operator-token 生成一个随机 operator token。重启容器或替换镜像后，这个 token 保持不变。

按上面的 bind mount 布局，在宿主上这样读取：

cat motrix-data/operator-token

打开 http://NAS_HOST:8080，Web 界面会显示 「解锁 Motrix」 页面，其中有一个 「Operator token」 输入框。把 token 粘贴进去，点击 「解锁」。

你也可以自己设置 MOTRIX_OPERATOR_TOKEN，但环境变量能从容器元数据里读到——单机部署用自动生成的文件更安全。

Tip

解锁失败时，请重新读取当前的 /data/operator-token。从另一套部署复制来的 token 永远不会生效。

你大概会用到的环境变量

变量	镜像默认值	作用
`PORT`	`8080`	容器内 Web/API 监听端口
`MOTRIX_DATA_DIR`	`/data`	状态目录，必须是可写的绝对路径
`MOTRIX_DEFAULT_SAVE_DIR`	`/downloads`	新任务默认保存到哪里
`MOTRIX_ALLOWED_SAVE_DIRS`	`/downloads`	以冒号分隔的绝对根目录清单，由服务端强制执行
`MOTRIX_PUBLIC_URL`	未设置	交给配对客户端的、外部可访问的 Web 审批 URL
`MOTRIX_OPERATOR_TOKEN`	自动生成文件	operator 凭据；不想读文件时可以自己提供
`MOTRIX_FFMPEG_PATH`	自动探测	你自行提供的 FFmpeg 可执行文件绝对路径
`LOG_LEVEL`	`info`	输出到容器 stdout 的日志级别

要增加第二个下载根目录，必须同时挂载并允许它，只做一半会让任务被拒绝：

environment:
  MOTRIX_ALLOWED_SAVE_DIRS: /downloads:/archive
volumes:
  - /srv/archive:/archive

完整的环境变量参考——插件来源、secret seed、宿主绑定地址、MDXP listener 细节——见本页末尾链接的部署指南。

配对 CLI 与 AI agent

桌面版走的本机 socket 捷径在这里并不存在，所以远程的 motrix CLI 或 agent 需要通过 MDXP 用 device code 配对。

MOTRIX_PUBLIC_URL 就是返回给客户端的 Web 审批 URL。它没有 localhost 默认值：请把它设成其他机器实际使用的地址——用 Web 端口（或它的反向代理 URL），不要用 MDXP 端口，也不要用 localhost、127.0.0.1 或 0.0.0.0。留空不会禁用配对，但客户端拿不到可用的审批链接。

先在客户端发起配对，然后用以下两种方式之一批准：

在 Web 界面里——打开 设置 → 「集成」→「命令行工具」，请求会带着验证码出现在 「待审批」 里，点 「批准」（或 「拒绝」）。
通过 SSH——在运行中的容器里批准指定的验证码：

docker compose exec server motrix-admin pairing pending
docker compose exec server motrix-admin pairing approve ABCD-EFGH
docker compose exec server motrix-admin pairing deny ABCD-EFGH

motrix-admin 只通过容器 loopback 与运行中的服务器通信，不会输出 operator 凭据或客户端 token。它刻意不提供 approve-latest、approve-all 或远程 endpoint——你必须手动输入客户端显示的那串验证码。Web 审批仍然是正常路径，这条命令是 headless 部署下的恢复手段。

安全边界

在可信 LAN 里使用明文 HTTP 是合理的，Motrix 不强制 HTTPS。

Warning

不要以明文 HTTP 把任何一个端口暴露到公网。公网访问必须做两件事：在可信反向代理上终止 TLS，并且用防火墙保护 origin 端口——两项服务都要做。只转发 8080 不会发布 MDXP，只转发 16801 也不会提供审批界面。代理需要保留 cookie、Authorization header 和流式响应。

不要用禁用配对的方式来实现这些保护。远程 CLI 与 agent 配对始终是一项需要 operator 审批的正常流程。

容器自身默认已经加固：以非 root 用户运行、根文件系统只读、启用 no-new-privileges，并为 /tmp 挂一个小的 noexec tmpfs。请保持这些设置——不要挂载 Docker socket，也不要把整个文件系统交给容器。

与桌面版的差异

Note

Web 界面的 设置 → 「关于」 里会写明 「此 Web 版本由部署管理员负责更新。」 这里没有应用内更新按钮：升级的方式是拉取新镜像并重建容器。升级前先备份 /data、记下正在替换的 digest；跨主版本前请先读 release notes。

其他需要如实说明的差异：

浏览器扩展配对只有桌面版有。 扩展的首次配对走 native messaging flow，headless server 不提供该流程。参见浏览器扩展。
官方镜像不含 FFmpeg。 依赖它的插件需要基于官方镜像做一层派生镜像，安装 Alpine 的 ffmpeg 包，并设置 MOTRIX_FFMPEG_PATH=/usr/bin/ffmpeg。
Web 版的一键 registry 安装即将推出。 你现在可以浏览插件目录，但安装要么在界面里上传 .moext 包，要么用 MOTRIX_PLUGIN_INSTALL_URLS / MOTRIX_PLUGIN_IMPORT_DIRS 在启动时声明来源。已安装的包、授权、配置和 secret 都持久化在 /data，替换容器后仍然保留。参见插件。

除此之外——HTTP 与 BitTorrent 任务、速度限制、tracker、代理——行为都和本手册其他章节所写的一致。

NAS 平台

群晖 DSM 7 的 Container Manager 和飞牛 fnOS 都可以把 compose.yaml 作为项目导入，两者的做法是同一套：在真实存储池上创建那两个目录，把它们交给一个专用非管理员账户的数字 UID/GID，把 MOTRIX_UID / MOTRIX_GID 设成相同的数字，把 MOTRIX_PUBLIC_URL 设成其他设备实际访问的 URL，然后启动项目，等 health 状态正常后再打开 Web 界面。不要启用「高权限」，也不要让 NAS 做本地镜像 build——它应该直接拉取已发布的镜像。两个平台的逐步说明见部署指南。

接下来

Motrix 命令行工具——安装 @motrix/cli 并与这台服务器配对。
插件——插件能做什么，以及怎么安装。
疑难排解——下载不动了怎么办。

镜像签名与 provenance、tag 策略、named volume、反向代理拓扑、升级与回滚流程、/api/diagnostics、DSM 与 fnOS 的完整步骤，以及完整的环境变量表格，都在完整部署指南里。

Motrix 服务器版（Docker）

容器对外提供什么#

开始之前#

用 Docker Compose 快速开始#

等价的 docker run 写法#

首次登录：operator token#

你大概会用到的环境变量#

配对 CLI 与 AI agent#

安全边界#

与桌面版的差异#

NAS 平台#

接下来#