← 返回主頁
開放 API 實戰 · 2026-08-14

夸克網盤 × Google Drive 自動同步 · 101 教學

用兩哪的開放 API 做指定 Folder 同步 · 單向 / 雙向都做到
事前準備、工作原理、系統負荷、實戰腳本、cron 排程 —— 一次過講清

⚡ 本教學基於 2026-08-14 實測(夸克網盤官方 Skill v1.0.11 + Google Drive API)。所有步驟都要用真實帳號授權,不涉及任何第三方收費服務。
0 架構 1 事前準備 2 安裝夸克 Skill 3 授權夸克 4 授權 GDrive 5 工作原理 6 單向同步 7 雙向同步 8 Cron 排程 9 系統負荷 10 踩坑合集 11 命令速查 附 附錄

0 為何這樣做(架構概覽)

Google Drive 同夸克網盤都開放 API,但兩哪係不同的雲端,沒有直接互傳通道。同步的本質 = 一部中間機器(VM)定時「查看兩哪 → 對比 → 補齊」。用的係兩哪官方開放 API,$0 成本,不使任何第三方中介。

Google Drive Folder Drive API (list/download) VM 中轉(diff + 暫存) 夸克開放 API (upload) 夸克網盤 Folder

反向同步(夸克 → GDrive)就是將鏈路反向;雙向同步 = 兩條鏈路同時執行 + 衝突規則。

🔁

自動對比

定時 list 兩哪檔案,檔名 + 大小 + 修改時間 diff,有缺有變先傳

💻

VM 中轉

沒有 server-to-server 直傳,檔案一定要經中間機暫存再上傳

💰

完全免費

兩哪 API 都不收費(有免費額度),VM 用 Oracle Always Free 都夠跑

🎛️

幾種模式

單向備份 / 單向歸檔 / 雙向同步,folder 自訂,頻率自訂

1 事前準備(文件清單)

開始之前,逐項準備好下面的帳號同工具。大部分你已經有 —— 不使買任何東西。

檔案 / 帳號點樣準備用途
夸克網盤帳號pan.quark.cn 註冊(APP / 網頁都得,免費 10GB)同步目標 / 來源之一
Google 帳號 + Drive普通 Gmail 帳號 + 有 Drive 空間同步目標 / 來源之一
Google Cloud OAuth 憑證Google Cloud Console → APIs & Services → OAuth Client ID(Desktop 類型),下載 JSONGDrive API 授權(client_id / client_secret)
Linux VMOracle Always Free ARM(2 OCPU / 12GB)或任何有 Node ≥16 的機行 sync script + cron
Node.js ≥ 16node --version 檢查,沒有就裝夸克官方 CLI 需要
夸克網盤 Skill(官方 zip)官方下載:quarkclouddrive-1.0.11.zip夸克 API CLI(search / upload / download)
gws CLI 或 google_api.pyHermes google-workspace skill 內置,或用 gcloud 生態工具GDrive API 操作
全部就緒後,由安裝到第一次同步成功,約 15–30 分鐘(視乎你熟不熟 OAuth)。

2 安裝夸克網盤 Skill

夸克官方發佈了一個命令行 Skill(Skill 包 = SKILL.md + scripts + references),入面的 quark-drive.cjs 就是完整 CLI,包晒檔案上傳/下載/搜尋/分享。

下載官方 Skill zip

curl -sL -o quark-skill.zip "https://pdds.quark.cn/download/stfile/ssyytvtxsstwsu8uo/quarkclouddrive-1.0.11.zip"

這個係夸克官方 pdds 分發網址,zip 內含 SKILL.mdscripts/(CLI)、references/(操作文件)。

安裝去 agent 全局 skills 目錄

unzip -qo quark-skill.zip -d ~/.hermes/skills/quarkclouddrive

放在全局目錄(不要放在項目目錄),任何項目都能用。

驗證 CLI

cd ~/.hermes/skills/quarkclouddrive && node scripts/quark-drive.cjs --version # 輸出: 1.0.11-1e57fff

