故障排除

本指南帮助您快速诊断和解决使用 Maildrone 过程中遇到的常见技术问题。按照分类查找相应的解决方案，如果问题仍然存在，请联系技术支持。

🚨 紧急故障

邮件发送完全中断

症状： 所有邮件都发送失败，系统报错

快速诊断：

检查系统状态页 - 是否有服务中断通知
查看活动详情页 - 确认错误信息
检查账户状态 - 是否欠费或被暂停

解决步骤：

# 1. 检查 SMTP 连接
curl -v telnet://smtp.your-server.com:587

# 2. 验证 DNS 记录
dig TXT _spf.yourdomain.com
dig TXT _dmarc.yourdomain.com

# 3. 测试发件人域名
nslookup yourdomain.com

常见原因和解决方案：

错误信息	原因	解决方案
`SMTP Authentication Failed`	SMTP 密码错误	重新配置 SMTP 设置
`Domain not found`	DNS 解析问题	联系域名服务商
`Account suspended`	账户被暂停	联系客服恢复账户
`Rate limit exceeded`	发送超限	升级套餐或等待重置

系统无法登录

症状： 输入正确用户名密码后无法登录

快速检查：

🌐 尝试其他浏览器或无痕模式
🔄 清除浏览器缓存和 Cookie
🛡️ 检查是否启用了双重认证
📡 确认网络连接正常

解决方案：

忘记密码：

点击登录页面的"忘记密码"
输入注册邮箱地址
查收重置邮件（检查垃圾箱）
点击链接设置新密码

双重认证问题：

// 如果手机丢失或验证器应用无法使用
// 使用备份恢复码登录：
1. 登录页面输入用户名密码
2. 在验证码输入框输入恢复码
3. 登录后立即更新双重认证设置

IP 被限制：

联系技术支持提供当前 IP 地址
申请临时解除限制
配置 IP 白名单

📧 邮件发送问题

邮件发送缓慢

症状： 邮件活动发送速度异常缓慢

诊断步骤：

检查发送设置

当前设置检查：
✅ SMTP 服务器响应时间
✅ 批次间隔设置  
✅ 并发连接数量
✅ 重试策略配置

监控发送队列
- 进入活动详情 > 发送状态
- 查看队列积压情况
- 检查失败重试次数

优化方案：

// 推荐的发送配置
{
  "batch_size": 100,           // 每批发送数量
  "batch_interval": 10,        // 批次间隔（秒）
  "concurrent_connections": 5,  // 并发连接数
  "retry_attempts": 3,         // 重试次数
  "retry_delay": 300          // 重试间隔（秒）
}

进阶优化：

🚀 升级到更高性能的 SMTP 服务
⚡ 使用专用 IP 地址发送
🔄 分时段发送避开高峰期
📊 监控收件方服务器响应

邮件内容显示异常

症状： 收到的邮件格式混乱、图片不显示或链接失效

HTML 渲染问题：

