部署

• 一台能运行 Docker 与 Docker Compose 的主机，例如 NAS。
• Plex 能扫描到的媒体，可以是本地文件、.strm 文件，或者两者放在同一个媒体库里。STRM 要指向可以访问的远端媒体地址。Cirvel 不生成 STRM，也不绑定任何 STRM 工具。
• 已经在用 Plex 的，沿用原来的配置目录即可，服务器、媒体库和观看记录会原样保留。

Cirvel 镜像里内置了一个经过验证的 Plex Media Server。已经用 Compose 运行 Plex 的，把原来的 image 换成 tidewren/cirvel:latest，其余配置都不用动。全新部署可以参考下面的写法。

services:
  cirvel:
    image: tidewren/cirvel:latest
    container_name: cirvel
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
      # 全新部署也可以用 Plex 认领令牌认领，令牌从 plex.tv/claim 获取，见下一节
      # - PLEX_CLAIM=claim-xxxxxxxxxxxxxxxxxxxx
    volumes:
      - ./app_data/config:/config
      - /path/to/media:/data
    # 有 Intel 或 AMD 核显时映射进来，Plex 才能硬件转码，见「硬件转码」
    # devices:
    #   - /dev/dri:/dev/dri
    ports:
      - 32400:32400
    restart: unless-stopped

1. 1把 /path/to/media 换成主机上的媒体目录，PUID 与 PGID 换成对这些目录有读写权限的用户。
2. 2在 compose.yaml 所在目录执行 docker compose up -d 启动容器。
3. 3在浏览器打开 http://<服务器地址>:32400/web，用自己的 Plex 账号登录。全新部署的服务器会先转到管理面板认领，见下一节。

镜像发布在 Docker Hub，GitHub Container Registry 同步提供 ghcr.io/tidewren/cirvel，两者内容相同。

全新部署的 Plex 要先认领到你的 Plex 账号，认领之后才能用这个账号登录 Plex 与管理面板。沿用原来配置目录的服务器早已认领，跳过这一节。

在管理面板里认领最简单，host 与 bridge 网络都适用。

1. 1容器启动后在浏览器打开 http://<服务器地址>:32400/web，还没认领的服务器会转到管理面板的「认领这台 Plex 服务器」。也可以直接打开 http://<服务器地址>:32400/cirvel/。
2. 2点「使用 Plex 账号登录并认领」，在弹出的 Plex 窗口里登录，等认领完成即可。浏览器已经登录 Plex 时，按钮是「认领服务器」。
3. 3页面上有「认领码」一栏时（经外网地址、域名或反向代理打开时常见），先填上认领码，再点同一个按钮。
4. 4认领完成后自动进入管理面板，这时 Plex Web 与 Plex 客户端也能用这个账号找到服务器。

认领码写在容器日志、Cirvel.log 与配置目录里的 cirvel/claim-code.txt 中，只有能看到这台服务器的人才读得到，免得服务器开在公网上时被别人抢先认领。容器重启后认领码会换新，以最新的为准。认领成功后这个文件会删除。配置目录只有容器的运行用户可读，经 SMB、NFS 或宿主机上的其他账号查看时请使用与 PUID 对应的账号，或者直接在容器日志里找认领码。

不方便打开面板，或者想在部署时一并认领，也可以用 Plex 认领令牌。

1. 1用自己的 Plex 账号登录 https://plex.tv/claim，复制页面上以 claim- 开头的 Plex 认领令牌。令牌 4 分钟内有效，拿到后尽快进行下一步。
2. 2在 compose.yaml 的 environment 里加上 PLEX_CLAIM=<Plex 认领令牌>，执行 docker compose up -d。
3. 3容器启动后打开 http://<服务器地址>:32400/web，用同一个账号登录，能进入这台服务器就是认领成功了。

媒体目录在容器里的路径，必须与本地文件和 STRM 被 Plex 扫描时的路径一致。原来的 Plex 把媒体挂在 /data 下，换成 Cirvel 后也挂在 /data 下。

