# binary_log_agent

**Repository Path**: gilbertwang/binary_log_agent

## Basic Information

- **Project Name**: binary_log_agent
- **Description**: 去中心化，分布式本地缓存的实现，采用WAL的方式，C语言实现；详细介绍：https://blog.csdn.net/tq02h2a/article/details/77103762
- **Primary Language**: C++
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2021-12-27
- **Last Updated**: 2026-06-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Binary Log Agent

基于共享内存的分布式缓存二进制日志复制代理。该守护进程持续读取共享内存中的缓存变更操作（SET / DEL / NOTIFY），并通过 TCP 网络将这些操作实时广播到集群中的所有节点，实现分布式缓存的数据同步。

---

## 项目概述

`binary_log_agent` 是分布式本地缓存系统的核心同步组件，负责：

- **读取共享内存日志**：通过文件锁同步机制，从双缓冲共享内存文件中顺序读取缓存操作记录
- **集群节点发现**：基于组播（Multicast）协议自动发现集群中的其他节点，动态维护节点列表
- **数据实时广播**：通过 TCP 长连接将缓存操作可靠地复制到所有在线节点
- **心跳与故障恢复**：支持自动重连、心跳保活和故障节点检测

---

## 架构与核心组件

```
┌─────────────────┐      ┌──────────────────┐      ┌─────────────────┐
│   Shared Memory │      │  Binary Log      │      │  Cluster Nodes  │
│   (Index/Data)  │─────▶│  Agent           │─────▶│  (TCP Peers)    │
└─────────────────┘      └──────────────────┘      └─────────────────┘
                                │
                                ▼
                         ┌──────────────────┐
                         │  Multicast       │
                         │  Discovery       │
                         └──────────────────┘
```

| 组件 | 文件 | 说明 |
|------|------|------|
| **主程序** | `main.cpp` | 进程初始化、守护进程模式、主循环 |
| **共享内存读取器** | `shmreader.h/cpp` | 管理索引与数据共享内存的读取、文件切换 |
| **共享内存管理** | `shm.h/cpp` | 基于 `mmap` 的共享内存读写封装 |
| **网络连接器** | `connector.h/cpp` | TCP 客户端连接、消息收发、心跳线程、自动重连 |
| **复制器** | `replicator.h/cpp` | 单例模式，负责将数据广播到所有节点 |
| **命名服务** | `naming.h/cpp` | 组播服务发现、节点管理、验证回调、故障检测 |
| **文件锁** | `filelock.h/cpp` | 基于文件描述符的进程间互斥锁 |
| **MD5 工具** | `md5.h/cpp` | 节点间通信的验证码生成 |
| **内存数据库工具** | `memdb.h/cpp` | 共享内存索引与数据头结构解析 |

---

## 支持的操作类型

| 操作码 | 名称 | 说明 |
|--------|------|------|
| `0` | `BINLOG_OPTYPE_NOTIFY` | 缓存刷新通知（如全量刷新） |
| `1` | `BINLOG_OPTYPE_SET` | 设置键值对 |
| `2` | `BINLOG_OPTYPE_DEL` | 删除键 |
| `3` | `BINLOG_OPTYPE_ERR` | 错误通知（节点故障时回传） |
| `127` | `BINLOG_OPTYPE_HB` | 心跳包 |

---

## 构建

### 依赖库

- **protobuf** — 协议序列化
- **log4cpp** — 日志记录
- **pthread** — 多线程支持
- **commonlib4c** — 公共基础库（异步日志、互斥锁、组播等）

### 编译

```bash
cd src
make
```

编译产物为当前目录下的 `binary_log_agent` 可执行文件。

### 清理

```bash
make clean
```

---

## 运行

### 基本用法

```bash
# 前台运行
./binary_log_agent 0

# 后台守护进程模式
./binary_log_agent 1
```

### 环境变量

| 环境变量 | 默认值 | 说明 |
|----------|--------|------|
| `DISTRIBUTED_STRING_LOCAL_CACHE_INDEX_PATH` | `.` | 索引共享内存与锁文件所在目录 |
| `DISTRIBUTED_STRING_LOCAL_CACHE_DATA_PATH` | `.` | 数据共享内存文件所在目录 |
| `DISTRIBUTED_STRING_LOCAL_CACHE_PASS` | `hello-world-12345-!#$%@` | 节点间通信验证密码 |

