MacCMS Tools 功能详解以及使用教程

快速开始 (Quick Start)

部署启动：运行程序后，访问 http://<IP>:5000 或绑定域名即可进入登录界面。
初始登录：默认凭证 admin / 123456.0（强烈建议首次登录后立即修改密码）。
环境配置：
- 进入【设置】模块，准确配置 CMS 安装路径（如 /www/wwwroot/cms）及网页端域名（需包含协议头）。
- 完成授权验证，解锁全部高级功能。
业务接入：
- 在【采集资源】中添加目标资源站，完成分类映射。
- 创建【定时任务】，设定采集策略与去重规则，开启自动化运维之旅。

主界面概览

程序主页分为三个主要区域：

顶部：显示当前授权状态；
中部：提供程序功能简介；
底部：展示服务器环境信息，包括操作系统、Python 版本、数据库地址及连接状态。

若有新版本可用，系统将在主页显著位置提示，并支持 一键在线更新。

核心功能模块

日志模块

日志模块实时记录系统运行状态，支持动态滚动刷新，始终聚焦最新日志内容。
对于定时任务，日志将以如下格式清晰标识：

[时间] [定时任务名称] [日志内容]

右上角提供 “清空日志” 按钮，便于快速清理历史记录，提升可维护性。

资源管理

资源列表

支持封面预览；
每项资源右侧提供 查看详情、删除等操作入口。

资源搜索

在搜索框中输入资源名称，系统将实时匹配并高亮显示相关结果。

资源详情页

展示资源的完整元数据，包括：

基础信息（名称、分类、更新时间等）；
播放器配置；
剧集列表（支持点击直接播放）。

搜索框输入资源名称，对应的资源即可自动弹出

资源详情页面可以查看资源的详细信息，点击对应的剧集还可以直接播放。

资源采集

MacCMS Tools 内置一套智能高效的采集引擎，支持多源对接。

添加资源站

点击右上角 “添加资源站”；
填写任意名称，选择接口类型（如 MacCMS、苹果CMS 等），并输入 API 地址；
点击 “添加” 完成配置。

鼠标悬停于资源站卡片时，右上角将显示编辑与删除按钮，并高亮标注其接口类型，便于识别。

资源站详情页

展示该站点所有可采集资源（含 ID、名称、最新剧集、分类、更新时间等）；
提供 分类筛选、关键词搜索、分类映射 及 单条入库 功能。

📌 重要步骤：首次采集前，请务必点击 “分类映射”，将远程分类同步至本地，否则无法正常入库。

手动采集

在搜索框中输入目标资源名称并回车，系统将返回匹配结果。点击 “入库” 即可立即将资源导入本地数据库。

附件同步策略配置：

默认行为 (Default Behavior)

策略定义：保持采集源状态不变。
执行逻辑：

资源图片的地址格式（本地或远程）将严格维持采集入库时的原始状态。

系统不对现有资源的图片进行任何干预（不下载、不替换、不迁移）。

同步模式详解(Incremental Sync Mode)

策略定义：仅针对新增资源执行本地化操作。
执行逻辑：

新增资源：自动下载图片至本地存储（路径格式：upload/vod/YYYYMMDD/.ext），并将数据库中的图片地址更新为对应的本地相对路径。

已存在资源：跳过处理，图片地址及文件状态保持不变。

强制覆盖模式 (Overwrite Mode)

策略定义：确保所有资源图片最终状态为“本地化”。
执行逻辑：

结果：实现从“远程链接”到“本地文件”的无缝迁移。

场景一：库内图片已是本地路径

动作：跳过下载（避免冗余IO），保持现有本地路径不变。

场景二：库内图片为远程地址

动作：执行下载操作，将图片保存至本地存储（upload/vod/YYYYMMDD/.ext），并将数据库地址覆写为新的本地相对路径。

图床映射模式 (Image Hosting Mapping)

策略定义：优先保留本地文件，仅更新远程引用。
执行逻辑：

结果：防止误删已转存本地的珍贵资源。

场景一：库内图片为远程地址

动作：更新图片地址为本次采集指定的图床地址（覆盖旧链接）。

场景二：库内图片为本地路径

动作：跳过处理，保护本地文件不被移除或修改，地址保持不变。

图床强制覆盖模式 (Hosting Overwrite Mode)

