NAS-Tools

NAS 媒体库资源归集、整理自动化工具

部署方式 • 功能 • 安装 • 配置

本分支修改内容

测试环境：群晖 Container Manager（Docker）和 macOS，其他环境仅供参考。

1. 媒体识别优化：模糊匹配与动漫类型修复

修改文件：

app/media/media.py - TMDB搜索和缓存逻辑
app/media/meta/_base.py - 类型判断逻辑

功能改进：

TMDB模糊搜索
- 当精确搜索无结果时，自动尝试用部分关键词重新搜索
- 解决字幕组拼写错误（如 "Srange" vs "Strange"）导致无法匹配TMDB的问题
名称相似度匹配
- 使用difflib计算相似度，阈值0.8以上认为匹配成功
- 解决因拼写差异导致的匹配失败问题
动漫类型识别修复
- 支持从genres字段获取类型信息（TMDB详细信息查询）
- 修复缓存保存时动漫类型丢失的问题（第一次识别正确，第二次变成电视剧）
- 保护已识别出集数的剧集不被TMDB电影结果覆盖
TMDB多结果匹配优先级修复
- 优化 __search_multi_tmdb() 选择策略：同名电影与电视剧同时命中时，按匹配分数选择，分数接近优先电影
- 避免先命中的 movie 被后续 tv 结果覆盖，导致电影被误判为动漫
- 统一 media_type 归一化，减少缓存和后续类型判断偏差

效果对比：

以 [绿茶字幕组] 命运-奇异赝品 / Fate Srange Fake [05][WebRip][1080p] 为例：

项目	修改前	修改后
类型	电影	动漫
TMDB匹配	未匹配	229858
缓存一致性	第二次变电视剧	始终为动漫

以 Chou Kaguya-hime!（TMDB: 1575337，movie）为例：

项目	修改前	修改后
multi检索结果	可能被tv覆盖	movie优先保留
页面标签	可能显示“动漫”	正确显示“电影”
季集展示	可能出现 `S01`	不再出现默认季信息

2. 动漫名称识别算法优化

优化了动漫文件名的季数识别，支持非标准命名格式。

修改文件：

app/media/meta/metainfo.py - is_anime() 函数
app/media/meta/metaanime.py - 非标准季数识别逻辑

效果对比：

以 [LoliHouse] Mato Seihei no Slave 2 - 05 为例：

项目	修改前	修改后
名称	Mato Seihei No Slave 2	Mato Seihei No Slave
季数	未识别	S02
集数	E05	E05

技术细节：

is_anime() 增加对 标题 2 - 05 格式的支持
MetaAnime 在 anitopy 无法识别季数时，从标题末尾提取数字作为季数

3. 修复 .DS_Store 导致数据库初始化失败

修改文件：

app/utils/path_utils.py - get_dir_level1_files() 函数

问题描述：

macOS 自动创建的 .DS_Store 文件会导致数据库初始化时 UTF-8 解码错误：

UnicodeDecodeError: 'utf-8' codec can't decode byte 0x80 in position 3131

原因分析：

Python 中 "" in ".sql" 返回 True，导致无扩展名文件被错误包含。修复后增加了空扩展名过滤。

4. 新增服务项：网络连通性测试-anime

在“服务”页面新增 网络连通性测试-anime，用于一键检测动漫相关站点连通性。

修改文件：

app/conf/moduleconf.py - 新增动漫网络测试目标列表
web/main.py - 服务页新增 nettest_anime 服务项
web/templates/service.html - 新增动漫网络测试弹窗与前端测试逻辑
web/action.py - net_test 兼容完整 URL 输入

测试目标：

bgm.tv
api.bgm.tv
www.comicat.org
mikanani.me

5. 页面切换动画和导航栏高亮过渡

为页面内容切换和导航栏高亮增加平滑过渡效果，消除突然闪变的视觉体验。

修改文件：

web/static/css/style.css - 添加 #page_content 的 opacity 过渡和 .content-fade-out class
web/templates/navigation.html - navmenu() 和 popstate 处理器中加入淡出/淡入逻辑
web/static/components/layout/navbar/index.js - 导航菜单项添加 background-color 过渡

功能改进：

页面内容淡入淡出
- 点击导航切换页面时，当前内容先淡出（150ms），新内容加载完成后淡入
- 浏览器前进/后退恢复页面时同样有淡出→淡入过渡
导航栏高亮平滑过渡
- 左侧导航栏的活跃项背景色切换增加 200ms 过渡动画，不再突变

6. 导航栏菜单搜索过滤

在左侧导航栏 logo 下方新增搜索框，输入关键词可实时过滤导航菜单项，快速定位功能页面。

修改文件：

web/static/components/layout/navbar/index.js - 搜索框 UI 及过滤逻辑

功能说明：

实时过滤
- 输入关键词后，导航栏仅显示名称匹配的菜单项，不区分大小写
- 有子菜单的分组会自动展开并只显示匹配的子项；分组名称本身匹配时显示全部子项
自动恢复
- 点击搜索结果中的菜单项后，搜索框自动清空，导航栏恢复完整显示
- 选中的菜单项所在分组自动展开并滚动居中
- 点击输入框右侧 X 按钮可手动清空搜索

7. 识别流程修复：忽略片名尾部版本号 + 中文兜底检索

针对 RSS/手动识别中的误判场景，补充了两类修复：

修改文件：

