telegram-management-system/SMS_PLATFORM_INTEGRATION_GUIDE.md

短信接码平台集成使用指南

一、系统概述

本系统已集成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密钥：

// SMS-Activate
smsKey: "你的API密钥"

// SMS-PVA
sms2Username: "用户名"
sms2Pwd: "密码"

// 新平台配置格式
sms_5sim_apiKey: "API密钥"
sms_smsman_apiKey: "API密钥"
sms_getsmscode_username: "用户名"
sms_getsmscode_apiKey: "API密钥"
// ... 其他平台类似

2. 平台启用配置

// 在 sms_platforms 表中配置
{
    platform_code: "5sim",
    is_enabled: true,      // 是否启用
    priority: 1,           // 优先级（数字越小优先级越高）
    api_key: "xxx"         // API密钥
}

3. 路由策略配置

// 在 config 表中配置
sms_default_strategy: "price"  // 默认策略
sms_failover_strategy: "priority"  // 故障转移策略
sms_max_retries: 30  // 最大重试次数
sms_retry_interval: 20000  // 重试间隔(毫秒)

四、API接口使用

1. 获取手机号码

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. 获取验证码

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. 设置订单状态

POST /api/sms/setStatus
Content-Type: application/json
Authorization: Bearer {token}

{
    "orderId": "12345",
    "status": "complete",   // complete|cancel|6|8
    "platform": "5sim"
}

4. 查询平台余额

# 单个平台余额
GET /api/sms/platforms/{platformCode}/balance
Authorization: Bearer {token}

# 所有平台余额
GET /api/sms/balances
Authorization: Bearer {token}

5. 获取价格列表

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. 平台健康检查

GET /api/sms/platforms/{platformCode}/health
Authorization: Bearer {token}

7. 获取统计信息

GET /api/sms/statistics?startDate=2024-01-01&endDate=2024-01-31
Authorization: Bearer {token}

五、代码使用示例

1. 直接使用SmsServiceManager

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

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. 批量价格比较

// 获取所有平台的美国号码价格
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. 自动故障转移

当某个平台出现故障时，系统会自动切换到备用平台：

// 平台故障时会自动重试其他平台
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. 日志查看

# 查看短信服务日志
tail -f backend/logs/tg.log | grep "短信"

# 查看特定平台日志
tail -f backend/logs/tg.log | grep "5SIM"

十、后续优化计划

1. 添加更多短信平台支持
2. 实现智能定价策略
3. 添加批量号码获取功能
4. 支持号码池管理
5. 增强统计分析功能
6. 添加WebSocket实时推送