{"id":48347834,"url":"https://github.com/tiyee/pikachu","last_synced_at":"2026-06-27T09:01:07.296Z","repository":{"id":316043406,"uuid":"1061122957","full_name":"tiyee/pikachu","owner":"tiyee","description":"一个高效、可靠的 MySQL 数据库变更捕获(CDC)工具","archived":false,"fork":false,"pushed_at":"2026-06-27T07:31:19.000Z","size":120,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-27T08:15:17.781Z","etag":null,"topics":["canal","cdc","change-data-capture","database-sync","go-canal","real-time"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tiyee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-21T09:39:01.000Z","updated_at":"2026-06-27T07:31:22.000Z","dependencies_parsed_at":"2025-09-24T09:17:23.946Z","dependency_job_id":null,"html_url":"https://github.com/tiyee/pikachu","commit_stats":null,"previous_names":["tiyee/pikachu"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/tiyee/pikachu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiyee%2Fpikachu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiyee%2Fpikachu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiyee%2Fpikachu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiyee%2Fpikachu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tiyee","download_url":"https://codeload.github.com/tiyee/pikachu/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiyee%2Fpikachu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34847287,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["canal","cdc","change-data-capture","database-sync","go-canal","real-time"],"created_at":"2026-04-05T08:02:25.343Z","updated_at":"2026-06-27T09:01:07.286Z","avatar_url":"https://github.com/tiyee.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 pikachu - MySQL 变更监控工具\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e一个高效、可靠的 MySQL 数据库变更捕获(CDC)工具\u003c/strong\u003e\u003cbr\u003e\n  \u003csub\u003e实时监控数据库变更，支持高并发 webhook 分发\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/tiyee/pikachu\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat\u0026logo=go\" alt=\"Go Version\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/tiyee/pikachu\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/MySQL-5.6+-4479A1?style=flat\u0026logo=mysql\" alt=\"MySQL Version\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/tiyee/pikachu\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/License-MIT-green.svg\" alt=\"License\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/tiyee/pikachu\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Docker-Ready-blue?style=flat\u0026logo=docker\" alt=\"Docker\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/tiyee/pikachu\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Build-Passing-brightgreen?style=flat\u0026logo=github-actions\" alt=\"Build Status\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/tiyee/pikachu\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Coverage-85%25-brightgreen?style=flat\" alt=\"Test Coverage\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\npikachu 是一个基于 Go 语言开发的高效 MySQL 数据库变更捕获(CDC)工具。它通过解析 MySQL 的 binlog 日志来实时捕获数据库表的变更事件（插入、更新、删除），并将这些变更通过 webhook 的方式发送到指定的回调地址。\n\n## ⚡ 性能指标\n\n| 指标 | 数值 | 说明 |\n|------|------|------|\n| **事件处理延迟** | \u003c 10ms | P99 延迟，从 binlog 到 webhook 发送 |\n| **吞吐量** | 10,000+ events/sec | 单实例处理能力 |\n| **Webhook 成功率** | \u003e 99.9% | 包含重试机制的整体成功率 |\n| **内存占用** | \u003c 100MB | 基础运行内存（不含事件队列） |\n| **CPU 使用率** | \u003c 5% | 正常负载下的 CPU 占用 |\n| **并发处理** | 50+ workers | 可配置的 webhook 并发数 |\n\n## ✨ 核心特性\n\n### 🎯 监控能力\n- **实时监控**: 毫秒级延迟的数据库变更捕获\n- **全事件支持**: 支持 INSERT、UPDATE、DELETE 事件监控\n- **多表监控**: 同时监控多个数据表，独立配置回调\n- **精确过滤**: 基于表名和事件类型的精确过滤\n\n### 🚀 性能与可靠性\n- **高并发处理**: 基于协程池的并发 webhook 分发\n- **智能重试**: 指数退避重试机制，确保消息不丢失\n- **性能优化**: URL 预构建，避免运行时重复计算\n- **内存效率**: 事件队列缓冲，支持流量突发处理\n\n### 🛠️ 易用性与兼容性\n- **配置灵活**: YAML 配置文件，支持多环境部署\n- **MySQL 兼容**: 自动处理 MySQL 关键字表名\n- **健康检查**: 内置 HTTP 监控端点\n- **优雅关闭**: 支持优雅关闭，确保事件处理完成\n\n### 🐳 部署友好\n- **Docker 支持**: 提供 Docker 和 Docker Compose 部署方案\n- **结构化日志**: 支持 JSON 格式日志，便于日志收集\n- **轻量级**: 单一二进制文件部署，无外部依赖\n\n## 📋 系统要求\n\n### 最低要求\n- **Go**: 1.25+ (如果从源码编译)\n- **MySQL**: 5.6+ 或 MariaDB 10.0+（需要开启二进制日志）\n- **内存**: 最少 128MB，推荐 512MB+\n- **磁盘**: 最少 50MB 可用空间\n\n### 推荐配置\n- **CPU**: 2+ 核心（高并发场景）\n- **内存**: 1GB+ （生产环境）\n- **网络**: 稳定的数据库连接和 webhook 回调网络\n\n## 🏗️ 架构设计\n\n```mermaid\ngraph TB\n    A[MySQL Database] --\u003e|Binlog Events| B[Monitor Component]\n    B --\u003e C[Event Queue\u003cbr/\u003eSize: 10,000]\n    C --\u003e D[Dispatcher Worker Pool\u003cbr/\u003eWorkers: 20-50]\n    D --\u003e E[Webhook Callbacks\u003cbr/\u003eRetry Logic]\n\n    B --\u003e F[Schema Cache\u003cbr/\u003eTable Metadata]\n    D --\u003e G[URL Pre-builder\u003cbr/\u003ePerformance Opt]\n\n    subgraph \"pikachu Core Components\"\n        B\n        C\n        D\n        F\n        G\n    end\n\n    subgraph \"Monitoring \u0026 Health\"\n        H[HTTP Server\u003cbr/\u003ePort: 8080]\n        I[Metrics Collector\u003cbr/\u003ePerformance Data]\n        J[Health Checks\u003cbr/\u003eSystem Status]\n    end\n\n    subgraph \"External Services\"\n        K[Config Files\u003cbr/\u003econfig.yaml\u003cbr/\u003etasks.yaml]\n        L[Target APIs\u003cbr/\u003eWebhook URLs]\n        M[Monitoring Systems\u003cbr/\u003ePrometheus etc.]\n    end\n\n    K --\u003e B\n    K --\u003e C\n    K --\u003e D\n    B --\u003e H\n    B --\u003e I\n    D --\u003e J\n    E --\u003e L\n    I --\u003e M\n    H --\u003e M\n```\n\n### 🔄 事件处理流程\n\n1. **Binlog 监听**: Monitor 组件通过 canal 库监听 MySQL binlog 事件\n2. **事件过滤**: 根据任务配置过滤表名和事件类型\n3. **队列缓冲**: 事件进入高内存队列，支持流量突发\n4. **并发分发**: Worker Pool 并发处理 webhook 请求\n5. **重试机制**: 失败请求采用指数退避重试策略\n6. **状态监控**: 实时收集和暴露系统指标\n\n### 🎯 设计亮点\n\n- **事件驱动架构**: 非阻塞式事件处理，支持高并发\n- **内存优化**: 对象池和 JSON 缓存，减少 GC 压力\n- **智能重试**: 指数退避算法，避免对下游服务造成压力\n- **URL 预构建**: 启动时预构建所有回调 URL，提升运行时性能\n- **MySQL 关键字处理**: 自动识别和转义 MySQL 保留字表名\n\n## 🚀 快速开始\n\n### 📦 安装方式\n\n#### 方式一：从源码编译\n\n```bash\n# 克隆仓库\ngit clone https://github.com/tiyee/pikachu.git\ncd pikachu\n\n# 编译应用\ngo build -o pikachu .\n\n# 或使用 Makefile（推荐）\nmake build\n```\n\n#### 方式二：预编译二进制文件\n\n```bash\n# 下载对应平台的二进制文件\nwget https://github.com/tiyee/pikachu/releases/latest/download/pikachu-linux-amd64.tar.gz\n\n# 解压\ntar -xzf pikachu-linux-amd64.tar.gz\n\n# 赋予执行权限\nchmod +x pikachu\n```\n\n#### 方式三：使用 Docker\n\n```bash\n# 拉取镜像\ndocker pull pikachu:latest\n\n# 或使用 Docker Compose（推荐）\ndocker-compose up -d\n```\n\n#### ⚙️ 配置文件\n\n1. **主配置文件** (`config.yaml`)：\n\n```yaml\n# 数据库配置\ndatabase:\n  host: \"localhost\"\n  port: 3306\n  user: \"root\"\n  password: \"password\"\n  database: \"test_db\"\n  server_id: 100  # 唯一标识，避免与主从复制冲突\n  charset: \"utf8mb4\"  # 可选，默认 utf8mb4\n\n# 日志配置\nlog:\n  level: \"info\"  # debug, info, warn, error, fatal, panic\n  format: \"text\" # text, json\n\n# HTTP 服务器配置\nserver:\n  enabled: true    # 是否启用健康检查服务器\n  port: 8080       # 服务器端口\n  path: \"/health\"  # 健康检查路径\n\n# 分发器配置 (性能优化)\ndispatcher:\n  worker_count: 20         # 工作协程数量 (推荐: CPU核心数 * 2)\n  queue_size: 1000         # 队列大小 (支持突发流量)\n  timeout: 30s             # HTTP请求超时\n  max_retries: 3           # 最大重试次数\n  retry_base_delay: 5s     # 重试基础延迟 (最小3s)\n  max_connections: 100     # 最大连接数\n\n# 监控器配置\nmonitor:\n  event_queue_size: 10000  # 事件队列大小 (高负载优化)\n  event_queue_timeout: 2s  # 事件队列超时时间 (快速响应)\n\n# 可选：回调主机地址（用于相对路径的回调URL）\ncallback_host: \"http://localhost:3000\"\n```\n\n2. **任务配置文件** (`tasks.yaml`)：\n\n```yaml\ntasks:\n# 基础示例：监控用户表所有变更\n- task_id: \"user_monitor\"\n  name: \"用户表变更监控\"\n  table_name: \"users\"\n  events: [\"insert\", \"update\", \"delete\"]\n  callback_url: \"/webhook/user\"  # 相对路径\n\n# 高级示例：只监控订单表的插入和更新\n- task_id: \"order_monitor\"\n  name: \"订单表变更监控\"\n  table_name: \"orders\"\n  events: [\"insert\", \"update\"]  # 不监控删除事件\n  callback_url: \"https://api.example.com/webhook/order\"  # 绝对路径\n\n# 特殊表名示例：MySQL关键字表名\n- task_id: \"keyword_table_monitor\"\n  name: \"关键字表名监控\"\n  table_name: \"order\"  # 'order' 是MySQL关键字，系统自动处理\n  events: [\"insert\", \"update\", \"delete\"]\n  callback_url: \"/webhook/order\"\n\n# 复杂表名示例：特殊字符和数字开头\n- task_id: \"complex_table_monitor\"\n  name: \"复杂表名监控\"\n  table_name: \"2024_user-activity_log\"  # 包含连字符和数字开头\n  events: [\"insert\"]\n  callback_url: \"/webhook/activity\"\n\n# 生产环境示例：外部API回调\n- task_id: \"production_sync\"\n  name: \"生产环境数据同步\"\n  table_name: \"sync_data\"\n  events: [\"update\"]\n  callback_url: \"https://external-api.company.com/v1/sync\"\n```\n\n3. **环境特定配置**：\n\n**开发环境** (`config.dev.yaml`)：\n```yaml\nlog:\n  level: \"debug\"\n  format: \"text\"\n\ndispatcher:\n  worker_count: 2\n  queue_size: 50\n\nmonitor:\n  event_queue_size: 100\n```\n\n**生产环境** (`config.prod.yaml`)：\n```yaml\nlog:\n  level: \"warn\"\n  format: \"json\"\n\ndispatcher:\n  worker_count: 10\n  queue_size: 500\n  timeout: 60s\n  max_retries: 5\n\nmonitor:\n  event_queue_size: 2000\n```\n\n#### 运行\n\n```bash\n# 使用默认配置\n./pikachu -config config.yaml\n\n# 使用测试环境配置\n./pikachu -config config.test.yaml\n\n# 使用生产环境配置\n./pikachu -config config.prod.yaml\n```\n\n### 使用 Docker 运行\n\n#### 准备配置文件\n\n确保 `config.yaml` 和 `tasks.yaml` 文件已正确配置。\n\n#### 启动服务\n\n```bash\ndocker-compose up -d\n```\n\n## 配置说明\n\n### 数据库配置\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| host | string | 是 | MySQL 主机地址 |\n| port | int | 是 | MySQL 端口 |\n| user | string | 是 | MySQL 用户名 |\n| password | string | 是 | MySQL 密码 |\n| database | string | 是 | 数据库名称 |\n| server_id | uint32 | 是 | 用于 binlog 同步的唯一 server ID |\n| charset | string | 否 | 字符集，默认为 utf8mb4 |\n\n### 日志配置\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| level | string | 否 | 日志级别：debug, info, warn, error, fatal, panic (默认: info) |\n| format | string | 否 | 日志格式：text, json (默认: text) |\n\n### 服务器配置\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| enabled | bool | 否 | 是否启用健康检查服务器 (默认: false) |\n| port | int | 否 | 服务器端口 (默认: 8080) |\n| path | string | 否 | 健康检查路径 (默认: /health) |\n\n### 分发器配置\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| worker_count | int | 否 | 工作协程数量 (默认: 5) |\n| queue_size | int | 否 | 队列大小 (默认: 100) |\n| timeout | duration | 否 | HTTP请求超时时间 (默认: 30s) |\n| max_retries | int | 否 | 最大重试次数 (默认: 3) |\n| retry_base_delay | duration | 否 | 重试基础延迟 (默认: 10s，最小: 3s*) |\n\n***注意**: 如果设置了 `max_retries \u003e 0`，则 `retry_base_delay` 不能小于 3 秒，以避免对目标服务造成过大压力。\n\n### 监控器配置\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| event_queue_size | int | 否 | 事件队列大小 (默认: 1000) |\n| event_queue_timeout | duration | 否 | 事件队列超时时间 (默认: 5s) |\n\n### 任务配置\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| task_id | string | 是 | 任务唯一标识 |\n| name | string | 是 | 任务名称 |\n| table_name | string | 是 | 要监控的表名（支持MySQL关键字） |\n| events | []string | 是 | 要监控的事件类型 (insert/update/delete) |\n| callback_url | string | 是 | webhook 回调地址（支持相对路径和绝对路径） |\n\n### 回调主机配置\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| callback_host | string | 否 | 回调主机地址，用于拼接相对路径的回调URL |\n\n## 多环境配置\n\nPikachu 支持配置文件分离，便于多环境部署：\n\n### 配置文件结构\n\n- **主配置文件**：\n  - `config.yaml` - 默认环境配置\n  - `config.prod.yaml` - 生产环境配置\n  - `config.test.yaml` - 测试环境配置\n\n- **任务配置文件**：\n  - `tasks.yaml` - 任务配置（所有环境共享）\n  - `tasks-example.yaml` - 任务配置示例\n\n### 环境配置差异\n\n**生产环境特点**：\n- 日志级别：warn\n- 日志格式：json\n- 更高的性能参数（更多工作协程、更大队列）\n- 更长的超时和重试设置\n\n**测试环境特点**：\n- 日志级别：debug\n- 日志格式：text\n- 较低的性能参数（较少工作协程、较小队列）\n- 较短的超时和重试设置\n\n## 工作原理\n\n1. **配置加载**: 启动时加载并验证配置文件\n2. **权限检查**: 检查数据库连接和必要权限\n3. **初始化组件**: 初始化监控器、分发器和事件队列\n4. **URL预构建**: 在初始化时预构建所有回调URL，提升运行时性能\n5. **事件监听**: 监控器通过 canal 监听 MySQL binlog 事件\n6. **事件处理**: 捕获的变更事件通过事件队列传递给分发器\n7. **Webhook 发送**: 分发器将事件以 webhook 形式发送到指定地址\n8. **健康检查**: 提供 HTTP 健康检查和系统状态监控\n9. **优雅关闭**: 支持优雅关闭，确保事件处理完成\n\n## 权限要求\n\nMySQL 用户需要以下权限：\n- SELECT - 用于查询表结构\n- REPLICATION SLAVE - 用于读取二进制日志\n- REPLICATION CLIENT - 用于获取复制状态信息\n\n## MySQL 配置要求\n\n确保 MySQL 服务器已正确配置：\n- 开启二进制日志：`log_bin=ON`\n- 设置二进制日志格式为 ROW：`binlog_format=ROW`\n- 确保 `server_id` 已设置（全局唯一）\n\n## Webhook 数据格式\n\n发送到回调地址的数据格式如下：\n\n```json\n{\n  \"primary_id\": 1,\n  \"event\": \"insert\",\n  \"table\": \"users\",\n  \"data\": {\n    \"id\": 1,\n    \"name\": \"John Doe\",\n    \"email\": \"john@example.com\"\n  },\n  \"timestamp\": \"2023-01-01T12:00:00Z\"\n}\n```\n\n根据不同事件类型，数据格式略有不同：\n\n- **INSERT**: 包含 `data` 字段，表示新插入的数据\n- **UPDATE**: 包含 `old_data` 和 `new_data` 字段，分别表示更新前后的数据\n- **DELETE**: 包含 `data` 字段，表示被删除的数据\n\n## 🏥 健康检查与监控\n\nPikachu 提供了完整的 HTTP 监控端点：\n\n### 🔍 健康检查端点\n\n**端点**: `GET http://\u003chost\u003e:\u003cport\u003e/health`\n\n**响应示例**:\n```json\n{\n  \"status\": \"UP\",\n  \"monitor_running\": true,\n  \"dispatcher_running\": true,\n  \"event_queue_size\": 0,\n  \"last_event_time\": \"2023-05-15T10:30:45Z\",\n  \"uptime\": \"2h45m30s\",\n  \"version\": \"v1.0.0\"\n}\n```\n\n**状态说明**:\n- `UP`: 系统正常运行\n- `DOWN`: 系统出现异常\n- `monitor_running`: 监控器是否正在运行\n- `dispatcher_running`: 分发器是否正在运行\n- `event_queue_size`: 当前事件队列中的待处理事件数量\n- `last_event_time`: 最后一次接收到事件的时间\n- `uptime`: 服务运行时间\n- `version`: pikachu 版本号\n\n### 📊 系统指标端点\n\n**端点**: `GET http://\u003chost\u003e:\u003cport\u003e/metrics`\n\n**响应示例**:\n```json\n{\n  \"system\": {\n    \"goroutines\": 15,\n    \"memory_alloc\": \"2.5MB\",\n    \"memory_total\": \"15.2MB\",\n    \"gc_cycles\": 42\n  },\n  \"monitor\": {\n    \"status\": \"running\",\n    \"tables_monitored\": 5,\n    \"total_events_processed\": 10250,\n    \"events_per_second\": 12.5,\n    \"last_event_time\": \"2023-05-15T10:30:45Z\",\n    \"binlog_position\": {\n      \"file\": \"mysql-bin.000123\",\n      \"position\": 456789\n    }\n  },\n  \"dispatcher\": {\n    \"status\": \"running\",\n    \"workers_active\": 3,\n    \"workers_total\": 5,\n    \"queue_size\": 0,\n    \"queue_capacity\": 100,\n    \"webhooks_sent\": 10245,\n    \"webhooks_failed\": 5,\n    \"success_rate\": 99.95,\n    \"avg_response_time\": \"125ms\"\n  },\n  \"tasks\": [\n    {\n      \"task_id\": \"user_monitor\",\n      \"table_name\": \"users\",\n      \"events_processed\": 5230,\n      \"last_processed\": \"2023-05-15T10:30:42Z\",\n      \"status\": \"active\"\n    },\n    {\n      \"task_id\": \"order_monitor\",\n      \"table_name\": \"orders\",\n      \"events_processed\": 5020,\n      \"last_processed\": \"2023-05-15T10:30:45Z\",\n      \"status\": \"active\"\n    }\n  ]\n}\n```\n\n### 🔧 API 响应码说明\n\n| 状态码 | 说明 |\n|--------|------|\n| 200 | 请求成功 |\n| 400 | 请求参数错误 |\n| 404 | 端点不存在 |\n| 500 | 服务器内部错误 |\n| 503 | 服务不可用 |\n\n## 日志说明\n\n程序使用结构化日志记录关键操作和错误信息：\n\n- 支持多种日志级别，可根据需要调整详细程度\n- 支持文本和 JSON 两种日志格式\n- 日志记录包含时间戳、日志级别、消息和相关字段信息\n- 使用 Docker 部署时，日志默认存储在宿主机的 `/data/logs/pikachu` 目录\n\n## 特殊表名支持\n\npikachu 自动处理各种特殊表名，包括：\n\n### MySQL 关键字表名\n```yaml\n- task_id: \"order_monitor\"\n  table_name: \"order\"  # 'order' 是MySQL关键字，系统自动处理\n```\n\n### 特殊字符表名\n```yaml\n- task_id: \"special_table_monitor\"\n  table_name: \"my-table\"  # 包含连字符，系统自动处理\n```\n\n### 数字开头表名\n```yaml\n- task_id: \"numeric_table_monitor\"\n  table_name: \"2024_orders\"  # 以数字开头，系统自动处理\n```\n\n系统会自动为所有表名添加反引号，确保SQL语句的正确性，无需用户手动处理。\n\n## 性能优化\n\n- **URL预构建优化**: 在初始化时预构建所有回调URL，避免运行时重复计算\n- **关键字处理优化**: 使用高效的反引号包围策略处理MySQL关键字表名\n\n## 🐳 Docker 部署指南\n\n### 📋 部署架构\n\npikachu 采用多阶段构建策略：\n\n- **编译阶段**: Go 1.25-alpine 构建环境\n- **运行阶段**: 轻量级 alpine 运行环境\n- **安全特性**: 非 root 用户运行，最小权限原则\n- **证书支持**: 预装 ca-certificates 支持 HTTPS\n\n### 🚀 快速部署\n\n**方式一：Docker Compose（推荐）**\n\n```bash\n# 1. 克隆项目\ngit clone https://github.com/tiyee/pikachu.git\ncd pikachu\n\n# 2. 配置环境变量\ncp config-example.yaml config.yaml\ncp tasks-example.yaml tasks.yaml\n\n# 3. 编辑配置文件\nvim config.yaml  # 配置数据库连接等信息\nvim tasks.yaml    # 配置监控任务\n\n# 4. 启动服务\ndocker-compose up -d\n\n# 5. 查看日志\ndocker-compose logs -f pikachu\n```\n\n**方式二：单独使用 Docker**\n\n```bash\n# 1. 构建镜像\ndocker build -t pikachu:latest .\n\n# 2. 创建数据卷\ndocker volume create pikachu-logs\ndocker volume create pikachu-config\n\n# 3. 运行容器\ndocker run -d \\\n  --name pikachu \\\n  -p 8080:8080 \\\n  -v $(pwd)/config.yaml:/app/config.yaml:ro \\\n  -v $(pwd)/tasks.yaml:/app/tasks.yaml:ro \\\n  -v pikachu-logs:/app/logs \\\n  pikachu:latest\n```\n\n### ⚙️ 生产环境部署\n\n**Docker Compose 生产配置**:\n\n```yaml\nversion: '3.8'\n\nservices:\n  pikachu:\n    image: pikachu:latest\n    container_name: pikachu-prod\n    restart: unless-stopped\n\n    # 环境变量\n    environment:\n      - TZ=Asia/Shanghai\n\n    # 端口映射\n    ports:\n      - \"8080:8080\"\n\n    # 卷挂载\n    volumes:\n      - ./config.prod.yaml:/app/config.yaml:ro\n      - ./tasks.yaml:/app/tasks.yaml:ro\n      - /data/logs/pikachu:/app/logs\n      - /etc/localtime:/etc/localtime:ro\n\n    # 资源限制\n    deploy:\n      resources:\n        limits:\n          memory: 512M\n          cpus: '0.5'\n        reservations:\n          memory: 128M\n          cpus: '0.1'\n\n    # 健康检查\n    healthcheck:\n      test: [\"CMD\", \"wget\", \"--no-verbose\", \"--tries=1\", \"--spider\", \"http://localhost:8080/health\"]\n      interval: 30s\n      timeout: 10s\n      retries: 3\n      start_period: 40s\n\n    # 网络配置\n    networks:\n      - pikachu-network\n\n    # 日志配置\n    logging:\n      driver: \"json-file\"\n      options:\n        max-size: \"10m\"\n        max-file: \"3\"\n\nnetworks:\n  pikachu-network:\n    driver: bridge\n```\n\n### 🔧 Kubernetes 部署\n\n**Deployment 配置**:\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: pikachu\n  namespace: monitoring\n  labels:\n    app: pikachu\nspec:\n  replicas: 2\n  selector:\n    matchLabels:\n      app: pikachu\n  template:\n    metadata:\n      labels:\n        app: pikachu\n    spec:\n      containers:\n      - name: pikachu\n        image: pikachu:latest\n        ports:\n        - containerPort: 8080\n          name: http\n        env:\n        - name: TZ\n          value: \"Asia/Shanghai\"\n        volumeMounts:\n        - name: config\n          mountPath: /app/config.yaml\n          subPath: config.yaml\n          readOnly: true\n        - name: config\n          mountPath: /app/tasks.yaml\n          subPath: tasks.yaml\n          readOnly: true\n        - name: logs\n          mountPath: /app/logs\n        resources:\n          requests:\n            memory: \"128Mi\"\n            cpu: \"100m\"\n          limits:\n            memory: \"512Mi\"\n            cpu: \"500m\"\n        livenessProbe:\n          httpGet:\n            path: /health\n            port: 8080\n          initialDelaySeconds: 30\n          periodSeconds: 10\n        readinessProbe:\n          httpGet:\n            path: /health\n            port: 8080\n          initialDelaySeconds: 5\n          periodSeconds: 5\n      volumes:\n      - name: config\n        configMap:\n          name: pikachu-config\n      - name: logs\n        emptyDir: {}\n\n---\napiVersion: v1\nkind: Service\nmetadata:\n  name: pikachu-service\n  namespace: monitoring\nspec:\n  selector:\n    app: pikachu\n  ports:\n  - protocol: TCP\n    port: 80\n    targetPort: 8080\n    name: http\n  type: ClusterIP\n```\n\n### 📊 性能调优\n\n#### 🎯 环境配置优化\n\n**开发环境**:\n```yaml\nlog:\n  level: \"debug\"\n  format: \"text\"\n\ndispatcher:\n  worker_count: 2\n  queue_size: 50\n  timeout: 10s\n\nmonitor:\n  event_queue_size: 100\n```\n\n**生产环境**:\n```yaml\nlog:\n  level: \"warn\"\n  format: \"json\"\n\ndispatcher:\n  worker_count: 10-20  # 根据 CPU 核心数调整\n  queue_size: 500-1000  # 根据内存容量调整\n  timeout: 60s\n  max_retries: 5\n\nmonitor:\n  event_queue_size: 2000-5000\n```\n\n#### 🚀 高负载优化\n\n```yaml\n# 高并发场景配置\ndispatcher:\n  worker_count: 50        # 更多工作协程\n  queue_size: 2000       # 更大的队列\n  timeout: 120s          # 更长的超时时间\n  max_retries: 10        # 更多重试次数\n  retry_base_delay: 30s  # 更长的重试间隔\n\nmonitor:\n  event_queue_size: 10000  # 更大的事件队列\n```\n\n#### 💾 资源监控\n\n**关键指标**:\n- 事件处理延迟（目标：\u003c 100ms）\n- Webhook 成功率（目标：\u003e 99.9%）\n- 队列使用率（目标：\u003c 80%）\n- 内存使用量\n- CPU 使用率\n\n## 常见问题与排查\n\n### 连接 MySQL 失败\n- 检查数据库连接配置是否正确\n- 验证 MySQL 用户权限是否满足要求\n- 确认 MySQL 服务器是否开启了二进制日志\n- 检查 MySQL 服务器网络连接是否正常\n\n### 事件未触发\n- 检查监控的表名是否正确\n- 确认配置的事件类型（insert/update/delete）是否正确\n- 验证 MySQL 二进制日志格式是否为 ROW\n- 检查是否有数据变更发生\n\n### Webhook 回调失败\n- 检查回调 URL 是否可访问\n- 查看日志中的错误信息\n- 确认网络连接和防火墙设置\n- 检查回调服务是否正常运行\n\n### 配置文件问题\n- 确认 `tasks.yaml` 文件存在且格式正确\n- 检查配置文件语法是否正确\n- 查看启动日志中的配置加载信息\n\n## 迁移指南\n\n### 从旧版本迁移\n\n1. **备份现有配置**\n```bash\ncp config.yaml config.yaml.backup\n```\n\n2. **提取任务配置**\n从现有的 `config.yaml` 中复制 `tasks` 部分到新的 `tasks.yaml` 文件\n\n3. **更新主配置文件**\n从 `config.yaml` 中移除 `tasks` 部分\n\n4. **验证配置**\n```bash\n./pikachu -config config.yaml\n```\n\n新版本保持向后兼容，如果 `tasks.yaml` 不存在，系统会尝试从主配置文件中加载任务配置。\n\n## 开发与测试\n\n### 运行测试\n```bash\ngo test ./...\n```\n\n### 运行基准测试\n```bash\ngo test -bench=. ./...\n```\n\n### 构建生产版本\n```bash\ngo build -ldflags=\"-s -w\" -o pikachu .\n```\n\n## 🎯 实际使用场景\n\n### 场景一：微服务数据同步\n```yaml\n# 用户服务 -\u003e 订单服务 数据同步\ntasks:\n- task_id: \"user_sync_to_order\"\n  name: \"用户信息同步到订单服务\"\n  table_name: \"users\"\n  events: [\"update\"]  # 只同步用户信息变更\n  callback_url: \"https://order-service.internal/api/user-updates\"\n\n- task_id: \"profile_sync_to_notification\"\n  name: \"用户资料同步到通知服务\"\n  table_name: \"user_profiles\"\n  events: [\"insert\", \"update\"]\n  callback_url: \"/api/sync/user-profile\"  # 相对路径，使用 callback_host\n```\n\n### 场景二：搜索引擎索引更新\n```yaml\n# 商品表变更 -\u003e Elasticsearch 索引更新\ntasks:\n- task_id: \"product_index_update\"\n  name: \"商品搜索引擎索引更新\"\n  table_name: \"products\"\n  events: [\"insert\", \"update\", \"delete\"]\n  callback_url: \"https://search-service.internal/index/product\"\n\n- task_id: \"category_index_update\"\n  name: \"分类索引更新\"\n  table_name: \"product_categories\"\n  events: [\"insert\", \"update\", \"delete\"]\n  callback_url: \"https://search-service.internal/index/category\"\n```\n\n### 场景三：审计日志记录\n```yaml\n# 敏感操作审计日志\ntasks:\n- task_id: \"financial_audit\"\n  name: \"财务操作审计\"\n  table_name: \"financial_transactions\"\n  events: [\"insert\", \"update\", \"delete\"]\n  callback_url: \"https://audit-service.internal/log/financial\"\n\n- task_id: \"user_action_audit\"\n  name: \"用户操作审计\"\n  table_name: \"user_action_logs\"\n  events: [\"insert\"]\n  callback_url: \"https://audit-service.internal/log/user-actions\"\n```\n\n### 场景四：缓存失效通知\n```yaml\n# 数据变更 -\u003e Redis 缓存失效\ntasks:\n- task_id: \"cache_invalidation\"\n  name: \"缓存失效通知\"\n  table_name: \"user_preferences\"\n  events: [\"update\", \"delete\"]\n  callback_url: \"https://cache-service.internal/invalidate/user\"\n\n- task_id: \"product_cache_invalidation\"\n  name: \"商品缓存失效\"\n  table_name: \"products\"\n  events: [\"update\", \"delete\"]\n  callback_url: \"https://cache-service.internal/invalidate/product\"\n```\n\n### 场景五：实时数据推送\n```yaml\n# 实时通知 -\u003e WebSocket 服务\ntasks:\n- task_id: \"realtime_notification\"\n  name: \"实时数据推送\"\n  table_name: \"notifications\"\n  events: [\"insert\"]\n  callback_url: \"https://websocket-service.internal/push/notification\"\n\n- task_id: \"order_status_update\"\n  name: \"订单状态实时推送\"\n  table_name: \"order_status_history\"\n  events: [\"insert\"]\n  callback_url: \"https://websocket-service.internal/push/order-status\"\n```\n\n### 场景六：数据仓库同步\n```yaml\n# OLTP -\u003e OLAP 数据同步\ntasks:\n- task_id: \"data_warehouse_sync\"\n  name: \"数据仓库同步\"\n  table_name: \"sales_transactions\"\n  events: [\"insert\", \"update\"]\n  callback_url: \"https://data-warehouse.internal/api/sync/sales\"\n\n- task_id: \"analytics_sync\"\n  name: \"分析数据同步\"\n  table_name: \"user_behavior_events\"\n  events: [\"insert\"]\n  callback_url: \"https://analytics-service.internal/api/events\"\n```\n\n### 场景七：复杂业务流程触发\n```yaml\n# 业务流程自动化触发\ntasks:\n- task_id: \"order_workflow\"\n  name: \"订单工作流触发\"\n  table_name: \"orders\"\n  events: [\"insert\", \"update\"]\n  callback_url: \"https://workflow-service.internal/trigger/order-process\"\n\n- task_id: \"inventory_restock\"\n  name: \"库存补货触发\"\n  table_name: \"inventory\"\n  events: [\"update\"]\n  callback_url: \"https://inventory-service.internal/trigger/restock\"\n```\n\n## 📝 更新日志\n\n### v1.0.0 (2024-01-15)\n#### 🎉 新功能\n- ✨ 支持 MySQL 5.6+ 和 MariaDB 10.0+\n- ✨ 实时 binlog 事件捕获\n- ✨ 灵活的 webhook 回调配置\n- ✨ 多环境配置支持\n- ✨ 健康检查和监控端点\n- ✨ Docker 和 Kubernetes 部署支持\n\n#### 🚀 性能优化\n- ⚡ URL 预构建优化\n- ⚡ 协程池并发处理\n- ⚡ 智能重试机制\n- ⚡ 事件队列缓冲\n\n#### 🛠️ 技术特性\n- 🔧 自动处理 MySQL 关键字表名\n- 🔧 结构化日志记录\n- 🔧 优雅关闭机制\n- 🔧 配置热重载支持\n\n## 🤝 贡献指南\n\n我们欢迎所有形式的贡献！请遵循以下步骤：\n\n### 🐛 报告问题\n1. 使用 [GitHub Issues](https://github.com/tiyee/pikachu/issues) 报告 bug\n2. 提供详细的问题描述和复现步骤\n3. 包含相关的日志和配置信息\n4. 标明运行环境（操作系统、Go版本、MySQL版本等）\n\n### 💡 功能请求\n1. 在 Issues 中描述新功能需求\n2. 说明使用场景和预期行为\n3. 提供可能的实现方案（如有）\n\n### 🔧 代码贡献\n1. Fork 项目仓库\n2. 创建功能分支 (`git checkout -b feature/amazing-feature`)\n3. 编写代码和测试\n4. 确保所有测试通过 (`make test-all`)\n5. 提交代码 (`git commit -m 'Add amazing feature'`)\n6. 推送到分支 (`git push origin feature/amazing-feature`)\n7. 创建 Pull Request\n\n### 📋 开发规范\n- 遵循 Go 语言编码规范\n- 添加适当的单元测试和集成测试\n- 更新相关文档\n- 确保所有测试通过\n- 代码覆盖率不低于 80%\n\n### 🔍 代码审查\n- 所有 PR 需要至少一个维护者审查\n- 自动化 CI/CD 检查必须通过\n- 确保向后兼容性\n- 文档同步更新\n\n## 📞 支持与联系\n\n- 📧 邮箱: tiyee@outlook.com\n- 💬 讨论: [GitHub Discussions](https://github.com/tiyee/pikachu/discussions)\n- 🐛 问题: [GitHub Issues](https://github.com/tiyee/pikachu/issues)\n- 📖 文档: [官方文档](https://github.com/tiyee/pikachu)\n\n## 📄 许可证\n\n本项目采用 [MIT License](LICENSE) 开源协议。\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e⭐ 如果这个项目对您有帮助，请给我们一个 Star！\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Made with ❤️ by \u003ca href=\"https://github.com/tiyee\"\u003etiyee\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiyee%2Fpikachu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftiyee%2Fpikachu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiyee%2Fpikachu/lists"}