feat(external-imap): 新增外部 IMAP 全局开关与后台配置

- 支持在系统设置中启用/禁用外部 IMAP，并持久化相关密钥与 OAuth 配置。 - 在公共设置和前端页面中联动开关状态，未启用时隐藏外部 IMAP 相关功能并拦截后端接口。 - 补充外部 IMAP 默认关闭、配置说明与回调地址文档。
2026-06-25 22:44:32 +08:00
parent cc75382869
commit 707f11687d
12 changed files with 394 additions and 180 deletions
@@ -308,28 +308,36 @@ func updateRegularPermissionGroupWithLimits(t *testing.T, admin *testClient, per

 func systemSettingsPayload(settings SystemSettings) map[string]any {
 	return map[string]any{
-		"publicHostname":          settings.PublicHostname,
-		"publicBaseUrl":           settings.PublicBaseURL,
-		"smtpHost":                settings.SMTPHost,
-		"smtpPort":                settings.SMTPPort,
-		"smtpUsername":            settings.SMTPUsername,
-		"smtpPassword":            "",
-		"smtpRequireTls":          settings.SMTPRequireTLS,
-		"maildirRoot":             settings.MaildirRoot,
-		"maildirScanSeconds":      settings.MaildirScanSeconds,
-		"sessionTtlHours":         settings.SessionTTLHours,
-		"allowInsecureHttp":       settings.AllowInsecureHTTP,
-		"openRegistration":        settings.OpenRegistration,
-		"twoFactorEnabled":        settings.TwoFactorEnabled,
-		"turnstileEnabled":        settings.TurnstileEnabled,
-		"turnstileSiteKey":        settings.TurnstileSiteKey,
-		"turnstileSecretKey":      "",
-		"catchAllEnabled":         settings.CatchAllEnabled,
-		"mailAutoRefresh":         settings.MailAutoRefresh,
-		"mailRefreshSeconds":      settings.MailRefreshSeconds,
-		"userMailboxApplyEnabled": settings.UserMailboxApplyEnabled,
-		"userMailboxDomainIds":    settings.UserMailboxDomainIDs,
-		"reservedMailboxPrefixes": settings.ReservedMailboxPrefixes,
+		"publicHostname":                  settings.PublicHostname,
+		"publicBaseUrl":                   settings.PublicBaseURL,
+		"smtpHost":                        settings.SMTPHost,
+		"smtpPort":                        settings.SMTPPort,
+		"smtpUsername":                    settings.SMTPUsername,
+		"smtpPassword":                    "",
+		"smtpRequireTls":                  settings.SMTPRequireTLS,
+		"maildirRoot":                     settings.MaildirRoot,
+		"maildirScanSeconds":              settings.MaildirScanSeconds,
+		"sessionTtlHours":                 settings.SessionTTLHours,
+		"allowInsecureHttp":               settings.AllowInsecureHTTP,
+		"openRegistration":                settings.OpenRegistration,
+		"twoFactorEnabled":                settings.TwoFactorEnabled,
+		"turnstileEnabled":                settings.TurnstileEnabled,
+		"turnstileSiteKey":                settings.TurnstileSiteKey,
+		"turnstileSecretKey":              "",
+		"catchAllEnabled":                 settings.CatchAllEnabled,
+		"mailAutoRefresh":                 settings.MailAutoRefresh,
+		"mailRefreshSeconds":              settings.MailRefreshSeconds,
+		"userMailboxApplyEnabled":         settings.UserMailboxApplyEnabled,
+		"userMailboxDomainIds":            settings.UserMailboxDomainIDs,
+		"reservedMailboxPrefixes":         settings.ReservedMailboxPrefixes,
+		"externalImapEnabled":             settings.ExternalIMAPEnabled,
+		"externalImapSecretKey":           "",
+		"externalImapSyncSeconds":         settings.ExternalIMAPSyncSeconds,
+		"externalImapAllowPrivateHosts":   settings.ExternalIMAPAllowPrivateHosts,
+		"externalImapGmailClientId":       settings.ExternalIMAPGmailClientID,
+		"externalImapGmailClientSecret":   "",
+		"externalImapOutlookClientId":     settings.ExternalIMAPOutlookClientID,
+		"externalImapOutlookClientSecret": "",
 	}
 }

@@ -450,6 +458,7 @@ func TestExternalIMAPAccountEncryptsPasswordAndDoesNotReturnSecret(t *testing.T)
 		PublicHostname:                "mail.example.test",
 		PublicBaseURL:                 "http://localhost:5173",
 		AllowInsecureHTTP:             true,
+		ExternalIMAPEnabled:           true,
 		ExternalIMAPSecretKey:         "test-secret",
 		ExternalIMAPAllowPrivateHosts: true,
 	})
@@ -494,8 +503,57 @@ func TestExternalIMAPAccountEncryptsPasswordAndDoesNotReturnSecret(t *testing.T)
 	}
 }

+func TestExternalIMAPDisabledByDefaultAndAdminSettings(t *testing.T) {
+	a := newTestApp(t)
+	ts := httptest.NewServer(a.Router())
+	defer ts.Close()
+	admin := &testClient{t: t, server: ts}
+	if code := admin.do("POST", "/api/auth/login", map[string]string{"email": "admin@lanqin.local", "password": "ChangeMe123!"}, nil); code != http.StatusOK {
+		t.Fatalf("login code=%d", code)
+	}
+	_, mb := defaultAdminUserAndMailbox(t, a)
+	payload := map[string]any{"mailboxId": mb.ID, "name": "Disabled", "host": "imap.example.com", "port": 993, "tlsMode": "tls", "username": "user@example.com", "password": "secret", "storageMode": "remote"}
+	var body map[string]any
+	if code := admin.do("POST", "/api/me/external-imap-accounts", payload, &body); code != http.StatusForbidden {
+		t.Fatalf("external imap should be disabled by default code=%d body=%v", code, body)
+	}
+	var public PublicSettings
+	if code := admin.do("GET", "/api/public/settings", nil, &public); code != http.StatusOK || public.ExternalIMAPEnabled {
+		t.Fatalf("public settings should expose disabled external imap code=%d settings=%+v", code, public)
+	}
+	var settings SystemSettings
+	if code := admin.do("GET", "/api/admin/settings", nil, &settings); code != http.StatusOK {
+		t.Fatalf("get settings code=%d", code)
+	}
+	update := systemSettingsPayload(settings)
+	update["externalImapEnabled"] = true
+	if code := admin.do("POST", "/api/admin/settings", update, &body); code != http.StatusBadRequest {
+		t.Fatalf("enable without secret should fail code=%d body=%v", code, body)
+	}
+	update["externalImapSecretKey"] = "test-secret"
+	update["externalImapSyncSeconds"] = 120
+	update["externalImapAllowPrivateHosts"] = true
+	update["externalImapGmailClientId"] = "gmail-client"
+	update["externalImapGmailClientSecret"] = "gmail-secret"
+	update["externalImapOutlookClientId"] = "outlook-client"
+	update["externalImapOutlookClientSecret"] = "outlook-secret"
+	if code := admin.do("POST", "/api/admin/settings", update, &settings); code != http.StatusOK || !settings.ExternalIMAPEnabled || !settings.ExternalIMAPSecretSet || settings.ExternalIMAPSyncSeconds != 120 || !settings.ExternalIMAPAllowPrivateHosts || !settings.ExternalIMAPGmailClientSecretSet || !settings.ExternalIMAPOutlookClientSecretSet {
+		t.Fatalf("enable external imap code=%d settings=%+v", code, settings)
+	}
+	if settings.ExternalIMAPGmailClientID != "gmail-client" || settings.ExternalIMAPOutlookClientID != "outlook-client" {
+		t.Fatalf("oauth client ids not saved: %+v", settings)
+	}
+	if a.cfg.ExternalIMAPSecretKey != "test-secret" || a.cfg.ExternalIMAPGmailClientSecret != "gmail-secret" || a.cfg.ExternalIMAPOutlookClientSecret != "outlook-secret" {
+		t.Fatalf("secret settings not persisted in config")
+	}
+	if code := admin.do("GET", "/api/public/settings", nil, &public); code != http.StatusOK || !public.ExternalIMAPEnabled {
+		t.Fatalf("public settings should expose enabled external imap code=%d settings=%+v", code, public)
+	}
+}
+
 func TestExternalIMAPRejectsPrivateHostsByDefault(t *testing.T) {
 	a := newTestApp(t)
+	a.cfg.ExternalIMAPEnabled = true
 	a.cfg.ExternalIMAPSecretKey = "test-secret"
 	ts := httptest.NewServer(a.Router())
 	defer ts.Close()
@@ -524,6 +582,7 @@ func TestExternalIMAPOAuthStateDoesNotDefaultToLocalMailbox(t *testing.T) {
 		PublicHostname:                  "mail.example.test",
 		PublicBaseURL:                   "http://localhost:5173",
 		AllowInsecureHTTP:               true,
+		ExternalIMAPEnabled:             true,
 		ExternalIMAPSecretKey:           "test-secret",
 		ExternalIMAPOutlookClientID:     "client-id",
 		ExternalIMAPOutlookClientSecret: "client-secret",
@@ -635,6 +694,7 @@ func TestExternalIMAPAccountOwnershipIsolation(t *testing.T) {
 		PublicHostname:                "mail.example.test",
 		PublicBaseURL:                 "http://localhost:5173",
 		AllowInsecureHTTP:             true,
+		ExternalIMAPEnabled:           true,
 		ExternalIMAPSecretKey:         "test-secret",
 		ExternalIMAPAllowPrivateHosts: true,
 	})
@@ -1457,27 +1517,8 @@ func TestCatchAllStoresUnregisteredMailForAdminOnly(t *testing.T) {
 	if code := admin.do("GET", "/api/admin/settings", nil, &settings); code != http.StatusOK {
 		t.Fatalf("get settings code=%d", code)
 	}
-	update := map[string]any{
-		"publicHostname":     settings.PublicHostname,
-		"publicBaseUrl":      settings.PublicBaseURL,
-		"smtpHost":           settings.SMTPHost,
-		"smtpPort":           settings.SMTPPort,
-		"smtpUsername":       settings.SMTPUsername,
-		"smtpPassword":       "",
-		"smtpRequireTls":     settings.SMTPRequireTLS,
-		"maildirRoot":        settings.MaildirRoot,
-		"maildirScanSeconds": settings.MaildirScanSeconds,
-		"sessionTtlHours":    settings.SessionTTLHours,
-		"allowInsecureHttp":  settings.AllowInsecureHTTP,
-		"openRegistration":   settings.OpenRegistration,
-		"twoFactorEnabled":   settings.TwoFactorEnabled,
-		"turnstileEnabled":   settings.TurnstileEnabled,
-		"turnstileSiteKey":   settings.TurnstileSiteKey,
-		"turnstileSecretKey": "",
-		"catchAllEnabled":    true,
-		"mailAutoRefresh":    settings.MailAutoRefresh,
-		"mailRefreshSeconds": settings.MailRefreshSeconds,
-	}
+	update := systemSettingsPayload(settings)
+	update["catchAllEnabled"] = true
 	if code := admin.do("POST", "/api/admin/settings", update, &settings); code != http.StatusOK || !settings.CatchAllEnabled {
 		t.Fatalf("enable catch-all code=%d settings=%+v", code, settings)
 	}
@@ -41,6 +41,7 @@ type Config struct {
 	UserMailboxApplyEnabled         bool
 	UserMailboxDomainIDs            string
 	ReservedMailboxPrefixes         string
+	ExternalIMAPEnabled             bool
 	ExternalIMAPSecretKey           string
 	ExternalIMAPSyncSeconds         int
 	ExternalIMAPAllowPrivateHosts   bool
@@ -86,6 +87,7 @@ func LoadConfig() Config {
 		UserMailboxApplyEnabled:         getenvBool("LANQIN_USER_MAILBOX_APPLY_ENABLED", false),
 		UserMailboxDomainIDs:            getenv("LANQIN_USER_MAILBOX_DOMAIN_IDS", ""),
 		ReservedMailboxPrefixes:         getenv("LANQIN_RESERVED_MAILBOX_PREFIXES", "admin,postmaster,abuse,hostmaster,webmaster,root,security,noreply,no-reply,mailer-daemon"),
+		ExternalIMAPEnabled:             getenvBool("LANQIN_EXTERNAL_IMAP_ENABLED", false),
 		ExternalIMAPSecretKey:           getenv("LANQIN_EXTERNAL_IMAP_SECRET_KEY", ""),
 		ExternalIMAPSyncSeconds:         getenvInt("LANQIN_EXTERNAL_IMAP_SYNC_SECONDS", 300),
 		ExternalIMAPAllowPrivateHosts:   getenvBool("LANQIN_EXTERNAL_IMAP_ALLOW_PRIVATE_HOSTS", false),
@@ -148,6 +148,9 @@ func (a *App) externalIMAPWorker(ctx context.Context) {
 }

 func (a *App) syncDueExternalIMAPAccounts(ctx context.Context) {
+	if !a.cfg.ExternalIMAPEnabled {
+		return
+	}
 	rows, err := a.db.QueryContext(ctx, `SELECT id FROM external_imap_accounts WHERE enabled=1 AND storage_mode=? ORDER BY COALESCE(last_sync_at, created_at) ASC LIMIT 10`, externalIMAPStorageLocal)
 	if err != nil {
 		a.log.Warn("failed to list external imap accounts", "error", err)
@@ -165,6 +168,16 @@ func (a *App) syncDueExternalIMAPAccounts(ctx context.Context) {
 	}
 }

+func (a *App) requireExternalIMAPEnabled(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if !a.cfg.ExternalIMAPEnabled {
+			respondError(w, http.StatusForbidden, "external imap is disabled")
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
 func (a *App) handleListExternalIMAPAccounts(w http.ResponseWriter, r *http.Request) {
 	user := currentUser(r)
 	mailboxID := strings.TrimSpace(r.URL.Query().Get("mailboxId"))
@@ -59,16 +59,16 @@ func (a *App) Router() http.Handler {
 		r.With(a.requireAuth, a.requirePermission(PermissionMailBlocked)).Delete("/me/blocked-senders/{id}", a.handleDeleteBlockedSender)
 		r.With(a.requireAuth, a.requirePermission(PermissionMailStats)).Get("/me/stats", a.handleMailStats)
 		r.With(a.requireAuth, a.requirePermission(PermissionMailOrganize)).Post("/me/cleanup", a.handleMailCleanup)
-		r.With(a.requireAuth, a.requirePermission(PermissionMailAccess)).Get("/me/external-imap-accounts", a.handleListExternalIMAPAccounts)
-		r.With(a.requireAuth, a.requirePermission(PermissionMailAccess)).Post("/me/external-imap-accounts", a.handleCreateExternalIMAPAccount)
-		r.With(a.requireAuth, a.requirePermission(PermissionMailAccess)).Post("/me/external-imap-accounts/{id}", a.handleUpdateExternalIMAPAccount)
-		r.With(a.requireAuth, a.requirePermission(PermissionMailAccess)).Delete("/me/external-imap-accounts/{id}", a.handleDeleteExternalIMAPAccount)
-		r.With(a.requireAuth, a.requirePermission(PermissionMailAccess)).Post("/me/external-imap-accounts/{id}/test", a.handleTestExternalIMAPAccount)
-		r.With(a.requireAuth, a.requirePermission(PermissionMailAccess)).Get("/me/external-imap-accounts/{id}/runs", a.handleExternalIMAPSyncRuns)
-		r.With(a.requireAuth, a.requirePermission(PermissionMailAccess)).Post("/me/external-imap-accounts/{id}/sync", a.handleSyncExternalIMAPAccount)
-		r.With(a.requireAuth, a.requirePermission(PermissionMailAccess)).Post("/me/external-imap-accounts/{id}/sync-folder", a.handleSyncExternalIMAPFolder)
-		r.With(a.requireAuth, a.requirePermission(PermissionMailAccess)).Post("/me/external-imap-oauth/{provider}/start", a.handleStartExternalIMAPOAuth)
-		r.Get("/external-imap-oauth/{provider}/callback", a.handleExternalIMAPOAuthCallback)
+		r.With(a.requireAuth, a.requirePermission(PermissionMailAccess), a.requireExternalIMAPEnabled).Get("/me/external-imap-accounts", a.handleListExternalIMAPAccounts)
+		r.With(a.requireAuth, a.requirePermission(PermissionMailAccess), a.requireExternalIMAPEnabled).Post("/me/external-imap-accounts", a.handleCreateExternalIMAPAccount)
+		r.With(a.requireAuth, a.requirePermission(PermissionMailAccess), a.requireExternalIMAPEnabled).Post("/me/external-imap-accounts/{id}", a.handleUpdateExternalIMAPAccount)
+		r.With(a.requireAuth, a.requirePermission(PermissionMailAccess), a.requireExternalIMAPEnabled).Delete("/me/external-imap-accounts/{id}", a.handleDeleteExternalIMAPAccount)
+		r.With(a.requireAuth, a.requirePermission(PermissionMailAccess), a.requireExternalIMAPEnabled).Post("/me/external-imap-accounts/{id}/test", a.handleTestExternalIMAPAccount)
+		r.With(a.requireAuth, a.requirePermission(PermissionMailAccess), a.requireExternalIMAPEnabled).Get("/me/external-imap-accounts/{id}/runs", a.handleExternalIMAPSyncRuns)
+		r.With(a.requireAuth, a.requirePermission(PermissionMailAccess), a.requireExternalIMAPEnabled).Post("/me/external-imap-accounts/{id}/sync", a.handleSyncExternalIMAPAccount)
+		r.With(a.requireAuth, a.requirePermission(PermissionMailAccess), a.requireExternalIMAPEnabled).Post("/me/external-imap-accounts/{id}/sync-folder", a.handleSyncExternalIMAPFolder)
+		r.With(a.requireAuth, a.requirePermission(PermissionMailAccess), a.requireExternalIMAPEnabled).Post("/me/external-imap-oauth/{provider}/start", a.handleStartExternalIMAPOAuth)
+		r.With(a.requireExternalIMAPEnabled).Get("/external-imap-oauth/{provider}/callback", a.handleExternalIMAPOAuthCallback)
 		r.With(a.requireAuth).Get("/events", a.handleEvents)

 		r.Group(func(r chi.Router) {
@@ -84,12 +84,12 @@ func (a *App) Router() http.Handler {
 			r.With(a.requirePermission(PermissionMailRead)).Get("/mail/messages", a.handleMailMessages)
 			r.With(a.requirePermission(PermissionMailRead)).Get("/mail/starred", a.handleStarredMessages)
 			r.With(a.requirePermission(PermissionMailRead)).Get("/mail/messages/{id}", a.handleMailMessage)
-			r.With(a.requirePermission(PermissionMailRead)).Get("/mail/external-accounts", a.handleMailExternalAccounts)
-			r.With(a.requirePermission(PermissionMailRead)).Get("/mail/external-accounts/{id}/folders", a.handleExternalIMAPFolders)
-			r.With(a.requirePermission(PermissionMailRead)).Get("/mail/external-accounts/{id}/messages", a.handleExternalIMAPMessages)
-			r.With(a.requirePermission(PermissionMailRead)).Get("/mail/external-accounts/{id}/messages/{remoteId}", a.handleExternalIMAPMessage)
-			r.With(a.requirePermission(PermissionMailAttachments)).Get("/mail/external-accounts/{id}/attachments/{remoteId}/{partId}", a.handleExternalIMAPAttachment)
-			r.With(a.requirePermission(PermissionMailOrganize)).Post("/mail/external-accounts/{id}/messages/{remoteId}/mark-read", a.handleExternalIMAPMarkRead)
+			r.With(a.requirePermission(PermissionMailRead), a.requireExternalIMAPEnabled).Get("/mail/external-accounts", a.handleMailExternalAccounts)
+			r.With(a.requirePermission(PermissionMailRead), a.requireExternalIMAPEnabled).Get("/mail/external-accounts/{id}/folders", a.handleExternalIMAPFolders)
+			r.With(a.requirePermission(PermissionMailRead), a.requireExternalIMAPEnabled).Get("/mail/external-accounts/{id}/messages", a.handleExternalIMAPMessages)
+			r.With(a.requirePermission(PermissionMailRead), a.requireExternalIMAPEnabled).Get("/mail/external-accounts/{id}/messages/{remoteId}", a.handleExternalIMAPMessage)
+			r.With(a.requirePermission(PermissionMailAttachments), a.requireExternalIMAPEnabled).Get("/mail/external-accounts/{id}/attachments/{remoteId}/{partId}", a.handleExternalIMAPAttachment)
+			r.With(a.requirePermission(PermissionMailOrganize), a.requireExternalIMAPEnabled).Post("/mail/external-accounts/{id}/messages/{remoteId}/mark-read", a.handleExternalIMAPMarkRead)
 			r.With(a.requirePermission(PermissionMailSend)).Post("/mail/send", a.handleMailSend)
 			r.With(a.requirePermission(PermissionMailRead)).Get("/mail/send-queue", a.handleSendQueue)
 			r.With(a.requirePermission(PermissionMailRead)).Get("/mail/send-queue/{id}/audit", a.handleSendQueueAudit)
@@ -10,63 +10,80 @@ import (
 )

 type SystemSettings struct {
-	PublicHostname          string   `json:"publicHostname"`
-	PublicBaseURL           string   `json:"publicBaseUrl"`
-	SMTPHost                string   `json:"smtpHost"`
-	SMTPPort                string   `json:"smtpPort"`
-	SMTPUsername            string   `json:"smtpUsername"`
-	SMTPPasswordSet         bool     `json:"smtpPasswordSet"`
-	SMTPRequireTLS          bool     `json:"smtpRequireTls"`
-	MaildirRoot             string   `json:"maildirRoot"`
-	MaildirScanSeconds      int      `json:"maildirScanSeconds"`
-	SessionTTLHours         int      `json:"sessionTtlHours"`
-	AllowInsecureHTTP       bool     `json:"allowInsecureHttp"`
-	OpenRegistration        bool     `json:"openRegistration"`
-	TwoFactorEnabled        bool     `json:"twoFactorEnabled"`
-	TurnstileEnabled        bool     `json:"turnstileEnabled"`
-	TurnstileSiteKey        string   `json:"turnstileSiteKey"`
-	TurnstileSecretSet      bool     `json:"turnstileSecretSet"`
-	CatchAllEnabled         bool     `json:"catchAllEnabled"`
-	MailAutoRefresh         bool     `json:"mailAutoRefresh"`
-	MailRefreshSeconds      int      `json:"mailRefreshSeconds"`
-	UserMailboxApplyEnabled bool     `json:"userMailboxApplyEnabled"`
-	UserMailboxDomainIDs    []string `json:"userMailboxDomainIds"`
-	ReservedMailboxPrefixes string   `json:"reservedMailboxPrefixes"`
+	PublicHostname                     string   `json:"publicHostname"`
+	PublicBaseURL                      string   `json:"publicBaseUrl"`
+	SMTPHost                           string   `json:"smtpHost"`
+	SMTPPort                           string   `json:"smtpPort"`
+	SMTPUsername                       string   `json:"smtpUsername"`
+	SMTPPasswordSet                    bool     `json:"smtpPasswordSet"`
+	SMTPRequireTLS                     bool     `json:"smtpRequireTls"`
+	MaildirRoot                        string   `json:"maildirRoot"`
+	MaildirScanSeconds                 int      `json:"maildirScanSeconds"`
+	SessionTTLHours                    int      `json:"sessionTtlHours"`
+	AllowInsecureHTTP                  bool     `json:"allowInsecureHttp"`
+	OpenRegistration                   bool     `json:"openRegistration"`
+	TwoFactorEnabled                   bool     `json:"twoFactorEnabled"`
+	TurnstileEnabled                   bool     `json:"turnstileEnabled"`
+	TurnstileSiteKey                   string   `json:"turnstileSiteKey"`
+	TurnstileSecretSet                 bool     `json:"turnstileSecretSet"`
+	CatchAllEnabled                    bool     `json:"catchAllEnabled"`
+	MailAutoRefresh                    bool     `json:"mailAutoRefresh"`
+	MailRefreshSeconds                 int      `json:"mailRefreshSeconds"`
+	UserMailboxApplyEnabled            bool     `json:"userMailboxApplyEnabled"`
+	UserMailboxDomainIDs               []string `json:"userMailboxDomainIds"`
+	ReservedMailboxPrefixes            string   `json:"reservedMailboxPrefixes"`
+	ExternalIMAPEnabled                bool     `json:"externalImapEnabled"`
+	ExternalIMAPSecretSet              bool     `json:"externalImapSecretSet"`
+	ExternalIMAPSyncSeconds            int      `json:"externalImapSyncSeconds"`
+	ExternalIMAPAllowPrivateHosts      bool     `json:"externalImapAllowPrivateHosts"`
+	ExternalIMAPGmailClientID          string   `json:"externalImapGmailClientId"`
+	ExternalIMAPGmailClientSecretSet   bool     `json:"externalImapGmailClientSecretSet"`
+	ExternalIMAPOutlookClientID        string   `json:"externalImapOutlookClientId"`
+	ExternalIMAPOutlookClientSecretSet bool     `json:"externalImapOutlookClientSecretSet"`
 }

 type systemSettingsUpdate struct {
-	PublicHostname          string   `json:"publicHostname"`
-	PublicBaseURL           string   `json:"publicBaseUrl"`
-	SMTPHost                string   `json:"smtpHost"`
-	SMTPPort                string   `json:"smtpPort"`
-	SMTPUsername            string   `json:"smtpUsername"`
-	SMTPPassword            string   `json:"smtpPassword"`
-	SMTPRequireTLS          bool     `json:"smtpRequireTls"`
-	MaildirRoot             string   `json:"maildirRoot"`
-	MaildirScanSeconds      int      `json:"maildirScanSeconds"`
-	SessionTTLHours         int      `json:"sessionTtlHours"`
-	AllowInsecureHTTP       bool     `json:"allowInsecureHttp"`
-	OpenRegistration        bool     `json:"openRegistration"`
-	TwoFactorEnabled        bool     `json:"twoFactorEnabled"`
-	TurnstileEnabled        bool     `json:"turnstileEnabled"`
-	TurnstileSiteKey        string   `json:"turnstileSiteKey"`
-	TurnstileSecretKey      string   `json:"turnstileSecretKey"`
-	CatchAllEnabled         bool     `json:"catchAllEnabled"`
-	MailAutoRefresh         bool     `json:"mailAutoRefresh"`
-	MailRefreshSeconds      int      `json:"mailRefreshSeconds"`
-	UserMailboxApplyEnabled bool     `json:"userMailboxApplyEnabled"`
-	UserMailboxDomainIDs    []string `json:"userMailboxDomainIds"`
-	ReservedMailboxPrefixes string   `json:"reservedMailboxPrefixes"`
+	PublicHostname                  string   `json:"publicHostname"`
+	PublicBaseURL                   string   `json:"publicBaseUrl"`
+	SMTPHost                        string   `json:"smtpHost"`
+	SMTPPort                        string   `json:"smtpPort"`
+	SMTPUsername                    string   `json:"smtpUsername"`
+	SMTPPassword                    string   `json:"smtpPassword"`
+	SMTPRequireTLS                  bool     `json:"smtpRequireTls"`
+	MaildirRoot                     string   `json:"maildirRoot"`
+	MaildirScanSeconds              int      `json:"maildirScanSeconds"`
+	SessionTTLHours                 int      `json:"sessionTtlHours"`
+	AllowInsecureHTTP               bool     `json:"allowInsecureHttp"`
+	OpenRegistration                bool     `json:"openRegistration"`
+	TwoFactorEnabled                bool     `json:"twoFactorEnabled"`
+	TurnstileEnabled                bool     `json:"turnstileEnabled"`
+	TurnstileSiteKey                string   `json:"turnstileSiteKey"`
+	TurnstileSecretKey              string   `json:"turnstileSecretKey"`
+	CatchAllEnabled                 bool     `json:"catchAllEnabled"`
+	MailAutoRefresh                 bool     `json:"mailAutoRefresh"`
+	MailRefreshSeconds              int      `json:"mailRefreshSeconds"`
+	UserMailboxApplyEnabled         bool     `json:"userMailboxApplyEnabled"`
+	UserMailboxDomainIDs            []string `json:"userMailboxDomainIds"`
+	ReservedMailboxPrefixes         string   `json:"reservedMailboxPrefixes"`
+	ExternalIMAPEnabled             bool     `json:"externalImapEnabled"`
+	ExternalIMAPSecretKey           string   `json:"externalImapSecretKey"`
+	ExternalIMAPSyncSeconds         int      `json:"externalImapSyncSeconds"`
+	ExternalIMAPAllowPrivateHosts   bool     `json:"externalImapAllowPrivateHosts"`
+	ExternalIMAPGmailClientID       string   `json:"externalImapGmailClientId"`
+	ExternalIMAPGmailClientSecret   string   `json:"externalImapGmailClientSecret"`
+	ExternalIMAPOutlookClientID     string   `json:"externalImapOutlookClientId"`
+	ExternalIMAPOutlookClientSecret string   `json:"externalImapOutlookClientSecret"`
 }

 type PublicSettings struct {
-	OpenRegistration bool           `json:"openRegistration"`
-	TurnstileEnabled bool           `json:"turnstileEnabled"`
-	TurnstileSiteKey string         `json:"turnstileSiteKey"`
-	PublicHostname   string         `json:"publicHostname"`
-	MailAutoRefresh  bool           `json:"mailAutoRefresh"`
-	MailRefreshMs    int            `json:"mailRefreshMs"`
-	MailboxDomains   []PublicDomain `json:"mailboxDomains,omitempty"`
+	OpenRegistration    bool           `json:"openRegistration"`
+	TurnstileEnabled    bool           `json:"turnstileEnabled"`
+	TurnstileSiteKey    string         `json:"turnstileSiteKey"`
+	PublicHostname      string         `json:"publicHostname"`
+	MailAutoRefresh     bool           `json:"mailAutoRefresh"`
+	MailRefreshMs       int            `json:"mailRefreshMs"`
+	ExternalIMAPEnabled bool           `json:"externalImapEnabled"`
+	MailboxDomains      []PublicDomain `json:"mailboxDomains,omitempty"`
 }

 type PublicDomain struct {
@@ -88,7 +105,7 @@ func (a *App) handlePublicSettings(w http.ResponseWriter, r *http.Request) {
 	if refreshSeconds <= 0 {
 		refreshSeconds = 30
 	}
-	settings := PublicSettings{OpenRegistration: a.cfg.OpenRegistration, TurnstileEnabled: enabled, TurnstileSiteKey: a.cfg.TurnstileSiteKey, PublicHostname: a.cfg.PublicHostname, MailAutoRefresh: a.cfg.MailAutoRefresh, MailRefreshMs: refreshSeconds * 1000}
+	settings := PublicSettings{OpenRegistration: a.cfg.OpenRegistration, TurnstileEnabled: enabled, TurnstileSiteKey: a.cfg.TurnstileSiteKey, PublicHostname: a.cfg.PublicHostname, MailAutoRefresh: a.cfg.MailAutoRefresh, MailRefreshMs: refreshSeconds * 1000, ExternalIMAPEnabled: a.cfg.ExternalIMAPEnabled}

 	// Include available domains for mailbox creation during registration
 	if a.cfg.OpenRegistration {
@@ -165,6 +182,27 @@ func (a *App) handleUpdateSystemSettings(w http.ResponseWriter, r *http.Request)
 	next.UserMailboxApplyEnabled = req.UserMailboxApplyEnabled
 	next.UserMailboxDomainIDs = strings.Join(cleanIDList(req.UserMailboxDomainIDs), ",")
 	next.ReservedMailboxPrefixes = strings.Join(parseReservedPrefixes(req.ReservedMailboxPrefixes), ",")
+	next.ExternalIMAPEnabled = req.ExternalIMAPEnabled
+	if strings.TrimSpace(req.ExternalIMAPSecretKey) != "" {
+		next.ExternalIMAPSecretKey = strings.TrimSpace(req.ExternalIMAPSecretKey)
+	}
+	if req.ExternalIMAPSyncSeconds <= 0 {
+		req.ExternalIMAPSyncSeconds = 300
+	}
+	next.ExternalIMAPSyncSeconds = req.ExternalIMAPSyncSeconds
+	next.ExternalIMAPAllowPrivateHosts = req.ExternalIMAPAllowPrivateHosts
+	next.ExternalIMAPGmailClientID = strings.TrimSpace(req.ExternalIMAPGmailClientID)
+	if strings.TrimSpace(req.ExternalIMAPGmailClientSecret) != "" {
+		next.ExternalIMAPGmailClientSecret = strings.TrimSpace(req.ExternalIMAPGmailClientSecret)
+	}
+	next.ExternalIMAPOutlookClientID = strings.TrimSpace(req.ExternalIMAPOutlookClientID)
+	if strings.TrimSpace(req.ExternalIMAPOutlookClientSecret) != "" {
+		next.ExternalIMAPOutlookClientSecret = strings.TrimSpace(req.ExternalIMAPOutlookClientSecret)
+	}
+	if next.ExternalIMAPEnabled && strings.TrimSpace(next.ExternalIMAPSecretKey) == "" {
+		badRequest(w, errors.New("外部 IMAP 加密密钥未设置"))
+		return
+	}

 	if err := a.saveSystemSettings(r.Context(), next); err != nil {
 		respondError(w, http.StatusInternalServerError, "failed to save settings")
@@ -248,28 +286,36 @@ func (a *App) handleTestSMTP(w http.ResponseWriter, r *http.Request) {

 func (a *App) systemSettingsSnapshot() SystemSettings {
 	return SystemSettings{
-		PublicHostname:          a.cfg.PublicHostname,
-		PublicBaseURL:           a.cfg.PublicBaseURL,
-		SMTPHost:                a.cfg.SMTPHost,
-		SMTPPort:                a.cfg.SMTPPort,
-		SMTPUsername:            a.cfg.SMTPUsername,
-		SMTPPasswordSet:         strings.TrimSpace(a.cfg.SMTPPassword) != "",
-		SMTPRequireTLS:          a.cfg.SMTPRequireTLS,
-		MaildirRoot:             a.cfg.MaildirRoot,
-		MaildirScanSeconds:      a.cfg.MaildirScanSeconds,
-		SessionTTLHours:         a.cfg.SessionTTLHours,
-		AllowInsecureHTTP:       a.cfg.AllowInsecureHTTP,
-		OpenRegistration:        a.cfg.OpenRegistration,
-		TwoFactorEnabled:        a.cfg.TwoFactorEnabled,
-		TurnstileEnabled:        a.cfg.TurnstileEnabled,
-		TurnstileSiteKey:        a.cfg.TurnstileSiteKey,
-		TurnstileSecretSet:      strings.TrimSpace(a.cfg.TurnstileSecretKey) != "",
-		CatchAllEnabled:         a.cfg.CatchAllEnabled,
-		MailAutoRefresh:         a.cfg.MailAutoRefresh,
-		MailRefreshSeconds:      a.cfg.MailRefreshSeconds,
-		UserMailboxApplyEnabled: a.cfg.UserMailboxApplyEnabled,
-		UserMailboxDomainIDs:    cleanIDList(strings.Split(a.cfg.UserMailboxDomainIDs, ",")),
-		ReservedMailboxPrefixes: strings.Join(parseReservedPrefixes(a.cfg.ReservedMailboxPrefixes), "\n"),
+		PublicHostname:                     a.cfg.PublicHostname,
+		PublicBaseURL:                      a.cfg.PublicBaseURL,
+		SMTPHost:                           a.cfg.SMTPHost,
+		SMTPPort:                           a.cfg.SMTPPort,
+		SMTPUsername:                       a.cfg.SMTPUsername,
+		SMTPPasswordSet:                    strings.TrimSpace(a.cfg.SMTPPassword) != "",
+		SMTPRequireTLS:                     a.cfg.SMTPRequireTLS,
+		MaildirRoot:                        a.cfg.MaildirRoot,
+		MaildirScanSeconds:                 a.cfg.MaildirScanSeconds,
+		SessionTTLHours:                    a.cfg.SessionTTLHours,
+		AllowInsecureHTTP:                  a.cfg.AllowInsecureHTTP,
+		OpenRegistration:                   a.cfg.OpenRegistration,
+		TwoFactorEnabled:                   a.cfg.TwoFactorEnabled,
+		TurnstileEnabled:                   a.cfg.TurnstileEnabled,
+		TurnstileSiteKey:                   a.cfg.TurnstileSiteKey,
+		TurnstileSecretSet:                 strings.TrimSpace(a.cfg.TurnstileSecretKey) != "",
+		CatchAllEnabled:                    a.cfg.CatchAllEnabled,
+		MailAutoRefresh:                    a.cfg.MailAutoRefresh,
+		MailRefreshSeconds:                 a.cfg.MailRefreshSeconds,
+		UserMailboxApplyEnabled:            a.cfg.UserMailboxApplyEnabled,
+		UserMailboxDomainIDs:               cleanIDList(strings.Split(a.cfg.UserMailboxDomainIDs, ",")),
+		ReservedMailboxPrefixes:            strings.Join(parseReservedPrefixes(a.cfg.ReservedMailboxPrefixes), "\n"),
+		ExternalIMAPEnabled:                a.cfg.ExternalIMAPEnabled,
+		ExternalIMAPSecretSet:              strings.TrimSpace(a.cfg.ExternalIMAPSecretKey) != "",
+		ExternalIMAPSyncSeconds:            a.cfg.ExternalIMAPSyncSeconds,
+		ExternalIMAPAllowPrivateHosts:      a.cfg.ExternalIMAPAllowPrivateHosts,
+		ExternalIMAPGmailClientID:          a.cfg.ExternalIMAPGmailClientID,
+		ExternalIMAPGmailClientSecretSet:   strings.TrimSpace(a.cfg.ExternalIMAPGmailClientSecret) != "",
+		ExternalIMAPOutlookClientID:        a.cfg.ExternalIMAPOutlookClientID,
+		ExternalIMAPOutlookClientSecretSet: strings.TrimSpace(a.cfg.ExternalIMAPOutlookClientSecret) != "",
 	}
 }

@@ -335,6 +381,24 @@ func (a *App) loadPersistedSystemSettings(ctx context.Context) error {
 			a.cfg.UserMailboxDomainIDs = value
 		case "reservedMailboxPrefixes":
 			a.cfg.ReservedMailboxPrefixes = value
+		case "externalImapEnabled":
+			a.cfg.ExternalIMAPEnabled = value == "true"
+		case "externalImapSecretKey":
+			a.cfg.ExternalIMAPSecretKey = value
+		case "externalImapSyncSeconds":
+			if n, err := strconv.Atoi(value); err == nil && n > 0 {
+				a.cfg.ExternalIMAPSyncSeconds = n
+			}
+		case "externalImapAllowPrivateHosts":
+			a.cfg.ExternalIMAPAllowPrivateHosts = value == "true"
+		case "externalImapGmailClientId":
+			a.cfg.ExternalIMAPGmailClientID = value
+		case "externalImapGmailClientSecret":
+			a.cfg.ExternalIMAPGmailClientSecret = value
+		case "externalImapOutlookClientId":
+			a.cfg.ExternalIMAPOutlookClientID = value
+		case "externalImapOutlookClientSecret":
+			a.cfg.ExternalIMAPOutlookClientSecret = value
 		}
 	}
 	return rows.Err()
@@ -342,28 +406,36 @@ func (a *App) loadPersistedSystemSettings(ctx context.Context) error {

 func (a *App) saveSystemSettings(ctx context.Context, cfg Config) error {
 	values := map[string]string{
-		"publicHostname":          cfg.PublicHostname,
-		"publicBaseUrl":           cfg.PublicBaseURL,
-		"smtpHost":                cfg.SMTPHost,
-		"smtpPort":                cfg.SMTPPort,
-		"smtpUsername":            cfg.SMTPUsername,
-		"smtpPassword":            cfg.SMTPPassword,
-		"smtpRequireTls":          strconv.FormatBool(cfg.SMTPRequireTLS),
-		"maildirRoot":             cfg.MaildirRoot,
-		"maildirScanSeconds":      strconv.Itoa(cfg.MaildirScanSeconds),
-		"sessionTtlHours":         strconv.Itoa(cfg.SessionTTLHours),
-		"allowInsecureHttp":       strconv.FormatBool(cfg.AllowInsecureHTTP),
-		"openRegistration":        strconv.FormatBool(cfg.OpenRegistration),
-		"twoFactorEnabled":        strconv.FormatBool(cfg.TwoFactorEnabled),
-		"turnstileEnabled":        strconv.FormatBool(cfg.TurnstileEnabled),
-		"turnstileSiteKey":        cfg.TurnstileSiteKey,
-		"turnstileSecretKey":      cfg.TurnstileSecretKey,
-		"catchAllEnabled":         strconv.FormatBool(cfg.CatchAllEnabled),
-		"mailAutoRefresh":         strconv.FormatBool(cfg.MailAutoRefresh),
-		"mailRefreshSeconds":      strconv.Itoa(cfg.MailRefreshSeconds),
-		"userMailboxApplyEnabled": strconv.FormatBool(cfg.UserMailboxApplyEnabled),
-		"userMailboxDomainIds":    strings.Join(cleanIDList(strings.Split(cfg.UserMailboxDomainIDs, ",")), ","),
-		"reservedMailboxPrefixes": strings.Join(parseReservedPrefixes(cfg.ReservedMailboxPrefixes), ","),
+		"publicHostname":                  cfg.PublicHostname,
+		"publicBaseUrl":                   cfg.PublicBaseURL,
+		"smtpHost":                        cfg.SMTPHost,
+		"smtpPort":                        cfg.SMTPPort,
+		"smtpUsername":                    cfg.SMTPUsername,
+		"smtpPassword":                    cfg.SMTPPassword,
+		"smtpRequireTls":                  strconv.FormatBool(cfg.SMTPRequireTLS),
+		"maildirRoot":                     cfg.MaildirRoot,
+		"maildirScanSeconds":              strconv.Itoa(cfg.MaildirScanSeconds),
+		"sessionTtlHours":                 strconv.Itoa(cfg.SessionTTLHours),
+		"allowInsecureHttp":               strconv.FormatBool(cfg.AllowInsecureHTTP),
+		"openRegistration":                strconv.FormatBool(cfg.OpenRegistration),
+		"twoFactorEnabled":                strconv.FormatBool(cfg.TwoFactorEnabled),
+		"turnstileEnabled":                strconv.FormatBool(cfg.TurnstileEnabled),
+		"turnstileSiteKey":                cfg.TurnstileSiteKey,
+		"turnstileSecretKey":              cfg.TurnstileSecretKey,
+		"catchAllEnabled":                 strconv.FormatBool(cfg.CatchAllEnabled),
+		"mailAutoRefresh":                 strconv.FormatBool(cfg.MailAutoRefresh),
+		"mailRefreshSeconds":              strconv.Itoa(cfg.MailRefreshSeconds),
+		"userMailboxApplyEnabled":         strconv.FormatBool(cfg.UserMailboxApplyEnabled),
+		"userMailboxDomainIds":            strings.Join(cleanIDList(strings.Split(cfg.UserMailboxDomainIDs, ",")), ","),
+		"reservedMailboxPrefixes":         strings.Join(parseReservedPrefixes(cfg.ReservedMailboxPrefixes), ","),
+		"externalImapEnabled":             strconv.FormatBool(cfg.ExternalIMAPEnabled),
+		"externalImapSecretKey":           cfg.ExternalIMAPSecretKey,
+		"externalImapSyncSeconds":         strconv.Itoa(cfg.ExternalIMAPSyncSeconds),
+		"externalImapAllowPrivateHosts":   strconv.FormatBool(cfg.ExternalIMAPAllowPrivateHosts),
+		"externalImapGmailClientId":       cfg.ExternalIMAPGmailClientID,
+		"externalImapGmailClientSecret":   cfg.ExternalIMAPGmailClientSecret,
+		"externalImapOutlookClientId":     cfg.ExternalIMAPOutlookClientID,
+		"externalImapOutlookClientSecret": cfg.ExternalIMAPOutlookClientSecret,
 	}
 	now := a.now().UTC().Format(time.RFC3339Nano)
 	tx, err := a.db.BeginTx(ctx, nil)