fix: 迁移 attachments→files 增加内容回退策略，防重建表后 id 撞号漏搬

场景：中途部署过旧版二进制时 AutoMigrate 会把 attachments 以
id=1 重新编号；此前按 id 对齐的 NOT EXISTS 会误判已迁移，
导致新上传行静默丢失。现在第二段按 stored_name（内容 SHA-256）
补齐 id 冲突的行（省略 id 由数据库重新分配，内容已登记则跳过）。

README.md

@@ -56,11 +56,17 @@ go run .
 | Linux | `/etc/blog_go/config.yaml` | `/srv/blog_go/` |
 | Windows | `./win/etc/blog_go/config.yaml` | `./win/srv/blog_go/` |
 
+已存在的配置文件若缺少配置项（例如升级前的旧文件没有 `database` 段），启动时会自动用默认值补齐并写回。
+
 ```yaml
 # config.yaml
 database:
   type: sqlite        # sqlite（默认）或 mysql
-  dsn: ""             # MySQL 连接串，sqlite 模式下忽略
+  db_name: ""         # MySQL 数据库名，sqlite 模式下忽略
+  username: ""        # MySQL 用户名，sqlite 模式下忽略
+  password: ""        # MySQL 密码，sqlite 模式下忽略
+  host: ""            # MySQL IP 或主机名，sqlite 模式下忽略
+  port: ""            # MySQL 端口，sqlite 模式下忽略
 web:
   port: "8080"                # Web 服务端口，"" 或 "0" 可只启用 socket
   socket: ""                  # unix socket 路径（Linux 部署推荐，见 install_linux.sh）
@@ -78,7 +84,11 @@ secret: <自动生成>     # Session 加密密钥；缺失时拒绝启动
 ```yaml
 database:
   type: mysql
