---
belongs_to:
  - "[[INDEX · 铸渊·协作指令｜GitHub ↔ Notion 桥接协议]]"
---
# 🔄 铸渊指令｜OAuth2 Token 自动续期引擎 + 天眼休眠避让机制（下篇）· 多用户Token流程 + 告警推送 + 天眼扫描清单 + 执行回执（ZY-TOKEN-RENEW-2026-0324-001）

---

<aside>
🚨

**指令编号：ZY-TOKEN-RENEW-2026-0324-001（下篇）**

**上篇：** [🔄 铸渊指令｜OAuth2 Token 自动续期引擎 + 天眼休眠避让机制（上篇）· 6天自动刷新 + 休眠窗口智能避让 + 多用户Token管理架构（ZY-TOKEN-RENEW-2026-0324-001）](%F0%9F%94%84%20%E9%93%B8%E6%B8%8A%E6%8C%87%E4%BB%A4%EF%BD%9COAuth2%20Token%20%E8%87%AA%E5%8A%A8%E7%BB%AD%E6%9C%9F%E5%BC%95%E6%93%8E%20+%20%E5%A4%A9%E7%9C%BC%E4%BC%91%E7%9C%A0%E9%81%BF%E8%AE%A9%E6%9C%BA%E5%88%B6%EF%BC%88%E4%B8%8A%E7%AF%87%EF%BC%89%C2%B7%206%E5%A4%A9%E8%87%AA%E5%8A%A8%E5%88%B7%E6%96%B0%20%20bee3531f4e1a4e52a597922626c9d317.md)

**前置指令：** [🔑 铸渊指令｜Google Drive OAuth2 代理人重构 · Service Account→OAuth2 全量替换 + 天眼全局扫描验收（ZY-OAUTH2-REBUILD-2026-0324-001）](%F0%9F%94%91%20%E9%93%B8%E6%B8%8A%E6%8C%87%E4%BB%A4%EF%BD%9CGoogle%20Drive%20OAuth2%20%E4%BB%A3%E7%90%86%E4%BA%BA%E9%87%8D%E6%9E%84%20%C2%B7%20Service%20Account%20ea304b59af9f473fbadfe1df1faee61e.md)

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

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

</aside>

---

## Phase F · 多用户 Token 流程

### 新用户接入流程

当新开发者需要接入 Drive 权限时，流程如下：

```mermaid
sequenceDiagram
    participant Dev as 新开发者
    participant Human as 冰朔（人类管理员）
    participant ZY as 铸渊（自动化）
    participant GH as GitHub Secrets
    participant GG as Google OAuth2
    
    Dev->>Human: 申请 Drive 权限
    Human->>GG: 在 Google Cloud 加入测试用户白名单
    Human->>GG: 用新用户 Gmail 完成 OAuth 授权
    Human->>GH: 注入 GDRIVE_REFRESH_TOKEN_DEVxxx
    Human->>ZY: 通知铸渊更新注册表
    ZY->>ZY: 在 gdrive-tokens.json 添加新条目
    ZY->>ZY: 提交注册表更新
    Note over ZY: 下次 CRON 触发时自动纳入续期管理
```

### 新用户注册表条目模板

铸渊收到新用户接入通知后，在 `config/gdrive-tokens.json` 的 `tokens` 数组中添加：

```json
{
  "user_id": "DEV-001",
  "user_name": "开发者名称",
  "role": "developer",
  "github_secret_name": "GDRIVE_REFRESH_TOKEN_DEV001",
  "last_renewed": "2026-XX-XXTXX:XX:XX+08:00",
  "expires_at": "2026-XX-XXTXX:XX:XX+08:00",
  "status": "active",
  "renew_count": 0,
  "notes": "开发者描述"
}
```

### GitHub Secret 命名规范

| **角色** | **Secret 命名** | **示例** |
| --- | --- | --- |
| 主控（冰朔） | `GDRIVE_REFRESH_TOKEN` | 已存在 |
| 开发者 1 | `GDRIVE_REFRESH_TOKEN_DEV001` | 未来添加 |
| 开发者 2 | `GDRIVE_REFRESH_TOKEN_DEV002` | 未来添加 |
| CI/CD 测试 | `GDRIVE_REFRESH_TOKEN_CI` | 可选 |

### Workflow 如何读取多用户 Token

`renew-tokens.js` 已设计为遍历注册表，根据每个条目的 `github_secret_name` 从环境变量读取对应 Token。

