dunglas/mercure

Mercure 镜像文档

1. 镜像概述和主要用途

Mercure 是一个开源的实时通信解决方案，旨在提供快速、可靠且电池高效的服务器发送实时更新（Server-Sent Events, SSE）能力。作为 WebSocket API 及相关高级库/服务的现代替代品，Mercure 基于 HTTP 和 SSE 协议构建，原生支持现代 Web 浏览器、移动应用及 IoT 设备。其核心用途是为 REST 和 GraphQL API 添加流式和异步通信能力，实现服务器到客户端的实时数据推送。

官方 Docker 镜像 dunglas/mercure 提供了 Mercure 协议参考实现（hub，即服务器）的容器化部署方式，支持生产环境使用，同时提供免费（开源）版本及托管服务选项。

2. 核心功能和特性

• 实时通信协议：基于 HTTP 和 SSE 构建，轻量且标准化，无需复杂的双工连接管理。
• 替代 WebSocket：作为 WebSocket 的现代替代品，降低实时通信的实现复杂度和资源消耗。
• 原生跨平台支持：无需额外客户端库，直接兼容现代浏览器（通过 EventSource API）、移动应用及 IoT 设备。
• 高效与低功耗：优化电池使用，适合移动设备和资源受限场景（如 IoT）。
• API 扩展能力：无缝集成 REST 和 GraphQL API，为现有后端服务添加实时更新能力。
• 可靠性：支持消息重连和恢复，确保更新不丢失（需服务端配置）。
• 开源与标准化：协议规范为 IETF 互联网草案，参考实现以 AGPL 许可开源，可自由部署和定制。

3. 使用场景和适用范围

• REST/GraphQL API 实时扩展：为现有 API 添加实时通知、数据更新能力（如社交媒体通知、实时分析数据）。
• Web 应用实时功能：实现网页实时聊天、实时仪表盘、协作编辑等功能。
• 移动应用后台更新：为移动应用提供低功耗的实时数据推送（如新闻推送、状态更新）。
• IoT 设备数据传输：适用于 IoT 设备向中心服务器发送或接收实时数据（如传感器数据流）。
• 多客户端实时同步：需要保持多客户端状态一致的场景（如多人游戏、实时协作工具）。

4. 使用方法和配置说明

4.1 基本 Docker 部署

4.1.1 使用 docker run 启动

以下命令启动 Mercure hub，监听本地 8080 端口（开发环境配置，生产环境需强化安全设置）：

bash
docker run -d \
  -p 8080:8080 \
  -e MERCURE_PUBLISHER_JWT_KEY='your-publisher-secret' \
  -e MERCURE_SUBSCRIBER_JWT_KEY='your-subscriber-secret' \
  -e MERCURE_EXTRA_DIRECTIVES='cors_origins *' \
  -e MERCURE_ALLOW_ANONYMOUS=1 \
  dunglas/mercure

4.1.2 使用 docker-compose 部署

创建 docker-compose.yml 文件，配置持久化、网络及环境变量：

yaml
version: '3.8'

services:
  mercure:
    image: dunglas/mercure
    ports:
      - "8080:8080"  # HTTP 端口（生产环境建议替换为 443 并启用 HTTPS）
    environment:
      - MERCURE_LISTEN_ADDR=:8080
      - MERCURE_PUBLISHER_JWT_KEY=your-secure-publisher-key  # 生产环境使用强密钥
      - MERCURE_SUBSCRIBER_JWT_KEY=your-secure-subscriber-key
      - MERCURE_CORS_ORIGINS=https://your-frontend.example.com  # 限制允许的前端域名
      - MERCURE_ALLOW_ANONYMOUS=0  # 禁用匿名订阅
      - MERCURE_DEBUG=0  # 禁用调试模式
    volumes:
      # 挂载 SSL 证书（生产环境启用 HTTPS 时需配置）
      # - ./certs:/etc/mercure/certs
    restart: unless-stopped

启动服务：

bash
docker-compose up -d

4.2 核心环境变量配置

Mercure 镜像通过环境变量进行配置，以下为常用核心配置项（完整列表请参考 官方文档）：

4.3 生产环境配置注意事项

• 安全认证：必须配置强密钥（MERCURE_PUBLISHER_JWT_KEY 和 MERCURE_SUBSCRIBER_JWT_KEY），推荐使用 RSA/EC 密钥对而非 HMAC 密钥。
• HTTPS 启用：生产环境需通过挂载 SSL 证书（如 Let's Encrypt）并配置 MERCURE_LISTEN_ADDR=:443 启用 HTTPS，避免 SSE 连接被拦截。
• CORS 限制：MERCURE_CORS_ORIGINS 应指定具体前端域名，而非使用 *，增强安全性。
• 持久化存储：如需消息持久化（用于重连恢复），可配置外部存储（如 Redis），具体参考官方文档。

5. 许可与版权

Mercure 参考实现（hub）采用 AGPLv3 许可协议，详细条款见 官方许可文档。

6. Credits

• 由 Kévin Dunglas 创建。
• 图形设计由 https://github.com/ginifizz 完成。
• 由 Les-Tilleuls.coop 赞助开发。