Initial commit: Telegram Management System
Some checks failed
Deploy / deploy (push) Has been cancelled
Some checks failed
Deploy / deploy (push) Has been cancelled
Full-stack web application for Telegram management - Frontend: Vue 3 + Vben Admin - Backend: NestJS - Features: User management, group broadcast, statistics 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
你的用户名
336
SMS_PLATFORM_INTEGRATION_GUIDE.md
Normal file
336
SMS_PLATFORM_INTEGRATION_GUIDE.md
Normal file
@@ -0,0 +1,336 @@
|
||||
# 短信接码平台集成使用指南
|
||||
|
||||
## 一、系统概述
|
||||
|
||||
本系统已集成10个主流短信接码平台，提供统一的接口和智能路由功能，支持：
|
||||
- 多平台自动切换
|
||||
- 智能价格比较
|
||||
- 自动故障转移
|
||||
- 负载均衡
|
||||
- 统一的API接口
|
||||
|
||||
## 二、已集成的平台
|
||||
|
||||
| 平台名称 | 平台代码 | 特点 | 支持国家数 |
|
||||
|---------|---------|------|-----------|
|
||||
| SMS-Activate | smsactivate | 老牌服务商，稳定可靠 | 180+ |
|
||||
| SMS-PVA | smspva | 价格适中，服务稳定 | 100+ |
|
||||
| 5SIM | 5sim | 价格低廉，号码质量高 | 180+ |
|
||||
| SMS-Man | smsman | 即时激活，高成功率 | 150+ |
|
||||
| GetSMSCode | getsmscode | 支持支付宝/微信支付 | 100+ |
|
||||
| SMS-REG | smsreg | 老牌服务商，稳定可靠 | 120+ |
|
||||
| OnlineSIM | onlinesim | 号码资源丰富 | 100+ |
|
||||
| TextNow | textnow | 免费美国号码 | 美国/加拿大 |
|
||||
| Receive-SMS | receivesms | 支持长期租赁 | 80+ |
|
||||
| SMS-Service | smsservice | 新兴平台，价格优势 | 90+ |
|
||||
|
||||
## 三、配置说明
|
||||
|
||||
### 1. 平台API密钥配置
|
||||
|
||||
在数据库的 `config` 表中配置各平台的API密钥：
|
||||
|
||||
```javascript
|
||||
// SMS-Activate
|
||||
smsKey: "你的API密钥"
|
||||
|
||||
// SMS-PVA
|
||||
sms2Username: "用户名"
|
||||
sms2Pwd: "密码"
|
||||
|
||||
// 新平台配置格式
|
||||
sms_5sim_apiKey: "API密钥"
|
||||
sms_smsman_apiKey: "API密钥"
|
||||
sms_getsmscode_username: "用户名"
|
||||
sms_getsmscode_apiKey: "API密钥"
|
||||
// ... 其他平台类似
|
||||
```
|
||||
|
||||
### 2. 平台启用配置
|
||||
|
||||
```javascript
|
||||
// 在 sms_platforms 表中配置
|
||||
{
|
||||
platform_code: "5sim",
|
||||
is_enabled: true, // 是否启用
|
||||
priority: 1, // 优先级（数字越小优先级越高）
|
||||
api_key: "xxx" // API密钥
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 路由策略配置
|
||||
|
||||
```javascript
|
||||
// 在 config 表中配置
|
||||
sms_default_strategy: "price" // 默认策略
|
||||
sms_failover_strategy: "priority" // 故障转移策略
|
||||
sms_max_retries: 30 // 最大重试次数
|
||||
sms_retry_interval: 20000 // 重试间隔(毫秒)
|
||||
```
|
||||
|
||||
## 四、API接口使用
|
||||
|
||||
### 1. 获取手机号码
|
||||
|
||||
```bash
|
||||
POST /api/sms/getPhone
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer {token}
|
||||
|
||||
{
|
||||
"country": "us", // 国家代码（可选）
|
||||
"service": "tg", // 服务类型，默认tg
|
||||
"platform": "5sim", // 指定平台（可选）
|
||||
"strategy": "price" // 选择策略：price|success|balance|random|priority
|
||||
}
|
||||
|
||||
# 响应
|
||||
{
|
||||
"code": 0,
|
||||
"data": {
|
||||
"id": "12345",
|
||||
"phone": "1234567890",
|
||||
"country": "us",
|
||||
"price": 15,
|
||||
"platform": "5sim",
|
||||
"platformName": "5SIM"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 获取验证码
|
||||
|
||||
```bash
|
||||
POST /api/sms/getSmsCode
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer {token}
|
||||
|
||||
{
|
||||
"orderId": "12345",
|
||||
"phone": "1234567890",
|
||||
"platform": "5sim",
|
||||
"maxRetries": 30, // 可选，默认30次
|
||||
"retryInterval": 20000 // 可选，默认20秒
|
||||
}
|
||||
|
||||
# 响应
|
||||
{
|
||||
"code": 0,
|
||||
"data": {
|
||||
"code": "123456"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 设置订单状态
|
||||
|
||||
```bash
|
||||
POST /api/sms/setStatus
|
||||
Content-Type: application/json
|
||||
Authorization: Bearer {token}
|
||||
|
||||
{
|
||||
"orderId": "12345",
|
||||
"status": "complete", // complete|cancel|6|8
|
||||
"platform": "5sim"
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 查询平台余额
|
||||
|
||||
```bash
|
||||
# 单个平台余额
|
||||
GET /api/sms/platforms/{platformCode}/balance
|
||||
Authorization: Bearer {token}
|
||||
|
||||
# 所有平台余额
|
||||
GET /api/sms/balances
|
||||
Authorization: Bearer {token}
|
||||
```
|
||||
|
||||
### 5. 获取价格列表
|
||||
|
||||
```bash
|
||||
GET /api/sms/prices?service=tg&country=us
|
||||
Authorization: Bearer {token}
|
||||
|
||||
# 响应
|
||||
{
|
||||
"code": 0,
|
||||
"data": {
|
||||
"priceList": [
|
||||
{
|
||||
"platform": "5sim",
|
||||
"platformName": "5SIM",
|
||||
"code": "us",
|
||||
"name": "美国",
|
||||
"price": 15,
|
||||
"count": 1000
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 6. 平台健康检查
|
||||
|
||||
```bash
|
||||
GET /api/sms/platforms/{platformCode}/health
|
||||
Authorization: Bearer {token}
|
||||
```
|
||||
|
||||
### 7. 获取统计信息
|
||||
|
||||
```bash
|
||||
GET /api/sms/statistics?startDate=2024-01-01&endDate=2024-01-31
|
||||
Authorization: Bearer {token}
|
||||
```
|
||||
|
||||
## 五、代码使用示例
|
||||
|
||||
### 1. 直接使用SmsServiceManager
|
||||
|
||||
```javascript
|
||||
const SmsServiceManager = require("@src/util/sms/SmsServiceManager");
|
||||
|
||||
// 获取手机号码（自动选择最优平台）
|
||||
const phoneResult = await SmsServiceManager.getPhone({
|
||||
country: "us",
|
||||
service: "tg",
|
||||
strategy: "price" // 选择最便宜的平台
|
||||
});
|
||||
|
||||
console.log(`获取到号码: ${phoneResult.phone}, 平台: ${phoneResult.platformName}`);
|
||||
|
||||
// 获取验证码
|
||||
const code = await SmsServiceManager.getSmsCode(
|
||||
phoneResult.id,
|
||||
phoneResult.phone,
|
||||
phoneResult.platform
|
||||
);
|
||||
|
||||
console.log(`验证码: ${code}`);
|
||||
|
||||
// 完成激活
|
||||
await SmsServiceManager.setOrderStatus(phoneResult.id, "complete", phoneResult.platform);
|
||||
```
|
||||
|
||||
### 2. 使用兼容的SimUtil
|
||||
|
||||
```javascript
|
||||
const SimUtil = require("@src/util/SimUtil");
|
||||
|
||||
// 新方法（推荐）
|
||||
const phone = await SimUtil.getPhone({
|
||||
country: "us",
|
||||
strategy: "price"
|
||||
});
|
||||
|
||||
// 旧方法（兼容）
|
||||
const smsBean = await SimUtil.getBean();
|
||||
const phone2 = await smsBean.getPhone();
|
||||
```
|
||||
|
||||
### 3. 批量价格比较
|
||||
|
||||
```javascript
|
||||
// 获取所有平台的美国号码价格
|
||||
const priceList = await SmsServiceManager.getPriceList("tg", "us");
|
||||
console.log("价格列表（从低到高）:", priceList);
|
||||
|
||||
// 获取推荐平台
|
||||
const recommended = await SmsServiceManager.getRecommendedPlatform({
|
||||
country: "us",
|
||||
service: "tg"
|
||||
});
|
||||
console.log("推荐平台:", recommended);
|
||||
```
|
||||
|
||||
## 六、高级功能
|
||||
|
||||
### 1. 智能路由策略
|
||||
|
||||
系统支持5种路由策略：
|
||||
|
||||
- **price**: 价格优先，自动选择最便宜的平台
|
||||
- **success**: 成功率优先，选择成功率最高的平台
|
||||
- **balance**: 余额均衡，优先使用余额较多的平台
|
||||
- **random**: 随机选择，实现负载均衡
|
||||
- **priority**: 优先级模式，按配置的优先级选择
|
||||
|
||||
### 2. 自动故障转移
|
||||
|
||||
当某个平台出现故障时，系统会自动切换到备用平台：
|
||||
|
||||
```javascript
|
||||
// 平台故障时会自动重试其他平台
|
||||
const phone = await SmsServiceManager.getPhone({
|
||||
maxRetries: 3 // 最多尝试3个不同的平台
|
||||
});
|
||||
```
|
||||
|
||||
### 3. 缓存机制
|
||||
|
||||
- 国家列表缓存：24小时
|
||||
- 价格信息缓存：1小时
|
||||
- 平台状态缓存：5分钟
|
||||
- 验证码缓存：10分钟
|
||||
|
||||
### 4. 健康检查
|
||||
|
||||
系统每5分钟自动检查所有平台的健康状态，包括：
|
||||
- API连通性
|
||||
- 余额查询
|
||||
- 响应时间
|
||||
|
||||
## 七、监控和统计
|
||||
|
||||
### 1. 实时监控
|
||||
|
||||
- 平台余额监控
|
||||
- 成功率统计
|
||||
- 响应时间监控
|
||||
- 故障告警
|
||||
|
||||
### 2. 统计报表
|
||||
|
||||
- 日/周/月使用统计
|
||||
- 成本分析
|
||||
- 平台对比
|
||||
- 国家分布
|
||||
|
||||
## 八、最佳实践
|
||||
|
||||
1. **合理配置优先级**：将稳定性高的平台设置较高优先级
|
||||
2. **启用多个平台**：至少启用3-5个平台确保高可用性
|
||||
3. **定期检查余额**：设置余额告警阈值
|
||||
4. **监控成功率**：定期查看各平台成功率，调整策略
|
||||
5. **使用缓存**：充分利用价格缓存减少API调用
|
||||
|
||||
## 九、故障排查
|
||||
|
||||
### 1. 常见错误
|
||||
|
||||
- **余额不足**：检查平台余额，及时充值
|
||||
- **API密钥错误**：验证配置的API密钥是否正确
|
||||
- **无可用号码**：该国家/服务暂时无号码，尝试其他平台
|
||||
- **超时错误**：增加重试次数或重试间隔
|
||||
|
||||
### 2. 日志查看
|
||||
|
||||
```bash
|
||||
# 查看短信服务日志
|
||||
tail -f backend/logs/tg.log | grep "短信"
|
||||
|
||||
# 查看特定平台日志
|
||||
tail -f backend/logs/tg.log | grep "5SIM"
|
||||
```
|
||||
|
||||
## 十、后续优化计划
|
||||
|
||||
1. 添加更多短信平台支持
|
||||
2. 实现智能定价策略
|
||||
3. 添加批量号码获取功能
|
||||
4. 支持号码池管理
|
||||
5. 增强统计分析功能
|
||||
6. 添加WebSocket实时推送
|
||||
Reference in New Issue
Block a user