但 Workflow 中需要显式将 Secret 注入环境变量。铸渊在添加新用户时，同时更新 Workflow YAML：

```yaml
# 在 renew-gdrive-tokens.yml 和 check-token-health.yml 的 env 中添加：
env:
  GDRIVE_CLIENT_ID: $ secrets.GDRIVE_CLIENT_ID 
  GDRIVE_CLIENT_SECRET: $ secrets.GDRIVE_CLIENT_SECRET 
  GDRIVE_REFRESH_TOKEN: $ secrets.GDRIVE_REFRESH_TOKEN 
  # 新增开发者 Token（每次加人时追加）
  # GDRIVE_REFRESH_TOKEN_DEV001: $ secrets.GDRIVE_REFRESH_TOKEN_DEV001 
  # GDRIVE_REFRESH_TOKEN_DEV002: $ secrets.GDRIVE_REFRESH_TOKEN_DEV002 
  GITHUB_TOKEN: $ secrets.GITHUB_TOKEN 
```

---

## Phase G · 告警推送系统

### 告警级别

| **级别** | **触发条件** | **推送渠道** | **行动** |
| --- | --- | --- | --- |
| 🟢 INFO | Token 刷新成功 | 回执日志（注册表 renew_log） | 无需操作 |
| 🟡 WARN | Token 剩余 < 72小时但刷新成功 | 回执日志 + grid-db/logs/ | 关注但无需操作 |
| 🟠 ALERT | Token 剩余 < 48小时且刷新失败 | token-alert.json + 主控台 + 公告板 | 要求人类 24 小时内介入 |
| 🔴 CRITICAL | Token 已过期 / 全部刷新失败 | token-alert.json + 主控台 + 公告板 + Workflow 失败标记 | **紧急：人类立即介入重新授权** |

### 告警输出文件：`grid-db/logs/token-alert.json`

刷新脚本在有失败时自动生成此文件，天眼系统可读取它来决定是否推送告警：

```json
{
  "alert_type": "TOKEN_RENEWAL_FAILURE",
  "severity": "CRITICAL",
  "time": "2026-03-30T10:00:00Z",
  "failed_users": ["TCS-0002"],
  "message": "1 个 Token 刷新失败，需要人类介入",
  "action_required": "HUMAN_REAUTH",
  "instructions": [
    "1. 登录 Google Cloud Console",
    "2. 访问授权链接获取新 code",
    "3. 运行换 token 脚本获取新 refresh_token",
    "4. 更新 GitHub Secret: GDRIVE_REFRESH_TOKEN",
    "5. 手动触发 renew-gdrive-tokens workflow 验证"
  ]
}
```

### 天眼告警读取脚本：`scripts/gdrive/push-token-alerts.js`

```jsx
/**
 * push-token-alerts.js
 * 
 * 天眼系统调用此脚本读取 token-alert.json
 * 并将告警信息写入主控台 + 公告板
 * 
 * 输出：
 *   - grid-db/notifications/token-alert-{timestamp}.md  → 主控台通知
 *   - grid-db/bulletin/token-alert-{timestamp}.md       → 公告板通知
 */

const fs = require('fs');
const path = require('path');

function pushAlerts() {
  const alertPath = path.join(__dirname, '../../grid-db/logs/token-alert.json');
  
  if (!fs.existsSync(alertPath)) {
    console.log('✅ 无告警。');
    return;
  }
  
  const alert = JSON.parse(fs.readFileSync(alertPath, 'utf8'));
  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
  
  // 生成主控台通知
  const dashboardContent = [
    `# ⚠️ Token 续期告警`,
    ``,
    `**时间:** ${alert.time}`,
    `**严重级:** ${alert.severity || 'ALERT'}`,
    `**影响用户:** ${alert.failed_users.join(', ')}`,
    ``,
    `## 描述`,
    alert.message,
    ``,
    `## 需要人类操作`,
    ...(alert.instructions || []).map((s, i) => s),
    ``,
    `---`,
    `*此告警由 Token 续期引擎自动生成*`
  ].join('\n');
  
  // 写入主控台
  const notifDir = path.join(__dirname, '../../grid-db/notifications');
  if (!fs.existsSync(notifDir)) fs.mkdirSync(notifDir, { recursive: true });
  fs.writeFileSync(path.join(notifDir, `token-alert-${timestamp}.md`), dashboardContent);
  
  // 写入公告板
  const bulletinDir = path.join(__dirname, '../../grid-db/bulletin');
  if (!fs.existsSync(bulletinDir)) fs.mkdirSync(bulletinDir, { recursive: true });
  fs.writeFileSync(path.join(bulletinDir, `token-alert-${timestamp}.md`), dashboardContent);
  
  // 清除已处理的告警文件
  fs.unlinkSync(alertPath);
  
  console.log(`⚠️ 告警已推送到主控台 + 公告板: token-alert-${timestamp}.md`);
}

