!65 fix: 七牛云私有 bucket 下载 URL 签名支持

Merge pull request !65 from 何朝晖/fix/qiniu

backend/internal/config/config.go

@@ -71,6 +71,7 @@ type QiniuConfig struct {
 	Bucket    string `mapstructure:"bucket"`
 	CDNHost   string `mapstructure:"cdn_host"`
 	UseHTTPS  bool   `mapstructure:"use_https"`
+	URLExpire int64  `mapstructure:"url_expire"` // 私有下载签名 URL 有效期（秒），默认 3600
 }
 
 // Load 从 YAML 配置文件和环境变量加载配置。
@@ -142,6 +143,7 @@ func setDefaults(v *viper.Viper) {
 	v.SetDefault("qiniu.bucket", "")
 	v.SetDefault("qiniu.cdn_host", "")
 	v.SetDefault("qiniu.use_https", true)
+	v.SetDefault("qiniu.url_expire", int64(3600))
 }
 
 func bindEnvVars(v *viper.Viper) {
@@ -179,4 +181,5 @@ func bindEnvVars(v *viper.Viper) {
 	v.BindEnv("qiniu.bucket", "GEN2D_QINIU_BUCKET")
 	v.BindEnv("qiniu.cdn_host", "GEN2D_QINIU_CDN_HOST")
 	v.BindEnv("qiniu.use_https", "GEN2D_QINIU_USE_HTTPS")
+	v.BindEnv("qiniu.url_expire", "GEN2D_QINIU_URL_EXPIRE")
 }

backend/internal/config/config.yml

@@ -31,3 +31,11 @@ image_gen:
   width: 1024
   height: 1024
   quality: "low"
+
+qiniu:
+  access_key: ""
+  secret_key: ""
+  bucket: ""
+  cdn_host: ""
+  use_https: true
+  url_expire: 3600  # 私有下载签名 URL 有效期（秒）

backend/internal/handler/generate.go

@@ -207,7 +207,7 @@ func GetAssets(c *gin.Context) {
 	for _, a := range assets {
 		response = append(response, model.AssetResponse{
 			Key:    a.Key,
-			URL:    a.URL,
+			URL:    storageSvc.GetSignedURL(a.Key),
 			Format: a.Format,
 		})
 	}

backend/internal/service/storage.go

@@ -3,6 +3,9 @@ package service
 import (
 	"bytes"
 	"context"
+	"crypto/hmac"
+	"crypto/sha1"
+	"encoding/base64"
 	"fmt"
 	"net/url"
 	"path/filepath"
@@ -65,15 +68,43 @@ func (s *StorageService) Upload(ctx context.Context, key string, data []byte) (s
 		return "", fmt.Errorf("qiniu upload: %w", err)
 	}
 
-	cdnURL := s.buildURL(key)
+	cdnURL := s.buildBaseURL(key)
 	l.Info("upload succeeded", "key", key, "url", cdnURL)
 	return cdnURL, nil
 }
 
 // GetDownloadURL 生成素材的下载 URL。
-// 公开 bucket 直接返回 CDN URL；私有 bucket 生成带签名的临时 URL。
+// 私有 bucket 生成带签名和过期时间的临时 URL。
 func (s *StorageService) GetDownloadURL(_ context.Context, key string) (string, error) {
-	return s.buildURL(key), nil
+	return s.signDownloadURL(key), nil
+}
+
+// GetSignedURL 获取私有资源签名 URL（公开方法，供 handler 层使用）。
+func (s *StorageService) GetSignedURL(key string) string {
+	return s.signDownloadURL(key)
+}
+
+// signDownloadURL 生成七牛云私有资源下载签名 URL。
+// 格式：http://<domain>/<key>?e=<deadline>&token=<downloadToken>
+func (s *StorageService) signDownloadURL(key string) string {
+	baseURL := s.buildBaseURL(key)
+
+	expire := s.cfg.URLExpire
+	if expire <= 0 {
+		expire = 3600
+	}
+	deadline := time.Now().Unix() + expire
+
+	signStr := fmt.Sprintf("%s?e=%d", baseURL, deadline)
+
+	mac := hmac.New(sha1.New, []byte(s.cfg.SecretKey))
+	mac.Write([]byte(signStr))
+	signature := mac.Sum(nil)
+
+	encodedSign := base64.URLEncoding.EncodeToString(signature)
+	token := fmt.Sprintf("%s:%s", s.cfg.AccessKey, encodedSign)
+
+	return fmt.Sprintf("%s?e=%d&token=%s", baseURL, deadline, token)
 }
 
 // Delete 从七牛云删除指定对象。
@@ -91,9 +122,17 @@ func (s *StorageService) Delete(ctx context.Context, key string) error {
 	return nil
 }
 
-// buildURL 根据配置构建完整的 CDN URL。
-func (s *StorageService) buildURL(key string) string {
+// buildBaseURL 根据配置构建完整的基础 CDN URL（不含签名参数）。
+func (s *StorageService) buildBaseURL(key string) string {
 	host := strings.TrimRight(s.cfg.CDNHost, "/")
+	scheme := "http"
+	if s.cfg.UseHTTPS {
+		scheme = "https"
+	}
+	// 如果 host 已经包含 scheme，直接使用；否则添加
+	if !strings.HasPrefix(host, "http://") && !strings.HasPrefix(host, "https://") {
+		host = scheme + "://" + host
+	}
 	segments := strings.Split(key, "/")
 	for i, seg := range segments {
 		segments[i] = url.PathEscape(seg)

docs/api.md

@@ -516,14 +516,14 @@ POST /api/v1/prompt/optimize
 
 ### GET /api/v1/assets/download
 
-公开接口（无需认证）。返回 302 重定向到七牛云 CDN URL。前端可通过此接口加载素材图片，作为 CDN 直接访问的替代方案。
+公开接口（无需认证）。返回 302 重定向到七牛云带签名的临时下载 URL（私有 bucket 签名有效时长默认为 3600 秒）。前端可通过此接口加载素材图片。
 
 | 参数 | 类型 | 说明 |
 |------|------|------|
 | `key` | string | 对象存储 Key，查询参数 |
 
 响应：
-- HTTP 302，`Location` 头指向 CDN URL
+- HTTP 302，`Location` 头指向带签名的临时下载 URL
 - 400：缺少 key 参数
 - 500：生成下载链接失败
 

docs/database.md

@@ -150,16 +150,18 @@ users/user_a1B2c3/projects/proj_abc/tasks/task_xyz/output/spritesheet.png
 
 ### 访问方式
 
-素材上传后返回 CDN URL，前端直接通过该 URL 访问图片。
+素材上传后 asset 表存储对象 Key 和基础 CDN URL。由于 bucket 为私有读，前端通过 API 获取的 `url` 字段为带签名参数的临时下载链接（有效期可配置，默认 3600 秒）。
 
-下载接口 `GET /api/v1/assets/download?key=...` 返回 302 重定向到 CDN URL。
+格式：`https://cdn.example.com/<key>?e=<deadline>&token=<downloadToken>`
+
+下载接口 `GET /api/v1/assets/download?key=...` 返回 302 重定向到带签名的临时 URL。
 
 ### asset 表的 url 字段
 
-存储七牛云 CDN 完整 URL，如：
+存储七牛云基础 CDN URL（不含签名），如：
 `https://cdn.example.com/users/user_a1B2c3/projects/proj_abc/tasks/task_xyz/output/spritesheet.png`
 
-前端直接使用该 URL 加载图片，无需拼接路径。
+注意：该字段仅在数据库中使用，API 返回给前端的 URL 会根据对象 Key 实时生成带签名的临时下载链接。
 
 ---
 
@@ -190,6 +192,7 @@ users/user_a1B2c3/projects/proj_abc/tasks/task_xyz/output/spritesheet.png
 | `GEN2D_QINIU_BUCKET` | — | 七牛云 Bucket 名称 |
 | `GEN2D_QINIU_CDN_HOST` | — | CDN 域名（如 `https://cdn.example.com`） |
 | `GEN2D_QINIU_USE_HTTPS` | `true` | 是否使用 HTTPS |
+| `GEN2D_QINIU_URL_EXPIRE` | `3600` | 私有下载签名 URL 有效期（秒） |
 
 在 `config.go` 中扩展字段即可，无需额外依赖。