### 共享内存文件结构

```
${DISTRIBUTED_STRING_LOCAL_CACHE_INDEX_PATH}/
├── index.lock          # 索引区文件锁
├── index.shm           # 索引共享内存（writeCtr / readCtr / total / index）

${DISTRIBUTED_STRING_LOCAL_CACHE_DATA_PATH}/
├── data.0.lock         # 数据区文件锁
├── data.0.shm          # 当前数据共享内存文件
└── data.0.shm.<ts>.bak # 写满后自动归档的旧数据文件
```

---

## 配置文件

`config/log.conf` 为 **log4cpp** 日志配置文件，默认将日志写入：

```
/apps/logs/log_receiver/binary_log_agent.log
```

同时输出到控制台。可按需调整日志级别与路径。

---

## 通信协议

### 节点发现（Multicast）

- **组播端口**：`10012`
- **验证机制**：基于环境变量密码生成 MD5 验证码，防止非法节点加入
- **发现流程**：
  1. 节点启动后周期性发送组播广播，携带本机 IP 与验证码
  2. 其他节点接收并验证通过后，将其加入 TCP 连接列表

### 数据复制（TCP）

- 与每个集群节点建立独立的 TCP 长连接
- 消息格式：

```
+--------+---------+
| 4 bytes |  N bytes |
+--------+---------+
| length | payload  |
+--------+---------+
```

- `length`：大端序（`htonl`）的 payload 长度
- `payload`：protobuf 序列化后的 `CacheCommand` 消息

---

## 项目目录结构

```
binary_log_agent/
├── README.md                          # 本文件
├── config/
│   └── log.conf                       # log4cpp 日志配置
├── proto/
│   └── configure.proto                # 节点发现配置协议定义
└── src/
    ├── Makefile                       # 构建脚本
    ├── main.cpp                       # 主入口
    ├── shm.h/cpp                      # 共享内存管理
    ├── shmreader.h/cpp                # 共享内存读取器
    ├── connector.h/cpp                # TCP 网络连接器
    ├── replicator.h/cpp               # 数据复制器
    ├── naming.h/cpp                   # 命名服务与节点发现
    ├── filelock.h/cpp                 # 文件锁
    ├── md5.h/cpp                      # MD5 工具
    ├── memdb.h/cpp                    # 共享内存结构解析
    ├── configure.pb.h/cpp             # protobuf 生成文件（配置）
    ├── common_local_cache.pb.h/cpp    # protobuf 生成文件（缓存命令）
    └── shared_memory_struct.pb.h/cpp  # protobuf 生成文件（共享内存对象）
```

---

## 技术要点

- **双缓冲共享内存**：索引区与数据区分离，数据区采用轮转文件机制，写满后自动切换到新的共享内存文件
- **文件锁同步**：通过 `index.lock` / `data.*.lock` 实现多进程间的读写互斥与同步
- **自动重连**：`Connector` 在连接断开后自动尝试重连，并附带 5 秒退避间隔
- **心跳保活**：每个连接独立维护心跳线程，每 5 秒发送一次心跳包
- **节点失效检测**：`NamingService` 定期检查节点心跳时间，超过 45 秒未更新视为失效

---

## 协议文件说明

- **`proto/configure.proto`**：定义了节点发现阶段的配置消息 `ConfigObject`，用于组播广播与验证
- **`common_local_cache.proto`**（生成 `common_local_cache.pb.h/cpp`）：定义缓存操作命令 `CacheCommand`
- **`shared_memory_struct.proto`**（生成 `shared_memory_struct.pb.h/cpp`）：定义共享内存中的数据对象 `SharedMemoryObject`

> 注：`.pb.h` / `.pb.cpp` 为 `protoc` 编译生成的代码，请勿手动修改。

---

## 作者

本项目为分布式本地缓存系统的配套组件，用于保障多节点间缓存数据的一致性同步。