苹果CMSv10数据采集工具文档

苹果CMSv10数据采集工具是一个高效的数据采集与入库解决方案，支持从其他网站采集数据并导入到苹果CMSv10系统。

主要特点包括多线程采集、自动分类映射、时间限制采集、关键词过滤等。通过简单的配置，您可以快速建立一个完整的自动化数据采集流程。

使用预编译的可执行文件版本无需安装Python环境，按照以下步骤快速部署：

1. 下载可执行文件

   从下载页面获取适合您系统的预编译版本：

   • Linux用户：下载apple-cms-collector-linux文件
   • Windows用户：下载apple-cms-collector-win.exe文件
2. 添加执行权限（仅Linux）

   Linux系统需要为下载的文件添加执行权限：

   chmod +x apple-cms-collector-linux
3. 创建配置文件

   在与可执行文件相同的目录下创建config.json文件，填写您的配置。可参考下面的配置文件章节获取配置模板。

   确保配置文件使用UTF-8编码保存。

4. 运行程序

   Linux系统：

   ./apple-cms-collector-linux

   Windows系统：直接双击apple-cms-collector-win.exe文件或通过命令行运行：

   apple-cms-collector-win.exe

   程序将根据配置文件自动开始数据采集工作。

5. 设置定时任务（可选）

   您可以设置定时任务自动运行程序：

   1. Linux系统 - Cron任务

   crontab -e # 添加以下行（每天凌晨2点运行） 0 2 * * * cd /path/to/collector && ./apple-cms-collector-linux >> /var/log/collector.log 2>&1

   2. 宝塔面板 - 计划任务

   如果您使用宝塔面板管理服务器，可以通过宝塔面板的计划任务功能轻松设置：

   1. 登录宝塔面板，点击左侧菜单的计划任务
   2. 点击添加计划任务按钮
   3. 填写任务信息：
      • 任务名称：苹果CMS数据采集
      • 执行周期：根据需要选择（如每小时、每天等）
      • 脚本类型：选择Shell脚本
      • 脚本内容：
        cd /www/wwwroot/插件目录/ && ./apple-cms-collector-linux >> /www/wwwlogs/collector.log 2>&1
   4. 点击提交按钮保存任务

   宝塔面板会自动管理任务的执行，您可以在计划任务列表中查看执行记录和日志。

   3. Windows系统 - 计划任务程序

   Windows系统可以使用计划任务程序（Task Scheduler）实现类似功能：

   1. 打开任务计划程序（可通过控制面板或搜索找到）
   2. 点击创建基本任务
   3. 按照向导设置任务名称、触发器（执行频率）和操作
   4. 操作类型选择启动程序，程序路径设置为可执行文件的完整路径

配置文件是工具运行的核心，通过配置文件您可以定义采集来源、规则和处理方式。

配置文件格式

配置文件采用JSON格式，包含以下主要部分：

{
    "maccms_url": "http://your-maccms-site.com/",
    "api_key": "your_api_key",
    "threads": 5,
    "min_request_delay": 0.5,
    "max_request_delay": 2.0,
    "default_type_id": 1,
    "filter_keywords": [
        "屏蔽词1", 
        "屏蔽词2", 
        "敏感内容"
    ],
    "title_replace_rules": {
        "第1季": "第一季",
        "第2季": "第二季",
        "第3季": "第三季",
        "S0?(\\d)": "第$1季",
        "Season\\s?(\\d+)": "第$1季",
        "\\s+": " "
    },
    "proxy_pool": {
        "enabled": true,
        "proxy_source": "txt",
        "proxy_txt_path": "proxies.txt",
        "proxy_api_url": "http://api.example.com/proxy?count=10",
        "proxies": [
            "http://user:pass@192.168.1.1:8080",
            "http://192.168.1.2:8080",
            "socks5://192.168.1.3:1080"
        ],
        "timeout": 10,
        "retry_count": 3,
        "check_interval": 3600
    },
    "collect_urls": [
        {
            "url": "http://source-site.com/api.php/provide/vod/?ac=videolist&pg=1",
            "remark": "电影资源",
            "hours": 24,           // 仅采集最近24小时内的数据
            "use_proxy": true      // 使用代理池
        },
        {
            "url": "http://source-site.com/api.php/provide/vod/?ac=videolist&pg=1&t=2",
            "remark": "电视剧资源",
            "hours": 0,            // 设置为0表示不限制采集时间
            "use_proxy": false     // 不使用代理池
        }
    ],
    "category_mapping": {
        "电影": 20,
        "电视剧": 21,
        "综艺": 22,
        "动漫": 23,
        "纪录片": 24
    },
    "enable_name_mapping": true,
    "logging": {
        "file": "logs/collector.log",
        "level": "INFO",
        "format": "%(asctime)s - %(levelname)s - %(message)s",
        "date_format": "%Y-%m-%d %H:%M:%S",
        "rotate_daily": true,         
        "max_size_mb": 10,            
        "backup_count": 7            
    }
}

配置说明

