短剧大数据监控系统 · 开发与使用手册全集

涵盖系统架构、所有 CLI 命令行指令、Laravel RESTful API 规范、短剧算法指标及 MySQL 数据字典

返回大盘指挥中心
快速检索目录
1. 系统整体架构设计

本系统采用 “业务与中枢管理（Laravel 10 + MySQL） $\longleftrightarrow$ 分布式采集引擎（Python + DouYin_Spider）” 的解耦架构。彻底摒弃了 Redis 强依赖，所有任务调度、并发锁及增量对比完全由 MySQL 轻量状态机接管。

架构分层核心组件与位置职责说明
管理中枢与视图 C:\wamp64\www\app (Laravel 10) 提供 AdminLTE 3 后台、批量导入多行链接、大盘指标看板、历史增长折线图、Excel 导出
调度与内部 API /api/v1/crawler/* 基于 MySQL crawl_status + next_crawl_at 进行原子锁任务派发，接收 Python 数据回传
数据采集 Worker D:\code\duanju\worker.py 常驻守护进程或计划任务，循环拉取任务、执行抖音 Web 抓取、解析短剧标签并回传入库
单号深度分析器 D:\code\duanju\spider.py 面向单个账号的独立深度分析与 Excel/Markdown 研报导出工具
底层逆向轮子 D:\code\duanju\DouYin_Spider 封装纯 Python 版 a_bogus 签名、DouyinAuth 凭证会话与官方 API
2. 命令行指令速查全集 (CLI Cheat Sheet)
2.1 批量采集 Worker 指令 (`worker.py`)

在 D:\code\duanju 目录下执行，负责从 Laravel 自动认领上百到上千个账号进行批量抓取：

# 1. 日常快速巡检：抓取各账号最新 30 条新集数，跑完自动退出 python worker.py --once --max-works 30 # 2. 单视频精准刷新 (靶向直查)：指定作品ID或链接，直接刷新最新数据并写入历史增量流水 python worker.py --refresh-video 7687929167865777444 # 3. 批量作品ID直查模式：提取库中已收录的历史作品ID批量精准刷新数据，绝不卡死！ python worker.py --once --full # 4. 强制全量重跑模式 (重点)：忽略下次计划时间，立刻强制重新刷一遍所有账号！ python worker.py --once --force --max-works 30 # 5. 一键重置状态：将数据库中所有账号的下次调度时间归零，全部变为就绪状态 python worker.py --reset-all # 6. 加大批次提高吞吐 (适合账号多、机器性能强场景，每批拉取 20 个) python worker.py --once --batch-size 20 --max-works 30 # 7. 常驻后台守护模式 (全天候自动化监控：抓完后休眠，到期自动唤醒继续增量巡检) python worker.py --max-works 30
参数默认值功能说明
--refresh-video IDNone单视频精准单查：指定单条视频 ID 或链接，秒级精准拉取最新点赞/收藏并入库
--onceFalse跑完当前所有待采账号后自动退出（适合手动触发或加入 Windows 计划任务）
--forceFalse强制忽略计划调度时间，把库中所有账号立即重新抓取一遍
--fullFalse作品ID直查刷新模式：直接提取库中已收录的作品 ID 单点直查，不走长游标翻页，彻底解决深层翻页卡死与旧视频漏刷问题
--video-delay N2.5单视频直查时的基准休眠秒数（带拟人化随机波动，防风控）
--account-delay N4.0账号与账号之间的基准休眠秒数（带拟人化随机波动）
--reset-allFalse调用 API 一键将数据库中所有账号的下次抓取时间清零，全部恢复待抓取
--max-works N30每个创作者最多处理的作品条数（与 --full 联用可限制刷新最新的前 N 条已入库作品）
--batch-size N10单次从 Laravel 认领的账号任务个数
--api-base URLhttp://localhost/api/v1/crawlerLaravel API 服务端地址
--interval N10队列暂无任务时的轮询休眠秒数（常驻模式下生效）
2.2 单账号深度分析脚本 (`spider.py`)

独立分析某个特定抖音账号，并在终端输出控制台看板、生成 Excel 及 Markdown 研报：

# 1. 基础用法：分析指定账号并导出 Excel、Markdown 和 JSON python spider.py https://www.douyin.com/user/MS4wLjABAAAAwxSwDD4RZfGj3siJd68Wbw9Iq7pkjx8TCT6C1d9ebPoG528yfM-KYkMEcTwmI4dY --max-works 50 # 2. 极速模式：跳过评论区采样，仅导出 50 条视频互动明细 Excel 表格 python spider.py https://www.douyin.com/user/MS4wLjABAAAAwxSw... --max-works 50 --no-comments --export xlsx # 3. 指定短剧进行卡点与留存衰减分析 python spider.py https://www.douyin.com/user/MS4wLjABAAAAwxSw... --target-drama "龙王赘婿"
2.3 Laravel 常用维护指令 (WAMP)
# 在 C:\wamp64\www\app 目录下使用 WAMP 的 PHP 运行 Artisan 指令： & "C:\wamp64\bin\php\php8.2.29\php.exe" artisan migrate # 执行未迁移的表结构 & "C:\wamp64\bin\php\php8.2.29\php.exe" artisan route:list # 查看全部路由与 API & "C:\wamp64\bin\php\php8.2.29\php.exe" artisan config:clear # 清理配置缓存
3. Laravel 内部 API 规范全景
GET /api/v1/crawler/tasks —— 采集器拉取待抓取任务（加锁防并发）

从 MySQL 查询当前已到期（next_crawl_at <= NOW()）且状态为 idle 的账号，并在事务中原子置为 running，防止多个 Worker 重复采集。

请求 Query 参数：
参数名类型必填说明
limitinteger否本次拉取最大数量（默认 10，上限 100）
worker_idstring否采集节点标识，如 worker-1
forceboolean否传 1 时忽略计划时间，强制认领全部账号
响应 JSON 格式示例：
{ "code": 200, "count": 1, "tasks": [ { "id": 1, "sec_uid": "MS4wLjABAAAAwxSwDD4RZfGj3siJd68Wbw9Iq7pkjx8TCT6C1d9ebPoG528yfM-KYkMEcTwmI4dY", "unique_id": "fuxiaofan365", "nickname": "傅小凡老师", "url": "https://www.douyin.com/user/MS4wLjABAAAAwxSwDD4...", "priority": "S", "latest_aweme_id": "7688562860029209818" // 该账号库中最新视频，用于做增量比对跳出 } ] }
POST /api/v1/crawler/sync-data —— 采集数据回传与批量 Upsert 入库

Python 采集完成后回传，服务端自动更新账号画像、生成每日增长快照、对视频表以 aweme_id 做 Upsert，记录单视频增量流水，并顺延下一次抓取时间。

请求 Body (JSON) 结构：
{ "account_id": 1, "sec_uid": "MS4wLjABAAAAwxSw...", "worker_id": "worker-1", "duration_ms": 3200, "account_info": { "nickname": "某某短剧场", "unique_id": "drama_theater", "avatar": "https://p3.douyinpic.com/...", "signature": "正片持续更新，点击置顶追剧", "ip_location": "浙江", "follower_count": 685000, "total_favorited": 8920000, "aweme_count": 45, "following_count": 28 }, "works": [ { "work_id": "7400000001", "title": "《龙王赘婿》第01集：三年之期已到", "desc": "战神回归都市！#微短剧 #战神", "topics": ["微短剧", "战神"], "parsed_drama_type": "真人剧", "parsed_drama_title": "龙王赘婿", "parsed_episode": 1, "parsed_hooks": ["打脸", "身份亮明"], "digg_count": 128500, "comment_count": 6420, "collect_count": 21300, "share_count": 12400, "create_time": 1728000000, "video_cover": "https://...", "video_addr": "https://..." } ] }
POST /api/v1/crawler/report-error —— 采集异常上报与熔断

当触发反爬风控、验证码或 Cookie 失效时调用，将账号置为 failed 状态，并记录在爬虫流水日志中。

{ "account_id": 1, "sec_uid": "MS4wLjAB...", "worker_id": "worker-1", "error_message": "触发抖音人机滑块验证码拦截 (bdturing)" }
4. 云端 MCP 智能体服务与部署 (www.httpadd.com)

本系统内置完整的 MCP (Model Context Protocol) 协议服务端 (mcp_server.py)，支持线上远程网络 SSE (Server-Sent Events) 长连接传输，以及本地 stdio 管道直连。大模型（如 Claude Desktop / Cursor / Dify 等）可直接通过自然语言调用爬虫执行抓取、查询指标、以及自动生成并推送研报。

4.1 开放的 8 大 AI 智能体工具 (Tools)
工具名称 (Tool)类型核心功能适用对话场景
get_market_overview只读查询调取当前大盘账号总数、视频总数、三剧种占比分布与平均收藏率“分析一下当前大盘整体情况”、“AI短剧占比多少”
get_top_viral_videos只读查询获取爆款视频榜单（支持按点赞、追剧收藏率、争议评论率排序）“挑出最近收藏率最高的3个AI短剧”、“今天点赞最高的有哪些”
get_series_cliff_analysis只读查询查询指定短剧的留存衰减瀑布与系统推定的付费卡点集数诊断“分析《督军府大小姐》在哪一集出现断崖”、“付费卡点设在第几集”
get_account_growth_trend只读查询调取指定创作者的历史每日粉丝与点赞增量流水“看一下‘月光剧场’这几天的吸粉涨赞走势”
add_and_crawl_account写操作输入抖音主页链接，自动提取 sec_uid 录入数据库并立即触发抓取“帮我监控这个新短剧账号：https://www.douyin.com/user/...”
refresh_single_video写操作指定单条视频 ID 或链接，秒级精准刷新最新点赞/收藏并入库“刷新一下 7687929167865777444 这个视频的点赞”
reset_all_crawler_tasks写操作一键清空全盘账号的计划时间，全部设为就绪（从头重跑）“把所有账号调度重置，准备重抓”
send_notification_briefing消息推送将生成的分析 Markdown 研报推送到飞书、企业微信或钉钉群机器人“把刚才的分析结果生成简报发到我的飞书群”
4.2 客户端接入配置示例 (Claude Desktop / Cursor)
线上远程 SSE 模式 (配置 www.httpadd.com):
// 放到 claude_desktop_config.json { "mcpServers": { "duanju_online": { "url": "https://www.httpadd.com/sse", "headers": { "Authorization": "Bearer 你的MCP秘钥" } } } }
本地 stdio 模式 (直接连接本机 Python 脚本):
// 放到 claude_desktop_config.json { "mcpServers": { "duanju_local": { "command": "python", "args": [ "D:\\code\\duanju\\mcp_server.py", "--transport", "stdio" ] } } }
4.3 线上生产部署一键配置文件清单
配置文件存放路径功能说明
deploy.sh项目根目录Ubuntu 22.04 一键自动部署脚本（自动安装 PHP8.2, Nginx, Python3, MCP依赖, 迁移数据库）
nginx_httpadd.conf项目根目录Nginx 生产配置，支持 HTTPS，将 Web/API 分流给 PHP-FPM，将 /sse 分流给 Python MCP
supervisor/mcp-server.confsupervisor/Supervisor 进程守护：确保 Python MCP 服务（端口 8080）7x24小时常驻运行，崩溃秒级自启
supervisor/douyin-worker.confsupervisor/Supervisor 进程守护：确保 Python 采集 Worker 全天候按优先级巡检 300+ 账号更新
5. 短剧核心商业指标与算法公式
指标名称 计算公式 行业基准区间 短剧业务商业价值与诊断含义
1. 赞粉比
(Likes / Fans)		 总获赞量 / max(粉丝量, 1) 常规：3 ~ 8
极高：> 12		 衡量账号内容吸粉能级。若赞粉比极高但粉丝少，说明爆款多但用户大多“只点赞不关注”，需优化账号主页置顶合集与主页引流钩子。
2. 追剧收藏率
(Collect Rate)		 收藏数 / max(点赞数, 1) 普通：5% ~ 10%
高黏性：> 15%
爆款钩子：> 25%		 短剧最核心的“存留书签”指标！用户点击收藏代表强烈期待接续观看后续剧集。当某集收藏率激增，说明该集正是绝佳付费卡点或小程序承接集。
3. 深度评论率
(Comment Rate)		 评论数 / max(点赞数, 1) 常规：3% ~ 6%
高争议：> 8%		 反映剧情冲突拉扯感与话题讨论度。真人爽剧的“打脸亮明身份”集，或 AI 短剧的“画风技术评价”通常出现评论率高峰。
4. 裂变分享率
(Share Rate)		 分享数 / max(点赞数, 1) 常规：1% ~ 2%
高传播：> 5%		 反映社交货币价值（用户自发转发至群聊/私信）。多见于极度猎奇、高设定反差、或超现实 AI 短剧内容。
5. 付费断崖卡点
(Paywall Cliff)		 (前集点赞 - 当集点赞) / 前集点赞 断崖阈值：≥ 50% ~ 70% 逆向推算竞品的小程序引导断点。例如第 10 集点赞 9.6 万，第 11 集骤降至 7800（跌幅 -91.9%），系统自动断定第 10 集为免费引流卡点集。
6. MySQL 数据库数据字典
① `douyin_accounts` (账号主表)
  • sec_uid (VARCHAR 150, UNIQUE)：抖音账号全局唯一加密标识
  • nickname, unique_id, avatar, signature：账号展示属性
  • follower_count, total_favorited, aweme_count：最新大盘指标
  • primary_drama_type：AI剧 / 漫剧 / 真人剧 / 其他
  • priority：S 级 (2h)、A 级 (6h)、B 级 (12h)、C 级 (24h)
  • crawl_status：idle (就绪) / running (采集中) / failed (失败)
  • next_crawl_at：调度时间戳索引（替代 Redis 任务池）
② `douyin_videos` (短视频明细表)
  • aweme_id (VARCHAR 64, UNIQUE)：作品全局唯一 ID (防重核心)
  • drama_type, drama_title, episode, hooks：短剧语义提取
  • digg_count, comment_count, collect_count, share_count：互动数据
  • comment_rate, collect_rate, share_rate：互动衍生比率
  • video_cover, video_addr, published_at：媒体源地址与时间
③ `account_metrics_history` (账号每日快照表)
  • account_id, snapshot_date (联合唯一索引)
  • follower_delta：较昨日净增粉丝数
  • favorited_delta：较昨日净增点赞数
  • 用于生成账号 30 天粉丝走势与增长拐点折线图
④ `video_metrics_history` (视频增量流水表)
  • video_id, recorded_at：每次 Worker 抓取记录一个时间点
  • digg_delta：两次抓取之间的点赞净增突跃量
  • collect_delta：追剧收藏净增突跃量
  • 用于单视频流量爆发点识别与算法推流走势图
7. 运维排错与常见问题 (FAQ)
Q1: 运行 `worker.py` 提示“当前所有待抓取账号已全部采集完成！累计处理 0 个账号”？
原因：系统上一轮已经成功把所有账号全部抓取入库，并自动把下一次轮询时间推迟到 24 小时后。当前时刻没有“到期”账号，所以返回 0。
解决办法：若需要立即强制重新刷新所有账号，只需加入 --force 参数：
python worker.py --once --force --max-works 30
Q2: 多次重复抓取同一个账号，视频数据会不会重复变多？
不会。数据库采用 aweme_id 作为主键唯一索引进行 updateOrCreate。已有视频只会刷新点赞、收藏等最新数值，并追加一条历史时间快照用于绘制折线图，绝不产生重复记录。
Q3: 提示 `UIFID Not Found` 或 Cookie 失效如何更新？
解决步骤：
1. 在 PC 浏览器打开 www.douyin.com 并登录个人账号；
2. 按 F12 打开控制台，在【网络(Network)】中筛选 /aweme/v1/web/ 开头的请求；
3. 复制请求头中的完整 Cookie（确保字符串中包含 UIFID=... 字段）；
4. 粘贴到 D:\code\duanju\.env 和 C:\wamp64\www\app\.env 的 DY_COOKIES='...' 中保存即可。
Q4: 如何避免上百个账号连续抓取时触发抖音风控？
worker.py 已经内置了 2.0 ~ 3.5 秒 的随机抖动休眠；建议单机单进程运行，批次大小保持在 10~20 个账号，既能稳定在半小时内刷完 300 多个账号，又能完全规避 IP 封禁与滑块验证。