alibaba/canal

Item: alibaba/canal
Rating: 5
Author: RepoPilot

阿里巴巴 MySQL binlog 增量订阅&消费组件

Healthy

Healthy across the board

weakest axis

Use as dependencyHealthy

Permissive license, no critical CVEs, actively maintained — safe to depend on.

Fork & modifyHealthy

Has a license, tests, and CI — clean foundation to fork and modify.

Learn fromHealthy

Documented and popular — useful reference codebase to read through.

Deploy as-isHealthy

No critical CVEs, sane security posture — runnable as-is.

✓Last commit 1w ago
✓33+ active contributors
✓Apache-2.0 licensed

Show all 6 evidence items →

✓CI configured
✓Tests present
⚠Concentrated ownership — top contributor handles 53% of recent commits

Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests

Informational only. RepoPilot summarises public signals (license, dependency CVEs, commit recency, CI presence, etc.) at the time of analysis. Signals can be incomplete or stale. Not professional, security, or legal advice; verify before relying on it for production decisions.

Embed the "Healthy" badge

Paste into your README — live-updates from the latest cached analysis.

Variant:

[![RepoPilot: Healthy](https://repopilot.app/api/badge/alibaba/canal)](https://repopilot.app/r/alibaba/canal)

Paste at the top of your README.md — renders inline like a shields.io badge.

▸Preview social card (1200×630)

This card auto-renders when someone shares https://repopilot.app/r/alibaba/canal on X, Slack, or LinkedIn.

Onboarding doc

Onboarding: alibaba/canal

Generated by RepoPilot · 2026-05-09 · Source

🤖Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/alibaba/canal shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

🎯Verdict

GO — Healthy across the board

Last commit 1w ago
33+ active contributors
Apache-2.0 licensed
CI configured
Tests present
⚠ Concentrated ownership — top contributor handles 53% of recent commits

<sub>Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests</sub>

✅Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live alibaba/canal repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/alibaba/canal.

What it runs against: a local clone of alibaba/canal — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in alibaba/canal | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 39 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>alibaba/canal</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of alibaba/canal. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/alibaba/canal.git
#   cd canal
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of alibaba/canal and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "alibaba/canal(\\.git)?\\b" \\
  && ok "origin remote is alibaba/canal" \\
  || miss "origin remote is not alibaba/canal (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "admin/admin-ui/src/main.js" \\
  && ok "admin/admin-ui/src/main.js" \\
  || miss "missing critical file: admin/admin-ui/src/main.js"
test -f "admin/admin-ui/src/router/index.js" \\
  && ok "admin/admin-ui/src/router/index.js" \\
  || miss "missing critical file: admin/admin-ui/src/router/index.js"
test -f "admin/admin-ui/src/api/canalInstance.js" \\
  && ok "admin/admin-ui/src/api/canalInstance.js" \\
  || miss "missing critical file: admin/admin-ui/src/api/canalInstance.js"
test -f "admin/admin-ui/src/store/index.js" \\
  && ok "admin/admin-ui/src/store/index.js" \\
  || miss "missing critical file: admin/admin-ui/src/store/index.js"
test -f "admin/admin-ui/package.json" \\
  && ok "admin/admin-ui/package.json" \\
  || miss "missing critical file: admin/admin-ui/package.json"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 39 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~9d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/alibaba/canal"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

⚡TL;DR

Canal is Alibaba's MySQL binlog log parsing component that enables real-time incremental data subscription and consumption. It mimics a MySQL slave to intercept binary log events from a MySQL master, parse them, and deliver incremental changes to consumers via Kafka, RocketMQ, or direct TCP. Core use cases include database mirroring, real-time backups, search index maintenance, and cache invalidation. Monorepo structure: canal/ root contains core Java modules (binlog parser, protocol handlers, connectors), admin/ contains canal-admin backend and admin/admin-ui/ contains the Vue 2 management dashboard. The admin-ui is a separate Vue CLI project with Babel, ESLint, Jest, and Element UI for WebUI operations; core modules handle MySQL protocol emulation and binlog event transformation.

👥Who it's for

Data infrastructure engineers and platform teams at companies running MySQL who need to sync incremental changes across heterogeneous systems (data warehouses, search indices, caches, event systems) without modifying application code. Also appeals to DevOps engineers managing canal-admin for cluster operations.

🌱Maturity & risk

Production-ready and actively maintained. The project has been battle-tested since ~2010 at Alibaba scale, with v1.1.x bringing significant performance gains (150%+ improvement), native Kafka/RocketMQ support, Prometheus monitoring, and Aliyun RDS binlog support. v1.1.4 introduced canal-admin with WebUI for operations. Travis CI and GitHub Actions configured; multiple version releases tracked in RELEASE.txt.

Standard open source risks apply.

Active areas of work

Active development on canal-admin platform (WebUI operations, cluster management). GitHub workflows configured for Maven builds and codecov integration. Recent focus areas include Prometheus metrics, Kafka/RocketMQ delivery, Aliyun RDS support, and Docker containerization. Issue templates in .github/ISSUE_TEMPLATE/ indicate ongoing community support for bug reports and feature requests.

🚀Get running

git clone https://github.com/alibaba/canal.git
cd canal
# For Java backend:
mvn clean install
# For admin-ui frontend:
cd admin/admin-ui
npm install
npm run dev

Daily commands: Backend: mvn clean package then run generated binary; Frontend: cd admin/admin-ui && npm run dev starts webpack dev server on localhost. Production build: npm run build generates dist/ for deployment. Mock server available in admin/admin-ui/mock/ for UI development without backend.

🗺️Map of the codebase

admin/admin-ui/src/main.js — Vue application entry point; initializes router, store, and permission guards that control the entire admin UI
admin/admin-ui/src/router/index.js — Defines all routes and navigation structure; essential for understanding how pages and features are organized
admin/admin-ui/src/api/canalInstance.js — Core API client for Canal instance operations; all instance management depends on these endpoints
admin/admin-ui/src/store/index.js — Vuex store configuration; manages global state for authentication, UI settings, and application data
admin/admin-ui/package.json — Declares all npm dependencies (Element UI, axios, Vue); understanding versions is critical for compatibility
admin/admin-ui/src/permission.js — Route guard implementation; controls access to authenticated pages and role-based visibility
admin/admin-ui/babel.config.js — JavaScript transpilation configuration; affects how modern JS features are converted for browser compatibility

🛠️How to make changes

Add a New Admin Page with Routing

Create a new Vue single-file component in admin/admin-ui/src/views/ directory (e.g., MyNewFeature.vue) (admin/admin-ui/src/views/MyNewFeature.vue)
Add a route entry in the router configuration to include the new page with icon and permissions (admin/admin-ui/src/router/index.js)
Add menu item text to language i18n files if internationalization is configured (admin/admin-ui/src/lang/)
Import and use api client (e.g., canalInstance.js) in the component to fetch/mutate data (admin/admin-ui/src/api/canalInstance.js)
Use Element UI components and global styles following existing page patterns (e.g., tables, forms, dialogs) (admin/admin-ui/src/styles/index.scss)

Add a New API Endpoint Integration

Create a new API module file in admin/admin-ui/src/api/ (e.g., newFeature.js) following the axios pattern (admin/admin-ui/src/api/newFeature.js)
Define request functions (GET, POST, PUT, DELETE) that call backend endpoints with proper error handling (admin/admin-ui/src/api/canalInstance.js)
Import the API module into components or Vuex actions where data is needed (admin/admin-ui/src/store/modules/user.js)
Handle responses in components using async/await or .then() chains with proper loading/error states (admin/admin-ui/src/views/)

Add a New Vuex State Module for Feature Data

Create a new module file in admin/admin-ui/src/store/modules/ (e.g., myFeature.js) with state, mutations, actions, and getters (admin/admin-ui/src/store/modules/myFeature.js)
Import and register the module in the store initialization file (admin/admin-ui/src/store/index.js)
Use mapState, mapGetters, and mapActions in components to access and mutate module state (admin/admin-ui/src/layout/index.vue)
Call API methods from actions to fetch data and commit mutations to update state (admin/admin-ui/src/api/)

Add a New Reusable UI Component

Create a new .vue file in admin/admin-ui/src/components/ directory with template, script, and scoped styles (admin/admin-ui/src/components/MyComponent/index.vue)
Define props, events, and slots to make the component configurable and composable (admin/admin-ui/src/components/Pagination/index.vue)
Import the component in admin/admin-ui/src/main.js or use Vue.component() to register globally, or import locally where needed (admin/admin-ui/src/main.js)
Use Element UI as the base and apply global styles from admin/admin-ui/src/styles/ for consistency (admin/admin-ui/src/styles/index.scss)

🔧Why these technologies

Vue.js 2.x — Progressive framework for building reactive UI; integrates seamlessly with Element UI components and Vuex for state management
Element UI 2.7.2 — Enterprise-grade Vue component library providing pre-built form controls, tables, dialogs, and layout components matching admin UI patterns
Vuex — Centralized state management for user authentication, global UI state, and shared application data across routes and components
Axios 0.18.1 — Promise-based HTTP client for REST API communication with automatic JSON serialization and request/response interceptors
Vue Router — Official Vue routing library enabling client-side navigation with nested routes, lazy-loading, and permission-based guards
SCSS — CSS preprocessor providing mixins, variables, and nesting for maintainable and reusable styling across the admin UI

🪤Traps & gotchas

Node version constraint: engines.node >= 8.9 (consider using nvm for compatibility). Admin-UI uses old Vue 2 with deprecated dependency versions—Node/npm versions may cause build failures. MySQL master must have binlog enabled and accessible over network (firewall/credentials). Canal mimics MySQL slave, so replication account with REPLICATION privilege required. Aliyun RDS and on-prem MySQL require different configuration—check canal-admin instance config. Docker quickstart assumes Docker daemon running. No visible environment variables documented in provided files; check wikis for CANAL_* or ADMIN_* vars.

🏗️Architecture

💡Concepts to learn

MySQL Binary Log (Binlog) — Canal's entire function revolves around parsing MySQL binlog format (row-based, statement-based, mixed); understanding binlog events (WRITE_ROWS, UPDATE_ROWS, DELETE_ROWS, DDL) is core to contributing to Canal
MySQL Replication Protocol — Canal impersonates a MySQL slave using the binlog dump protocol; knowledge of COM_BINLOG_DUMP and replication handshake is essential for protocol-level changes
Change Data Capture (CDC) — Canal is a CDC tool; understanding CDC patterns (log-based vs query-based, exactly-once delivery, ordering guarantees) frames the design decisions in Canal
Position-based Replication Offset Tracking — Canal must track MySQL binlog file name and position (e.g., 'mysql-bin.000001:4') to resume after restarts; offset management is critical for fault tolerance
Row-Level Event Filtering (Sharding) — Canal supports filtering/mapping rows to different Kafka topics based on database/table rules; understanding regex-based table routing in canal-admin is important for deployments
Message Idempotency & Delivery Guarantees — Canal can deliver messages to Kafka/RocketMQ with at-least-once semantics; downstreams must handle duplicate events from position rewinds
Vue 2 Composition & State Management (Vuex) — Admin-UI uses Vuex for state (user auth, instance list, config); understanding how admin/admin-ui/src/ components interact with Vuex stores is essential for frontend contributions

alibaba/otter — Predecessor to Canal; handles cross-IDC MySQL replication. Canal extracted binlog parsing logic from Otter for broader use.
debezium/debezium — Alternative CDC (Change Data Capture) solution supporting multiple databases; competes with Canal in Kafka-based change streaming but with different architecture
mysql/mysql-server — MySQL source code; understanding binlog format and replication protocol essential for Canal development
apache/kafka — Primary message broker integration; Canal's Kafka connector depends on Kafka producer API for delivering binlog events
alibaba/nacos — Often paired with Canal in Alibaba ecosystems for dynamic configuration and service discovery of Canal instances

🪄PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for admin-ui API modules

The admin-ui has 6 API modules (canalCluster.js, canalConfig.js, canalInstance.js, nodeServer.js, table.js, user.js) in admin/admin-ui/src/api/ with no visible test files. Given the project uses Jest and @vue/test-utils, adding unit tests for these API client modules would improve reliability of the UI layer and catch regressions early. This is especially critical for production-grade admin interfaces.

[ ] Create admin/admin-ui/tests/unit/api/ directory structure
[ ] Add unit tests for admin/admin-ui/src/api/canalCluster.js covering HTTP methods and error handling
[ ] Add unit tests for admin/admin-ui/src/api/canalInstance.js with mock axios responses
[ ] Add unit tests for admin/admin-ui/src/api/user.js covering authentication flows
[ ] Update admin/admin-ui/jest.config.js if needed to include test coverage reporting
[ ] Document test execution in admin/admin-ui/README.md

Add Node.js/npm dependency security scanning to GitHub Actions

The repo has .github/workflows/maven.yml for Java builds but no automated security scanning for the admin-ui Node.js dependencies. With outdated packages like axios 0.18.1, element-ui 2.7.2, and node-sass ^4.9.0 listed in admin/admin-ui/package.json, adding npm audit and Snyk scanning to CI would catch known vulnerabilities automatically and prevent security regressions.

[ ] Create .github/workflows/npm-security.yml for admin-ui dependency scanning
[ ] Add npm audit step to scan admin/admin-ui/package.json for vulnerabilities
[ ] Configure step to fail on high/critical severity issues
[ ] Optional: Integrate Snyk action for enhanced vulnerability detection
[ ] Document security scanning expectations in SECURITY.md

Add integration tests for Vue components in admin-ui

The admin/admin-ui/src/components/ directory contains reusable components (Breadcrumb, Hamburger, Pagination, SvgIcon) with no visible component tests despite having @vue/test-utils configured. Component integration tests would ensure UI reliability and catch regressions in navigation, icon rendering, and pagination logic used across admin pages.

[ ] Create admin/admin-ui/tests/unit/components/ directory
[ ] Add component test for admin/admin-ui/src/components/Pagination/index.vue covering pagination state changes
[ ] Add component test for admin/admin-ui/src/components/Breadcrumb/index.vue with routing integration
[ ] Add component test for admin/admin-ui/src/components/SvgIcon/index.vue with SVG sprite loader validation
[ ] Update admin/admin-ui/jest.config.js moduleNameMapper for SVG sprite loader if needed
[ ] Document component testing patterns in admin/admin-ui/README.md

🌿Good first issues

Add unit tests to admin/admin-ui/src/api/nodeServer.js—currently no test file visible in jest.config.js; mock server tests exist but client API lacks coverage
Document the admin-ui authentication flow (user.js API present) in a new ADMIN_UI_AUTHENTICATION.md—setup docs reference WebUI but don't explain login/RBAC
Create a starter example in examples/ showing how to build a custom Canal consumer in Java (Kafka output is documented, but direct TCP consumer pattern is not)

⭐Top contributors

Click to expand

@agapple — 53 commits
@sunxien — 7 commits
@dingxiaobo — 4 commits
@daguimu — 3 commits
@gcanlin — 2 commits

📝Recent commits