• maccms_url: 您的苹果CMS网站地址
• api_key: 苹果CMS的API密钥
• threads: 并发线程数
• min_request_delay: 最小请求延迟（秒）
• max_request_delay: 最大请求延迟（秒）
• default_type_id: 默认分类ID
• filter_keywords: 过滤关键词列表，视频名称中包含这些关键词的条目会被过滤不入库
• title_replace_rules: 标题替换规则，键为要匹配的正则表达式，值为替换的文本
• proxy_pool: 代理池配置，包含代理来源和相关设置
• collect_urls: 采集URL列表，包含URL、分类ID、备注信息、时间限制和代理使用设置
• category_mapping: 分类名称映射，将特定名称映射到对应的分类ID
• enable_name_mapping: 是否启用分类名称映射功能
• logging: 日志配置

采集URL配置

在collect_urls中，每个采集源可配置以下参数：

• url: 采集源的API地址，必填项
• remark: 备注信息，将保存到影片的备注字段中，可选
• hours: 时间限制，仅采集最近几小时内的数据，可选；设置为0表示不限制采集时间
• use_proxy: 是否使用代理池，可选；默认值取决于全局代理池设置

时间限制采集功能可以帮助您只采集最近指定小时内的数据，避免重复采集历史数据。

配置时间限制

通过配置hours参数，您可以实现仅采集最近指定小时内的数据：

"collect_urls": [
    {
        "url": "http://source-site.com/api.php/provide/vod/?ac=videolist&pg=1",
        "remark": "电影资源",
        "hours": 24    // 仅采集最近24小时内的数据
    },
    {
        "url": "http://source-site.com/api.php/provide/vod/?ac=videolist&pg=1&t=2",
        "remark": "电视剧资源",
        "hours": 0     // 设置为0表示不限制采集时间
    }
]

时间限制实现方式

系统实现时间限制的方式有两种：

1. API参数方式：系统会在采集URL中自动添加h=小时数参数（例如h=24），如果源站支持此参数，则会直接返回符合时间条件的数据
2. 本地过滤方式：系统会检查每条数据的更新时间，仅保留符合时间条件的数据

支持的时间格式

系统会尝试从以下字段中获取更新时间：

• vod_time
• vod_addtime
• vod_pubdate
• update_time
• last_update

支持的时间格式包括：

• Unix时间戳（10位数字）
• 常见的日期时间格式（如YYYY-MM-DD HH:MM:SS、YYYY/MM/DD HH:MM:SS、YYYY-MM-DD）

分类名称映射功能可以实现根据内容名称自动设置对应的分类ID，提高数据分类的准确性。

配置分类映射

"category_mapping": {
    "电影": 20,
    "电视剧": 21,
    "综艺": 22,
    "动漫": 23,
    "纪录片": 24
},
"enable_name_mapping": true

映射规则

系统会按以下优先级进行映射：

1. 首先尝试匹配分类名称（type_name字段）
2. 然后尝试匹配分类标签（vod_class字段）
3. 最后尝试匹配标题关键词

标题替换功能可以对视频标题进行自动替换和格式化，使标题更加规范和统一。

配置标题替换

"title_replace_rules": {
    "第1季": "第一季",
    "第2季": "第二季",
    "第3季": "第三季",
    "S0?(\\d)": "第$1季",
    "Season\\s?(\\d+)": "第$1季",
    "\\s+": " "
}

替换规则说明

系统使用正则表达式进行替换，所以可以使用捕获组（$1、$2等）来引用匹配的内容。上面的配置可以实现以下替换效果：

• "第1季" → "第一季"
• "S1" 或 "S01" → "第1季"
• "Season 1" → "第1季"
• 多余的空格会被合并成一个空格

关键词过滤功能可以过滤掉视频标题中包含特定关键词的内容，不将其入库。

配置关键词过滤

"filter_keywords": [
    "屏蔽词1", 
    "屏蔽词2", 
    "敏感内容"
]

过滤机制

系统会在入库前检查每个视频标题，如果包含任一关键词，将跳过该条目并在日志中记录。被过滤的数量会在最终统计中显示。

代理池功能可以帮助您通过不同IP地址发送请求，避免IP被封禁，提高采集稳定性和成功率。

代理池配置选项

"proxy_pool": {
    "enabled": true,
    "proxy_source": "txt",
    "proxy_txt_path": "proxies.txt",
    "proxy_api_url": "http://api.example.com/proxy?count=10",
    "proxies": [
        "http://user:pass@192.168.1.1:8080",
        "http://192.168.1.2:8080",
        "socks5://192.168.1.3:1080"
    ],
    "timeout": 10,
    "retry_count": 3,
    "check_interval": 3600
}

参数说明

• enabled: 是否启用代理池功能（全局开关）
• proxy_source: 代理来源，支持从配置、文件或API获取代理，可选值: null(仅使用配置中的代理), "txt"(从文本文件获取), "api"(从API获取)
• proxy_txt_path: 代理文本文件路径，每行一个代理
• proxy_api_url: 代理API接口URL，返回文本格式，每行一个代理
• proxies: 配置中的代理服务器列表
• timeout: 请求超时时间（秒）
• retry_count: 请求失败后的重试次数
• check_interval: 代理有效性检查间隔（秒）