-  dsn: user:password@tcp(127.0.0.1:3306)/blog_go?charset=utf8mb4&parseTime=True&loc=Local
+  db_name: blog_go
+  username: user
+  password: password
+  host: 127.0.0.1
+  port: "3306"
 web:
   port: "8080"
 ```

config/config.go

@@ -3,10 +3,12 @@ package config
 import (
 	"crypto/rand"
 	"encoding/hex"
+	"fmt"
 	"log"
 	"os"
 	"path/filepath"
 	"runtime"
+	"strings"
 
 	"gopkg.in/yaml.v3"
 )
@@ -21,8 +23,20 @@ type Config struct {
 
 // DatabaseConfig 保存数据库相关配置。
 type DatabaseConfig struct {
-	Type string `yaml:"type"` // "sqlite"（默认）或 "mysql"
-	DSN  string `yaml:"dsn"`  // MySQL 连接字符串（type 为 "mysql" 时必填）
+	Type     string `yaml:"type"`     // "sqlite"（默认）或 "mysql"
+	DBName   string `yaml:"db_name"`  // 数据库名（type 为 "mysql" 时必填）
+	Username string `yaml:"username"` // 用户名（type 为 "mysql" 时必填）
+	Password string `yaml:"password"` // 密码（type 为 "mysql" 时必填）
+	Host     string `yaml:"host"`     // IP 或主机名（type 为 "mysql" 时必填）
+	Port     string `yaml:"port"`     // 端口（type 为 "mysql" 时必填）
+}
+
+// MySQLDSN 根据拆分字段构建 MySQL 连接字符串。
+func (d *DatabaseConfig) MySQLDSN() string {
+	return fmt.Sprintf(
+		"%s:%s@tcp(%s:%s)/%s?charset=utf8mb4&parseTime=True&loc=Local",
+		d.Username, d.Password, d.Host, d.Port, d.DBName,
+	)
 }
 
 // WebConfig 保存 Web 服务器监听配置。
@@ -41,8 +55,20 @@ var defaultTrustedProxies = []string{"127.0.0.1", "::1"}
 
 const defaultPort = "8080"
 
-// mysqlExampleDSN 会写入新建的配置文件，作为参考示例。
-const mysqlExampleDSN = "user:password@tcp(127.0.0.1:3306)/blog_go?charset=utf8mb4&parseTime=True&loc=Local"
+// MySQL 示例值，用于写入新建配置文件或补齐缺失的数据库段。
+const (
+	mysqlExampleDBName   = "blog_go"
+	mysqlExampleUser     = "user"
+	mysqlExamplePassword = "password"
+	mysqlExampleHost     = "127.0.0.1"
+	mysqlExamplePort     = "3306"
+)
+
+// databaseKeys / webKeys 用于检查配置文件中缺失的子键。
+var (
+	databaseKeys = []string{"type", "db_name", "username", "password", "host", "port"}
+	webKeys      = []string{"port", "socket", "trusted_proxies"}
+)
 
 // getConfigPath 返回按操作系统区分的配置目录和配置文件路径。
 func getConfigPath() (dir, file string) {
@@ -107,8 +133,12 @@ func LoadConfig(customPath string) *Config {
 
 		cfg := &Config{
 			Database: DatabaseConfig{
-				Type: "sqlite",
-				DSN:  mysqlExampleDSN,
+				Type:     "sqlite",
+				DBName:   mysqlExampleDBName,
+				Username: mysqlExampleUser,
+				Password: mysqlExamplePassword,
+				Host:     mysqlExampleHost,
+				Port:     mysqlExamplePort,
 			},
 			Web: WebConfig{
 				Port:   defaultPort,
@@ -118,14 +148,7 @@ func LoadConfig(customPath string) *Config {
 			Secret: generateSecret(),
 		}
 
-		data, err := yaml.Marshal(cfg)
-		if err != nil {
-			log.Fatalf("Failed to marshal default config: %v", err)
-		}
-
-		if err := os.WriteFile(configFile, data, 0640); err != nil {
-			log.Fatalf("Failed to write config file %s: %v", configFile, err)
-		}
+		writeConfigFile(configFile, cfg)
 		// SECURITY_TODO #11：配置文件保存会话密钥；仅允许所有者读取
 		// （install_linux.sh 已应用 0640 权限）。
 		log.Printf("Default config created at %s", configFile)
@@ -141,9 +164,84 @@ func LoadConfig(customPath string) *Config {
 	cfg := &Config{}
 	if err := yaml.Unmarshal(data, cfg); err != nil {
 		log.Printf("Warning: malformed config file %s: %v, using defaults", configFile, err)
+		return applyDefaults(cfg, defaultPath, configFile)
 	}
 
-	return applyDefaults(cfg, defaultPath, configFile)
+	cfg = applyDefaults(cfg, defaultPath, configFile)
+
+	// 检查配置文件里缺失的键（如旧版本没有 database 段），缺失项自动补全并回写。
+	if missing := missingConfigKeys(data); len(missing) > 0 {
+		fillDatabaseExamples(&cfg.Database)
+		writeConfigFile(configFile, cfg)
+		log.Printf("Config file %s was missing: %s. Added defaults.", configFile, strings.Join(missing, ", "))
+	}
+
+	return cfg
+}
+
+// writeConfigFile 以 0640 权限写入配置文件；已有文件保留原权限。
+func writeConfigFile(configFile string, cfg *Config) {
+	data, err := yaml.Marshal(cfg)
+	if err != nil {
+		log.Fatalf("Failed to marshal config: %v", err)
+	}
+	if err := os.WriteFile(configFile, data, 0640); err != nil {
+		log.Fatalf("Failed to write config file %s: %v", configFile, err)
+	}
+}
+
+// missingConfigKeys 返回配置文件中缺失的键（含顶层与 database/web 子键）。
+// 解析失败时不返回任何缺失（调用方已按 malformed 路径处理）。
+func missingConfigKeys(data []byte) []string {
+	raw := map[string]any{}
+	if err := yaml.Unmarshal(data, &raw); err != nil {
+		return nil
+	}
+	var missing []string
+	if db, ok := raw["database"].(map[string]any); ok {
+		for _, k := range databaseKeys {
+			if _, ok := db[k]; !ok {
+				missing = append(missing, "database."+k)
+			}
+		}
+	} else {
+		missing = append(missing, "database")
+	}
+	if web, ok := raw["web"].(map[string]any); ok {
+		for _, k := range webKeys {
+			if _, ok := web[k]; !ok {
+				missing = append(missing, "web."+k)
+			}
+		}
+	} else {
+		missing = append(missing, "web")
+	}
+	if _, ok := raw["path"]; !ok {
+		missing = append(missing, "path")
+	}
+	return missing
+}
+
+// fillDatabaseExamples 用示例值填充数据库段中的空字段，用于补齐缺失配置后的回写。
+func fillDatabaseExamples(d *DatabaseConfig) {
+	if d.Type == "" {
+		d.Type = "sqlite"
+	}
+	if d.DBName == "" {
+		d.DBName = mysqlExampleDBName
+	}
+	if d.Username == "" {
+		d.Username = mysqlExampleUser
+	}
+	if d.Password == "" {
+		d.Password = mysqlExamplePassword
+	}
+	if d.Host == "" {
+		d.Host = mysqlExampleHost
+	}
+	if d.Port == "" {
+		d.Port = mysqlExamplePort
+	}
 }
 
 // applyDefaults 以合理的默认值填充零值字段。

config/config_test.go

@@ -1,9 +1,13 @@
 package config
 
 import (
+	"bytes"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
+
+	"gopkg.in/yaml.v3"
 )
 
 // TestConfigFileCreatedNotWorldReadable 覆盖 SECURITY_TODO #11：
@@ -20,3 +24,118 @@ func TestConfigFileCreatedNotWorldReadable(t *testing.T) {
 		t.Fatalf("config perms = %v, want 0640", perm)
 	}
 }
+
+func TestMySQLDSN(t *testing.T) {
+	d := &DatabaseConfig{
+		DBName:   "blog_go",
+		Username: "user",
+		Password: "pass:word",
+		Host:     "127.0.0.1",
+		Port:     "3306",
+	}
+	want := "user:pass:word@tcp(127.0.0.1:3306)/blog_go?charset=utf8mb4&parseTime=True&loc=Local"
+	if got := d.MySQLDSN(); got != want {
+		t.Fatalf("MySQLDSN() = %q, want %q", got, want)
+	}
+}
+
+// TestLoadConfigFillsMissingKeys 覆盖启动时补齐缺失配置项并回写文件：
+// 旧格式配置（无 database 段）应被补全，且不覆盖已存在的 path。
+func TestLoadConfigFillsMissingKeys(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "config.yaml")
+	secret := strings.Repeat("a", 64)
+	old := "secret: " + secret + "\npath: ./data\n"
+	if err := os.WriteFile(path, []byte(old), 0640); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+
+	cfg := LoadConfig(path)
+
+	if cfg.Database.Type != "sqlite" || cfg.Database.DBName != mysqlExampleDBName ||
+		cfg.Database.Username != mysqlExampleUser || cfg.Database.Password != mysqlExamplePassword ||
+		cfg.Database.Host != mysqlExampleHost || cfg.Database.Port != mysqlExamplePort {
+		t.Fatalf("database defaults not filled: %+v", cfg.Database)
+	}
+	if cfg.Web.Port != defaultPort {
+		t.Fatalf("web port = %q, want %q", cfg.Web.Port, defaultPort)
+	}
+	if cfg.Path != "./data" {
+		t.Fatalf("path = %q, want ./data (must not be overwritten)", cfg.Path)
+	}
+
+	st, err := os.Stat(path)
+	if err != nil {
+		t.Fatalf("stat config: %v", err)
+	}
+	if perm := st.Mode().Perm(); perm != 0640 {
+		t.Fatalf("config perms = %v, want 0640", perm)
+	}
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read config: %v", err)
+	}
+	back := &Config{}
+	if err := yaml.Unmarshal(data, back); err != nil {
+		t.Fatalf("reload config: %v", err)
+	}
+	if back.Database.DBName != mysqlExampleDBName {
+		t.Fatalf("rewritten file db_name = %q, want %q", back.Database.DBName, mysqlExampleDBName)
+	}
+}
+
+// TestLoadConfigKeepsCompleteFile 覆盖配置完整时不回写文件。
+func TestLoadConfigKeepsCompleteFile(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "config.yaml")
+	content := "database:\n" +
+		"  type: mysql\n" +
+		"  db_name: myblog\n" +
+		"  username: root\n" +
+		"  password: p@ss\n" +
+		"  host: db.local\n" +
+		"  port: \"3307\"\n" +
+		"web:\n" +
+		"  port: \"8080\"\n" +
+		"  socket: \"\"\n" +
+		"  trusted_proxies:\n" +
+		"    - 127.0.0.1\n" +
+		"    - ::1\n" +
+		"path: ./data\n" +
+		"secret: " + strings.Repeat("a", 64) + "\n"
+	if err := os.WriteFile(path, []byte(content), 0640); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+
+	cfg := LoadConfig(path)
+
+	if cfg.Database.Password != "p@ss" {
+		t.Fatalf("password = %q, want p@ss (must not be overwritten)", cfg.Database.Password)
+	}
+	after, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read config: %v", err)
+	}
+	if !bytes.Equal(after, []byte(content)) {
+		t.Fatalf("complete config file was rewritten:\n%s", after)
+	}
+}
+
+// TestLoadConfigMalformedNoRewrite 覆盖解析失败的配置文件不被回写。
+func TestLoadConfigMalformedNoRewrite(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "config.yaml")
+	// web.port 为序列不能解码到 string，yaml.Unmarshal 报错。
+	content := "secret: " + strings.Repeat("a", 64) + "\nweb:\n  port: [8080]\n"
+	if err := os.WriteFile(path, []byte(content), 0640); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+
+	LoadConfig(path)
+
+	after, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatalf("read config: %v", err)
+	}
+	if !bytes.Equal(after, []byte(content)) {
+		t.Fatalf("malformed config was rewritten:\n%s", after)
+	}
+}

handlers/attachment.go

@@ -76,6 +76,8 @@ func canManageArticle(c *gin.Context, db *gorm.DB, articleID uint) bool {
 // UploadAttachment 处理来自文章创建/编辑表单的 AJAX 附件上传。
 // 请求携带真实的 article_id（编辑页）或 session_token（创建页，待绑定）。
 // 文件按 SHA-256 内容寻址，实现磁盘去重。
+//
+// 记录写入全站统一的 files 表（Type=attachments），与历史数据同属一个表。
 func UploadAttachment(db *gorm.DB, storagePath string) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		uploaderID, ok := sessionAuthorID(c)
@@ -152,7 +154,8 @@ func UploadAttachment(db *gorm.DB, storagePath string) gin.HandlerFunc {
 		}
 
 		ext := strings.ToLower(filepath.Ext(header.Filename))
-		att := models.Attachment{
+		att := models.File{
+			Type:         models.FileTypeAttachment,
 			ArticleID:    articleID,
 			SessionToken: token,
 			UploaderID:   uploaderID,
@@ -181,14 +184,14 @@ func UploadAttachment(db *gorm.DB, storagePath string) gin.HandlerFunc {
 
 // ---------------- 删除 ----------------
 
-// DeleteAttachment 软删除附件记录，仅当没有其余记录引用时才删除磁盘文件
-// （引用计数，因为内容寻址的文件可能被共享）。只有管理员、上传者或
-// 文件所在文章的作者可以删除。
+// DeleteAttachment 软删除附件记录（files 表，Type=attachments），仅当
+// 没有其余记录引用时才删除磁盘文件（引用计数，因为内容寻址的文件可能
+// 被共享）。只有管理员、上传者或文件所在文章的作者可以删除。
 func DeleteAttachment(db *gorm.DB, storagePath string) gin.HandlerFunc {
 	return func(c *gin.Context) {
 		id := parseUintParam(c, "id")
-		var att models.Attachment
-		if err := db.First(&att, id).Error; err != nil {
+		var att models.File
+		if err := db.First(&att, "id = ? AND type = ?", id, models.FileTypeAttachment).Error; err != nil {
 			c.JSON(http.StatusNotFound, gin.H{"error": "not found"})
 			return
 		}
@@ -214,7 +217,7 @@ func DeleteAttachment(db *gorm.DB, storagePath string) gin.HandlerFunc {
 
 		// 引用计数：还有任何其他（未删除）行指向此文件吗？
 		var count int64
-		db.Model(&models.Attachment{}).Where("stored_name = ?", stored).Count(&count)
+		db.Model(&models.File{}).Where("stored_name = ? AND type = ?", stored, models.FileTypeAttachment).Count(&count)
 		if count == 0 {
 			os.Remove(filepath.Join(attachmentsDir(storagePath), stored)) // 忽略错误
 		}
@@ -225,6 +228,7 @@ func DeleteAttachment(db *gorm.DB, storagePath string) gin.HandlerFunc {
 // ---------------- 列表 ----------------
 
 // ListAttachments 以 JSON 返回文章的附件（供编辑页加载时重新填充列表）。
+// 只读取 files 表中 Type=attachments 的记录。
 // 只有文章作者（或管理员）可以列出。
 func ListAttachments(db *gorm.DB) gin.HandlerFunc {
 	return func(c *gin.Context) {
@@ -237,8 +241,9 @@ func ListAttachments(db *gorm.DB) gin.HandlerFunc {
 			c.JSON(http.StatusForbidden, gin.H{"error": "forbidden"})
 			return
 		}
-		var atts []models.Attachment
-		db.Where("article_id = ?", articleID).Order("created_at ASC").Find(&atts)
+		var atts []models.File
+		db.Where("article_id = ? AND type = ?", articleID, models.FileTypeAttachment).
+			Order("created_at ASC").Find(&atts)
 
 		out := make([]gin.H, 0, len(atts))
 		for _, a := range atts {
@@ -264,8 +269,8 @@ func BindPendingAttachments(db *gorm.DB, token string, articleID uint) error {
 	if token == "" {
 		return nil
 	}
-	return db.Model(&models.Attachment{}).
-		Where("session_token = ? AND article_id = 0", token).
+	return db.Model(&models.File{}).
+		Where("session_token = ? AND article_id = 0 AND type = ?", token, models.FileTypeAttachment).
 		Updates(map[string]interface{}{"article_id": articleID, "session_token": ""}).Error
 }
 

handlers/bodylimit_test.go

@@ -91,7 +91,7 @@ func TestBodyLimitRejectsOversizedMultipart(t *testing.T) {
 	}
 
 	var count int64
-	e.db.Model(&models.Attachment{}).Where("filename = ?", "big.txt").Count(&count)
+	e.db.Model(&models.File{}).Where("filename = ?", "big.txt").Count(&count)
 	if count != 0 {
 		t.Fatalf("oversized multipart created %d attachment rows, want 0", count)
 	}

handlers/security_test.go

@@ -47,7 +47,7 @@ func newSecurityTestEnv(t *testing.T) *securityTestEnv {
 	if err != nil {
 		t.Fatalf("open sqlite: %v", err)
 	}
-	if err := db.AutoMigrate(&models.User{}, &models.Article{}, &models.Attachment{}, &models.SiteSetting{},
+	if err := db.AutoMigrate(&models.User{}, &models.Article{}, &models.File{}, &models.SiteSetting{},
 		&models.UploadConfig{}, &models.UploadFileType{}, &models.CommentConfig{}, &models.NavLink{},
 		&models.DownloadBaseURL{}, &models.Comment{}); err != nil {
 		t.Fatalf("migrate: %v", err)
@@ -439,7 +439,7 @@ func TestAttachmentDeleteRequiresOwnership(t *testing.T) {
 		t.Fatalf("upload (bob): status = %d, body %s", w.Code, w.Body.String())
 	}
 
-	var bobAtt models.Attachment
+	var bobAtt models.File
 	if err := e.db.Where("uploader_id = ?", userIDByUsername(t, e.db, "bob")).First(&bobAtt).Error; err != nil {
 		t.Fatalf("bob attachment not found: %v", err)
 	}
@@ -458,7 +458,7 @@ func TestAttachmentDeleteRequiresOwnership(t *testing.T) {
 
 	// Bob 的附件记录应该已删除。
 	var count int64
-	e.db.Model(&models.Attachment{}).Where("id = ?", bobAtt.ID).Count(&count)
+	e.db.Model(&models.File{}).Where("id = ?", bobAtt.ID).Count(&count)
 	if count != 0 {
 		t.Fatal("attachment was not deleted")
 	}

install_linux.sh

@@ -53,7 +53,11 @@ if [[ ! -f "${CONFIG_DIR}/config.yaml" ]]; then
   cat > "${CONFIG_DIR}/config.yaml" <<EOF
 database:
     type: sqlite
-    dsn: ""
+    db_name: ""
+    username: ""
+    password: ""
+    host: ""
+    port: ""
 web:
     port: "8080"
     socket: ${SOCKET_PATH}

models/db.go

@@ -2,6 +2,7 @@ package models
 
 import (
 	"crypto/rand"
+	"errors"
 	"log"
 	"os"
 	"path/filepath"
@@ -36,6 +37,26 @@ func randomAdminPassword() string {
 	return string(out)
 }
 
+// validateMySQLConfig 校验 MySQL 连接所需字段均非空。
+func validateMySQLConfig(d *config.DatabaseConfig) error {
+	if d.DBName == "" {
+		return errors.New("'db_name' is required when type is 'mysql'")
+	}
+	if d.Username == "" {
+		return errors.New("'username' is required when type is 'mysql'")
+	}
+	if d.Password == "" {
+		return errors.New("'password' is required when type is 'mysql'")
+	}
+	if d.Host == "" {
+		return errors.New("'host' is required when type is 'mysql'")
+	}
+	if d.Port == "" {
+		return errors.New("'port' is required when type is 'mysql'")
+	}
+	return nil
+}
+
 // InitDB 打开数据库连接、执行迁移并初始化管理员用户。
 func InitDB(cfg *config.Config) *gorm.DB {
 	// 确保存储目录存在。
@@ -47,10 +68,10 @@ func InitDB(cfg *config.Config) *gorm.DB {
 
 	switch cfg.Database.Type {
 	case "mysql":
-		if cfg.Database.DSN == "" {
-			log.Fatalf("Database DSN is required when type is 'mysql'. Please set it in your config file.")
+		if err := validateMySQLConfig(&cfg.Database); err != nil {
+			log.Fatalf("Invalid MySQL config: %v", err)
 		}
-		dialector = mysql.Open(cfg.Database.DSN)
+		dialector = mysql.Open(cfg.Database.MySQLDSN())
 	default:
 		dbPath := filepath.Join(cfg.Path, "blog.db")
 		dialector = sqlite.Open(dbPath)
@@ -63,11 +84,16 @@ func InitDB(cfg *config.Config) *gorm.DB {
 		log.Fatalf("Failed to connect to database: %v", err)
 	}
 
-	// 自动迁移数据表（幂等操作）。
-	if err := db.AutoMigrate(&User{}, &Article{}, &SiteSetting{}, &UploadConfig{}, &UploadFileType{}, &DownloadBaseURL{}, &Attachment{}, &Comment{}, &CommentConfig{}, &ArticleView{}, &NavLink{}, &Tag{}, &ArticleTag{}); err != nil {
+	// 自动迁移数据表（幂等操作）。attachments 旧表已由 files 替代，
+	// 不再参与迁移；历史数据在下方 migrateAttachmentsToFiles 中一次性搬运。
+	if err := db.AutoMigrate(&User{}, &Article{}, &SiteSetting{}, &UploadConfig{}, &UploadFileType{}, &DownloadBaseURL{}, &File{}, &Comment{}, &CommentConfig{}, &ArticleView{}, &NavLink{}, &Tag{}, &ArticleTag{}); err != nil {
 		log.Fatalf("Failed to auto-migrate database: %v", err)
 	}
 
+	// 数据迁移：attachments → 全站统一 files 表（type='attachments'），幂等。
+	// 仅当旧表仍存在时执行（已删除则为无操作），保证升级路径上的数据不丢。
+	migrateAttachmentsToFiles(db)
+
 	// 首次运行时初始化站点平台配置。
 	seedSiteSettings(db)
 	seedUploadConfig(db)
@@ -111,3 +137,55 @@ func InitDB(cfg *config.Config) *gorm.DB {
 	DB = db
 	return db
 }
+
+// migrateAttachmentsToFiles 将旧 attachments 表中的历史数据复制到统一的
+// files 表，type 一律标记为 "attachments"。仅当 attachments 表仍存在时
+// 执行——新安装从未创建过该表，而已经切换的部署会将其删除。
+//
+// 幂等与异常恢复策略：
+//  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)
+SELECT
+	a.id, '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 NOT EXISTS (SELECT 1 FROM files f WHERE f.id = a.id)`)
+	if res.Error != nil {
+		log.Printf("Migration attachments -> files failed: %v", res.Error)
+		return
+	}
+	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