pushAlerts();
```

---

## Phase H · 天眼全局扫描清单（必须执行）

<aside>
🦅

**所有代码写完后，必须运行天眼系统进行全局扫描！**

天眼扫描通过后才能提交。

</aside>

### 1. 文件完整性扫描

| **检查项** | **预期** | **状态** |
| --- | --- | --- |
| `config/gdrive-tokens.json` 存在 | ✅ 存在且 JSON 格式有效 | ⏳ |
| `scripts/gdrive/renew-tokens.js` 存在 | ✅ 存在且可执行 | ⏳ |
| `scripts/gdrive/check-hibernation.js` 存在 | ✅ 存在且可导入 | ⏳ |
| `scripts/gdrive/push-token-alerts.js` 存在 | ✅ 存在且可执行 | ⏳ |
| `.github/workflows/renew-gdrive-tokens.yml` 存在 | ✅ 存在且 YAML 格式有效 | ⏳ |
| `.github/workflows/check-token-health.yml` 存在 | ✅ 存在且 YAML 格式有效 | ⏳ |
| `grid-db/logs/` 目录存在 | ✅ 存在（可为空） | ⏳ |
| `grid-db/notifications/` 目录存在 | ✅ 存在（可为空） | ⏳ |
| `grid-db/bulletin/` 目录存在 | ✅ 存在（可为空） | ⏳ |

### 2. 注册表数据完整性扫描

- ✅ `schema_version` 字段存在
- ✅ `oauth_app.token_ttl_days` = 7
- ✅ `oauth_app.renew_interval_days` = 6
- ✅ `tokens` 数组至少包含主控 TCS-0002
- ✅ 主控条目的 `github_secret_name` = `GDRIVE_REFRESH_TOKEN`
- ✅ 主控条目的 `status` = `active`
- ✅ 主控条目的 `expires_at` 在未来（未过期）
- ✅ 每个条目的 `github_secret_name` 唯一且对应一个实际存在的 GitHub Secret

### 3. CRON 与休眠冲突扫描

| **检查项** | **预期** | **状态** |
| --- | --- | --- |
| 主刷新 A CRON 时间不在周六 20:00-00:00 CST | ✅ 周一 10:00 CST 安全 | ⏳ |
| 主刷新 B CRON 时间不在周六 20:00-00:00 CST | ✅ 周四 10:00 CST 安全 | ⏳ |
| 安全网 CRON 时间不在日休眠 04:00-04:10 CST | ✅ 12:15 CST 安全 | ⏳ |
| 主刷新 A + B 间隔 ≤ 6 天 | ✅ 周一→周四 = 3天，周四→下周一 = 4天 | ⏳ |
| 最坏情况：周一失败+周四失败，安全网能在 48h 内发现 | ✅ 每天检查，最晚 1 天内发现 | ⏳ |
| 最极端场景：连续 3 次刷新都失败→告警输出 | ✅ token-alert.json + 非零退出码 | ⏳ |

### 4. 天眼生命线任务集成扫描

- ✅ `skyeye-config.json`（或等价）中包含 `TOKEN-RENEW` 和 `TOKEN-HEALTH` 生命线任务
- ✅ 两个任务均标记 `hibernate_exempt: true`
- ✅ 休眠决策引擎已加入生命线豁免逻辑
- ✅ 天眼休眠期内触发 Token 刷新，确认能正常执行（不被休眠拦截）

### 5. 安全扫描

- ❌ `renew-tokens.js` 中无硬编码凭据
- ❌ 日志输出中不包含 Token 实体（grep 检查 `console.log` 中是否输出 `refresh_token`）
- ❌ `gdrive-tokens.json` 中不包含 Token 实体（只有元数据）
- ✅ 所有凭据仅通过 `process.env` 读取
- ✅ GitHub Secret 更新用 `tweetsodium` 加密（不明文传输）

### 6. Workflow 完整性扫描

- ✅ `renew-gdrive-tokens.yml` 包含 `[skip ci]` 防循环触发
- ✅ `check-token-health.yml` 包含 `[skip ci]` 防循环触发
- ✅ 两个 Workflow 均支持 `workflow_dispatch` 手动触发
- ✅ 失败时有告警输出（非零退出码 + alert 文件）
- ✅ `tweetsodium` 依赖在 workflow 中安装（不依赖本地 node_modules）

### 7. 端到端流程验证

- ✅ 手动触发 `renew-gdrive-tokens` Workflow，确认能正常完成
- ✅ 检查注册表 `renew_log` 中是否写入了成功记录
- ✅ 检查 `expires_at` 是否已更新为新的 7 天后
- ✅ 检查 GitHub Secret `GDRIVE_REFRESH_TOKEN` 是否被更新（看 secret 的 "Updated" 时间戳）
- ✅ 手动触发 `check-token-health` Workflow，确认显示 “All tokens healthy”

---

## Phase I · 提交

天眼扫描全部通过后：

```bash
git add -A
git commit -m "feat: OAuth2 Token 自动续期引擎 + 天眼生命线任务豁免 + 多用户Token管理 · ZY-TOKEN-RENEW-2026-0324-001 [skip ci]"
git push
```

提交后，手动触发一次 `renew-gdrive-tokens` Workflow，确认全绿。

---

## 📈 生命周期时序图

以下是一个典型周期的时序图，展示刷新、休眠、检查的协作关系：

```mermaid
gantt
    title Token 续期生命周期（一周示例）
    dateFormat HH:mm
    axisFormat %H:%M
    
    section 周一
    主刷新 A :done, 10:00, 10:10
    安全网检查 :done, 12:15, 12:20
    
    section 周二
    安全网检查 :done, 12:15, 12:20
    
    section 周三
    安全网检查 :done, 12:15, 12:20
    
    section 周四
    主刷新 B :done, 10:00, 10:10
    安全网检查 :done, 12:15, 12:20
    
    section 周五
    安全网检查 :done, 12:15, 12:20
    
    section 周六
    安全网检查 :done, 12:15, 12:20
    天眼休眠 :crit, 20:00, 24:00
    
    section 周日
    安全网检查 :done, 12:15, 12:20
