gogcli 邮件打开跟踪密钥管理gog gmail track key rotate轮换机制与源码级原理【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligogcligog为gog gmail send --track提供的邮件打开跟踪功能依赖一个加密跟踪像素tracking pixel像素 URL 中携带用 AES-GCM 加密的负载由自部署的 Cloudflare Worker 解密并记录打开事件。本文以命令参考gog gmail track key为主体完整覆盖其用法、子命令与全部可用 Flags并结合 internal/cmd/gmail_track_key.go、internal/tracking/crypto.go 等源码深入讲解密钥轮换key rotation的版本化设计、密钥环keyring存储与 Worker 端兼容性帮助你安全地轮换跟踪加密密钥而不使历史跟踪 ID 失效。命令定位gog gmail track key在邮件跟踪体系中的角色gog gmail (mail,email) track key的职责是管理跟踪加密密钥Manage tracking encryption keys它是gog gmail trackEmail open tracking命令族下唯一负责密钥生命周期管理的入口。完整命令族见 gog gmail track 参考页track key管理跟踪加密密钥本文主题track opens查询邮件打开记录track setup初始化跟踪部署 Cloudflare Workertrack status查看跟踪配置状态跟踪体系的加密链路可参考 docs/email-tracking.md 的架构描述发送带--track的邮件时CLI 端把PixelPayload收件人、主题哈希、发送时间戳用当前版跟踪密钥以 AES-GCM 加密编码为 URL-safe base64 后嵌入像素 URL收件人客户端加载图片时Cloudflare Worker 用TRACKING_KEY/TRACKING_KEY_VN密钥解密负载把打开事件写入 D1 数据库gog gmail track opens通过管理密钥ADMIN_KEY向 Worker 查询打开记录。正因为密钥同时存在于 CLI 本地配置/密钥环与 Worker 环境变量中密钥一旦泄露或怀疑暴露就需要一套换钥但不断链的轮换机制——这正是track key rotate解决的问题。用法与子命令基本用法gog gmail (mail,email) track key commandmail与email互为别名。该父命令本身不执行动作只提供密钥管理子命令子命令说明gog gmail track key rotate轮换跟踪加密密钥Rotate tracking encryption key全局 Flags 完整说明gog gmail track key继承 gogcli 的全局 Flags以下表格完整继承自命令参考页Flag类型默认值说明--access-tokenstring直接使用提供的 access token绕过已存储的 refresh tokentoken 有效期约 1 小时-a--account--acctstring账户邮箱、别名或 auto用于已认证的 Google API 命令--clientstringOAuth client 名称选择已存储的凭据 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 范围--results-onlyboolJSON 模式下只输出主结果丢弃 nextPageToken 等信封字段--select--pick--projectstringJSON 模式下选择逗号分隔的字段尽力而为支持点分路径。多数命令建议使用 --fields-v--verbosebool启用详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出中将抓取到的文本字段包裹在外部不可信内容标记内命令索引见 docs/commands/README.md。track key rotate轮换命令详解用法与专属 Flagsgog gmail (mail,email) track key rotate [flags]rotate在继承全部全局 Flags 的基础上额外提供两个专属 FlagsFlag类型说明--no-deploybool只更新本地跟踪密钥不部署 Worker--worker-dirstringWorker 目录默认internal/tracking/worker前置条件从 internal/cmd/gmail_track_key.go 的实现看rotate执行前会做两层校验cfg.IsConfigured()必须为真即账户已完成gog gmail track setupEnabled、WorkerURL、TrackingKey齐备定义见 internal/tracking/config.go。否则报错tracking not configured; run gog gmail track setup first管理密钥ADMIN_KEY必须已配置。否则报错tracking admin key not configured; run gog gmail track setup again。轮换全流程源码视角Rotate.Run的完整执行链internal/cmd/gmail_track_key.goDry-run 拦截若传入-n/--dry-run仅打印预定动作account、worker_dir、deploy并成功退出加载现有密钥通过密钥环按已知版本列表加载全部版本密钥。若密钥环为空但配置文件里仍有明文TrackingKey旧版布局则将其视为版本 1 的密钥实现向后兼容生成新版本密钥nextTrackingKeyVersion取当前版本与所有已存版本中的最大值 1作为新版本号internal/cmd/gmail_track_key.go密钥本体由 internal/tracking/crypto.go 的GenerateKey()生成——使用crypto/rand读取 32 字节即256 位 AES 密钥以标准 base64 编码部署 Worker默认执行除非指定--no-deploy否则调用tracking.DeployWorkerinternal/tracking/deploy.go内部通过wrangler完成wrangler d1 create/info确保 D1 数据库存在--worker-dir默认指向仓库内的 internal/tracking/worker将全部版本密钥写入 Worker 环境变量当前版本写入TRACKING_KEY每个版本写入TRACKING_KEY_VN当前版本号写入TRACKING_CURRENT_KEY_VERSION管理密钥写入ADMIN_KEYinternal/tracking/deploy.gowrangler deploy发布 Worker。 注意 Worker 名称缺失时会提示重新执行gog gmail track setup数据库名默认与 Worker 名一致保存本地密钥把完整版本密钥集写入密钥环SecretStore.SaveTrackingKeys随后把本地配置标记为SecretsInKeyringtrue、清空配置文件中的明文TrackingKey、写入新的TrackingCurrentKeyVersion与TrackingKeyVersionsinternal/cmd/gmail_track_key.go。也就是说轮换完成后明文密钥只存在于系统密钥环keyring中JSON 配置文件不再保留输出结果普通模式TSVtracking_key_rotated true tracking_key_version N tracking_key_versions 1,2,... deployed true|falseJSON 模式-j输出account、databaseName、deployed、trackingKeyRotated、trackingKeyVersion、trackingKeyVersions、workerName字段便于脚本判断。密钥环中的存储布局internal/tracking/secrets.go 定义了按账户隔离的密钥命名规则scopedSecretKeyL230-L237tracking/account/tracking_key_vN—— 每个版本的跟踪密钥versionedTrackingKeySecretSuffixtracking/account/tracking_key—— 当前版本密钥的镜像供只读快速访问tracking/account/admin_key—— 管理密钥。读取时存在 legacy 回退若按版本读取失败会尝试旧格式键名tracking/tracking_keyinternal/tracking/secrets.go保证早期单密钥安装升级后仍可解密。版本合法性约束为1–255与密文中 1 字节版本前缀的取值范围一致internal/tracking/crypto.go。版本化密文设计为什么轮换后旧邮件仍可解密这是rotate能够不断链的核心实现在 internal/tracking/crypto.go加密EncryptWithVersionL36-L43在 nonce 之前追加 1 字节密钥版本号形成[version | nonce | ciphertexttag]结构再做 URL-safe base64无 padding编码。无版本号的EncryptL30-L32产生[nonce | ciphertexttag]的 legacy 结构解密DecryptWithKeysL88-L116接收版本号 → 密钥映射先按密文首字节识别版本并优先尝试该版本prioritizeVersionL201-L214失败后遍历其余版本最后以nonceOffset0再尝试一轮 legacy 无版本密文。任何一轮 AES-GCM 验证失败aead.Open返回错都会换下一把密钥重试密钥规范化NormalizeTrackingKeyVersionsinternal/tracking/config.go会把版本收敛到 1–255 范围内、排序并去重确保配置中不会残留非法版本。Worker 端TypeScript 实现与 Go 端算法严格对等internal/tracking/worker/src/crypto.ts 的decryptWithKeys同样按版本优先 → 全量重试 → legacy 回退的顺序用 Web Crypto AES-GCM12 字节 IV逐版本尝试解密因此 CLI 与 Worker 可独立持有不同版本的密钥子集而互相兼容。结合 docs/email-tracking.md 的说明轮换命令会生成下一个密钥版本部署所有活跃的TRACKING_KEY_VN密钥及TRACKING_CURRENT_KEY_VERSION并把新的当前版本写入本地配置旧版无版本号的跟踪 ID 依然通过存储的TRACKING_KEY回退路径解密。实操建议与限制# 常规轮换生成新版本密钥 重新部署 Worker 更新本地密钥环 gog gmail track key rotate # 仅本地测试只更新本地密钥不部署 Worker gog gmail track key rotate --no-deploy # 预览动作不落地 gog gmail track key rotate -n # 指定 Worker 目录默认 internal/tracking/worker gog gmail track key rotate --worker-dir /path/to/worker # JSON 输出便于脚本解析 gog gmail track key rotate -j使用要点依据 docs/email-tracking.md 与源码实现--no-deploy后的关键限制在 Worker 获得对应版本的TRACKING_KEY_VN之前不要发送新的受跟踪邮件否则新像素将无法被解密docs/email-tracking.md Rotate tracking keys 节明确告警轮换后无打开记录的排查确认 Worker 端存在当前版本对应的TRACKING_KEY_VN且TRACKING_CURRENT_KEY_VERSION与其一致401/403/opens查询通常是ADMIN_KEY不匹配需重新部署密钥并视情况重跑track setup密钥永不落明文文件轮换完成后SecretsInKeyringtrue、配置文件中TrackingKey置空密钥仅保存在系统密钥环这一点可结合 docs/email-tracking.md 的 setup 说明per-account tracking/admin keys are stored in your keychain/keyring (not in the JSON file)互相印证依赖wrangler在 PATH 中否则DeployWorker返回wrangler not found in PATH且 Worker 目录内须有wrangler.toml。验证与测试依据命令行为测试internal/cmd/gmail_track_cmd_test.go 覆盖track key rotate的执行路径与 dry-run 行为加解密单元测试internal/tracking/crypto_test.go 覆盖版本化/legacy 密文的加密-解密往返与错误分支部署流程测试internal/tracking/deploy_test.go密钥存储测试internal/tracking/secrets_test.go更多跟踪相关文档docs/email-tracking.md、docs/commands/gog-gmail-track.md、docs/commands/gog-gmail-track-key-rotate.md。小结gog gmail track key是 gogcli 邮件打开跟踪体系中的密钥管理入口其核心子命令rotate通过1 字节版本前缀密文 多版本密钥并存 密钥环存储 wrangler 原子部署四件套实现了跟踪加密密钥的平滑轮换新邮件使用新密钥加密历史 tracking ID 继续通过旧版本密钥或 legacyTRACKING_KEY回退路径解密而明文密钥始终只驻留在系统密钥环中。理解 internal/tracking/crypto.go 的解密优先级和 internal/tracking/deploy.go 的密钥下发顺序是安全操作--no-deploy等变体模式的前提。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/17 5:57:38 · 阅读 1.2k gogcli 邮件打开跟踪密钥管理：`gog gmail track key rotate` 轮换机制与源码级原理
gogcli 邮件打开跟踪密钥管理gog gmail track key rotate轮换机制与源码级原理【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcligogcligog为gog gmail send --track提供的邮件打开跟踪功能依赖一个加密跟踪像素tracking pixel像素 URL 中携带用 AES-GCM 加密的负载由自部署的 Cloudflare Worker 解密并记录打开事件。本文以命令参考gog gmail track key为主体完整覆盖其用法、子命令与全部可用 Flags并结合 internal/cmd/gmail_track_key.go、internal/tracking/crypto.go 等源码深入讲解密钥轮换key rotation的版本化设计、密钥环keyring存储与 Worker 端兼容性帮助你安全地轮换跟踪加密密钥而不使历史跟踪 ID 失效。命令定位gog gmail track key在邮件跟踪体系中的角色gog gmail (mail,email) track key的职责是管理跟踪加密密钥Manage tracking encryption keys它是gog gmail trackEmail open tracking命令族下唯一负责密钥生命周期管理的入口。完整命令族见 gog gmail track 参考页track key管理跟踪加密密钥本文主题track opens查询邮件打开记录track setup初始化跟踪部署 Cloudflare Workertrack status查看跟踪配置状态跟踪体系的加密链路可参考 docs/email-tracking.md 的架构描述发送带--track的邮件时CLI 端把PixelPayload收件人、主题哈希、发送时间戳用当前版跟踪密钥以 AES-GCM 加密编码为 URL-safe base64 后嵌入像素 URL收件人客户端加载图片时Cloudflare Worker 用TRACKING_KEY/TRACKING_KEY_VN密钥解密负载把打开事件写入 D1 数据库gog gmail track opens通过管理密钥ADMIN_KEY向 Worker 查询打开记录。正因为密钥同时存在于 CLI 本地配置/密钥环与 Worker 环境变量中密钥一旦泄露或怀疑暴露就需要一套换钥但不断链的轮换机制——这正是track key rotate解决的问题。用法与子命令基本用法gog gmail (mail,email) track key commandmail与email互为别名。该父命令本身不执行动作只提供密钥管理子命令子命令说明gog gmail track key rotate轮换跟踪加密密钥Rotate tracking encryption key全局 Flags 完整说明gog gmail track key继承 gogcli 的全局 Flags以下表格完整继承自命令参考页Flag类型默认值说明--access-tokenstring直接使用提供的 access token绕过已存储的 refresh tokentoken 有效期约 1 小时-a--account--acctstring账户邮箱、别名或 auto用于已认证的 Google API 命令--clientstringOAuth client 名称选择已存储的凭据 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 范围--results-onlyboolJSON 模式下只输出主结果丢弃 nextPageToken 等信封字段--select--pick--projectstringJSON 模式下选择逗号分隔的字段尽力而为支持点分路径。多数命令建议使用 --fields-v--verbosebool启用详细日志--versionkong.VersionFlag打印版本并退出--wrap-untrustedboolfalseJSON/raw 输出中将抓取到的文本字段包裹在外部不可信内容标记内命令索引见 docs/commands/README.md。track key rotate轮换命令详解用法与专属 Flagsgog gmail (mail,email) track key rotate [flags]rotate在继承全部全局 Flags 的基础上额外提供两个专属 FlagsFlag类型说明--no-deploybool只更新本地跟踪密钥不部署 Worker--worker-dirstringWorker 目录默认internal/tracking/worker前置条件从 internal/cmd/gmail_track_key.go 的实现看rotate执行前会做两层校验cfg.IsConfigured()必须为真即账户已完成gog gmail track setupEnabled、WorkerURL、TrackingKey齐备定义见 internal/tracking/config.go。否则报错tracking not configured; run gog gmail track setup first管理密钥ADMIN_KEY必须已配置。否则报错tracking admin key not configured; run gog gmail track setup again。轮换全流程源码视角Rotate.Run的完整执行链internal/cmd/gmail_track_key.goDry-run 拦截若传入-n/--dry-run仅打印预定动作account、worker_dir、deploy并成功退出加载现有密钥通过密钥环按已知版本列表加载全部版本密钥。若密钥环为空但配置文件里仍有明文TrackingKey旧版布局则将其视为版本 1 的密钥实现向后兼容生成新版本密钥nextTrackingKeyVersion取当前版本与所有已存版本中的最大值 1作为新版本号internal/cmd/gmail_track_key.go密钥本体由 internal/tracking/crypto.go 的GenerateKey()生成——使用crypto/rand读取 32 字节即256 位 AES 密钥以标准 base64 编码部署 Worker默认执行除非指定--no-deploy否则调用tracking.DeployWorkerinternal/tracking/deploy.go内部通过wrangler完成wrangler d1 create/info确保 D1 数据库存在--worker-dir默认指向仓库内的 internal/tracking/worker将全部版本密钥写入 Worker 环境变量当前版本写入TRACKING_KEY每个版本写入TRACKING_KEY_VN当前版本号写入TRACKING_CURRENT_KEY_VERSION管理密钥写入ADMIN_KEYinternal/tracking/deploy.gowrangler deploy发布 Worker。 注意 Worker 名称缺失时会提示重新执行gog gmail track setup数据库名默认与 Worker 名一致保存本地密钥把完整版本密钥集写入密钥环SecretStore.SaveTrackingKeys随后把本地配置标记为SecretsInKeyringtrue、清空配置文件中的明文TrackingKey、写入新的TrackingCurrentKeyVersion与TrackingKeyVersionsinternal/cmd/gmail_track_key.go。也就是说轮换完成后明文密钥只存在于系统密钥环keyring中JSON 配置文件不再保留输出结果普通模式TSVtracking_key_rotated true tracking_key_version N tracking_key_versions 1,2,... deployed true|falseJSON 模式-j输出account、databaseName、deployed、trackingKeyRotated、trackingKeyVersion、trackingKeyVersions、workerName字段便于脚本判断。密钥环中的存储布局internal/tracking/secrets.go 定义了按账户隔离的密钥命名规则scopedSecretKeyL230-L237tracking/account/tracking_key_vN—— 每个版本的跟踪密钥versionedTrackingKeySecretSuffixtracking/account/tracking_key—— 当前版本密钥的镜像供只读快速访问tracking/account/admin_key—— 管理密钥。读取时存在 legacy 回退若按版本读取失败会尝试旧格式键名tracking/tracking_keyinternal/tracking/secrets.go保证早期单密钥安装升级后仍可解密。版本合法性约束为1–255与密文中 1 字节版本前缀的取值范围一致internal/tracking/crypto.go。版本化密文设计为什么轮换后旧邮件仍可解密这是rotate能够不断链的核心实现在 internal/tracking/crypto.go加密EncryptWithVersionL36-L43在 nonce 之前追加 1 字节密钥版本号形成[version | nonce | ciphertexttag]结构再做 URL-safe base64无 padding编码。无版本号的EncryptL30-L32产生[nonce | ciphertexttag]的 legacy 结构解密DecryptWithKeysL88-L116接收版本号 → 密钥映射先按密文首字节识别版本并优先尝试该版本prioritizeVersionL201-L214失败后遍历其余版本最后以nonceOffset0再尝试一轮 legacy 无版本密文。任何一轮 AES-GCM 验证失败aead.Open返回错都会换下一把密钥重试密钥规范化NormalizeTrackingKeyVersionsinternal/tracking/config.go会把版本收敛到 1–255 范围内、排序并去重确保配置中不会残留非法版本。Worker 端TypeScript 实现与 Go 端算法严格对等internal/tracking/worker/src/crypto.ts 的decryptWithKeys同样按版本优先 → 全量重试 → legacy 回退的顺序用 Web Crypto AES-GCM12 字节 IV逐版本尝试解密因此 CLI 与 Worker 可独立持有不同版本的密钥子集而互相兼容。结合 docs/email-tracking.md 的说明轮换命令会生成下一个密钥版本部署所有活跃的TRACKING_KEY_VN密钥及TRACKING_CURRENT_KEY_VERSION并把新的当前版本写入本地配置旧版无版本号的跟踪 ID 依然通过存储的TRACKING_KEY回退路径解密。实操建议与限制# 常规轮换生成新版本密钥 重新部署 Worker 更新本地密钥环 gog gmail track key rotate # 仅本地测试只更新本地密钥不部署 Worker gog gmail track key rotate --no-deploy # 预览动作不落地 gog gmail track key rotate -n # 指定 Worker 目录默认 internal/tracking/worker gog gmail track key rotate --worker-dir /path/to/worker # JSON 输出便于脚本解析 gog gmail track key rotate -j使用要点依据 docs/email-tracking.md 与源码实现--no-deploy后的关键限制在 Worker 获得对应版本的TRACKING_KEY_VN之前不要发送新的受跟踪邮件否则新像素将无法被解密docs/email-tracking.md Rotate tracking keys 节明确告警轮换后无打开记录的排查确认 Worker 端存在当前版本对应的TRACKING_KEY_VN且TRACKING_CURRENT_KEY_VERSION与其一致401/403/opens查询通常是ADMIN_KEY不匹配需重新部署密钥并视情况重跑track setup密钥永不落明文文件轮换完成后SecretsInKeyringtrue、配置文件中TrackingKey置空密钥仅保存在系统密钥环这一点可结合 docs/email-tracking.md 的 setup 说明per-account tracking/admin keys are stored in your keychain/keyring (not in the JSON file)互相印证依赖wrangler在 PATH 中否则DeployWorker返回wrangler not found in PATH且 Worker 目录内须有wrangler.toml。验证与测试依据命令行为测试internal/cmd/gmail_track_cmd_test.go 覆盖track key rotate的执行路径与 dry-run 行为加解密单元测试internal/tracking/crypto_test.go 覆盖版本化/legacy 密文的加密-解密往返与错误分支部署流程测试internal/tracking/deploy_test.go密钥存储测试internal/tracking/secrets_test.go更多跟踪相关文档docs/email-tracking.md、docs/commands/gog-gmail-track.md、docs/commands/gog-gmail-track-key-rotate.md。小结gog gmail track key是 gogcli 邮件打开跟踪体系中的密钥管理入口其核心子命令rotate通过1 字节版本前缀密文 多版本密钥并存 密钥环存储 wrangler 原子部署四件套实现了跟踪加密密钥的平滑轮换新邮件使用新密钥加密历史 tracking ID 继续通过旧版本密钥或 legacyTRACKING_KEY回退路径解密而明文密钥始终只驻留在系统密钥环中。理解 internal/tracking/crypto.go 的解密优先级和 internal/tracking/deploy.go 的密钥下发顺序是安全操作--no-deploy等变体模式的前提。【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考