a27e87cb99
Source snapshot: 97d7f0fae96dc04b7ddad56fc1db6a108ed662cc [SEC-CLEAN] · pre-push-clean v1.0 · 109处敏感信息已自动转乱码
315 lines
11 KiB
Markdown
315 lines
11 KiB
Markdown
---
|
||
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 |