app/media/meta/_base.py - 新增尾部发布修订号清理方法
app/media/meta/metavideo.py - 视频名称清理接入版本号尾部剥离
app/media/meta/metaanime.py - 动漫中英文名称清理接入版本号尾部剥离
app/media/media.py - 增加中文兜底检索、兜底名称提取与噪音过滤
tests/cases/meta_cases.py - 新增版本号尾部识别用例
tests/test_media_cn_fallback.py - 新增中文兜底与噪音标题回归测试
tests/run.py - 纳入 MediaCnFallbackTest

功能改进：

忽略片名尾部发布修订号
- 仅清理片名尾部 v1/v2/V10/ver2/ver.2 这类修订号。
- 不处理片名中间内容，不影响 01v2/03v2 这类集号写法。
英文检索失败后自动中文兜底
- 先按原识别名检索 TMDB，失败后自动尝试中文候选名。
- 若两次都失败，页面“识别名称”默认展示中文名，便于人工修正。
中文兜底候选噪音过滤
- 过滤字幕组/编码/分辨率等发布信息干扰，避免将整段种子描述当作片名。
- 修复类似 TSDM 标题中“识别名称”显示过长且不准确的问题。

8. LLM 媒体识别增强

新增 LLM API接入，用于解析文件名、提取元信息。

修改文件：

文件	变更说明
`requirements.txt`	新增 OpenAI Python SDK 依赖
`app/media/meta/llm_parser.py`	新增 LLM 解析模块（OpenAI 协议）、检索增强、结果标准化、提示词规则、解析缓存
`app/media/meta/metainfo.py`	在规则识别后接入 LLM 合并流程
`app/media/meta/__init__.py`	导出 LLM 模块入口
`app/media/media.py`	支持读取 LLM 直出 `tmdb_id` 并优先按 ID 查询 TMDB
`check_config.py`	增加 `llm` 配置迁移、默认值补齐与参数校验
`web/templates/setting/basic.html`	新增 LLM 设置项（开关/模式/base_url/api_key/model/检索增强）与连接测试入口
`config/config.yaml`	增加 `llm` 模板配置区（空占位）
`tests/test_meta_llm_parser.py`	新增/扩展 LLM 解析与异常回退测试
`tests/run.py`	纳入 LLM 测试集

功能改进：

新增 LLM 媒体识别增强，可在规则识别链路上补齐或覆盖字段，输出结构与原有识别字段保持兼容。
支持两种识别策略：conservative（保守，默认）与 balanced（平衡）。保守＝规则识别出的字段一律保留、LLM 只补空；平衡＝片名允许 LLM 覆盖，其余字段仍只补空。作品与季集身份（TMDB ID、季号、集号）不受模式影响，走候选校验与季集映射；旧值 rule_first／fallback 迁移为保守，llm_first／primary／hybrid 迁移为平衡，confidence_threshold 已废弃。
支持第三方 OpenAI 协议兼容接口（base_url + api_key + model），设置页可直接保存并“测试连接”。
API 配置建议优先使用 DeepSeek 等开放平台（OpenAI 协议），示例：base_url=https://api.deepseek.com/v1、model=deepseek-chat。
新增检索增强上下文：在 LLM 解析前可先检索 TMDB与Bangumi 候选，并作为 external_candidates 提供给模型参考。
增强检索 query 归一化（去平台/编码/发布组噪声，提取核心标题），提高复杂标题命中率。
支持 LLM 返回 tmdb_id/tmdb_type，命中时优先按 ID 拉取 TMDB 详情，失败自动回退到原名称检索。
新增稳定性兜底：LLM 超时、异常、非法 JSON 时不影响原流程，自动回落规则识别。
新增可观测性：日志增加 LLM 原始返回、检索候选数量、直出 TMDBID 记录，便于排查识别问题。
配置迁移兼容旧版本：旧 config.yaml 自动补全 llm 字段。
检索增强候选携带季列表（seasons：季号/季名/首播年份/集数）、别名与 IMDb/TVDB 外链，LLM 据此一次性选定作品与季集；季号必须在该作品季列表内，集号必须存在于目标季集列表，否则不采用。
同名候选处理：标题里有年份时，年份对得上的候选排在前面（只重排不过滤，避免发布年份与首播年份不同的剧集被筛掉）；同名候选里若存在带 IMDb/TVDB 外链的正式条目，丢弃无外链的疑似重复条目并记录日志。
检索回退：规则解析名与 LLM 译名都会作为检索词尝试，避免某一侧译名失配导致识别失败。
集号硬约束：发布季标记与最终 TMDB 季号不一致时，集号必须有三者之一作为依据——作品级季集映射规则命中、LLM 给出且通过目标季集列表校验的集号、或可验证的绝对集号换算（前季集数之和换算并核对目标季集列表）；都不成立则拒绝绑定、保留待重试，并在日志中打印可直接粘贴到 media.episode_mappings 的规则模板。

9. Docker 镜像更新与部署规范

统一本分支 Docker 部署基线，减少容器环境差异导致的依赖问题。

修改文件：

文件	变更说明
`README.md`	更新 Docker 镜像标签、部署步骤与代理环境变量说明

功能改进：

Docker 基础镜像统一为 jhboy/nastools-comp:2.10.2v1。
AMD64 架构用户使用 jhboy/nastools-comp:2.10.2v1-amd64。
建议部署时开启 NASTOOL_AUTO_UPDATE=true 与 NASTOOL_CN_UPDATE=true，便于自动更新并使用国内源加速依赖安装。
支持按需新增容器环境变量 HTTP_PROXY、HTTPS_PROXY、NO_PROXY 挂载网络代理。
建议继续挂载 /config 到原有宿主机路径，复用历史配置与数据库数据。

