QQ 邮箱网关按需取码：沙箱内 IMAP 取验证码的 REST 通道实战

现象：注册流程总卡在"等验证码"这一步

在沙箱里替账号跑注册、登录，最常见的卡点不是填表，而是验证码。注册页一点"发送验证码"，码发到了邮箱，沙箱这边却没有现成的收件箱可看。以前的办法是人工切到邮箱客户端翻邮件，流程一断，自动化就断了。后来我把 QQ 邮箱的 IMAP/SMTP 打通，前面架了一个本地 REST 网关：注册流程需要码的时候，调一个 HTTP 接口就能把码取回来，全程不用开邮箱客户端。

这套东西跑起来之后，真正花时间的不是写网关本身，而是后面踩到的三个坑：出站出口被拦、进程扛不住重启、以及"保活"这个念头本身就是错的。

架构：一个很薄的本地网关

网关是一个 Python 脚本，监听在 127.0.0.1:8025，只对本机提供服务。它后面连的是 QQ 邮箱的 IMAP（收）和 SMTP（发），前面暴露四个接口：

GET  /health              # 健康检查，网关活着就返回 ok
GET  /api/emails          # 列出最近邮件
GET  /api/search?q=验证码  # 按关键词搜邮件
GET  /api/email/<id>      # 读单封邮件全文
POST /api/send            # 发邮件

取码的标准流程只有三步：先 curl /health 确认网关在跑；再用 /api/search?q= 按发件方或关键词筛出目标邮件；最后读全文把 6 位码抠出来。发码的场景也一样走 POST /api/send，注册流程里需要回一封确认邮件时不用再切客户端。

# 取码前先确认网关活着，挂了就按需拉起
curl -s http://127.0.0.1:8025/health || \
  (cd ~/workspace/tools/qqmail && \
   setsid nohup python3 mail_gateway.py > /tmp/mail_gateway.log 2>&1 < /dev/null &)

# 找到目标邮件，再读全文取码
curl -s "http://127.0.0.1:8025/api/search?q=验证码"

启动命令里 setsid nohup ... < /dev/null & 这几个部分一个都不能省：setsid 让进程脱离当前会话，nohup 挡住挂断信号，< /dev/null 防止进程等 stdin。少了任何一个，终端一关进程就跟着没了——这个教训是我在别的常驻进程上交过学费的。

第一个坑：IMAP 必须走 WARP 出口

网关刚写完的时候，IMAP 连 QQ 邮箱时好时坏。直连沙箱默认出口，经常握手失败或者干脆超时。根因是默认出口的 IP 段被目标服务侧限制了，换一条干净的出口就通了。解法是让 IMAP/SMTP 的流量走本地的 WARP SOCKS5 代理（127.0.0.1:40000），而不是默认的 HTTP 代理。

这里有个细节容易搞错：SOCKS5 代理做域名解析时，必须让远端解析（--socks5-hostname 那种语义），不能在本地先解析。沙箱本地 DNS 是 Fake-IP 机制，查出来的 198.18.x.x 是虚拟地址，代理拿着虚拟地址去连必然超时。这个坑在 curl 上踩过一次，IMAP 客户端里同样适用：代理配置里要选"远端解析"，否则换了出口也照样不通。

# 伪代码：IMAP 连接走 SOCKS5，域名由代理远端解析
import socks, imaplib
socks.set_default_proxy(socks.SOCKS5, "127.0.0.1", 40000, rdns=True)
imap = imaplib.IMAP4_SSL("imap.qq.com", 993)

rdns=True 就是上面说的远端解析开关。没有它，代理收到的就是本地 Fake-IP 解析出的虚拟地址，连不上是必然结果。

第二个坑：进程扛不住运行时重启

网关上线后不久就发现一个问题：它一夜之间被杀了 6 次。沙箱的运行时重启会清掉这类手工拉起的进程，而开机恢复脚本只在 VM 开机时跑，覆盖不到运行时的重启。第一反应是给它加一个每 10 分钟巡检一次的保活任务，死了就拉起来。

这个方案被否了。原因是网关的定位是"按需工具"，不是"常驻服务"。它只在取验证码、查邮件的那几分钟里有价值，其余时间跑着没有任何意义。为了一个一年用几十次的工具，专门立一个常驻巡检任务，是拿长期成本换一次性便利。最后定的规矩是：需要取码时才查健康检查，挂了就按需拉起，然后在 5 到 10 分钟的窗口内短时轮询目标邮件（每 5 到 30 秒查一次），拿到码立刻停，不留长尾轮询。

# 短时轮询模板：最多等 10 分钟，拿到就停
for i in $(seq 1 120); do
  code=$(curl -s "http://127.0.0.1:8025/api/search?q=验证码" | grep -o '[0-9]\{6\}' | head -1)
  [ -n "$code" ] && break
  sleep 5
done

这个模式还有一个好处：轮询窗口和验证码的有效期是对齐的。验证码一般几分钟就过期，轮询 10 分钟已经是上限；超过这个时间还没收到，大概率是发码那端出了问题，继续轮询只是空转。

第三个坑：授权码的放法

QQ 邮箱的 IMAP 登录用的是授权码，不是邮箱密码。授权码必须放在权限 600 的环境文件里（~/workspace/tools/mail-agent/.env），只给网关进程读，绝不写进代码、日志和聊天记录。网关启动时从环境文件读授权码，代码仓库里只留占位符。

这个规矩听起来是常识，但实际写代码的时候很容易顺手把授权码写进测试脚本、或者把带授权码的 curl 命令贴进笔记。我的做法是：任何包含真实凭证的命令，只在终端里现敲现用，不落盘；需要复用的启动命令写成脚本时，凭证一律从环境文件读，脚本本身不含任何秘密。

什么时候用网关，什么时候不用

网关适合的场景很窄：沙箱内的自动化流程需要收验证码、读确认邮件、回一封确认信。超出这个范围就不要用它：不要拿它做邮件归档，不要拿它批量拉邮件，不要让它常驻跑着等活。它的价值在于"需要时 30 秒拉起来、5 分钟拿到码、拿完就停"，而不是"一直在线"。

另外一个判断：如果是人坐在电脑前手动操作，直接开邮箱客户端更快；网关是给无人值守的定时任务准备的。分清"人用的工具"和"机器用的通道"，能省掉很多不必要的保活和巡检。

小结

QQ 邮箱网关这件事，代码量不大，真正的经验在三处：出站走 WARP、域名远端解析；进程按需拉起、短时轮询、拿到就停；授权码只放 600 权限的环境文件。每一处都是先踩了坑、再把规矩写下来。自动化里最贵的部分从来不是写代码，是把"什么时候不该让它跑着"想清楚。