PHP整合七牛雲存儲實現遠程圖片抓取上傳

前言

七牛雲存儲提供了強大的遠程抓取 API，開發者無需將文件先下載到本地服務器，再上傳到七牛，而是直接通過 API 指令讓七牛服務器主動抓取遠程圖片。這種「服務端直傳」模式極大地節省了帶寬與時間成本。本文將詳細介紹如何使用 PHP 結合七牛的 fetch 接口，實現遠程圖片的高效上傳。

核心原理

七牛的抓取接口採用簽名授權機制。開發者需使用 AccessKey 與 SecretKey 對請求 URL 進行 HMAC-SHA1 簽名，生成 access_token，放入 HTTP Header 的 Authorization 字段中，然後向七牛的 fetch 端點發送 POST 請求即可觸發抓取。

關鍵步驟解析

1. URL 安全的 Base64 編碼

七牛 API 要求對部分參數進行 URL 安全的 Base64 編碼（將 + 替換為 -，/ 替換為 _，並去除填充字符 =）。

2. 生成簽名

簽名字符串由請求路徑、查詢參數、換行符及請求體組成。使用 hash_hmac('sha1', ...) 計算摘要，再經 URL 安全 Base64 編碼，最終拼接為 AccessKey:EncodedDigest 格式。

3. 發送抓取請求

構造完整的抓取 URL：https://iovip.qbox.me/fetch/{encodedSourceUrl}/to/{encodedEntryUri}，其中 encodedEntryUri 格式為 Bucket:Key。攜帶 Authorization: QBox {access_token} 與 Content-Type: application/json 發送 POST 請求。

完整代碼示例

<?php
/**
 * URL 安全 Base64 編碼
 */
function urlsafe_base64_encode($str) {
    $find = ['+', '/'];
    $replace = ['-', '_'];
    return str_replace($find, $replace, base64_encode($str));
}

/**
 * 生成七牛管理憑證
 */
function generate_access_token($access_key, $secret_key, $url, $params = '') {
    $parsed = parse_url($url);
    $path = $parsed['path'];
    $signing_str = $path;
    if (isset($parsed['query'])) {
        $signing_str .= '?' . $parsed['query'];
    }
    $signing_str .= "\n";
    if ($params) {
        if (is_array($params)) $params = http_build_query($params);
        $signing_str .= $params;
    }
    $digest = hash_hmac('sha1', $signing_str, $secret_key, true);
    return $access_key . ':' . urlsafe_base64_encode($digest);
}

/** 測試配置 */
$access_key = 'your_access_key';
$secret_key = 'your_secret_key';
$source_url = 'https://203.208.46.200/images/srpr/logo11w.png';
$bucket = 'ibeircn';
$key = '11.jpg';

$encoded_source = urlsafe_base64_encode($source_url);
$encoded_entry = urlsafe_base64_encode("$bucket:$key");
$fetch_url = "https://iovip.qbox.me/fetch/$encoded_source/to/$encoded_entry";

$token = generate_access_token($access_key, $secret_key, $fetch_url);
$headers = [
    'Content-Type: application/json',
    "Authorization: QBox $token"
];

$ch = curl_init($fetch_url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HEADER => true,
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_POST => true,
]);
$response = curl_exec($ch);
if ($response === false) {
    echo 'CURL ERROR: ' . curl_error($ch);
} else {
    var_dump($response);
}
curl_close($ch);
?>

常見問題與注意事項

• 區域選擇：上傳域名需根據存儲空間所在地區選擇（華東 iovip.qbox.me、華北 iovip-z1.qbox.me、華南 iovip-z2.qbox.me、北美 iovip-na0.qbox.me）。
• 文件大小限制：單次抓取文件不得超過 32MB。
• 錯誤碼排查：常見 401 為簽名錯誤，400 為參數格式錯誤，573 為源站響應超時。
• 回調通知：可在請求中添加 callbackurl 參數，抓取完成後七牛會回調業務服務器。

總結

通過 PHP 實現七牛遠程抓取上傳，核心在於正確構造簽名與請求格式。掌握此技術後，可輕鬆構建圖片遷移、熱鏈保護轉存、用戶頭像自動抓取等實用功能，顯著提升業務處理效率。