fix: 收敛正确性缺口并补齐质量门禁

备份、隧道生命周期、日志、会话与设置项存在一批「静默失效」问题，本次一并收敛。

正确性：
- 备份归档补上 session_secret 与 frp 配置。缺密钥时换机恢复后库里所有凭据都解不开，
  界面表现为「配置都在、一执行就报解密失败」；同时支持口令加密（scrypt + AES-256-GCM）。
- 修复「立即备份」必失败：tar 头用的是遍历时的文件尺寸，而 logs、frpc 配置在打包期间
  还在增长，读出的字节多于声明值导致 archive/tar 报错、整份备份作废。改为打开后重新
  取尺寸并用 LimitReader 兜住，被截短时补零保持条目结构完整。
- 数据库改用 VACUUM INTO 生成一致性快照。直接打包正在写入的 SQLite 文件可能得到
  结构完整但内容自相矛盾的副本，恢复后才暴露。
- Cloudflare 启动改用 StartAuto，Shutdown 显式 StopAll，子进程绑定应用 ctx。此前
  重启会把用户手动停掉的隧道重新拉起，退出也可能留下孤儿进程。
- Nginx 访问/错误日志加轮转（200MB 阈值、gzip 归档、USR1 重开），读取改为从文件尾
  分块倒读，并跨当日归档统计。此前日志只增不减，读接口每次全量扫描。
- 过期会话改由日任务清理；删除反代规则时同步清掉流量累计，避免同名规则重建继承旧读数。
- 启动加就绪门：Nginx bootstrap 完成后再放行 FRP 对账、Agent 隧道与 Cloudflare 自启。

设置项：
- 新增设置项注册表（internal/settings/registry.go），白名单与默认值从它派生，
  并记录每个键的消费者，防止再出现「界面能改、后端没人读」的黑洞设置。
- 接上三个此前不生效的设置项：timezone（启动与保存时应用到 time.Local）、
  theme（后端为权威源，挂载时覆盖本地偏好、顶栏切换回写）、log_retention_days
  （控制日志归档保留天数）。

工程质量：
- gofmt 全量格式化 23 个历史文件，CI 增加格式化门禁。
- 前端引入 ESLint（flat config）与 lint 脚本，CI 增加 lint 步骤；顺带修掉
  logDisplay 的 let→const 与 LogsView 模板内直接改 prop 两处问题。
- 删除无引用的 pnpm-lock.yaml，prototype/ 加入忽略列表。
- 打包版本对齐：Docker manifest 同步到 2.0.0，CI 校验 VERSION 与 package.json 一致。

验证：gofmt 0 文件、go vet、go test ./...、npm run lint/typecheck/test/build 全绿。

