feat: create standalone native fnOS repository

app-src/internal/backup/archive.go

@@ -0,0 +1,157 @@
+package backup
+
+import (
+	"archive/tar"
+	"compress/gzip"
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"time"
+
+	"github.com/havline/havline/internal/settings"
+)
+
+// 保留份数的边界：0/负数按默认值处理，上限防止把磁盘塞满
+const (
+	DefaultKeepCount = 7
+	MaxKeepCount     = 60
+)
+
+// archiveNamePattern 备份命名格式（Export 用 CreateTemp 生成，后缀是随机数字）。
+// List / Path 都按它过滤，避免把 backups 目录里任意文件当成备份读写或删除。
+var archiveNamePattern = regexp.MustCompile(`^havline-backup-\d{8}-\d{6}-\d+\.tar\.gz$`)
+
+// Archive 留在磁盘上的一份备份
+type Archive struct {
+	Name    string    `json:"name"`
+	Size    int64     `json:"size"`
+	ModTime time.Time `json:"mod_time"`
+}
+
+func (s *Service) backupsDir() string {
+	return filepath.Join(s.dataDir, "backups")
+}
+
+// List 按新的在前列出备份；目录不存在返回空列表（还没备份过是正常状态）。
+func (s *Service) List() ([]Archive, error) {
+	entries, err := os.ReadDir(s.backupsDir())
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	archives := make([]Archive, 0, len(entries))
+	for _, entry := range entries {
+		if entry.IsDir() || !archiveNamePattern.MatchString(entry.Name()) {
+			continue
+		}
+		info, err := entry.Info()
+		if err != nil {
+			continue
+		}
+		archives = append(archives, Archive{Name: entry.Name(), Size: info.Size(), ModTime: info.ModTime().UTC()})
+	}
+	// 文件名前缀就是时间戳，按名倒序即按时间倒序
+	sort.Slice(archives, func(i, j int) bool { return archives[i].Name > archives[j].Name })
+	return archives, nil
+}
+
+// Prune 只保留最新的 keep 份，返回删除数量；keep <= 0 表示不剪枝。
+func (s *Service) Prune(keep int) (int, error) {
+	if keep <= 0 {
+		return 0, nil
+	}
+	archives, err := s.List()
+	if err != nil {
+		return 0, err
+	}
+	removed := 0
+	for _, archive := range archives[min(keep, len(archives)):] {
+		if err := s.Remove(archive.Name); err != nil {
+			return removed, err
+		}
+		removed++
+	}
+	return removed, nil
+}
+
+// Path 把备份名解析成绝对路径；名字必须匹配备份命名格式，避免被用来读写目录外的文件。
+func (s *Service) Path(name string) (string, error) {
+	if !archiveNamePattern.MatchString(name) {
+		return "", fmt.Errorf("备份名无效")
+	}
+	return filepath.Join(s.backupsDir(), name), nil
+}
+
+// Remove 删除指定备份
+func (s *Service) Remove(name string) error {
+	path, err := s.Path(name)
+	if err != nil {
+		return err
+	}
+	if err := os.Remove(path); err != nil {
+		if os.IsNotExist(err) {
+			return fmt.Errorf("备份不存在")
+		}
+		return err
+	}
+	return nil
+}
+
+// Verify 回读归档并返回条目数：确认这份备份不是写了一半的残件，
+// 同时要求包内必须有 havline.db（否则多半不是 Havline 的备份）。
+func (s *Service) Verify(ctx context.Context, path string) (int, error) {
+	file, err := os.Open(path)
+	if err != nil {
+		return 0, err
+	}
+	defer file.Close()
+
+	gr, err := gzip.NewReader(file)
+	if err != nil {
+		return 0, fmt.Errorf("备份文件无法解压：%w", err)
+	}
+	defer gr.Close()
+
+	tr := tar.NewReader(gr)
+	count := 0
+	hasDatabase := false
+	for {
+		header, err := tr.Next()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			return count, fmt.Errorf("备份文件已损坏：%w", err)
+		}
+		if err := ctx.Err(); err != nil {
+			return count, err
+		}
+		count++
+		if header.Name == "havline.db" {
+			hasDatabase = true
+		}
+	}
+	if !hasDatabase {
+		return count, fmt.Errorf("备份里没有 havline.db，可能不是 Havline 的备份")
+	}
+	return count, nil
+}
+
+// KeepCount 读取保留份数（未配置或越界时回落到默认值）。
+// 自动备份任务与「立即备份」共用它，避免两处各写一套默认值。
+func KeepCount(ctx context.Context, store *settings.Store) int {
+	keep, err := store.GetInt(ctx, settings.KeyBackupKeepCount)
+	if err != nil || keep <= 0 {
+		return DefaultKeepCount
+	}
+	if keep > MaxKeepCount {
+		return MaxKeepCount
+	}
+	return keep
+}