作品目录名里写上编号，Plex 就不会把同名或翻拍的作品认错。Plex 只认花括号加短横线的写法，例如「绝命毒师 (2008) {tmdb-1396}」，也可以写「{tvdb-81189}」或「{imdb-tt0903747}」。Emby 常用的「[tmdbid=1396]」与 Jellyfin 常用的「[tmdbid-1396]」Plex 都不认，目录按这两种规则命名时，在整理工具的重命名格式里改成 Plex 的写法，之后新入库的作品就按编号匹配。

Pro 的「元数据」页另有「按路径编号纠正匹配」，Emby 与 Jellyfin 的这两种写法也认，按路径里的编号纠正 Plex 认错的作品，见「元数据」一章。

STRM 默认由客户端直连 CDN，NAS 不转码。只有片源交给 Plex 转换时才会转码，例如勾选了「局域网交给 Plex 播放」的客户端放不了原文件，或客户端起播失败后改要服务器转换。转码时 Plex 有核显就用核显，没有就全靠 CPU。低功耗的 NAS 用 CPU 转码 4K 片源常常跟不上，表现为播几秒、卡几秒。

1. 1在主机上执行 ls /dev/dri，看到 renderD128 之类的设备说明核显可用。
2. 2在 compose.yaml 里取消 devices 那几行的注释，把 /dev/dri 映射进容器，然后执行 docker compose up -d。
3. 3在 Plex 设置的「转码器」里打开硬件加速的选项，也可以在管理面板「诊断」页的「硬件转码」点「打开」。
4. 4播放一个需要转码的片源，在管理面板的「仪表板」查看这次播放，传输一项写着「Plex 在 NAS 上用硬件转码」就是在用核显。

「诊断」页的「硬件转码」写明 Plex 转码能不能用硬件加速。缺 Plex Pass、容器里没有可用的显卡，或 Plex 设置里没有打开硬件加速时分别说明，只是没打开时可以直接点「打开」。播放时转码跟不上，「仪表板」的卡片上会提示「NAS 转码跟不上播放，画面会时播时停」，用的是 CPU 时附上这一节的链接。

• 硬件转码需要 Plex Pass，这是 Plex 的规则。
• 从原来的 Plex 换过来时，原 compose 里的 devices 照样保留即可。
• ls /dev/dri 没有输出时，主机上没有可用的核显驱动，先在 NAS 系统里确认核显已启用。
• NVIDIA 显卡的映射方式不同，按 Plex 官方的说明配置。

host 与 bridge 网络都可以用，用 bridge 网络时照常映射 32400 端口。全新部署时在管理面板里认领服务器，两种网络都一样，见「全新部署时认领服务器」。

Cirvel 判断播放设备在家还是在外，依据的是 Plex 设置「网络」里的「局域网络」。留空时只认服务器物理网卡所在的子网，容器网桥与 VPN 不算，经局域网里的反向代理转来的外网设备也按在外处理，拿不准时按在外处理。

用域名、反向代理或内网穿透访问 Plex 时，上游地址要填运行 Cirvel 的主机的局域网地址，例如 http://192.168.1.10:32400。

上游填错时，在 Plex Web 的服务器设置里点「Cirvel」会弹出一段说明，提示把上游改成主机的局域网地址。

请求经过多层转发时，例如先用 frp 等内网穿透把服务器连到 VPS，再由 VPS 上的反向代理对外提供域名，要看的是最后进入主机的那一层。VPS 上的反向代理照常指向 frp 在 VPS 上开放的端口，主机上 frpc 的 localIP 要填主机的局域网地址，不要填 127.0.0.1。其他穿透工具、隧道与旁路由转发同理，凡是在主机这一侧把请求交给 Plex 的那一层，目标都填主机的局域网地址。

最后这一层指向了 127.0.0.1 时，Plex 客户端的播放不经过 Cirvel。Cirvel 发现这种情况后，在概览顶部与「诊断」页的「网络连接」里提示「部分播放没有经过 Cirvel」，并写着最近一次的时间、次数与来自哪种客户端。

这不是安全问题

客户端仍然要登录 Plex 账号才能访问服务器，只是 STRM 直连等 Cirvel 的能力对这些播放不生效，在外播放可能一直转圈。

