文件上传：R2 对象存储 + 后台文件管理 + 编辑器/封面联动

存储抽象（internal/storage，新包） - BlobStore 接口（Put / Open / Delete）+ 两个实现：R2（aws-sdk-go-v2 走 R2 的 S3 兼容 API，path-style、region auto）与本地磁盘（DataDir/uploads，零配置兜底）。选择：Endpoint / S3Api / Bucket / AccessKey / SecretAccessKey 齐全 → R2，缺任一项回落本地并在启动日志提示缺失的字段名（只报名字不报值） - 端点 URL 里的路径段不交给 SDK：path-style 下它会被折进对象 key，导致「数据库 key」和「实际对象 key」对不上（直链 404，实测复现）。 EndpointKeyPrefix 提取路径段给上传 handler 拼进 key，StripEndpointPath 只取 scheme://host 给 SDK——数据库 / 存储端 / 直链三方一致数据与 API - files 表：id / key(唯一) / name / mime / size / sha256 / store(r2|local) / created_at；URL 不入库，按「store 来源 + PublicBase」响应时解析，切存储端不破坏存量链接 - POST /api/admin/files：multipart 多文件，单文件 ≤50MB（MaxBytesReader 64MB）；类型白名单 = 图片（jpg/png/webp/gif/avif）+ 附件（pdf/zip/txt），扩展名 + http.DetectContentType 双重校验（实测拦截随机字节改名 .png）， SVG 拒绝（同源脚本）；内容 sha256 做 key（2026/09/{哈希前12位}{扩展名}），同内容重复上传自动去重复用 - GET /api/admin/files（分页 + 文件名搜索）、DELETE /{id}（先删对象再删行，存储端失败保留行可重试） - 公开路由 GET /uploads/{key}（main.go 挂载）：按 key 查行、存储层流式返回， Cache-Control immutable + ETag 304；R2 + PublicBase 时 302 直链（后端不出流量） - URL 解析：FileURL(store, key, PublicBase)——R2 且配了公开域名走直链，否则 /uploads/ 流式后台文件管理页（FilesView，「工作台 → 文件」） - 点击 / 拖拽多选上传（uploadFiles 走 FormData 裸 fetch，401 广播与 request() 一致）；缩略图卡片网格（图片出图、其他出类型占位）；复制链接（clipboard，非 https 回落 prompt）/ 打开 / 删除（确认提示）；分页、loading/empty 沿用既有模式编辑器联动（EditorView） - 封面：URL 输入框旁「上传」按钮，选图自动填 cover_url - wysiwyg：Crepe ImageBlock 官方 onUpload 钩子——粘贴 / 拖拽 / 插图全部走上传，返回 URL 后由 Crepe 插节点 - Markdown 模式：插图弹层加「上传」按钮 + 编辑器粘贴 / 拖拽图片，上传后在原光标处插入 ![](url)（异步上传先记光标位，逐张追踪偏移） .env.example - 模板入库（无敏感值）：Endpoint = 公开访问域名（直链）、S3Api = 上传端点、 Bucket / AccessKey / SecretAccessKey 验证 - 本地兜底全流程：上传 201、同内容去重复用、随机字节改名 .png 被内容嗅探拒绝、.svg 拒绝、公开路由 immutable 缓存头 + 内容一致、删除后存储与公开路由双清 404 - R2 真实链路（站主 .env）：上传 store=r2、直链 200（过程中定位并修复 S3Api 路径段折进 key 导致的直链 404，见 EndpointKeyPrefix） - 后端 go build/test/vet 全绿；前端构建通过
2026-09-27 16:26:11 +08:00
parent bc1b0ccce3
commit 34f0faedcc
18 changed files with 1191 additions and 15 deletions
@@ -4,15 +4,25 @@
 package admin

 import (
+	"context"
+	"crypto/sha256"
 	"crypto/subtle"
+	"encoding/hex"
 	"errors"
+	"fmt"
+	"io"
+	"mime/multipart"
 	"net/http"
+	"os"
+	"path/filepath"
 	"strings"
 	"sync"
+	"time"

 	"oneblog/internal/config"
 	"oneblog/internal/httpx"
 	"oneblog/internal/model"
+	"oneblog/internal/storage"
 	"oneblog/internal/store"
 )

