kalbasit/signal-api-receiver

Signal API Receiver https://github.com/kalbasit/signal-api-receiver

概述

问题背景

我在服务器上使用由https://github.com/bbernhard开发的优秀https://github.com/bbernhard/signal-cli-rest-api，并将Home Assistant配置为向我和家庭群组发送各类通知。对于许多自动化场景，快速发送消息至关重要，因此我将API运行在https://github.com/bbernhard/signal-cli-rest-api?tab=readme-ov-file#execution-modes。

最近，我希望添加一种方式，让Home Assistant能够接收我们发送的消息以触发（或停止）自动化。然而，当signal-api运行在json-rpc模式时，/v1/receive端点仅支持WebSocket，而Home Assistant的signal_messenger集成依赖REST API调用，不支持WebSocket。

解决方案

本项目signal-api-receiver提供了一个轻量级包装器，通过以下方式解决该问题：

• 消费/v1/receive端点的WebSocket流
• 在内存中存储接收到的消息
• 暴露REST API用于检索这些消息

这种方式使Home Assistant能够轻松接收Signal消息并触发自动化，无需修改现有的signal-cli-rest-api或Home Assistant集成。

替代方案

虽然开发signal-api-receiver解决了我的即时需求，但还有其他潜在解决方案：

1. 改进Home Assistant与Signal的集成，使其支持WebSocket
2. 向signal-cli-rest-api提议新增一个支持REST的端点

这些替代方案长期来看可能更全面，但创建包装器为我的特定用例提供了更即时、更聚焦的解决方案。

核心功能与特性

• WebSocket消费：持续接收来自signal-cli-rest-api的WebSocket消息流
• 消息存储：在内存中暂存接收到的消息
• REST API暴露：提供简单的REST端点供外部系统（如Home Assistant）检索消息
• 轻量级设计：资源占用低，易于部署和集成

API端点

signal-api-receiver提供以下API端点：

• GET /receive/pop：

  • 从队列中每次返回一条消息
  • 若无可用消息，返回204 No Content状态码

• GET /receive/flush：

  • 返回所有可用消息的列表
  • 若无可用消息，返回空列表（[]）

使用场景与适用范围

适用于已部署signal-cli-rest-api（运行在json-rpc模式）并使用Home Assistant的用户，需要通过接收Signal消息触发自动化场景，例如：

• 通过发送特定消息控制智能家居设备
• 接收系统通知并自动执行响应操作
• 实现基于消息的家庭自动化工作流

使用方法与配置说明

Docker运行（推荐）

signal-api-receiver在https://hub.docker.com/r/kalbasit/signal-api-receiver提供镜像，这是推荐的运行方式。

首先拉取镜像：

bash
docker pull kalbasit/signal-api-receiver:latest

示例运行命令：

bash
docker run -p 8105:8105 \
  -e SIGNAL_ACCOUNT="your_signal_account" \
  -e SIGNAL_API_URL="wss://your-signal-api-url" \
  kalbasit/signal-api-receiver:latest

参数说明：

• -p 8105:8105：将主机的8105端口映射到容器的8105端口
• -e SIGNAL_ACCOUNT="your_signal_account"：设置Signal账号环境变量，需替换为实际账号
• -e SIGNAL_API_URL="wss://your-signal-api-url"：设置Signal API的WebSocket URL，需替换为实际API地址

更多信息请参考https://hub.docker.com/r/kalbasit/signal-api-receiver页面。

从源码运行

从源码运行时，需提供以下命令行参数：

全局选项：

• --log-level <value>：设置日志级别（默认："info"），可通过$LOG_LEVEL环境变量设置

serve命令选项：

• --record-message-type <value>：指定要记录的消息类型，有效值："receipt"、"typing"、"data"、"data-message"、"sync"，可重复指定多个类型（默认："data-message"）
• --repeat-last-message：若启用，当无新消息时重复最后一条消息（适用于/receive/pop），可通过$REPEAT_LAST_MESSAGE环境变量设置（默认：false）
• --signal-account <value>：必填，指定Signal账号，可通过$SIGNAL_ACCOUNT环境变量设置
• --signal-api-url <value>：必填，指定Signal API的URL（含协议，如wss://signal-api.example.com），可通过$SIGNAL_API_URL环境变量设置
• --server-addr <value>：设置服务器监听地址（默认：":8105"），可通过$SERVER_ADDR环境变量设置

默认服务器监听地址为:8105，可通过--server-addr修改（如--server-addr :8080）。

查看所有可用选项：

bash
signal-api-receiver serve --help

Kubernetes部署示例

以下是在Kubernetes中部署signal-api-receiver的示例（假设已存在signal-cli-rest-api部署，此处未展示）：

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: signal-api-receiver
  labels:
    app: signal-receiver
    tier: api
spec:
  replicas: 1
  selector:
    matchLabels:
      app: signal-receiver
      tier: api
  template:
    metadata:
      labels:
        app: signal-receiver
        tier: api
    spec:
      containers:
        - image: kalbasit/signal-receiver:latest
          name: signal-receiver
          args:
            - /bin/signal-api-receiver
            - serve
            - --signal-api-url=ws://signal-api.ns.svc:8080
            - --signal-account=+19876543210
          ports:
            - containerPort: 8105
              name: receiver-web
          livenessProbe:
            httpGet:
              path: /healthz
              port: receiver-web
            initialDelaySeconds: 15
            periodSeconds: 20
          readinessProbe:
            httpGet:
              path: /healthz
              port: receiver-web
            initialDelaySeconds: 5
            periodSeconds: 10

yaml
apiVersion: v1
kind: Service
metadata:
  name: signal-api-receiver
  labels:
    app: signal-receiver
    tier: api
spec:
  type: ClusterIP
  ports:
    - name: receiver-web
      port: 8105
  selector:
    app: signal-receiver
    tier: api

yaml
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
  name: signal-api
spec:
  entryPoints:
    - web
    - websecure
  routes:
    # 此规则用于已存在的signal-cli-rest-api服务（未展示）
    - kind: Rule
      match: Host(`signal-api.example.com`)
      priority: 10
      services:
        - name: signal-api
          port: http-web
    # 新规则用于signal-api-receiver
    - kind: Rule
      match: Host(`signal-api.example.com`) && Path(`/receive`)
      priority: 20
      services:
        - name: signal-api-receiver
          port: receiver-web
  tls:
    secretName: signal-api-tls

许可证

本项目采用MIT许可证 - 详见https://github.com/kalbasit/signal-api-receiver/blob/main/LICENSE%E6%96%87%E4%BB%B6%E3%80%82