用 Docker 安装

Kryspal Media 由两个容器组成：服务器和它的 PostgreSQL 数据库，用一个 Docker Compose 文件启动。镜像支持 x86（amd64）与 ARM（arm64）。

开始之前#

• 已安装 Docker 与 Docker Compose v2。
• 知道媒体文件在主机上的位置（例如 /volume1/movies）。

用一条命令安装（Linux 主机或 VPS）#

适合已经装好 Docker 的 Linux 主机或 VPS。脚本会写出 compose 文件、启动，并等到服务器健康。把 /srv/media 换成放电影和剧集的文件夹：

curl -fsSL https://media.kryspal.net/install.sh | bash -s -- --media /srv/media

再运行一次同一条命令就是升级，见升级与备份。

• 先看脚本。 先下载，看过内容，再运行：

  curl -fsSL https://media.kryspal.net/install.sh -o install.sh
  less install.sh
  bash install.sh --media /srv/media
  

• 多个媒体文件夹。 重复写 --media，例如 --media /volume1/movies --media /volume2/tv。只有一个文件夹时挂载在 /media；有多个时，每个挂载在 /media 加完整主机路径，例如 /media/volume1/movies。想沿用其他容器路径，见媒体放在 /media 以外的位置。

  curl -fsSL https://media.kryspal.net/install.sh | bash -s -- \
    --media /volume1/movies \
    --media /volume2/tv
  

升级时会忽略 --media；要改文件夹，请编辑 compose.yaml。 - 东西放在哪里。 compose 文件和一个很小的 .env 放在 /opt/kryspal-media（用 --dir 可以改）。数据放在 Docker 卷 kryspal-media_data、kryspal-media_pgdata 和 kryspal-media_db。 - 没有装 Docker 时， 脚本会停下来并告诉你去哪里取得。加上 --install-docker 可以让它改用 Docker 官方的安装脚本；离线的主机加 --no-pull。 - 升级做了什么。 它会拉取最新的镜像并重建容器，不会删除你的数据。你的 compose.yaml 不会被改动；新版本如果改了这个文件，新的会另存在旁边，名为 compose.yaml.new。 - 开放到外网。 这个端口说的是明文 HTTP，请在前面放一个带 HTTPS 的反向代理，不要直接转发 5797 端口。见远程访问。 - NAS 不要用这个方式。 用命令行建立的项目，在 NAS 的容器管理器里看不到，NAS 请用 Docker Compose。

在 NAS 上用 Docker Compose 安装#

群晖、威联通等 NAS 请用这种方式：在容器管理器里贴上 compose YAML 来创建项目。其他装了 Docker 的主机也可以用。

1. 新建一个文件夹，在里面创建 compose.yaml，内容如下（在 NAS 的容器管理器里，贴在它要求填写 compose 文件的地方）：

   services:
     server:
       image: kryspal/kryspalmedia:latest
       restart: unless-stopped
       stop_grace_period: 60s
       ports:
         - "5797:5797" # LAN
         - "5798:5798" # WAN
         # - "7359:7359/udp" # discovery
       environment:
         EXTERNAL_HTTP_ADDR: ":5798" # WAN
       volumes:
         - /path/to/media:/media
         # 2+ folders: use these instead
         # - /mnt/movies:/media/mnt/movies
         # - /mnt/tv:/media/mnt/tv
         - data:/var/lib/mediaserver
         - db:/var/lib/kryspal-db:ro
       depends_on:
         - postgres
     postgres:
       image: kryspal/kryspalmedia-postgres:16
       restart: unless-stopped
       stop_grace_period: 60s
       volumes:
         - pgdata:/var/lib/postgresql/data
         - db:/var/lib/kryspal-db
   volumes:
     data:
     pgdata:
     db:
   

2. 把 /path/to/media 换成主机上的媒体文件夹。有多个文件夹就每个加一行 volumes，挂在 /media 加完整主机路径之下，例如 - /mnt/tv:/media/mnt/tv。挂在 /media 之外的文件夹会被服务器拒绝。

3. 启动（在 NAS 的容器管理器里，创建并启动项目）：

   docker compose up -d
   

