Skip to content
gokelePublic

About

No description, website, or topics provided.

Resources

Stars

14 stars

Watchers

0 watching

Forks

Latest commit

 

History

58 Commits

Folders and files

Repository files navigation

Outlook 取件台

Outlook 账号池的管理与取件系统。批量导入账号,按需在线取件收验证码,自动轮换令牌防止 90 天过期,并对外提供 API。

特点

  • 按需取件,不做轮询。 只在进入详情页、调用 API、点击刷新时才连 Outlook。
  • 邮件不落库。 全部在线获取,取到的永远是此刻邮箱上的真实状态。库里只有账号与令牌等元数据,五千个账号不到 10 MB。
  • 令牌自动续期。 启动立即补跑全部已到轮换时间的账号,运行中每分钟扫描,优先处理临近硬过期的账号并强制轮换新的 refresh_token。每批 256 个,处理完继续下一批;默认 32 并发,可在设置页调整,不设固定的 IP、应用或首验每分钟配额。网络故障保留失败退避,微软实际限流仍遵守 Retry-After。
  • 正文链接可直接打开。 HTML 与纯文本邮件里的链接都在新标签页打开,正文脚本保持禁用,远程图片默认阻断。
  • 三条通道。 Graph、IMAP、POP3 自动降级,覆盖范围变化会如实标注。
  • 防误杀。 网络故障与限流绝不把账号标记为失效;应用被封时按 client_id 熔断,而不是逐个标记账号。
  • 按规模切开存放。 PostgreSQL 上账号表按邮箱哈希切成 64 个分区,唯一性、查重与按邮箱取件都不受影响;日志按天分区,过期整个分区丢弃而不是逐行删除;总览页与调度器的计数一律封顶,代价不随账号数增长。SQLite 保持单表,本地开发与小规模部署照常。
  • 迁移不丢数据。 表结构变更整个在一个事务里完成,搬完当场核对行数,对不上就回滚、原表一个字节不动。表已经很大时不在启动时自动改,只提示由人挑维护窗口执行——期间系统照常工作。
  • 单文件部署。 前端嵌在二进制里,服务器上只需要一个可执行文件,不必再配 Nginx 托管静态资源。
  • 一键在线更新。 从 GitHub Releases 拉新版,校验 SHA256 后原地替换并自动重启,页面上就能完成。

快速开始(本地)

# 后端。什么都不用配:首次启动会自动生成 .env(含随机主密钥,权限 0600),
# 数据库默认用 SQLite,不需要安装任何数据库服务。
cd backend
go run .
# 首次启动会在日志里打印随机生成的管理员密码,形如:
# {"level":"WARN","msg":"已创建默认管理员,请立即登录并修改密码","username":"admin","password":"..."}
#
# 这串密码只出现这一次。没看到或忘了,重新生成一个:
#   go run . -reset-password admin        # 服务器上是 ./api -reset-password admin

# 前端
cd frontend
npm install
npm run dev        # 打开 http://localhost:5173

全部配置项与各自的取舍见 env.example,自动生成的 .env 内容与它一致,可以直接编辑。

主密钥务必备份。 库里的授权码与账号密码都用它加密,丢了就只能重新导入全部账号。对外提供服务时建议把它挪到环境变量里,别让密钥和数据库躺在同一个目录被一起打包带走。

导入格式

每行一个账号,四段以 ---- 分隔:

邮箱----密码----clientid----授权码
邮箱----密码----clientid----授权码----辅助邮箱----辅助邮箱密码
alice@outlook.com----Pa55word----9e5f94bc-e8a4-4e73-b8be-63364c29d753----M.C528_BAY.0.U.-Cj1…
bob@hotmail.com--------9e5f94bc-e8a4-4e73-b8be-63364c29d753----M.C528_BAY.0.U.-Ab9…
carol@outlook.com----Pa55word----9e5f94bc-…----M.C528_BAY.0.U.-Xy2…----carol.bak@gmail.com----BakPw

这四段通常由账号提供方一并给出,直接整段粘过来就行,不需要自己去微软申请。 其中 clientid 是微软的应用注册 ID,授权码就是 OAuth2 的 refresh_token —— 它们看着像是要自己去 Azure 折腾一遍,实际上买号时就跟着一起来了。 密码可以为空(连续两个分隔符)。

