---
belongs_to:
  - "[[INDEX · 铸渊·协作指令｜GitHub ↔ Notion 桥接协议]]"
---
# 🔑 铸渊指令｜Google Drive OAuth2 代理人重构 · Service Account→OAuth2 全量替换 + 天眼全局扫描验收（ZY-OAUTH2-REBUILD-2026-0324-001）

---

<aside>
🚨

**指令编号：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）](%F0%9F%AA%9E%20%E9%93%B8%E6%B8%8A%E6%8C%87%E4%BB%A4%EF%BD%9CGoogle%20Drive%20%E9%95%9C%E5%83%8F%E6%A1%A5%E6%8E%A5%E5%B1%82%20%C2%B7%20Gemini%E2%86%94%E6%A0%BC%E7%82%B9%E5%BA%93%E5%AE%9E%E6%97%B6%E5%90%8C%E6%AD%A5%EF%BC%88ZY-DRIV%2054042e08dd004fe484b75a0a13d90661.md)

**关联仓库：** [https://github.com/qinfendebingshuo/guanghulab](https://github.com/qinfendebingshuo/guanghulab)

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

</aside>

---

## 🎯 指令背景

### 核心矛盾

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

<aside>
❌

**Service Account 的 Google Drive 配额为 0GB。**

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

错误码：`403: Storage Quota Exceeded`

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

</aside>

### 解决方案

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

<aside>
✅

**以下凭据已全部就绪，已注入 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 已列入测试用户白名单 ✅**

</aside>

---

## 📋 铸渊执行任务清单

### 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 · 🦅 天眼全局扫描（必须执行）

<aside>
🦅

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

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

</aside>

天眼扫描清单：

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 过期预警

<aside>
⚠️

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

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

**短期方案（本周内）：**

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

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

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

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

---

## 📝 执行回执区

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

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

---

## 👤 人类手动操作区

<aside>
👤

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

</aside>

### 已完成 ✅

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