SAE Storage 分散式儲存服務使用完整指南

前言

Sina App Engine (SAE) 為安全考量採用唯讀程式碼環境，無法直接寫入本地檔案系統。SAE 提供 Storage 服務 作為持久化儲存方案，適用於使用者上傳圖片、文件、日誌等資產。本文說明兩種存取方式與完整上傳範例。

核心概念

• Domain (域)：儲存容器，對應一個獨立的命名空間，需在 SAE 管理後台建立。
• 路徑格式：saestor://DomainName/目錄/檔案名
• 自動建立目錄：無需呼叫 mkdir()，直接寫入完整路徑即可自動建立中間目錄。

方式一：原生檔案系統函數 (推薦)

SAE 實作了 stream wrapper，可直接使用 fopen、fwrite、move_uploaded_file、file_get_contents 等標準函數操作 saestor:// 路徑。

完整上傳範例

<!DOCTYPE html>
<html><body>
<form action="" method="post" enctype="multipart/form-data">
    <label>選擇檔案: <input type="file" name="file" /></label>
    <input type="submit" name="submit" value="上傳" />
</form>

<?php
if ($_SERVER['REQUEST_METHOD'] === 'POST' && isset($_FILES['file'])) {
    $domain = 'test'; // SAE 後台建立的 Domain 名稱
    $upload_dir = "saestor://$domain/uploads/";
    
    $file = $_FILES['file'];
    if ($file['error'] !== UPLOAD_ERR_OK) {
        die("上傳錯誤代碼: {$file['error']}");
    }
    
    $dest = $upload_dir . basename($file['name']);
    if (move_uploaded_file($file['tmp_name'], $dest)) {
        echo "上傳成功: $dest";
    } else {
        echo "上傳失敗";
    }
}
?>
</body></html>

方式二：官方 SaeStorage 類別 (舊版相容)

// 需在 SAE 環境自動載入，或 require 'SaeStorage.php'
$storage = new SaeStorage();
$domain = 'mydomain';

// 寫入
$storage->write($domain, 'path/to/file.jpg', $binary_data);

// 讀取
$data = $storage->read($domain, 'path/to/file.jpg');

// 刪除
$storage->delete($domain, 'path/to/file.jpg');

// 列出檔案
$list = $storage->getList($domain, 'path/to/');

關鍵注意事項

1. Domain 必須預先建立：在 SAE 管理面板 → Storage → 新增 Domain。
2. 權限控管：Domain 可設為私有或公開，公開 Domain 的檔案可直接透過 URL 存取 (如 https://domain-name.stor.sinaapp.com/path/file.jpg)。
3. 檔案大小限制：單檔預設上限 2MB (可透過 sae.storage.max_file_size 設定調整)。
4. 不支援 mkdir() 權限參數：mkdir($path, 0777) 的模式參數會被忽略。
5. 串流複製大檔：大檔建議使用 stream_copy_to_stream 避免記憶體耗盡。

進階：取得公開存取 URL

function get_public_url($domain, $path) {
    // 公開 Domain 可直接拼接
    return "https://$domain.stor.sinaapp.com/$path";
}

// 私有 Domain 需簽名 URL (參考 SAE 官方簽名演算法)

結語

SAE Storage 以標準檔案系統介面提供分散式儲存，開發體驗極佳。掌握 saestor:// 協定與 Domain 管理，即可輕鬆處理使用者上傳、靜態資產部署、日誌持久化等需求。