后两段是可选的,有就写、没有就按四段写,同一批里混着也没关系。识别靠第五段是不是合法邮箱,而不是看总段数——授权码是不透明串,里面出现 ---- 完全可能;认不出六段就把多切的部分原样接回授权码,因此授权码含分隔符不会被误切。辅助邮箱密码同样可以留空。

密码与辅助邮箱密码都加密存储,辅助邮箱本身也不随列表下发。要查看得在账号列表点「凭据」,用登录密码解锁一次,之后 15 分钟内免重复输入,每次查看都留审计。

导入不做任何在线验证,避免短时间大量请求触发风控。账号写入后状态为未验证,验证由首次取件触发,或由调度器在下一次扫描时连续处理首验队列。想快速知道这批账号的成色,用导入后的抽样验证,几分钟给出有效率估算。

API

前缀 /api/v1,请求头 Authorization: Bearer <api_key>。

全部端点都收 POST,参数写在 JSON 请求体里;读取类端点同时保留 GET。

# 取回此刻邮箱里最新的一封,顺便提取验证码。默认立刻返回。
curl -sS -X POST "https://console.example.com/api/v1/mail/latest" \
  -H "Authorization: Bearer kl_xxx" \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@outlook.com","code_regex":"default"}'

响应里的 folder_coverage 说明本次实际覆盖了哪些文件夹。降级到 POP3 时只有 ["inbox"],意味着看不到垃圾邮件,结果可能不完整。

主要参数:email 或 account_id、folder(默认 inbox,junk)、from、subject、since、code_regex、lease(申请账号租约的秒数),以及可选的 wait。

wait 默认是 0,也就是立刻返回。 传了它才长轮询:服务器挂住连接一直等新邮件, 最长 120 秒,请求会卡住几十秒——那是它的本意,用于"先触发对方发信、再来收码"的流程。 调试时不要顺手加它,更不要同时加 subject 过滤,那等于让邮箱里已有的邮件一封都不返回。

完整的接口列表、字段说明与错误码见 API.md。

没有缓存层,高频轮询会直接命中 429。要等新邮件请用 wait 长轮询,不要自己循环调用。

部署

生产不使用容器。前端嵌在二进制里,目标机器上只需要一个可执行文件加一个 PostgreSQL。

最省事的方式是直接下 Releases 里的现成二进制, 名字形如 outlook-v0.4.3-linux-amd64(Windows 是 -windows-amd64.exe):

V=v0.4.3   # 换成 Releases 页上最新的那个标签
curl -LO "https://github.com/gokele/Outlook/releases/download/$V/outlook-$V-linux-amd64"
# 下面的命令与 systemd 配置里都写作 ./api,所以改个名
mv "outlook-$V-linux-amd64" api && chmod +x api

checksums.txt 与二进制一同发布,介意的话先 sha256sum -c 对一遍。

要自己构建(或者改过代码)也可以:

# 1. 构建前端,产物拷进 backend/web/dist 供 go:embed 打包
cd frontend && npm ci && npm run build
rm -rf ../backend/web/dist && cp -R dist ../backend/web/dist

# 2. 编译。版本号必须由 ldflags 注入,否则是 dev 版,在线更新对它不生效。
#    pgx 与 modernc.org/sqlite 都是纯 Go,CGO_ENABLED=0 即可从任意平台交叉编译。
cd ../backend
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
  go build -trimpath -ldflags="-s -w -X main.version=v0.1.0" -o api .

把 api 拷到服务器、配好环境变量、跑起来即可。不需要 Nginx 托管静态资源;要 HTTPS 时前面挂一层反代即可。

第一次登录

用户名是 admin。密码是首次启动时随机生成的,只在日志里出现那一次,形如:

{"level":"WARN","msg":"已创建默认管理员,请立即登录并修改密码","username":"admin","password":"..."}

用 systemd 起的服务在 journalctl -u <服务名> | grep 已创建默认管理员 里看。

错过了或者忘了也不要紧,在服务器上重新生成一个:

./api -reset-password admin              # 生成一个新的强密码并打印
./api -reset-password admin:自己定的密码   # 或者直接指定

重设会同时踢掉该账号的全部会话。

进程守护与反代按各自环境配置,仓库不提供模板 —— 它们与具体的发行版、 反代软件和证书方案强耦合,给一份模板多半还是要改。需要注意的只有两点: .env 权限设为 0600,以及在线更新会重启进程(Linux 走 execve, 进程号不变,systemd 之类无感)。

