gogcli Gmail 加密备份实战指南：gog backup gmail push 的分片、断点续传与 Checkpoint 机制

gogcli Gmail 加密备份实战指南gog backup gmail push 的分片、断点续传与 Checkpoint 机制【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli导读本文以 gogcli 的gog backup gmail命令族为核心系统讲解如何将 Gmail 邮箱中的标签与原始 MIME 消息导出为age 加密、gzip 压缩的 JSONL 分片并推送到私有 Git 仓库。你将掌握gog backup gmail push的全部核心参数分片大小、缓存、断点续传、Checkpoint 推送、查询过滤等理解消息分片按月份分桶、本地缓存复用、崩溃可恢复 Checkpoint 提升等底层实现原理并能在几分钟内配置出一条面向全邮箱规模、可中断恢复的加密备份流水线。命令族概览gog backup gmail是gog backupEncrypted Google account backups体系下的 Gmail 专属子命令组负责Export Gmail into encrypted backup shards将 Gmail 导出为加密备份分片。命令层级如下gog backup ├── gog backup init # 初始化加密备份配置与仓库 ├── gog backup push # 将各服务导出为加密分片 ├── gog backup gmail # Gmail 备份操作 │ └── gog backup gmail push # 将 Gmail 导出为加密分片 ├── gog backup cat # 解密单个分片到 stdout ├── gog backup export # 写出本地明文导出 ├── gog backup status # 不解密分片检查备份清单 └── gog backup verify # 解密并校验全部备份分片基础用法gog backup gmail command其中唯一子命令为gog backup gmail push [flags]。与gog backup push --services gmail不同gog backup gmail push只面向 Gmail 单个服务同时暴露了更细粒度的 Gmail 专属参数缓存、Checkpoint、分片行数等是深度使用 Gmail 备份时的首选入口。gog backup gmail push 核心参数详解gog backup gmail push的可调参数分为备份业务参数与全局通用参数两类。先看业务专属参数Flag类型默认值说明--configstring备份配置文件路径默认读取~/.gog/backup.json--repostring本地备份仓库路径--remotestring备份 Git 远程仓库 URL--identitystring本地 age 私钥路径默认~/.gog/age.key--recipient[]string公开 age 接收方可重复指定多个--shard-max-rowsint1000每个加密分片的最大消息行数--checkpointsbooltrue长耗时缓存抓取期间提交并推送不完整的加密 Checkpoint--checkpoint-rowsint10000每个加密 Checkpoint 分块的消息条数0表示禁用按行触发的 Checkpoint--checkpoint-intervaltime.Duration30m抓取期间两次 Checkpoint 提交的最大时间间隔0表示禁用按时间触发的 Checkpoint--gmail-cachebooltrue在本地缓存已抓取的原始消息使中断的全量备份可断点续传--gmail-refresh-cachebool即使本地备份缓存已有条目也重新抓取消息--include-spam-trashbooltrue是否包含垃圾邮件与回收站--querystringGmail 查询语句用于有边界/测试型备份--max--limitint640最多导出的 Gmail 消息条数0表示全部--no-pushbool仅本地提交不推送到远程其中三组参数共同决定了整条流水线的行为下面逐一展开。1. 分片粒度--shard-max-rows--shard-max-rows默认 1000控制每个加密分片包含多少条消息。在源码层面internal/backup/gmail/planner.go中定义了DefaultMessageShardMaxRows 1000同时还有一条保守的明文大小上限DefaultMessageShardMaxPlaintext 32 MiB32 * 1024 * 1024 字节。也就是说分片切分是行数优先 字节兜底的双重约束// internal/backup/gmail/planner.go const ( Service gmail MessageShardKind messages DefaultMessageShardMaxRows 1000 DefaultMessageShardMaxPlaintext int64(32 * 1024 * 1024) )BuildMessageShards先按消息internalDate的年月分桶messageMonthKey生成YYYY/MM键再在同一桶内按行数与累积明文字节数切块。因此仓库中的分片路径天然带月份目录data/gmail/account-hash/messages/2026/09/part-0001.jsonl.gz.age data/gmail/account-hash/messages/2026/09/part-0002.jsonl.gz.age data/gmail/account-hash/messages/2026/08/part-0001.jsonl.gz.age这条字节上限32 MiB的意义在于即使单封邮件携带大体积附件也不至于生成会让 Git 平台拒绝的单文件超大 blob。字节切割逻辑见messageChunkEnd与messageValueChunkEndplanner.go。2. 缓存与断点续传--gmail-cache / --gmail-refresh-cacheGmail 全量备份最昂贵的阶段是逐封拉取formatraw的原始消息。为让中断的备份能够续跑--gmail-cache默认 true会在本地用户缓存目录下保存两份状态消息列表分页状态cache/backup/gmail/account-hash/list-v1/*.json记录query、max、includeSpamTrash、pageToken、已收集的ids与complete标记已抓取的原始消息cache/backup/gmail/account-hash/raw-v1/sha256(messageID).json存储与最终加密进分片完全相同的行。上述路径与Selection哈希逻辑见 cache.go。消息缓存文件以消息 ID 的 SHA-256 命名写入采用临时文件 rename且权限为0600的方式避免半写状态。在抓取阶段fetch.gorunFetch启动默认并发为 2 的工作池DefaultFetchConcurrent 2逐条先查缓存、命中则直接复用记为CacheHits未命中才调用users.messages.get(formatraw)同时校验返回的消息 ID 与请求一致errMessageIDMismatch并将新消息写回缓存。列表分页阶段默认每页 500 条DefaultListPageSize 500并检测重复pageToken以防御死循环。--gmail-refresh-cache用于强制绕过缓存重抓--no-gmail-cache则彻底关闭本地缓存层。文档 docs/backup.md 明确提示缓存是本地明文数据若不希望机器在加密备份位置之外留存邮件副本应清理该缓存目录。3. Checkpoint 崩溃恢复--checkpoints / --checkpoint-rows / --checkpoint-interval对几十万封邮件的大邮箱单次 push 可能持续数小时。--checkpoints默认 true会在长抓取期间把已抓到的部分消息加密成不完整快照推送进 Git 仓库让备份过程崩溃可恢复。其底层实现集中在 checkpoint.goCheckpoint 分片与清单位于checkpoints/gmail/account-hash/run-id/使用与正式分片相同的 age 接收方加密Checkpoint 清单带incomplete: true标记gog backup status/verify/cat/export仍以根目录manifest.json为权威完整备份不会把半成品误当正式快照提交触发条件--checkpoint-rows默认 10000 条消息或--checkpoint-interval默认 30 分钟两者任一达到即提交将对应值设为0可禁用该触发维度用--no-checkpoints可整体关闭Checkpoint 提交走单条有序后台队列记录精确 commit SHA 后继续抓取随后按序逐个推送避免并发 push 相互覆盖瞬时推送失败会重试GitHub 硬性拒绝会中止后续 Checkpoint后代提交会继承被拒对象最终完成时若存在完全匹配的 Checkpoint按有序消息 ID 指纹、run 服务、账号、行数、接收方全部一致判定则**直接提升promote**其消息分片进根 manifest而不是把整个邮箱重新加密推第二遍。Checkpoint 分片同样受行数与明文字节上限约束默认 250 行 / 32 MiB见DefaultCheckpointShardMaxRows大邮件不会造成巨型 blob。相关常量定义于 planner.go。全局通用 Flags以下全局 flags 在gog backup gmail与其子命令push上均可用保持 gogcli 全命令族一致的 CLI 体验Flag类型默认值说明--access-tokenstring直接使用提供的 access token绕过存储的 refresh tokentoken 约 1 小时过期-a/--account/--acctstring账户邮箱、别名或 auto用于已认证的 Google API 命令--clientstringOAuth 客户端名选择存储的凭据与 token 桶--colorstringauto彩色输出auto/always/never--disable-commandsstring逗号分隔的禁用命令列表支持点路径-n/--dry-run/--dryrun/--noop/--previewbool不实际变更打印预期动作并以成功退出--enable-commandsstring逗号分隔的启用命令前缀点路径用于收紧 CLI--enable-commands-exactstring逗号分隔的精确启用命令点路径父命令不自动启用子命令-y/--force/--assume-yes/--yesbool跳过破坏性命令的确认--gmail-no-sendboolfalse阻止 Gmail 发送操作Agent 安全选项-h/--helpkong.helpFlag显示上下文相关的帮助--homestring覆盖 gogcli 配置/数据/状态/缓存根目录等价于GOG_HOME-j/--json/--machineboolfalse向 stdout 输出 JSON最适合脚本化--no-input/--non-interactive/--noninteractivebool永不提示直接失败适合 CI-p/--plain/--tsvboolfalse向 stdout 输出稳定可解析文本TSV无颜色--quota-projectstring为 API 用量计费的 Google Cloud 项目以X-Goog-User-Project发送部分 API 在--access-token或 ADC 下需要--readonlyboolfalse运行时阻止变更型 API 请求auth add也会请求只读 OAuth scope--results-onlyboolJSON 模式下只输出主结果丢弃nextPageToken等信封字段--select/--pick/--projectstringJSON 模式下选择逗号分隔字段best-effort支持点路径-v/--verbosebool启用详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出中对外部获取的文本字段包裹 untrusted-content 标记注意--dry-run在gog backup gmail push上的行为仅校验参数并打印预期备份计划不进行认证、不访问 Google、不接触仓库、不创建缓存与 Checkpoint、不写任何文件见 docs/backup.md非常适合先验证配置再执行正式备份。端到端实操从初始化到验证以下步骤基于 docs/backup.md 的完整工作流。步骤 1初始化备份仓库与 age 身份gog backup init \ --repo ~/Projects/backup-gog \ --remote https://github.com/steipete/backup-gog.git该命令会生成本地配置文件与~/.gog/backup.json、按需创建 age 身份~/.gog/age.key、初始化备份 Git 仓库并打印公开接收方age1...开头可安全放入backup.json与manifest.json。使用--no-push可只本地提交而不推送远程。步骤 2执行全量 Gmail 备份gog backup gmail push --account steipetegmail.com等价地也可以使用统一的gog backup push --services gmail --account steipetegmail.comgog backup push默认开启--gmail-cache与--best-effort。推式子集只会更新被选中的服务并在 age 接收方不变的前提下保留其他服务的既有分片。步骤 3有边界的小批量冒烟测试gog backup gmail push --account steipetegmail.com \ --query newer_than:7d \ --max 25--query接受任意 Gmail 搜索语法--max限定导出条数二者组合可以在几秒内验证整条链路是否打通。正式全量备份时则省略二者。步骤 4检查、验证与解密# 不解密分片查看明文清单元数据 gog backup status # 解密每个分片校验哈希与行数 gog backup verify # 解密单个分片到 stdout gog backup cat data/gmail/account-hash/labels.jsonl.gz.age --pretty # 写出本地明文导出供日常阅读 gog backup export --out ~/Documents/gog-backup-export gog backup export --no-pull --out ~/Documents/gog-backup-markdown --gmail-format markdownstatus/verify/cat/export默认会先拉取已配置仓库--no-pull直接读本地它们永不初始化新 Git 仓库克隆失败时保持配置路径不被破坏。明文导出使用--gmail-format markdown会生成带 YAML 元数据的message.md与attachments/附件目录--gmail-format both则同时写 Markdown 与.eml。导出目录是未加密的文档明确要求不要将其放进备份 Git 仓库内。数据形态与加密流程备份内容Gmail 适配器source.go备份两类数据标签users.labels.list返回的完整标签对象ID、名称、类型、可见性、消息/线程计数原始消息users.messages.get(formatraw)返回的 base64url 编码 RFC 2822 原始 MIME 文本同时保留threadId、historyId、internalDate、labelIds、sizeEstimate字段。消息行 JSON Schema 见 cache.go 的Message结构。原始消息载荷以 base64url 形式保存在加密 JSONL 行内保持分片格式文本友好且不丢失任何 MIME 内容。加密与清单整个备份体系使用 Go 的filippo.io/age库、X25519 身份加密没有备份密码。私有身份AGE-SECRET-KEY-...必须留在本机或密码管理器中公开接收方age1...可写入backup.json与manifest.json。每个分片的处理流水线docs/backup.md 文档化流程导出确定性 JSONL 行用固定 gzip 时间戳压缩 JSONL用 age 对每个配置的接收方加密压缩字节仅向 Git 写入加密的*.jsonl.gz.age文件写出明文manifest.json元数据格式版本、导出时间、age 接收方、服务名、账号哈希、分片路径、行数、加密字节数、用于校验的明文 SHA-256。manifest.json故意保持明文但它不包含邮件主题、发件人、收件人、正文、原始消息 ID 或标签它泄露的是导出时间、接收方、账号哈希、分片路径、行数、加密字节大小与备份节奏等操作性元数据。账号哈希account-hash用于避免在路径中出现字面邮箱地址但它不是匿名机制——能猜出邮箱地址的人可以自行计算比对同一哈希。安全边界与信任模型加密分片保护的是 Google 内容本身邮件正文、主题、收发件人、原始 MIME 载荷、标签、文件名、联系人、事件标题等。当前信任模型如下机密性只要~/.gog/age.key保密对私有 GitHub 备份仓库足够安全随机损坏的完整性age 认证、gzip 解码、明文 SHA-256 与行数校验可发现损坏分片仓库写者完整性受限——任何有 push 权限的人都能用公开接收方换入不同的加密数据因此应限制仓库写权限并审查异常提交密钥泄露若AGE-SECRET-KEY-...泄露Git 历史中的历史分片可能被读取应轮换接收方、重新加密并将旧历史视为已暴露除非重写历史并删除全部副本。此外读取端对加密分片头施加 2 MiB 与 1024 个接收方 stanzas 的上限超出即拒绝以此限制头部解析开销而不限制加密内容大小。脚本化与进度输出备份命令遵循 gogcli 统一的输出约定长时间运行的 Gmail 备份会向stderr报告 list / fetch / shard-build 计数器而stdout 保持可解析。结合-jJSON或-pTSV可以在 CI 或脚本中稳定消费结果# JSON 输出仅主结果 gog backup gmail push --account steipetegmail.com --query newer_than:1d --max 10 -j # 非交互、只读校验 gog backup verify --no-input --no-pull小结gog backup gmail不是简单的下载邮箱而是一条完整的加密、分片、可恢复、可验证的备份流水线--shard-max-rows与 32 MiB 字节上限保证 Git 友好--gmail-cache让昂贵的原始消息抓取阶段断点续传--checkpoints系列参数让数小时的长任务崩溃后可恢复且最终直接复用 Checkpoint 分片status/verify/cat/export构成完整的只读验证与取回链路。对看重数据主权与可恢复性的用户而言这是把 Gmail 完整握在自己手中的实用方案。延伸阅读gog backup gmail 命令参考gog backup gmail push 命令参考gog backup 加密备份总览Gmail 适配器源码 · 抓取与并发 · 本地缓存 · 分片规划 · Checkpoint 机制【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考