fix(migrate): 目标库缺少 mailbox_states 表时自动建表（兼容上游模型未含 MailboxState 的场景）

- Attachment 模型移除 Message 关联：其 foreignKey 名 MessageID 与
  Message.MessageID 字符串字段冲突，GORM AutoMigrate 会生成错误外键
  （messages.message_id → attachments.id 且强转 bigint），MySQL 下建表
  直接失败（SQLite 因动态类型侥幸可用）
- Message.TextBody/HtmlBody 改 mediumtext：MySQL TEXT 仅 64KB，
  大 HTML 邮件会写入失败
- 新增 cmd/migrate：SQLite → MySQL 一次性迁移工具（GORM 模型读源、
  批量写目标、时间统一 UTC、ban_entries 零值时间转 NULL、逐表校验）

.gitignore

@@ -40,3 +40,4 @@ win/srv/
 
 # 临时测试文件
 login_test.html
+migrate

cmd/migrate/main.go

@@ -0,0 +1,260 @@
+// migrate 一次性工具：把 SQLite 数据迁移到 MySQL（mailgo 库）。
+// 用法：go run ./cmd/migrate -from /srv/mail_go/mail.db -dsn "mailgo:密码@tcp(127.0.0.1:3306)/mailgo?charset=utf8mb4&parseTime=True&loc=UTC"
+package main
+
+import (
+	"flag"
+	"fmt"
+	"log"
+	"time"
+
+	"mail_go/config"
+	"mail_go/internal/db"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/logger"
+)
+
+var (
+	fromDSN = flag.String("from", "/srv/mail_go/mail.db", "SQLite 数据库路径")
+	mysqlDSN = flag.String("dsn", "", "MySQL DSN（目标库，需已创建 mailgo 库与用户）")
+)
+
+func main() {
+	flag.Parse()
+	if *mysqlDSN == "" {
+		log.Fatal("缺少 -dsn")
+	}
+
+	// 目标：MySQL（InitDB 内含 AutoMigrate，按当前模型建表）
+	mdb, err := db.InitDB(config.DatabaseConfig{Driver: "mysql", DSN: *mysqlDSN}, config.StorageConfig{BaseDir: "/srv/mail_go/"})
+	if err != nil {
+		log.Fatalf("连接 MySQL 失败: %v", err)
+	}
+	log.Println("MySQL 建表完成（AutoMigrate）")
+
+	// 源：SQLite（只读）
+	sdb, err := db.InitDB(config.DatabaseConfig{Driver: "sqlite", DSN: *fromDSN}, config.StorageConfig{BaseDir: "/srv/mail_go/"})
+	if err != nil {
+		log.Fatalf("连接 SQLite 失败: %v", err)
+	}
+	sdb.Logger = logger.Default.LogMode(logger.Silent)
+
+	// 关闭 GORM 自动时间戳（保留原始 CreatedAt/UpdatedAt）
+	mw := mdb.Session(&gorm.Session{SkipHooks: true})
+
+	stateWant := int64(-1) // mailbox_states 期望行数；-1 = 源库无此表不校验
+
+	// 按外键依赖顺序复制：domains → users → messages → attachments → 其余
+	// 所有时间统一 UTC（MySQL DATETIME 无时区）。
+	utc := func(t time.Time) time.Time {
+		if t.IsZero() {
+			// MySQL DATETIME 最小年份 1000；零值由调用方转 NULL
+			return t
+		}
+		return t.UTC()
+	}
+	_ = utc
+
+	// ---- domains ----
+	var domains []db.Domain
+	if err := sdb.Order("id").Find(&domains).Error; err != nil {
+		log.Fatalf("读 domains: %v", err)
+	}
+	for i := range domains {
+		domains[i].CreatedAt = domains[i].CreatedAt.UTC()
+		domains[i].UpdatedAt = domains[i].UpdatedAt.UTC()
+	}
+	if err := mw.Create(&domains).Error; err != nil {
+		log.Fatalf("写 domains: %v", err)
+	}
+	log.Printf("domains: %d", len(domains))
+
+	// ---- users ----
+	var users []db.User
+	if err := sdb.Order("id").Find(&users).Error; err != nil {
+		log.Fatalf("读 users: %v", err)
+	}
+	for i := range users {
+		users[i].CreatedAt = users[i].CreatedAt.UTC()
+		users[i].UpdatedAt = users[i].UpdatedAt.UTC()
+	}
+	if err := mw.Create(&users).Error; err != nil {
+		log.Fatalf("写 users: %v", err)
+	}
+	log.Printf("users: %d", len(users))
+
+	// ---- messages ----
+	var msgs []db.Message
+	if err := sdb.Order("id").Find(&msgs).Error; err != nil {
+		log.Fatalf("读 messages: %v", err)
+	}
+	for i := range msgs {
+		msgs[i].Date = msgs[i].Date.UTC()
+		msgs[i].CreatedAt = msgs[i].CreatedAt.UTC()
+	}
+	if err := mw.Create(&msgs).Error; err != nil {
+		log.Fatalf("写 messages: %v", err)
+	}
+	log.Printf("messages: %d", len(msgs))
+
+	// ---- attachments ----
+	var atts []db.Attachment
+	if err := sdb.Order("id").Find(&atts).Error; err != nil {
+		log.Fatalf("读 attachments: %v", err)
+	}
+	for i := range atts {
+		atts[i].CreatedAt = atts[i].CreatedAt.UTC()
+	}
+	if err := mw.Create(&atts).Error; err != nil {
+		log.Fatalf("写 attachments: %v", err)
+	}
+	log.Printf("attachments: %d", len(atts))
+
+	// ---- outbound_messages（原样，含时间转 UTC）----
+	var outs []db.OutboundMessage
+	if err := sdb.Order("id").Find(&outs).Error; err != nil {
+		log.Fatalf("读 outbound_messages: %v", err)
+	}
+	for i := range outs {
+		outs[i].NextAttemptAt = outs[i].NextAttemptAt.UTC()
+		if outs[i].CompletedAt != nil && !outs[i].CompletedAt.IsZero() {
+			u := outs[i].CompletedAt.UTC()
+			outs[i].CompletedAt = &u
+		}
+		outs[i].CreatedAt = outs[i].CreatedAt.UTC()
+		outs[i].UpdatedAt = outs[i].UpdatedAt.UTC()
+	}
+	if err := mw.Create(&outs).Error; err != nil {
+		log.Fatalf("写 outbound_messages: %v", err)
+	}
+	log.Printf("outbound_messages: %d", len(outs))
+
+	// ---- ban_entries（expires_at 零值 → NULL）----
+	rows, err := sdb.Raw("SELECT id, ip_address, reason, fail_count, ban_count, expires_at, created_at, updated_at FROM ban_entries ORDER BY id").Rows()
+	if err != nil {
+		log.Fatalf("读 ban_entries: %v", err)
+	}
+	defer rows.Close()
+	bans := 0
+	for rows.Next() {
+		var (
+			id        uint
+			ip        string
+			reason    *string
+			failCount int
+			banCount  int
+			expires   *time.Time
+			created   *time.Time
+			updated   *time.Time
+		)
+		if err := rows.Scan(&id, &ip, &reason, &failCount, &banCount, &expires, &created, &updated); err != nil {
+			log.Fatalf("扫 ban_entries: %v", err)
+		}
+		norm := func(t *time.Time) *time.Time {
+			if t == nil || t.IsZero() {
+				return nil
+			}
+			u := t.UTC()
+			return &u
+		}
+		if err := mdb.Exec("INSERT INTO ban_entries (id, ip_address, reason, fail_count, ban_count, expires_at, created_at, updated_at) VALUES (?,?,?,?,?,?,?,?)",
+			id, ip, reason, failCount, banCount, norm(expires), norm(created), norm(updated)).Error; err != nil {
+			log.Fatalf("写 ban_entries id=%d: %v", id, err)
+		}
+		bans++
+	}
+	log.Printf("ban_entries: %d", bans)
+
+	// ---- protocol_logs ----
+	var logs []db.ProtocolLog
+	if err := sdb.Order("id").Find(&logs).Error; err != nil {
+		log.Fatalf("读 protocol_logs: %v", err)
+	}
+	for i := range logs {
+		logs[i].CreatedAt = logs[i].CreatedAt.UTC()
+	}
+	if err := mw.Create(&logs).Error; err != nil {
+		log.Fatalf("写 protocol_logs: %v", err)
+	}
+	log.Printf("protocol_logs: %d", len(logs))
+
+	// ---- mailbox_states（原生 SQL：该表随 UIDVALIDITY 特性存在，旧版本源库可能没有）----
+	var stateCount int64
+	sdb.Raw("SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name='mailbox_states'").Scan(&stateCount)
+	if stateCount > 0 {
+		// 目标库若没有该表（上游模型未含 MailboxState 时 AutoMigrate 不会建），先建表
+		var tcnt int64
+		mdb.Raw("SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name = 'mailbox_states'").Scan(&tcnt)
+		if tcnt == 0 {
+			if err := mdb.Exec(`CREATE TABLE mailbox_states (
+				user_id bigint unsigned NOT NULL,
+				folder varchar(64) NOT NULL,
+				uid_validity bigint unsigned NOT NULL,
+				created_at datetime(3) NULL,
+				updated_at datetime(3) NULL,
+				PRIMARY KEY (user_id, folder))`).Error; err != nil {
+				log.Fatalf("建 mailbox_states 表: %v", err)
+			}
+			log.Println("mailbox_states: 目标库已建表")
+		}
+		srows, err := sdb.Raw("SELECT user_id, folder, uid_validity, created_at, updated_at FROM mailbox_states ORDER BY user_id, folder").Rows()
+		if err != nil {
+			log.Fatalf("读 mailbox_states: %v", err)
+		}
+		defer srows.Close()
+		states := 0
+		for srows.Next() {
+			var (
+				userID   uint
+				folder   string
+				validity uint32
+				created  *time.Time
+				updated  *time.Time
+			)
+			if err := srows.Scan(&userID, &folder, &validity, &created, &updated); err != nil {
+				log.Fatalf("扫 mailbox_states: %v", err)
+			}
+			norm := func(t *time.Time) *time.Time {
+				if t == nil || t.IsZero() {
+					return nil
+				}
+				u := t.UTC()
+				return &u
+			}
+			if err := mdb.Exec("INSERT INTO mailbox_states (user_id, folder, uid_validity, created_at, updated_at) VALUES (?,?,?,?,?)",
+				userID, folder, validity, norm(created), norm(updated)).Error; err != nil {
+				log.Fatalf("写 mailbox_states: %v", err)
+			}
+			states++
+		}
+		log.Printf("mailbox_states: %d", states)
+		stateWant = int64(states)
+	} else {
+		log.Println("mailbox_states: 源库无此表，跳过")
+	}
+
+	// ---- 校验 ----
+	check := func(table string, want int64) {
+		var got int64
+		if err := mdb.Table(table).Count(&got).Error; err != nil {
+			log.Fatalf("校验 %s: %v", table, err)
+		}
+		if got != want {
+			log.Fatalf("校验 %s 失败: got %d want %d", table, got, want)
+		}
+		fmt.Printf("校验 %s: %d/%d ✓\n", table, got, want)
+	}
+	check("domains", int64(len(domains)))
+	check("users", int64(len(users)))
+	check("messages", int64(len(msgs)))
+	check("attachments", int64(len(atts)))
+	check("outbound_messages", int64(len(outs)))
+	check("ban_entries", int64(bans))
+	check("protocol_logs", int64(len(logs)))
+	if stateWant >= 0 {
+		check("mailbox_states", stateWant)
+	}
+
+	log.Println("迁移完成 ✅")
+}

internal/db/models.go

@@ -60,8 +60,8 @@ type Message struct {
 	ToAddr    string    `gorm:"size:2048;not null" json:"to_addr"`
 	CcAddr    string    `gorm:"size:2048" json:"cc_addr"`
 	Subject   string    `gorm:"size:1024" json:"subject"`
-	TextBody  string    `gorm:"type:text" json:"text_body"`
-	HtmlBody  string    `gorm:"type:text" json:"html_body"`
+	TextBody  string    `gorm:"type:mediumtext" json:"text_body"`
+	HtmlBody  string    `gorm:"type:mediumtext" json:"html_body"`
 	RawData   string    `gorm:"type:mediumtext" json:"raw_data"`
 	IsRead    bool      `gorm:"default:false" json:"is_read"`
 	IsFlagged bool      `gorm:"default:false" json:"is_flagged"`
@@ -155,10 +155,11 @@ func (ProtocolLog) TableName() string {
 }
 
 // Attachment represents a file attached to an email message.
+// 注意：不声明 Message 关联（避免 GORM 外键名 MessageID 与
+// Message.MessageID 字符串字段冲突，导致 AutoMigrate 生成错误外键）。
 type Attachment struct {
 	ID          uint      `gorm:"primaryKey" json:"id"`
 	MessageID   uint      `gorm:"index;not null" json:"message_id"`
-	Message     Message   `gorm:"foreignKey:MessageID" json:"message"`
 	FileName    string    `gorm:"size:255;not null" json:"file_name"`
 	FilePath    string    `gorm:"size:512;not null" json:"file_path"`
 	ContentType string    `gorm:"size:128" json:"content_type"`

internal/imap_server/backend.go

@@ -461,6 +461,15 @@ func (m *imapMailbox) buildIMAPMessage(dbMsg *db.Message, seqNum uint32, items [
 			if err == nil {
 				imapMsg.BodyStructure, _ = backendutil.FetchBodyStructure(hdr, body, item == imap.FetchBodyStructure)
 			}
+			// 防御：FetchBodyStructure 对部分合法/畸形 MIME 会失败并返回
+			// nil（典型：message/rfc822 附件为 base64 编码时库内不解码
+			// 直接按嵌套消息解析头；或 multipart 边界截断）。BodyStructure
+			// 为 nil 时 go-imap 格式化 FETCH 响应会在 send() 协程 panic
+			// （nil 指针解引用），连接中断导致客户端只收到部分邮件甚至
+			// 一直卡在同步。解析失败时降级为 text/plain 单段结构。
+			if imapMsg.BodyStructure == nil {
+				imapMsg.BodyStructure = fallbackBodyStructure(rawMsg)
+			}
 		default:
 			section, err := imap.ParseBodySectionName(item)
 			if err != nil {
@@ -471,13 +480,33 @@ func (m *imapMailbox) buildIMAPMessage(dbMsg *db.Message, seqNum uint32, items [
 				return nil, err
 			}
 			literal, _ := backendutil.FetchBodySection(hdr, body, section)
-			imapMsg.Body[section] = literal
+			if literal != nil {
+				imapMsg.Body[section] = literal
+			}
 		}
 	}
 
 	return imapMsg, nil
 }
 
+// fallbackBodyStructure 构造一个 text/plain 单段 BodyStructure，用于
+// MIME 解析失败的消息（保证 FETCH BODY/BODYSTRUCTURE 不因 nil 崩溃）。
+func fallbackBodyStructure(raw []byte) *imap.BodyStructure {
+	size := uint32(len(raw))
+	lines := uint32(bytes.Count(raw, []byte{'\n'}))
+	if len(raw) > 0 && raw[len(raw)-1] != '\n' {
+		lines++
+	}
+	return &imap.BodyStructure{
+		MIMEType:    "text",
+		MIMESubType: "plain",
+		Params:      map[string]string{"charset": "utf-8"},
+		Encoding:    "8bit",
+		Size:        size,
+		Lines:       lines,
+	}
+}
+
 func messageRawData(msg *db.Message) []byte {
 	if msg.RawData != "" {
 		return []byte(msg.RawData)

internal/imap_server/integration_test.go

@@ -188,3 +188,95 @@ func TestSeqStoreClientSelfNumbered(t *testing.T) {
 	// 客户端意图是标记最新一封（ids[2]）为已读
 	assertReadState(t, stores, ids[2], true)
 }
+
+// TestFetchBodyMalformedMIME 回归：消息包含无法解析的 MIME（base64 编码的
+// message/rfc822 附件 / 截断的 multipart）时，FETCH BODY/BODYSTRUCTURE
+// 不得因 nil BodyStructure 触发服务器 panic（否则连接中断，客户端只收到
+// 部分邮件或一直卡在同步）。修复前 go-imap send() 协程会 nil 指针崩溃。
+func TestFetchBodyMalformedMIME(t *testing.T) {
+	stores, addr := startIntegrationServer(t)
+
+	// 1) base64 编码的 message/rfc822 附件（转发邮件场景）：
+	//    backendutil.FetchBodyStructure 不解码 base64，直接把编码文本
+	//    当嵌套消息头解析 → "malformed MIME header line" 错误。
+	rfc822Body := "UmVjZWl2ZWQ6IGZyb20gb3V0Ym91bmQuY2kuaWNsb3VkLmNvbSAodW5rbm93biBbMTI3LjAuMC4yKVxuXHQgYnkgcDAwLWljbG91ZG10YS1hc210cC11cy1jZW50cmFsLTFrLTEwMC1wZXJjZW50LTggKFBvc3RmaXgpIHdpdGggRVNNVFBTIGlkIDIxRTlBMThDQURDRjM4MlxuXHQgZm9yIDxkc2hAbG12ZS5uZXQ+OyBTdW4sIDE2IEF1ZyAyMDI2IDEzOjU4OjIxICswMDAwIChVVEMpXG5YLUlDTC1SZXBJZDogRURWY1BlQ3RlWG4tZ0Z1T0xxUWhfSjZvcE9fN1B2OEtsOW1mMDg2VUFxZ29zXG5EYXRlOiBTdW4sIDE2IEF1ZyAyMDI2IDEzOjU4OjIxICswMDAwXG5Gcm9tOiBkYXZpZEB5YW5kZXguY29tXG5UbzogZHNoQGxtdmUubmV0XG5NZXNzYWdlLUlEOiA8QTIxNzBEMTEtMkI1MC00MTQwLTlEQTMtMkI3M0U2RUIwQTc4QHlhbmRleC5jb20+XG5TdWJqZWN0OiB0ZXN0XG5cbmhlbGxvXG4="
+	msgWithRFC822 := &db.Message{
+		UserID:   1,
+		Folder:   "INBOX",
+		FromAddr: "alice@example.com",
+		ToAddr:   "alice@example.com",
+		Subject:  "fwd",
+		Date:     time.Now().Add(-2 * time.Hour),
+		RawData: "From: alice@example.com\r\n" +
+			"To: alice@example.com\r\n" +
+			"Subject: fwd\r\n" +
+			"MIME-Version: 1.0\r\n" +
+			"Content-Type: multipart/mixed; boundary=\"==fwd==\"\r\n\r\n" +
+			"--==fwd==\r\n" +
+			"Content-Type: text/plain; charset=\"utf-8\"\r\n" +
+			"Content-Transfer-Encoding: 8bit\r\n\r\n" +
+			"正文\r\n\r\n" +
+			"--==fwd==\r\n" +
+			"Content-Type: message/rfc822\r\n" +
+			"Content-Transfer-Encoding: base64\r\n" +
+			"Content-Disposition: attachment; filename=\"original.eml\"\r\n" +
+			"MIME-Version: 1.0\r\n\r\n" +
+			rfc822Body + "\r\n" +
+			"--==fwd==--\r\n",
+	}
+	// 2) 截断的 multipart（缺少结束边界）：BODYSTRUCTURE(extended) 解析报错
+	msgTruncated := &db.Message{
+		UserID:   1,
+		Folder:   "INBOX",
+		FromAddr: "alice@example.com",
+		ToAddr:   "alice@example.com",
+		Subject:  "truncated",
+		Date:     time.Now().Add(-1 * time.Hour),
+		RawData: "From: alice@example.com\r\n" +
+			"To: alice@example.com\r\n" +
+			"Subject: truncated\r\n" +
+			"MIME-Version: 1.0\r\n" +
+			"Content-Type: multipart/alternative; boundary=\"==trunc==\"\r\n\r\n" +
+			"--==trunc==\r\n" +
+			"Content-Type: text/plain\r\n\r\n" +
+			"hello\r\n",
+		// 无结束边界
+	}
+	if err := stores.Mails.Create(msgWithRFC822); err != nil {
+		t.Fatalf("create msg: %v", err)
+	}
+	if err := stores.Mails.Create(msgTruncated); err != nil {
+		t.Fatalf("create msg: %v", err)
+	}
+
+	c := loginAndSelect(t, addr)
+
+	seqset := new(imap.SeqSet)
+	seqset.AddRange(1, 2)
+
+	// BODY：历史上 message/rfc822 消息解析失败 → nil BodyStructure → panic
+	msgs := make(chan *imap.Message, 10)
+	if err := c.Fetch(seqset, []imap.FetchItem{imap.FetchBody}, msgs); err != nil {
+		t.Fatalf("fetch body: %v", err)
+	}
+	got := 0
+	for range msgs {
+		got++
+	}
+	if got != 2 {
+		t.Fatalf("FETCH BODY 返回 %d/2 封", got)
+	}
+
+	// BODYSTRUCTURE：截断 multipart 在 extended 解析时报错 → nil → panic
+	msgs2 := make(chan *imap.Message, 10)
+	if err := c.Fetch(seqset, []imap.FetchItem{imap.FetchBodyStructure}, msgs2); err != nil {
+		t.Fatalf("fetch bodystructure: %v", err)
+	}
+	got2 := 0
+	for range msgs2 {
+		got2++
+	}
+	if got2 != 2 {
+		t.Fatalf("FETCH BODYSTRUCTURE 返回 %d/2 封", got2)
+	}
+}