基于Python(FastAPI)在GCP Run搭建API暴露私有GCS桶文件的最佳实践及方案验证

你的思路可行性验证 #

直接用return FileResponse(some_file_path)的方案不可行，核心原因：

• GCP Run/Cloud Functions的本地文件系统是临时且无持久化的，私有GCS桶内的文件不会自动挂载到本地路径，some_file_path指向的本地文件大概率不存在
• 即便手动将GCS文件下载到临时目录后再返回，会产生额外的流量成本、磁盘IO开销，且临时目录有容量限制（GCP Run默认10GB，Cloud Functions仅512MB），大文件场景会直接失败

推荐最佳实践 #

1. 预签名URL（优先选择） #

直接生成GCS对象的预签名URL返回给请求方，让请求方直接从GCS下载，无需API层中转。这种方案的优势：

• 无额外流量成本，GCS直接响应下载请求
• 性能最优，避免API层成为带宽瓶颈
• 代码简洁，无需处理文件流逻辑

示例代码：

from fastapi import FastAPI
from google.cloud import storage
import os
from datetime import timedelta

app = FastAPI()
storage_client = storage.Client()
BUCKET_NAME = os.getenv("GCS_BUCKET_NAME")

@app.get("/files/{file_name}")
def get_file_download_url(file_name: str):
    bucket = storage_client.bucket(BUCKET_NAME)
    blob = bucket.blob(file_name)
    
    # 生成有效期1小时的预签名URL
    signed_url = blob.generate_signed_url(
        version="v4",
        expiration=timedelta(hours=1),
        method="GET"
    )
    return {"download_url": signed_url}

2. 流式传输（仅适合必须API中转的场景） #

如果业务要求必须通过API层转发（比如需要额外权限校验、请求日志记录），不要落地文件到本地，直接流式读取GCS对象并返回响应流：

示例代码：

from fastapi import FastAPI
from google.cloud import storage
import os
from fastapi.responses import StreamingResponse

app = FastAPI()
storage_client = storage.Client()
BUCKET_NAME = os.getenv("GCS_BUCKET_NAME")

@app.get("/files/{file_name}")
def stream_file(file_name: str):
    bucket = storage_client.bucket(BUCKET_NAME)
    blob = bucket.blob(file_name)
    content_type = blob.content_type or "application/octet-stream"

    # 按1MB分片流式读取GCS对象
    def file_stream():
        chunk_size = 1024 * 1024
        with blob.open("rb") as f:
            while chunk := f.read(chunk_size):
                yield chunk

    return StreamingResponse(
        file_stream(),
        media_type=content_type,
        headers={"Content-Disposition": f"attachment; filename={file_name}"}
    )

部署关键注意事项 #

• 权限配置：给GCP Run服务账号授予roles/storage.objectViewer权限（针对目标私有GCS桶），禁止硬编码密钥
• 环境变量：通过GCP Run环境变量传入桶名，不要硬编码在代码中
• 资源限制：若采用流式传输，根据文件大小调整GCP Run的CPU/内存配置，避免请求超时
• 缓存策略：为响应添加Cache-Control等缓存头，减少重复请求开销

内容的提问来源于stack exchange，提问作者user1502505