ChineseSubFinder Docker 部署与使用指南

项目概述

ChineseSubFinder 是一款自动为中英文字幕下载工具，能够自动为你的影视库匹配和下载中文字幕。它支持多种媒体服务器平台，包括 Emby、Jellyfin、Plex 等，通过 Docker 容器化部署可以方便地在各种环境中运行。

部署前提条件

在使用 ChineseSubFinder 前，需要确保你的视频文件已经通过以下媒体服务器软件进行了削刮（Scraping）：

• Emby
• Jellyfin
• Plex
• tinyMediaManager

重要提示：未经削刮的视频文件，特别是连续剧，可能无法正确下载字幕。同时，正确的目录结构对于字幕下载也至关重要。

镜像版本选择

ChineseSubFinder 提供两种 Docker 镜像版本：

1. 完整版 (latest标签)

• 基于 Ubuntu 系统
• 包含 Chrome、Xorg、ImageMagick 等完整依赖
• 支持所有字幕源（包括 subhd、zimuku）
• 仅支持 linux/amd64 和 linux/arm64 架构
• 不支持基于 musl-libc 的系统（如 OpenWRT、Alpine）

2. 轻量版 (latest-lite标签)

• 基于 Alpine 系统
• 不包含 Chrome 等大型依赖
• 不支持 subhd 和 zimuku 字幕源
• 支持更多架构：linux/amd64、linux/arm64、linux/386、linux/arm/v7
• 兼容 glibc 和 musl-libc 系统

部署教程

通过 Docker CLI 部署

完整版部署命令

docker run -d \
    -v /path/to/config:/config \
    -v /path/to/media:/media \
    -v /path/to/browser:/root/.cache/rod/browser \
    -e PUID=1026 \
    -e PGID=100 \
    -e PERMS=true \
    -e TZ=Asia/Shanghai \
    -e UMASK=022 \
    -p 19035:19035 \
    -p 19037:19037 \
    --name chinesesubfinder \
    --hostname chinesesubfinder \
    --log-driver "json-file" \
    --log-opt "max-size=100m" \
    ChineseSubFinder/ChineseSubFinder

轻量版部署命令

docker run -d \
    -v /path/to/config:/config \
    -v /path/to/media:/media \
    -e PUID=1026 \
    -e PGID=100 \
    -e PERMS=true \
    -e TZ=Asia/Shanghai \
    -e UMASK=022 \
    -p 19035:19035 \
    -p 19037:19037 \
    --name chinesesubfinder \
    --hostname chinesesubfinder \
    --log-driver "json-file" \
    --log-opt "max-size=100m" \
    ChineseSubFinder/ChineseSubFinder:latest-lite

通过 Docker Compose 部署

完整版 docker-compose.yml

version: "3"
services:
  chinesesubfinder:
    image: ChineseSubFinder/ChineseSubFinder:latest
    volumes:
      - ./config:/config
      - ./media:/media
      - ./browser:/root/.cache/rod/browser
    environment:
      - PUID=1026
      - PGID=100
      - PERMS=true
      - TZ=Asia/Shanghai
      - UMASK=022
    restart: always
    network_mode: bridge
    hostname: chinesesubfinder
    container_name: chinesesubfinder
    ports:
      - 19035:19035
      - 19037:19037
    logging:
        driver: "json-file"
        options:
          max-size: "100m"

轻量版 docker-compose.yml

version: "3"
services:
  chinesesubfinder:
    image: ChineseSubFinder/ChineseSubFinder:latest-lite
    volumes:
      - ./config:/config
      - ./media:/media
    environment:
      - PUID=1026
      - PGID=100
      - PERMS=true
      - TZ=Asia/Shanghai
      - UMASK=022
    restart: always
    network_mode: bridge
    hostname: chinesesubfinder
    container_name: chinesesubfinder
    ports:
      - 19035:19035
      - 19037:19037
    logging:
        driver: "json-file"
        options:
          max-size: "100m"

配置说明

关键参数解析

1. 卷挂载：

   • /config：存储配置文件和日志
   • /media：媒体文件目录（必须映射）
   • /root/.cache/rod/browser：Chrome 浏览器缓存（仅完整版需要）

2. 环境变量：

   • PUID/PGID：设置容器运行的用户/组ID，应与媒体文件所有者一致
   • PERMS：是否重置/media目录权限（建议true）
   • TZ：时区设置（Asia/Shanghai）
   • UMASK：文件权限掩码（022）

3. 端口映射：

   • 19035：Web管理界面端口
   • 19037：视频列表图片读取端口（不建议暴露到外网）

权限管理建议

为确保 ChineseSubFinder 能正常读写媒体文件，建议：

1. 将 PUID/PGID 设置为与媒体服务器相同的值
2. 检查媒体目录权限，确保容器用户有读写权限
3. 可通过进入容器执行 ls -l /media 验证权限设置

使用指南

1. 部署完成后，访问 http://<服务器IP>:19035 进入Web管理界面
2. 首次使用需要进行基本配置：
   • 设置媒体目录（应与挂载的/media目录一致）
   • 配置字幕源和下载策略
   • 设置计划任务
3. 对于轻量版用户，建议开启"实验室->共享字幕"功能以弥补字幕源不足

常见问题

1. 为什么连续剧无法下载字幕？

   • 确保视频已通过媒体服务器削刮
   • 检查目录结构是否符合要求

2. 如何判断该使用哪个镜像版本？

   • 需要完整字幕源支持 → 选择完整版
   • 资源有限或特殊架构 → 选择轻量版

3. 容器日志过大怎么办？

   • 通过 --log-opt "max-size=100m" 参数限制日志大小
   • 可调整 max-size 值为适合的大小

最佳实践

1. 建议将媒体目录按标准结构组织：

   • 电影：/media/movies/电影名 (年份)/电影名 (年份).mkv
   • 剧集：/media/tvshows/剧集名 (年份)/Season XX/剧集名 SXXEXX.mkv

2. 对于多媒体目录的情况，可以添加多个 -v 参数映射不同目录

3. 定期检查日志，确保字幕下载任务正常运行

通过以上配置，ChineseSubFinder 将能自动为你的媒体库匹配和下载高质量的中文字幕，极大提升观影体验。