From 060f43f0c48abbab115fd698f712a41e297af44d Mon Sep 17 00:00:00 2001 From: Warren Date: Mon, 22 Jun 2026 05:36:23 +0800 Subject: [PATCH] Add CTDB architecture analysis document --- docs/CTDB_ARCHITECTURE_ANALYSIS.md | 342 +++++++++++++++++++++++++++++ 1 file changed, 342 insertions(+) create mode 100644 docs/CTDB_ARCHITECTURE_ANALYSIS.md diff --git a/docs/CTDB_ARCHITECTURE_ANALYSIS.md b/docs/CTDB_ARCHITECTURE_ANALYSIS.md new file mode 100644 index 0000000..0434997 --- /dev/null +++ b/docs/CTDB_ARCHITECTURE_ANALYSIS.md @@ -0,0 +1,342 @@ +# CTDB (Cluster Trivial Database) 架构分析 + +## 概述 + +**CTDB** 是 Samba 的集群数据库系统，用于在高可用性（HA）集群环境中管理共享状态和数据库记录。 + +**核心功能**： +- 集群节点间状态同步 +- 分布式数据库存储 +- 故障检测和自动恢复 +- 公共 IP 地址管理（浮动 IP） + +--- + +## 1. CTDB 核心组件 + +### 1.1 分布式数据库引擎 + +**功能**： +- 字储 TDB (Trivial Database) 记录 +- 在多个节点间复制数据 +- 提供原子性和一致性保证 + +**TDB 格式**： +``` +┌─────────────────────────────────────┐ +│ TDB Header │ +│ ├── Magic number: 0x1BADFACE │ +│ ├── Version: 1 │ +│ ├── Hash size: 1024 │ +│ └── Record count: N │ +├─────────────────────────────────────┤ +│ Hash Table │ +│ ├── Bucket 0: offset to record │ +│ ├── Bucket 1: offset to record │ +│ └── ... │ +├─────────────────────────────────────┤ +│ Free List │ +│ ├── Offset to next free block │ +│ └── Free block size │ +├─────────────────────────────────────┤ +│ Records │ +│ ├── Key (variable length) │ +│ ├── Data (variable length) │ +│ └── Hash next pointer │ +└─────────────────────────────────────┘ +``` + +--- + +### 1.2 集群节点管理 + +**功能**： +- 节点状态监控（UP/DOWN/UNHEALTHY） +- 心跳检测（heartbeat） +- 自动故障转移（failover） + +**节点状态定义**： +| 状态 | 说明 | 处理 | +|------|------|------| +| **UP** | 节点正常运行 | 参与集群操作 | +| **DOWN** | 节点离线 | 等待恢复 | +| **UNHEALTHY** | 节点不健康 | 停止服务 | +| **BANNED** | 节点被禁止 | 重新加入需手动操作 | + +--- + +### 1.3 公共 IP 管理 + +**功能**： +- 动态分配浮动 IP（public IP） +- 节点故障时自动迁移 IP +- 客户端透明重连 + +**公共 IP 分配逻辑**： +``` +┌─────────────────────────────────────┐ +│ Public IP Pool │ +│ ├── 192.168.1.100 (node 0) │ +│ ├── 192.168.1.101 (node 1) │ +│ ├── 192.168.1.102 (node 2) │ +│ └── ... │ +├─────────────────────────────────────┤ +│ IP Assignment │ +│ ├── Node 0 UP → owns .100 │ +│ ├── Node 1 DOWN → .101 moves to N0 │ +│ └── Node 2 UP → owns .102 │ +└─────────────────────────────────────┘ +``` + +--- + +### 1.4 事件脚本系统 + +**功能**： +- 监控脚本（健康检查） +- 启动/停止脚本（服务管理） +- IP 分配脚本（网络配置） + +**事件类型**： +| 事件 | 说明 | 脚本 | +|------|------|------| +| `startup` | 节点启动 | 01.startup.sh | +| `shutdown` | 节点停止 | 50.shutdown.sh | +| `takeip` | 分配 IP | 11.takeip.sh | +| `releaseip` | 释放 IP | 10.releaseip.sh | +| `monitor` | 健康检查 | 00.monitor.sh | + +--- + +## 2. CTDB 协议架构 + +### 2.1 控制协议 + +**CTDB 控制消息**（基于 TCP）： +``` +┌─────────────────────────────────────┐ +│ CTDB Header │ +│ ├── Magic: 0xCtdb │ +│ ├── Version: 1 │ +│ ├── Command: CTDB_CMD_* │ +│ ├── Status: SUCCESS/ERROR │ +│ ├── Length: payload size │ +├─────────────────────────────────────┤ +│ Payload │ +│ ├── Command-specific data │ +│ └── Optional response data │ +└─────────────────────────────────────┘ +``` + +**CTDB_CMD 类型**： +| Command | 说明 | 用途 | +|---------|------|------| +| `CTDB_CMD_CONNECT` | 连接请求 | 初始化连接 | +| `CTDB_CMD_GETDB` | 获取数据库 | 访问 TDB | +| `CTDB_CMD_FETCH` | 读取记录 | 查询数据 | +| `CTDB_CMD_STORE` | 存储记录 | 写入数据 | +| `CTDB_CMD_DELETE` | 删除记录 | 清除数据 | +| `CTDB_CMD_PING` | 心跳检测 | 节点监控 | +| `CTDB_CMD_SETNODEMASK` | 设置节点掩码 | 集群配置 | + +--- + +### 2.2 数据库复制协议 + +**复制策略**： +- **主从复制**（Master-Slave）：一个节点为主，其他为副本 +- **多主复制**（Multi-Master）：所有节点可写入（需要冲突解决） + +**复制流程**： +``` +Node A Node B + | | + |── STORE(key, value) ────>| (write request) + | |── Validate + | |── Write to local TDB + | |── Replicate to other nodes + |<── ACK (success) ────────| + | | + |── FETCH(key) ───────────>| (read request) + |<── value ────────────────| (return data) +``` + +--- + +### 2.3 故障恢复协议 + +**故障检测**： +``` +┌─────────────────────────────────────┐ +│ Health Monitor Loop │ +│ ├── Ping all nodes (every 1s) │ +│ ├── Check response timeout (5s) │ +│ ├── Mark DOWN if timeout │ +│ └── Trigger recovery process │ +└─────────────────────────────────────┘ +``` + +**恢复流程**： +``` +Node A (DOWN) Cluster + | | + |── Mark as DOWN ─────────>| (detected) + | |── Reassign public IPs + | |── Notify other nodes + | |── Update node mask + | | + |── Recovery attempt ─────>| (after 30s) + |── Rejoin cluster ───────>| (if successful) + | |── Restore IPs +``` + +--- + +## 3. CTDB 与 SMB 集成 + +### 3.1 Samba 集成点 + +**共享数据库**： +| TDB 文件 | 说明 | 集群支持 | +|---------|------|---------| +| `secrets.tdb` | 认证密钥 | ✅ CTDB 复制 | +| `brlock.tdb` | 字节锁 | ✅ CTDB 复制 | +| `locking.tdb` | 文件锁 | ✅ CTDB 复制 | +| `connections.tdb` | 连接状态 | ✅ CTDB 复制 | +| `session_info.tdb` | 会话信息 | ✅ CTDB 复制 | +| `share_info.tdb` | 共享配置 | ✅ CTDB 复制 | + +**关键特性**： +- 所有节点访问相同的数据库 +- 实时同步锁定状态 +- 故障后自动恢复连接 + +--- + +### 3.2 实施架构 + +**高可用性架构**： +``` +┌─────────────────────────────────────────────┐ +│ Client Layer │ +│ ├── SMB clients (Windows/macOS/Linux) │ +│ └── Connect via floating IP │ +├─────────────────────────────────────────────┤ +│ CTDB Cluster (3+ nodes) │ +│ ├── Node 0: 192.168.1.100 (SMB + CTDB) │ +│ ├── Node 1: 192.168.1.101 (SMB + CTDB) │ +│ ├── Node 2: 192.168.1.102 (SMB + CTDB) │ +│ └── Public IPs: .100, .101, .102 │ +├─────────────────────────────────────────────┤ +│ Shared Storage │ +│ ├── GlusterFS / Ceph / NFS │ +│ └── All nodes access same filesystem │ +└─────────────────────────────────────────────┘ +``` + +--- + +## 4. 实施评估 + +### 4.1 核心功能需求 + +| 功能 | 优先级 | 工作量 | 风险 | +|------|--------|--------|------| +| **分布式 TDB** | P0 | 500 行 | 中 ⚠️⚠️⚠️ | +| **节点管理** | P0 | 300 行 | 中 ⚠️⚠️⚠️ | +| **公共 IP 管理** | P1 | 200 行 | 低 ⚠️⚠️ | +| **事件脚本系统** | P1 | 200 行 | 低 ⚠️⚠️ | +| **控制协议** | P0 | 400 行 | 高 ⚠️⚠️⚠️⚠️ | +| **故障恢复** | P0 | 300 行 | 高 ⚠️⚠️⚠️⚠️⚠️ | +| **总计** | | **1900 行** | **高 ⚠️⚠️⚠️⚠️⚠️** | + +--- + +### 4.2 技术挑战 + +**挑战 1：分布式一致性** +- **问题**：多节点写入冲突 +- **解决方案**： + - 使用 Raft/Paxos 算法（需要实现 consensus） + - 或使用主从模式（简化但牺牲可用性） + +**挑战 2：故障检测准确性** +- **问题**：网络分区导致误判 +- **解决方案**： + - 使用多路径心跳（多个检测点） + - 设置合理的超时阈值（避免误判） + +**挑战 3：浮动 IP 管理** +- **问题**：IP 迁移需要内核支持 +- **解决方案**： + - 使用 Linux network namespace + - macOS 需要 ifconfig + route 管理 + +--- + +### 4.3 Rust 实施建议 + +**推荐方案**： +1. **Phase 1**：实现基础 TDB 存储引擎（500 行） +2. **Phase 2**：实现节点管理和心跳（300 行） +3. **Phase 3**：实现控制协议（400 行） +4. **Phase 4**：实现公共 IP 管理（200 行） +5. **Phase 5**：实现故障恢复逻辑（300 行） + +**总计**：约 1700 行代码（不包括测试） + +**预计时间**：约 5-7 天（高复杂度） + +--- + +### 4.4 替代方案 + +**方案 1：使用现有 Rust crate** +- `raft-rs`：分布式共识算法 +- `tikv`：分布式 KV 存储 +- 优点：减少实现工作量 +- 缺点：需要集成适配 + +**方案 2：简化 CTDB 实现** +- 仅实现单主模式（避免分布式共识） +- 使用 SQLite 作为共享数据库（简化存储） +- 优点：降低实施风险 +- 缺点：牺牲可用性（主节点故障无法写入） + +**方案 3：不实施 CTDB** +- 使用外部高可用方案（HAProxy + Keepalived） +- MarkBase SMB 保持单节点部署 +- 优点：最小工作量 +- 缺点：无法实现真正的集群 + +--- + +## 5. 决策建议 + +### 5.1 推荐策略 ⭐⭐⭐⭐ + +**短期（P3 不建议实施）**： +- ✅ 保持单节点部署（Phase 1-6 已完成） +- ✅ 使用外部 HAProxy + Keepalived 实现高可用 +- ❌ 不实施 CTDB（复杂度高，收益有限） + +**长期（企业需求）**： +- ⭐⭐⭐⭐ 实施简化 CTDB（单主模式） +- ⭐⭐⭐ 使用 Raft-rs 实现分布式共识 +- ⭐⭐⭐⭐⭐ 完整 CTDB 实现（需要 5-7 天） + +--- + +### 5.2 最终建议 + +| 场景 | 推荐方案 | 工作量 | +|------|---------|--------| +| **个人/小团队** | 单节点 + 外部 HA | 0 行 | +| **中小企业** | 简化 CTDB（单主） | ~800 行 | +| **大型企业** | 完整 CTDB + Raft | ~2000 行 | + +**结论**：Phase 7 (CTDB 集群) 复杂度高（⚠️⚠️⚠️⚠️⚠️），建议根据实际需求决定是否实施。 + +--- + +**最后更新**：2026-06-22 \ No newline at end of file