10. 新增微信(OpenClaw)消息推送接口

新增 微信(OpenClaw) 消息通知渠道，用于普通微信号接收 NAS-Tools 推送，规避企业微信新应用公网固定 IP/白名单限制。

修改文件：

文件	变更说明
`app/conf/moduleconf.py`	新增 `wechat_openclaw` 消息渠道配置项
`app/helper/openclaw_helper.py`	新增 Web UI 扫码登录辅助接口
`app/helper/openclaw_wechat_login.py`	保留独立 CLI 扫码登录脚本
`app/message/client/wechat_openclaw.py`	新增 OpenClaw 消息客户端、长轮询 token 缓存、文本/图片发送
`app/message/message.py`	兼容测试模式，避免测试按钮启动额外长轮询
`web/action.py`	新增扫码登录接口与非交互消息端处理
`web/templates/setting/notification.html`	消息通知页面新增扫码登录弹窗
`web/static/js/libs/qrcode.min.js`	新增前端二维码渲染依赖
`tests/test_wechat_openclaw.py`	新增 OpenClaw 消息客户端回归测试

功能改进：

在“设置 → 消息通知”中新增 微信(OpenClaw) 渠道，可通过页面扫码自动填入 Bot Token、接收用户 ID 与 API 地址。
OpenClaw 渠道仅作为推送端使用，不接入 NAS-Tools 搜索/下载远程交互命令。
后台维护单 token 长轮询，用于缓存 context_token 与 get_updates_buf；配置刷新时避免同一 bot_token 并发长轮询。
支持文本推送、列表消息文本化推送、自定义消息推送。
支持原生微信图片气泡：图片会下载后经 AES-128-ECB 加密上传微信 CDN，再发送 image_item。
图片上传支持 NAS-Tools 代理配置；若图片下载、上传或发送失败，会自动回退为文本链接推送，避免通知完全丢失。
增加可选 CDN 地址 配置，默认使用 https://novac2c.cdn.weixin.qq.com/c2c。

使用注意：

扫码登录保存配置后，需要用刚扫码的微信号主动给 bot 发一条任意消息（如 hi），用于获取主动推送所需的 context_token。
如果测试或推送提示 会话过期(errcode=-14)，先等待后台轮询恢复；仍失败时重新给 bot 发消息或重新扫码。
若图片推送长时间卡在发送中并最终收到 URL 文本，请检查 NAS-Tools 代理是否能访问微信 CDN。

11. 手动字幕后台任务、低 IO 检测与局部刷新

手动上传、外挂字幕检测和问题字幕二次处理均由持久后台任务执行。HTTP 上传完成后立即返回任务 ID，页面关闭或刷新不会终止处理；任务可查询、取消并在任务中心重新连接。上传任务可在服务重启后按检查点恢复，检测和二次处理会标记为“已中断”，不会在 NAS 重启后突然继续扫盘。

修改文件：

文件	变更说明
`web/templates/rename/mediafile.html`	文件管理页新增“上传字幕”按钮与上传弹窗
`web/templates/rename/medialibrary.html`	字幕库页面、筛选与排序、分类检测、状态说明、上传对齐与任务设置入口
`web/static/js/media-library.js`	字幕库列表、分页、延迟加载、筛选排序、剧集选择、检测记录和二次处理交互
`web/static/js/subtitle-tasks.js`	共享字幕任务中心、上传字节进度、后台轮询、重连和显式取消
`web/static/js/media-sync.js`	抽离媒体库同步弹窗逻辑，供首页复用
`web/static/components/layout/navbar/index.js`	在“媒体整理”分类下提供“字幕库”菜单入口
`web/main.py`	提供字幕上传、分类检测、检测历史和单部电影二次处理接口
`app/helper/subtitle_tasks.py`	SQLite 持久队列、资源配额、任务恢复、取消、去重、探测缓存和保留清理
`app/subtitle.py`	字幕保存、标准化命名、冲突编号、多字幕来源保留、目标同步和二次处理
`app/helper/subtitle_health.py`	检测字符编码、内容结构、语言标签和媒体服务器可识别性，并安全修复非标准 SRT/ASS
`app/helper/subtitle_media_status.py`	按媒体服务器和媒体路径持久化字幕状态快照，供列表纯数据库读取
`app/helper/subtitle_align.py`	基于目标视频内嵌文本字幕进行稳健偏移、线性漂移、确认分段和 LLM 跨语言对齐
`app/utils/llm_client.py`	统一 OpenAI Chat Completions 兼容请求，支持 API 根地址及完整端点容错
`app/helper/db_helper.py`	新增按源文件查询最新整理历史
`app/mediaserver/media_server.py`	对 Emby/Jellyfin/Plex 执行单项目、父剧集或受限路径刷新
`app/library.py`	字幕库分类、状态聚合、排序、剧集查询、分类检测及最近 3 次记录
`tests/test_media_library.py`	字幕库、分类检测、状态排序、检测历史和性能缓存回归测试
`tests/test_subtitle_upload.py` / `tests/test_subtitle_align.py`	上传标准化、多来源命名、二次处理和字幕对齐回归测试

功能改进：