主密钥用 openssl rand -hex 32 生成,通过环境变量或 systemd 的 EnvironmentFile 注入,配置文件权限必须是 0600。一旦启用不可更改,改了之后已存的令牌全部无法解密。它不进备份,备份泄露不足以解出令牌。

在线更新

设置页有「在线更新」面板:显示当前版本、GitHub 上最新发布的说明,一键完成下载、校验、替换与重启。

发布由 GitHub Actions 完成,推一个标签即可:

git tag v0.1.0 && git push origin v0.1.0

.github/workflows/release.yml 会构建前端、嵌进二进制、交叉编译四个平台 (linux/windows × amd64/arm64)、生成 checksums.txt,并按上一个标签以来的提交 自动整理变更说明,发成一个 Release。

校验和不是可选项。 更新决定本机下一刻运行什么代码,是系统里权限最高的通路;缺 checksums.txt 的发布会被直接拒绝,散列对不上则整个放弃、不碰原二进制。

替换分两层保护:

  1. 换之前先把新二进制跑一次 -version。 跑不起来(下载损坏、架构不匹配)或版本号与发布标签对不上,就整个放弃——现役文件一个字节都不会被动。
  2. 换之后写一个待验证标记。 新版本要自己活到「端口绑上、开始对外服务」那一刻才会把它删掉;没删掉就重启了,下次启动会自动换回 api.old。

第一层是第二层的前提:重启走 execve,没有进程守护时新版本一崩就没人再拉起它,事后回滚也就没机会执行。

替换的顺序在两个平台上不同:Unix 直接覆盖原路径(内核按 inode 引用运行中的映像),Windows 必须先把自己改名让路——它不允许覆盖运行中的 exe;放不回去时会把旧的改回来。

重启在 Linux 上走 execve 原地换映像,进程号不变,不依赖 systemd 之类的进程守护;Windows 没有 execve,改为拉起新进程后自己退出,进程号会变。安装需要重新输入登录密码。

用 UPDATE_REPO 改更新源,留空即关闭。dev 版不参与在线更新——本地构建的代码不在任何发布里,"更新"它等于悄悄丢掉未提交的改动。

登录防护

后台登录与所有「重新输入登录密码」的二次确认(改密、改名、查看账号凭据、 含令牌导出、安装更新)都有限速:连续失败超过 4 次后按指数退避封禁, 单 IP 最长 15 分钟,单用户名最长 60 秒。

两个维度的上限刻意不同。按用户名封是双刃剑——攻击者只要不停用正确的用户名 试错误密码,就能把真正的管理员一起锁在门外,拒绝服务比爆破更容易达成。 所以这一维只做「拖慢到不划算」,长封禁只作用于来源 IP。

密码用 PBKDF2-SHA256(21 万次迭代、16 字节随机盐)存储,恒定时间比较。 用户不存在时也会跑一次等量的哈希计算——否则响应快几十毫秒, 那个时间差就是个用户名枚举探针。

登录失败会记录来源 IP 与用户名(不记密码)。被爆破时日志是唯一的信号。

来源 IP 必须可信,限速才有意义。 只有当连接本身来自 TRUSTED_PROXIES 列出的地址时,X-Forwarded-For / X-Real-IP 才会被采信;其他情况一律以 TCP 连接地址为准。默认只信本机回环,对应「Nginx 与本服务同机」这种部署。

这不是可有可无的配置项:无条件相信这些请求头,等于让请求方自己声明来源 IP —— 每次换一个伪造值就能让限速永远数不满,填上白名单里的地址就能穿过 API Key 的 IP 白名单。反代装在另一台机器上时,务必把那台机器的地址加进 TRUSTED_PROXIES; 直接对外、前面没有反代时留空最安全。配错了会在日志里提示一次。

注意事项

  • 没有历史。 邮件不落库,调用方错过的验证码在系统内找不回,只能重新触发发信。
  • 调度器不要关。 关了之后闲置账号会在 90 天后失效。总览页在关闭时会显示第一个账号预计失效的日期。
  • 关注失败原因与应用熔断。 调度器不按 IP 或应用预设每分钟配额;应用注册出问题时仍会熔断,避免把同批健康账号一起判为失效。总览展示真实队列和轮换进度。

About

No description, website, or topics provided.

Resources

Stars

14 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages