API 总览

页面地址：/pages/ · 站点：mhw.schwuaclawai.top

架构速览

MHW 分两层：站内 PHP/JSON API（浏览器与看板调用）和 第三方 / 外部服务（排名、抓取、模型、性能检测）。第三方结果写入 MySQL 后，各页面只读库展示，避免页面直连外网。

运营看板 → 站内 API → MySQL ← CLI/cron/worker ← 第三方（SerpAPI / SF / LLM / PSI / 抓取栈）

第三方服务一览

服务	用途	触发入口	写入表 / 缓存	环境变量 / 配置
SerpAPI `serpapi.com/search.json`	① 周排名抓取（目标 URL 位次 + 域名位次） ② SERP Top10 快照（有机结果标题/链接/摘要） ③ PAA / Related Searches 抓取	`/pages/ranking-job`、`cli/` 排名 worker `python/cli/serp_top10_snapshot.py` `cli/batch-fetch-keyword-paa.php`	`keyword_ranking_logs`（含 `serp_top10_json`） `mhw_keyword_paa_cache`	`MHW_SERPAPI_KEY` / `MHW_SERPAPI_KEYS`（多 key 故障转移） `MHW_SERPAPI_PAGE_DELAY_MS`、`MHW_SERPAPI_KEYWORD_DELAY_MS` `config/serpapi.local.php`、`config/ranking_scan.local.php`（gl=au, hl=en）
Screaming Frog SEO Spider 本地 CLI `screamingfrogseospider`	全站/补充 URL 爬取，导出内链明细（Inlinks），用于站内锚文统计、与计划内链对比	`scripts/screaming_frog_crawl_to_db.py` `scripts/run_screaming_frog_supplement.sh`（cron）	`sf_crawl_jobs` `sf_inlinks_detail`	服务器安装 SF CLI；`--project` 区分站点；无云端 API key
LLM（OpenAI 兼容网关）默认 `llm.azopenai.com/v1`	① TDH SERP 推荐 Title/Description/H1（GPT JSON） ② 内容优化：PAA 查询生成、聚类、全量诊断 ③ CWV 优化建议文案 ④ 垃圾外链域名行业分类	`/pages/tdh-serp-analysis-api` action=analyze `/pages/content-optimization-api` `/pages/target-url-cwv-advice-api` `cli/spam-backlinks-domain-industry-llm.php` `python/cli/content_optimization_worker.py`	`tdh_serp_analysis` `mhw_content_optimization_job` `target_url_cwv_advice_log` `spam_source_domain`	`AZOPENAI_API_KEY`、`AZOPENAI_BASE_URL`（读 `cur_project/.env.shared`）模型：`MHW_TDH_SERP_MODEL`、`MHW_CWV_ADVICE_MODEL`、`MHW_OPENAI_MODEL`、`ELITE_PREFILL_MODEL` 兜底：`config/openai.local.php`
Google PageSpeed Insights `pagespeedonline/v5/runPagespeed`	落地页 Core Web Vitals / Lighthouse 指标（mobile & desktop）	`/pages/target-url-cwv-api`（看板「重新检测」） `includes/target_url_dashboard.php`	`target_url_cwv_cache`（默认缓存 7 天）	`PAGESPEED_API_KEY` / `GOOGLE_PAGESPEED_API_KEY`（`cur_project/.env.shared`）
正文抓取栈 `canonical_body_stack`	竞品/目标 URL HTML 抓取 → 解析 TDH（Title、Meta、H1、正文片段）；链式降级：青果 Docker 浏览器 → ZenRows → ScraperAPI	`scripts/fetch_target_url_page_cache.py` `scripts/fetch_single_url_page_cache.py` `/pages/tdh-peer-landing-api` POST 刷新 TDH 看板「同步 H1」	`target_url_page_cache`	scrapers 栈密钥（与 Elite 同源，`cur_project/.env.shared`）；降级时 `ZENROWS_API_KEY`；脚本参数 `--driver canonical_body_stack`
ZenRows（抓取栈一环）	正文栈不可用或垃圾外链域名首页 403 时的 HTTP 代理抓取	`fetch_target_url_page_cache.py` fallback `includes/spam_backlinks_domain_crawl.php`	`target_url_page_cache`、spam 域名探测缓存	`ZENROWS_API_KEY`

说明：backlink_details、spam_backlinks 等外链数据来自 Excel/CSV 离线导入（非实时第三方 API）。关键词 Volume/KD 列与 SEMrush 导出表头对齐，但系统不直连 SEMrush API。

第三方调用与业务模块对应

业务模块	第三方依赖	本地规则引擎（不调模型）
周排名 / 首页排名展示	SerpAPI 有机扫描	`ranking_display.php` 批次可见性规则
TDH / SERP 工作区	SerpAPI Top10（先入库）→ 可选 LLM 建议	`tdh_serp_rule_engine.php` 规则分与动作
竞品 TDH 对比	canonical_body_stack 抓 HTML	读 `target_url_page_cache`，同类型页筛选
内容优化流水线	SerpAPI PAA + LLM 多步	SERP 规则前置、硬门槛评分
目标 URL 技术看板	PageSpeed API + LLM 建议	OnPage 缓存、SF 内链统计
单词看板 · 内链区块	Screaming Frog 导入数据	`internal_link_logs` 计划 vs 实际
垃圾外链治理	LLM 域名行业 + ZenRows 补抓	规则表、白名单、启发式

站内 API（PHP JSON，需登录 Session）

路径	主要 action	是否调第三方
`/pages/?api=1`	首页列表分页	否（只读库）
`/pages/editor-api`	list / get / save / import_* / export_*	否
`/pages/tdh-serp-analysis-api`	get / analyze / apply	analyze → LLM；输入来自库内 SERP 快照
`/pages/tdh-peer-landing-api`	GET 读缓存 / POST 触发抓取	POST → canonical_body_stack 脚本
`/pages/content-optimization-api`	get / run / tick / cancel	tick 推进 → PAA（SerpAPI 预抓取表）+ LLM
`/pages/target-url-cwv-api`	读缓存 / refresh	refresh → PageSpeed API
`/pages/target-url-cwv-advice-api`	生成建议	→ LLM

CLI / Python Worker（cron 或页面触发）

脚本	第三方
`cli/` 排名抓取 worker	SerpAPI（`includes/ranking_fetch_service.php` + SerpApiRankingCore）
`python/cli/serp_top10_snapshot.py`	SerpAPI → `serp_top10_json`
`cli/batch-fetch-keyword-paa.php`	SerpAPI PAA
`cli/tdh-serp-rule-refresh.php`	否（仅规则引擎写 `tdh_serp_analysis`）
`scripts/screaming_frog_crawl_to_db.py`	Screaming Frog CLI
`scripts/fetch_target_url_page_cache.py`	canonical_body_stack / ZenRows
`python/cli/content_optimization_worker.py`	LLM（`MHW_CONTENT_OPTIMIZATION_PYTHON=1` 时替代 PHP tick）
`cli/spam-backlinks-domain-industry-llm.php`	LLM 批量域名分类

环境加载：各入口通过 cur_project/.env.shared 或 bootstrap_workspace_env 读取共用密钥；PHP 抓取脚本使用 cur_project/.venv。

讲解时可强调的数据流

排名：每周 SerpAPI 任务 → keyword_ranking_logs → 首页/单词看板（批次完成后才展示）。
SERP 分析：同一批 SerpAPI 结果存 serp_top10_json → 规则引擎（免费）→ 按需点「GPT 建议」（消耗 LLM）。
内链：SF 定期爬全站入 sf_inlinks_detail；运营 Excel 导入执行记录到 internal_link_logs；看板对比两者。
内容优化：先 batch PAA（SerpAPI）→ 异步 job 多步 LLM → 结果落在 job 表与内容快照。
技术项：OnPage 来自抓取栈缓存；CWV 来自 Google PSI；建议文案来自 LLM。