@@ -6,7 +6,9 @@ import (
 	"gorm.io/gorm"
 )
 
-// Attachment 表示附加到文章的文件。
+// File 是全站统一的上传文件登记表，用于管理所有类型的上传文件
+// （附件、头像、Logo 等）。字段与原 attachments 表对齐，额外通过
+// Type 字段区分文件归属类型。
 //
 // 生命周期（方案 A——先上传后绑定）：
 //   - 在文章创建页面上文章尚不存在，因此 ArticleID 为 0，
@@ -17,29 +19,33 @@ import (
 //
 // 磁盘去重：StoredName 是文件内容的 SHA-256。写入前，
 // 处理器会检查磁盘上是否已存在同名文件；若已存在则复用（不重写）。
-// 删除采用引用计数——仅当没有任何 Attachment 行引用时，才删除磁盘文件。
-type Attachment struct {
+// 删除采用引用计数——仅当没有任何 File 行引用时，才删除磁盘文件。
+type File struct {
 	ID           uint           `gorm:"primarykey" json:"id"`
-	ArticleID    uint           `gorm:"index" json:"article_id"`        // 在创建页面上待绑定时为 0
-	SessionToken string         `gorm:"size:64;index" json:"-"`         // 创建页面上的临时归属令牌
+	Type         string         `gorm:"size:32;index;default:attachments" json:"type"` // 归属类型：attachment 等
+	ArticleID    uint           `gorm:"index" json:"article_id"`                       // 在创建页面上待绑定时为 0
+	SessionToken string         `gorm:"size:64;index" json:"-"`                        // 创建页面上的临时归属令牌
 	UploaderID   uint           `gorm:"index" json:"uploader_id"`
-	Filename     string         `gorm:"size:255" json:"filename"`        // 原始文件名
-	StoredName   string         `gorm:"size:64;index" json:"stored_name"` // SHA-256 十六进制字符串，磁盘文件名
+	Filename     string         `gorm:"size:255" json:"filename"`                      // 原始文件名
+	StoredName   string         `gorm:"size:64;index" json:"stored_name"`              // SHA-256 十六进制字符串，磁盘文件名
 	Ext          string         `gorm:"size:32" json:"ext"`
 	MIME         string         `gorm:"size:128" json:"mime"`
 	Size         int64          `gorm:"default:0" json:"size"`
-	Category     string         `gorm:"size:32" json:"category"`        // image/document/archive/video/other
+	Category     string         `gorm:"size:32" json:"category"` // image/document/archive/video/other
 	CreatedAt    time.Time      `json:"created_at"`
 	UpdatedAt    time.Time      `json:"updated_at"`
 	DeletedAt    gorm.DeletedAt `gorm:"index" json:"deleted_at"`
 }
 
 // TableName 覆盖 GORM 默认的表名。
-func (Attachment) TableName() string {
-	return "attachments"
+func (File) TableName() string {
+	return "files"
 }
 
-// IsImage 报告该附件是否为图片（用于决定 Markdown 插入形式：![]() 还是 []()）。
-func (a *Attachment) IsImage() bool {
-	return a.Category == CategoryImage
+// FileTypeAttachment 是文件归属类型常量：文章附件（原 attachments 表历史数据）。
+const FileTypeAttachment = "attachments"
+
+// IsImage 报告该文件是否为图片（用于决定 Markdown 插入形式：![]() 还是 []()）。
+func (f *File) IsImage() bool {
+	return f.Category == CategoryImage
 }

scripts/add_files_table.sql

@@ -0,0 +1,39 @@
+-- Migration: 新增全站统一上传文件表 files，并把 attachments 数据迁入（type='attachments'）
+-- Date: 2026-08-28
+-- Description: files 表用于管理全站所有上传文件（附件/头像/Logo 等），
+--              Type 字段区分归属类型；attachments 历史数据逐行复制，type 填 'attachments'。
+-- 幂等：表用 IF NOT EXISTS，数据按主键 id 对齐跳过已迁移行，可重复执行。
+
+-- 1) 建表（与 GORM AutoMigrate 输出一致）
+CREATE TABLE IF NOT EXISTS `files` (
+  `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,
+  `type` varchar(32) DEFAULT 'attachments',
+  `article_id` bigint(20) unsigned DEFAULT NULL,
+  `session_token` varchar(64) DEFAULT NULL,
+  `uploader_id` bigint(20) unsigned DEFAULT NULL,
+  `filename` varchar(255) DEFAULT NULL,
+  `stored_name` varchar(64) DEFAULT NULL,
+  `ext` varchar(32) DEFAULT NULL,
+  `mime` varchar(128) DEFAULT NULL,
+  `size` bigint(20) DEFAULT 0,
+  `category` varchar(32) DEFAULT NULL,
+  `created_at` datetime(3) DEFAULT NULL,
+  `updated_at` datetime(3) DEFAULT NULL,
+  `deleted_at` datetime(3) DEFAULT NULL,
+  PRIMARY KEY (`id`),
+  KEY `idx_files_type` (`type`),
+  KEY `idx_files_article_id` (`article_id`),
+  KEY `idx_files_session_token` (`session_token`),
+  KEY `idx_files_uploader_id` (`uploader_id`),
+  KEY `idx_files_stored_name` (`stored_name`),
+  KEY `idx_files_deleted_at` (`deleted_at`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+
+-- 2) 数据迁移：attachments 全部行（含软删除）复制进 files，type='attachments'
+INSERT INTO `files`
+  (`id`,`type`,`article_id`,`session_token`,`uploader_id`,`filename`,`stored_name`,`ext`,`mime`,`size`,`category`,`created_at`,`updated_at`,`deleted_at`)
+SELECT
+  a.`id`, '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 NOT EXISTS (SELECT 1 FROM `files` f WHERE f.`id` = a.`id`);

scripts/drop_attachments_table.sql

@@ -0,0 +1,11 @@
+-- Migration: 删除旧 attachments 表（数据已迁移至统一 files 表，type='attachments'）
+-- Date: 2026-08-28
+-- 前置条件：已部署使用 files 表的新版 blog_go 并完成验证（启动迁移会把
+--           尚未搬运的 attachments 行复制进 files）。本脚本幂等，可安全重跑。
+--
+-- 执行前确认：
+--   SELECT COUNT(*) AS remaining FROM attachments a
+--   WHERE NOT EXISTS (SELECT 1 FROM files f WHERE f.id = a.id);
+-- 结果应为 0——若有遗留行，先重启新版本服务让其自动搬运。
+
+DROP TABLE IF EXISTS `attachments`;

templates/admin/article_create.html

@@ -120,6 +120,7 @@
 <script>
 var easyMDE = new EasyMDE({
     element: document.getElementById('articleContent'),
+    autoDownloadFontAwesome: false,
     spellChecker: false,
     autosave: { enabled: false },
     placeholder: '{{index .Tr "article_content"}}',

templates/layouts/base.html

@@ -20,6 +20,7 @@
     <link rel="stylesheet" href="/static/vendor/cropper.min.css?v=1">
     <script src="/static/vendor/cropper.min.js?v=1"></script>
     <link rel="stylesheet" href="/static/vendor/easymde.min.css?v=1">
+    <link rel="stylesheet" href="/static/vendor/font-awesome/4.7.0/css/font-awesome.min.css?v=1">
     <script src="/static/vendor/easymde.min.js?v=1"></script>
 </head>
 <body class="bg-gray-50 min-h-screen flex flex-col">

templates/user/my_article_form.html

@@ -84,6 +84,7 @@ var myEasyMDE = null;
 document.addEventListener('DOMContentLoaded', function() {
     myEasyMDE = new EasyMDE({
         element: document.getElementById('content'),
+        autoDownloadFontAwesome: false,
         spellChecker: false,
         status: false,
         previewRender: function (plainText, preview) {