見到版本號即安裝成功。所有夸克操作都透過 node scripts/quark-drive.cjs <命令> 執行。

3 授權夸克網盤帳號

CLI 用夸克開放平台 OAuth 授權。在普通桌面機一跑 login 就會自動開瀏覽器;但在無桌面的 server(例如 Oracle VM)就要用下面流程。

起 login,拿授權連結

node scripts/quark-drive.cjs login

在無 browser 的環境,命令會即時 fail,但錯誤訊息入面有一條完整授權 URL(開頭係 https://pan.quark.cn/open/v1/oauth/agent?...)。複製它。

在手機 / 電腦開條連結完成授權

用夸克網盤 APP 掃 QR code,或者瀏覽器開連結登入 → 點擊「授權」。授權頁會顯示一個 授權碼(格式 AAC-xxxx...,複製它。

用授權碼完成綁定

node scripts/quark-drive.cjs login --token "AAC-你在授權頁複製的授權碼" # 輸出: {"code":0,"msg":"成功","data":{"userId":"your_user_id"}}

code:0 即成功,access token 已存本地(之後所有命令自動用)。

驗證

node scripts/quark-drive.cjs search --keyword "test" # 輸出 file_list = 你網盤的檔案

搜到檔案 = 授權有效。常用命令:search(搜尋)、uploaddownloadcreate-foldershare

授權碼有效期約 10 分鐘,逾時就重新行一次 login 拿新連結。授權過一次之後,refresh token 自動續期,不需要再操作。
⚠️ ~/.hermes/skills/quarkclouddrive/ 內會存 access token —— 這個係敏感資料,公開 repo / 備份前一定要排除。

4 授權 Google Drive API

Google 側要在 Cloud Console 開一個 OAuth Client,再授權一次,取得 token 先可以讀寫你的 Drive。

開 OAuth Client

Google Cloud Console → APIs & Services → OAuth consent screen(External + 加自己做測試使用者)→ Credentials → Create OAuth Client ID → 類型選擇 Desktop app → 下載 client_secret.json

啟用 Drive API

# Console → APIs & Services → Library → 搜 "Google Drive API" → Enable

授權 + 拿 token

gws CLI 或任何 OAuth 流程(本機開 browser → 授權 → 回調拿 code → 換 token.json)。之後所有 Drive 操作都用 token.json

驗證

gws drive list --max 10 # 或者 python3 google_api.py drive search "trashed = false" --max 10
⚠️ OAuth 測試模式的 token 大約 7 日就過期。長期運行建議將 app 在 consent screen 發佈(publish),或準備自動 refresh 流程,不是就要定期重新授權。

5 工作原理(同步引擎)

同步引擎行三步:list → diff → transfer。每次運行都是這樣循環,分別只在 diff 的規則。

① List 兩哪 ② Diff(名+大小+時間) ③ Transfer 缺/變 ④ 更新狀態 (下次 cron 再行)

Diff 判定表

情況單向(GDrive → 夸克)單向(夸克 → GDrive)雙向
A 有、B 沒有上傳去夸克上傳去 GDrive上傳去另一哪
兩哪都有、內容不同GDrive 版覆蓋夸克夸克版覆蓋 GDrive修改時間新者勝
兩哪一樣(名+大小+時間)跳過(不浪費流量)
A 沒有、B 有(刪除)刪夸克 / 保留刪 GDrive / 保留⚠️ 要設規則(見 §7)
🔑 關鍵限制:沒有 server-to-server 直傳。檔案一定要經 VM 暫存(下載下來 → 上傳上去)。所以 VM 要預留空間 ≈ 最大單一檔案 × 2。

6 單向同步實戰(GDrive → 夸克備份)

最常見場景:GDrive 係 master,夸克做備份。寫一個 Python sync script,定期跑。

#!/usr/bin/env python3 # gdrive2quark.py — 單向同步: GDrive folder → 夸克 folder import json, os, subprocess, tempfile, hashlib GD_FOLDER_ID = "1ABC..." # GDrive folder ID (URL /drive/folders/<ID>) QK_ROOT_FOLDER = "/我的雲盤/備份" # 夸克目標路徑 GWS = "python3 ~/.hermes/skills/productivity/google-workspace/scripts/google_api.py" QKCLI = "node ~/.hermes/skills/quarkclouddrive/scripts/quark-drive.cjs" def gd_list(): r = subprocess.run(f'{GWS} drive search "\'{GD_FOLDER_ID}\' in parents and trashed=false" --raw-query --max 500', shell=True, capture_output=True, text=True) out = r.stdout.strip().splitlines() files = {} for line in out: try: j = json.loads(line) files[j["name"]] = {"id": j["id"], "mime": j["mimeType"]} except Exception: pass return files def qk_list(): r = subprocess.run(f'{QKCLI} search --keyword "備份"', shell=True, capture_output=True, text=True) # 實際用夸克 API 按 folder 列出; 此處簡化示範 return {} def qk_upload(local_path, remote_name): subprocess.run(f'{QKCLI} upload "{local_path}" --name "{remote_name}"', shell=True, capture_output=True) def main(): gd = gd_list() qk = qk_list() for name, meta in gd.items(): if name in qk: # 已存在 → 跳過(示範簡化) print(f"skip {name}") continue print(f"download {name}") tmp = f"/tmp/sync/{name}" subprocess.run(f'{GWS} drive download {meta["id"]} --output {tmp}', shell=True) print(f"upload {name}") qk_upload(tmp, name) os.remove(tmp) if __name__ == "__main__": main()

↑ 完整版會加埋大小/修改時間比較、錯誤重試、日誌輸出 —— 上面係核心骨架,跑通先再擴充。

✅ 單向同步最安全:master 永遠清晰,錯了都只是備份副本過期,不會搞亂原檔。

7 雙向同步進階

雙向 = 兩哪都是 master。風險係衝突同刪除,所以要多做兩件事:修改時間比較垃圾桶規則

修改時間(modifiedTime)係唯一仲裁

兩哪都有同名檔 → 比較 modifiedTime(GDrive API 有;夸克 API 有 updated_at),新的覆蓋舊的。時間差少於 2 秒當相同(時鐘偏差容錯)。

內容 hash 做二次確認

同大小同時間不等於同內容。為求穩妥:檔案 < 50MB 可以比對 MD5/SHA1(GDrive 有內建 MD5 checksum,夸克要下載才能計算 —— 所以預設不建議那麼做,太耗流量)。權衡

刪除要用「軟刪除」

雙向同步最大地雷:A 刪了檔案,同步過去會連 B 那份也刪除。建議:不同步刪除,或者刪除之前先移去「垃圾桶」保留 30 日。

⚠️ 雙向同步不建議一開波就用在重要資料。先單向行一段時間,確認 diff 邏輯合適,先開雙向。

8 Cron 自動排程

同步 script 寫好之後,用 cron 定時跑就變成全自動。以下係常用頻率:

# crontab -e # 每 30 分鐘同步一次(GDrive → 夸克) */30 * * * * cd /home/ubuntu/sync && /usr/bin/python3 gdrive2quark.py >> sync.log 2>&1 # 或者每日凌晨 3 點做一次全量 0 3 * * * cd /home/ubuntu/sync && /usr/bin/python3 gdrive2quark.py >> sync.log 2>&1 # 雙向同步建議錯開兩個方向的時間 */30 * * * * cd /home/ubuntu/sync && /usr/bin/python3 sync_both.py >> sync.log 2>&1
⚠️ cron 環境 PATH 非常精簡(/usr/bin:/bin)—— script 入面所有命令要用絕對路徑(/usr/bin/python3~/bin/... 展開),不要只寫 python3,否則 cron 執行時會找不到。
日誌會越來越大,加一行 logrotate:*/30 * * * * 那一行改用 >> sync.log,然後每週手動 truncate -s 0 sync.log 或安裝 logrotate。

9 系統負荷估算

同步是「輕量但間歇性」的 workload:平時幾乎零負載,傳大檔時才消耗資源。以下是實測數量級:

項目估算備註
CPU(list + diff)< 5 秒 / 1000 檔主要係 API 回應等待,不是運算
CPU(傳檔)單核心 20–40%上傳/下載壓縮加密,短暫
記憶體30–80 MBPython + 兩個 CLI 子進程
VM 暫存磁碟最大單檔 × 2下載下來 + 上傳進行中同時存在
網絡流量每次 = 變更檔案總量 × 2GDrive 下載 + 夸克上傳,各計一次
API 配額(GDrive)list 1 req + 每檔 download 1 req免費 quota 每日約 100 萬次,家用 100 萬倍有餘
API 配額(夸克)search 1 req + 每檔 upload 1 req免費額度內,但不要狂刷(見 §10)
Oracle Always Free 夠不夠✅ 綽綽有餘2 OCPU / 12GB 行 cron 同步完全沒有壓力
🟢 100 個 5MB 檔案首次全量同步 ≈ 1GB 流量 + 約 10–20 分鐘(視乎兩哪網速)。之後每次只傳變更,通常幾十秒完成。

10 踩坑合集(全部親測)

夸克 login 在 server 沒有 browser 即刻 fail —— 不用慌,授權 URL 在錯誤訊息內,複製出來給用戶打開即可;授權後複製 AAC-xxx 授權碼回來用 login --token 綁定。
GDrive OAuth 測試模式 token 7 日死 —— 長跑要 publish consent screen 或者加自動 refresh。
夸克 API 有速率限制 —— 全量同步幾百個檔要分批次 + sleep,不要一次過度請求,會 429。
VM 暫存空間 —— 傳 10GB 大檔前檢查 df -h,不夠位會 sync 失敗(temp 檔要即傳即刪)。
cron 見不到命令 —— 用絕對路徑 + 開頭 cd,仲要確認 script 有 chmod +x 或者用 /usr/bin/python3 直接叫。
檔名 Unicode / 空格 —— 兩個 API 對檔名處理不同,同步 script 入面檔名要統一用 UTF-8 並正確 quote。
token 檔案不要放進 git —— 夸克 access token + GDrive token.json 都都是敏感資料,sync 項目 repo 要加 .gitignore

11 命令速查表

命令作用
node quark-drive.cjs search --keyword "K"搜尋夸克檔案
node quark-drive.cjs upload "file" --name "名"上傳去夸克
node quark-drive.cjs download --fid "..."下載夸克檔案
node quark-drive.cjs create-folder "名"開資料夾
node quark-drive.cjs share --fid "..."分享連結
node quark-drive.cjs whoami / login --token AAC-...看帳號 / 綁定授權
gws drive search "trashed = false" --max 100列 GDrive 檔案
gws drive download <file_id> --output 路徑下載 GDrive 檔案
crontab -e / crontab -l編輯 / 看排程

附錄:檔案路徑 + 完成清單

▎關鍵檔案路徑

路徑說明
~/.hermes/skills/quarkclouddrive/scripts/quark-drive.cjs夸克 CLI 主程式
~/.hermes/skills/quarkclouddrive/(config 目錄)夸克授權 token 存放處
client_secret.json + token.jsonGDrive OAuth 憑證
/home/ubuntu/sync/gdrive2quark.py同步 script(示例位置)
/home/ubuntu/sync/sync.log同步日誌

▎部署完成清單

檢查項
夸克 CLI 執行 --versionsearch 搜到網盤檔案
GDrive gws drive search 出到檔案列表
sync script 手動行一次成功(不要直接上 cron)
目標 folder 兩哪檔案數一致(search --keyword 對數)
cron 加入 + 等一個週期,確認 sync.log 有新輸出
token 檔案確認沒有入任何 git repo

喜歡這份教學?請我飲杯咖啡 ☕

☕ 請我飲咖啡