app-src/internal/backup/auto.go

@@ -0,0 +1,89 @@
+package backup
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"path/filepath"
+	"time"
+
+	"github.com/havline/havline/internal/notify"
+	"github.com/havline/havline/internal/settings"
+)
+
+// AutoInterval 自动备份间隔。scheduler 启动时会先跑一轮，靠「最新备份是否还在间隔内」
+// 判断该不该备份，因此频繁重启（NAS 上很常见）不会重复备份。
+const AutoInterval = 24 * time.Hour
+
+// AutoRunner 定期导出一份归档、回读校验、再按保留份数剪枝。
+type AutoRunner struct {
+	svc      *Service
+	settings *settings.Store
+	notify   *notify.Service
+	logger   *slog.Logger
+	now      func() time.Time
+}
+
+func NewAutoRunner(svc *Service, settingsStore *settings.Store, notifySvc *notify.Service, logger *slog.Logger) *AutoRunner {
+	if logger == nil {
+		logger = slog.Default()
+	}
+	return &AutoRunner{svc: svc, settings: settingsStore, notify: notifySvc, logger: logger, now: time.Now}
+}
+
+// Run 跑一轮。失败只通知、不返回错误：scheduler 的任务没有重试机制，通知才是可见性来源。
+func (r *AutoRunner) Run(ctx context.Context) {
+	if r == nil || r.svc == nil || r.settings == nil {
+		return
+	}
+	enabled, err := r.settings.GetBool(ctx, settings.KeyBackupAutoEnabled)
+	if err != nil || !enabled {
+		return
+	}
+
+	archives, err := r.svc.List()
+	if err != nil {
+		r.logger.Warn("读取备份列表失败", "module", "BACKUP", "error", err.Error())
+		return
+	}
+	if len(archives) > 0 && !dueForBackup(archives[0].ModTime, r.now(), AutoInterval) {
+		return
+	}
+
+	path, err := r.svc.Export(ctx)
+	if err != nil {
+		r.fail(ctx, fmt.Sprintf("导出备份失败：%s", err.Error()))
+		return
+	}
+	entries, err := r.svc.Verify(ctx, path)
+	if err != nil {
+		// 校验不过的归档不算一份可用备份：删掉并如实告警，别让用户以为已经有备份
+		if removeErr := r.svc.Remove(filepath.Base(path)); removeErr != nil {
+			r.logger.Warn("删除校验失败的备份失败", "module", "BACKUP", "error", removeErr.Error())
+		}
+		r.fail(ctx, fmt.Sprintf("备份校验失败：%s", err.Error()))
+		return
+	}
+
+	removed, err := r.svc.Prune(KeepCount(ctx, r.settings))
+	if err != nil {
+		r.logger.Warn("剪枝旧备份失败", "module", "BACKUP", "error", err.Error())
+	}
+	r.logger.Info("自动备份完成", "module", "BACKUP",
+		"file", filepath.Base(path), "entries", entries, "removed", removed)
+}
+
+// dueForBackup 判断该不该做一次备份：没有备份，或最新一份已超过间隔。
+func dueForBackup(newest, now time.Time, interval time.Duration) bool {
+	if newest.IsZero() {
+		return true
+	}
+	return now.Sub(newest) >= interval
+}
+
+func (r *AutoRunner) fail(ctx context.Context, message string) {
+	r.logger.Error("自动备份失败", "module", "BACKUP", "error", message)
+	if r.notify != nil {
+		r.notify.Alert(ctx, notify.EventBackupFailure, "自动备份失败", message)
+	}
+}

