gog 管理命令指南用 gog admin 安全运维 Google Workspace 域资源【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本篇技术指南聚焦 gog CLI 的gog admin命令族讲解如何基于 Admin SDK Directory API 管理 Google Workspace 域内的用户users、群组groups与组织架构单元orgunits。读完本文你将掌握 admin 命令的完整调用方式、域级委派前置条件、安全执行纪律--readonly/--dry-run/--no-input以及面向 Agent 与脚本的 JSON 契约用法能够把用户批量查询、群组成员维护、组织单元创建等日常运维工作直接搬进终端与自动化流水线。gog admin目录管理能力的命令骨架在 gog 中admin是管理 Google Workspace 目录数据的命令族对应 Admin SDK Directory API。其命令结构定义在 internal/cmd/admin.gotype AdminCmd struct { Users AdminUsersCmd cmd: name:users help:Manage Workspace users Groups AdminGroupsCmd cmd: name:groups help:Manage Workspace groups Orgunits AdminOrgunitsCmd cmd: name:orgunits aliases:org-units,ou help:Manage Workspace organizational units }从源码结构可以推断出三点关键信息admin下只挂载了三个一级子命令users、groups、orgunits分别管理用户、群组和组织单元orgunits提供了org-units与ou两个别名便于快速输入这一层不包含“删除域”“迁移数据”等更重的管理操作——它是聚焦目录读写的轻量管理面与 gog 其他服务命令gmail、drive、calendar 等共用同一套认证、输出与安全机制。官方生成的命令参考见 docs/commands/gog-admin.md其中gog admin command --help与gog schema admin command --json分别提供人类可读的帮助和机器可读的契约避免凭记忆猜测参数。前置条件域级委派与 Workspace 账号gog admin与普通 Gmail/Drive 命令最大的不同在于认证模型。它依赖 Admin SDK Directory API而该 API 通常要求一个Google Workspace账号而非个人gmail.com消费者账号服务账号已开启域级委派domain-wide delegation。这一限制直接体现在源码 internal/cmd/admin_common.go 的requireAdminAccount函数中它先校验账号存在再调用isConsumerAccount拒绝gmail.com/googlemail.com等消费者账号否则返回“Admin SDK Directory API requires a Google Workspace account with domain-wide delegation”的用户可见错误。此外internal/cmd/admin.go 的注释也写明AdminCmd需要“domain-wide delegation with a service account”。结合 .agents/skills/gog/SKILL.md 中“Service accounts are Workspace-only and mainly fit Admin, Groups, Keep, and domain-wide delegation flows”的说明可以确认 admin 命令属于企业域管理场景不适合个人 Gmail 账号。实操要求在 Workspace 管理控制台为服务账号开启域级委派并在 Google Cloud Console 的命令文档。安全启动先检查再操作管理命令的破坏力远高于普通读写命令因此 .agents/skills/gog-admin/SKILL.md 在“Safe start”一节给出了三条前置检查命令gog auth list --check --json --no-input gog schema admin --json gog --readonly --account userexample.com admin --help这三步的含义分别是检查认证状态gog auth list --check --json --no-input确认目标账号已认证、token 未过期、scope 覆盖完整。--no-input保证在无人值守环境下认证失败会直接报错而不是挂起等待输入拉取机器可读契约gog schema admin --json输出 admin 命令族的语法、退出码与安全状态供 Agent 或脚本解析只读探测命令结构gog --readonly ... admin --help以只读模式查看帮助确认参数后再真正执行。SKILL.md 同时给出了四条铁律贯穿所有 admin 操作显式指定账号用--account明确选择操作对象避免默认账号造成误操作Agent 可读输出读取 Google 内容时使用--json --wrap-untrusted将远程获取的文本字段用不可信内容标记包裹默认只读任务不涉及变更 Google 数据时一律加--readonly只在用户明确批准的具体写入上移除先预览后落地自动化场景使用--no-input支持的写入操作先--dry-run任何删除前必须确认账号、对象与变更内容。这些安全规则与 .agents/skills/gog/SKILL.md 的全局约定一致破坏性命令需要--force除非用户明确要求该精确变更否则不得自行追加。管理群组gog admin groups群组管理由AdminGroupsCmd承载internal/cmd/admin_groups.go包含list与members两个子命令而members下又细分list、add、remove命令用途gog admin groups list列出指定域的群组gog admin groups members list列出群组成员gog admin groups members add向群组添加成员gog admin groups members remove从群组移除成员列出域内群组gog --readonly --account userexample.com admin groups list --domain example.com --json关键参数对应源码 internal/cmd/admin_groups.go--domain必填指定要列举的域如example.com--max别名--limit每页最大结果数默认100--page别名--cursor分页游标--all别名--all-pages自动拉取全部分页--fail-empty无结果时以退出码 3 结束适合在 CI 中断言“必须存在结果”。列表的 JSON 输出为{groups: [{email,name,description,directMembersCount}], nextPageToken: ...}其中directMembersCount是群组的直接成员数。群组成员管理# 列出成员 gog --readonly --account userexample.com admin groups members list engineeringexample.com --json # 添加成员角色MEMBER / MANAGER / OWNER gog --account userexample.com admin groups members add engineeringexample.com devexample.com --role MEMBER --dry-run # 移除成员破坏性操作需要确认或 --force gog --account userexample.com admin groups members remove engineeringexample.com devexample.com --force实现细节印证internal/cmd/admin_groups.go--role默认MEMBER只接受MEMBER、MANAGER、OWNER三个枚举值大小写会被归一化源码第 220-223 行校验add会先做validatePlainEmail邮箱格式校验再进入dryRunExit的 dry-run 检查点源码第 230-235 行随后调用Members.Insertremove是破坏性命令必须经过dryRunAndConfirmDestructive源码第 275-280 行先走 dry-run再要求确认或显式--force最后才执行Members.Delete角色常量定义在 internal/cmd/admin_common.goMEMBER、OWNER、MANAGER。管理组织架构单元gog admin orgunits组织单元Org Unit命令定义在 internal/cmd/admin_orgunits.go提供完整的 CRUDlist、get、create、update、delete。# 列出根目录下的一级子单元 gog --readonly --account userexample.com admin orgunits list --parent / --type children --json # 查看指定单元详情 gog --readonly --account userexample.com admin orgunits get /Sales # 创建组织单元父路径默认为 / gog --account userexample.com admin orgunits create Sales --parent / --description Sales team --dry-run # 删除组织单元破坏性操作 gog --account userexample.com admin orgunits delete /Sales --force关键参数与实现细节list的--parent默认/--type取值all、children、allIncludingParent默认children源码第 21-24 行所有 orgunit 请求固定使用客户 IDmy_customerinternal/cmd/admin_common.go 的adminCustomerID常量即“当前客户”语义get对路径做了normalizeAdminOrgUnitPath归一化保证/前缀一致源码第 73-81 行非 JSON 模式下get以 key-value 文本输出 Name / Path / ID / Parent Path / Parent ID / Description 六项字段源码第 97-107 行。注意 orgunit 命令族依赖的是独立的adminOrgUnitDirectoryService与wrapAdminOrgUnitDirectoryErrorinternal/cmd/admin_common.go其错误提示会单独列出admin.directory.orgunitscope——这意味着组织单元接口与用户/群组接口在 scope 层面是分开授予的。管理用户gog admin users用户管理命令定义在 internal/cmd/admin_users.go包含list、get、create、delete、suspend五个子命令。# 列出域内用户 gog --readonly --account userexample.com admin users list --domain example.com --max 50 --json # 查看单个用户详情 gog --readonly --account userexample.com admin users get aliceexample.com --json # 创建用户可用 --dry-run 先预览 gog --account userexample.com admin users create aliceexample.com Alice Chen --dry-run # 暂停用户账号 gog --account userexample.com admin users suspend aliceexample.com --force # 删除用户永久性操作务必确认 gog --account userexample.com admin users delete aliceexample.com --force值得注意的实现细节list的 JSON 输出为{users: [{email,name,suspended,admin}], nextPageToken: ...}其中suspended标记账号是否被暂停、admin标记是否管理员源码第 73-95 行非常适合脚本做账号健康扫描用户创建涉及密码策略。密码生成逻辑在 internal/cmd/admin_common.go 的generateAdminUserPassword中实现强制长度不少于 8 位并保证小写、大写、数字、特殊字符四类字符各至少出现一个再使用crypto/rand做 Fisher-Yates 洗牌——也就是说 gog 生成的临时密码满足 Google 的基础复杂度要求--hash-function参数接受MD5、SHA-1、crypt归一化逻辑见 internal/cmd/admin_common.go用于导入既有密码哈希而非明文密码更多用户子命令参数可参考 gog-admin-users-create.md、gog-admin-users-suspend.md 等命令文档。面向 Agent 与脚本的输出与契约SKILL.md 的核心原则之一是“不要猜测命令语法”。对应到自动化场景有三条实践路径运行时探查gog admin command --help查看任意子命令的参数gog schema admin command --json获取其机器可读契约JSON 输出所有 admin 读取命令均支持--json列表类命令输出items nextPageToken的包络结构--results-only可去掉包络字段只保留主结果--select/--fields用于字段投影不可信内容防护读取 Google 返回的文本内容时加--wrap-untrusted在 JSON/raw 输出中为外部文本字段打上不可信标记防止 Agent 将远程内容误当作本地指令执行。命令级安全护栏同样作用于 admin 命令族与 .agents/skills/gog/SKILL.md 全局规则一致# 只允许指定命令、显式禁用破坏性命令 gog --enable-commands admin.users.list,admin.groups.list --disable-commands admin.users.delete \ --account userexample.com admin users list --domain example.com --json常见错误与排障Admin SDK 的错误映射集中实现在wrapAdminDirectoryErrorWithScopesinternal/cmd/admin_common.go常见错误提示与含义触发条件提示信息处理建议accessNotConfigured/ “Admin SDK API has not been used”Admin SDK API 未启用在 Cloud Console 的 Admin SDK API 页面启用该 APIinsufficientPermissions/insufficient authentication scopes/Not Authorized权限或 scope 不足确认服务账号开启域级委派并授予admin.directory.user、admin.directory.group、admin.directory.group.memberscopedomain_wide_delegation/invalid_grant域级委派未配置或无效到 Workspace 管理控制台确认服务账号的域级委派配置消费者账号gmail.com/googlemail.com不支持消费者账号使用 Workspace 账号并配置域级委派从源码结构可以看出admin错误包装区分了两类 scope用户/群组接口提示三个 scopeuser、group、group.member组织单元接口单独提示admin.directory.orgunit——排障时先确认错误来自哪类接口再对照授权。总结gog admin为 Workspace 域管理员提供了三条终端化的运维通道users用户生命周期、groups群组与成员、orgunits组织架构。其核心价值有三层一是以 Admin SDK Directory API 为后端能力边界清晰可查--help/schema --json二是全程贯彻安全纪律--readonly、--dry-run、--no-input、破坏性命令确认机制让高风险操作可控可审计三是输出面向机器JSON 契约 分页游标 稳定退出码使其天然适配 Agent 与 CI 流水线。需要更深入的资料时可以继续阅读仓库内的以下内容管理命令生成文档docs/commands/gog-admin.md含全部全局 flag 说明子命令细节如 gog-admin-groups.md、gog-admin-orgunits.md、gog-admin-users.mdAgent 技能约定.agents/skills/gog-admin/SKILL.md 与 .agents/skills/gog/SKILL.md安全执行总纲docs/safety-profiles.mdreadonly / agent-safe 预编译二进制的说明认证与密钥gog auth相关命令文档如 gog-auth-service-account-set.md以及源码目录 internal/googleauth、internal/secrets【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考