在“媒体整理 → 字幕库”中展示已媒体链接的电影、电视剧和动漫，支持类型、小分类、字幕状态、标题/年份筛选。
支持按“是否有内嵌字幕”、“是否有外挂字幕”和“字幕检测问题程度”升序/降序排序；问题程度排序可优先显示有问题的字幕。
打开字幕库、刷新、翻页、筛选和排序只读取媒体同步数据及 SQLite 媒体状态快照，不执行 isfile、目录枚举或 ffprobe；快照缺失且媒体服务器未明确提供字幕流信息时显示“未检测”，不会误报为“缺中文字幕”。
媒体卡片会同时展示内嵌/外挂中文字幕状态和最近一次外挂字幕检测结果。电视剧/动漫可先选择具体剧集再上传。
每批最多 20 个逻辑字幕；.sub + .idx 作为一个 VobSub 字幕成对上传、命名和发布。孤立 .idx、缺少 .idx 的二进制 .sub 会被拒绝，VobSub 不支持时间轴对齐。
上传时可选择 Jellyfin、Emby 或 Plex；默认使用全局影视服务器配置。
存在有效媒体链接目标时，链接目标目录是字幕唯一主副本，不再同时写入原始下载目录；只有无法取得链接目标时才写当前媒体文件目录。升级不会主动删除以前已经存在的源字幕。
目标字幕使用 Jellyfin/Emby/Plex 可识别的语言标签、来源和序号命名，例如：
- Movie (2024).zh-CN.srt
- Movie (2024).zh-TW.ass
- Movie (2024).zh-CN.bluray(1).srt
HTTP multipart 受 260 MiB 硬上限保护，并串行直写任务暂存卷的受控入口；校验大小和 SHA-256 后以同卷原子移动纳入独立 UUID 目录，不经过系统临时卷或第二次整文件写入。规范化、对齐和最终发布均使用派生文件及原子操作；已存在同名字幕不会覆盖，崩溃恢复不会重新编号或重复对齐。
可选字幕对齐模式保持“不对齐、自动选择、仅整体偏移、多锚点分段、LLM 跨语言对齐”兼容。候选文本先经规范化和 n-gram 索引缩小范围，再以受限模糊比较生成候选，并用单调锚点链避免重复对白抢占错误位置。锚点经中位残差与 MAD 剔除异常值；仅在数量、覆盖率和匹配度达标后改写。
offset 使用稳健中位偏移；auto 在整体偏移、轻微线性漂移和经连续锚点确认的分段模型中选择；segmented 不再直接把每个原始锚点作为插值节点。写入前验证时间轴单调、最小时长和伸缩范围，失败时保留原字幕。结果包含置信度、模型、内点/异常点、覆盖率和 P95 残差。
FFmpeg 抽取的内嵌文本参考轨按媒体路径、大小、mtime、流索引、缓存版本和 ffmpeg 版本缓存 30 天，原子发布；媒体或工具变化自动失效。缓存最多占字幕暂存额度的 10%，且硬上限为 256 MiB，任务取消或抽取失败不会产生可用记录。
LLM 跨语言对齐为显式选择的可选功能，默认上传不调用 API。参考字幕按时间均匀抽取高信息量句子，先翻译部分样本，匹配不足时才使用剩余批次补足覆盖，不再翻译整片字幕。LLM 不可用或锚点不足时安全跳过，不转用音频方案。
默认检测只读取 TRANSFER_HISTORY 中已媒体链接的目标文件，按目录分组且每个目录只枚举一次，不递归扫描媒体库根目录。检测会为已覆盖媒体写入状态快照，包括未发现外挂字幕的媒体；深度扫描位于高级选项，必须再次确认，并受目录数、变化字幕数和 60 分钟预算限制。
字幕探测结果按路径、大小、纳秒时间戳、VobSub 配对信息、校验器及 ffprobe 版本持久缓存；未变化字幕不会重复启动 ffprobe。检测历史、字幕状态和媒体级快照保存在 SQLite，问题明细有硬上限。
对于可读取但语言显示“未定义”、命名不规范或编码/格式异常的电影字幕，卡片提供“二次处理”；上传或处理后只复检当前电影/剧集并更新对应快照，不重新扫描整个分类。
上传或二次处理完成后只刷新精确电影/剧集项目，必要时降级到父剧集；Plex 可在可信 section 内刷新目标父目录。无法验证项目 ID 或路径映射时跳过并提示，绝不自动触发全媒体库刷新。
NAS 保守默认值：上传单 worker、全局同时最多一个 ffprobe/ffmpeg/LLM 重操作、上传队列最多 10 批；文本单文件 20 MiB、VobSub 组合 200 MiB、批次 250 MiB、暂存总额 2 GiB，并为暂存卷和目标卷保留至少 1 GiB 可用空间。暂存额度按普通上传最多 3 倍批次、对齐上传最多 6 倍批次预留；设置页和后端都拒绝无法覆盖最坏对齐派生量的组合。
“取消”是合作式操作：排队任务会立即停止；运行任务在复制分块、阶段边界或子进程轮询点停止。网络文件系统若阻塞在目录系统调用中，界面会保持“正在取消”，不会虚报任务已经结束；已经原子发布的字幕会保留并显示为部分完成。
无媒体链接历史时，上传源文件必须位于已配置的下载访问目录或媒体库根目录。媒体库中的媒体文件本身可以是指向下载卷的软链接，字幕仍写在该链接的目录；任务会固定并复核链接与目标身份，且拒绝操作软链接字幕或越出已授权目录。服务重启仅自动恢复具备逐项检查点的上传任务，检测和二次处理标记为中断且不会自行恢复磁盘负载。
本分支明确不包含 TTS、ASR、VAD、Whisper、音频切片、模型下载/管理、硬件探测或音频强制对齐，也不预埋相关数据库字段、设置、接口或依赖；端侧模型作为独立后续分支另行设计。

