bbernhard/signal-cli-rest-api
GitHub: bbernhard/signal-cli-rest-api
围绕 signal-cli 构建的 Docker 化 Signal 即时通讯 REST API，通过标准 HTTP 接口实现消息收发、号码注册与群组管理等功能。
Stars: 2642 | Forks: 294
# Dockerized Signal Messenger REST API
本项目围绕 [signal-cli](https://github.com/AsamK/signal-cli) 创建了一个小型的 Docker 化 REST API。
目前，通过 REST 暴露了以下功能：
- 注册号码
- 使用通过短信接收到的验证码验证号码
- 向多个接收者（或群组）发送消息（及附件）
- 接收消息
- 链接设备
- 创建/列出/删除群组
- 列出/提供/删除附件
- 更新个人资料
以及[更多功能](https://bbernhard.github.io/signal-cli-rest-api/)
## 新手入门
1. 为配置创建一个目录
这允许您通过简单地删除并重新创建容器来更新 `signal-cli-rest-api`，而无需重新注册您的 Signal 号码
```
$ mkdir -p $HOME/.local/share/signal-api
```
2. 启动容器
```
$ sudo docker run -d --name signal-api --restart=always -p 8080:8080 \
-v $HOME/.local/share/signal-api:/home/.local/share/signal-cli \
-e 'MODE=native' bbernhard/signal-cli-rest-api
```
3. 注册或链接您的 Signal 号码
在这种情况下，我们将把容器注册为辅助设备，假设您的主要号码已经在手机上运行/分配。
因此，在浏览器中打开 http://localhost:8080/v1/qrcodelink?device_name=signal-api ，在手机上打开 Signal，转到 _设置 > 已链接设备_，然后使用 _+_ 按钮扫描二维码。
4. 测试您的新 REST API
调用 REST API endpoint 并发送测试消息：将 `+4412345` 替换为国际号码格式的 Signal 号码，将 `+44987654` 替换为接收者的号码。
```
$ curl -X POST -H "Content-Type: application/json" 'http://localhost:8080/v2/send' \
-d '{"message": "Test via Signal API!", "number": "+4412345", "recipients": [ "+44987654" ]}'
```
您现在应该已经向 `+44987654` 发送了一条消息。
## 执行模式
`signal-cli-rest-api` 支持三种不同的执行模式，可以通过设置 `MODE` 环境变量来控制。
* **`normal` 模式：（默认）** 每次发出 REST API 请求时都会调用 `signal-cli` 可执行文件。由于是 Java 应用程序，每次 REST 调用都需要重新启动 JVM (Java Virtual Machine)，这增加了延迟，因此是最慢的操作模式。
* **`native` 模式：** 每次发出 REST API 请求时都使用预编译的二进制文件 `signal-cli-native`（使用 GraalVM）。这使得每次调用的延迟和内存占用大大降低。在 `armv7` 平台上，此模式不可用并会回退到 `normal` 模式。由于 GraalVM 编译器处于实验阶段，native 模式可能也不太稳定。
* `json-rpc` 模式：作为 daemon 进程生成单个基于 JVM 的 `signal-cli` 实例。这种模式通常最快，但由于 JVM 会一直运行，因此需要更多的内存。
* `json-rpc-native` 模式：使用 `signal-cli-native` 二进制文件并以 daemon 模式启动（此模式基本上结合了 `native` 模式和 `json-rpc` 模式的优点）。
| 模式 | 速度 | 常驻内存占用 |
| ---------: | :------------------------------------------------------- | :-------------------- |
| `normal` | :heavy_check_mark: | 正常 |
| `native` | :heavy_check_mark: :heavy_check_mark: | 正常 |
| `json-rpc` | :heavy_check_mark: :heavy_check_mark: :heavy_check_mark: | 增加 |
| `json-rpc-native` | :heavy_check_mark: :heavy_check_mark: :heavy_check_mark: :heavy_check_mark: | 正常 |
**以 `native` 模式运行 `signal-cli-rest` 的示例**
```
$ sudo docker run -d --name signal-api --restart=always -p 9922:8080 \
-v /home/user/signal-api:/home/.local/share/signal-cli \
-e 'MODE=native' bbernhard/signal-cli-rest-api
```
这将启动一个可以通过 http://localhost:9922/v2/send 访问的 REST 服务实例。为了保留 Signal 号码注册（例如用于更新），`signal-cli` 配置的存储位置会作为 Docker Volume 映射到本地的 `/home/user/signal-api` 目录。
## 自动接收计划
此 REST API 包装器基于的 [signal-cli](https://github.com/AsamK/signal-cli)，建议定期调用 `receive`。因此，如果您还没有定期调用 `receive` endpoint，建议在 docker-compose.yml 文件中设置 `AUTO_RECEIVE_SCHEDULE` 参数。`AUTO_RECEIVE_SCHEDULE` 接受 cron 调度表达式，并在给定的时间自动调用 `receive` endpoint。例如：`0 22 * * *` 会在每天晚上 10 点调用 `receive`。如果您不熟悉 cron 调度表达式，可以使用这个[网站](https://crontab.guru)。
**警告** 调用 `receive` 将从 Signal Server 获取已注册 Signal 号码的所有消息！因此，如果您使用 REST API 来接收消息，使用 `AUTO_RECEIVE_SCHEDULE` 参数 _不是_ 一个好主意，因为您可能会因此丢失一些消息。
## 示例
示例 `docker-compose.yml` 文件：
```
version: "3"
services:
signal-cli-rest-api:
image: bbernhard/signal-cli-rest-api:latest
environment:
- MODE=normal #supported modes: json-rpc, native, normal
#- AUTO_RECEIVE_SCHEDULE=0 22 * * * #enable this parameter on demand (see description below)
ports:
- "8080:8080" #map docker port 8080 to host port 8080.
volumes:
- "./signal-cli-config:/home/.local/share/signal-cli" #map "signal-cli-config" folder on host system into docker container. the folder contains the password and cryptographic keys when a new number is registered
```
## 文档与用法
### API 参考
Swagger API 文档可以在[这里](https://bbernhard.github.io/signal-cli-rest-api/)找到。如果您更喜欢简单的基于文本文件的 API 文档，请查看[这里](https://github.com/bbernhard/signal-cli-rest-api/blob/master/doc/EXAMPLES.md)。
### 博客文章
- [在 Azure Web App for Containers 中运行 Signal Messenger REST API](https://stefanstranger.github.io/2021/06/01/RunningSignalRESTAPIinAppService/)，作者 [@stefanstranger](https://github.com/stefanstranger)
- [发送 Signal 消息](https://blog.aawadia.dev/2023/04/24/signal-api/)，作者 [@asad-awadia](https://github.com/asad-awadia)
### 社区项目
| 名称 | 类型 | 语言 | 描述 | 维护者 |
| ------------------------------------------------------------------------ | :-----: | :--------: | -------------------------------------- | :------------------------------------------------: |
| [pysignalclirestapi](https://pypi.org/project/pysignalclirestapi/) | 库 | Python | 小型 Python 库 | [@bbernhard](https://github.com/bbernhard) |
| [signalbot](https://pypi.org/project/signalbot/) | 库 | Python | 用于构建 Signal 机器人的框架 | [@signalbot-org](https://github.com/orgs/signalbot-org/people) |
| [signal-cli-to-file](https://github.com/jneidel/signal-cli-to-file) | 脚本 | JavaScript | 将传入的 Signal 消息保存为文件 | [@jneidel](https://github.com/jneidel) |
| [signal-rest-ts](https://www.npmjs.com/package/signal-rest-ts) | 库 | TypeScript | 用于构建 Signal 机器人的 TypeScript 模块 | [@pseudogeneric](https://github.com/pseudogeneric) |
| [secured-signal-api](https://github.com/codeshelldev/secured-signal-api) | API 网关 | Go | 具有许多 QoL 功能的安全 Docker API 网关 | [@codeshelldev](https://github.com/codeshelldev) |
如果您需要更多功能，请**提交工单**或**创建 PR**。
## 插件
插件机制允许您注册自定义 endpoint（具有不同的 payload），而无需 fork 本项目。详情请查看[这里](https://github.com/bbernhard/signal-cli-rest-api/tree/master/plugins)。
## 高级设置
在 Docker 容器内部可以设置一系列环境变量，用于更改一些技术细节。这些设置面向开发者和高级用户。通常您 *不需要* 在这里更改任何内容 —— 默认值就已经完全没问题了！
* `SIGNAL_CLI_CONFIG_DIR`：指定 Docker 容器内 `signal-cli` 配置目录的路径。默认为 `/home/.local/share/signal-cli/`
* `SIGNAL_CLI_UID`：指定 Docker 容器内 `signal-api` 用户的 uid。默认为 `1000`
* `SIGNAL_CLI_GID`：指定 Docker 容器内 `signal-api` 组的 gid。默认为 `1000`
* `SIGNAL_CLI_CHOWN_ON_STARTUP`：如果设置为 `false`，将跳过启动时有时会很耗时的 chown 操作。默认为 `true`
* `SWAGGER_HOST`：在 Swagger UI 中用于交互式示例的 host（在运行于反向代理后时很有用）。默认为 SWAGGER_IP:PORT。
* `SWAGGER_IP`：在 Swagger UI 中用于交互式示例的 IP。默认为容器 IP。
* `SWAGGER_USE_HTTPS_AS_PREFERRED_SCHEME`：在 Swagger UI 中将 HTTPS Scheme 作为首选 scheme。
* `PORT`：除非设置此环境变量另行指定，否则默认为端口 `8080`。
* `DEFAULT_SIGNAL_TEXT_MODE`：允许设置发送消息时应使用的默认文本模式（支持的值：`normal`，`styled`）。只有在 `send` 方法的 payload 中未明确设置 `text_mode` 时，才会使用此设置。
* `LOG_LEVEL`：允许设置日志级别。支持的值：`debug`，`info`，`warn`，`error`。如果未指定，默认为 `info`。
* `JSON_RPC_IGNORE_ATTACHMENTS`：设置为 `true` 时，在 json-rpc 模式下不会自动下载附件（默认：`false`）
* `JSON_RPC_IGNORE_STORIES`：设置为 `true` 时，在 json-rpc 模式下不会自动下载快照（stories）（默认：`false`）
* `JSON_RPC_IGNORE_AVATARS`：设置为 `true` 时，在 json-rpc 模式下不会自动下载头像（默认：`false`）
* `JSON_RPC_IGNORE_STICKERS`：设置为 `true` 时，在 json-rpc 模式下不会自动下载贴纸包（默认：`false`）
* `JSON_RPC_TRUST_NEW_IDENTITIES`：选择在 json-rpc 模式下如何信任新身份。支持的值：`on-first-use`，`always`，`never`。（默认：`on-first-use`）
标签：API封装, Docker, EVTX分析, JS文件枚举, REST API, Signal, 即时通讯, 安全防御评估, 请求拦截, 调试插件, 通讯工具