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>
2026-10-24 16:30:00 +08:00
parent 6dd2136dd2
commit 9d75fb1d3e
49 changed files with 4469 additions and 1617 deletions
@@ -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
 }