# 木雷消息服务

**Repository Path**: muleiwu/message-push

## Basic Information

- **Project Name**: 木雷消息服务
- **Description**: 面向短信、邮件、企业微信和钉钉的统一高可用消息投递服务。业务应用只需接入一套 API，平台负责模板管理、异步排队、供应商选择、故障切换、发送回执和投递统计。
- **Primary Language**: Go
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 12
- **Forks**: 5
- **Created**: 2025-11-28
- **Last Updated**: 2026-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 木雷消息服务

简体中文 · [English](README.md)

面向短信、邮件、企业微信、钉钉和 QQ（OneBot 11）的统一高可用消息投递服务。业务应用只需接入一套 API，平台负责模板管理、异步排队、供应商选择、故障切换、发送回执和投递统计。

**技术栈：** Go 1.25+ · Redis Streams · MySQL/PostgreSQL · Vue · Ant Design Vue

![木雷消息服务系统架构](docs/archify/zh-CN/message-push-system.png)

## 为什么使用木雷消息服务？

直接接入单个供应商很容易开始，但当多个业务应用、消息类型或供应商同时存在时，凭证、模板、路由、失败处理和发送记录会迅速变得难以维护。木雷消息服务将这些能力收敛到统一的应用接入边界之后。

## 核心能力

- **多种消息渠道：** 短信、邮件、企业微信、钉钉和 [QQ（OneBot 11）](docs/onebot.md)。
- **灵活投递方式：** 单条、批量和定时消息。
- **统一配置管理：** 系统模板、服务商账号、供应商模板、供应商签名和发送通道。
- **高可用发送：** 优先级分组、平滑加权轮询、供应商切换、熔断状态、自动停用和失败重试。
- **异步消息处理：** 任务持久化、Redis Streams、Worker Pool、定时调度和死信处理。
- **安全与治理：** HMAC-SHA256 请求签名、时间戳、随机数、防重放、配额、限流和可选的 OIDC 管理员登录。
- **全链路追踪：** 发送任务、供应商请求与响应、投递回执、Webhook 日志、上行短信和统计分析。

## 投递流程

```text
业务应用
  → HMAC 鉴权、配额与发送就绪检查
  → 模板渲染与任务持久化
  → Redis Stream 或定时队列
  → 通道选择与供应商发送
  → 失败策略、回执、Webhook 与投递日志
```

![木雷消息服务发送准备台](https://static.1ms.run/mdoc/uploads/2026/07/23/b813c058-4008-45a0-9561-9281272fcc28.png)

## 本机演示

本机演示会创建带有确定性假数据的完整 SQLite 数据库，可用于浏览管理后台和制作文档截图，不会调用真实短信、邮件或机器人服务。

前置条件：

- Go 1.25 或更高版本
- 本机可用的 Redis

```bash
make demo-reset
make demo-run
```

服务启动后：

| 资源 | 地址或凭证 |
|---|---|
| 管理后台 | `http://localhost:8080/admin/` |
| 健康检查 | `http://localhost:8080/health` |
| 用户名 | `demo-admin` |
| 密码 | `demo-pass-2026` |

> SQLite 数据库、假凭证和固定管理员账号仅限本机使用。请勿将演示环境暴露到网络，也不要用于生产环境。

## 生产环境

生产安装使用 MySQL 或 PostgreSQL，并配合独立的 Redis。数据库凭证、应用加密密钥、JWT 密钥、服务商凭证和 OIDC 配置都应使用独立的生产值。

安装、API 接入、部署、安全和运维说明统一维护在[完整文档](https://mdoc.cc/mliev/message-push)中。

## 开发命令

| 命令 | 用途 |
|---|---|
| `make dev` | 以开发模式运行服务 |
| `make build` | 构建 `bin/push-service` |
| `make test` | 运行全部 Go 测试并输出覆盖率 |

## 更多文档

通过[开放通道目录与可视化接入](docs/public-channel-catalog.md)，在业务系统中选择通道、展示模板与变量、选择签名后发送消息。

打开[木雷消息服务文档](https://mdoc.cc/mliev/message-push)，查看安装指南、管理后台手册、API 认证与示例、部署说明、故障排查和架构设计。

## 许可协议

版权所有 © 2025-2026 合肥木雷坞信息技术有限公司。允许的使用方式和限制请查看 [LICENSE](LICENSE)。