<!-- 问题代码示例 -->
<style>
  .container { background: #f5f5f5; }
</style>
<div class="container">内容</div>

<!-- 修复后的代码 -->
<div style="background: #f5f5f5; padding: 20px;">
  内容
</div>

图片显示问题：

检查图片 URL

# 测试图片可访问性
curl -I https://yourdomain.com/images/logo.png

# 确认返回状态码为 200
HTTP/1.1 200 OK
Content-Type: image/png

图片格式优化

<!-- 推荐的图片标签 -->
<img src="https://yourdomain.com/logo.png" 
     alt="公司Logo" 
     width="200" 
     height="100"
     style="display:block; max-width:100%; height:auto;">

链接跟踪问题：

检查点击跟踪是否正常：

// 原始链接
https://company.com/product/123

// 跟踪链接（正常）
https://track.maildrone.com/c/abc123def456

// 如果跟踪链接返回 404 错误：
1. 检查活动是否已发送
2. 确认跟踪域名 DNS 设置
3. 联系技术支持检查跟踪服务

高退信率问题

症状： 邮件退信率超过 5%

退信类型分析：

软退信（临时失败）

常见原因：
- 收件箱已满：稍后自动重试
- 服务器临时故障：24小时内重试
- 灰名单机制：发件人声誉待验证

解决方案：
✅ 系统自动处理，无需手动干预
✅ 监控重试成功率

硬退信（永久失败）

常见原因：
- 邮箱地址不存在：550 User unknown
- 域名无效：550 Domain not found  
- 被收件方拒绝：550 Message rejected

解决方案：
❌ 立即从发送列表移除
🧹 定期清理无效邮箱

预防措施：

-- 识别高风险邮箱的 SQL 查询
SELECT email, bounce_count, last_bounce_date
FROM contacts 
WHERE bounce_count >= 3 
   OR last_bounce_date > DATE_SUB(NOW(), INTERVAL 30 DAY)
ORDER BY bounce_count DESC;

邮箱验证流程：

实施双重确认订阅
定期发送重激活邮件
使用邮箱验证 API
监控域名信誉度

🔗 API 集成问题

API 请求失败

症状： API 调用返回错误响应

常见 HTTP 错误码：

400 Bad Request

{
  "error": "VALIDATION_ERROR",
  "message": "请求参数无效",
  "details": {
    "email": "邮箱格式不正确"
  }
}

解决方案：

// 正确的请求格式
const response = await fetch('https://api.maildrone.com/v2/contacts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    email: '[email protected]',  // 确保邮箱格式正确
    first_name: '张',
    last_name: '三'
  })
});

401 Unauthorized

# 检查 API 密钥格式
curl -H "Authorization: Bearer mp_live_1a2b3c..." \
     https://api.maildrone.com/v2/contacts

# 确认密钥权限范围
# 在系统设置 > API 密钥中检查权限

429 Rate Limit Exceeded

// 实施指数退避重试机制
async function apiRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After');
      const delay = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, attempt) * 1000;
      
      console.log(`Rate limited, retrying after ${delay}ms`);
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

Webhook 事件丢失

症状： 配置了 Webhook 但收不到事件通知

调试检查清单：

端点可访问性测试

# 测试 Webhook 端点
curl -X POST https://your-server.com/webhook \
     -H "Content-Type: application/json" \
     -H "X-Maildrone-Signature: sha256=test" \
     -d '{"event":"email.sent","data":{"test":true}}'

# 预期返回 200 状态码

SSL 证书验证

# 检查 SSL 证书有效性
curl -I https://your-server.com/webhook

# 或使用在线工具
# https://www.ssllabs.com/ssltest/

签名验证实现

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  
  // 注意：signature 包含 'sha256=' 前缀
  return signature === `sha256=${expectedSignature}`;
}

常见问题和解决方案：

问题	原因	解决方案
超时无响应	处理逻辑太慢	优化处理速度，异步处理
返回非 200 状态码	业务逻辑错误	修复错误处理逻辑
SSL 握手失败	证书配置问题	检查 SSL 证书和中间证书
签名验证失败	签名算法错误	检查 HMAC-SHA256 实现

🎨 模板和编辑器

模板保存失败

症状： 编辑模板时无法保存或保存后丢失

快速修复：

📋 复制当前模板内容到剪贴板
🔄 刷新页面重新登录
📝 重新粘贴内容并保存
✅ 确认保存成功提示

深层原因分析：

// 检查浏览器控制台错误信息
// 常见错误：
1. "QuotaExceededError" - 浏览器存储空间不足
   解决：清理浏览器缓存

2. "NetworkError" - 网络连接中断
   解决：检查网络连接，重试保存

3. "Payload too large" - 内容过大
   解决：优化图片大小，简化 HTML 结构

模板渲染错误

症状： 模板预览显示异常或变量未替换

变量语法检查：

<!-- 正确的变量语法 -->
<h1>你好，{{first_name}}！</h1>
<p>您的订单号是：{{order.id}}</p>

