【优质帖】本地AV刮削封面墙GitHub项目分享

项目地址：<https://github.com/Solr159/JavBoss&gt; ｜ 当前版本：v2.0.1（2026-08-16）

最近在折腾本地影音库管理，试了下 JavBoss——一个用 Go 写的本地 JAV/视频刮削、管理与播放一站式工具。它主打「开箱即用」，支持命令行一键安装和 Docker 部署，只需把目录丢进去就能自动生成封面、识别番号、抓元数据、还能直接播放。踩了点坑之后把完整部署过程梳理出来，给想自部署的朋友一份能照着敲的参考。

一、项目简介与核心功能

JavBoss 的定位很清晰：本地优先的私人影音媒体库，不依赖任何第三方云服务，所有数据都在你自己的机器上。

核心能力：

• 自动扫描与指纹：扫描本地视频目录，生成封面截图与视频指纹，零侵入（不改动你的视频目录）。
• 番号识别与刮削：从文件名提取番号（如 IPX-633）识别 JAV，自动抓取标题、发行时间、演员、标签、厂商、系列；多数据源（javbus、avmoo、theporndb 等），支持手动补全。
• 双模式管理：视频库 / JAV 库双模式，支持排序、筛选、随机浏览、收藏夹。
• 内置播放器：内置 mpv（搭配 ModernZ OSC），支持截图、进度预览；桌面端可直接调本机 mpv。
• 响应式 Web UI：普通视频库 / JAV 库 / 女优视角三种视图，低心智负担。

技术栈（来自官方 DEVELOPMENT.md）：

• 后端：Go + Gin + GORM + SQLite
• 前端：React + Vite + Tailwind + Zustand
• 媒体探测：ffprobe；缩略图截图：macOS 用 ffmpeg，其他平台用 mpv；播放与手动截图：mpv

二、部署前的环境准备与依赖要求

按你想要的部署方式准备，别一股脑全装：

通用前提：

• 联网：首次刮削需要访问外网（中国大陆需代理/梯子）；已入库的数据离线可用。
• 端口：默认 8655（Docker 容器内实际监听 17654，映射出来是 8655）。
• 默认密码：admin，上线后务必改。

三、详细部署步骤

方式一：Docker 部署（推荐服务器 / NAS）

这是最省心、最适合「上线」的方式。官方给出的 docker-compose.yaml 如下：

services:
  javboss:
    image: ghcr.io/solr159/javboss:latest
    container_name: javboss
    ports:
      - "8655:17654"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - ./data:/app/data
      - /:/host:ro
    restart: unless-stopped

启动：

docker compose up -d

访问 http://<主机IP>:8655（同局域网用主机 IP 即可）。升级：

docker compose pull && docker compose up -d

几个关键点：

• 容器内进程监听 17654，所以端口映射必须是 8655:17654，写反或写成 8655:8655 会直接连不上。
• ./data:/app/data 是持久化目录（数据库、封面、截图），升级时别删。
• /:/host:ro 是 Docker 模式下「宿主机路径前缀」映射所需，让容器内访问到你在 UI 里填的宿主机真实路径。
• Docker 模式下播放走浏览器，不调用本机 mpv，添加媒体目录时填宿主机真实路径（如 /mnt/disk1/videos）。

方式二：一键脚本安装（桌面 / 本机）

Linux / macOS 一条命令搞定：

curl -fsSL https://raw.githubusercontent.com/Solr159/JavBoss/main/scripts/install.sh | bash

Windows PowerShell：

irm https://raw.githubusercontent.com/Solr159/JavBoss/main/scripts/install.ps1 | iex

脚本实际做了什么（读了下 install.sh 源码）：

1. 检测 OS/架构，下载对应 v2.0.1 的 release 压缩包；
2. 解压到默认目录（Linux：~/.local/share/javboss，macOS：~/Applications/JavBoss）；
3. 创建 javboss 命令软链并写入 PATH profile；
4. 保护已有 config.toml 不被覆盖（升级友好）；
5. 启动服务并自动打开浏览器。

后续启动：Linux/macOS 终端直接敲 javboss；Windows 双击快捷方式。

方式三：从源码构建（开发者 / 自定义）

想改界面或加功能就走这条路：

git clone https://github.com/Solr159/JavBoss.git
cd JavBoss

# 1. 下载 ffprobe + mpv 等运行时依赖
./scripts/cli.sh download linux-x86_64

# 2. 前端依赖
cd web && npm install && cd ..

