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服务器：需提前配置集群地址、认证信息（如有）
配置文件：需准备服务配置文件（参考示例配置）

4.2 Docker容器运行

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

bash
# 假设本地配置文件路径为 ./config.yml
docker run -v $(pwd)/config.yml:/app/config.yml 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:
      max***: 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: 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"  # 卷内文件名