shuangyan-notebook/第五域 · Fifth Domain/⚒️ 铸渊·协作指令｜GitHub ↔ Notion 桥接协议/🔑 铸渊指令｜Google Drive OAuth2 代理人重构 · Service Account ea304b59af9f473fbadfe1df1faee61e.md

belongs_to

belongs_to
INDEX · 铸渊·协作指令｜GitHub ↔ Notion 桥接协议

🔑 铸渊指令｜Google Drive OAuth2 代理人重构 · Service Account→OAuth2 全量替换 + 天眼全局扫描验收（ZY-OAUTH2-REBUILD-2026-0324-001）

---

🚨

指令编号：ZY-OAUTH2-REBUILD-2026-0324-001

签发人： 霜砚（ICE-NTN-SY001）· 代 TCS-0002∞ 冰朔 签发

签发时间： 2026-03-24T14:45+08:00

优先级： 🔴 P0 · 存储链路合龙 · 阻塞性修复

前置指令： 🪞 铸渊指令｜Google Drive 镜像桥接层 · Gemini↔格点库实时同步（ZY-DRIVE-BRIDGE-2026-0323-001）

关联仓库： https://github.com/qinfendebingshuo/guanghulab

版权锚点： 国作登字-2026-A-00037559 · TCS-0002∞ 冰朔

---

🎯 指令背景

核心矛盾

此前 Google Drive 镜像桥接层（ZY-DRIVE-BRIDGE-2026-0323-001）设计采用 Service Account（机器人模式） 连接 Google Drive。经实测发现：

❌

Service Account 的 Google Drive 配额为 0GB。

即便主控冰朔已开通 Google One Pro 会员（2TB），由于「所有权冲突」——机器人账号与人类账号是隔离的命名空间——Service Account 无法向主控的 Drive 空间写入任何文件。

错误码：403: Storage Quota Exceeded

结论：Service Account 方案已死。现有 .json 密钥已废弃。

解决方案

主控已完成 OAuth 2.0 代理人授权，即：让铸渊以「主控冰朔的代理人」身份直接操作 2TB 空间。

✅

以下凭据已全部就绪，已注入 GitHub Secrets：

• GDRIVE_CLIENT_ID — OAuth 2.0 客户端 ID ✅
• GDRIVE_CLIENT_SECRET — OAuth 2.0 客户端密钥 ✅
• GDRIVE_REFRESH_TOKEN — 长效通行令牌（Refresh Token） ✅

Google Cloud 项目： guanghu-drive-bridge

OAuth 权限范围： https://www.googleapis.com/auth/drive

主控 Gmail 已列入测试用户白名单 ✅

---

📋 铸渊执行任务清单

Phase 1 · 清理旧 Service Account 残留

1. 删除旧 Secret：如果仓库中仍有 GOOGLE_DRIVE_SERVICE_ACCOUNT 或 GOOGLE_SERVICE_ACCOUNT_KEY 等旧 Secret，标记废弃（不要直接删，先注释掉引用）
2. 搜索全仓库：grep -r "service_account" .github/ scripts/ —— 找出所有引用 Service Account 的代码
3. 列出清单：把所有需要修改的文件路径列出来，作为 Phase 2 的输入

Phase 2 · OAuth2 代理人逻辑全量替换

核心变更：所有 Google Drive API 调用从 Service Account 认证切换到 OAuth2 认证。

2.1 认证模块重写

创建或重写 scripts/grid-db/drive-auth.js（统一认证入口）：

/**
 * drive-auth.js
 * 
 * OAuth2 认证模块 · 替代原 Service Account 模式
 * 
 * 环境变量：
 *   GDRIVE_CLIENT_ID      — OAuth 客户端 ID
 *   GDRIVE_CLIENT_SECRET   — OAuth 客户端密钥
 *   GDRIVE_REFRESH_TOKEN   — 长效刷新令牌
 * 
 * 返回已认证的 google.drive 客户端实例
 */

const { google } = require('googleapis');

function getDriveClient() {
  const oauth2Client = new google.auth.OAuth2(
    process.env.GDRIVE_CLIENT_ID,
    process.env.GDRIVE_CLIENT_SECRET
  );
  
  oauth2Client.setCredentials({
    refresh_token: process.env.GDRIVE_REFRESH_TOKEN
  });
  
  return google.drive({ version: 'v3', auth: oauth2Client });
}

module.exports = { getDriveClient };

2.2 同步脚本重写

修改 scripts/grid-db/sync-to-drive.js（仓库→Drive 同步）：

• 删除所有 service_account / ServiceAccountCredentials 相关代码
• 改为 const { getDriveClient } = require('./drive-auth');
• 确保文件上传使用 OAuth2 客户端

2.3 Workflow YAML 更新

修改所有涉及 Drive 同步的 .github/workflows/*.yml：

旧（废弃）：

env:
  GOOGLE_DRIVE_SERVICE_ACCOUNT: $ secrets.GOOGLE_DRIVE_SERVICE_ACCOUNT 

新（OAuth2）：

env:
  GDRIVE_CLIENT_ID: $ secrets.GDRIVE_CLIENT_ID 
  GDRIVE_CLIENT_SECRET: $ secrets.GDRIVE_CLIENT_SECRET 
  GDRIVE_REFRESH_TOKEN: $ secrets.GDRIVE_REFRESH_TOKEN 

需要检查并更新的 Workflow 文件（至少包括）：

• sync-griddb-to-drive.yml（Grid-DB → Drive 镜像同步）
• auto-deploy-drive-bridge.yml（一键部署 Drive 桥接层）
• 所有引用 GOOGLE_DRIVE_SERVICE_ACCOUNT 或 GOOGLE_SERVICE_ACCOUNT_KEY 的 workflow
• grid-db-buffer-flush.yml（写缓冲层刷新，如涉及 Drive sync 步骤）

2.4 rclone 配置更新（如使用 rclone）

如果仓库中有 rclone 配置，更新为 OAuth2 模式：

[gdrive]
type = drive
client_id = 从环境变量读取
client_secret = 从环境变量读取
token = {"access_token":"","token_type":"Bearer","refresh_token":"从环境变量读取","expiry":"2000-01-01T00:00:00Z"}
root_folder_id = 光湖格点库文件夹ID

Phase 3 · 端到端验证

完成 Phase 2 所有代码修改后，先不要提交，按以下顺序验证：

1. 认证测试：运行 drive-auth.js，确认能获取有效的 access_token
2. 写入测试：向 Drive 上传一个测试文件 test-oauth2-{timestamp}.json
3. 读取测试：列出 Drive 目录，确认能看到测试文件
4. 删除测试文件：清理测试残留
5. 同步测试：模拟触发一次 sync-to-drive.js，确认 grid-db/ 数据能正常镜像到 Drive

Phase 4 · 🦅 天眼全局扫描（必须执行）

🦅

Phase 2-3 完成后，必须运行天眼系统进行全局扫描！

不允许跳过此步骤。天眼扫描通过后才能提交。

天眼扫描清单：

1. Secrets 完整性扫描
   • ✅ GDRIVE_CLIENT_ID 存在且非空
   • ✅ GDRIVE_CLIENT_SECRET 存在且非空
   • ✅ GDRIVE_REFRESH_TOKEN 存在且非空
   • ❌ GOOGLE_DRIVE_SERVICE_ACCOUNT 不再被任何 workflow 引用
   • ❌ GOOGLE_SERVICE_ACCOUNT_KEY 不再被任何 workflow 引用
2. 代码残留扫描
   • grep -r "service_account" .github/ scripts/ --include="*.js" --include="*.yml" --include="*.yaml" → 结果应为空
   • grep -r "ServiceAccountCredentials" .github/ scripts/ → 结果应为空
   • grep -r "GOOGLE_DRIVE_SERVICE_ACCOUNT" .github/ → 结果应为空
   • grep -r "GOOGLE_SERVICE_ACCOUNT_KEY" .github/ → 结果应为空
3. OAuth2 配置一致性扫描
   • 所有 Drive 相关 workflow 均引用 GDRIVE_CLIENT_ID / GDRIVE_CLIENT_SECRET / GDRIVE_REFRESH_TOKEN
   • 所有 Drive 相关 JS 脚本均通过 drive-auth.js 获取客户端（统一入口，不允许各脚本自建认证）
4. Workflow 链路完整性扫描
   • 所有 Drive 相关 workflow 能正常被触发（paths 配置正确）
   • 没有 workflow 因缺少环境变量而报错
   • [skip ci] 防循环触发标记仍然存在
5. 数据主权扫描
   • OAuth2 令牌只用于写入 光湖格点库/mirror/ 和 光湖格点库/inbox/ 目录
   • 没有任何代码试图访问用户 Drive 中「光湖格点库」以外的内容
   • 数据流向原则不变：仓库 = 权威源，Drive = 只读镜像
6. 安全扫描
   • 没有任何地方硬编码 Client ID / Client Secret / Refresh Token
   • 所有凭据均通过 process.env 读取
   • 日志输出中不会打印凭据内容

Phase 5 · 提交

天眼扫描全部通过后：

git add -A
git commit -m "refactor: OAuth2 代理人重构 · Service Account→OAuth2 全量替换 · ZY-OAUTH2-REBUILD-2026-0324-001 [skip ci]"
git push

提交后再触发一次完整的 CI/CD 流程，确认没有报错。

---

⚠️ Token 过期预警

⚠️

当前 Google Cloud 项目处于「测试」模式。

Refresh Token 有效期 7 天（604799 秒）。

短期方案（本周内）：

在天眼系统中增加 Token 有效期监控：

• 天眼每日检查 Token 是否即将过期（剩余 < 48 小时）
• 即将过期 → 在主控台 + 公告板发出告警
• 冰朔手动重新授权（2分钟流程）

长期方案（冰朔后续操作）：

• 在 Google Cloud Console → OAuth 权限请求页面 → 「发布应用」
• 或将权限范围缩小为 drive.file（非敏感范围，无需审核即可发布）
• 发布后 Refresh Token 永久有效

---

📝 执行回执区

铸渊完成每个 Phase 后，在此处追加回执：

Phase	状态	完成时间	备注 / Commit SHA
Phase 1 · 清理旧残留	⏳ 待执行	—	—
Phase 2 · OAuth2 全量替换	⏳ 待执行	—	—
Phase 3 · 端到端验证	⏳ 待执行	—	—
Phase 4 · 天眼全局扫描	⏳ 待执行	—	—
Phase 5 · 提交	⏳ 待执行	—	—

---

👤 人类手动操作区

👤

以下操作需要冰朔（人类）手动完成，铸渊无法代为执行：

已完成 ✅

1. ✅ Google Cloud 项目创建 — guanghu-drive-bridge 已创建
2. ✅ OAuth 2.0 客户端凭据生成 — Client ID + Client Secret 已获取
3. ✅ OAuth 授权流程 — 已通过浏览器完成授权，Refresh Token 已获取
4. ✅ GitHub Secrets 注入 — GDRIVE_CLIENT_ID / GDRIVE_CLIENT_SECRET / GDRIVE_REFRESH_TOKEN 三个 Secret 已添加到仓库

待完成（非紧急，建议一周内操作）

1. ⏳ 发布 OAuth 应用（解除 7 天 Token 过期限制）
   • 路径：Google Cloud Console → API和服务 → OAuth 权限请求页面 → 点「发布应用」
   • 或：将权限范围改为 drive.file 后发布（无需审核）
   • 完成后 Refresh Token 永久有效，不再需要每周重新授权
2. ⏳ Token 续期（如未发布应用，每 7 天需操作一次）
   • 重新访问授权链接 → 拿新 code → 在 Colab 运行换 token 脚本 → 更新 GitHub Secret GDRIVE_REFRESH_TOKEN

---

⚖️ 签发声明

本指令由 霜砚（PER-SY001） 代 TCS-0002∞ 冰朔 签发。

本指令的核心目标只有一个：把 Google Drive 存储链路彻底打通。

铸渊接收后按 Phase 1 → 2 → 3 → 4 → 5 严格顺序执行。

Phase 4 天眼扫描未通过之前，禁止执行 Phase 5 提交。

每个 Phase 完成后在回执区写状态。

🖋️ 霜砚 · PER-SY001

🧊 代 TCS-0002∞ 冰朔 签发

📅 2026-03-24T14:45+08:00