diogob/postgres-websockets

数据库WebSocket桥接镜像

镜像概述

该Docker镜像提供了WebSocket与数据库的连接桥梁，通过数据库原生的LISTEN/NOTIFY机制，实现数据库事件与WebSocket客户端之间的实时通信。用户无需开发复杂的中间件代码，即可快速构建数据库事件的实时推送服务，适用于需要数据库变更实时通知的场景。

核心功能和特性

核心功能

• LISTEN/NOTIFY事件监听：持续监听数据库指定频道的NOTIFY事件
• WebSocket实时推送：将数据库事件通过WebSocket协议实时推送给连接的客户端
• 多频道支持：可同时监听多个数据库通知频道，实现多类型事件的并行处理

主要特性

• 轻量级设计：基于高效的事件驱动架构，资源占用低
• 配置简单：通过环境变量即可完成数据库连接和WebSocket服务配置
• 跨平台兼容：支持主流操作系统的Docker环境
• 自动重连：数据库连接断开后自动尝试重连，保证服务稳定性

使用场景和适用范围

典型使用场景

• 实时数据仪表盘：数据库数据更新后立即推送至前端仪表盘
• 即时通知系统：订单状态变更、消息提醒等事件的实时推送
• 协同编辑工具：多用户编辑时的数据变更实时同步
• 实时监控告警：数据库异常事件（如阈值超限）的即时告警推送

适用范围

• 支持LISTEN/NOTIFY机制的数据库（如PostgreSQL）
• 需要数据库事件实时通知的Web应用
• 中小型项目的实时通信需求
• 快速原型开发和生产环境部署

使用方法和配置说明

基本使用（docker run）

bash
docker run -d \
  --name db-ws-bridge \
  -e DB_HOST=your-db-host \
  -e DB_PORT=5432 \
  -e DB_USER=db-user \
  -e DB_PASSWORD=db-password \
  -e DB_NAME=db-name \
  -e LISTEN_CHANNELS=order_updates,stock_changes \
  -e WS_PORT=8080 \
  -p 8080:8080 \
  [镜像名称]

Docker Compose配置示例

yaml
version: '3.8'

services:
  db-ws-bridge:
    image: [镜像名称]
    container_name: db-ws-bridge
    restart: always
    environment:
      - DB_HOST=postgres
      - DB_PORT=5432
      - DB_USER=postgres
      - DB_PASSWORD=postgres_password
      - DB_NAME=app_db
      - LISTEN_CHANNELS=user_activity,system_events
      - WS_PORT=8080
      - LOG_LEVEL=info
    ports:
      - "8080:8080"
    depends_on:
      - postgres

  postgres:
    image: postgres:14
    container_name: postgres-db
    restart: always
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres_password
      - POSTGRES_DB=app_db
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

配置参数详解

环境变量配置

客户端连接示例

WebSocket客户端可通过ws://<host>:<WS_PORT>/连接服务，连接成功后将收到数据库NOTIFY事件的JSON格式消息：

javascript
// 浏览器端WebSocket连接示例
const ws = new WebSocket('ws://localhost:8080/');

ws.onopen = () => {
  console.log('WebSocket连接已建立');
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('收到数据库事件:', data);
  // 处理事件数据...
};

ws.onclose = () => {
  console.log('WebSocket连接已关闭');
};

注意事项

1. 确保数据库支持LISTEN/NOTIFY机制（如PostgreSQL）
2. 数据库用户需具备LISTEN权限
3. 生产环境建议配置TLS加密（如使用反向代理添加wss支持）
4. 高并发场景下建议配置连接池参数
5. 监听频道名称应避免使用特殊字符