MacCMS API 视频管理系统

🎯 项目简介

MacCMS API 视频管理系统是一个基于 FastAPI 的视频数据采集和管理平台，提供完整的 MacCMS 兼容 API，支持多站点视频数据采集、分类管理、搜索功能等。

核心特性

• 🚀 高性能: 基于 FastAPI 框架，支持异步处理
• 📺 多站点支持: 支持多个视频站点数据采集
• 🗂️ 智能分类: 统一的分类映射体系
• 🔍 全文搜索: 支持视频标题、演员、导演等搜索
• 📱 MacCMS兼容: 完全兼容 MacCMS API 规范
• 🎬 播放支持: 支持多种播放源和格式
• 📊 数据统计: 完整的统计数据和分析
• 🔄 自动更新: 支持定时采集和数据更新

🚀 快速开始

环境要求

• Python 3.8+
• SQLite 3
• 网络连接

安装依赖

# 克隆项目
git clone <repository-url>
cd video

# 安装依赖
pip install -r requirements.txt

# 激活虚拟环境（推荐）
python -m venv .venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # Linux/Mac

启动服务

# 方法1: 使用重启脚本（推荐）
python restart_service.py

# 方法2: 直接启动
python -m uvicorn app:app --host 0.0.0.0 --port 8000

# 方法3: 使用启动脚本
python start_server.py

访问服务

• API地址: http://127.0.0.1:8000/maccms/api/vod
• 文档地址: http://127.0.0.1:8000/docs
• 健康检查: http://127.0.0.1:8000/maccms/api/vod/?ac=list

📋 API 接口

基础接口

获取分类列表

GET /maccms/api/vod/?ac=list

响应示例:

{
  "code": 1,
  "msg": "数据列表",
  "page": 1,
  "pagecount": 5,
  "total": 100,
  "list": [...],
  "class": [
    {
      "type_id": 1,
      "type_name": "电影片",
      "type_pid": 0
    }
  ]
}

搜索视频

GET /maccms/api/vod/?ac=search&wd=关键词

获取视频详情

GET /maccms/api/vod/?ac=detail&ids=视频ID

获取播放地址

GET /maccms/api/vod/?ac=play&ids=视频ID

分类筛选

按分类ID筛选

GET /maccms/api/vod/?ac=list&t=30&pg=1

按年份筛选

GET /maccms/api/vod/?ac=list&year=2025&pg=1

按地区筛选

GET /maccms/api/vod/?ac=list&area=韩国&pg=1

🏗️ 项目结构

d:\project\video\
├── api/                    # API接口模块
│   ├── maccms.py          # MacCMS API实现
│   ├── progress.py        # 采集进度接口
│   ├── scrape.py          # 数据采集接口
│   ├── site_status.py     # 站点状态接口
│   └── stats.py           # 统计数据接口
├── config/                 # 配置模块
│   ├── database.py        # 数据库配置
│   └── settings.py        # 应用设置
├── database/              # 数据库模块
│   ├── connection.py      # 数据库连接
│   └── operations.py      # 数据库操作
├── models/                # 数据模型
│   └── video.py           # 视频数据模型
├── scrapers/              # 爬虫模块
│   ├── base.py            # 基础爬虫类
│   └── maccms.py          # MacCMS爬虫实现
├── utils/                 # 工具模块
│   ├── category_mapper.py # 分类映射器
│   ├── data_source.py     # 数据源管理
│   ├── maccms_formatter.py # MacCMS格式化器
│   ├── logger.py          # 日志工具
│   ├── backup.py          # 备份工具
│   └── monitor.py         # 监控工具
├── test/                  # 测试脚本
├── md/                    # 文档目录
├── backups/               # 备份文件
├── logs/                  # 日志文件
├── static/                # 静态文件
├── templates/             # 模板文件
├── app.py                 # FastAPI应用主文件
├── main.py                # 视频采集主逻辑
├── restart_service.py     # 服务重启脚本
├── start_server.py        # 服务启动脚本
├── requirements.txt       # 依赖包列表
├── .env                   # 环境变量配置
└── video_data.db          # SQLite数据库文件

🎬 功能特性

数据采集

多站点支持

• 支持多个视频站点同时采集
• 自动站点状态检测
• 智能重试机制
• 并发采集控制

分类管理

• 统一的分类映射体系
• 自动分类识别和映射
• 支持自定义分类规则
• 分类数据持久化存储

数据处理

• 自动去重和合并
• 数据清洗和标准化
• 播放地址解析
• 多语言支持

API功能

MacCMS兼容

• 完全兼容MacCMS API规范
• 支持TVBox等客户端
• 标准化的响应格式
• 完整的字段映射

搜索功能

• 全文搜索支持
• 多字段搜索
• 模糊匹配
• 结果排序

分页支持

• 灵活的分页参数
• 总数统计
• 页码导航
• 性能优化

系统管理

监控功能

• 实时系统状态
• 采集进度监控
• 错误日志记录
• 性能统计

备份恢复

• 自动数据备份
• 手动备份功能
• 数据恢复工具
• 备份文件管理

配置管理

• 站点配置管理
• 采集参数配置
• 系统设置配置
• 环境变量配置

🔧 配置说明

环境变量