使用入口：

字幕库：媒体整理 → 字幕库
文件管理上传：媒体整理 → 文件管理 → 选中电影 → 上传字幕
字幕检测：媒体整理 → 字幕库 → 外挂字幕全部检测
任务与资源限制：媒体整理 → 字幕库 → 任务设置（独立页面，支持返回字幕库）
LLM 配置：设置 → 基础设置 → LLM识别

部署方式

识别与转移可靠性修复（2026-09-22）

字幕缓存清理即使删除 0 行也会结束写事务，异常时回滚，避免后台线程空闲时仍持有 SQLite 写锁。文件已硬链接但转移记录写入失败时，任务返回失败供目录同步重试；重试确认同一硬链接后补记历史，成功记录前不标记已处理。

识别流程保留 TSDM 方括号片名，避免将 Beyblade X 中的 X 当作第十季；短中文片名不再因前缀相似绑定到另一作品。动画检索候选携带分类并排除非动画，LLM 推断年份与文件明确年份分开处理，名称检索失败时继续尝试英文名和明确别名。

缺集检查使用 TMDB 季详情中的实际集号，包括海贼王的 S23E1179。内置映射仅覆盖已核实的作品与集数范围：TMDB 65942 的发布版第4季第1–19集映射到 S01E67–85；TMDB 37854 的发布版 S01E1156–1181 映射到 S23 同集号。每次映射还会核对 TMDB 目标集号；超范围或详情不可用时保留待重试。RSS 识别与下载后的文件识别共用这些规则。

现有配置无需修改即可使用内置映射。可在 media.name_aliases 中添加或覆盖别名；设置 media.episode_mappings 会替换内置映射，空列表可禁用。每条规则包含 tmdb_id、source_season、source_begin、source_end、target_season、offset。规则定义见 app/media/meta/recognition_rules.py。更新代码不会自动移动历史错季文件或补写旧转移记录，历史数据需要单独核对修复。

Docker 部署

新建容器，按架构选择镜像：

通用架构：jhboy/nastools-comp:2.10.2v1
AMD64 架构：jhboy/nastools-comp:2.10.2v1-amd64

建议环境变量如下：

PUID=0
PGID=0
TZ=Asia/Shanghai
UMASK=000
WORKDIR=/nas-tools
NASTOOL_CONFIG=/config/config.yaml

# 以下两项必须修改为true
NASTOOL_AUTO_UPDATE=true
NASTOOL_CN_UPDATE=true

NASTOOL_VERSION=master
REPO_URL=https://github.com/JHBOY-ha/nas-tools-complement.git
PYPI_MIRROR=https://pypi.tuna.tsinghua.edu.cn/simple
ALPINE_MIRROR=mirrors.ustc.edu.cn
# 代理按照本级环境选择使用：
#HTTP_PROXY=http://172.17.0.1:20171
#HTTPS_PROXY=http://172.17.0.1:20171
#NO_PROXY=localhost,127.0.0.1,172.17.0.0/16

建议将容器 /config 挂载到你当前正在使用的宿主机配置目录，避免历史配置和数据库丢失。如不使用代理，可删除 HTTP_PROXY、HTTPS_PROXY、NO_PROXY 三项。

网络代理配置

NAS-Tools 需要访问 TMDB、豆瓣、GitHub 等外部服务，建议配置代理：

代理类型	配置位置	用途
群晖系统代理	控制面板 → 网络 → 代理服务器	容器更新拉取 GitHub 代码
NAS-Tools 代理	设置 → 基础设置 → 系统 → 代理服务器	TMDB、豆瓣等服务访问

推荐使用 v2rayA 在 NAS 上部署代理服务。

功能：

本软件的初衷是实现影视资源的自动化管理，释放双手、聚焦观影。需要有良好的网络环境及私有站点才能获得较好的使用体验。

1、资源检索和订阅

站点RSS聚合，想看的加入订阅，资源自动实时追新。
通过微信、Telegram、Slack、Synology Chat或者WEB界面聚合资源搜索下载，最新热门资源一键搜索或者订阅。
与豆瓣联动，在豆瓣中标记想看后台自动检索下载，未出全的自动加入订阅。

2、媒体库整理

监控下载软件，下载完成后自动识别真实名称，硬链接到媒体库并重命名。
对目录进行监控，文件变化时自动识别媒体信息硬链接到媒体库并重命名。
解决保种与媒体库整理冲突的问题，专为中文环境优化，支持国产剧集和动漫，重命名准确率高，改名后Emby/Jellyfin/Plex完美刮削海报墙。
支持在文件管理中为单部电影手动上传外挂字幕，并按 Emby/Jellyfin 规范命名后同步到已整理的媒体库目标目录。

3、站点养护

全面的站点数据统计，实时监测你的站点流量情况。
全自动化托管养站，支持远程下载器（本工具内建刷流功能仅为日常养站使用，如果追求数据建议使用更加强大的刷流工具：Vertex）。
站点每日自动登录保号。

4、消息服务

