ihippik/wal-listener

WAL-Listener Docker镜像文档

1. 镜像概述和主要用途

WAL-Listener是一个用于实现事件驱动架构（Event-driven Architecture）的服务镜像。其核心功能是通过PostgreSQL数据库的逻辑解码（Logical Decoding）能力，实时订阅数据库变更事件，并将这些事件可靠地发布到NATS Streaming服务器。该服务支持事务性消息发布，确保数据库模型变更与事件发布在同一事务中完成，从而维持系统数据一致性。

2. 核心功能和特性

2.1 核心功能

• 基于PostgreSQL逻辑解码：利用PostgreSQL的WAL（Write-Ahead Logging）逻辑解码机制，捕获数据库表结构及数据的INSERT/UPDATE/DELETE变更
• 事务性消息发布：确保事件发布与数据库事务同步执行，避免数据变更与事件发布不一致
• NATS Streaming集成：原生支持将变更事件发布到NATS Streaming服务器，实现高可靠的事件传递
• 配置驱动：通过配置文件灵活定义监听规则、数据源连接参数、目标消息服务器配置等

2.2 关键特性

• 轻量级部署：容器化设计，支持Docker/Kubernetes环境快速部署
• 低侵入性：无需修改PostgreSQL业务表结构，基于数据库日志实现变更捕获
• 高可配置：支持自定义事件格式、过滤规则及重试策略

3. 使用场景和适用范围

3.1 典型使用场景

• 事件驱动架构系统：作为事件源（Event Source）组件，连接数据库与事件总线
• 实时数据同步：需将PostgreSQL数据变更实时同步至缓存、搜索服务或其他数据库的场景
• 微服务通信：实现微服务间基于事件的松耦合通信，降低服务依赖
• 数据变更审计：记录数据库变更历史，用于审计、追踪或数据恢复

3.2 适用范围

• 基于PostgreSQL的业务系统（需PostgreSQL 10+，且启用逻辑解码）
• 采用事件驱动架构的微服务集群
• 需要实时响应数据库变更的业务场景

4. 使用方法和部署说明

4.1 前提条件

• 运行中的PostgreSQL数据库：需配置wal_level=logical（启用逻辑解码），并创建具有REPLICATION权限的用户
• 运行中的NATS Streaming服务器：需提前配置集群地址、认证信息（如有）
• 配置文件：需准备服务配置文件（参考https://github.com/ihippik/wal-listener/blob/master/config_example.yml%EF%BC%89

4.2 Docker容器运行

通过挂载本地配置文件启动容器，命令示例：

bash
# 假设本地配置文件路径为 ./config.yml
docker run -v $(pwd)/config.yml:/app/config.yml docker.xuanyuan.run/ihippik/wal-listener:latest

参数说明：

• -v $(pwd)/config.yml:/app/config.yml：将本地配置文件挂载到容器内默认配置路径/app/config.yml，服务启动时自动加载该配置

4.3 Kubernetes部署

4.3.1 部署清单示例

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: wal-listener
  namespace: dev  # 部署命名空间，需提前创建
spec:
  replicas: 1  # 单副本部署（根据业务需求调整）
  strategy:
    rollingUpdate:
      maxSurge: 1        # 滚动更新时允许超出期望副本数的最大Pod数量
      maxUnavailable: 0  # 滚动更新时允许不可用的最大Pod数量（保证服务不中断）
    type: RollingUpdate  # 采用滚动更新策略
  selector:
    matchLabels:
      app: wal-listener  # 匹配标签为"app: wal-listener"的Pod
  template:
    metadata:
      name: wal-listener
      labels:
        app: wal-listener  # Pod标签
    spec:
      containers:
        - name: app
          image: docker.xuanyuan.run/ihippik/wal-listener:latest
          imagePullPolicy: IfNotPresent  # 本地存在镜像时不拉取
          command: ["./app"]  # 启动命令
          args: ["--config", "/var/configuration/config.configmap.yml"]  # 指定配置文件路径
          volumeMounts:
            - name: "config"        # 挂载配置卷
              mountPath: "/var/configuration"  # 容器内配置文件目录
              readOnly: true        # 配置文件只读
          resources:
            requests:  # 资源请求
              memory: "64Mi"
              cpu: "100m"
            limits:    # 资源限制
              memory: "64Mi"
              cpu: "100m"
      volumes:
        - name: "config"  # 定义配置卷（基于ConfigMap）
          configMap:
            name: "wal-listener"  # 引用的ConfigMap名称（需提前创建）
            items:
              - key: "config.configmap.yml"  # ConfigMap中的配置文件key
                path: "config.configmap.yml"  # 卷内文件名

4.3.2 部署步骤

1. 创建ConfigMap：将配置文件内容存入Kubernetes ConfigMap（示例中名称为wal-listener）
2. 应用部署清单：执行kubectl apply -f wal-listener-deployment.yaml
3. 验证部署：通过kubectl logs -f <pod-name> -n dev查看服务日志，确认连接正常

5. 配置说明

WAL-Listener的行为完全由配置文件驱动，需在启动时通过挂载方式将配置文件传入容器。配置文件需包含PostgreSQL连接信息、NATS Streaming连接信息、监听规则等核心参数。

5.1 配置文件获取

官方示例配置文件可参考：https://github.com/ihippik/wal-listener/blob/master/config_example.yml

5.2 配置文件挂载要求

• 容器内配置文件路径可通过启动参数--config指定（如--config /var/configuration/config.yml）
• 需确保容器对挂载路径有读权限（建议设置readOnly: true）

6. 注意事项

• PostgreSQL配置：需确保数据库wal_level=logical，且监听用户具有REPLICATION和目标数据库的SELECT权限
• NATS Streaming依赖：服务启动前需确保NATS Streaming服务器可访问，否则将阻塞事件发布
• 配置文件更新：修改配置文件后需重启容器或通过Kubernetes滚动更新使配置生效