```

---

## 📝 执行回执区

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

| **Phase** | **状态** | **完成时间** | **备注 / Commit SHA** |
| --- | --- | --- | --- |
| A · Token 注册表 | ⏳ 待执行 | — | — |
| B · Token 自动刷新脚本 | ⏳ 待执行 | — | — |
| C · 天眼休眠避让机制 | ⏳ 待执行 | — | — |
| D · GitHub Action Workflow | ⏳ 待执行 | — | — |
| E · 天眼生命线任务注册 | ⏳ 待执行 | — | — |
| F · 多用户 Token 流程 | ⏳ 待执行 | — | — |
| G · 告警推送系统 | ⏳ 待执行 | — | — |
| H · 天眼全局扫描 | ⏳ 待执行 | — | — |
| I · 提交 | ⏳ 待执行 | — | — |

---

## 👤 人类手动操作区

<aside>
👤

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

</aside>

### 当前无需人类操作 ✅

本指令的所有任务均可由铸渊独立完成。

### 未来可能需要的人类操作

1. ⏳ **添加新开发者时**：
    - 在 Google Cloud Console 加入测试用户白名单
    - 用新用户 Gmail 完成 OAuth 授权
    - 在 GitHub 添加对应的 `GDRIVE_REFRESH_TOKEN_DEVxxx` Secret
    - 通知铸渊更新注册表
2. ⏳ **Token 刷新失败时（告警触发）**：
    - 重新访问授权链接 → 拿新 code → 换新 token → 更新 GitHub Secret
    - 手动触发 `renew-gdrive-tokens` Workflow 验证
3. ⏳ **发布 OAuth 应用（彻底解决过期问题）**：
    - 路径：Google Cloud Console → API和服务 → OAuth 权限请求页面 → 点「发布应用」
    - 发布后 Refresh Token 永久有效，续期引擎变为安全备份而非必要操作

---

## ⚖️ 指令执行顺序

<aside>
🚦

**上篇 Phase A→E + 下篇 Phase F→I，严格顺序执行。**

Phase H 天眼扫描未通过前，禁止执行 Phase I 提交。

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

</aside>

---

🖋️ 霜砚 · PER-SY001

🧊 代 TCS-0002∞ 冰朔 签发

📅 2026-03-24T15:00+08:00