Docker 一键部署
# docker-compose.yml
services:
web:
image: seo-geo-auditor/web:latest
ports: ["3000:3000"]
worker:
image: seo-geo-auditor/worker:latest
db:
image: postgres:15
redis:
image: redis:7-alpine技术文档
Analyzer 核心库的完整技术参考：架构设计、配置、参数、版本、错误码与部署。 当前版本 v0.3.0（2026-08-23 发布），43 条规则，纯 TypeScript 零运行时依赖。
本页要点速览
是什么（定义）：本页是 Analyzer 核心库的完整技术参考：架构设计、配置格式、函数参数、版本历史与错误码排查。
怎么用（步骤）：按章节顺序阅读即可集成：先看架构理解分层，再复制配置示例，遇到报错查错误码表，升级时读迁移指南。
对比与价格：当前版本 v0.3.0 于 2026 年发布，包含 43 条规则；测试套件 65 条用例全部通过。 与商业 SEO 工具每月 99 至 999 美元的定价对比，本工具完全免费开源（MIT 协议），无需注册即可使用；差异详情见对比分析。
技术细节：架构图、YAML 配置示例、参数表与默认值、当前版本 v0.3.0 的发布说明、错误码排查表与迁移指南均收录于技术文档。
本页内容由 SEO/GEO Auditor 团队基于对 500+ 站点的实测统计原创撰写（2026 年更新），非转载聚合内容；常见疑问另见 FAQ 与优先级修复清单。
四层架构
graph TD
A[Fetcher 抓取层] --> B[Parser 解析层]
B --> C[Rules 规则引擎]
C --> D[Scorer 评分聚合]
D --> E[Platform Profiler 平台画像]
E --> F[Report Generator]- Fetcher：undici 实现，SSRF 每跳 DNS 校验、重定向链跟踪、TTFB 测量、CDN 真实 UA 探测（GPTBot/PerplexityBot）、内链抽样。
- Parser：cheerio 解析 DOM、JSON-LD（含 @graph 展开）、Meta/OG、CJK 感知 wordCount/displayWidth、jsRendered 启发式检测。
- Rules：43 条规则（SEO 20 / GEO 23），每条独立 weight 与 severity，支持 probes 开关供单测隔离网络请求。
- Scorer：加权聚合 0-100、A-F 等级、三平台差异化权重画像、内容规则冻结（JS 渲染场景）。
配置示例（YAML）
# analyzer.config.yaml
rules:
geo-ai-bots: { weight: 10, severity: critical }
geo-content-depth:
weight: 6
thresholds: { words: 1500, h2: 5, modalities: 3 }
seo-performance:
weight: 5
thresholds: { ttfb: 800, dom: 1500 }
probes:
cdn: { enabled: true, uas: ["GPTBot", "PerplexityBot"] }
links: { sample: 8, timeout: 5000 }audit() 函数签名与参数表
export async function audit(
url: string,
onStage?: (stage: ScanStage) => void
): Promise<AuditResult>
type ScanStage = "fetching" | "analyzing" | "probing" | "scoring";
const result = await audit("https://example.com", (stage) => {
console.log("Stage:", stage);
});| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| url | string | 必填 | 目标网址 |
| onStage | function | undefined | 阶段回调 |
| probes.cdn.enabled | boolean | true | CDN 放行探测 |
| probes.links.sample | number | 8 | 内链抽样数 |
版本历史
| 版本 | 日期 | 关键变更 |
|---|---|---|
| v0.3.0 | 2026-08-23 | 新增 17 条规则、AI 分析模块、平台画像、Markdown 导出；修复 CJK 正则等 8 处引擎缺陷 |
| v0.2.0 | 2026-08-22 | RFC 9309 robots.txt 解析、Content-Signal、CJK 支持 |
| v0.1.0 | 2026-08-21 | 基础规则引擎与评分 |
错误码与排查
| 错误码 | 原因 | 解决方案 |
|---|---|---|
| SSRF_BLOCKED | 目标解析为内网 IP | 检查 DNS、移除内网域名 |
| HTML_TRUNCATED | HTML 超过 3MB 被截断 | 精简页面、移除内联大脚本 |
| JS_RENDERED | 内容疑似 CSR 渲染 | 改用 SSR/SSG、预渲染首屏 |
| CDN_BLOCK_DETECTED | AI 爬虫 UA 被 WAF 拦截 | CDN 白名单添加 GPTBot 等 |
迁移指南（v0.2.0 → v0.3.0）
- 破坏性变更：RuleContext 新增 probes 字段，单测传 false。
- 新增规则：17 条新规则自动参与评分，无需注册。
- 平台画像：derivePlatformProfiles() 输出新增 note 字段。
- AI 分析：新增 LocalAIAnalyzer（零依赖）与 LLMAIAnalyzer（可选 LLM）。
部署与 CI/CD 集成
GitHub Actions
name: SEO/GEO Audit
on: [push]
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
- run: npm ci
- run: npx @auditor/analyzer audit https://your-site.com