创建 .env 文件：

# 数据库配置
DATABASE_URL=sqlite:///./video_data.db

# 服务配置
HOST=0.0.0.0
PORT=8000
DEBUG=false

# 日志配置
LOG_LEVEL=INFO
LOG_FILE=logs/app.log

# 采集配置
MAX_WORKERS=4
REQUEST_TIMEOUT=30
RETRY_TIMES=3

站点配置

修改 db.json 文件：

{
  "sites": [
    {
      "key": "ffzy",
      "name": "飞飞影视",
      "api": "https://api.ffzyapi.com",
      "active": true,
      "timeout": 30,
      "retry_times": 3
    }
  ]
}

📱 客户端配置

TVBox配置

{
  "key": "local_maccms",
  "name": "本地MacCMS",
  "type": 3,
  "api": "http://127.0.0.1:8000/maccms/api/vod",
  "searchable": 1,
  "quickSearch": 1,
  "filterable": 1
}

其他客户端

支持所有MacCMS兼容的客户端，如：

• TVBox
• 饭太硬
• 猫影视
• 等等

🧪 测试和调试

运行测试

# 运行所有测试
python test/test_maccms_api.py

# 测试API功能
python test/test_api_type_id.py

# 测试数据采集
python test/test_real_scraping.py

# 测试服务状态
python test/test_web_service.py

调试工具

# 调试API响应
python test/debug_api.py

# 调试数据源
python test/debug_data_size.py

# 调试分类映射
python test/test_category_mapping.py

性能测试

# 性能测试
python test/test_performance.py

# 并发测试
python test/test_threading_fix.py

# 站点状态测试
python test/test_site_status.py

📊 数据统计

系统统计

# 获取基础统计
curl "http://127.0.0.1:8000/api/stats"

# 获取站点统计
curl "http://127.0.0.1:8000/api/stats/sites"

# 获取分类统计
curl "http://127.0.0.1:8000/api/stats/categories"

# 获取年份统计
curl "http://127.0.0.1:8000/api/stats/years"

# 获取最近添加的视频
curl "http://127.0.0.1:8000/api/stats/recent"

# 获取每日增长统计
curl "http://127.0.0.1:8000/api/stats/growth"

# 获取系统健康状态
curl "http://127.0.0.1:8000/api/health"

# 获取站点状态
curl "http://127.0.0.1:8000/api/sites/status"

# 获取站点配置
curl "http://127.0.0.1:8000/api/sites"

# 获取采集进度
curl "http://127.0.0.1:8000/api/progress"

# 获取采集日志
curl "http://127.0.0.1:8000/api/logs"

# 获取所有任务状态
curl "http://127.0.0.1:8000/api/tasks"

数据分析

• 视频总数统计
• 分类分布统计
• 站点数据统计
• 采集进度统计
• 错误率统计

🔄 数据管理

数据采集

# 启动数据采集
python main.py

# 按站点采集
python main.py --site ffzy

# 按分类采集
python main.py --category 30

数据备份

# 手动备份
python utils/backup.py

# 自动备份（定时）
python utils/monitor.py --backup

数据清理

# 清理过期数据
python database/operations.py --cleanup

# 重建索引
python database/operations.py --rebuild

🛠️ 开发指南

添加新站点

1. 在 db.json 中添加站点配置
2. 在 scrapers/ 目录下创建爬虫类
3. 继承 BaseScraper 类
4. 实现必要的方法

扩展API

1. 在 api/ 目录下创建新的API文件
2. 定义FastAPI路由
3. 实现业务逻辑
4. 添加到主应用中

自定义分类

1. 修改 utils/category_mapper.py
2. 添加分类映射规则
3. 更新数据库结构
4. 测试分类功能

📝 更新日志

v1.0.0 (2026-03-18)

• ✨ 初始版本发布
• 🚀 基础API功能实现
• 📺 多站点数据采集支持
• 🗂️ 统一分类映射系统
• 🔍 全文搜索功能
• 📱 MacCMS兼容API
• 📊 数据统计功能
• 🔄 自动更新机制

近期更新

• 🔧 修复type_id字段缺失问题
• 🚀 服务端口改为8000
• 📁 项目目录结构优化
• 🛠️ 重启脚本优化
• 📝 完善文档说明

🤝 贡献指南

开发环境设置

1. 克隆项目
2. 创建虚拟环境
3. 安装依赖
4. 配置环境变量
5. 运行测试

提交规范

• 使用清晰的提交信息
• 遵循代码规范
• 添加必要的测试
• 更新文档

问题反馈

• 使用GitHub Issues
• 提供详细的错误信息
• 包含复现步骤
• 标明环境信息

📄 许可证

本项目采用 MIT 许可证，详见 LICENSE 文件。

🙏 致谢

感谢以下开源项目：

• FastAPI - 现代化的Python Web框架
• SQLAlchemy - Python SQL工具包
• uvicorn - ASGI服务器
• requests - HTTP库

📞 联系方式

• 项目主页: [GitHub Repository]
• 问题反馈: [GitHub Issues]
• 技术交流: [Discord/微信群]

---

🎊 感谢使用 MacCMS API 视频管理系统！

如果这个项目对您有帮助，请给个⭐️支持一下！