常见问题

1. 如何升级到新版本

正常升级只需保留原来的/workspace挂载目录，容器重建不会影响其中的数据。升级前仍建议先备份/workspace，尤其是/workspace/database下的数据库文件，方便在异常情况下回滚。

Docker CLI 手动升级

bash

# 拉取最新镜像
docker pull kaloscope/kaloscope:latest

# 停止并删除旧容器
docker stop kaloscope
docker rm kaloscope

# 用原来的启动参数重新创建容器
docker run -d \
  --name kaloscope \
  ...

# 可选：清理旧版本镜像释放空间
docker image prune -f

Docker Compose 手动升级

bash

docker compose pull       # 拉取最新镜像
docker compose up -d      # 重建并启动容器
docker image prune -f     # 可选：清理旧版本镜像释放空间

Watchtower 自动更新

使用 Watchtower 实现镜像自动更新，无需手动操作。在docker-compose.yml中添加以下服务：

yaml

services:
  watchtower:
    image: containrrr/watchtower:latest
    container_name: watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - TZ=Asia/Shanghai
      - WATCHTOWER_CLEANUP=true           # 更新后删除旧镜像
      - WATCHTOWER_POLL_INTERVAL=86400    # 检查间隔（秒）
      - WATCHTOWER_LABEL_ENABLE=true      # 仅更新带有启用标签的容器
      - DOCKER_API_VERSION=1.44           # 可选：指定 Docker API 版本
    restart: unless-stopped

然后在 kaloscope 服务上添加 label 标记需要自动更新：

yaml

kaloscope:
  labels:
    - com.centurylinklabs.watchtower.enable=true

完成后执行docker compose up -d即可。按照当前配置，Watchtower 会每 24 小时检查一次新版本，发现更新后会自动拉取并重启容器。

如果不希望自动更新而只想接收通知，可将WATCHTOWER_LABEL_ENABLE替换为WATCHTOWER_MONITOR_ONLY=true，并配置邮件或 Webhook 通知。

2. 第三方工作流是否安全

不一定。工作流可包含任意 HTTP 请求和 Python 脚本，导入前请自行审查其行为。

3. 和 Jellyfin / Emby 有什么区别

Jellyfin 等工具专注于媒体播放与流媒体分发。Kaloscope 的差异化在于通过可编辑工作流接入任意资源站，自动完成搜索、下载、整理全流程。两者定位不同，可搭配使用。

4. 连接宿主机下载器时，下载路径不一致

当 Kaloscope 以容器方式运行，而下载器部署在宿主机时，两边看到的下载目录路径可能不同，从而导致下载失败。例如容器/downloads对应宿主机/data/downloads。

该问题可以通过固定下载路径来解决。以 qBittorrent 为例，配置文件中有两处savepath，分别对应磁力链接和种子文件的下载路径：

yaml

methods:
  add_link:
    form:
      savepath: '{{dir}}' # 改为宿主机路径，如 /data/downloads
      urls: '{{link}}'
  add_torrent:
    form:
      savepath: '{{dir}}' # 同样改为宿主机路径
      torrents: '{{torrent}}'

将这两处配置中的{{dir}}替换为宿主机中的绝对路径，下载器就能直接使用宿主机路径进行下载。

5. 部署后无法通过 http://<宿主机IP>:8000 访问

如果确认容器已经正常启动，但访问http://<宿主机IP>:8000无法打开页面，可以检查是否开启了AUTO_TLS=true。开启该选项后，服务会使用 HTTPS，此时需要通过https://<宿主机IP>:8000访问。

如果没有 PWA 安装需求，一般不需要开启AUTO_TLS。

6. 流程模板处导入数据源失败怎么办

流程模板的数据源托管在 GitHub，直连不稳定时可能会请求失败。可以先重试几次，通常可以成功；如果配置了代理，建议在「网络设置」页面将https://*github.com绑定到代理，这样会更稳定。

如果仍然无法成功，也可以通过下载模板仓库源码来手动导入。可前往模板仓库的 GitHub 页面，例如 kaloscope/workflows，点击「Code」->「Download ZIP」下载源码压缩包。下载完成后，在「流程定义」页面点击右上角导入按钮，选择该 ZIP 文件即可导入。

工作流

资源搜索

下载管理

媒体库

常见问题

常见问题 ​

常见问题