常见问题
按场景分组。找不到答案时：服务端看 docker logs -f jav-scribe， 客户端看看板行级状态与 toast；接口层面见 API 参考。
部署与环境
服务端没任务时是不是也一直占着显卡？
不是。转译模型非常驻：任务真正开始处理时才拉起模型进程（每实例约 4–6GB 显存）， 处理完进程退出、显存释放。空闲时服务端只占很少内存。处理中 nvidia-smi 看到显存 上升是正常的；「⚙ 服务设置 → 转译并发数」（1~4）决定最多同时几个模型实例。
显存占用满了但利用率不高，正常吗？
正常。ja→zh 翻译是「整模型载入 + 长序列解码」的负载形态：处理中显存占用恒定 （模型全量驻留），利用率波动大。想提高整批吞吐，在显存允许下调高「转译并发数」 （每实例 4~6GB）并开「批量推理」，单任务耗时基本不变。
显卡还在跑别的服务（数字人 / 推理 API 等），能共用吗？
能。按显存算账：JavScribe 处理时约 4~6GB/实例，空闲不占。只要并发实例数 × 6GB 加上其它服务常驻量小于总显存即可；显存不够时先降「转译并发数」回 1。
点「⚙ 服务设置」提示「无法读取服务端设置 / 该服务尚未设置 API Key」
服务端没设 JAVSCRIBE_API_KEY。在服务端 compose 的 environment 加 JAVSCRIBE_API_KEY: "<随机串>" 并重启容器，然后回到客户端：服务卡片编辑 → API Key 填同一个值 → 保存。不填 Key 也能看看板、提交生成任务， 但服务端 /config、/scan 等受保护接口需要 Key。client-v0.2.66 的 Web 工作台 本地扫描发生在客户端部署机，不依赖服务端 /scan；服务端 API Key 也不是全站鉴权。
扫描目录提示路径不存在
先确认使用的是哪个入口，再核对路径实际在哪台机器：
- Web 工作台「扫描目录」：
client-v0.2.66在客户端部署机扫描，容器必须挂载并能读取该目录；浏览器所在电脑的路径不能直接填给另一台机器上的 Web 容器。完成后要写回字幕，目标目录还需有写入权限，只有只读挂载不够。 - 「选择文件/文件夹」：读取的是打开工作台的浏览器所在电脑上的文件，不是 Web 部署机或 Serve 的路径。
- 服务端
/scan：扫描的是Serve 容器可访问的目录。JAVSCRIBE_HOST_ROOT在 Serve 与 Web 客户端中分别设置、分别解析；只给 Serve 配置该变量，不能让 Web 容器读取 Serve 的目录。
两种扫描都应先核对各自容器的实际挂载；不要为排障直接暴露整个宿主机根目录。详见部署指南和路径语义速查。
Docker 镜像拉不动 / 机器没外网
- 服务端：离线时
docker compose up -d --build从仓库源码本地构建； 内网机器之间可用docker save jav-scribe:latest | gzip > j.tar.gz→ 对端gunzip -c j.tar.gz | docker load传镜像。 - 客户端（Web 形态）：在部署机本地
docker build（仓库web/目录， 1~2 分钟），运行期不需要外网。 - 模型权重（首启 ~3.4G）只首次需要下载，之后在模型卷里。
再部署一台服务端（如第二张卡 / 第二台机器）
每台机器一个 serve 实例（各自 JAV_PORT、各自 JAVSCRIBE_API_KEY、 各自模型卷）。客户端「添加服务」登记新服务即可；勾上「⚖ 自动均衡」后， 新提交的任务会实时分给在途任务最少的在线服务。旧任务不会自动搬家， 用行级/批量「改派」调整。
服务端运行后，模型是一系列全自动的吗？
是。首次启动的完整链路无需手工干预：
- entrypoint 自检：检查模型卷（
JAV_MODELS_DIR）缺件 → 自动下载 （HF → hf-mirror 回退 + 429 重试，约 3.4G）；已齐全则跳过； - 服务自启：监听
watch.dirs/ 接收 inbox 上传音轨，无需再执行任何命令； - 模型按需加载：每个任务起独立推理子进程加载模型，任务结束释放， 不常驻显存（见「服务端没任务时是不是也一直占着显卡」）。
唯一前提：首启那一刻机器能下模型——直连外网 / 配 JAV_PROXY / 提前把模型放进模型卷（三选一）。另需 GPU 驱动（容器要 --gpus）； 建议首启就设 JAVSCRIBE_API_KEY（见「服务端设置」提示那一条）。
机器不能直连外网，模型怎么下？
两条路，推荐第一条：
- 走代理（serve v0.2.6+）：compose 里加
JAV_PROXY=http://<代理IP>:<端口>，entrypoint 注入容器全局，首启下载自动走代理； 内网地址自动豁免不走代理，需要额外豁免用JAV_NO_PROXY（支持 CIDR）。 - 离线放置：在有网机器上跑 ChickenRice 的
download_models.py，把整个models/目录传到服务端JAV_MODELS_DIR（结构见部署指南）。
Docker 镜像本身拉不动时：docker save / docker load 内网搬运，或本地 docker compose up -d --build 从源码构建。
怎么看服务端组件与模型是否就绪？
客户端「⚙ 服务设置」弹窗顶部的**「组件就绪」卡片**（serve v0.2.6+）： 打开弹窗自动拉取一次服务端自检，逐项显示
- 必需项：ASR 主模型 / VAD / 特征提取器 / ffmpeg / GPU 驱动 / 磁盘空间—— 全部绿色才算「全部就绪」，红色（fail）会直接挡住任务（如模型缺失）；
- 可选项：监听目录 / AI 润色 / Emby / JASNA / 外网代理——未启用显示灰（off）， 不影响核心功能；
- 顶部汇总：
全部就绪/存在未就绪项+ 服务版本 + 设备（cuda/cpu）。
自检只做本地检查（文件存在性、命令探测、磁盘空间），不探测 LLM / Emby 等网络连通性——连通性问题会在对应任务失败时体现。旧版服务端无此接口， 卡片显示升级提示（升级服务端到 v0.2.6+ 即可）。
任务与进度
看板统计和实际总数对不上（处理了 400+，统计只有几百）
任务状态以服务端为真源；看板只显示服务端当前返回的有限窗口：
- 「进行中 / 排队 / 提取 / 转译」等活跃行只能来自现行窗口（超窗口的活跃行不存在—— 窗口外的都是终态）；
- 「完成 / 跳过 / 失败」用服务端累计计数（超窗口也准确）；
- 仅对
serve-v0.2.16源码/自行构建版本，启用持久数据目录时终态任务历史写入jobs.json，重启后可恢复未被清理的完成历史；窗口上限仍在。不要把旧版的纯内存行为推给这个版本，也不要把此结论套用到未核实的公开旧版服务端包。
看板右上角「更新于 hh:mm:ss」是最近一次轮询时间（5 秒/次）。
服务端更新/重启后，历史任务怎么没了？
先检查实际 Serve 版本和持久化数据目录。仅对 serve-v0.2.16 源码/自行构建版本， 服务端会在持久数据目录的 jobs.json 保存已完成的终态任务历史；重启后可恢复未被清理的历史， 未完成及在途任务不会恢复执行，应核对源文件与字幕状态后重新提交。 客户端记住本工作台派发过的任务 ID，用于区分本机与他端任务；它不能代替服务端历史。 此恢复行为不能据 serve-v0.2.16 源码标签推断为已有公开安装包的能力。
已有产出应按原任务的实际写回位置检查：
- 扫描目录（客户端部署机）链路：
.zh.srt已写回影片旁，看行尾回写标记即可； - 其它链路：服务端 inbox 里保留字幕副本（默认 7 天保留期），可
↓ 下载 srt。
要长期留档：备份实际的影片旁 .zh.srt，并按需备份服务端数据卷；不要依赖任务看板窗口永久保留历史。
为什么任务都挤在一台服务上？
「⚖ 自动均衡」只对新派发的任务生效（实时分给在途最少的在线服务）， 已经在跑 / 已经在排的不会自动搬。想让排队或已暂停的任务换服务： 选中行 →「改派」→ 指定目标服务或「⚖ 自动均衡」。 服务卡上的「参与均衡」勾选可把某台临时移出均衡池（只收手动指定的任务）。
「提取音频失败: 提取停滞超时」是什么？ffmpeg 慢会被误杀吗？
这是卡住检测，不是慢速惩罚：ffmpeg 连续 10 分钟零输出进展才判停滞 （典型原因：文件损坏 / 磁盘 IO 挂死 / 网络盘掉线 / 文件被独占锁定）。 真有进展的慢提取不会被中断。出现时优先检查该文件所在磁盘 / NAS 的健康与连接。
400+ 任务怎么批量暂停 / 继续 / 重试？
- 批量：行首勾选（表头勾选 = 全选当前筛选集）→ 底部批量操作条： 暂停 / 继续 / 重试 / 取消 / 改派，一次作用于所有勾选项；
- 全局：顶栏「⏸ 暂停所有 / ▶ 继续任务」= 本机管线闸 + 代理所有在线服务队列暂停， 是服务端级操作（所有连到这些服务的客户端都会看到队列挂起，弹窗有警示）。
更新 Serve 前先等待在途任务完成并备份数据目录；仅暂停队列不能保证重启后在途任务续跑。
文件列显示的是 hash（如 8363…opus）而不是影片名？
早期版本看板「文件」列曾显示服务端 inbox 缓存文件名。新版已显示原始影片名。 看到 hash 说明客户端版本过旧——用底栏「检查更新」升级（Web 形态重建镜像）。
字幕与命名
视频内嵌了压制字幕 / 同目录已有字幕文件，会重复生成吗？
扫描结果会逐行标记：内嵌 xx（ffprobe 探测，显示语言）/ 外部 srt / C 版（名），这类文件默认不勾选；勾选后提交前会弹确认 （「已检测到 N 个文件带有字幕，是否继续生成」）。确认入队后服务端还有兜底：
- 外部字幕：
字幕已存在时跳过（默认开）； - 内嵌字幕：
内嵌字幕时跳过（默认target= 内嵌轨命中目标语言时跳过， 目标语言默认zh，均可在服务设置调）。
确实想对已有字幕的片重做：手动勾选 + 确认提交，再把 覆盖已存在字幕 打开 （否则落位阶段发现已有字幕仍会跳过）。
「C 版（名）/ 无字幕（名）」判定什么意思？
文件名带独立 C 段（不与番号 / CD / 集数混排，如 XXX-123-c.mp4） 按「无字幕版」语义处理，扫描行会标注出来。语义可在扫描区切换： 视为已压字幕 / 视为无字幕 / 关闭判定。
小于 200MB 的文件怎么处理？
列出但不默认勾选（挡预告片 / 坏文件），仍可手动勾选。 阈值在扫描区「忽略小于」调整（0 = 不忽略）。
字幕内容不合语境、同一句话在同一秒重复很多次（如大量「555」）？
主链路是 ja→zh 一步模型（ASR+翻译合一）。非语音段（BGM / 音效 / 环境音） 会让 ASR 产生幻觉重复文本，这是最常见原因。按顺序尝试：
- 调高 VAD 阈值（服务设置 → VAD，0.5 → 0.6~0.7）：让非语音段不进入识别， 重复/幻觉显著减少；轻声台词多则别调太高；
- 开 AI 润色（任意 OpenAI 兼容端点：Ollama / vLLM / 商用 API）： LLM 第二遍通读修正错译、漏译、不通顺；
- 确认素材确实是日语：其它语言的素材不在一步模型的适用范围内。
srt 结尾有一段奇怪的 0 时长条目 / 注释？
那是 JavScribe 指纹（字幕写入 JavScribe 指纹，默认开）： 注释 + 0 时长 cue，用于识别「本工具产出」，对播放器无影响、幂等不重复写。 不需要可关。
多客户端与多服务端
多个客户端连同一台服务端，会互相影响吗？
不会冲突，但注意可见性：
- 任务状态单一真源在服务端内存，每个客户端都是「视图 + 操作代理」，轮询秒级收敛；
- 他端提交的任务以虚线「他端」标记：可看进度、可
↓ 下载 srt、 可暂停/继续/重试/取消；但源视频不在本机，字幕不会自动落回本机磁盘； - 「暂停所有」等服务端级操作所有人可见（弹窗有警示）；
- 各客户端的登记表 / Key / 筛选 / 分页 / 阈值等偏好独立保存，互不影响。
多台服务端时任务怎么分配？在途任务能搬吗？
新任务由「⚖ 自动均衡」实时分给在途最少的在线服务（不是整批绑死一台）； 在途/排队任务不自动搬，用「改派」（单行或批量）。 服务卡「参与均衡」勾选可把某台临时移出均衡池。
更新与版本
在哪儿检查更新？服务端的新版本在哪儿看？
全部在客户端前端（服务端没有界面可提示）：
- 客户端新版本：底栏「检查更新」chip——自动定期检查 + 手动点击； 发现新版本后「下载安装 → 重启安装」（安装版）或重建镜像（Web 形态）；
- 服务端新版本：服务卡片上的版本落后提示（客户端轮询服务端版本并比对 GitHub Release）。
各形态的更新动作：
| 形态 | 动作 |
|---|---|
| 客户端 · 安装版 | 弹窗「下载安装」→「重启并安装」 |
| 客户端 · Web | 部署机重建镜像 + up -d --force-recreate（数据卷保留登记表/Key/本机设置） |
| 服务端 | 核对实际公开镜像版本或从固定源码 tag 自行构建，再按部署指南备份与更新；serve-v0.2.16 的终态历史可在持久数据目录恢复，在途任务不续跑 |
为什么 exe 装的版本和 Web 页面版本不一样？
同一产品的两种分发形态，版本号同一来源（同号同 commit 发布）， 但更新通道独立：exe 走「检查更新」，Web 形态版本 = 部署机镜像版本 （需要重建镜像）。两边都升到位后一致。
serve-vX / client-vX 版本号怎么理解？
| 组件 | tag | 发布 |
|---|---|---|
| 服务端 | serve-vX.Y.Z | 独立演进；源码 tag 不等于公开 Release 或可下载的预构建镜像 |
| 客户端 · Web 与安装版 | client-vX.Y.Z | 共用同一客户端版本体系；Web 没有独立 web-v* tag，安装版的资产以正式 Release 为准 |
已核 client-v0.2.66 有公开 Release；serve-v0.2.16 只核实到源码 tag，未核到对应公开安装包。 部署前在 JavScribe Releases 核对实际可获取资产；不要把客户端版本号当作服务端版本号。