策略定义：强制统一为远程图床地址，清理本地冗余文件。
执行逻辑：

结果：实现全站图片的“去本地化”，统一由外部图床托管。

场景一：库内图片为本地路径

动作：

文件清理：删除服务器上对应的本地图片文件。

地址切换：将数据库地址覆写为本次采集的远程图床地址。

场景二：库内图片为远程地址

动作：直接更新图片地址为本次采集指定的图床地址。

卡片右上角会用标签高亮显示该资源站类型和图片同步模式方便区分，

鼠标移动到添加的资源站卡片上，卡片右上角会显示，编辑按钮和删除按钮，以及会在卡片右上角高亮这个资源站的接口类型，方便辨认。

点击卡片即可打开资源站的详细界面，界面包括资源站名字，资源站内的资源列表，id，名字，更新到了哪一集，分类，更新时间，采集按钮等等，分类选择，搜索，分类映射按钮等等。

点击你需要的分类，会显示对应分类下的资源

首选需要点击分类映射按钮，映射分类到本地，映射后即可采集对应分类下的资源

在搜索编辑框输入你要需要的资源回车后，即可查询出你需要的资源，点击入库即可立即入库

此时再点击资源列表会就会发现刚刚采集的资源，比如我刚刚采集到了一个叫东北雷神的资源。

定时任务

程序集成企业级调度引擎，支持灵活创建与管理自动化任务。

任务类型

定时采集任务：按设定周期自动拉取指定资源站的更新内容；
定时合并任务：执行数据库去重与清洗（详见下文）；
定时清理日志：根据设置的范围自动清理程序日志；
定时访问URL任务：用于自定义程序的推送等；

任务卡片

每个任务以独立卡片形式展示，包含：

任务名称；
上次执行时间；
下次计划执行时间；
“立即执行” 按钮（用于手动触发）。

执行过程中的详细日志将实时输出至 日志模块，便于监控与排查。

点击创建任务按钮，可以选择创建任务类型，点击资源定时采集

此时目标资源站列表会显示，你创建的资源站列表，并且会显示该资源站的接口类型，用于辨认同名但不同接口类型的资源站。

采集时间范围，意思是采集该资源站，什么时间段的资源，1个小时就是采集该资源站，这个小时内更新的资源，1天则是当天更新的资源，以此类推。

点击保存即可保存该定时任务

数据去重与合并（核心亮点）

MacCMS Tools 内置高性能数据库清洗引擎，采用 轻量索引 + 相似度评分模型，非简单字段匹配，确保去重结果精准可靠。

性能表现

在 2核2G 低配服务器上，可高效处理 三十万级 数据；
实测：37万条记录（1.45GB）的数据库，45秒内完成全量去重；
首次建立索引后，后续增量去重可在 数秒内完成，即使面对百万级数据亦游刃有余。

此功能极大降低人工维护成本，保障数据一致性与系统性能。

定时采集资源

定时执行URL

定时清理日志

点击日志按钮后会显示该定时任务的专属日志

定时任务卡片会显示，定时任务的图标，名称，执行周期，上次执行日期，下次执行日期，运行状态，开关按钮，编辑按钮，删除按钮，立即执行按钮，停止按钮，日志按钮，等。

播放器智能配置

程序支持 自动创建播放器，无需手动干预：

用户仍可通过播放器右侧的 “编辑” 按钮进行高级自定义（如解析接口、加密规则等）。

当采集的资源站使用本地未注册的播放器时，系统将在采集过程中 动态生成对应播放器配置；

点击播放器右侧的编辑按钮还可直接进行高级编辑。

分类设置

程序内置分类管理器，支持一键创建，删除，修改分类，且提供非常清晰且现代的管理组件

父分类下的子分类会自动进行缩放，提升可读性

系统设置

设置页面涵盖以下关键配置项：

表格

配置项	说明
后台密码	修改管理员登录凭证
自助换绑	更换授权域名（换绑后有 3天冷却期）
CMS 路径	必填项，格式如 `/www/wwwroot/cms`（以 `/` 开头，不以 `/` 结尾）
CMS 网页域名	若部署了 Web 前端，需填写完整 URL（含 `http://` 或 `https://`）
去重权重	自定义各字段（如标题、演员、简介）在相似度计算中的权重
Ridis配置	多进程必需
数据库配置	调整连接参数（通常无需修改）
卡密授权	自助授权