支持微信、Telegram、Slack、Synology Chat、Bark、PushPlus、爱语飞飞等近十种渠道图文消息通知
支持通过微信、Telegram、Slack、Synology Chat远程控制订阅和下载。
Emby/Jellyfin/Plex播放状态通知。

安装

1、Docker

docker pull jhboy/nastools-comp:2.10.2v1
# AMD64:
docker pull jhboy/nastools-comp:2.10.2v1-amd64

教程见这里。

默认建议开启自动更新（NASTOOL_AUTO_UPDATE=true）。如无法连接 GitHub，可临时关闭自动更新（NASTOOL_AUTO_UPDATE=false），并将 NASTOOL_CN_UPDATE=true 以使用国内源加速依赖安装。

配置

1、申请相关API KEY

申请TMDB用户，在 https://www.themoviedb.org/ 申请用户，得到API KEY。
申请 LLM API（可选）
1. 建议优先使用 DeepSeek 等开放 API 平台（OpenAI 协议兼容）。
2. 在对应平台创建 API Key，并确认可用模型名称（如 deepseek-chat）。
3. 常见 OpenAI 协议地址示例：https://api.deepseek.com/v1。
申请消息通知服务
1. 微信（推荐）：在 https://work.weixin.qq.com/ 申请企业微信自建应用，获得企业ID、自建应用secret、agentid，微信扫描自建应用二维码可实现在微信中使用消息服务，无需打开企业微信
2. Telegram（推荐）：关注BotFather申请机器人获取token，关注getuserID拿到chat_id。该渠道支持远程控制，详情参考："5、配置微信/Telegram/Slack/Synology Chat远程控制"。
3. Slack：在 https://api.slack.com/apps 申请应用，该渠道支持远程控制，详情参考频道说明。
4. Synology Chat：在群晖中安装Synology Chat套件，点击Chat界面"右上角头像->整合->机器人"创建机器人，"传出URL"设置为："NAStool地址/synology"，"传入URL"及"令牌"填入到NAStool消息服务设置中，该渠道支持远程控制。
5. 其它：仍然会持续增加对通知渠道的支持，API KEY获取方式类似，不一一说明。

2、基础配置

文件转移模式说明：目前支持六种模式：复制、硬链接、软链接、移动、RCLONE、MINIO。
1. 复制模式下载做种和媒体库是两份，多占用存储（下载盘大小决定能保多少种），好处是媒体库的盘不用24小时运行可以休眠；
2. 硬链接模式不用额外增加存储空间，一份文件两份目录，但需要下载目录和媒体库目录在一个磁盘分区或者存储空间；软链接模式就是快捷方式，需要容器内路径与真实路径一致才能正常使用；
3. 移动模式会移动和删除原文件及目录；
4. RCLONE模式只针对RCLONE网盘使用场景，注意，使用RCLONE模式需要自行映射rclone配置目录到容器中，具体参考设置项小问号说明；
5. MINIO只针对S3/云原生场景，注意，使用MINIO，媒体库应当设置为/bucket名/类别名，例如,bucket的名字叫cloud,电影的分类文件夹名叫movie，则媒体库电影路径为：/cloud/movie,最好母集用s3fs挂载到/cloud/movie，只读就行。
启动程序并配置：Docker默认使用3000端口启动（群晖套件默认3003端口），默认用户密码：admin/password（docker需要参考教程提前映射好端口、下载目录、媒体库目录）。登录管理界面后，在设置中根据每个配置项的提示在WEB页面修改好配置并重启生效（基础设置中有标红星的是必须要配置的，如TMDB APIKEY等），每一个配置项后都有小问号，点击会有详细的配置说明，推荐阅读。
LLM识别（可选）：
1. 设置路径：设置 -> 基础设置 -> LLM识别
2. Base URL 为 OpenAI协议兼容 API URL（例如 https://api.openai.com/v1 或第三方兼容服务的 /v1 地址）
3. 同时填写 API Key、Model 后可使用“测试连接”校验
4. 建议优先使用 DeepSeek 等开放 API 平台（OpenAI 协议），示例：Base URL=https://api.deepseek.com/v1、Model=deepseek-chat

3、设置媒体库服务器

支持 Emby（推荐）、Jellyfin、Plex，设置媒体服务器后可以对本地资源进行判重避免重复下载，同时能标识本地已存在的资源：

在Emby/Jellyfin/Plex的Webhook插件中，设置地址为：http(s)://IP:PORT/emby、jellyfin、plex，用于接收播放通知（可选）
将Emby/Jellyfin/Plex的相关信息配置到”设置-》媒体服务器“中
如果启用了默认分类，需按如下的目录结构分别设置好媒体库；如是自定义分类，请按自己的定义建立好媒体库目录，分类定义请参考default-category.yaml分类配置文件模板。注意，开启二级分类时，媒体库需要将目录设置到二级分类子目录中（可添加多个子目录到一个媒体库，也可以一个子目录设置一个媒体库），否则媒体库管理软件可能无法正常搜刮识别。

电影

精选华语电影外语电影动画电影

电视剧

国产剧欧美剧日韩剧动漫纪录片综艺儿童

4、配置下载器及下载目录

支持qbittorrent（推荐）、transmission、aria2、115网盘、pikpak网盘等，右上角按钮设置好下载目录。

5、配置同步目录

目录同步可以对多个分散的文件夹进行监控，文件夹中有新增媒体文件时会自动进行识别重命名，并按配置的转移方式转移到媒体库目录或指定的目录中。
如将下载软件的下载目录也纳入目录同步范围的，建议关闭下载软件监控功能，否则会触发重复处理。

