企业官网建设流程全解析

gogcli Drive 审计命令实战：用gog drive tree/du/inventory/audit做只读的清理规划与权限排查

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

本指南围绕 gogcli 的 Drive 审计（Drive Audits）命令集展开，介绍如何在不修改任何文件的前提下，用gog drive tree、gog drive du、gog drive inventory、gog drive audit sharing/user等只读命令完成文件夹结构盘点、容量汇总、库存导出与权限风险排查。读完本文，你将掌握这些命令的参数用法、JSON 输出约定、失败语义与批量操作的安全边界，可直接用于清理规划、迁移审查和需要稳定 JSON 的自动化场景。

Drive 审计命令是什么

gogcli 的 Drive 审计命令是一组只读的报告型工具，定位是清理规划（cleanup planning）、迁移审查（migration review）以及需要稳定 JSON 输出、但不回写 Drive 的自动化任务。与gog drive bulk这类批量变更命令不同，审计命令本身不做任何写入，核心包括 8 个命令：

适用场景判断：当你只是想"看"文件夹内容、体积或库存，而不改动文件时，就走这套命令；当需要批量改权限、批量移除公开共享时，应切换到gog drive bulk系列并配合--dry-run（详见下文）。

输出约定：人看表格，机器看 JSON

所有审计命令都支持统一的输出控制，最常用的两个标志是：

• -j/--json/--machine：向 stdout 输出 JSON，最适合脚本消费；
• -p/--plain/--tsv：输出稳定、可解析的纯文本（TSV，无颜色）。

其余通用标志还包括--color auto|always|never、--max、--depth、--parent、--all-drives（默认true，可配合--no-all-drives）、--results-only（JSON 模式下只输出主结果、丢弃nextPageToken等信封字段）以及--select（JSON 模式下按逗号分隔选取字段，最佳实践是用--fields）。这些标志的完整定义可以在对应命令页（如 gog-drive-tree）中查看。

在源码层，命令统一通过outfmt.IsJSON(ctx)判断输出格式、用outfmt.WriteJSON写出 JSON，非 JSON 时走outfmt.WriteTable（见 internal/cmd/drive_reporting.go），因此同一套标志在 tree、du、inventory、audit 上的行为一致。

文件夹树：gog drive tree

打印可读的文件夹树：

gog drive tree --parent <folderId> --depth 2

当结果需要交给其他工具消费时，改用 JSON：

gog drive tree --parent <folderId> --depth 3 --json

关键参数：

• --parent：起始文件夹 ID，缺省为 root；
• --depth：最大深度，0表示不限制，默认值为 2；
• --max：返回的最大条目数，0表示不限制，默认值为 0（即不截断）。

tree的 JSON 输出包含items与truncated两个字段：当扫描因--max被截断时，truncated为true，并且非 JSON 模式会向 stderr 提示 "Results truncated; increase --max to see more."。从源码看，tree请求的字段集为driveTreeFields（id,name,mimeType,size,modifiedTime,shortcutDetails(...)），每行输出一个"placement"（见下文"多父目录与 placement"），并附带path与depth信息（internal/cmd/drive_reporting.go 中的driveTreeItem结构）。

大小汇总：gog drive du

汇总文件夹体积：

gog drive du --parent <folderId> --max 20 gog drive du --parent <folderId> --depth 2 --sort size --json

du的关键参数与默认值：

• --depth：文件夹汇总的深度，默认 1；
• --max：最多返回的文件夹数，默认 50（0为不限）；
• --sort：按size、path或files排序，默认size；
• --order：asc/desc，默认desc。

多父目录与 placement 语义

drive tree和drive inventory对每个发现的 placement 输出一行——所谓 placement，是指"文件在某条路径上的一个出现位置"。因此，通过多个父目录都能到达的历史遗留条目，会在每条路径下各自保留一次。而drive du会把这些 placement 独立聚合成文件夹汇总，再按size、path或files排序。这套逻辑对应 internal/drivereport 包中的traverse.go（placement 遍历）与summary.go（聚合汇总），du命令本身在 internal/cmd/drive_reporting.go 的DriveDuCmd中实现：先调用listDrivePlacements全量扫描（不设深度/条目上限），若意外截断会直接返回 "drive du truncated unexpectedly" 错误，保证汇总结果完整。

快捷方式（Shortcut）如何处理

快捷方式会被计为"内容字节为零的文件 placement"，扫描过程不会跟随 shortcut 指向的目标去递归。也就是说，du的容量统计只反映真实文件所占空间，避免因 shortcut 造成重复或虚高的体积。

库存导出：gog drive inventory

导出只读的条目清单：

gog drive inventory --parent <folderId> --json gog drive inventory --parent <folderId> --max 0 --depth 0 --json > drive-inventory.json

当需要一份"机器可读的 Drive 对象列表"用于审查、diff 或下游清理脚本时，使用 inventory 输出。它的关键参数：

• --depth：默认 0（即默认全深度扫描）；
• --max：最大条目数，默认 500；
• --sort：按path、size或modified排序，默认path；
• --order：默认asc。

相比 tree，inventory 额外请求了owners(emailAddress,displayName)字段（见 internal/cmd/drive_reporting.go 的driveInventoryFields），因此每条记录会带出属主邮箱/显示名，便于后续按属主归类做清理或迁移评估。把--max 0 --depth 0组合即可一次性导出完整清单重定向到文件。

修订历史：gog drive revisions

先列出某文件的修订元数据，再查看某一条修订：

gog drive revisions list <fileId> --all --json gog drive revisions get <fileId> <revisionId> --json

Drive API 会暴露修订 ID、时间戳、keep-forever（永久保留）状态，以及可用的 provider 导出链接。需要特别注意的是：对于 Google 原生文档（Docs/Sheets/Slides 等 Docs Editors 文件），API 并不暴露完整的编辑历史或历史文档正文，所以这里只能拿到修订元数据，无法拿回历史版本内容。revisions list的默认--max为 200，可通过--all（拉取全部分页）或--max/--limit控制；--fail-empty可在没有任何修订时以退出码 3 结束，便于脚本判断。相关命令页：gog-drive-revisions、gog-drive-revisions-list、gog-drive-revisions-get。

权限审计：gog drive audit sharing与gog drive audit user

找出公开或外部共享

gog drive audit sharing --parent <folderId> --internal-domain example.com --json gog drive audit sharing --parent <folderId> --public-only --fail-found

audit sharing（别名permissions、perms、public、external）扫描指定文件夹树，对每个条目拉取权限列表并判定是否存在风险共享。关键参数：

• --internal-domain：视为内部的域名，可重复传多次；不指定时默认取当前账号邮箱的域名；
• --public-only：只报告 anyone-with-link / 公开权限；
• --external-only：只报告外部用户/组/域权限；
• --file / --file-id：只审计单个文件 ID，而不是整个文件夹树；
• --fail-found：存在发现项时以退出码 3结束（便于 CI 判定）；
• --max：最多扫描的文件/文件夹数，默认 500；--depth：最大文件夹深度，默认 2。

注意：--public-only与--external-only不能同时使用（源码会直接返回 usage 错误，见 internal/cmd/drive_audit.go）。一条发现项（finding）会带出path、mimeType、ownerEmails、permissionId、permissionType、role、email、domain、allowFileDiscovery、deleted、expirationTime、reasons与inherited等字段，其中reasons标明命中原因是public还是external，inherited/permissionDetails则记录了权限是否从父级继承而来。

判定逻辑（internal/cmd/drive_audit.go 中的driveSharingFinding/isExternalDrivePermission）：type=anyone判为 public；type=user或group时比较邮箱域名、type=domain时比较域，若不在--internal-domain名单内则判为 external。内部域名单会做小写化与去首尾点号归一化（normalizeDomain），并以sortedKeys的形式回显在 JSON 输出的internalDomains字段中。

找出共享给特定用户的文件

gog drive audit user clawdbot@gmail.com --parent <folderId> --json

audit user <user>接收一个用户邮箱作为位置参数，扫描文件夹树后找出所有授予该用户权限的条目。与 sharing 相同，也支持--file/--file-id、--parent、--depth、--max、--all-drives、--fail-found。两条 audit 命令的 JSON 输出都包含findings、findingCount、scannedFileCount、truncated（以及 sharing 的internalDomains），便于脚本统计覆盖率。

批量权限操作与审计的边界

批量权限操作被刻意与审计命令分开，且必须经过 dry-run 或确认才能执行：

gog drive bulk remove-public --parent <folderId> --dry-run gog drive bulk update-role --parent <folderId> --from writer --to reader --target contractor@example.com --dry-run

也就是说：审计负责"发现问题"，bulk 负责"解决问题"，二者职责分离，防止误操作。

失败语义：分页必须完整，绝不输出部分成功

审计命令在安全方面有几个刻意设计的行为，值得在自动化时重点理解：

• 权限分页必须全部完成：对扫描范围内的每个文件，权限列表的分页都要走完。API 调用失败、出现重复的 page token、或遇到页数限制错误时，整个命令会失败并拒绝输出部分审计结果——绝不给出"半份"的审计报告，避免下游依据残缺数据做决策。
• 批量操作先完成权限扫描再写入：gog drive bulk系列在执行任何变更之前，会先完成上述完整的权限扫描。因此，如果列表/扫描阶段失败，写入会被阻止（"a listing failure prevents writes"）；但需要明确：这并不能回滚后续写入阶段本身发生的失败。计划类操作请始终先跑--dry-run验证扫描能完整通过。
• 重复 page token 防护：文件夹列表遍历同样拒绝重复的 page token。从源码看，listDriveChildren每次翻页前都会调用pageTokenGuard检查（internal/cmd/drive_reporting.go），一旦发现 token 被重复使用即报错终止，防止死循环或脏数据。这些报告在产出输出之前就会拒绝这类异常 token；而成功完成的扫描会保留其既有的 size 与 depth 上限语义。
• 退出码约定：--fail-found（审计有发现项时）与--fail-empty（revisions 无结果时）均使用退出码 3表达"有结论/无结论"的脚本可判定状态。

共享盘（Shared Drives）控制

审计命令在底层 Drive API 支持的情况下，默认包含共享盘。如果需要把扫描范围限制在"我的云端硬盘"（My Drive），传入--no-all-drives：

gog drive inventory --parent root --no-all-drives --json

--all-drives在所有审计类命令上默认值为true且可否定（negatable），对应源码中AllDrives bool ... default:"true" negatable:"_"的定义（internal/cmd/drive_reporting.go 与 internal/cmd/drive_audit.go）。底层请求会带上supportsAllDrives语义以正确遍历共享盘。

对象级检查：--fields与原始对象

当需要对单个对象做精细检查时，用gog drive get配合--fields精确选取需要的字段：

gog drive get <fileId> --fields 'id,name,mimeType,size,owners,emailAddress' --json

如果连字段裁剪都不需要、要拿 Drive API 的原始对象，则用gog drive raw。raw输出的敏感字段处理行为（脱敏/标记等）详见文档 Raw API Dumps。drive get与drive raw构成审计链路的最后两块拼图：前者适合快速字段探查，后者适合需要完整原始结构的调试与取证。

实战组合建议

把上述命令串成一条典型的只读审计流水线：

# 1) 先出完整库存清单 gog drive inventory --parent <folderId> --max 0 --depth 0 --json > drive-inventory.json # 2) 再按体积看哪里最占空间 gog drive du --parent <folderId> --depth 2 --sort size --max 20 --json # 3) 排查公开共享风险（CI 里可用 --fail-found 触发告警） gog drive audit sharing --parent <folderId> --public-only --fail-found --json # 4) 确认某个外部协作者拿到的权限范围 gog drive audit user contractor@example.com --parent <folderId> --json # 5) 确认无误后再进入 bulk 阶段，且先 dry-run gog drive bulk remove-public --parent <folderId> --dry-run

整套链路只读、可脚本化、可判定（退出码 3），既适合人工清理规划，也适合定时任务做持续的安全巡检。所有命令的完整标志表可在 docs/commands 目录下对应命令页中查阅，实现细节可进一步阅读 internal/cmd/drive_reporting.go、internal/cmd/drive_audit.go 与 internal/drivereport 包。

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