企业官网建设流程全解析

gogcligog auth add完全指南：在终端授权 Google 账户并安全存储刷新令牌

【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli

gog auth add是 gogcli（Google Workspace in your terminal）中负责 OAuth 授权的核心命令：它引导用户在浏览器中完成 Google 账户或 Google Workspace 账户授权，获取并安全存储刷新令牌（refresh token），为后续所有 Gmail、Drive、Calendar、Sheets 等命令调用提供身份基础。读完本篇，你将掌握该命令的完整参数体系、浏览器/无浏览器两种授权流程、服务与 scope 的精细控制，以及授权后身份校验与令牌存储的底层实现原理。

命令定位与基础用法

gog auth add属于 gog auth 子命令族，职责是“授权一个 Google Account 或 Google Workspace 账户并存储刷新令牌”。该文档由gog schema --json自动生成，执行make docs-commands可重新生成。

基础用法：

gog auth add <email> [flags]

其中<email>是必需的位置参数。源码中它被定义为AuthAddCmd的Email字段（internal/cmd/auth_add.go），其帮助文本明确指出：必须是 Google Account 或 Google Workspace 邮箱，普通非 Google 邮箱无法完成授权。

执行时会先输出一条提示（googleAccountAuthorizationHint）：若同意授权失败，应显式指定--services重试，并在重新授权时保留已有服务。

快速上手：标准浏览器授权流程

在配置好 OAuth 客户端凭证后（参见 gog auth credentials 与 gog auth setup），最简单的一次授权只需：

gog auth add you@example.com

默认行为（源码Run方法流程，见 internal/cmd/auth_add.go）：

1. 解析账户对应的 OAuth 客户端（authclient.ResolveClientWithOverride）；
2. 解析--services，默认加载全部默认用户服务（user预设）；
3. 计算 OAuth scope 列表（googleauth.ScopesForManageWithOptions，internal/googleauth/service.go）；
4. 启动本地回调监听，打开浏览器完成授权；
5. 用刷新令牌回调用户信息（fetchAuthIdentity），校验授权邮箱与命令行传入邮箱一致；
6. 将令牌写入密钥库/加密存储（secrets.Store.SetToken）。

授权成功后输出账户邮箱、已授权服务与客户端名。测试 internal/cmd/auth_add_test.go 中的TestAuthAddCmd_EmailMismatch验证了邮箱不匹配时命令直接报错拒绝存储。

Flags 完整参考

以下表格完整继承自官方命令文档（docs/commands/gog-auth-add.md），其中--access-token等全局 Flags 用于所有 gogcli 命令，而--manual、--remote、--services、--drive-scope、--gmail-scope等为授权流程专属参数：

无浏览器场景：manual 与 remote 两步流程

对于无图形界面的服务器或 SSH 环境，gog auth add提供两种无浏览器授权方式，相关标志定义与校验逻辑见 internal/cmd/auth_add.go。

--manual：粘贴回调 URL

gog auth add you@example.com --manual

命令打印授权 URL，你在任何有浏览器的设备上打开并完成授权，再把浏览器重定向地址复制粘贴回终端。--redirect-uri可覆盖默认回调地址，--timeout可调整等待时间（未指定时手动流程默认 5 分钟）。

--remote --step：远程服务器两段式

适合自动化脚本，分两次执行：

# 第一步：打印授权 URL（不启动回调监听） gog auth add you@example.com --remote --step 1 # 第二步：带上浏览器重定向 URL 交换 code gog auth add you@example.com --remote --step 2 --auth-url '<redirect-url>'

第一步还会输出state_reused提示，并回显第二步需要复用的完整命令（formatRemoteStep2Instruction会把--redirect-host、--redirect-uri、--services、--readonly、--drive-scope、--gmail-scope、--extra-scopes、--force-consent等参数一并拼进提示）。第二步要求--auth-url必填，并且强制进行 state 校验（源码中--auth-code与--remote互斥，见 internal/cmd/auth_add.go）；--step只允许 1 或 2，且必须与--remote同时使用。

--redirect-host与--redirect-uri互斥（resolvedRedirectURI）：前者拼接为https://{host}/oauth2/callback，后者直接覆盖整个 URI。

服务范围与 scope 精细控制

--services选择授权服务

默认值user覆盖全部默认用户 OAuth 服务；也可以按需精确挑选，例如：

gog auth add you@example.com --services gmail,calendar,drive,docs,sheets