app-src/internal/backup/auto_test.go

@@ -0,0 +1,130 @@
+package backup
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+func TestDueForBackup(t *testing.T) {
+	now := time.Date(2026, 9, 25, 10, 0, 0, 0, time.UTC)
+
+	// 还没有备份 → 立刻做一份
+	if !dueForBackup(time.Time{}, now, AutoInterval) {
+		t.Fatal("没有备份时应立即备份")
+	}
+	// 刚备份过 → 跳过：这正是重启不会重复备份的原因
+	if dueForBackup(now.Add(-time.Hour), now, AutoInterval) {
+		t.Fatal("间隔内的备份不应重复执行")
+	}
+	// 正好到间隔 → 该做了
+	if !dueForBackup(now.Add(-AutoInterval), now, AutoInterval) {
+		t.Fatal("到达间隔应再备份一次")
+	}
+	// 超过间隔 → 该做
+	if !dueForBackup(now.Add(-25*time.Hour), now, AutoInterval) {
+		t.Fatal("超过间隔应再备份一次")
+	}
+}
+
+func TestExportVerifyRoundTrip(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "havline.db"), []byte("db"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	svc := New(dir)
+
+	path, err := svc.Export(context.Background())
+	if err != nil {
+		t.Fatalf("export: %v", err)
+	}
+	entries, err := svc.Verify(context.Background(), path)
+	if err != nil {
+		t.Fatalf("verify: %v", err)
+	}
+	if entries < 1 {
+		t.Fatalf("条目数应至少为 1，实际 %d", entries)
+	}
+
+	archives, err := svc.List()
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if len(archives) != 1 {
+		t.Fatalf("应列出 1 份备份，实际 %d", len(archives))
+	}
+	if archives[0].Size == 0 || !archiveNamePattern.MatchString(archives[0].Name) {
+		t.Fatalf("备份条目异常：%+v", archives[0])
+	}
+}
+
+func TestVerifyRejectsGarbage(t *testing.T) {
+	svc := New(t.TempDir())
+	path := filepath.Join(svc.backupsDir(), "havline-backup-20260925-000000-1.tar.gz")
+	if err := os.MkdirAll(svc.backupsDir(), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte("not a gzip stream"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := svc.Verify(context.Background(), path); err == nil {
+		t.Fatal("非 gzip 内容应校验失败")
+	}
+}
+
+func TestListPruneAndPath(t *testing.T) {
+	svc := New(t.TempDir())
+	if err := os.MkdirAll(svc.backupsDir(), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	for _, name := range []string{
+		"havline-backup-20260923-100000-1.tar.gz",
+		"havline-backup-20260924-100000-2.tar.gz",
+		"havline-backup-20260925-100000-3.tar.gz",
+	} {
+		if err := os.WriteFile(filepath.Join(svc.backupsDir(), name), []byte("x"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	// 不符合命名格式的文件不参与：备份目录里可能混着手工放进来的东西
+	if err := os.WriteFile(filepath.Join(svc.backupsDir(), "notes.txt"), []byte("x"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	archives, err := svc.List()
+	if err != nil {
+		t.Fatalf("list: %v", err)
+	}
+	if len(archives) != 3 {
+		t.Fatalf("应只列出 3 份备份，实际 %d", len(archives))
+	}
+	if archives[0].Name != "havline-backup-20260925-100000-3.tar.gz" {
+		t.Fatalf("应按时间倒序，实际首条 %s", archives[0].Name)
+	}
+
+	removed, err := svc.Prune(2)
+	if err != nil {
+		t.Fatalf("prune: %v", err)
+	}
+	if removed != 1 {
+		t.Fatalf("应删除 1 份，实际 %d", removed)
+	}
+	if archives, _ = svc.List(); len(archives) != 2 {
+		t.Fatalf("剪枝后应剩 2 份，实际 %d", len(archives))
+	}
+
+	// 名称校验：不能让备份名把读写带出备份目录
+	for _, name := range []string{"../havline.db", "notes.txt", "", "havline-backup-x.tar.gz"} {
+		if _, err := svc.Path(name); err == nil {
+			t.Fatalf("非法备份名应拒绝：%q", name)
+		}
+	}
+	if err := svc.Remove("havline-backup-20260920-100000-9.tar.gz"); err == nil {
+		t.Fatal("删除不存在的备份应报错")
+	}
+	if _, err := svc.Prune(0); err != nil {
+		t.Fatalf("keep<=0 应直接返回：%v", err)
+	}
+}

app-src/internal/backup/service.go

@@ -0,0 +1,194 @@
+package backup
+
+import (
+	"archive/tar"
+	"compress/gzip"
+	"context"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"time"
+)
+
+type Service struct {
+	dataDir string
+}
+
+// 还原时的固定权限：备份内容只有数据库、证书与 nginx 配置，不接受归档自带的权限位
+const (
+	restoreFileMode = 0o640
+	restoreDirMode  = 0o750
+)
+
+func New(dataDir string) *Service {
+	return &Service{dataDir: dataDir}
+}
+
+// backupTimeFmt 归档文件名里的时间戳；List / Path 都按同一套格式校验
+const backupTimeFmt = "20060102-150405"
+
+// Export 导出一份归档并返回路径；文件留在 <DataDir>/backups 下，由调用方决定下载后删除还是长期保留。
+func (s *Service) Export(ctx context.Context) (string, error) {
+	if err := os.MkdirAll(s.backupsDir(), 0o755); err != nil {
+		return "", err
+	}
+	// CreateTemp 保证同一秒内多次导出不会覆盖已有备份（文件名带随机后缀）
+	file, err := os.CreateTemp(s.backupsDir(), fmt.Sprintf("havline-backup-%s-*.tar.gz", time.Now().Format(backupTimeFmt)))
+	if err != nil {
+		return "", err
+	}
+	outPath := file.Name()
+	if err := s.writeArchive(ctx, file, outPath); err != nil {
+		return "", err
+	}
+	return outPath, nil
+}
+
+// writeArchive 写归档，逐层检查关闭错误。
+//
+// Close 的错误必须往上抛：tar/gzip 的尾部与文件系统的 flush 都发生在 Close，
+// 忽略它就会出现「备份文件不完整、函数却返回成功」——这是最坏的一种假成功。
+// 任一步失败都删掉半成品，不留一个看起来能用的备份。
+func (s *Service) writeArchive(ctx context.Context, file *os.File, outPath string) error {
+	discard := func() {
+		_ = file.Close()
+		_ = os.Remove(outPath)
+	}
+
+	gw := gzip.NewWriter(file)
+	tw := tar.NewWriter(gw)
+	for _, entry := range []string{"havline.db", "certs", "nginx", "cloudflared/tunnels"} {
+		if err := addToArchive(ctx, tw, s.dataDir, entry); err != nil {
+			discard()
+			return err
+		}
+	}
+	if err := tw.Close(); err != nil {
+		discard()
+		return err
+	}
+	if err := gw.Close(); err != nil {
+		discard()
+		return err
+	}
+	if err := file.Close(); err != nil {
+		_ = os.Remove(outPath)
+		return err
+	}
+	return nil
+}
+
+func (s *Service) Restore(ctx context.Context, archivePath string) error {
+	file, err := os.Open(archivePath)
+	if err != nil {
+		return err
+	}
+	defer file.Close()
+
+	gr, err := gzip.NewReader(file)
+	if err != nil {
+		return fmt.Errorf("无效的备份文件")
+	}
+	defer gr.Close()
+
+	tr := tar.NewReader(gr)
+	for {
+		header, err := tr.Next()
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			return err
+		}
+		if header.Typeflag != tar.TypeReg && header.Typeflag != tar.TypeDir {
+			continue
+		}
+		target := filepath.Join(s.dataDir, header.Name)
+		// 归档条目必须落在 DataDir 内：前缀比较会被 ../data-other 这类同前缀路径绕过，用 Rel 判定
+		rel, err := filepath.Rel(s.dataDir, target)
+		if err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+			return fmt.Errorf("备份条目非法: %s", header.Name)
+		}
+		switch header.Typeflag {
+		case tar.TypeDir:
+			if err := os.MkdirAll(target, restoreDirMode); err != nil {
+				return err
+			}
+		case tar.TypeReg:
+			if err := os.MkdirAll(filepath.Dir(target), restoreDirMode); err != nil {
+				return err
+			}
+			// 归档里的权限位不照搬（构造的归档可带 0777 / 执行位）：备份内容只有数据库、证书与 nginx 配置
+			out, err := os.OpenFile(target, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, restoreFileMode)
+			if err != nil {
+				return err
+			}
+			if _, err := io.Copy(out, tr); err != nil {
+				out.Close()
+				return err
+			}
+			out.Close()
+		}
+	}
+	return nil
+}
+
+func addToArchive(ctx context.Context, tw *tar.Writer, baseDir, rel string) error {
+	path := filepath.Join(baseDir, rel)
+	info, err := os.Stat(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil
+		}
+		return err
+	}
+	if info.IsDir() {
+		return addDir(ctx, tw, baseDir, rel)
+	}
+	return addFile(tw, baseDir, rel, info)
+}
+
+func addDir(ctx context.Context, tw *tar.Writer, baseDir, rel string) error {
+	root := filepath.Join(baseDir, rel)
+	return filepath.WalkDir(root, func(path string, d os.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if d.IsDir() {
+			return nil
+		}
+		if strings.Contains(path, string(os.PathSeparator)+"backups"+string(os.PathSeparator)) {
+			return nil
+		}
+		info, err := d.Info()
+		if err != nil {
+			return err
+		}
+		relPath, err := filepath.Rel(baseDir, path)
+		if err != nil {
+			return err
+		}
+		return addFile(tw, baseDir, relPath, info)
+	})
+}
+
+func addFile(tw *tar.Writer, baseDir, rel string, info os.FileInfo) error {
+	path := filepath.Join(baseDir, rel)
+	file, err := os.Open(path)
+	if err != nil {
+		return err
+	}
+	defer file.Close()
+	header, err := tar.FileInfoHeader(info, "")
+	if err != nil {
+		return err
+	}
+	header.Name = filepath.ToSlash(rel)
+	if err := tw.WriteHeader(header); err != nil {
+		return err
+	}
+	_, err = io.Copy(tw, file)
+	return err
+}

app-src/internal/backup/service_test.go

@@ -0,0 +1,130 @@
+package backup
+
+import (
+	"archive/tar"
+	"compress/gzip"
+	"context"
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+)
+
+// writeArchive 造一个含指定条目的 tar.gz，用于验证还原侧的路径校验与权限处理。
+func writeArchive(t *testing.T, entries map[string]string) string {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "backup.tar.gz")
+	file, err := os.Create(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer file.Close()
+	gz := gzip.NewWriter(file)
+	tw := tar.NewWriter(gz)
+	for name, content := range entries {
+		header := &tar.Header{Name: name, Mode: 0o777, Size: int64(len(content)), Typeflag: tar.TypeReg}
+		if err := tw.WriteHeader(header); err != nil {
+			t.Fatal(err)
+		}
+		if _, err := tw.Write([]byte(content)); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if err := tw.Close(); err != nil {
+		t.Fatal(err)
+	}
+	if err := gz.Close(); err != nil {
+		t.Fatal(err)
+	}
+	return path
+}
+
+// TestRestoreRejectsEscapingEntries 覆盖「同前缀绕过」：旧实现用 strings.HasPrefix 判断，
+// DataDir=/data 时 ../data-other/x 会通过前缀匹配写到 DataDir 之外。
+func TestRestoreRejectsEscapingEntries(t *testing.T) {
+	root := t.TempDir()
+	dataDir := filepath.Join(root, "data")
+	if err := os.MkdirAll(dataDir, 0o750); err != nil {
+		t.Fatal(err)
+	}
+	archive := writeArchive(t, map[string]string{"../data-other/evil.txt": "x"})
+	if err := New(dataDir).Restore(context.Background(), archive); err == nil {
+		t.Fatal("应当拒绝逃出 DataDir 的条目")
+	}
+	if _, err := os.Stat(filepath.Join(root, "data-other", "evil.txt")); err == nil {
+		t.Fatal("逃逸条目被写到了 DataDir 之外")
+	}
+}
+
+func TestRestoreRejectsParentEscape(t *testing.T) {
+	root := t.TempDir()
+	dataDir := filepath.Join(root, "data")
+	if err := os.MkdirAll(dataDir, 0o750); err != nil {
+		t.Fatal(err)
+	}
+	archive := writeArchive(t, map[string]string{"../../evil.txt": "x"})
+	if err := New(dataDir).Restore(context.Background(), archive); err == nil {
+		t.Fatal("应当拒绝带 .. 的条目")
+	}
+}
+
+// TestRestoreAppliesFixedMode：归档里的权限位不照搬（构造的归档可带 0777 / 执行位）。
+func TestRestoreAppliesFixedMode(t *testing.T) {
+	dataDir := t.TempDir()
+	archive := writeArchive(t, map[string]string{"nginx/nginx.conf": "worker_processes 1;"})
+	if err := New(dataDir).Restore(context.Background(), archive); err != nil {
+		t.Fatal(err)
+	}
+	info, err := os.Stat(filepath.Join(dataDir, "nginx", "nginx.conf"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := info.Mode().Perm(); runtime.GOOS == "windows" {
+		// Windows 不保留 Unix 权限位（可写文件统一报 0666）：只断言没带上执行位
+		if got&0o111 != 0 {
+			t.Fatalf("还原后的文件不应带执行位，实际 %o", got)
+		}
+	} else if got != restoreFileMode {
+		t.Fatalf("还原后的权限应为 %o，实际 %o", restoreFileMode, got)
+	}
+}
+
+func TestExportIncludesCloudflareTunnelConfig(t *testing.T) {
+	dataDir := t.TempDir()
+	tunnelDir := filepath.Join(dataDir, "cloudflared", "tunnels", "home")
+	if err := os.MkdirAll(tunnelDir, 0o750); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(tunnelDir, "config.yml"), []byte("tunnel: test\n"), 0o640); err != nil {
+		t.Fatal(err)
+	}
+	path, err := New(dataDir).Export(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	file, err := os.Open(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer file.Close()
+	gr, err := gzip.NewReader(file)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer gr.Close()
+	tr := tar.NewReader(gr)
+	found := false
+	for {
+		header, err := tr.Next()
+		if err != nil {
+			break
+		}
+		if header.Name == "cloudflared/tunnels/home/config.yml" {
+			found = true
+			break
+		}
+	}
+	if !found {
+		t.Fatal("备份应包含 Cloudflare 隧道配置")
+	}
+}