改法

找到最后把请求交给服务器的那一层，把目标从 127.0.0.1 改成运行 Cirvel 的主机的局域网地址与映射出来的端口，例如 http://192.168.1.10:32400，按上文多层转发的说明逐层核对。

提示何时消失

24 小时内没有新的这类播放时自动消失，也可以点「知道了」关掉。之后再出现新的这类播放时会重新提示。

在外访问用反向代理域名。按上文配置反向代理，再在 Plex 设置「网络」的「自定义服务器访问 URL」里填上这个地址并写明端口，例如 https://plex.example.com:443，端口照实写。Plex 的远程访问与中转都不再推荐使用，填好之后把两者关闭，见下一节「推荐的 Plex 网络设置」。

经 Plex 中转连接的客户端里 STRM 无法播放，Cirvel 的其它能力也不生效。填好自定义服务器访问 URL 之后，在「诊断」页的「Plex 中转」点「关闭中转」即可。还没填好之前不要关闭，否则在外完全连不上。

Plex 客户端从 plex.tv 拿到服务器公布的全部地址后逐个去试，每个连不上的地址都要白等一阵，访问 plex.tv 不稳定时更明显。推荐在 Plex 设置的「网络」里按下面设置，在外经自己的反向代理域名访问，客户端就只会尝试局域网的 plex.direct 地址与这个域名。

自定义服务器访问 URL

填反向代理的域名，写成 https://域名:端口，例如 https://域名:443，端口照实写。在外就经这个地址访问，反向代理的配置见上文「反向代理与内网穿透」。

远程访问

关闭。Plex 的远程访问与中转都不再推荐使用。关闭后 Plex 仍公布自定义服务器访问 URL 与局域网地址，只是不再公布公网 IP，也不再注册中转。

启用中转

关闭。

加密连接

选「优先」。

首选网络接口

容器用 host 网络时，选持有局域网地址的网卡，不留自动。留自动时 Plex 会把容器网桥这类局域网设备连不到的地址也公布出去。

放行 plex.direct

在路由器的 DNS 与代理规则里放行，见「常见问题排查」一章的「plex.direct 解析不出来」。

启用本地网络发现功能（GDM）

保持开启。容器用 host 网络时才生效。

先填好自定义服务器访问 URL，再关闭远程访问与中转。管理面板「诊断」页的「Plex 网络设置」会按这台服务器的实际情况逐项检查，可以逐项修改或一键优化，见「开始使用」一章的「Plex 网络设置与一键优化」。

Cirvel 与 Plex 共用容器的代理设置。访问 plex.tv、许可服务、TMDB 与 Wikidata，以及校验 STRM 时读取网盘，都按 HTTPS_PROXY 与 HTTP_PROXY 走，https 地址用前者，http 地址用后者，大小写都认。

    environment:
      - HTTP_PROXY=http://192.168.1.2:7890
      - HTTPS_PROXY=http://192.168.1.2:7890
      - NO_PROXY=localhost,127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16

局域网地址始终直连

私有 IP、容器名（例如 STRM 里写的 http://strm-server:8080）以及 .local、.lan 结尾的主机名都不经过代理，NO_PROXY 里不写也一样。

NO_PROXY 的写法

用逗号分隔，可以写网段、IP 与域名，域名同时包含它的子域。

改了之后重建容器

代理设置在容器启动时读取，修改后重建容器才生效。因连不上而暂停的后台分析随之解除。

内置 FFmpeg 只认小写变量

分析 STRM、生成片头片尾与进度条预览时读网盘只看小写的 http_proxy，不看上面的大写变量，网盘必须经代理时见「常见问题排查」一章的「网盘要经代理才能访问」。

1. 1先备份 /config 对应的目录。
2. 2拉取新镜像并重建容器。
3. 3打开管理面板，在顶栏的帮助菜单里确认当前版本。

docker compose pull
docker compose up -d

有新版本时，管理面板的顶栏会提示。版本内容见官网的发布记录，也可以订阅 Telegram 频道获取公告。