5、配置微信/Telegram/Slack/Synology Chat远程控制

配置好微信、Telegram、Slack或Synology Chat机器人后，可以直接通过移动端发送名字实现自动检索下载，以及通过菜单控制程序运行。

微信消息推送及回调

配置消息推送代理

由于微信官方限制，2022年6月20日后创建的企业微信应用需要有固定的公网IP地址并加入IP白名单后才能接收到消息，使用有固定公网IP的代理服务器转发可解决该问题

如使用 Nginx 搭建代理服务，需在配置中增加以下代理配置：
```
location /cgi-bin/gettoken {
  proxy_pass https://qyapi.weixin.qq.com;
}
location /cgi-bin/message/send {
  proxy_pass https://qyapi.weixin.qq.com; 
}
```

如使用 Caddy 搭建代理服务，需在配置中增加以下代理配置（`{upstream_hostport}` 部分不是变量，不要改，原封不动复制粘贴过去即可）。
```
reverse_proxy https://qyapi.weixin.qq.com {
  header_up Host {upstream_hostport}
}
```

如使用 Traefik 搭建代理服务，需在额外配置:
```
loadBalancer.passHostHeader=false
```

注意：代理服务器仅适用于在微信中接收工具推送的消息，消息回调与代理服务器无关。

配置微信消息接收服务在企业微信自建应用管理页面-》API接收消息开启消息接收服务：
1. 在微信页面生成Token和EncodingAESKey，并在NASTool设置->消息通知->微信中填入对应的输入项并保存。
2. 重启NASTool。
3. 微信页面地址URL填写：http(s)://IP:PORT/wechat，点确定进行认证。
配置微信菜单控制通过菜单远程控制工具运行，在https://work.weixin.qq.com/wework_admin/frame#apps 应用自定义菜单页面按如下图所示维护好菜单，菜单内容为发送消息，消息内容随意。

一级菜单及一级菜单下的前几个子菜单顺序需要一模一样，在符合截图的示例项后可以自己增加别的二级菜单项。

Telegram Bot机器人

在NASTool设置中设置好本程序的外网访问地址，根据实际网络情况决定是否打开Telegram Webhook开关。

注意：WebHook受Telegram限制，程序运行端口需要设置为以下端口之一：443, 80, 88, 8443，且需要有以网认证的Https证书；非WebHook模式时，不能使用NAStool内建的SSL证书功能。

在Telegram BotFather机器人中按下表维护好bot命令菜单（要选），选择菜单或输入命令运行对应服务，输入其它内容则启动聚合检索。

Slack

详情参考频道说明

命令与功能对应关系

命令	功能
/rss	RSS订阅
/ssa	订阅搜索
/ptt	下载文件转移
/ptr	自动删种
/pts	站点签到
/udt	系统更新
/tbl	清理转移缓存
/trh	清理RSS缓存
/rst	目录同步
/db	豆瓣想看
/utf	重新识别

Synology Chat

无需额外设置，注意非同一服务器搭建的，还需要在基础设置->安全中调整IP地址限制策略。

6、配置索引器

配置索引器，以支持搜索站点资源：

本工具内建索引器目前已支持大部分主流PT站点及部分公开站点，建议启用内建索引器。
同时支持Jackett/Prowlarr，需额外搭建对应服务并获取API Key以及地址等信息，配置到设置->索引器->Jackett/Prowlarr中。

7、配置站点

本工具的电影电视剧订阅、资源搜索、站点数据统计、刷流、自动签到等功能均依赖于正确配置站点信息，需要在“站点管理->站点维护”中维护好站点RSS链接以及Cookie等。

其中站点RSS链接生成时请尽量选择影视类资源分类，且勾选副标题。

8、整理存量媒体资源

如果你的存量资源所在的目录与你目录同步中配置的源路径目的路径相同，则可以通过WEBUI或微信/Telegram的“目录同步”按钮触发全量同步。

如果不相同则可以按以下说明操作，手工输入命令整理特定目录下的媒体资源：

说明：-d 参数为可选，如不输入则会自动区分电影/电视剧/动漫分别存储到对应的媒体库目录中；-d 参数有输入时则不管类型，都往-d目录中转移。

Docker版本，宿主机上运行以下命令，nas-tools修改为你的docker名称，修改源目录和目的目录参数。
```
docker exec -it nas-tools sh
python3 /nas-tools/app/filetransfer.py -m link -s /from/path -d /to/path
```

群晖套件版本，ssh到后台运行以下命令，同样修改配置文件路径以及源目录、目的目录参数。

export NASTOOL_CONFIG=/var/packages/NASTool/target/config/config.yaml
/var/packages/py3k/target/usr/local/bin/python3 /var/packages/NASTool/target/app/filetransfer.py -m link -s /from/path -d /to/path

本地直接运行的，cd 到程序根目录，执行以下命令，修改配置文件、源目录和目的目录参数。
```
export NASTOOL_CONFIG=config/config.yaml
python3 app/filetransfer.py -m link -s /from/path -d /to/path
```

字幕库在线字幕

在字幕库顶部输入媒体名、原名或年份，点击“搜索影片”（或回车）查找已同步的媒体；搜索与类型、分类、字幕状态筛选可组合使用。

