Admin Guide
操作手冊與內部文件。此頁內容屬公開（只是 ops docs、無 token）；但所有 Jobs dashboard、API、上傳操作都需要認證。
1. 三種上傳路徑
| 路徑 | 用途 | 特性 |
|---|---|---|
| 首頁 | 拖拉本機 mp4 逐支上傳 | 直接 videos.insert、可自定 metadata、輸入上傳者 email 以追蹤 |
POST /api/jobs | Claude Skill 或腳本提交 mp4 URL | 非同步、cron 每小時處理、符合 YouTube 配額 |
| Jobs Dashboard | 看所有排程 job 狀態 | 自動每 15 秒刷新、可按 status / email 過濾 |
2. 認證方式
| 誰 | 怎麼認證 | Secret 名稱 |
|---|---|---|
| 瀏覽器使用者 | HTTP Basic Auth（user/任意、密碼共用） | SITE_PASSWORD |
| Claude Skill / 腳本 | Authorization: Bearer <token> | SKILL_API_TOKEN |
| Google OAuth（頻道綁定） | 一次性瀏覽器 OAuth flow | GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET |
3. 頻道綁定
- 首頁 Destination 卡片點 Register channel
- 跳到 Google 同意畫面，用要上傳到的 YouTube 頻道擁有者帳號登入
- 回到站點後下拉會多一個 option
- 多個頻道可切換預設（Set as default）、移除（Remove）
注意：新帳號要先在 GCP OAuth consent screen → Test users 加入後才能授權。
4. 重複上傳保護
規則
同一個頻道若已經有一支 status=done 且**標題完全相同**的影片，再來一次（browser 或 skill）會：
- Skill (
POST /api/jobs)：回 HTTP 200 +duplicate: true+ 現有video_url，不會再打 YouTube - Browser (
POST /api/upload/session)：回 HTTP 409 +duplicate_title，前端提示並提供現有連結
想重新上傳同標題 → 改一個字（例如加「v2」）再試。
5. 配額管理
YouTube Data API v3 預設配額：10,000 units/day，每支上傳耗 100 units = 一天最多 100 支。
查剩多少：
curl -H "Authorization: Bearer $SKILL_API_TOKEN" \ https://vup.onramplab.dev/api/quota
Cron worker 會在配額不足時自動停，隔天太平洋時間午夜重置後繼續處理排隊中的 job。
6. Teams 通知
每件事都通知 Youtube Uploader channel：
- ✅ 成功 含 YouTube URL 按鈕 + View job detail
- ⚠️ 失敗（可重試） 含 error_code + detail link
- ❌ 失敗（終局） 同上
- 🕐 每小時 tick 小結 —— 條列當次成功的 YouTube URL + Open Jobs dashboard
7. 重要連結
- 網站：https://vup.onramplab.dev/
- Jobs 看板：/jobs
- History API：
GET /api/uploads（瀏覽器上傳歷史） - CSV 匯出：/api/uploads/export.csv
- Google 驗證文件包：
docs/google-verification/（repo 裡） - Skill 給老闆：
for_ceo_skill/（repo 裡）
8. 常見維運操作
a. 手動觸發 cron 跑一次
curl -X POST https://yt-upload-worker.ifangdar.workers.dev/run
b. 查某個使用者今日的 job
curl -H "Authorization: Bearer $SKILL_API_TOKEN" \ "https://vup.onramplab.dev/api/jobs?email=xxx@xxx&since=2026-04-23"
c. 旋轉加密金鑰 / 更新 secrets
編輯 secrets/prod.env → 執行 bash scripts/sync-secrets.sh。此 script 會同步到 Pages 和 Worker 兩邊，避免手動 wrangler secret put 造成鍵不一致。
d. 加新的 GCP Test User
- GCP Console → APIs & Services → OAuth consent screen → Audience → Test users → Add
- 通知對方到 vup.onramplab.dev 按 Register channel
9. 錯誤代碼對照
| Code | 意義 | Retry? |
|---|---|---|
SSRF_BLOCKED | URL host 不在白名單 | — |
SOURCE_UNREACHABLE | mp4 404/403/timeout | — |
SOURCE_TOO_LARGE | > 10 GB | — |
QUOTA_EXHAUSTED | 今日配額用完 | ✅ 自動延到明天 |
AUTH_EXPIRED | 頻道 token 失效 | 要重綁頻道 |
YOUTUBE_REJECTED | YouTube 拒絕（版權 / 政策） | — |
CHANNEL_NOT_FOUND | channel_id 沒綁 | 先綁再試 |
NETWORK_ERROR | 暫時網路錯 | ✅ 指數退避最多 6h |
UNKNOWN | 其他 | — 查 Worker tail 看 detail |
10. 合規與驗證
Google API 送審三步驟（詳見 repo 的 docs/google-verification/）：
- OAuth Branding + Sensitive scope verification（3–5 工作天）
- YouTube Compliance Audit（必做，否則影片會被強制鎖 private）
- Quota Extension（跑一陣子有數據後再申請）
11. 聯絡
- 管理員：Eugene Chiang（eugene.chiang@onramplab.com）
- Cloudflare 帳號：
ifangdar@gmail.com - GCP 專案：
onr-yt-494200