快速开始
环境要求
- Node.js >= 18
- npm >= 9 或 pnpm >= 8
- Java >= 17（后端服务）
- MySQL >= 8.0
- Redis >= 6.0
- RabbitMQ >= 3.8（可选）
- Git
安装
克隆仓库
bash
git clone https://github.com/gitcoffee-os/pushreach.git
cd pushreach安装依赖
bash
npm install
# 或
pnpm install开发
启动开发服务器
bash
npm run dev
# 或
pnpm dev开发服务器启动后，访问 http://localhost:3000 即可预览。
构建生产版本
bash
npm run build
# 或
pnpm build构建产物将输出到 dist 目录。
项目结构
pushreach/
├── apps/ # 应用目录
│ ├── web/ # Web 管理后台
│ ├── mobile/ # 移动端应用
│ └── desktop/ # 桌面端应用
├── packages/ # 共享包
│ ├── ui/ # UI 组件库
│ ├── sdk/ # PushReach SDK
│ └── shared/ # 共享工具
├── server/ # 服务端
│ ├── gateway/ # API 网关
│ ├── message/ # 消息服务
│ ├── channel/ # 渠道适配器
│ ├── template/ # 模板服务
│ ├── router/ # 路由引擎
│ └── tenant/ # 租户服务
├── docs/ # 文档
└── scripts/ # 脚本配置说明
基础配置
在项目根目录创建 .env 文件：
env
# 服务端地址
VITE_API_BASE_URL=http://localhost:8080
# 应用名称
VITE_APP_NAME=PushReach服务端配置
env
# server/.env
# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_NAME=pushreach
DB_USER=root
DB_PASSWORD=your_password
# Redis 配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
# RabbitMQ 配置（可选）
RABBITMQ_HOST=localhost
RABBITMQ_PORT=5672
RABBITMQ_USER=guest
RABBITMQ_PASSWORD=guest渠道配置
短信渠道
env
# 阿里云短信
SMS_ALIYUN_ACCESS_KEY=your_access_key
SMS_ALIYUN_ACCESS_SECRET=your_access_secret
SMS_ALIYUN_SIGN_NAME=your_sign_name
# 腾讯云短信
SMS_TENCENT_SECRET_ID=your_secret_id
SMS_TENCENT_SECRET_KEY=your_secret_key
SMS_TENCENT_APP_ID=your_app_id
SMS_TENCENT_SIGN_NAME=your_sign_name邮件渠道
env
# SMTP 邮件
MAIL_SMTP_HOST=smtp.example.com
MAIL_SMTP_PORT=465
MAIL_SMTP_USERNAME=your_username
MAIL_SMTP_PASSWORD=your_password
MAIL_SMTP_FROM=noreply@example.com微信渠道
env
# 微信公众号
WECHAT_MP_APP_ID=your_app_id
WECHAT_MP_APP_SECRET=your_app_secret
# 微信小程序
WECHAT_MINI_APP_ID=your_app_id
WECHAT_MINI_APP_SECRET=your_app_secret使用示例
发送短信
typescript
import { PushReachClient } from '@pushreach/sdk'
const client = new PushReachClient({
apiKey: 'your_api_key',
apiSecret: 'your_api_secret',
baseUrl: 'http://localhost:8080'
})
await client.send({
channel: 'sms',
templateId: 'tpl_verification_code',
receivers: ['13800138000'],
params: {
code: '123456'
}
})发送邮件
typescript
await client.send({
channel: 'email',
templateId: 'tpl_welcome_email',
receivers: ['user@example.com'],
params: {
username: '张三',
activation_link: 'https://example.com/activate?token=xxx'
}
})智能路由发送
typescript
await client.send({
channel: 'auto',
templateId: 'tpl_order_notification',
receivers: ['user_id_001'],
params: {
order_no: 'ORD2024001',
status: '已发货'
},
routingStrategy: 'cost_first'
})批量发送
typescript
await client.batchSend({
channel: 'sms',
templateId: 'tpl_promotion',
receivers: ['13800138000', '13900139000', '13700137000'],
params: {
discount: '8折',
deadline: '2024-12-31'
}
})监听消息状态
typescript
client.onMessageStatus((event) => {
console.log('消息状态变更:', event)
})
client.onMessageStatus('delivered', (event) => {
console.log('消息已送达:', event)
})
client.onMessageStatus('failed', (event) => {
console.log('消息发送失败:', event)
})常见问题
Q: 如何添加新的消息渠道？
A: 通过渠道适配器 SDK 实现自定义渠道，参考 开发指南 中的渠道适配器开发章节。
Q: 如何配置智能路由策略？
A: 在管理后台的「路由管理」模块中，可以可视化配置路由规则，支持多维度条件组合。
Q: 如何实现消息去重？
A: PushReach 内置消息去重机制，通过消息指纹（Message Key）自动识别和过滤重复消息。
Q: 如何处理渠道发送失败？
A: PushReach 支持降级路由策略，主渠道失败时自动切换到备用渠道，同时支持自定义重试策略。