@@ -20,6 +30,9 @@ type API struct {
 	Store    *store.Store
 	Cfg      *config.Config
 	Sessions *Sessions
+	// 文件上传的存储后端与公开域名（main.go 装配，两个 API 共享同一实例）
+	Blobs      storage.BlobStore
+	PublicBase string

 	loginOnce sync.Once
 	logins    *loginLimiter
@@ -56,6 +69,8 @@ func (a *API) Routes() http.Handler {
 	mux.HandleFunc("/api/admin/tags/", a.guard(a.tagByID))
 	mux.HandleFunc("/api/admin/projects", a.guard(a.listProjects))
 	mux.HandleFunc("/api/admin/projects/", a.guard(a.projectByID))
+	mux.HandleFunc("/api/admin/files", a.guard(a.files))
+	mux.HandleFunc("/api/admin/files/", a.guard(a.fileByID))
 	mux.HandleFunc("/api/admin/settings", a.guard(a.settings))
 	return mux
 }
@@ -545,3 +560,215 @@ func (a *API) bulkPosts(w http.ResponseWriter, r *http.Request) {
 		httpx.BadRequest(w, "action must be one of publish|draft|delete")
 	}
 }
+
+// ---------- files（上传与文件管理） ----------
+
+// 单文件上限与类型白名单。SVG 拒绝：同源内联可执行脚本。
+const (
+	maxFileUpload = 50 << 20
+)
+
+var allowFileExt = map[string]string{
+	".jpg":  "image/jpeg",
+	".jpeg": "image/jpeg",
+	".png":  "image/png",
+	".webp": "image/webp",
+	".gif":  "image/gif",
+	".avif": "image/avif",
+	".pdf":  "application/pdf",
+	".zip":  "application/zip",
+	".txt":  "text/plain",
+}
+
+func (a *API) files(w http.ResponseWriter, r *http.Request) {
+	switch r.Method {
+	case http.MethodGet:
+		fp, err := a.Store.ListFiles(httpx.QueryInt(r, "page", 1), httpx.QueryInt(r, "size", 20), httpx.QueryString(r, "q"))
+		if err != nil {
+			httpx.ServerError(w, err)
+			return
+		}
+		for i := range fp.Items {
+			fp.Items[i].URL = storage.FileURL(fp.Items[i].Store, fp.Items[i].Key, a.Cfg.UploadsPublicBase)
+		}
+		httpx.OK(w, fp)
+	case http.MethodPost:
+		a.uploadFiles(w, r)
+	default:
+		httpx.Error(w, http.StatusMethodNotAllowed, "GET/POST required")
+	}
+}
+
+func (a *API) uploadFiles(w http.ResponseWriter, r *http.Request) {
+	// 64MB = 50MB 文件 + multipart 编码开销
+	r.Body = http.MaxBytesReader(w, r.Body, maxFileUpload+(8<<20))
+	if err := r.ParseMultipartForm(8 << 20); err != nil {
+		httpx.BadRequest(w, "上传失败：请求体超过上限（单文件 50MB）")
+		return
+	}
+	if r.MultipartForm != nil {
+		defer r.MultipartForm.RemoveAll()
+	}
+	fhs := r.MultipartForm.File["file"]
+	if len(fhs) == 0 {
+		httpx.BadRequest(w, "没有收到文件")
+		return
+	}
+	out := make([]model.File, 0, len(fhs))
+	for _, fh := range fhs {
+		f, err := a.storeOne(r.Context(), fh)
+		if err != nil {
+			if bu, ok := err.(badUpload); ok {
+				httpx.BadRequest(w, string(bu))
+				return
+			}
+			httpx.ServerError(w, err)
+			return
+		}
+		out = append(out, f)
+	}
+	// URL 统一在这里解析：storeOne 的「去重复用已有行」路径也不例外
+	for i := range out {
+		out[i].URL = storage.FileURL(out[i].Store, out[i].Key, a.Cfg.UploadsPublicBase)
+	}
+	httpx.Created(w, out)
+}
+
+// badUpload 区分「文件本身的问题」（类型 / 大小 → 400 直接告诉站主）与
+// 服务器故障（500，已入库的部分保留）。
+type badUpload string
+
+func (e badUpload) Error() string { return string(e) }
+
+// storeOne 校验、哈希、落盘单个文件。内容哈希做 key（同年月分目录），
+// 同内容重复上传直接复用已有行，不产生孤儿对象。
+func (a *API) storeOne(ctx context.Context, fh *multipart.FileHeader) (model.File, error) {
+	if fh.Size > maxFileUpload {
+		return model.File{}, badUpload(fmt.Sprintf("%s：超过单文件 50MB 上限", fh.Filename))
+	}
+	ext := strings.ToLower(filepath.Ext(fh.Filename))
+	mime, ok := allowFileExt[ext]
+	if !ok {
+		return model.File{}, badUpload(fmt.Sprintf("%s：不支持的类型 %q", fh.Filename, ext))
+	}
+	src, err := fh.Open()
+	if err != nil {
+		return model.File{}, err
+	}
+	defer src.Close()
+
+	// 头 512 字节给 http.DetectContentType 嗅探真实类型，全文流过 sha256，
+	// 同时落到临时文件（S3 PutObject 需要确定的 ContentLength）。
+	tmp, err := os.CreateTemp("", "one-upload-*")
+	if err != nil {
+		return model.File{}, err
+	}
+	defer os.Remove(tmp.Name())
+	hasher := sha256.New()
+	head := make([]byte, 512)
+	hn, _ := io.ReadFull(src, head)
+	head = head[:hn]
+	for _, w := range []io.Writer{tmp, hasher} {
+		if _, err := w.Write(head); err != nil {
+			tmp.Close()
+			return model.File{}, err
+		}
+	}
+	copied, err := io.Copy(io.MultiWriter(tmp, hasher), src)
+	if err != nil {
+		tmp.Close()
+		return model.File{}, err
+	}
+	if err := tmp.Close(); err != nil {
+		return model.File{}, err
+	}
+	size := int64(hn) + copied
+
+	// 嗅探结果必须与扩展名声明的类型完全一致（防改后缀绕过白名单）。
+	// 不给 octet-stream 留口子：一张「image/png」嗅探出 octet-stream
+	// 就绝不是 PNG——随机字节改名上传就是这么溜进来的。
+	detected := strings.SplitN(http.DetectContentType(head), ";", 2)[0]
+	if detected != mime {
+		return model.File{}, badUpload(fmt.Sprintf("%s：文件内容与扩展名不符", fh.Filename))
+	}
+
+	sum := hex.EncodeToString(hasher.Sum(nil))
+	key := fmt.Sprintf("%s/%s%s", time.Now().UTC().Format("2006/01"), sum[:12], ext)
+	// S3Api 端点带路径段时（如 .../oss），该段会折进对象 key——
+	// 数据库必须记录同样的完整 key，直链才不会 404
+	if p := storage.EndpointKeyPrefix(a.Cfg.S3Endpoint); p != "" {
+		key = p + "/" + key
+	}
+
+	// 内容去重：同一份内容只存一份，复用已有行
+	if exist, err := a.Store.GetFileByKey(key); err == nil {
+		return exist, nil
+	}
+
+	f, err := os.Open(tmp.Name())
+	if err != nil {
+		return model.File{}, err
+	}
+	defer f.Close()
+	if err := a.Blobs.Put(ctx, key, f, size, mime); err != nil {
+		return model.File{}, err
+	}
+
+	created, err := a.Store.CreateFile(model.File{
+		Key:    key,
+		Name:   fh.Filename,
+		Mime:   mime,
+		Size:   size,
+		SHA256: sum,
+		Store:  a.Cfg.StorageDriver,
+	})
+	if err != nil {
+		return model.File{}, err
+	}
+	created.URL = storage.FileURL(created.Store, created.Key, a.Cfg.UploadsPublicBase)
+	return created, nil
+}
+
+func (a *API) fileByID(w http.ResponseWriter, r *http.Request) {
+	id, err := parseInt(strings.Trim(strings.TrimPrefix(r.URL.Path, "/api/admin/files/"), "/"))
+	if err != nil {
+		httpx.BadRequest(w, "bad file id")
+		return
+	}
+	switch r.Method {
+	case http.MethodGet:
+		f, err := a.Store.GetFile(id)
+		if errors.Is(err, store.ErrNotFound) {
+			httpx.NotFound(w)
+			return
+		}
+		if err != nil {
+			httpx.ServerError(w, err)
+			return
+		}
+		f.URL = storage.FileURL(f.Store, f.Key, a.Cfg.UploadsPublicBase)
+		httpx.OK(w, f)
+	case http.MethodDelete:
+		f, err := a.Store.GetFile(id)
+		if errors.Is(err, store.ErrNotFound) {
+			httpx.NotFound(w)
+			return
+		}
+		if err != nil {
+			httpx.ServerError(w, err)
+			return
+		}
+		// 先删对象存储再删行：存储端失败时行保留，可以重试
+		if err := a.Blobs.Delete(r.Context(), f.Key); err != nil {
+			httpx.ServerError(w, err)
+			return
+		}
+		if _, err := a.Store.DeleteFile(id); err != nil {
+			httpx.ServerError(w, err)
+			return
+		}
+		httpx.OK(w, map[string]any{"ok": true})
+	default:
+		httpx.Error(w, http.StatusMethodNotAllowed, "GET/DELETE required")
+	}
+}