要点（源码 parseAuthServices 与测试 auth_add_test.go 中的TestAuthServicesAdSenseExplicitOptIn、TestAuthAddCmd_KeepRejected）：

• 支持user/all-user/all预设，以及逗号分隔的服务名列表；
• adsense、photospicker必须显式列名 opt-in；
• admin、groups、keep仅适用于 Workspace 服务账号，走gog auth service-account set <email> --key <service-account.json>路线，直接传给auth add会返回 usage 错误；
• 重复项自动去重；未选服务时报 “no services selected”。

--drive-scope与--gmail-scope

• --drive-scope：full（默认）/readonly/file；
• --gmail-scope：full（默认）/readonly/send/read-send。

authScopeModes（internal/cmd/auth_add.go）负责组合校验：任何非 full 的 Gmail 模式或 readonly/file 的 Drive 模式都会关闭增量授权（DisableIncludeGrantedScopes），从而在再次授权时重新请求完整 scope 清单。相关测试覆盖了 Gmail 发送类 scope 与 readonly 的冲突（TestAuthAddCmd_ReadonlyRejectsGmailSendingScopes）。

--readonly只读授权

--readonly会同时做两件事：运行时拦截变更类 API 请求，且本次auth add只申请只读 OAuth scope。注意它不能与--drive-scope=file（file 具备写能力）或--gmail-scope=send/read-send组合，组合时报 usage 错误（见authScopeModes与测试TestAuthAddCmd_ReadonlyWithDriveScopeFileRejected）。

--extra-scopes与--force-consent

• --extra-scopes：以逗号分隔追加自定义 scope URI，追加在所有服务 scope 之后（parseExtraScopesCSV会做 trim 与去空处理）；
• --force-consent：强制显示同意页，确保 Google 返回刷新令牌（对已授权过的账户很有用，可强制刷新授权状态）。

源码级原理：身份校验、令牌存储与邮箱迁移

授权成功后的处理链（internal/cmd/auth_add.go）值得关注：

1. 身份校验：用刷新令牌回调用户信息（fetchAuthIdentity，超时 15 秒），将返回的授权邮箱与命令行传入邮箱做规范化比较（normalizeEmail统一小写去空格）。不一致则报错authorized as X, expected Y，避免“授权了错误账户还写入存储”。
2. 令牌存储：openAuthSecretsStore打开密钥库（keyring/加密文件，--readonly之外的变更类操作前还会先ensureKeychainAccessIfNeeded验证密钥库可访问），随后store.SetToken写入Client / Subject / Email / Services / Scopes / RefreshToken。存储失败时报OAuth completed, but saving the refresh token failed: ...，明确区分“授权成功但保存失败”。
3. 邮箱迁移：若FindStoredSubjectIdentityEmail发现旧账户（例如大小写或别名变化），会自动把旧邮箱引用迁移到新邮箱并删除过期别名，输出Migrated auth account from A to B（测试TestExecuteAuthAddMigratesRuntimeEmailReferences覆盖）。

该命令支持--dry-run：在任何 OAuth 网络操作前打印计划动作并退出（dryRunExit），测试TestAuthAddCmd_DryRunSkipsOAuthForEveryFlow验证了 dry-run 对所有流程都不会发起真实 OAuth。

输出格式与脚本化

配合全局 Flags 可安全地接入脚本：

• -j/--json/--machine：输出{stored, email, services, client}结构；
• -p/--plain/--tsv：输出email<TAB>...、services<TAB>...、client<TAB>...的 TSV 行，无颜色，便于 grep/awk；
• --no-input/--non-interactive：CI 环境下不进入交互提示，直接失败。

授权后的账户管理链路

gog auth add只是整个认证体系的入口，后续管理请配合：

• gog auth list：列出已存储账户；
• gog auth status：查看认证配置与密钥库后端；
• gog auth import：非交互式导入刷新令牌（如从环境变量/文件/stdin 读取），适合无法打开浏览器的机器；
• gog auth remove / gog auth tokens：移除或管理刷新令牌；
• gog auth doctor：诊断 auth、密钥库与刷新令牌问题；
• gog auth service-account：Workspace 域范围委托（admin/groups/keep 服务需要）。

完整命令索引见 Command index。合理使用--dry-run先预览授权计划、用--services最小化权限、必要时叠加--readonly与--gmail-no-send，即可在保证安全的前提下完成 gogcli 的全部终端自动化场景。

【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli