---
belongs_to:
- "[[INDEX · 铸渊·协作指令｜GitHub ↔ Notion 桥接协议]]"
---
# 🔑 铸渊指令｜Google Drive OAuth2 代理人重构 · Service Account→OAuth2 全量替换 + 天眼全局扫描验收（ZY-OAUTH2-REBUILD-2026-0324-001）
---
---
## 🎯 指令背景
### 核心矛盾
此前 Google Drive 镜像桥接层（ZY-DRIVE-BRIDGE-2026-0323-001）设计采用 **Service Account（机器人模式）** 连接 Google Drive。经实测发现：
### 解决方案
主控已完成 **OAuth 2.0 代理人授权**，即：让铸渊以「主控冰朔的代理人」身份直接操作 2TB 空间。
---
## 📋 铸渊执行任务清单
### 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`（统一认证入口）：
```jsx
/**
* 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`：
**旧（废弃）：**
```yaml
env:
GOOGLE_DRIVE_SERVICE_ACCOUNT: $ secrets.GOOGLE_DRIVE_SERVICE_ACCOUNT
```
**新（OAuth2）：**
```yaml
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 · 🦅 天眼全局扫描（必须执行）
天眼扫描清单：
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 · 提交
天眼扫描全部通过后：
```bash
git add -A
git commit -m "refactor: OAuth2 代理人重构 · Service Account→OAuth2 全量替换 · ZY-OAUTH2-REBUILD-2026-0324-001 [skip ci]"
git push
```
提交后再触发一次完整的 CI/CD 流程，确认没有报错。
---
## ⚠️ 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