# 3. 开发模式（前后端热更新，开两个终端）
./scripts/cli.sh dev backend
./scripts/cli.sh dev frontend

生产构建（思路与官方 Dockerfile 一致，多阶段构建）：

# 前端产物
cd web && npm run build && cd ..

# 后端二进制（trimpath + 去符号，体积小）
go build -trimpath -ldflags="-s -w" -o javboss ./cmd/server

# 运行
./javboss

国内构建加速：Go 设 GOPROXY=https://goproxy.cn,direct；前端 npm 用 registry.npmmirror.com（官方 Dockerfile 已默认配好这两个镜像）。

配置说明

• config.toml：发布包根目录，可改 port（默认 8655）；Client 模式设 server_url = "http://192.168.1.100:8655" 连接远程 Server。
• Docker 模式环境变量（来自 Dockerfile）：JAVBOSS_CONTAINER=1、JAVBOSS_DISABLE_MPV=1、JAVBOSS_USE_FFMPEG_SCREENSHOTS=1、JAVBOSS_HOST_PATH_PREFIX=1、JAVBOSS_PROXY_HOST_GATEWAY=1 等，控制容器行为。
• 添加媒体目录：设置 → 目录管理，填宿主机真实路径；Docker 下填 /mnt/disk1/videos 这类挂载路径。

四、部署中遇到的关键问题及解决方案

下面这些是官方文档明确提示 + 实际部署容易踩的点，提前规避：

1. 端口映射写反 / 写错
容器内部是 17654，不是 8655。写成 8655:8655 必连不上。正确：8655:17654。
2. Docker 下播放没反应 / 目录不识别
Docker 模式用浏览器播放，不调本机 mpv；添加目录必须填宿主机真实路径，且依赖 /:/host:ro 挂载做路径前缀转译。别填容器内的相对路径。
3. 刮削一直转圈 / 抓不到元数据
刮削需访问外网，中国大陆需要代理。后端走 GOPROXY、前端走 npmmirror 只解决「构建」网络，不解决「刮削」网络。
4. NAS 硬盘狂转 / 寿命焦虑
默认扫描间隔是 1 分钟，NAS 上频繁扫盘伤硬盘。建议全局设置里调大间隔或关闭自动扫描。
5. 上线安全
默认密码 admin，部署到任何可达网络前，先去全局设置改密码。非 Docker 的局域网访问还需手动开启并重启。
6. 升级丢数据
升级只要保留 data/ 目录即可：Docker 已挂载 ./data；一键装会自动复制 data/ 到新版目录；源码构建自行备份 data/。install.sh 还会保护已有 config.toml 不被覆盖。
7. 换机器迁移
数据是 SQLite 单文件 + 封面/截图，全在 data/，整目录拷走就能迁移，零额外操作。

五、性能与功能亮点总结

• 零侵入 + 数据集中：视频目录原样不动，所有产物收在 data/，备份/迁移一个目录搞定。
• 多数据源刮削 + 手动补全：番号识别准，匹配不到可手动补，元数据完整度高。
• 内置 mpv + ModernZ OSC：桌面端播放体验好，截图/进度预览开箱即用。
• Go 单二进制 + distroless 镜像：官方最终镜像基于 gcr.io/distroless，体积小、启动快、攻击面小。
• 双模式架构：本地直连 / Client 模式连远程 Server，多端协同很灵活。
• 响应式 Web UI：三种视图切换，手机/平板也能管。

六、给读者的实践建议

• 服务器/NAS 直接上 Docker，别在服务器上折腾桌面端；restart: unless-stopped 省心。
• 端口与防火墙：只对外暴露 8655，绑定内网或前置反代 + 认证，别裸奔到公网。
• 改默认密码、关自动扫描（NAS）、定期备份 data/，这三件事上线前必做。
• 刮削走代理且别太频繁，避免被数据源限流。
• 大库首次扫描耐心等：封面/截图生成吃 CPU 和 IO，属于一次性开销。
• 想定制就 fork 改：前后端分离清晰，构建简单，改动成本低。
• 关注版本更新：项目迭代很快（v2.0.1 才刚发），新功能和新修复跟得紧。

如果你也在自部署媒体库，或者有更顺手的刮削/播放方案，欢迎在评论区聊聊——尤其想听听大家在大库性能调优和刮削数据源稳定性上的经验。

（本文部署命令与配置均对照 JavBoss 官方 README、DEVELOPMENT.md、Dockerfile 与 install.sh 验证，可复现。）