<!-- 错误的语法 -->
<h1>你好，{first_name}！</h1>     <!-- 缺少双花括号 -->
<p>订单号：{{ order_id }}</p>     <!-- 空格问题 -->

条件逻辑和循环：

<!-- 条件显示 -->
{{#if is_vip}}
  <div class="vip-badge">VIP 客户</div>
{{/if}}

<!-- 列表循环 -->
{{#each products}}
  <div class="product">
    <h3>{{name}}</h3>
    <p>价格：{{price}}</p>
  </div>
{{/each}}

调试技巧：

使用模板测试工具验证语法
检查变量名拼写是否正确
确认数据格式与模板匹配
查看浏览器控制台错误信息

📊 分析和报告

数据统计不准确

症状： 打开率、点击率等数据与实际不符

数据收集验证：

打开跟踪检查

<!-- 确认邮件包含跟踪像素 -->
<img src="https://track.maildrone.com/o/campaign_id/contact_id" 
     width="1" height="1" style="display:none;">

点击跟踪测试

# 检查链接是否正确重写
原始链接: https://company.com/products
跟踪链接: https://track.maildrone.com/c/abc123...

# 测试跟踪链接
curl -I "https://track.maildrone.com/c/abc123..."
# 应该返回 302 重定向到原始 URL

常见统计偏差原因：

问题	原因	解决方案
打开率偏低	图片被阻止加载	引导用户允许图片显示
重复统计	多次打开同一邮件	系统自动去重处理
点击率异常	安全软件预检	过滤机器人点击
地域数据缺失	IP 地址无法定位	使用更精确的 IP 库

报告导出失败

症状： 无法导出 Excel 或 PDF 报告

浏览器兼容性检查：

// 检查浏览器是否支持文件下载
function checkDownloadSupport() {
  const link = document.createElement('a');
  return typeof link.download !== 'undefined';
}

// 如果不支持，建议：
// 1. 升级浏览器到最新版本
// 2. 尝试其他浏览器（Chrome、Firefox、Safari）
// 3. 检查浏览器下载设置

网络连接测试：

# 测试大文件下载能力
curl -o /dev/null -s -w "Total time: %{time_total}s\nDownload speed: %{speed_download} bytes/sec\n" \
     https://api.maildrone.com/v2/reports/test-file

# 预期结果：
# - 能够完整下载
# - 速度合理（>100KB/s）

🔧 系统配置

DNS 设置问题

症状： 域名验证失败，邮件送达率低

SPF 记录检查：

# 查询 SPF 记录
dig TXT yourdomain.com | grep spf

# 正确的 SPF 记录示例
"v=spf1 include:_spf.maildrone.com ~all"

# 常见错误：
❌ 多个 SPF 记录
❌ 语法错误（缺少 v=spf1）
❌ 包含错误的服务商

DKIM 记录验证：

# 查询 DKIM 记录
dig TXT mp-2024-03._domainkey.yourdomain.com

# 验证 DKIM 签名
# 可以使用在线工具：
# https://www.mail-tester.com/

DMARC 策略配置：

# 查询 DMARC 记录
dig TXT _dmarc.yourdomain.com

# 推荐配置（逐步加强）
# 阶段1: "v=DMARC1;p=none;rua=mailto:[email protected]"
# 阶段2: "v=DMARC1;p=quarantine;rua=mailto:[email protected]"  
# 阶段3: "v=DMARC1;p=reject;rua=mailto:[email protected]"

SMTP 连接问题

症状： SMTP 服务器连接失败或不稳定

连接测试工具：

# 基础连接测试
telnet smtp.your-server.com 587

# SSL/TLS 连接测试
openssl s_client -connect smtp.your-server.com:465

# 发送测试邮件
swaks --to [email protected] \
      --from [email protected] \
      --server smtp.your-server.com:587 \
      --auth LOGIN \
      --auth-user [email protected] \
      --auth-password your-password

配置验证清单：

✅ SMTP 服务器地址正确
✅ 端口号正确（587/465/25）
✅ 加密方式匹配（STARTTLS/SSL）
✅ 用户名密码正确
✅ 防火墙允许相应端口
✅ ISP 未封锁 SMTP 端口

🚀 性能优化

页面加载缓慢

症状： 控制面板页面加载速度慢

前端优化检查：

网络性能测试

# 使用浏览器开发者工具
# Network 标签 > 刷新页面 > 查看：
# - 总加载时间
# - 资源大小
# - 失败的请求

缓存设置检查

// 清理浏览器缓存
// Chrome: Ctrl+Shift+Delete
// Firefox: Ctrl+Shift+Delete
// Safari: Cmd+Option+E

// 或使用无痕模式测试

CDN 连接测试

# 测试 CDN 响应时间
curl -w "Connect: %{time_connect} TTFB: %{time_starttransfer} Total: %{time_total}\n" \
     -o /dev/null -s https://cdn.maildrone.com/assets/app.js

优化建议：

🌐 使用更快的 DNS（8.8.8.8, 1.1.1.1）
🔄 定期清理浏览器缓存
📡 检查网络连接质量
🖥️ 关闭不必要的浏览器扩展

大量数据处理慢

症状： 批量导入联系人或发送大型活动时系统响应慢

批量操作优化：

// 分批处理大量联系人
async function batchImportContacts(contacts) {
  const batchSize = 1000;  // 每批1000条
  const batches = [];
  
  for (let i = 0; i < contacts.length; i += batchSize) {
    batches.push(contacts.slice(i, i + batchSize));
  }
  
  for (const batch of batches) {
    await importBatch(batch);
    // 批次间等待避免过载
    await new Promise(resolve => setTimeout(resolve, 5000));
  }
}

数据库查询优化：

📊 为常用查询字段添加索引
🔍 使用分页查询避免一次加载过多数据
⏰ 合理使用缓存减少重复查询
📈 监控慢查询并优化

📱 移动端问题

移动端显示异常

症状： 邮件在手机上显示效果差

响应式设计检查：

<!-- 确保包含 viewport meta 标签 -->
<meta name="viewport" content="width=device-width, initial-scale=1.0">

<!-- 使用媒体查询适配小屏幕 -->
<style>
  @media only screen and (max-width: 480px) {
    .container {
      width: 100% !important;
      padding: 10px !important;
    }
    
    .text {
      font-size: 16px !important;
      line-height: 1.4 !important;
    }
  }
</style>

移动端测试工具：

📱 浏览器开发者工具 > 设备模拟
📧 邮箱客户端预览：Gmail、Outlook、Apple Mail
🔍 在线测试工具：Email on Acid、Litmus

🔧 故障诊断工具

系统诊断命令

创建一个简单的诊断脚本：

#!/bin/bash
echo "Maildrone 系统诊断工具"
echo "======================"

echo "1. 网络连接测试"
ping -c 4 api.maildrone.com

echo "2. DNS 解析测试"
nslookup api.maildrone.com

echo "3. HTTPS 连接测试" 
curl -I https://api.maildrone.com/health

echo "4. 浏览器信息"
echo "User Agent: $HTTP_USER_AGENT"

echo "诊断完成，请将结果发送给技术支持"

日志收集

浏览器控制台日志：

按 F12 打开开发者工具
切换到 Console 标签
重现问题操作
复制错误信息

网络请求日志：

开发者工具 > Network 标签
勾选 "Preserve log"
重现问题
导出 HAR 文件

📞 获取帮助

如果以上解决方案都无法解决您的问题，请通过以下方式联系我们：

紧急技术支持

📧 技术支持邮箱: [email protected]
📞 紧急热线: 400-123-4567（7x24小时）
💬 在线客服: 请联系 [email protected]

提交工单时请包含：

🔍 详细问题描述：什么时候发生，具体现象
📷 截图或录屏：问题界面的视觉证据
🌐 环境信息：浏览器版本、操作系统
📋 错误信息：完整的错误提示文字
🔄 重现步骤：导致问题的具体操作步骤

我们的技术团队会在最短时间内为您解决问题！

故障排除

On this page