Generated with [Devin](https://devin.ai)

Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>

internal/backup/archive.go

@@ -10,6 +10,7 @@ import (
 	"path/filepath"
 	"regexp"
 	"sort"
+	"strings"
 	"time"
 
 	"github.com/havline/havline/internal/settings"
@@ -106,13 +107,37 @@ func (s *Service) Remove(name string) error {
 // Verify 回读归档并返回条目数：确认这份备份不是写了一半的残件，
 // 同时要求包内必须有 havline.db（否则多半不是 Havline 的备份）。
 func (s *Service) Verify(ctx context.Context, path string) (int, error) {
+	return s.VerifyWith(ctx, path, Options{})
+}
+
+// VerifyWith 校验归档；加密归档需要提供口令才能验证内容。
+// 自动备份若启用口令，必须把口令传进来，否则一份好备份会被判成坏包而删掉。
+func (s *Service) VerifyWith(ctx context.Context, path string, opts Options) (int, error) {
+	encrypted, err := IsEncrypted(path)
+	if err != nil {
+		return 0, err
+	}
+
 	file, err := os.Open(path)
 	if err != nil {
 		return 0, err
 	}
 	defer file.Close()
 
-	gr, err := gzip.NewReader(file)
+	var reader io.Reader = file
+	if encrypted {
+		passphrase := strings.TrimSpace(opts.Passphrase)
+		if passphrase == "" {
+			return 0, ErrPassphraseRequired
+		}
+		plain, err := openSealedFile(file, passphrase)
+		if err != nil {
+			return 0, err
+		}
+		reader = plain
+	}
+
+	gr, err := gzip.NewReader(reader)
 	if err != nil {
 		return 0, fmt.Errorf("备份文件无法解压：%w", err)
 	}
@@ -121,6 +146,7 @@ func (s *Service) Verify(ctx context.Context, path string) (int, error) {
 	tr := tar.NewReader(gr)
 	count := 0
 	hasDatabase := false
+	hasSecret := false
 	for {
 		header, err := tr.Next()
 		if err == io.EOF {
@@ -133,16 +159,69 @@ func (s *Service) Verify(ctx context.Context, path string) (int, error) {
 			return count, err
 		}
 		count++
-		if header.Name == "havline.db" {
+		switch header.Name {
+		case "havline.db":
 			hasDatabase = true
+		case "session_secret":
+			hasSecret = true
 		}
 	}
 	if !hasDatabase {
 		return count, fmt.Errorf("备份里没有 havline.db，可能不是 Havline 的备份")
 	}
+	// 缺少 session_secret 的归档不能判成坏包（旧版本导出的备份本来就长这样，
+	// 而且数据库与证书都还在，多半仍值得恢复），只是恢复后凭据解不开。
+	// 这个差别交给 MissingSessionSecret 单独告知调用方，别混进校验错误里。
+	_ = hasSecret
 	return count, nil
 }
 
+// MissingSessionSecret 判断归档是否缺少凭据加密密钥。
+// 只服务于「恢复后要不要提示用户」，不参与备份有效性判定。
+func (s *Service) MissingSessionSecret(ctx context.Context, path string, opts Options) (bool, error) {
+	encrypted, err := IsEncrypted(path)
+	if err != nil {
+		return false, err
+	}
+	file, err := os.Open(path)
+	if err != nil {
+		return false, err
+	}
+	defer file.Close()
+
+	var reader io.Reader = file
+	if encrypted {
+		passphrase := strings.TrimSpace(opts.Passphrase)
+		if passphrase == "" {
+			return false, ErrPassphraseRequired
+		}
+		plain, err := openSealedFile(file, passphrase)
+		if err != nil {
+			return false, err
+		}
+		reader = plain
+	}
+	gr, err := gzip.NewReader(reader)
+	if err != nil {
+		return false, fmt.Errorf("备份文件无法解压：%w", err)
+	}
+	defer gr.Close()
+
+	tr := tar.NewReader(gr)
+	for {
+		header, err := tr.Next()
+		if err == io.EOF {
+			return true, nil
+		}
+		if err != nil {
+			return false, err
+		}
+		if header.Name == "session_secret" {
+			return false, nil
+		}
+	}
+}
+
 // KeepCount 读取保留份数（未配置或越界时回落到默认值）。
 // 自动备份任务与「立即备份」共用它，避免两处各写一套默认值。
 func KeepCount(ctx context.Context, store *settings.Store) int {

internal/backup/auto.go

@@ -50,6 +50,8 @@ func (r *AutoRunner) Run(ctx context.Context) {
 		return
 	}
 
+	// 自动备份不加密：口令没法安全地存在同一台设备上（存了就等于没加密），
+	// 需要加密归档的用户走「立即备份 / 立即下载」手动流程。
 	path, err := r.svc.Export(ctx)
 	if err != nil {
 		r.fail(ctx, fmt.Sprintf("导出备份失败：%s", err.Error()))

internal/backup/crypto.go

@@ -0,0 +1,148 @@
+package backup
+
+import (
+	"bytes"
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/rand"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+
+	"golang.org/x/crypto/scrypt"
+)
+
+// 加密归档的容器格式：magic + salt + nonce + AES-256-GCM 密文。
+//
+// 为什么不用「拿 session_secret 直接加密」：那份密钥本来就在数据目录里，
+// 跟着归档一起发出去等于没加密。用户填的口令才是唯一不随文件流动的东西。
+var encMagic = []byte("HAVLINE-ENC1\n")
+
+// ErrPassphraseRequired 表示这份归档被口令加密过，必须提供口令才能读取。
+var ErrPassphraseRequired = errors.New("该备份已加密，需要提供口令")
+
+// 加密参数：默认值在 NAS 这类低功耗设备上约需几十到一百毫秒，
+// 对「一天一次备份」完全可接受，同时把离线爆破成本抬到足够高。
+const (
+	scryptN       = 1 << 15
+	scryptR       = 8
+	scryptP       = 1
+	scryptKeyLen  = 32
+	scryptSaltLen = 16
+)
+
+// IsEncrypted 判断一份归档是否被口令加密（只读开头几个字节）。
+func IsEncrypted(path string) (bool, error) {
+	file, err := os.Open(path)
+	if err != nil {
+		return false, err
+	}
+	defer file.Close()
+	head := make([]byte, len(encMagic))
+	if _, err := io.ReadFull(file, head); err != nil {
+		// 短到连 magic 都放不下：只能是空文件或残件，交给后续解压去报错
+		return false, nil
+	}
+	return string(head) == string(encMagic), nil
+}
+
+// sealFile 把 src 全量读出，加密后写进 dst。
+// 备份受「恢复上传 64MB」这一上限约束，整份读进内存是可控的，
+// 换来的是不需要自己拼分块 GCM 的复杂度。
+func sealFile(dst io.Writer, src io.Reader, passphrase string) error {
+	if passphrase == "" {
+		return fmt.Errorf("口令不能为空")
+	}
+	salt := make([]byte, scryptSaltLen)
+	if _, err := rand.Read(salt); err != nil {
+		return err
+	}
+	key, err := deriveKey(passphrase, salt)
+	if err != nil {
+		return err
+	}
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return err
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return err
+	}
+	nonce := make([]byte, gcm.NonceSize())
+	if _, err := rand.Read(nonce); err != nil {
+		return err
+	}
+	plain, err := io.ReadAll(src)
+	if err != nil {
+		return err
+	}
+
+	// magic 作为附加认证数据：容器格式被改动（比如换成别的格式）时解密直接失败
+	if _, err := dst.Write(encMagic); err != nil {
+		return err
+	}
+	if _, err := dst.Write(salt); err != nil {
+		return err
+	}
+	if _, err := dst.Write(nonce); err != nil {
+		return err
+	}
+	_, err = dst.Write(gcm.Seal(nil, nonce, plain, encMagic))
+	return err
+}
+
+// openFile 解开一份加密归档，返回可读的明文流。
+func openSealedFile(src io.Reader, passphrase string) (io.Reader, error) {
+	head := make([]byte, len(encMagic))
+	if _, err := io.ReadFull(src, head); err != nil {
+		return nil, fmt.Errorf("无效的备份文件")
+	}
+	if string(head) != string(encMagic) {
+		return nil, fmt.Errorf("无效的备份文件")
+	}
+	salt := make([]byte, scryptSaltLen)
+	if _, err := io.ReadFull(src, salt); err != nil {
+		return nil, fmt.Errorf("备份文件已损坏")
+	}
+	key, err := deriveKey(passphrase, salt)
+	if err != nil {
+		return nil, err
+	}
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, err
+	}
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return nil, err
+	}
+	nonce := make([]byte, gcm.NonceSize())
+	if _, err := io.ReadFull(src, nonce); err != nil {
+		return nil, fmt.Errorf("备份文件已损坏")
+	}
+	ciphertext, err := io.ReadAll(src)
+	if err != nil {
+		return nil, err
+	}
+	plain, err := gcm.Open(nil, nonce, ciphertext, encMagic)
+	if err != nil {
+		// 校验失败只说明「密钥不对或内容被改过」，对用户是同一件事
+		return nil, fmt.Errorf("口令错误，或备份文件已被修改")
+	}
+	return newByteReader(plain), nil
+}
+
+// newByteReader 把内存里的明文包成 io.Reader；抽出来是为了让调用点读起来短一点。
+func newByteReader(data []byte) io.Reader {
+	return bytes.NewReader(data)
+}
+
+func deriveKey(passphrase string, salt []byte) ([]byte, error) {
+	key, err := scrypt.Key([]byte(passphrase), salt, scryptN, scryptR, scryptP, scryptKeyLen)
+	if err != nil {
+		return nil, fmt.Errorf("派生加密密钥失败: %w", err)
+	}
+	return key, nil
+}

internal/backup/encryption_test.go

@@ -0,0 +1,269 @@
+package backup
+
+import (
+	"archive/tar"
+	"compress/gzip"
+	"context"
+	"errors"
+	"io"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// listEntries 读出归档里的条目名，用于断言包含关系。
+func listEntries(t *testing.T, path string) []string {
+	t.Helper()
+	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)
+	names := []string{}
+	for {
+		header, err := tr.Next()
+		if err == io.EOF {
+			return names
+		}
+		if err != nil {
+			t.Fatal(err)
+		}
+		names = append(names, header.Name)
+	}
+}
+
+// TestExportIncludesSessionSecretAndFrpConfig：备份必须带上凭据加密密钥与 frpc 配置。
+// 少了 session_secret，恢复后库里的 DDNS / FRP / Cloudflare / 通知凭据全部解不开。
+func TestExportIncludesSessionSecretAndFrpConfig(t *testing.T) {
+	dataDir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dataDir, "havline.db"), []byte("db"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dataDir, "session_secret"), []byte("secret"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	frpDir := filepath.Join(dataDir, "frp")
+	if err := os.MkdirAll(frpDir, 0o750); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(frpDir, "frpc-server-1.toml"), []byte("token = \"x\"\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	path, err := New(dataDir).Export(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	entries := listEntries(t, path)
+	has := map[string]bool{}
+	for _, name := range entries {
+		has[name] = true
+	}
+	for _, want := range []string{"havline.db", "session_secret", "frp/frpc-server-1.toml"} {
+		if !has[want] {
+			t.Fatalf("备份应包含 %q，实际条目：%v", want, entries)
+		}
+	}
+}
+
+// TestExportSkipsFrpBinariesAndLogs：frp/bin、frp/downloads 与 *.log 体积大且可重新获取，不进归档。
+func TestExportSkipsFrpBinariesAndLogs(t *testing.T) {
+	dataDir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dataDir, "havline.db"), []byte("db"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	frpDir := filepath.Join(dataDir, "frp")
+	for _, dir := range []string{filepath.Join(frpDir, "bin", "v0.70.1"), filepath.Join(frpDir, "downloads")} {
+		if err := os.MkdirAll(dir, 0o750); err != nil {
+			t.Fatal(err)
+		}
+	}
+	files := map[string]string{
+		filepath.Join(frpDir, "bin", "v0.70.1", "frpc"): "binary",
+		filepath.Join(frpDir, "downloads", "frpc.zip"):  "zip",
+		filepath.Join(frpDir, "frpc-server-1.log"):      "log",
+		filepath.Join(frpDir, "frpc-server-1.toml"):     "token = \"x\"\n",
+		filepath.Join(frpDir, "active.json"):            "{}",
+	}
+	for path, content := range files {
+		if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	path, err := New(dataDir).Export(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	entries := listEntries(t, path)
+	has := map[string]bool{}
+	for _, name := range entries {
+		has[name] = true
+	}
+	for _, skip := range []string{"frp/bin/v0.70.1/frpc", "frp/downloads/frpc.zip", "frp/frpc-server-1.log"} {
+		if has[skip] {
+			t.Fatalf("归档不应包含 %q，实际条目：%v", skip, entries)
+		}
+	}
+	for _, want := range []string{"frp/frpc-server-1.toml", "frp/active.json"} {
+		if !has[want] {
+			t.Fatalf("归档应保留 %q，实际条目：%v", want, entries)
+		}
+	}
+}
+
+// TestExportWithPassphraseIsEncrypted：给了口令就必须是加密容器，且不带口令读不出来。
+func TestExportWithPassphraseIsEncrypted(t *testing.T) {
+	dataDir := seedDataDir(t)
+	path, err := New(dataDir).ExportWith(context.Background(), Options{Passphrase: "correct horse"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	encrypted, err := IsEncrypted(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !encrypted {
+		t.Fatal("给了口令导出的归档应被标记为加密")
+	}
+
+	// 无口令恢复：必须明确报「需要口令」，而不是含糊的解压失败
+	target := t.TempDir()
+	if err := New(target).Restore(context.Background(), path); !errors.Is(err, ErrPassphraseRequired) {
+		t.Fatalf("无口令恢复应报 ErrPassphraseRequired，实际 %v", err)
+	}
+
+	// 错口令：GCM 校验失败
+	if err := New(target).RestoreWith(context.Background(), path, Options{Passphrase: "wrong"}); err == nil {
+		t.Fatal("错误口令不应恢复成功")
+	}
+
+	// 正确口令：能恢复出原来的文件内容
+	if err := New(target).RestoreWith(context.Background(), path, Options{Passphrase: "correct horse"}); err != nil {
+		t.Fatalf("正确口令应恢复成功：%v", err)
+	}
+	data, err := os.ReadFile(filepath.Join(target, "havline.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(data) != "db" {
+		t.Fatalf("恢复内容不符：%q", data)
+	}
+}
+
+// TestExportWithoutPassphraseStaysCompatible：不给口令时仍产出未加密归档，
+// 老版本与现有客户端可以直接解压。
+func TestExportWithoutPassphraseStaysCompatible(t *testing.T) {
+	dataDir := seedDataDir(t)
+	path, err := New(dataDir).Export(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	encrypted, err := IsEncrypted(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if encrypted {
+		t.Fatal("未给口令时的归档不应加密")
+	}
+	if _, err := New(t.TempDir()).Verify(context.Background(), path); err != nil {
+		t.Fatalf("未加密归档应能通过校验：%v", err)
+	}
+}
+
+// TestVerifyWithEncryptedArchiveNeedsPassphrase：加密归档校验同样需要口令，
+// 否则自动备份会把一份好备份判成坏包删掉。
+func TestVerifyWithEncryptedArchiveNeedsPassphrase(t *testing.T) {
+	dataDir := seedDataDir(t)
+	path, err := New(dataDir).ExportWith(context.Background(), Options{Passphrase: "pw"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := New(dataDir).Verify(context.Background(), path); !errors.Is(err, ErrPassphraseRequired) {
+		t.Fatalf("无口令校验应报 ErrPassphraseRequired，实际 %v", err)
+	}
+	count, err := New(dataDir).VerifyWith(context.Background(), path, Options{Passphrase: "pw"})
+	if err != nil {
+		t.Fatalf("带口令校验应通过：%v", err)
+	}
+	if count == 0 {
+		t.Fatal("校验应返回条目数")
+	}
+}
+
+// TestMissingSessionSecretDetectsLegacyArchive：旧归档没有 session_secret，
+// 能恢复但凭据解不开，要能被识别出来提示用户。
+func TestMissingSessionSecretDetectsLegacyArchive(t *testing.T) {
+	dataDir := t.TempDir()
+	// 手工造一个「只有 havline.db」的旧式归档
+	legacy := writeArchive(t, map[string]string{"havline.db": "db"})
+	svc := New(dataDir)
+
+	missing, err := svc.MissingSessionSecret(context.Background(), legacy, Options{})
+	if err != nil {
+		t.Fatalf("识别旧归档不应报错：%v", err)
+	}
+	if !missing {
+		t.Fatal("旧归档应被判定为缺少 session_secret")
+	}
+
+	fresh := seedExport(t, seedDataDir(t))
+	missing, err = svc.MissingSessionSecret(context.Background(), fresh, Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if missing {
+		t.Fatal("新归档包含 session_secret，不应判定为缺失")
+	}
+}
+
+// TestRestoreKeepsSecretPermissions：session_secret 还原后必须是 0600，
+// 否则同机其他用户就能读到解密凭据的钥匙。
+func TestRestoreKeepsSecretPermissions(t *testing.T) {
+	if os.PathSeparator == '\\' {
+		t.Skip("Windows 不保留 Unix 权限位")
+	}
+	dataDir := seedDataDir(t)
+	path, err := New(dataDir).Export(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	target := t.TempDir()
+	if err := New(target).Restore(context.Background(), path); err != nil {
+		t.Fatal(err)
+	}
+	info, err := os.Stat(filepath.Join(target, "session_secret"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := info.Mode().Perm(); got != restoreSecretMode {
+		t.Fatalf("session_secret 还原后权限应为 %o，实际 %o", restoreSecretMode, got)
+	}
+}
+
+func seedDataDir(t *testing.T) string {
+	t.Helper()
+	dataDir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dataDir, "havline.db"), []byte("db"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dataDir, "session_secret"), []byte("secret"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	return dataDir
+}
+
+func seedExport(t *testing.T, dataDir string) string {
+	t.Helper()
+	path, err := New(dataDir).Export(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	return path
+}

internal/backup/growing_test.go

@@ -0,0 +1,151 @@
+package backup
+
+import (
+	"archive/tar"
+	"compress/gzip"
+	"context"
+	"database/sql"
+	"io"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/havline/havline/internal/db"
+)
+
+// openTestDB 建一个跑过迁移的临时库，用于验证快照路径。
+func openTestDB(t *testing.T) (*sql.DB, error) {
+	t.Helper()
+	conn, err := db.Open(filepath.Join(t.TempDir(), "source.db"))
+	if err != nil {
+		return nil, err
+	}
+	if err := db.Migrate(context.Background(), conn, filepath.Join("..", "..", "migrations")); err != nil {
+		conn.Close()
+		return nil, err
+	}
+	return conn, nil
+}
+
+// TestExportSurvivesGrowingFiles 复现「立即备份」报 archive/tar: write too long 的现场。
+//
+// 成因：addFile 用 WalkDir 那一刻拿到的 FileInfo.Size() 写 tar 头，随后才去读文件内容。
+// 而 logs、frpc 配置这些文件在打包期间还在长，读到的字节多于头部声明，tar 直接报错、
+// 整份备份作废。这里的做法是让一个「边打包边追加」的写入者持续往文件里写。
+func TestExportSurvivesGrowingFiles(t *testing.T) {
+	dataDir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dataDir, "havline.db"), []byte("db"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	// 造一个会持续增长的文件，放在会被归档的目录下
+	frpDir := filepath.Join(dataDir, "frp")
+	if err := os.MkdirAll(frpDir, 0o750); err != nil {
+		t.Fatal(err)
+	}
+	growing := filepath.Join(frpDir, "frpc-server-1.toml")
+	if err := os.WriteFile(growing, []byte("token = \"x\"\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	stop := make(chan struct{})
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		chunk := []byte("padding = \"" + "0123456789abcdef" + "\"\n")
+		for {
+			select {
+			case <-stop:
+				return
+			default:
+			}
+			f, err := os.OpenFile(growing, os.O_APPEND|os.O_WRONLY, 0o600)
+			if err != nil {
+				return
+			}
+			_, _ = f.Write(chunk)
+			_ = f.Close()
+			time.Sleep(time.Millisecond)
+		}
+	}()
+
+	path, err := New(dataDir).Export(context.Background())
+	close(stop)
+	<-done
+
+	if err != nil {
+		t.Fatalf("文件在打包期间增长时导出不应失败：%v", err)
+	}
+	if _, err := New(dataDir).Verify(context.Background(), path); err != nil {
+		t.Fatalf("导出的归档应可校验：%v", err)
+	}
+}
+
+// TestExportUsesDatabaseSnapshot：注入数据库后，归档里的 havline.db 必须来自快照，
+// 而不是直接读主文件——主文件在写入时并不自洽。
+func TestExportUsesDatabaseSnapshot(t *testing.T) {
+	dataDir := t.TempDir()
+	// 故意在主文件里放一段「不是有效 SQLite」的内容：
+	// 若实现退回直接打包文件，归档里就会是这串字节。
+	if err := os.WriteFile(filepath.Join(dataDir, "havline.db"), []byte("not-a-valid-db"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dataDir, "session_secret"), []byte("secret"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	conn, err := openTestDB(t)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+
+	svc := New(dataDir)
+	svc.SetDB(conn)
+	path, err := svc.Export(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	content := readArchiveEntry(t, path, "havline.db")
+	if string(content) == "not-a-valid-db" {
+		t.Fatal("归档里的数据库应来自 VACUUM INTO 快照，而不是直接读取主文件")
+	}
+	// SQLite 文件头是 "SQLite format 3\x00"
+	if len(content) < 16 || string(content[:15]) != "SQLite format 3" {
+		t.Fatalf("快照应是有效 SQLite 文件，实际头部：%q", content[:min(16, len(content))])
+	}
+}
+
+func readArchiveEntry(t *testing.T, path, want string) []byte {
+	t.Helper()
+	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)
+	for {
+		header, err := tr.Next()
+		if err == io.EOF {
+			return nil
+		}
+		if err != nil {
+			t.Fatal(err)
+		}
+		if header.Name != want {
+			continue
+		}
+		data, err := io.ReadAll(tr)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return data
+	}
+}

internal/backup/realdata_test.go

@@ -0,0 +1,56 @@
+package backup
+
+import (
+	"context"
+	"os"
+	"testing"
+
+	"github.com/havline/havline/internal/db"
+)
+
+// TestExportRealData 用真实数据目录跑一遍完整导出，验证「立即备份」在实机上不再报
+// archive/tar: write too long，并且归档里确实带上了 session_secret 与 frp 配置。
+// 仅在设置了 HV_REAL_DATA 时执行，避免把本地数据依赖带进 CI。
+func TestExportRealData(t *testing.T) {
+	dir := os.Getenv("HV_REAL_DATA")
+	if dir == "" {
+		t.Skip("未设置 HV_REAL_DATA")
+	}
+	conn, err := db.Open(dir + "/havline.db")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+
+	svc := New(dir)
+	svc.SetDB(conn)
+	path, err := svc.Export(context.Background())
+	if err != nil {
+		t.Fatalf("导出失败：%v", err)
+	}
+	defer os.Remove(path)
+
+	entries, err := svc.Verify(context.Background(), path)
+	if err != nil {
+		t.Fatalf("校验失败：%v", err)
+	}
+	missing, err := svc.MissingSessionSecret(context.Background(), path, Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if missing {
+		t.Fatal("真实数据的归档应包含 session_secret")
+	}
+	t.Logf("导出成功：%s，条目 %d", path, entries)
+
+	// 有口令时也要能正常导出 + 校验
+	encPath, err := svc.ExportWith(context.Background(), Options{Passphrase: "test-pass"})
+	if err != nil {
+		t.Fatalf("加密导出失败：%v", err)
+	}
+	defer os.Remove(encPath)
+	if _, err := svc.VerifyWith(context.Background(), encPath, Options{Passphrase: "test-pass"}); err != nil {
+		t.Fatalf("加密归档校验失败：%v", err)
+	}
+	t.Logf("加密导出成功：%s", encPath)
+}

internal/backup/service.go

@@ -4,6 +4,7 @@ import (
 	"archive/tar"
 	"compress/gzip"
 	"context"
+	"database/sql"
 	"fmt"
 	"io"
 	"os"
@@ -14,36 +15,114 @@ import (
 
 type Service struct {
 	dataDir string
+	// db 用于把数据库导出成一致性快照。为 nil 时退回「直接打包数据库文件」，
+	// 后者只在测试或不接数据库的场景下使用。
+	db *sql.DB
 }
 
+// Options 是导出 / 恢复的可选项；Passphrase 非空时归档会被口令加密。
+type Options struct {
+	Passphrase string
+}
+
+// archiveEntries 是要打进归档的数据。
+//
+// 必须包含 session_secret：它同时是 secret.Box 的 AES-GCM 密钥，
+// 少了它则数据库里的 DDNS / FRP / Cloudflare / 通知凭据在换机恢复后全部解不开，
+// 界面表现为「配置都在，但一执行就报解密失败」。
+// 必须包含 frp：frpc 的 toml 里有明文 token，缺了它穿透服务需要重新配一遍。
+var archiveEntries = []string{"havline.db", "session_secret", "certs", "nginx", "frp", "cloudflared/tunnels"}
+
 // 还原时的固定权限：备份内容只有数据库、证书与 nginx 配置，不接受归档自带的权限位
 const (
 	restoreFileMode = 0o640
 	restoreDirMode  = 0o750
+	// 密钥文件的权限单独收紧：它是解密库里全部凭据的那把钥匙
+	restoreSecretMode = 0o600
 )
 
 func New(dataDir string) *Service {
 	return &Service{dataDir: dataDir}
 }
 
+// SetDB 注入数据库连接，导出一致性快照时使用。
+// 不放进 New 的签名里：现有调用点（含测试）很多只关心文件集合。
+func (s *Service) SetDB(db *sql.DB) {
+	s.db = db
+}
+
 // backupTimeFmt 归档文件名里的时间戳；List / Path 都按同一套格式校验
 const backupTimeFmt = "20060102-150405"
 
-// Export 导出一份归档并返回路径；文件留在 <DataDir>/backups 下，由调用方决定下载后删除还是长期保留。
+// Export 导出一份未加密归档并返回路径；文件留在 <DataDir>/backups 下，
+// 由调用方决定下载后删除还是长期保留。
 func (s *Service) Export(ctx context.Context) (string, error) {
+	return s.ExportWith(ctx, Options{})
+}
+
+// ExportWith 导出一份归档；Passphrase 非空时用口令加密。
+func (s *Service) ExportWith(ctx context.Context, opts Options) (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)))
+
+	// 先写到暂存文件：加密要先拿到完整的 tar.gz，且暂存名不匹配备份命名规则，
+	// 中途失败不会在列表里留下一个看起来能用的残件。
+	staging, err := os.CreateTemp(s.backupsDir(), "havline-backup-*.tar.gz.tmp")
 	if err != nil {
 		return "", err
 	}
-	outPath := file.Name()
-	if err := s.writeArchive(ctx, file, outPath); err != nil {
+	stagingPath := staging.Name()
+	defer os.Remove(stagingPath)
+	if err := s.writeArchive(ctx, staging, stagingPath); err != nil {
 		return "", err
 	}
-	return outPath, nil
+
+	// CreateTemp 保证同一秒内多次导出不会覆盖已有备份（文件名带随机后缀）
+	final, err := os.CreateTemp(s.backupsDir(), fmt.Sprintf("havline-backup-%s-*.tar.gz", time.Now().Format(backupTimeFmt)))
+	if err != nil {
+		return "", err
+	}
+	finalPath := final.Name()
+	if err := final.Close(); err != nil {
+		_ = os.Remove(finalPath)
+		return "", err
+	}
+	_ = os.Chmod(finalPath, 0o600)
+
+	passphrase := strings.TrimSpace(opts.Passphrase)
+	if passphrase == "" {
+		// 未加密：直接把暂存文件改名成正式备份名
+		if err := os.Remove(finalPath); err != nil && !os.IsNotExist(err) {
+			return "", err
+		}
+		if err := os.Rename(stagingPath, finalPath); err != nil {
+			return "", err
+		}
+		return finalPath, nil
+	}
+
+	src, err := os.Open(stagingPath)
+	if err != nil {
+		_ = os.Remove(finalPath)
+		return "", err
+	}
+	defer src.Close()
+	dst, err := os.OpenFile(finalPath, os.O_WRONLY|os.O_TRUNC, 0o600)
+	if err != nil {
+		_ = os.Remove(finalPath)
+		return "", err
+	}
+	if err := sealFile(dst, src, passphrase); err != nil {
+		_ = dst.Close()
+		_ = os.Remove(finalPath)
+		return "", err
+	}
+	if err := dst.Close(); err != nil {
+		_ = os.Remove(finalPath)
+		return "", err
+	}
+	return finalPath, nil
 }
 
 // writeArchive 写归档，逐层检查关闭错误。
@@ -59,7 +138,15 @@ func (s *Service) writeArchive(ctx context.Context, file *os.File, outPath strin
 
 	gw := gzip.NewWriter(file)
 	tw := tar.NewWriter(gw)
-	for _, entry := range []string{"havline.db", "certs", "nginx", "cloudflared/tunnels"} {
+	for _, entry := range archiveEntries {
+		// havline.db 走一致性快照，其余（证书 / nginx / frp / 密钥）直接打包
+		if entry == databaseName {
+			if err := s.addDatabase(ctx, tw); err != nil {
+				discard()
+				return err
+			}
+			continue
+		}
 		if err := addToArchive(ctx, tw, s.dataDir, entry); err != nil {
 			discard()
 			return err
@@ -80,14 +167,106 @@ func (s *Service) writeArchive(ctx context.Context, file *os.File, outPath strin
 	return nil
 }
 
+// databaseName 是归档里的数据库条目名，也是恢复时的落点文件名。
+const databaseName = "havline.db"
+
+// addDatabase 把数据库打成一份一致性快照。
+//
+// 不能直接读 havline.db 文件：SQLite 在写入过程中，主文件与 -wal / -journal
+// 的内容随时在变，直接 `cp` 出来的副本可能是「结构完整但内容自相矛盾」的库
+// （恢复后表现为表锁死、索引与数据不一致）。VACUUM INTO 由 SQLite 自己保证
+// 快照一致性，且不需要停机。
+func (s *Service) addDatabase(ctx context.Context, tw *tar.Writer) error {
+	if s.db == nil {
+		// 没接数据库（测试或旧调用点）：退回直接打包文件
+		return addToArchive(ctx, tw, s.dataDir, databaseName)
+	}
+
+	snapshot, err := os.CreateTemp("", "havline-snapshot-*.db")
+	if err != nil {
+		return err
+	}
+	snapshotPath := snapshot.Name()
+	// VACUUM INTO 要求目标文件不存在；CreateTemp 已经把文件创建出来了
+	if err := snapshot.Close(); err != nil {
+		_ = os.Remove(snapshotPath)
+		return err
+	}
+	if err := os.Remove(snapshotPath); err != nil {
+		return err
+	}
+	defer os.Remove(snapshotPath)
+
+	// 参数不能直接拼在 SQL 里（VACUUM INTO 支持字符串字面量，但不支持占位符），
+	// 所以这里做转义：路径里的单引号在 Windows 临时目录下可能出现。
+	quoted := strings.ReplaceAll(snapshotPath, "'", "''")
+	if _, err := s.db.ExecContext(ctx, `VACUUM INTO '`+quoted+`'`); err != nil {
+		return fmt.Errorf("导出数据库快照失败：%w", err)
+	}
+
+	info, err := os.Stat(snapshotPath)
+	if err != nil {
+		return err
+	}
+	file, err := os.Open(snapshotPath)
+	if err != nil {
+		return err
+	}
+	defer file.Close()
+
+	header, err := tar.FileInfoHeader(info, "")
+	if err != nil {
+		return err
+	}
+	header.Name = databaseName
+	header.Size = info.Size()
+	if err := tw.WriteHeader(header); err != nil {
+		return err
+	}
+	written, err := io.Copy(tw, io.LimitReader(file, info.Size()))
+	if err != nil {
+		return err
+	}
+	if written < info.Size() {
+		if _, err := io.CopyN(tw, zeroReader{}, info.Size()-written); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// Restore 还原一份未加密归档。
 func (s *Service) Restore(ctx context.Context, archivePath string) error {
+	return s.RestoreWith(ctx, archivePath, Options{})
+}
+
+// RestoreWith 还原归档；归档被口令加密时必须提供 Passphrase。
+func (s *Service) RestoreWith(ctx context.Context, archivePath string, opts Options) error {
+	encrypted, err := IsEncrypted(archivePath)
+	if err != nil {
+		return err
+	}
+
 	file, err := os.Open(archivePath)
 	if err != nil {
 		return err
 	}
 	defer file.Close()
 
-	gr, err := gzip.NewReader(file)
+	var reader io.Reader = file
+	if encrypted {
+		passphrase := strings.TrimSpace(opts.Passphrase)
+		if passphrase == "" {
+			return ErrPassphraseRequired
+		}
+		plain, err := openSealedFile(file, passphrase)
+		if err != nil {
+			return err
+		}
+		reader = plain
+	}
+
+	gr, err := gzip.NewReader(reader)
 	if err != nil {
 		return fmt.Errorf("无效的备份文件")
 	}
@@ -121,7 +300,7 @@ func (s *Service) Restore(ctx context.Context, archivePath string) error {
 				return err
 			}
 			// 归档里的权限位不照搬（构造的归档可带 0777 / 执行位）：备份内容只有数据库、证书与 nginx 配置
-			out, err := os.OpenFile(target, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, restoreFileMode)
+			out, err := os.OpenFile(target, os.O_CREATE|os.O_WRONLY|os.O_TRUNC, restoreModeFor(header.Name))
 			if err != nil {
 				return err
 			}
@@ -135,6 +314,14 @@ func (s *Service) Restore(ctx context.Context, archivePath string) error {
 	return nil
 }
 
+// restoreModeFor 决定还原后的权限：session_secret 是解密凭据的钥匙，单独收紧到 0600。
+func restoreModeFor(name string) os.FileMode {
+	if filepath.Base(filepath.ToSlash(name)) == "session_secret" {
+		return restoreSecretMode
+	}
+	return restoreFileMode
+}
+
 func addToArchive(ctx context.Context, tw *tar.Writer, baseDir, rel string) error {
 	path := filepath.Join(baseDir, rel)
 	info, err := os.Stat(path)
@@ -150,6 +337,24 @@ func addToArchive(ctx context.Context, tw *tar.Writer, baseDir, rel string) erro
 	return addFile(tw, baseDir, rel, info)
 }
 
+// skipArchivePath 排除不该进归档的内容：
+//   - backups/：备份里套备份会指数级膨胀；
+//   - frp/bin、frp/downloads：frpc 二进制与下载缓存，体积大且可重新下载；
+//   - frp/*.log：运行日志没有恢复价值。
+func skipArchivePath(rel string) bool {
+	slash := filepath.ToSlash(rel)
+	if strings.Contains("/"+slash+"/", "/backups/") {
+		return true
+	}
+	if slash == "frp/bin" || strings.HasPrefix(slash, "frp/bin/") {
+		return true
+	}
+	if slash == "frp/downloads" || strings.HasPrefix(slash, "frp/downloads/") {
+		return true
+	}
+	return strings.HasPrefix(slash, "frp/") && strings.HasSuffix(slash, ".log")
+}
+
 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 {
@@ -159,14 +364,14 @@ func addDir(ctx context.Context, tw *tar.Writer, baseDir, rel string) error {
 		if d.IsDir() {
 			return nil
 		}
-		if strings.Contains(path, string(os.PathSeparator)+"backups"+string(os.PathSeparator)) {
-			return nil
-		}
-		info, err := d.Info()
+		relPath, err := filepath.Rel(baseDir, path)
 		if err != nil {
 			return err
 		}
-		relPath, err := filepath.Rel(baseDir, path)
+		if skipArchivePath(relPath) {
+			return nil
+		}
+		info, err := d.Info()
 		if err != nil {
 			return err
 		}
@@ -181,14 +386,46 @@ func addFile(tw *tar.Writer, baseDir, rel string, info os.FileInfo) error {
 		return err
 	}
 	defer file.Close()
+
+	// 必须以「打开后」的尺寸为准：WalkDir 给的 info 是遍历那一刻的快照，
+	// 而这台机器上 logs、frpc 配置这些文件随时在长。用旧尺寸写进 tar 头、
+	// 再读出更多内容，就会报 archive/tar: write too long。
+	size := info.Size()
+	if current, err := file.Stat(); err == nil {
+		size = current.Size()
+	}
 	header, err := tar.FileInfoHeader(info, "")
 	if err != nil {
 		return err
 	}
 	header.Name = filepath.ToSlash(rel)
+	header.Size = size
 	if err := tw.WriteHeader(header); err != nil {
 		return err
 	}
-	_, err = io.Copy(tw, file)
-	return err
+
+	// 精确写入 size 字节：tar 要求实际字节数与头部声明严格相等。
+	//   - 文件在读取期间变长 → 多余部分截断（LimitReader）；
+	//   - 文件在读取期间被截短 → 补零凑够（zeroReader），保证这一条记录结构完整，
+	//     不至于让整份归档作废。
+	written, err := io.Copy(tw, io.LimitReader(file, size))
+	if err != nil {
+		return err
+	}
+	if written < size {
+		if _, err := io.CopyN(tw, zeroReader{}, size-written); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// zeroReader 提供无限个零字节，用于补齐读取期间被截短的文件条目。
+type zeroReader struct{}
+
+func (zeroReader) Read(p []byte) (int, error) {
+	for i := range p {
+		p[i] = 0
+	}
+	return len(p), nil
 }