电影卡片点击“在线字幕”，电视剧和动漫先“选择剧集”，按季、集筛选后点击对应集的“检索本集字幕”。检索框默认填入媒体名、英文原名（如有）、年份及季集，可手动修改或删除关键词，按回车或点击“检索字幕”搜索，也可点击“恢复默认词”。编辑后的检索词会原样传给迅雷或 Assrt（剧集未填写季集时自动补齐目标季集）；剧集以独立季集参数检索，并将下载结果绑定到选中的视频路径。检索结果会校验片名（含原名）、已知年份和季集，过滤无法确认的结果；缺少年份的电影结果会单独标注。迅雷无需配置，优先展示与本地视频 CID 匹配的字幕。Assrt 的 Token 在“设置 → 字幕设置 → 在线字幕”保存，也可配置 subtitle.assrt.token，不影响原有自动字幕下载器。

选择结果后点击“下载并保存”；ZIP 字幕包会先列出文件供选择，剧集只列出明确匹配当前季集的字幕，无法确认或属于其他集的文件不能保存；RAR 结果暂不支持，请选择其他结果。单次下载和字幕包展开内容限制为 20 MB。下载后进入统一字幕任务队列，可在任务中心查看进度；后台完成格式与编码校验、保存到选中的媒体文件旁，并更新字幕状态和刷新媒体服务器。保留已有字幕，沿用任务设置中的队列、暂存和资源限制。下载结果有效期为 30 分钟，过期后重新搜索。媒体文件需位于已配置的媒体库目录内且可读取。

在线检索协议和 CID 算法参考 MeiamSubtitles，按 NASTool 的字幕库和上传流程重新实现；上游采用 Apache-2.0，许可见 third_party/meiamsubtitles/LICENSE。未接入已停止维护的旧 Shooter 接口。

鸣谢

程序UI模板及图标来源于开源项目tabler，此外项目中还使用到了开源模块：anitopy、tmdbv3api、python-plexapi、qbittorrent-api、transmission-rpc等
感谢 nevinee 完善docker构建
感谢 tbc0309 适配群晖套件
感谢 PR 代码、完善WIKI、发布教程的所有大佬

上传整季字幕

在“字幕库 → 选择剧集”中选择具体的一季，点击“上传整季字幕包”，直接多选 SRT、ASS、SSA、VTT、SMI 字幕文件，或选择一个 ZIP 包，再点击“预览匹配”。上传和解包不依赖任何外部工具：RAR 请先解压，再多选其中的字幕文件。ZIP 支持包内子目录；不处理嵌套压缩包、加密包及图形字幕。

参照 ChineseSubFinder 的整季字幕按季集分组方式，按 S01E02、1x02、EP02、第2集、[02] 等文件名解析对应剧集；只含集数时使用当前所选季。缺集、跨季、集数范围、无法识别或同集多个视频版本的文件不自动分配。匹配范围固定为当前电视剧和所选季，请在预览中核对目标路径；同集的不同语言/版本可取消勾选。

点击“上传所选字幕”后创建一个持久后台任务，按集保存到对应视频旁，逐集复核路径授权、更新字幕快照并局部刷新媒体服务器。字幕包不会按内部路径直接解压到媒体目录，已有字幕不覆盖。关闭页面后后台继续，可通过任务中心查看逐项结果或取消，重启后按检查点恢复。

“任务设置 → 整季字幕包数量”默认允许 100 个文本字幕，最高 200 个；压缩包及展开内容仍受单批总量、文本单文件、暂存额度和任务时间限制。LLM 对齐仍受 LLM 单批数量限制。一次任务的目标必须处于同一存储卷，跨卷时分开勾选提交。

Name		Name	Last commit message	Last commit date
.github		.github
app		app
config		config
db_scripts		db_scripts
docker		docker
docs		docs
tests		tests
third_party		third_party
web		web
windows		windows
.dockerignore		.dockerignore
.gitignore		.gitignore
.gitmodules		.gitmodules
AGENT.md		AGENT.md
DESIGN.md		DESIGN.md
LICENSE.md		LICENSE.md
README.md		README.md
build_sites.py		build_sites.py
check_config.py		check_config.py
config.py		config.py
dbscript_gen.py		dbscript_gen.py
log.py		log.py
package_list.txt		package_list.txt
requirements.txt		requirements.txt
run.py		run.py
third_party.txt		third_party.txt
version.py		version.py

Navigation Menu

Repository navigation

About

Repository files navigation

NAS-Tools

本分支修改内容

部署方式

识别与转移可靠性修复（2026-09-22）

Docker 部署

网络代理配置

功能：

1、资源检索和订阅

2、媒体库整理

3、站点养护

4、消息服务

安装

1、Docker

配置

1、申请相关API KEY

2、基础配置

3、设置媒体库服务器

4、配置下载器及下载目录

5、配置同步目录

5、配置微信/Telegram/Slack/Synology Chat远程控制

6、配置索引器

7、配置站点

8、整理存量媒体资源

字幕库在线字幕

鸣谢

上传整季字幕

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

NAS-Tools

本分支修改内容

部署方式

识别与转移可靠性修复（2026-09-22）

Docker 部署

网络代理配置

功能：

1、资源检索和订阅

2、媒体库整理

3、站点养护

4、消息服务

安装

1、Docker

配置

1、申请相关API KEY

2、基础配置

3、设置媒体库服务器

4、配置下载器及下载目录

5、配置同步目录

5、配置微信/Telegram/Slack/Synology Chat远程控制

6、配置索引器

7、配置站点

8、整理存量媒体资源

字幕库在线字幕

鸣谢

上传整季字幕

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages