fix(maintenance): distinguish invalid backups from server failures

internal/api/maintenance.go

@@ -13,6 +13,7 @@ import (
 	"path/filepath"
 	"runtime"
 	"strings"
+	"syscall"
 	"time"
 
 	"rawmark/internal/backup"
@@ -53,9 +54,13 @@ func (s *Server) guardAPI(next http.Handler) http.Handler {
 		next.ServeHTTP(w, r)
 	})
 }
+
+var errMaintenanceBusy = errors.New("其他维护操作正在执行")
+var errMaintenanceInput = errors.New("维护请求无效")
+
 func (s *Server) maintain(operation string, fn func() error) error {
 	if !s.maintenanceMu.TryLock() {
-		return fmt.Errorf("其他维护操作正在执行")
+		return errMaintenanceBusy
 	}
 	defer s.maintenanceMu.Unlock()
 	s.maintenanceBusy.Store(true)
@@ -82,8 +87,20 @@ func (s *Server) maintenanceInfo(w http.ResponseWriter, r *http.Request) {
 	defer s.maintenanceStatusMu.Unlock()
 	writeJSON(w, 200, s.maintenanceState)
 }
-func (s *Server) maintenanceError(w http.ResponseWriter, err error) {
-	writeError(w, 400, "操作失败："+err.Error())
+func (s *Server) maintenanceError(w http.ResponseWriter, r *http.Request, err error) {
+	var pathError *os.PathError
+	switch {
+	case errors.Is(err, errMaintenanceBusy):
+		writeError(w, 503, err.Error())
+	case errors.Is(err, syscall.ENOSPC):
+		writeError(w, 503, "磁盘空间不足")
+	case errors.As(err, &pathError) && !errors.Is(pathError, os.ErrNotExist) && !errors.Is(pathError, syscall.ENOTDIR) && !errors.Is(pathError, syscall.EISDIR):
+		internalError(w, r, err)
+	case errors.Is(err, errMaintenanceInput), errors.Is(err, backup.ErrInvalidArchive):
+		writeError(w, 400, "操作失败："+err.Error())
+	default:
+		internalError(w, r, err)
+	}
 }
 func (s *Server) tempDir() (string, error) {
 	dir := filepath.Join(s.DataDir, "temp")
@@ -207,7 +224,7 @@ func (s *Server) exportBackup(w http.ResponseWriter, r *http.Request) {
 		return sendDownload(w, r, name, "rawmark-"+kind+"-"+time.Now().Format("20060102-150405")+".zip")
 	})
 	if err != nil {
-		s.maintenanceError(w, err)
+		s.maintenanceError(w, r, err)
 	}
 }
 func (s *Server) exportNotes(w http.ResponseWriter, r *http.Request) {
@@ -229,46 +246,46 @@ func (s *Server) exportNotes(w http.ResponseWriter, r *http.Request) {
 		return sendDownload(w, r, file.Name(), "rawmark-notes-"+time.Now().Format("20060102-150405")+".zip")
 	})
 	if err != nil {
-		s.maintenanceError(w, err)
+		s.maintenanceError(w, r, err)
 	}
 }
 
 func validatePreferences(values map[string]json.RawMessage) error {
 	for key, raw := range values {
 		if len(raw) > maxJSONBytes {
-			return fmt.Errorf("单项设置超过 1 MiB")
+			return fmt.Errorf("%w：单项设置超过 1 MiB", errMaintenanceInput)
 		}
 		switch {
 		case key == settingsKey:
 			var settings map[string]json.RawMessage
 			if err := json.Unmarshal(raw, &settings); err != nil || settings == nil {
-				return fmt.Errorf("偏好设置必须为对象")
+				return fmt.Errorf("%w：偏好设置必须为对象", errMaintenanceInput)
 			}
 			if _, err := trashRetentionDays(settings); err != nil {
-				return err
+				return fmt.Errorf("%w：%w", errMaintenanceInput, err)
 			}
 			if value, ok := settings["shortcuts"]; ok {
 				var shortcuts map[string][]string
 				if err := json.Unmarshal(value, &shortcuts); err != nil {
-					return fmt.Errorf("快捷键格式无效")
+					return fmt.Errorf("%w：快捷键格式无效", errMaintenanceInput)
 				}
 			}
 		case key == pluginEnabledKey:
 			var ids map[string]bool
 			if err := json.Unmarshal(raw, &ids); err != nil {
-				return err
+				return fmt.Errorf("%w：%w", errMaintenanceInput, err)
 			}
 			for id := range ids {
 				if !validPluginID(id) {
-					return fmt.Errorf("插件 ID 无效")
+					return fmt.Errorf("%w：插件 ID 无效", errMaintenanceInput)
 				}
 			}
 		case strings.HasPrefix(key, "plugin.data."):
 			if !validPluginID(strings.TrimPrefix(key, "plugin.data.")) || !json.Valid(raw) {
-				return fmt.Errorf("插件数据无效")
+				return fmt.Errorf("%w：插件数据无效", errMaintenanceInput)
 			}
 		default:
-			return fmt.Errorf("设置包包含不允许的设置项")
+			return fmt.Errorf("%w：设置包包含不允许的设置项", errMaintenanceInput)
 		}
 	}
 	return nil
@@ -279,7 +296,7 @@ func readPreferences(stage string) (map[string]json.RawMessage, error) {
 		return nil, err
 	}
 	if info.Size() > 32<<20 {
-		return nil, fmt.Errorf("设置包设置内容超过 32 MiB")
+		return nil, fmt.Errorf("%w：设置包设置内容超过 32 MiB", errMaintenanceInput)
 	}
 	raw, err := os.ReadFile(filepath.Join(stage, "settings.json"))
 	if err != nil {
@@ -287,7 +304,7 @@ func readPreferences(stage string) (map[string]json.RawMessage, error) {
 	}
 	var values map[string]json.RawMessage
 	if err = json.Unmarshal(raw, &values); err != nil || values == nil {
-		return nil, fmt.Errorf("设置包格式无效")
+		return nil, fmt.Errorf("%w：设置包格式无效", errMaintenanceInput)
 	}
 	if err = validatePreferences(values); err != nil {
 		return nil, err
@@ -314,7 +331,7 @@ func (s *Server) applySettings(w http.ResponseWriter, r *http.Request) {
 			return err
 		}
 		if !meta.Validated || meta.Kind != "settings" {
-			return fmt.Errorf("请先校验设置包")
+			return fmt.Errorf("%w：请先校验设置包", errMaintenanceInput)
 		}
 		stage := filepath.Join(dir, "stage")
 		values, err := readPreferences(stage)
@@ -407,7 +424,7 @@ func (s *Server) applySettings(w http.ResponseWriter, r *http.Request) {
 		return nil
 	})
 	if err != nil {
-		s.maintenanceError(w, err)
+		s.maintenanceError(w, r, err)
 		return
 	}
 	s.hub.Broadcast(events.Event{Type: "settings"}, events.Event{Type: "plugins"})
@@ -432,7 +449,7 @@ func (s *Server) resetSettings(w http.ResponseWriter, r *http.Request) {
 		return nil
 	})
 	if err != nil {
-		s.maintenanceError(w, err)
+		s.maintenanceError(w, r, err)
 		return
 	}
 	s.hub.Broadcast(events.Event{Type: "settings"}, events.Event{Type: "plugins"})
@@ -451,7 +468,7 @@ func (s *Server) maintainIndex(w http.ResponseWriter, r *http.Request) {
 		return s.index.Optimize(r.Context())
 	})
 	if err != nil {
-		s.maintenanceError(w, err)
+		s.maintenanceError(w, r, err)
 		return
 	}
 	s.hub.Broadcast(events.Event{Type: "indexed"})
@@ -518,6 +535,6 @@ func (s *Server) exportLogs(w http.ResponseWriter, r *http.Request) {
 		return sendDownload(w, r, file, "rawmark-system-logs.zip")
 	})
 	if err != nil {
-		s.maintenanceError(w, err)
+		s.maintenanceError(w, r, err)
 	}
 }

internal/api/maintenance_test.go

@@ -4,13 +4,16 @@ import (
 	"context"
 	"database/sql"
 	"encoding/json"
+	"errors"
 	"io"
+	"math"
 	"net/http"
 	"net/http/httptest"
 	"os"
 	"path/filepath"
 	"strconv"
 	"strings"
+	"syscall"
 	"testing"
 
 	"rawmark/internal/backup"
@@ -61,7 +64,7 @@ func exportedPackage(t *testing.T, f *fixture, kind string) []byte {
 	}
 	return data
 }
-func stagedPackage(t *testing.T, f *fixture, kind string, data []byte) string {
+func uploadedPackage(t *testing.T, f *fixture, kind string, data []byte) string {
 	t.Helper()
 	res := f.do(f.admin, "POST", "/api/v1/maintenance/uploads", `{"kind":"`+kind+`","size":`+strconv.Itoa(len(data))+`}`, nil)
 	if res.StatusCode != 201 {
@@ -82,7 +85,12 @@ func stagedPackage(t *testing.T, f *fixture, kind string, data []byte) string {
 		}
 		offset = next
 	}
-	res = f.do(f.admin, "POST", "/api/v1/maintenance/uploads/"+id+"/validate", "", nil)
+	return id
+}
+func stagedPackage(t *testing.T, f *fixture, kind string, data []byte) string {
+	t.Helper()
+	id := uploadedPackage(t, f, kind, data)
+	res := f.do(f.admin, "POST", "/api/v1/maintenance/uploads/"+id+"/validate", "", nil)
 	if res.StatusCode != 200 {
 		body, _ := io.ReadAll(res.Body)
 		t.Fatalf("校验失败: %d %s", res.StatusCode, body)
@@ -277,8 +285,8 @@ func TestSettingsPackageDatabaseFailureRollsBack(t *testing.T) {
 	}
 	id := stagedPackage(t, f, "settings", data)
 	res := f.do(f.admin, "POST", "/api/v1/maintenance/settings/import", `{"id":"`+id+`","confirmed":true}`, nil)
-	if res.StatusCode == 200 {
-		t.Fatal("错误提交返回成功")
+	if res.StatusCode != 500 {
+		t.Fatalf("数据库提交故障应返回 500，实际 %d", res.StatusCode)
 	}
 	value, _, err := f.store.Setting(settingsKey)
 	if err != nil || !strings.Contains(value, "18") {
@@ -288,3 +296,81 @@ func TestSettingsPackageDatabaseFailureRollsBack(t *testing.T) {
 		t.Fatal("成功回退后仍有待执行记录")
 	}
 }
+
+func TestMaintenanceErrorsPreserveHTTPStatus(t *testing.T) {
+	t.Run("invalid archive", func(t *testing.T) {
+		f := newFixture(t)
+		id := uploadedPackage(t, f, "settings", []byte("not a zip"))
+		res := f.do(f.admin, "POST", "/api/v1/maintenance/uploads/"+id+"/validate", "", nil)
+		defer res.Body.Close()
+		var body response
+		if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
+			t.Fatal(err)
+		}
+		if res.StatusCode != 400 || body.Code != 40000 || !strings.Contains(body.Message, "备份内容无效") {
+			t.Fatalf("无效备份响应错误: %d %+v", res.StatusCode, body)
+		}
+	})
+	t.Run("invalid resource structure", func(t *testing.T) {
+		f := newFixture(t)
+		dir := t.TempDir()
+		settings := filepath.Join(dir, "settings.json")
+		fonts := filepath.Join(dir, "fonts-file")
+		if err := os.WriteFile(settings, []byte("{}"), 0600); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(fonts, []byte("not a directory"), 0600); err != nil {
+			t.Fatal(err)
+		}
+		archive := filepath.Join(dir, "invalid-resources.zip")
+		if err := backup.Create(context.Background(), archive, "settings", []backup.Source{{Name: "settings.json", Path: settings}, {Name: "app/fonts", Path: fonts}}, nil); err != nil {
+			t.Fatal(err)
+		}
+		data, err := os.ReadFile(archive)
+		if err != nil {
+			t.Fatal(err)
+		}
+		id := uploadedPackage(t, f, "settings", data)
+		res := f.do(f.admin, "POST", "/api/v1/maintenance/uploads/"+id+"/validate", "", nil)
+		defer res.Body.Close()
+		if res.StatusCode != 400 {
+			t.Fatalf("归档资源结构错误应返回 400，实际 %d", res.StatusCode)
+		}
+	})
+	t.Run("filesystem failure", func(t *testing.T) {
+		f := newFixture(t)
+		if err := os.WriteFile(filepath.Join(f.server.DataDir, ".maintenance"), []byte("blocked"), 0600); err != nil {
+			t.Fatal(err)
+		}
+		res := f.do(f.admin, "POST", "/api/v1/maintenance/uploads", `{"kind":"settings","size":10}`, nil)
+		defer res.Body.Close()
+		var body response
+		if err := json.NewDecoder(res.Body).Decode(&body); err != nil {
+			t.Fatal(err)
+		}
+		if res.StatusCode != 500 || body.Code != 50000 || body.Message != "服务器内部错误" {
+			t.Fatalf("磁盘故障被当作输入错误: %d %+v", res.StatusCode, body)
+		}
+	})
+	t.Run("maintenance contention", func(t *testing.T) {
+		f := newFixture(t)
+		f.server.maintenanceMu.Lock()
+		defer f.server.maintenanceMu.Unlock()
+		res := f.do(f.admin, "POST", "/api/v1/maintenance/uploads", `{"kind":"settings","size":10}`, nil)
+		defer res.Body.Close()
+		if res.StatusCode != 503 {
+			t.Fatalf("维护占用应返回 503，实际 %d", res.StatusCode)
+		}
+	})
+	t.Run("insufficient disk space", func(t *testing.T) {
+		err := enoughSpace(t.TempDir(), math.MaxInt64)
+		if !errors.Is(err, syscall.ENOSPC) {
+			t.Fatalf("磁盘容量检查未保留 ENOSPC: %v", err)
+		}
+		w := httptest.NewRecorder()
+		(&Server{}).maintenanceError(w, httptest.NewRequest("POST", "/api/v1/maintenance/uploads", nil), err)
+		if w.Code != 503 {
+			t.Fatalf("磁盘空间不足应返回 503，实际 %d", w.Code)
+		}
+	})
+}

internal/api/maintenance_uploads.go

@@ -18,6 +18,8 @@ import (
 
 	"rawmark/internal/backup"
 	"rawmark/internal/store"
+
+	"modernc.org/sqlite"
 )
 
 const maintenanceChunkBytes int64 = 8 << 20
@@ -37,10 +39,13 @@ func uploadOwner(r *http.Request) string {
 func (s *Server) readUpload(r *http.Request, id string) (maintenanceUpload, string, error) {
 	var meta maintenanceUpload
 	if !uploadIDPattern.MatchString(id) {
-		return meta, "", fmt.Errorf("上传 ID 无效")
+		return meta, "", fmt.Errorf("%w：上传 ID 无效", errMaintenanceInput)
 	}
 	dir := filepath.Join(s.DataDir, ".maintenance", "uploads", id)
 	data, err := os.ReadFile(filepath.Join(dir, "upload.json"))
+	if errors.Is(err, os.ErrNotExist) {
+		return meta, "", fmt.Errorf("%w：上传不存在或已过期", errMaintenanceInput)
+	}
 	if err != nil {
 		return meta, "", err
 	}
@@ -48,7 +53,7 @@ func (s *Server) readUpload(r *http.Request, id string) (maintenanceUpload, stri
 		return meta, "", err
 	}
 	if meta.Owner != uploadOwner(r) {
-		return meta, "", fmt.Errorf("上传不属于当前会话")
+		return meta, "", fmt.Errorf("%w：上传不属于当前会话", errMaintenanceInput)
 	}
 	return meta, dir, nil
 }
@@ -65,7 +70,7 @@ func enoughSpace(dir string, size int64) error {
 		return err
 	}
 	if size < 0 || uint64(size)+(32<<20) > stat.Bavail*uint64(stat.Bsize) {
-		return fmt.Errorf("磁盘空间不足")
+		return fmt.Errorf("磁盘空间不足：%w", syscall.ENOSPC)
 	}
 	return nil
 }
@@ -107,7 +112,7 @@ func (s *Server) startMaintenanceUpload(w http.ResponseWriter, r *http.Request)
 		return f.Close()
 	})
 	if err != nil {
-		s.maintenanceError(w, err)
+		s.maintenanceError(w, r, err)
 		return
 	}
 	writeJSON(w, 201, map[string]string{"id": id})
@@ -126,7 +131,7 @@ func (s *Server) appendMaintenanceUpload(w http.ResponseWriter, r *http.Request)
 			return err
 		}
 		if meta.Validated {
-			return fmt.Errorf("已校验的上传不可修改")
+			return fmt.Errorf("%w：已校验的上传不可修改", errMaintenanceInput)
 		}
 		f, err := os.OpenFile(filepath.Join(dir, "archive.zip"), os.O_WRONLY, 0600)
 		if err != nil {
@@ -138,18 +143,22 @@ func (s *Server) appendMaintenanceUpload(w http.ResponseWriter, r *http.Request)
 			return err
 		}
 		if info.Size() != offset {
-			return fmt.Errorf("上传偏移不匹配，请重新上传")
+			return fmt.Errorf("%w：上传偏移不匹配，请重新上传", errMaintenanceInput)
 		}
 		limit := min(maintenanceChunkBytes, meta.Size-offset)
 		if limit <= 0 {
-			return fmt.Errorf("上传大小超出清单")
+			return fmt.Errorf("%w：上传大小超出清单", errMaintenanceInput)
 		}
 		data, err := io.ReadAll(http.MaxBytesReader(w, r.Body, limit))
 		if err != nil {
+			var tooLarge *http.MaxBytesError
+			if errors.As(err, &tooLarge) {
+				return fmt.Errorf("%w：%w", errMaintenanceInput, err)
+			}
 			return err
 		}
 		if len(data) == 0 {
-			return fmt.Errorf("上传内容为空")
+			return fmt.Errorf("%w：上传内容为空", errMaintenanceInput)
 		}
 		if err = enoughSpace(dir, int64(len(data))); err != nil {
 			return err
@@ -165,11 +174,20 @@ func (s *Server) appendMaintenanceUpload(w http.ResponseWriter, r *http.Request)
 		return nil
 	})
 	if err != nil {
-		s.maintenanceError(w, err)
+		s.maintenanceError(w, r, err)
 		return
 	}
 	writeJSON(w, 200, map[string]int64{"offset": next})
 }
+func backupResourceError(err error) error {
+	var pathError *os.PathError
+	// 缺失文件或文件／目录类型错误来自归档内容；其他磁盘故障仍由服务端处理。
+	if errors.As(err, &pathError) && !errors.Is(pathError, os.ErrNotExist) && !errors.Is(pathError, syscall.ENOTDIR) && !errors.Is(pathError, syscall.EISDIR) {
+		return err
+	}
+	return fmt.Errorf("%w：%w", backup.ErrInvalidArchive, err)
+}
+
 func (s *Server) validateResources(stage string) error {
 	temp := &Server{FontsDir: filepath.Join(stage, "app", "fonts"), ThemesDir: filepath.Join(stage, "app", "themes"), PluginsDir: filepath.Join(stage, "app", "plugins")}
 	for _, kind := range []string{"fonts", "themes", "plugins"} {
@@ -178,27 +196,27 @@ func (s *Server) validateResources(stage string) error {
 			continue
 		}
 		if err != nil {
-			return err
+			return backupResourceError(err)
 		}
 		for _, entry := range entries {
 			if !entry.IsDir() {
-				return fmt.Errorf("资源目录内包含非目录条目")
+				return fmt.Errorf("%w：资源目录内包含非目录条目", errMaintenanceInput)
 			}
 			switch kind {
 			case "fonts":
 				dir, _, err := temp.openFont(entry.Name())
 				if err != nil {
-					return err
+					return backupResourceError(err)
 				}
 				dir.Close()
 			case "themes":
 				if _, _, err := temp.readTheme(entry.Name()); err != nil {
-					return err
+					return backupResourceError(err)
 				}
 			case "plugins":
 				dir, _, err := temp.openPlugin(entry.Name())
 				if err != nil {
-					return err
+					return backupResourceError(err)
 				}
 				dir.Close()
 			}
@@ -219,7 +237,7 @@ func (s *Server) validateMaintenanceUpload(w http.ResponseWriter, r *http.Reques
 			return err
 		}
 		if info.Size() != meta.Size {
-			return fmt.Errorf("上传尚未完成")
+			return fmt.Errorf("%w：上传尚未完成", errMaintenanceInput)
 		}
 		meta.Validated = false
 		if err = saveUpload(dir, meta); err != nil {
@@ -237,12 +255,12 @@ func (s *Server) validateMaintenanceUpload(w http.ResponseWriter, r *http.Reques
 			return err
 		}
 		if manifest.Kind != meta.Kind {
-			return fmt.Errorf("备份类型与所选操作不符")
+			return fmt.Errorf("%w：备份类型与所选操作不符", errMaintenanceInput)
 		}
 		for _, entry := range manifest.Entries {
 			bytes += entry.Size
 			if strings.HasPrefix(entry.Path, "vault/") && backup.VaultExcluded(s.DataDir, s.vault.Root(), strings.TrimPrefix(entry.Path, "vault/")) {
-				return fmt.Errorf("笔记库内容与应用目录冲突")
+				return fmt.Errorf("%w：笔记库内容与应用目录冲突", errMaintenanceInput)
 			}
 		}
 		if err = enoughSpace(dir, bytes*2); err != nil {
@@ -263,6 +281,11 @@ func (s *Server) validateMaintenanceUpload(w http.ResponseWriter, r *http.Reques
 					prefs, err = st.Preferences()
 					if err == nil {
 						err = validatePreferences(prefs)
+					} else {
+						var databaseError *sqlite.Error
+						if !errors.As(err, &databaseError) {
+							err = fmt.Errorf("%w：%w", backup.ErrInvalidArchive, err)
+						}
 					}
 					err = errors.Join(err, st.Close())
 				}
@@ -275,7 +298,7 @@ func (s *Server) validateMaintenanceUpload(w http.ResponseWriter, r *http.Reques
 		return saveUpload(dir, meta)
 	})
 	if err != nil {
-		s.maintenanceError(w, err)
+		s.maintenanceError(w, r, err)
 		return
 	}
 	writeJSON(w, 200, map[string]any{"kind": manifest.Kind, "createdAt": manifest.CreatedAt, "entries": len(manifest.Entries), "size": bytes})
@@ -289,7 +312,7 @@ func (s *Server) deleteMaintenanceUpload(w http.ResponseWriter, r *http.Request)
 		return os.RemoveAll(dir)
 	})
 	if err != nil {
-		s.maintenanceError(w, err)
+		s.maintenanceError(w, r, err)
 		return
 	}
 	writeJSON(w, 200, map[string]bool{"ok": true})
@@ -316,7 +339,7 @@ func (s *Server) restoreInstance(w http.ResponseWriter, r *http.Request) {
 			return err
 		}
 		if !meta.Validated || meta.Kind != "full" {
-			return fmt.Errorf("请先校验完整服务备份")
+			return fmt.Errorf("%w：请先校验完整服务备份", errMaintenanceInput)
 		}
 		file, err := s.saveRollback(r.Context(), "full")
 		if err != nil {
@@ -329,7 +352,7 @@ func (s *Server) restoreInstance(w http.ResponseWriter, r *http.Request) {
 		return nil
 	})
 	if err != nil {
-		s.maintenanceError(w, err)
+		s.maintenanceError(w, r, err)
 		return
 	}
 	writeJSON(w, 202, map[string]bool{"restarting": true})
@@ -421,7 +444,7 @@ func (s *Server) clearTemp(w http.ResponseWriter, r *http.Request) {
 		return nil
 	})
 	if err != nil {
-		s.maintenanceError(w, err)
+		s.maintenanceError(w, r, err)
 		return
 	}
 	writeJSON(w, 200, result)