这个项目能做什么

## 概述 Traffic Analytics 是一个专为 Ghost 站点设计的 Web 分析代理。它拦截由 Ghost 的 `ghost-stats.js` 脚本发出的 `POST /api/v1/page_hit` 调用，增强有效负载（User-Agent 解析、来源分析、用户签名生成），并将数据转发至 Tinybird 的 `/v0/events` API，最终存储在 ClickHouse 数据库中。 ## 架构与运行模式 - **批处理模式 (默认)** – 接收服务验证请求、过滤机器人，并将原始事件发布到 Google Cloud Pub/Sub 主题。一个独立的 Worker 消费该订阅，对每个事件进行增强，将其分批并转发至 Tinybird。这种方式将请求处理与数据摄入解耦，提高了吞吐量。 - **代理模式 (同步)** – 当未配置 Pub/Sub 主题时，接收服务在同一个 HTTP 周期内直接进行增强处理，并将请求代理至 Tinybird。 运行模式通过 `WORKER_MODE` 环境变量以及 `PUBSUB_TOPIC_PAGE_HITS_RAW` 是否存在来选择。 ## 核心功能 - 用于检测操作系统、浏览器和设备的 User-Agent 解析。 - 来源 URL 的解析与分类。 - 具有每日轮换盐值的隐私保护用户签名。 - 可选的 `x-ghost-bot-detected: true` 响应头，用于标识被过滤的机器人流量。 ## 配置 将 `.env.example` 复制为 `.env` 并调整数值。重要变量包括： - `WORKER_MODE` – `worker` 或 `ingest`。 - `PUBSUB_TOPIC_PAGE_HITS_RAW` – 定义批处理模式。 - `ENABLE_BOT_DETECTION_HEADER` – 切换机器人检测响应头。 ## 开发工作流 1. **前提条件** – Docker (Desktop 或 Orbstack) 和 Docker Compose。 2. 克隆仓库并运行 `pnpm dev` 以启动所有服务；分析 API 将可通过 `http://localhost:3000` 访问。 3. 如需与 Ghost 检出版本进行本地集成，在本仓库运行 `pnpm dev:ghost`，并在 Ghost 仓库运行 `pnpm dev:analytics:local`。这将通过共享的 Docker 网络将两个容器连接在一起。 ### 多工作树 (Multi-Worktree) 支持 本项目支持同时运行多个 Git 工作树。每个工作树使用自己的 `.env` 文件来设置唯一的端口、Docker Compose 项目名称和隔离的卷，从而实现并行开发而不会产生端口冲突。 ## 测试与 Linting - `pnpm test:types` – TypeScript 类型检查。 - `pnpm test:unit` – 单元测试。 - `pnpm test:integration` – 集成测试。 - `pnpm test:e2e` – 使用 WireMock 的端到端测试。 - `pnpm lint` – ESLint 代码检查。 所有测试命令均在 Docker 容器内运行，以确保环境一致性。 ## 部署流水线 - **分支工作流** – 提交 PR，可选地标记 `deploy-staging` 以触发预发布环境部署。 - **合并操作** – 自动提升补丁版本号、创建 Git 标签、发布 Docker Hub 镜像、部署至 Cloud Run 的预发布和生产环境、执行健康检查并发送 Slack 通知。 - **手动触发** – 使用 GitHub Actions UI 通过 `workflow_dispatch` 运行 "Deploy" 工作流。 完整的 CI/CD 详情请参阅 `docs/deployment.md`。 ## 文档 - `docs/architecture.md` – 关于批处理与代理模式、Pub/Sub 流水线、OpenTelemetry 和 Worker 设计的详细图表。 - `docs/deployment.md` – CI/CD 流水线、预发布/生产流程及回滚程序。 ## 许可证 MIT © Ghost Foundation (2013‑2026)。