代理获取方式

代理池支持三种获取代理的方式：

1. 从配置文件 - 使用proxies数组中定义的代理
2. 从TXT文件 - 设置proxy_source: "txt"，从proxy_txt_path指定的文件中读取代理，每行一个
3. 从API接口 - 设置proxy_source: "api"，从proxy_api_url指定的接口获取代理，接口需返回文本，每行一个代理

支持的代理格式

• HTTP代理: http://ip:port 或 http://username:password@ip:port
• SOCKS5代理: socks5://ip:port 或 socks5://username:password@ip:port

代理TXT文件格式

如果使用TXT文件作为代理源，请遵循以下格式：

# 注释行以#开头
http://192.168.1.100:8080
http://user:pass@45.67.89.123:8080
socks5://192.168.1.102:1080

• 每行一个代理
• 支持HTTP和SOCKS5格式
• #开头的行会被视为注释

为单个采集任务配置代理

您可以在每个采集URL的配置中单独设置是否使用代理：

"collect_urls": [
    {
        "url": "http://source-site.com/api.php/provide/vod/?ac=videolist&pg=1",
        "remark": "电影资源",
        "hours": 24,
        "use_proxy": true      // 使用代理池
    },
    {
        "url": "http://source-site.com/api.php/provide/vod/?ac=videolist&pg=1&t=2",
        "remark": "电视剧资源",
        "hours": 0,
        "use_proxy": false     // 不使用代理池
    }
]

代理池特性

1. 自动检查：定期检查代理有效性，剔除失效代理
2. 随机选择：每次请求随机选择一个可用代理
3. 自动切换：当请求失败时自动切换到另一个代理重试
4. 单任务配置：支持为每个采集任务单独设置是否使用代理

日志配置可以帮助您跟踪采集过程，记录错误和统计信息，便于问题排查和性能优化。

日志配置选项

"logging": {
    "file": "logs/collector.log",
    "level": "INFO",
    "format": "%(asctime)s - %(levelname)s - %(message)s",
    "date_format": "%Y-%m-%d %H:%M:%S",
    "rotate_daily": true,         
    "max_size_mb": 10,            
    "backup_count": 7            
}

日志轮换机制

系统支持两种日志轮换方式：

• 基于时间的轮换：每天午夜自动创建新日志文件（设置rotate_daily: true）
• 基于大小的轮换：当日志文件达到指定大小时自动创建新文件（设置max_size_mb）

这两种方式都可以设置保留备份的数量（backup_count），超过数量的旧日志文件会被自动删除。

性能优化设置可以帮助您根据服务器资源和网络条件调整采集工具的运行效率。

优化特性

1. 请求重试机制：自动重试失败的请求，提高采集稳定性
2. 线程安全：使用线程锁保护共享资源访问
3. 错误处理：详细的错误日志和异常堆栈跟踪
4. 数据验证：入库前验证数据有效性，包括播放来源检查
5. 自动创建日志目录：如果日志文件所在目录不存在，会自动创建
6. 可配置的请求延迟：避免对源站点造成过大压力
7. 时间限制采集：只采集最近指定小时内的数据，提高采集效率
8. 关键词过滤：过滤不需要的内容，减少无用数据
9. 标题替换：自动格式化和统一视频标题，提高数据质量
10. 灵活的代理池：支持从配置文件、TXT文件或API接口获取代理，提高采集稳定性

并发和请求延迟

{
    "threads": 5,
    "min_request_delay": 0.5,      
    "max_request_delay": 2.0
}

当采集工具运行出现问题时，您可以参考以下常见问题及解决方法。

注意事项

1. 请合理设置线程数和请求延迟，避免对源站点造成过大压力
2. 确保配置文件中的API密钥正确
3. 确保网络环境稳定，能够正常访问源站点和目标苹果CMS站点
4. 采集前建议先测试单个URL，确认数据格式正确
5. 分类名称映射功能依赖于内容标题，建议配置全面的关键词映射
6. 备注信息会显示在前端界面，建议简明扼要
7. 如配置max_size_mb，日志文件会在超过指定大小时自动轮换
8. 如配置rotate_daily且未设置max_size_mb，日志文件会在每天午夜自动轮换
9. 必须提供播放来源（vod_play_from或play_from字段），否则数据不会入库
10. 时间限制采集功能依赖于数据中的时间字段，如果数据没有时间字段或格式不支持，则此功能可能无效
11. 过滤功能会检查完整标题，建议使用唯一性强的关键词
12. 标题替换使用正则表达式，请确保规则正确，避免意外替换
13. 使用代理池时，请确保代理服务器格式正确且代理服务器可用
14. 建议使用付费代理服务或自建代理，免费代理通常不稳定且容易失效

常见错误及解决方法

运行参数

# 正常运行
python main.py

# 指定配置文件路径
python main.py -c custom_config.json

# 显示版本信息
python main.py -v