🚀 使用 Docker Compose 部署 ChineseSubFinder

ChineseSubFinder 是一款开源自动化工具，用于为电影和剧集下载中文字幕。该项目采用 Go 语言编写，支持通过 Docker 容器化部署，能与 Emby、Jellyfin、Plex 等媒体服务器集成，并支持 Sonarr、Radarr 等自动化媒体管理工具。其核心价值在于自动化管理字幕，节省手动查找时间。

📦 项目简介

ChineseSubFinder 旨在自动化解决中文字幕下载问题。它支持从多个字幕网站和接口下载字幕，并能很好地融入家庭媒体库的自动化工作流。

主要特性： - 自动化字幕下载：自动监控指定目录，为新视频文件查找并下载中文字幕。 - 多字幕源支持：支持多种字幕源。 - 媒体服务器集成：支持与 Emby、Jellyfin、Plex 等媒体服务器集成。 - 自动化工具联动：可与 Sonarr、Radarr 等自动化媒体管理工具配合使用。 - 用户友好界面：提供 Web 管理界面进行配置和手动操作。 - 定时任务与实时监控：支持定时运行和实时监控文件系统变化。 - 字幕智能匹配：通过哈希值及文件名智能匹配视频与字幕。

⚙️ 部署前准备

环境要求
- 已安装 Docker 和 Docker Compose。
- 系统内存：建议 1GB 以上。
- 磁盘空间：至少 1GB 可用空间。
环境检查 终端执行以下命令确认 Docker 环境正常： bash docker --version docker-compose --version 若未安装，可使用国内服务器一键安装脚本： bash bash <(curl -sSL https://xuanyuan.cloud/docker.sh)
创建项目目录 建议创建独立目录管理 ChineseSubFinder： bash mkdir -p /opt/docker/chinesesubfinder cd /opt/docker/chinesesubfinder

🛠️ 配置 Docker Compose

基于你提供的配置，创建 docker-compose.yml 文件。以下是针对你遇到的目录映射问题的修正版本：

networks:
  videos:
    external: true # 使用已存在的外部网络，便于其他容器通信# 使用已创建的外部网络（需提前执行 docker network create videos）


#version: '3.8'
services:
  chinesesubfinder:
    image: allanpk716/chinesesubfinder:latest
    volumes:
      # 1. 配置与日志目录：主机 ./config 映射到容器 /config（保存设置、日志）
      - ./config:/config  # 冒号左边请修改为你想在主机上保存配置、日志等文件的路径
      #- ./video:/media

      # 2. 媒体目录：需映射到容器 /media 下的子目录（仅支持 /media 开头路径，否则权限报错）
      - /mnt/10t/videos/downloads:/media/1 # 媒体目录1（替换为你的影视路径）
      - /mnt/10t/videos/Link:/media/2      # 媒体目录2（替换为你的影视路径）
      - /mnt/10t/videos/like:/media/3      # 媒体目录3（替换为你的影视路径）
      #- /mnt/10t/videos/downloads:/media/video1  # 修正：使用 video1 格式
      #- /mnt/10t/videos/Link:/media/video2       # 修正：使用 video2 格式  
      #- /mnt/10t/videos/like:/media/video3       # 修正：使用 video3 格式

#报错，只允许/media的目录：请修改相关配置后继续
#软件运行在Docker中，请将基础设置中的电影和电视剧目录修改为 /media 下的目录，否则可能会因为权限问题导致无法正确的加载媒体库
      #- ./video/Movie:/media/video1   #电影
      #- ./video/TV-Play:/media/video2 #电视剧
      #- ./video/Anime:/media/video3   #动漫缩写
      #- ./video/link/movie:/media/link/movie    # 请修改为你的媒体目录，冒号右边可以改成你方便记忆的目录，多个媒体目录需要分别映射进来
      #- ./video/link/电视剧:/media/link/tv
      #- ./video/mv/link/番剧:/media/link/fanju
      #- ./video/mv/movie:/media/movie
      #- ./video/mv/番剧:/media/fanju
      #- ./video/mv/电视剧:/media/tv

      # 3. Chrome 缓存目录：避免容器重启后重复下载 Chrome（减少启动时间）
      - ./browser:/root/.cache/rod/browser    # 容器重启后无需再次下载 chrome，除非 go-rod 更新
    environment:
      - PUID=0          # 运行用户 ID（0 为 root 权限，避免权限问题，新手推荐默认）
      - PGID=0          # 运行用户组 ID（与 PUID 保持一致）
      - PERMS=true      # 自动修复 /media 目录权限（防止因权限导致扫描失败，建议开启）
      - TZ=Asia/Shanghai  # 时区（默认上海，无需修改）
      - UMASK=022       # 权限掩码（默认即可，控制新文件权限）
    restart: always     # 容器退出后自动重启（开机自启）
    #network_mode: bridge
    hostname: chinesesubfinder  # 容器主机名（默认即可）
    container_name: chinesesubfinder
    ports:
      - 5003:19035  # 从0.20.0版本开始，通过webui来设置 # WebUI 端口：主机 5003 → 容器 19035（用于访问管理界面）
      - 50030:19037  # webui 的视频列表读取图片用，务必设置不要暴露到外网 
      # 图片加载端口：主机 50030 → 容器 19037（禁止暴露到外网！）
      #- 8100:8100
      #- 8100-8105:8100-8105/tcp
      #- 8100-8105:8100-8105/udp

    logging:
      # 日志配置：限制单文件大小 100M，避免日志占满磁盘
        driver: "json-file"
        options:
          max-size: "100m" # 限制docker控制台日志大小，可自行调整



    #privileged: true
    #特权:真
    #restart: 'unless-stopped'
    networks:
     # 加入外部网络 videos，可与其他媒体服务（如 Jellyfin）通信
      videos:
        ipv4_address: 10.1.1.2  # 固定容器在 videos 网络中的 IP（默认即可，无需修改）
        #ipv6_address: 2001:3984:3989::10



#账密，密码六位数，不能有特殊符号。

关键配置说明：

配置项	说明与建议
`volumes`	媒体目录映射必须使用 `/media/video1`、`/media/video2` 格式，这是你遇到报错的原因。ChineseSubFinder 容器要求媒体路径必须位于 `/media` 下。
`environment`	`PUID=0` 和 `PGID=0` 以 root 权限运行，避免权限问题。`PERMS=true` 可自动修复挂载目录权限。
`ports`	`5003:19035` 用于访问 Web 界面，`50030:19037` 用于内部图片访问。
`networks`	使用外部网络 `videos` 便于与其他容器通信。
networks.videos.external	必须先创建 `videos` 网络（`docker network create videos`），否则启动报错。

注意：媒体目录映射必须遵循 /media/videoX 的命名规则，否则会导致 ChineseSubFinder 无法正确识别媒体文件。

🚀 启动与验证

启动服务 在 docker-compose.yml 所在目录执行： bash docker-compose up -d
检查服务状态 bash docker-compose ps 确认容器状态为 Up。
查看日志 如遇问题，查看日志输出： bash docker-compose logs -f chinesesubfinder
访问 Web 界面 浏览器访问 http://你的服务器IP:5003，使用默认账号 admin 和密码 admin 登录。

⚙️ 基础配置与使用

初始化设置
- 首次登录后立即修改管理员密码。
- 按照引导设置电影目录和电视剧目录：
- 电影目录：/media/video1 (对应 /mnt/10t/videos/downloads)
- 电视剧目录：/media/video2 (对应 /mnt/10t/videos/Link)
- 配置媒体服务器（如 Emby、Jellyfin）以实现更佳集成。
字幕源配置
- 在 "实验室功能" 中开启 "共享字幕" 以使用额外的字幕源。
- 可配置第三方字幕下载服务，如 SubtitleBest。
任务设置
- 定时任务：建议设置每天执行一次的定时任务。
- 立即运行：完成配置后点击"立即运行"进行首次字幕扫描。

🔒 维护与管理

服务管理：
停止：docker-compose down
重启：docker-compose restart
更新：docker-compose pull && docker-compose up -d
数据备份：
定期备份 ./config 目录，包含所有配置和数据库。
备份 docker-compose.yml 文件。
日志管理：配置的日志驱动限制单个日志文件最大 100MB，防止磁盘空间被占满。

🐛 常见问题排查

问题现象	可能原因与解决方法
媒体目录无法访问	检查目录映射是否使用 `/media/videoX` 格式，确保宿主机目录存在且有正确权限。
字幕下载失败	检查网络连接，确认字幕源配置正确，查看日志获取具体错误信息。
Web 界面无法访问	确认防火墙开放了 5003 端口，检查容器是否正常运行。
权限错误	确保 `PUID=0` 和 `PGID=0` 设置，或设置为有权限访问媒体目录的用户ID。

提示：ChineseSubFinder 对电影和连续剧的目录结构有一定要求，请确保媒体文件组织清晰（如按电影、电视剧分类存放），以便工具能正确识别。

通过以上步骤，你应该能成功部署并使用 ChineseSubFinder，享受自动化字幕下载的便利。如有问题，可参考项目官方文档或社区讨论。