4. 打开 http://<主机>:5797，按设置向导创建第一位管理员，见初次设置。管理后台在 http://<主机>:5797/web/。

5. 在播放器（Infuse 等）里填服务器地址 http://<主机>:5797 和一位成员的名称与密码。

带文件 ACL 的 NAS（绿联、群晖等）。 服务器在容器里以用户 mediaserver（uid 和 gid 都是 1000）运行。在这类系统上，ls 看到的权限并不是全部：真正决定能否读取的是 NAS 自己的 ACL，而它常常授权给 admin 之类的组，不是 gid 1000。症状是「library root unavailable: … permission denied」（媒体库显示离线），但文件夹看起来明明对所有人开放。一键安装脚本会替你检查：它用一个临时的只读容器逐个试读媒体文件夹，读不了时，把你的用户所在的、第一个能读的组作为 group_add 写进 compose.yaml。用自己写的 compose 时，把能读你媒体文件的那个组加到 server 服务里，再运行一次 docker compose up -d：

    group_add:
      - "10"   # 能读这些文件的用户的 gid，用 `id -g` 查看

想让媒体文件夹完全只读，在这一行末尾加 :ro；字幕下载、NFO 与图片写回和删除文件就无法使用。

升级：运行 docker compose pull 和 docker compose up -d。数据库结构会在新版第一次启动时自动升级，大片库可能需要一两分钟。详见升级与备份。

端口、文件夹与数据#

自动发现。 Emby、Jellyfin 也用 7359/udp，所以 compose 文件里这一行默认是注释。install.sh 在端口空着时会自动打开。

想让播放器自动找到服务器：

1. 确认没有 Emby 或 Jellyfin 占用 7359/udp。
2. 去掉 compose 文件里 7359:7359/udp 那一行前面的 #。
3. 重新创建容器。

播放器也可以直接输入服务器地址。

数据库不对外开放，密码也是自动生成的。

可以自行添加的内容#

• 外网访问。 compose 文件已经发布 5798 端口（标注 WAN），并设置了 EXTERNAL_HTTP_ADDR: ":5798"。路由器只转发 5798。从这个端口进来的连接一律算外网。不用 8920，是因为同一台机器上它会和 Emby 的 HTTPS 端口冲突。
• NAS 的文件权限。 如果你的 NAS 使用文件 ACL（例如群晖），在服务器上加 user: "<uid>:<gid>"，填媒体文件所有者的 id -u 与 id -g。
• 更大的数据库内存设置。 内存充足的主机可以给 postgres 服务加 command:，调高 PostgreSQL 的内存参数。

使用自己的 PostgreSQL#

需要 PostgreSQL 16 或更新版本，并安装 pg_bigm 扩展（中文搜索要用）。为 Kryspal Media 新建一个数据库和用户，删掉 postgres 服务、pgdata 与 db 卷，以及服务器的 depends_on 和 db 卷那一行，再给服务器加一个 environment: 段，把 DATABASE_URL 设成你自己的连接字符串，例如 postgres://user:password@db.example:5432/kryspal?sslmode=disable。服务器第一次启动时自己建表；需要由权限足够的账号事先执行 CREATE EXTENSION pg_bigm。

自动化部署#

如果用脚本部署、不想走向导，在服务器的 environment: 段里加上 INITIAL_ADMIN_PASSWORD。数据库里还没有任何成员时，服务器会在启动时直接创建管理员，设置向导会被跳过；不设置就走向导。

服务器反复重启，日志里有「the data directory does not match this database」#

启动时，服务器会核对 data 卷里的服务器身份与密钥，和数据库里记录的是不是同一份。对不上就拒绝启动，容器会反复重启，日志里是这一行：the data directory does not match this database。

1. 先确认 data 卷挂好了。 最常见的原因是 NAS 开机后，外接硬盘或网络磁盘比容器晚挂上，服务器看到的是一个空目录。等它挂好后重启容器就行：docker compose restart server。
2. 只有刻意更换了密钥或数据目录时，才需要接受这个变化：在服务器的 environment: 段加上 ACCEPT_DATA_DIR_CHANGE: "true"，启动一次。成功启动后，把这一行拿掉。

接下来#

• 初次设置
• 升级与备份