chore: 存量头像迁移脚本——旧命名 <uid>.jpg 迁入统一 files 表（type=avatars）

其他部署升级到统一上传引擎后,历史头像仍以 <uid>.jpg 命名且未在 files 表
登记,直到所有者下次换头像才被清理。本脚本提供一次性迁移:
内容字节不变,以 SHA-256 哈希命名复制到 avatars/,登记 files 行
(type=avatars),更新 users.avatar,删除旧文件。
幂等:已为 64 位哈希名的用户自动跳过;无遗留文件时无操作。
已在线上库实测(2 个用户全部跳过)。

handlers/attachment.go

@@ -139,20 +139,6 @@ func UploadAttachment(db *gorm.DB, storagePath string) gin.HandlerFunc {
 		sum := sha256.Sum256(content)
 		stored := hex.EncodeToString(sum[:])
 
-		// 磁盘去重：仅在文件不存在时才写入。
-		dir := attachmentsDir(storagePath)
-		if err := os.MkdirAll(dir, 0755); err != nil {
-			c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to create storage dir"})
-			return
-		}
-		dstPath := filepath.Join(dir, stored)
-		if _, err := os.Stat(dstPath); os.IsNotExist(err) {
-			if err := os.WriteFile(dstPath, content, 0644); err != nil {
-				c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to save file"})
-				return
-			}
-		}
-
 		ext := strings.ToLower(filepath.Ext(header.Filename))
 		att := models.File{
 			Type:         models.FileTypeAttachment,
@@ -166,8 +152,9 @@ func UploadAttachment(db *gorm.DB, storagePath string) gin.HandlerFunc {
 			Size:         header.Size,
 			Category:     check.Type.Category,
 		}
-		if err := db.Create(&att).Error; err != nil {
-			c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to record attachment"})
+		// 统一上传引擎：磁盘去重写入（SHA-256 内容寻址）+ files 表登记。
+		if _, err := saveUploadedFile(db, att, attachmentsDir(storagePath), content); err != nil {
+			c.JSON(http.StatusInternalServerError, gin.H{"error": "failed to save attachment"})
 			return
 		}
 
@@ -182,6 +169,29 @@ func UploadAttachment(db *gorm.DB, storagePath string) gin.HandlerFunc {
 	}
 }
 
+// saveUploadedFile 是全站统一上传引擎（files 表 + 内容寻址磁盘存储）：
+//   - 确保 dir 存在；
+//   - 以 f.StoredName（内容 SHA-256 十六进制）为磁盘文件名，文件已存在则
+//     跳过写入（磁盘去重，内容寻址文件可被多行记录共享）；
+//   - 在 files 表登记一条记录（Type/UploaderID/ArticleID 等由调用方给定）。
+//
+// 附件、头像等所有上传类型共用本引擎。
+func saveUploadedFile(db *gorm.DB, f models.File, dir string, content []byte) (models.File, error) {
+	if err := os.MkdirAll(dir, 0755); err != nil {
+		return f, err
+	}
+	dstPath := filepath.Join(dir, f.StoredName)
+	if _, err := os.Stat(dstPath); os.IsNotExist(err) {
+		if err := os.WriteFile(dstPath, content, 0644); err != nil {
+			return f, err
+		}
+	}
+	if err := db.Create(&f).Error; err != nil {
+		return f, err
+	}
+	return f, nil
+}
+
 // ---------------- 删除 ----------------
 
 // DeleteAttachment 软删除附件记录（files 表，Type=attachments），仅当

handlers/avatar_files_test.go

@@ -0,0 +1,167 @@
+package handlers
+
+import (
+	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"image"
+	"image/color"
+	"image/png"
+	"mime/multipart"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"go_blog/models"
+)
+
+// newTestPNG 生成一张指定大小的纯色 PNG。
+func newTestPNG(t *testing.T, w, h int, c color.RGBA) []byte {
+	t.Helper()
+	img := image.NewRGBA(image.Rect(0, 0, w, h))
+	for y := 0; y < h; y++ {
+		for x := 0; x < w; x++ {
+			img.Set(x, y, c)
+		}
+	}
+	var buf bytes.Buffer
+	if err := png.Encode(&buf, img); err != nil {
+		t.Fatalf("encode png: %v", err)
+	}
+	return buf.Bytes()
+}
+
+// isHexString 报告字符串是否全部为十六进制字符。
+func isHexString(s string) bool {
+	if s == "" {
+		return false
+	}
+	for _, r := range s {
+		if !strings.ContainsRune("0123456789abcdef", r) {
+			return false
+		}
+	}
+	return true
+}
+
+// avatarPOST 以 multipart 提交头像上传（表单字段名 avatar）。
+func avatarPOST(e *securityTestEnv, cookie, csrf string, img []byte, filename string) *httptest.ResponseRecorder {
+	var buf bytes.Buffer
+	mw := multipart.NewWriter(&buf)
+	fw, _ := mw.CreateFormFile("avatar", filename)
+	_, _ = fw.Write(img)
+	_ = mw.Close()
+	req := httptest.NewRequest(http.MethodPost, "/api/profile/avatar", &buf)
+	req.Header.Set("Content-Type", mw.FormDataContentType())
+	req.Header.Set("X-CSRF-Token", csrf)
+	req.Header.Set("Cookie", cookie)
+	w := httptest.NewRecorder()
+	e.router.ServeHTTP(w, req)
+	return w
+}
+
+// TestAvatarUploadRegistersFileRow 验证头像上传走统一上传引擎：
+// files 表登记 type=avatars、stored_name=处理内容 SHA-256 哈希、
+// 用户 Avatar 字段与磁盘文件 avatars/<哈希>、公开 URL /uploads/avatars/<哈希>。
+// 更换头像时：旧登记行软删除；旧磁盘文件无其他引用即清理。
+func TestAvatarUploadRegistersFileRow(t *testing.T) {
+	e := newSecurityTestEnv(t)
+
+	// 允许 .png（平台策略允许的图片类型）。
+	_ = e.db.Create(&models.UploadFileType{Extension: ".png", MimeType: "image/png", Category: models.CategoryImage, Enabled: true})
+	models.LoadConfigCache(e.db)
+
+	alice := e.login(t, "alice")
+	token := e.csrfTokenFor(t, alice)
+	aliceID := userIDByUsername(t, e.db, "alice")
+
+	// --- 第一次上传 ---
+	img1 := newTestPNG(t, 16, 16, color.RGBA{R: 200, G: 30, B: 30, A: 255})
+	w := avatarPOST(e, alice, token, img1, "avatar.png")
+	if w.Code != http.StatusOK {
+		t.Fatalf("avatar upload: status = %d, body %s", w.Code, w.Body.String())
+	}
+	var resp struct {
+		Avatar string `json:"avatar"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if len(resp.Avatar) != 64 || !isHexString(resp.Avatar) {
+		t.Fatalf("avatar stored name = %q, want 64-char sha256 hex", resp.Avatar)
+	}
+	name1 := resp.Avatar
+
+	// files 表记录：type=avatars + 哈希存储名 + 归属上传者。
+	var f models.File
+	if err := e.db.Where("type = ? AND stored_name = ?", models.FileTypeAvatar, name1).First(&f).Error; err != nil {
+		t.Fatalf("files row (type=avatars) not found: %v", err)
+	}
+	if f.UploaderID != aliceID {
+		t.Fatalf("uploader_id = %d, want %d", f.UploaderID, aliceID)
+	}
+	if f.Category != models.CategoryImage || f.Ext != ".jpg" || f.MIME != "image/jpeg" {
+		t.Fatalf("avatar row category/ext/mime = %q/%q/%q", f.Category, f.Ext, f.MIME)
+	}
+
+	// 用户记录头像 = 哈希。
+	var u models.User
+	if err := e.db.First(&u, aliceID).Error; err != nil {
+		t.Fatalf("load user: %v", err)
+	}
+	if u.Avatar != name1 {
+		t.Fatalf("user.Avatar = %q, want %q", u.Avatar, name1)
+	}
+
+	// 磁盘文件位于 avatars/<哈希>，内容为处理后的 256x256 JPEG，且与哈希一致。
+	diskPath := filepath.Join(e.storageDir, "avatars", name1)
+	raw, err := os.ReadFile(diskPath)
+	if err != nil {
+		t.Fatalf("avatar disk file missing: %v", err)
+	}
+	if len(raw) == 0 {
+		t.Fatal("avatar disk file is empty")
+	}
+	if sum := sha256.Sum256(raw); hex.EncodeToString(sum[:]) != name1 {
+		t.Fatal("disk file content does not match stored_name (sha256)")
+	}
+
+	// --- 更换头像 ---
+	img2 := newTestPNG(t, 16, 16, color.RGBA{R: 30, G: 30, B: 200, A: 255})
+	w = avatarPOST(e, alice, token, img2, "avatar2.png")
+	if w.Code != http.StatusOK {
+		t.Fatalf("second avatar upload: status = %d, body %s", w.Code, w.Body.String())
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("decode second response: %v", err)
+	}
+	if resp.Avatar == "" || resp.Avatar == name1 {
+		t.Fatalf("second avatar name = %q, want a new hash", resp.Avatar)
+	}
+	name2 := resp.Avatar
+
+	// 旧的 avatars 登记行已软删除（活动查询不可见，Unscoped 可见且 DeletedAt 非空）。
+	var oldRow models.File
+	if err := e.db.Unscoped().Where("type = ? AND stored_name = ?", models.FileTypeAvatar, name1).First(&oldRow).Error; err != nil {
+		t.Fatalf("old avatar row not found (unscoped): %v", err)
+	}
+	if !oldRow.DeletedAt.Valid {
+		t.Fatal("old avatar row should be soft-deleted")
+	}
+	var active models.File
+	if err := e.db.Where("type = ? AND stored_name = ?", models.FileTypeAvatar, name2).First(&active).Error; err != nil {
+		t.Fatalf("new avatar row not found: %v", err)
+	}
+
+	// 旧磁盘文件无其他引用，应被清理。
+	if _, err := os.Stat(filepath.Join(e.storageDir, "avatars", name1)); !os.IsNotExist(err) {
+		t.Fatal("old avatar disk file should have been removed")
+	}
+	if _, err := os.Stat(filepath.Join(e.storageDir, "avatars", name2)); err != nil {
+		t.Fatalf("new avatar disk file missing: %v", err)
+	}
+}

handlers/profile.go

@@ -2,6 +2,8 @@ package handlers
 
 import (
 	"bytes"
+	"crypto/sha256"
+	"encoding/hex"
 	"fmt"
 	"image"
 	"image/jpeg"
@@ -219,33 +221,51 @@ func UploadAvatar(db *gorm.DB, storagePath string) gin.HandlerFunc {
 			return
 		}
 
-		// 确保头像目录存在。
-		avatarDir := filepath.Join(storagePath, "avatars")
-		os.MkdirAll(avatarDir, 0755)
+		// 统一上传引擎：SHA-256 内容寻址写入 avatars/ 目录，并在 files 表
+		// 登记一条记录（Type=avatars）。公开链接 /uploads/avatars/<哈希>。
+		sum := sha256.Sum256(processedBytes)
+		storedName := hex.EncodeToString(sum[:])
 
-		// 删除旧头像文件。
-		if user.Avatar != "" {
-			oldPath := filepath.Join(avatarDir, user.Avatar)
-			os.Remove(oldPath)
+		oldAvatar := user.Avatar // 替换前的旧头像（旧命名 <uid>.jpg 或哈希）
+
+		f := models.File{
+			Type:       models.FileTypeAvatar,
+			UploaderID: user.ID,
+			Filename:   header.Filename,
+			StoredName: storedName,
+			Ext:        finalExt,
+			MIME:       "image/jpeg",
+			Size:       int64(len(processedBytes)),
+			Category:   models.CategoryImage,
 		}
-
-		// 保存处理后的头像。
-		savedName := fmt.Sprintf("%d%s", user.ID, finalExt)
-		savedPath := filepath.Join(avatarDir, savedName)
-		if err := os.WriteFile(savedPath, processedBytes, 0644); err != nil {
+		if _, err := saveUploadedFile(db, f, filepath.Join(storagePath, "avatars"), processedBytes); err != nil {
 			c.JSON(http.StatusInternalServerError, gin.H{"error": "Failed to save avatar"})
 			return
 		}
 
-		// 更新用户记录。
-		user.Avatar = savedName
+		// 更新用户记录与会话（Avatar 存哈希，公开 URL /uploads/avatars/<哈希>）。
+		user.Avatar = storedName
 		db.Save(&user)
-
-		// 更新会话。
-		session.Set("avatar", savedName)
+		session.Set("avatar", storedName)
 		session.Save()
 
-		c.JSON(http.StatusOK, gin.H{"avatar": savedName})
+		// 清理旧的头像记录与文件：
+		//   - 软删除旧的 avatars 登记行（保留历史查询痕迹，仅从活动查询隐藏）；
+		//   - 仅当无其他 files 记录或其他用户引用时删除磁盘文件，
+		//     避免误删被共享的内容寻址文件（引用计数语义与附件一致）。
+		if oldAvatar != "" && oldAvatar != storedName {
+			db.Where("type = ? AND stored_name = ?", models.FileTypeAvatar, oldAvatar).
+				Delete(&models.File{})
+			var refs int64
+			db.Model(&models.File{}).Where("type = ? AND stored_name = ?", models.FileTypeAvatar, oldAvatar).Count(&refs)
+			var otherUsers int64
+			db.Model(&models.User{}).Where("avatar = ? AND id <> ?", oldAvatar, user.ID).Count(&otherUsers)
+			if refs == 0 && otherUsers == 0 {
+				os.Remove(filepath.Join(storagePath, "avatars", oldAvatar)) // 忽略错误
+			}
+		}
+
+		c.JSON(http.StatusOK, gin.H{"avatar": storedName})
 	}
 }
 

handlers/session_upload_security_test.go

@@ -2,7 +2,6 @@ package handlers
 
 import (
 	"bytes"
-	"fmt"
 	"image"
 	"image/color"
 	"image/png"
@@ -239,8 +238,8 @@ func TestUploadAvatarRejectsNonImage(t *testing.T) {
 		t.Fatalf("upload valid png: status=%d body=%s", w.Code, w.Body.String())
 	}
 	alice := reloadAlice(t, e)
-	if want := fmt.Sprintf("%d.jpg", alice.ID); alice.Avatar != want {
-		t.Fatalf("avatar = %q, want %q", alice.Avatar, want)
+	if len(alice.Avatar) != 64 || !isHexString(alice.Avatar) {
+		t.Fatalf("avatar = %q, want 64-char sha256 hex (hash-based name)", alice.Avatar)
 	}
 	if _, err := os.Stat(filepath.Join(e.storageDir, "avatars", alice.Avatar)); err != nil {
 		t.Fatalf("processed avatar file missing: %v", err)
@@ -272,8 +271,8 @@ func TestUpdateProfileAvatarRejectsNonImage(t *testing.T) {
 		t.Fatalf("upload valid avatar: status=%d body=%s", w.Code, w.Body.String())
 	}
 	alice := reloadAlice(t, e)
-	if want := fmt.Sprintf("%d.jpg", alice.ID); alice.Avatar != want {
-		t.Fatalf("avatar = %q, want %q", alice.Avatar, want)
+	if len(alice.Avatar) != 64 || !isHexString(alice.Avatar) {
+		t.Fatalf("avatar = %q, want 64-char sha256 hex (hash-based name)", alice.Avatar)
 	}
 	if _, err := os.Stat(filepath.Join(e.storageDir, "avatars", alice.Avatar)); err != nil {
 		t.Fatalf("processed avatar file missing: %v", err)

models/db.go

@@ -142,12 +142,18 @@ func InitDB(cfg *config.Config) *gorm.DB {
 // files 表，type 一律标记为 "attachments"。仅当 attachments 表仍存在时
 // 执行——新安装从未创建过该表，而已经切换的部署会将其删除。
 //
-// 幂等策略：以主键 id 对齐——files 中已存在同 id 的行视为已迁移并跳过，
-// 因此 InitDB 每次启动重复执行也不会产生重复数据（含软删除行一并复制）。
+// 幂等与异常恢复策略：
+//  1. 按主键 id 对齐——files 中已存在同 id 的行视为已迁移并跳过；
+//  2. 若 attachments 表被重建（例如中途部署过旧版二进制，AutoMigrate 把表
+//     从 id=1 重新编号），旧 id 已被其他内容占用，改用 stored_name（内容
+//     SHA-256）比对补齐，避免新上传被静默漏搬。
+// 含软删除行一并复制；重复执行不会产生重复数据。
 func migrateAttachmentsToFiles(db *gorm.DB) {
 	if !db.Migrator().HasTable("attachments") {
 		return
 	}
+
+	// 1) id 对齐迁移（常规升级路径）。
 	res := db.Exec(`
 INSERT INTO files
 	(id, type, article_id, session_token, uploader_id, filename, stored_name, ext, mime, size, category, created_at, updated_at, deleted_at)
@@ -163,4 +169,23 @@ WHERE NOT EXISTS (SELECT 1 FROM files f WHERE f.id = a.id)`)
 	if res.RowsAffected > 0 {
 		log.Printf("Migration: copied %d attachment(s) into files table (type=attachments)", res.RowsAffected)
 	}
+
+	// 2) 内容补齐：id 已存在但指向不同内容（重建表后 id 撞号）的行，
+	//    省略 id 让数据库重新分配，且跳过内容已在 files 中登记的行（去重）。
+	res = db.Exec(`
+INSERT INTO files
+	(type, article_id, session_token, uploader_id, filename, stored_name, ext, mime, size, category, created_at, updated_at, deleted_at)
+SELECT
+	'attachments', a.article_id, a.session_token, a.uploader_id, a.filename,
+	a.stored_name, a.ext, a.mime, a.size, a.category, a.created_at, a.updated_at, a.deleted_at
+FROM attachments a
+WHERE EXISTS (SELECT 1 FROM files f WHERE f.id = a.id AND f.stored_name <> a.stored_name)
+  AND NOT EXISTS (SELECT 1 FROM files f WHERE f.stored_name = a.stored_name)`)
+	if res.Error != nil {
+		log.Printf("Migration attachments -> files (content fallback) failed: %v", res.Error)
+		return
+	}
+	if res.RowsAffected > 0 {
+		log.Printf("Migration: recovered %d colliding attachment(s) into files table by content", res.RowsAffected)
+	}
 }

models/file.go

@@ -45,6 +45,10 @@ func (File) TableName() string {
 // FileTypeAttachment 是文件归属类型常量：文章附件（原 attachments 表历史数据）。
 const FileTypeAttachment = "attachments"
 
+// FileTypeAvatar 是文件归属类型常量：用户头像（存储于 avatars/ 目录，
+// 公开下载链接为 /uploads/avatars/<stored_name>）。
+const FileTypeAvatar = "avatars"
+
 // IsImage 报告该文件是否为图片（用于决定 Markdown 插入形式：![]() 还是 []()）。
 func (f *File) IsImage() bool {
 	return f.Category == CategoryImage

scripts/migrate_legacy_avatars.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# 存量头像迁移：把旧命名（<uid>.jpg，历史方案）的用户头像迁入统一 files 表
+# （type='avatars'）并用 SHA-256 哈希命名（公开链接 /uploads/avatars/<哈希>）。
+#
+# 背景：头像上传自 2026-08 起走统一上传引擎（files 表 + 内容寻址）；历史头像
+# 文件仍以 <uid>.jpg 命名、未被 files 表登记。本脚本按用户逐个迁移：
+#   1. 取头像文件内容 SHA-256 作为新存储名（内容字节不变，不重新编码）；
+#   2. 复制为 avatars/<哈希> 并登记 files 行（type=avatars）；
+#   3. 更新 users.avatar；
+#   4. 删除旧的 <uid>.jpg。
+# 幂等：已是 64 位十六进制哈希名的用户自动跳过；无遗留文件时无操作。
+#
+# 用法：
+#   MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_USER=blog_go MYSQL_PASSWORD=xxx \
+#   MYSQL_DB=blog_go STORAGE_DIR=/srv/blog_go [SVC_USER=blog_go] \
+#   bash scripts/migrate_legacy_avatars.sh
+set -euo pipefail
+
+: "${MYSQL_HOST:=127.0.0.1}"
+: "${MYSQL_PORT:=3306}"
+: "${MYSQL_USER:?请设置 MYSQL_USER}"
+: "${MYSQL_PASSWORD:?请设置 MYSQL_PASSWORD}"
+: "${MYSQL_DB:?请设置 MYSQL_DB}"
+: "${STORAGE_DIR:?请设置 STORAGE_DIR（存储根目录，头像位于其 avatars/ 子目录）}"
+: "${SVC_USER:=blog_go}"
+
+AVATAR_DIR="$STORAGE_DIR/avatars"
+
+mysqlq() { mysql -h"$MYSQL_HOST" -P"$MYSQL_PORT" -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DB" -N -B -e "$1"; }
+
+# 前置检查：files 表与头像目录必须存在。
+if ! mysqlq "SHOW TABLES LIKE 'files'" | grep -q files; then
+  echo "错误：数据库 $MYSQL_DB 中不存在 files 表（需先部署 files 表版本）" >&2
+  exit 1
+fi
+if [ ! -d "$AVATAR_DIR" ]; then
+  echo "错误：头像目录不存在：$AVATAR_DIR" >&2
+  exit 1
+fi
+
+migrated=0
+skipped=0
+while IFS=$'\t' read -r uid avatar; do
+  [ -n "$avatar" ] || continue
+  if [[ "$avatar" =~ ^[0-9a-f]{64}$ ]]; then
+    echo "跳过 $uid：已是哈希命名（$avatar）"
+    skipped=$((skipped + 1))
+    continue
+  fi
+  src="$AVATAR_DIR/$avatar"
+  if [ ! -f "$src" ]; then
+    echo "跳过 $uid：磁盘文件缺失 $src（不影响 URL，仅提示）"
+    skipped=$((skipped + 1))
+    continue
+  fi
+  hash=$(sha256sum "$src" | awk '{print $1}')
+  dst="$AVATAR_DIR/$hash"
+  if [ ! -f "$dst" ]; then
+    cp "$src" "$dst"
+    chown "$SVC_USER:$SVC_USER" "$dst"
+  fi
+  # 登记 files 行（幂等：同类型同哈希已存在则跳过）。
+  mysqlq "INSERT INTO files (type, article_id, session_token, uploader_id, filename, stored_name, ext, mime, size, category, created_at, updated_at, deleted_at)
+          SELECT 'avatars', 0, '', $uid, '$avatar', '$hash', '.jpg', 'image/jpeg', $(stat -c%s "$src"), 'image', NOW(3), NOW(3), NULL
+          WHERE NOT EXISTS (SELECT 1 FROM files WHERE type='avatars' AND stored_name='$hash')"
+  mysqlq "UPDATE users SET avatar='$hash' WHERE id=$uid AND avatar='$avatar'"
+  rm -f "$src"
+  echo "迁移 $uid：$avatar -> $hash"
+  migrated=$((migrated + 1))
+done < <(mysqlq "SELECT id, avatar FROM users WHERE avatar <> ''")
+
+echo "完成：迁移 $migrated 个，跳过 $skipped 个。"