gog backup push 完全指南用 age 加密分片将 Google Workspace 数据安全推入 Git 仓库【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligog backup push是 gogcli 备份体系的写入命令它把 Gmail、日历、联系人、云端硬盘等服务数据导出为确定性 JSONL 行经 gzip 压缩后用 ageX25519加密成多个*.jsonl.gz.age分片只将密文提交并推送到你指定的 Git 远程仓库。读完本文你将掌握gog backup push的全部参数语义、加密与分片原理、检查点续传机制以及如何用--dry-run、--query/--max等参数安全地做小规模试运行从而把 Google 账户数据完整、私密、可验证地备份到私有仓库。命令概览与适用场景gog backup push属于 gog backup 命令族其职责help 原文是 “Export services into encrypted backup shards”即把服务导出为加密备份分片。它默认只备份gmail一个服务可通过--services all扩展到全部受支持的服务每次 push 只会更新被选中服务的分片未选中服务的既有分片会被原样保留前提是 age 接收者集合未变。对应的单服务变体是gog backup gmail push见 internal/cmd/backup.go它聚焦 Gmail 备份并暴露精简后的--checkpoint-rows/--checkpoint-interval参数。推荐工作流是先gog backup init完成一次性初始化再用gog backup push定期执行# 初始化创建 age 身份、写入本地配置、播种备份仓库、打印公钥接收者 gog backup init \ --repo ~/Projects/backup-gog \ --remote https://github.com/steipete/backup-gog.git # 备份全部受支持服务 gog backup push --services all --account steipetegmail.com # 仅备份 Gmail gog backup push --services gmail --account steipetegmail.com # 有界冒烟测试只取最近 7 天、最多 25 封邮件 gog backup push --services gmail --account steipetegmail.com --query newer_than:7d --max 25初始化生成的本地配置默认位于~/.gog/backup.jsonage 私钥默认位于~/.gog/age.key默认远程仓库为https://github.com/steipete/backup-gog.git见 internal/backup/config.go。需要说明的是备份仓库应为私有仓库因为 Git 历史中会长期保存密文分片服务载荷在 Git 见到之前就已加密。完整参数表Flagsgog backup push的完整参数如下这些参数均已在 internal/cmd/backup.go 中定义并由 kong 解析Flag类型默认值说明--access-tokenstring直接使用提供的 access token绕过存储的 refresh tokentoken 约 1 小时过期-a--account--acctstring认证的 Google API 命令所用账户邮箱、别名或auto--best-effortbooltrue将可选服务的错误记录为备份行后继续--clientstringOAuth 客户端名称选择存储的凭据与 token 桶--colorstringauto颜色输出auto|always|never--configstring备份配置路径--disable-commandsstring逗号分隔的禁用命令列表支持点路径--drive-binary-contentsbool在加密分片中包含非 Google 的 Drive 二进制文件字节--drive-collaborationbooltrue备份 Drive 权限、评论与修订元数据--drive-content-max-bytesint640跳过大于该字节数的单个 Drive 内容导出0 表示不限制--drive-content-timeouttime.Duration2m每个 Drive 文件的导出/下载超时--drive-contentsbooltrue将 Drive 文件内容下载/导出进加密分片-n--dry-run--dryrun--noop--previewbool不实际修改打印预期动作并成功退出--enable-commandsstring逗号分隔的启用命令前缀列表支持点路径限制 CLI--enable-commands-exactstring逗号分隔的精确启用命令列表父命令不自动启用子命令-y--force--assume-yes--yesbool对破坏性命令跳过确认--gmail-cachebooltrue在本地缓存已抓取的 Gmail 原始邮件使中断的全量备份可续跑--gmail-checkpoint-intervaltime.Duration30m抓取期间两次 Gmail 检查点推送之间的最大间隔0 禁用时间触发检查点--gmail-checkpoint-rowsint10000每个加密检查点块的 Gmail 邮件数0 禁用行数触发检查点--gmail-checkpointsbooltrue在长时间缓存抓取期间提交并推送不完整的加密 Gmail 检查点--gmail-no-sendboolfalse阻止 Gmail 发送操作Agent 安全--gmail-refresh-cachebool即使本地备份缓存已有条目也重新抓取 Gmail 邮件-h--helpkong.helpFlag显示上下文相关帮助--homestring覆盖 gogcli 的 config/data/state/cache 根目录等价于GOG_HOME--identitystring本地 age 身份路径--include-spam-trashbooltrue包含 Gmail 垃圾邮件与回收站-j--json--machineboolfalse向 stdout 输出 JSON最适合脚本--max--limitint640最多导出的 Gmail 邮件数0 表示全部--no-input--non-interactive--noninteractivebool从不提示失败即退出适合 CI--no-pushbool仅在本地提交不推送到远程-p--plain--tsvboolfalse向 stdout 输出稳定、可解析的纯文本TSV无颜色--querystring用于有界/测试备份的 Gmail 查询--quota-projectstring承担 API 用量费用的 Google Cloud 项目作为 X-Goog-User-Project 发送部分 API 在使用--access-token或 ADC 时需要--readonlyboolfalse在运行时阻止变更型 API 请求auth add也会请求只读 OAuth 作用域--recipient[]string公共 age 接收者可重复--remotestring备份 Git 远程 URL--repostring本地备份仓库路径--results-onlyboolJSON 模式下只输出主结果丢弃 nextPageToken 等信封字段--select--pick--projectstringJSON 模式下选择逗号分隔的字段尽力而为支持点路径--servicesstringgmail逗号分隔的待备份服务列表--shard-max-rowsint1000每个加密分片的最大行数-v--verbosebool开启详细日志--versionkong.VersionFlag打印版本并退出--workspace-max-filesint0每类 Docs/Sheets/Slides 的原生 Workspace 元数据最大文件数0 表示全部--workspace-nativebool在 Drive 导出之外额外抓取完整的原生 Docs/Sheets/Slides API JSON--wrap-untrustedboolfalseJSON/raw 输出中将抓取的文本字段包裹在外部不可信内容标记内从 internal/cmd/backup.go 可见 push 命令会校验参数合法性--max、--drive-content-max-bytes、--workspace-max-files、--gmail-checkpoint-rows、--gmail-checkpoint-interval必须非负--shard-max-rows必须大于 0--drive-content-timeout必须大于 0否则直接以 usage 错误退出——这保证了在发起昂贵抓取之前参数即已有效。默认启用的行为开关gog backup push默认开启以下四项关键能力docs/backup.md--drive-contents下载/导出 Drive 文件内容进加密分片用--no-drive-contents做仅元数据 Drive 备份--drive-collaboration备份每文件的权限、评论、修订元数据用--no-drive-collaboration跳过--gmail-cache在本地缓存抓取的原始 Gmail 邮件用--no-gmail-cache关闭--best-effort可选服务出错时把错误记录为加密errors分片并继续而不是中断整个备份用--no-best-effort让错误直接上抛。--drive-content-timeout默认 2m约束单个 Drive 文件的导出/下载耗时超时的文件被表示为加密错误行这样一次卡住的 Google 导出不会拖垮整个运行。--drive-content-max-bytes则允许你跳过体积过大的单文件下载。建议仅在明确需要把非 Google 二进制文件字节放进 Git 分片时才开启--drive-binary-contents个人 Drive 很容易包含数十 GB 二进制内容同理仅当需要比可读 Drive 导出更重的原生 API JSON 时才开启--workspace-native并用--workspace-max-files限制原生抓取规模用于冒烟测试。支持的服务清单--services接受逗号分隔的服务名all展开为全部服务常量定义见 internal/cmd/backup.gogmail标签与原始 MIME 邮件gmail-settings过滤器、转发地址、自动转发、send-as 别名、假期回复、委托可见性、POP、IMAP 与语言设置calendar日历列表条目、ACL、设置/颜色以及全部事件含已删除事件contactsPeople API 联系人、其他联系人与联系人分组tasks任务列表与任务含已完成、已删除、隐藏与指派任务drive共享云端硬盘、文件元数据、权限、评论、修订元数据以及下载/导出的文件内容workspaceDocs/Sheets/Slides 清单加上通过 Drive 发现的 Forms 与表单响应appscript通过 Drive 发现的 Apps Script 项目与源码内容chat聊天空间与消息账户/API 允许时classroom课程、主题、公告、作业、材料与提交内容groups账户所属 Cloud Identity 群组及成员列表仅 Workspace需显式 Workspace 账户 service-account 委派或等效的cloud-identity.groups.readonly直连 token/ADC 访问adminWorkspace Admin Directory 用户、群组与群组成员需既有 Admin SDK/全网域委派配置keepGoogle Keep 笔记仅 Workspace需既有 Keep service-account 配置。Drive 内容导出的默认格式为Google Docs 导出.docx与 MarkdownSheets 导出.xlsxSlides 导出.pptx与 PDFDrawings 导出 PNG 与 PDF二进制文件仅保留元数据除非设置--drive-binary-contents。groups、admin、keep为 Workspace-only 服务普通消费者账户访问会得到加密错误行--best-effort下。加密管线与仓库布局每次 push 的分片写入由 internal/backup/backup.go 的PushSnapshot驱动加密细节在 internal/backup/crypto.go。对每个分片管线为导出确定性 JSONL 行encodeJSONL逐行 JSON 编码见 backup.go用固定 gzip 时间戳Unix 0压缩 JSONL——固定时间戳让相同内容的 gzip 输出确定便于增量检测用filippo.io/age的 X25519 对每个配置的接收者加密压缩字节只向 Git 写入加密的*.jsonl.gz.age文件临时文件先写.shard-*.age随后原子 rename 并chmod 0600见 crypto.go写入明文manifest.json内含供 status/verify 使用的元数据。备份仓库布局密文分片按账户哈希分目录、Gmail 邮件按月分桶README.md manifest.json data/gmail/account-hash/labels.jsonl.gz.age data/gmail/account-hash/messages/YYYY/MM/part-0001.jsonl.gz.age data/calendar/account-hash/... data/contacts/account-hash/... data/drive/account-hash/... data/tasks/account-hash/... data/groups/account-hash/... data/admin/account-hash/... data/keep/account-hash/...账户哈希是sha256(小写账户字符串)的前 12 字节 hex见 internal/cmd/backup.go用来避免在路径中直接出现邮箱明文。Gmail 邮件分片先按邮件InternalDate归入YYYY/MM月桶桶内按内部日期与消息 ID 排序再按行数与保守的明文字节上限切分分片默认最多 1000 行、32 MiB 明文上限见 internal/backup/gmail/planner.go 与 backup.go超大邮件也不会产生被 GitHub 拒绝的巨型 blob。manifest.json刻意保持明文的元数据manifest.json是有意不加密的结构定义见 internal/backup/backup.go它包含格式版本、导出时间、公共 age 接收者、服务名、账户哈希、分片路径、行数、加密字节大小以及用于校验的明文 SHA-256 哈希。它不包含邮件主题、发件人、收件人、正文、原始消息 ID 或标签。因此它必然向仓库读者泄露以下运维元数据导出时间、公共接收者、服务名、账户哈希、分片路径与月桶、行数、加密字节大小、明文分片哈希、备份节奏与 Git 历史中哪些分片发生了变化。账户哈希不是匿名手段——它只是避免把邮箱字面量写进路径能猜到地址的人可以算出并比对同样的哈希。备份启动时还会调用rejectSymlinkPathbackup.go拒绝仓库内任何符号链接防止路径逃逸读取时resolveShardPath会把分片路径严格限制在data/与checkpoints/目录下的.age文件内backup.go。断点续传Gmail 缓存与检查点大邮箱全量备份可能耗时数小时为此--gmail-cache默认开启会在本地 OS 用户缓存目录gogcli/backup/gmail/account-hash/下缓存抓取结果消息列表分页检查点位于list-v1/已抓取的原始消息位于raw-v1/缓存文件以 Gmail 消息 ID 的 SHA-256 为键存储的正是将要加密进分片的同一行。中断后重跑可以复用已抓取的消息且加密分片是从缓存流式构建的internal/backup/gmail/planner.go因此全量邮箱备份不会把所有原始邮件常驻内存。--gmail-refresh-cache强制重新抓取缓存是本地明文数据若你希望机器上不保留加密备份/导出之外的本地邮件副本请清理该目录。对于启用缓存的长时间抓取--gmail-checkpoints默认开启会把不完整的加密检查点快照推入备份 Git 仓库检查点分片与清单位于checkpoints/gmail/account-hash/run-id/使用与普通分片相同的 age 接收者加密提交信息形如checkpoint: gmail backup 20000/359635清单带incomplete: true标记见 internal/backup/backup.go 的CheckpointManifest。status、verify、cat、export始终以根manifest.json为权威完成态不会把部分数据当作成品快照。检查点提交经由单一有序的后台队列推送internal/backup/async_push.gogogcli 记录确切提交 SHA、继续缓存抓取、逐个推送排队的 SHA。瞬时推送失败会重试最多 3 次、指数退避见 async_push.goGitHub 硬性拒绝如GH001、Large files detected、pre-receive hook declined见 async_push.go会终止后续检查点因为后续提交会继承被拒对象。最终完成的备份会等待队列排空然后把已完成的检查点消息分片提升进根清单而不是把整个邮箱再加密成第二个数 GB 的最终推送。检查点复用通过精确的有序消息 ID 指纹判定并要求清单运行、服务、账户、行数与加密接收者保持兼容。调节提交节奏的参数--gmail-checkpoint-rows默认 10000/--gmail-checkpoint-interval默认 30m置 0 禁用对应触发条件--no-gmail-checkpoints完全禁用检查点推送。Gmail 专用变体gog backup gmail push使用--checkpoint-rows/--checkpoint-interval。安全边界与信任模型加密分片保护的是 Google 内容本身邮件正文、主题、发件人、收件人、原始 MIME 载荷、标签、Drive 文件名、联系人、事件标题等。当前信任模型见 docs/backup.md机密性只要~/.gog/age.key保持私密对私有 GitHub 备份仓库而言是可靠的对随机损坏的完整性age 认证、gzip 解码、明文 SHA-256 与行数校验可捕获损坏分片verify的实现在 backup.go逐片解密、比对哈希、比对 JSONL 行数对仓库写入方的完整性有限。任何有推送权限的人都可能用公共接收者加密不同数据来替换备份内容因此应限制仓库写权限并审查异常提交密钥泄露若AGE-SECRET-KEY-...泄露Git 历史中的历史分片可能被解密。应轮换接收者、重新加密并把旧 Git 历史视为已暴露除非重写历史并清除所有副本。已知的加固方向包括清单只存密文哈希、把明文哈希移入加密分片元数据用本地签名密钥签名清单或提交让verify能证明备份的创建者以及为在意尺寸侧信道的部署场景增加分片填充或禁用 gzip。另外加密分片头部被限制为 2 MiB 与 1024 个接收者 stanza读取方会拒绝超限分片。干跑、输出与配套命令gog backup push --dry-run只校验选项并打印预期备份计划不会认证、接触 Google、访问仓库、创建缓存或检查点、也不会写任何文件实现见 internal/cmd/backup.go输出服务、仓库、远程、身份、接收者、推送开关与 Gmail 相关参数gog backup gmail push --dry-run行为一致。backup init/status/verify/cat/export的--dry-run同理只打印解析后的仓库/拉取计划。--no-push让 push 只提交到本地仓库而不推远程对应backup.Options.Push见 internal/cmd/backup.go。-j/--json输出机器可读结果repo、changed、encrypted、shards、按服务聚合的count.*便于脚本与 CI-p/--plain输出稳定 TSV。长 Gmail 运行的 list、fetch、shard-build 计数器写入 stderrstdout 保持可解析。推送完成后可用gog backup status检查明文清单元数据、gog backup verify解密每个分片并校验哈希与行数、gog backup cat解密单个分片、gog backup export生成未加密的本地可读副本如--gmail-format markdown导出带 YAML 元数据的message.md与attachments/目录。status/verify/cat/export会先拉取或克隆配置的远程--no-pull直接读取本地状态。所有读命令在仓库缺失或克隆失败时都不会新建 Git 仓库配合--no-input时Git 操作会禁用凭据/UI 提示与 SSH 密码提示。推荐的落地实践先小后大首次使用--services gmail --query newer_than:7d --max 25做有界冒烟测试确认认证、加密、推送链路全部正常后再--services all全量控制本地缓存默认 Gmail 缓存与检查点是明文本地数据明确机器上允许保留邮件副本否则用--no-gmail-cache --no-gmail-checkpoints限制推送内容体积为控制仓库体积可用--drive-content-max-bytes跳过超大单文件、用--no-drive-binary-contents默认不收录非 Google 二进制字节、用--no-drive-collaboration跳过每文件协作元数据CI 化之前先干跑--dry-run--no-input可在不触碰任何远程资源的前提下验证参数组合与备份计划密钥管理age1...公共接收者可以安全写进~/.gog/backup.json与manifest.jsonAGE-SECRET-KEY-...私钥必须留在本地或密码管理器中可重复使用--recipient为多个接收者加密同一份备份。更多细节可参阅备份总览 docs/backup.md、父命令 gog backup 与完整命令索引 docs/commands/README.md。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考