feat: create standalone native fnOS repository

2026-10-02 15:19:09 +08:00
parent 69f3c30fab
commit 6725fc131d
492 changed files with 94023 additions and 3 deletions
@@ -0,0 +1,227 @@
+// Package fsutil 收敛「原子写配置」与「覆盖前备份」两个到处重复的动作。
+//
+// 之前 agent、frp、nginx、chinacidr 各自实现了一遍：有的用固定 .tmp 名（并发写同一路径会互相踩），
+// 有的直接 os.WriteFile（读到写了一半的配置），有的写完不 chmod（权限跟着 umask 走）。
+package fsutil
+
+import (
+	"bytes"
+	"crypto/rand"
+	"encoding/hex"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
+)
+
+// WriteFileAtomic 先写同目录的临时文件再 rename：读者要么看到旧内容、要么看到新内容。
+// 临时文件名带随机后缀，避免并发写同一路径时互相覆盖。
+func WriteFileAtomic(path string, data []byte, mode os.FileMode) error {
+	dir := filepath.Dir(path)
+	tmp, err := os.CreateTemp(dir, filepath.Base(path)+".tmp-*")
+	if err != nil {
+		return err
+	}
+	tmpName := tmp.Name()
+	defer func() {
+		if tmpName != "" {
+			_ = os.Remove(tmpName)
+		}
+	}()
+	if _, err := tmp.Write(data); err != nil {
+		_ = tmp.Close()
+		return err
+	}
+	if err := tmp.Close(); err != nil {
+		return err
+	}
+	// CreateTemp 建出来的是 0600，这里显式对齐调用方要求的权限
+	if err := os.Chmod(tmpName, mode); err != nil {
+		return err
+	}
+	if err := os.Rename(tmpName, path); err != nil {
+		return err
+	}
+	tmpName = "" // rename 成功，不用再清理
+	return nil
+}
+
+// Backup 把现有文件复制成 <path>.bak；文件不存在视为无需备份。
+// 返回的错误必须由调用方处理——备份是「覆盖前留退路」的唯一保障。
+func Backup(path string) error {
+	data, err := os.ReadFile(path)
+	if os.IsNotExist(err) {
+		return nil
+	}
+	if err != nil {
+		return err
+	}
+	return WriteFileAtomic(path+".bak", data, 0o600)
+}
+
+// VersionsDir 返回某文件的版本目录（.<name>.versions），供列表 / 回滚读取。
+// 目录名以点号开头，避免被 nginx 的 include <dir>/* 当成配置文件读取。
+func VersionsDir(path string) string {
+	return filepath.Join(filepath.Dir(path), "."+filepath.Base(path)+".versions")
+}
+
+// legacyVersionsDir 是旧布局（<path>.versions）。它会被 nginx 的 include * 误读为配置文件，
+// 因此读取 / 备份前统一迁移到隐藏目录。
+func legacyVersionsDir(path string) string {
+	return path + ".versions"
+}
+
+// MigrateLegacyVersions 把旧版本目录迁移到隐藏目录。只移动内容，不删除历史版本；
+// 迁移后旧目录已空，删除它是为了让 nginx 的 include * 不再命中该目录。
+func MigrateLegacyVersions(path string) error {
+	legacy := legacyVersionsDir(path)
+	info, err := os.Stat(legacy)
+	if err != nil || !info.IsDir() {
+		return nil
+	}
+	target := VersionsDir(path)
+	if _, err := os.Stat(target); os.IsNotExist(err) {
+		if err := os.MkdirAll(filepath.Dir(target), 0o700); err != nil {
+			return err
+		}
+		if err := os.Rename(legacy, target); err == nil {
+			return nil
+		}
+	}
+	if err := os.MkdirAll(target, 0o700); err != nil {
+		return err
+	}
+	entries, err := os.ReadDir(legacy)
+	if err != nil {
+		return err
+	}
+	for _, entry := range entries {
+		src := filepath.Join(legacy, entry.Name())
+		dst := filepath.Join(target, entry.Name())
+		if _, err := os.Stat(dst); err == nil {
+			continue
+		}
+		if err := os.Rename(src, dst); err != nil {
+			return err
+		}
+	}
+	return os.Remove(legacy)
+}
+
+// BackupVersioned 把现有文件留存为 .<name>.versions/<时间戳>-<随机>.conf，并只保留最近 keep 份。
+// 文件名前缀是 UTC 时间戳（同一秒内用随机后缀避开冲突），因此目录内按文件名倒序就是版本新旧顺序。
+// 文件不存在视为无需备份，返回空串；keep <= 0 表示不剪枝。
+func BackupVersioned(path string, keep int) (string, error) {
+	if err := MigrateLegacyVersions(path); err != nil {
+		return "", err
+	}
+	data, err := os.ReadFile(path)
+	if os.IsNotExist(err) {
+		return "", nil
+	}
+	if err != nil {
+		return "", err
+	}
+	dir := VersionsDir(path)
+	// 内容与最新版本一致时不重复记录：Apply 每次保存都会调用，去重后保留期才对应「真实的 N 次变更」
+	if versions, err := ListVersions(path); err == nil && len(versions) > 0 {
+		if newest, err := ReadVersion(path, versions[0].Name); err == nil && bytes.Equal(newest, data) {
+			return filepath.Join(dir, versions[0].Name), nil
+		}
+	}
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		return "", err
+	}
+	name := time.Now().UTC().Format("20060102T150405.000") + "-" + randSuffix() + filepath.Ext(path)
+	target := filepath.Join(dir, name)
+	if err := WriteFileAtomic(target, data, 0o600); err != nil {
+		return "", err
+	}
+	if keep > 0 {
+		pruneVersions(dir, keep)
+	}
+	return target, nil
+}
+
+// VersionEntry 描述一个已留存的版本（名称前缀是 UTC 时间戳，因此按名称倒序就是新旧顺序）。
+type VersionEntry struct {
+	Name      string    `json:"name"`
+	Size      int64     `json:"size"`
+	CreatedAt time.Time `json:"created_at"`
+}
+
+// ListVersions 按新的在前列出版本；版本目录不存在时返回空列表（首次备份前是正常状态）。
+func ListVersions(path string) ([]VersionEntry, error) {
+	if err := MigrateLegacyVersions(path); err != nil {
+		return nil, err
+	}
+	entries, err := os.ReadDir(VersionsDir(path))
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, nil
+		}
+		return nil, err
+	}
+	out := make([]VersionEntry, 0, len(entries))
+	for _, entry := range entries {
+		if entry.IsDir() || strings.HasPrefix(entry.Name(), ".") {
+			continue
+		}
+		info, err := entry.Info()
+		if err != nil {
+			continue
+		}
+		out = append(out, VersionEntry{Name: entry.Name(), Size: info.Size(), CreatedAt: info.ModTime().UTC()})
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Name > out[j].Name })
+	return out, nil
+}
+
+// ReadVersion 读取指定版本的内容。版本名虽然来自 ListVersions，这里仍校验一次：
+// 带路径分隔符 / 上跳的名称直接拒绍，避免接口被用来读版本目录以外的文件。
+func ReadVersion(path, name string) ([]byte, error) {
+	if name == "" || name != filepath.Base(name) || name == "." || name == ".." {
+		return nil, fmt.Errorf("版本名无效")
+	}
+	if err := MigrateLegacyVersions(path); err != nil {
+		return nil, err
+	}
+	data, err := os.ReadFile(filepath.Join(VersionsDir(path), name))
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil, fmt.Errorf("版本不存在")
+		}
+		return nil, err
+	}
+	return data, nil
+}
+
+// pruneVersions 只保留最新的 keep 份（按文件名倒序，前缀是时间戳）。
+// 剪枝失败不影响本次备份结果，因此只忽略错误。
+func pruneVersions(dir string, keep int) {
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		return
+	}
+	names := make([]string, 0, len(entries))
+	for _, entry := range entries {
+		if entry.IsDir() || strings.HasPrefix(entry.Name(), ".") {
+			continue
+		}
+		names = append(names, entry.Name())
+	}
+	sort.Sort(sort.Reverse(sort.StringSlice(names)))
+	for _, name := range names[min(keep, len(names)):] {
+		_ = os.Remove(filepath.Join(dir, name))
+	}
+}
+
+func randSuffix() string {
+	var buf [2]byte
+	if _, err := rand.Read(buf[:]); err != nil {
+		return "0000"
+	}
+	return hex.EncodeToString(buf[:])
+}
@@ -0,0 +1,231 @@
+package fsutil
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestWriteFileAtomicReplacesContent(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "frps.toml")
+	if err := os.WriteFile(path, []byte("old"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := WriteFileAtomic(path, []byte("new"), 0o640); err != nil {
+		t.Fatal(err)
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(data) != "new" {
+		t.Fatalf("内容未替换：%q", data)
+	}
+}
+
+// TestWriteFileAtomicLeavesNoTempFiles：临时文件必须被 rename 或清理，不能在配置目录里留垃圾。
+func TestWriteFileAtomicLeavesNoTempFiles(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "nginx.conf")
+	if err := WriteFileAtomic(path, []byte("worker_processes 1;"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, entry := range entries {
+		if strings.Contains(entry.Name(), ".tmp-") {
+			t.Fatalf("残留临时文件：%s", entry.Name())
+		}
+	}
+	if len(entries) != 1 {
+		t.Fatalf("目录里应只剩目标文件，实际 %d 个", len(entries))
+	}
+}
+
+func TestBackupSkipsMissingFile(t *testing.T) {
+	if err := Backup(filepath.Join(t.TempDir(), "nope.conf")); err != nil {
+		t.Fatalf("文件不存在时应视为无需备份，实际 %v", err)
+	}
+}
+
+func TestBackupCopiesContent(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "frpc.toml")
+	if err := os.WriteFile(path, []byte("token = \"x\""), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := Backup(path); err != nil {
+		t.Fatal(err)
+	}
+	data, err := os.ReadFile(path + ".bak")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(data) != "token = \"x\"" {
+		t.Fatalf("备份内容不符：%q", data)
+	}
+}
+
+func TestBackupVersionedStoresContent(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "nginx.conf")
+	if err := os.WriteFile(path, []byte("worker_processes 1;"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	version, err := BackupVersioned(path, 5)
+	if err != nil || version == "" {
+		t.Fatalf("应返回版本路径：%q %v", version, err)
+	}
+	if !strings.Contains(version, VersionsDir(path)) {
+		t.Fatalf("版本应落在版本目录内：%s", version)
+	}
+	data, err := os.ReadFile(version)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(data) != "worker_processes 1;" {
+		t.Fatalf("版本内容不符：%q", data)
+	}
+}
+
+func TestBackupVersionedPrunesToKeep(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "nginx.conf")
+	// 每次写入不同内容：内容相同会被去重，剪枝也就无从检验
+	for _, content := range []string{"v1", "v2", "v3", "v4", "v5"} {
+		if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if _, err := BackupVersioned(path, 2); err != nil {
+			t.Fatal(err)
+		}
+	}
+	entries, err := os.ReadDir(VersionsDir(path))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(entries) != 2 {
+		t.Fatalf("应只保留 2 份版本，实际 %d", len(entries))
+	}
+}
+
+func TestBackupVersionedSkipsMissingFile(t *testing.T) {
+	version, err := BackupVersioned(filepath.Join(t.TempDir(), "nope.conf"), 5)
+	if err != nil || version != "" {
+		t.Fatalf("文件不存在时应返回空路径且无错误：%q %v", version, err)
+	}
+}
+
+func TestListVersionsNewestFirst(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "nginx.conf")
+	if err := os.WriteFile(path, []byte("v1"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := BackupVersioned(path, 5); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(path, []byte("v2"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := BackupVersioned(path, 5); err != nil {
+		t.Fatal(err)
+	}
+
+	versions, err := ListVersions(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(versions) != 2 || versions[0].Name <= versions[1].Name {
+		t.Fatalf("版本应按名称倒序（新的在前）列出：%v", versions)
+	}
+	seen := map[string]bool{}
+	for _, version := range versions {
+		data, err := ReadVersion(path, version.Name)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if version.Size != int64(len(data)) {
+			t.Fatalf("版本大小不符：%d vs %d", version.Size, len(data))
+		}
+		seen[string(data)] = true
+	}
+	if !seen["v1"] || !seen["v2"] {
+		t.Fatalf("两个版本的内容都应在：%v", seen)
+	}
+}
+
+func TestBackupVersionedSkipsIdenticalContent(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "nginx.conf")
+	if err := os.WriteFile(path, []byte("same"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	first, err := BackupVersioned(path, 5)
+	if err != nil {
+		t.Fatal(err)
+	}
+	second, err := BackupVersioned(path, 5)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if first != second {
+		t.Fatalf("内容未变时不应新增版本：%q vs %q", first, second)
+	}
+	versions, err := ListVersions(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(versions) != 1 {
+		t.Fatalf("内容未变时应只有 1 个版本，实际 %d", len(versions))
+	}
+}
+
+func TestReadVersionRejectsTraversal(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "nginx.conf")
+	if _, err := ReadVersion(path, "../nginx.conf"); err == nil {
+		t.Fatal("带路径上跳的版本名应被拒绝")
+	}
+	if _, err := ReadVersion(path, "missing.conf"); err == nil {
+		t.Fatal("不存在的版本应报错")
+	}
+	versions, err := ListVersions(path)
+	if err != nil || len(versions) != 0 {
+		t.Fatalf("版本目录不存在时应返回空列表且无错误：%v %v", versions, err)
+	}
+}
+
+func TestVersionsDirIsHidden(t *testing.T) {
+	path := filepath.Join("/etc/nginx/sites-enabled", "havlineagent-https.conf")
+	base := filepath.Base(VersionsDir(path))
+	if !strings.HasPrefix(base, ".") {
+		t.Fatalf("版本目录应以点号开头，避免被 nginx 的 include * 加载：%s", base)
+	}
+}
+
+func TestMigrateLegacyVersions(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "havlineagent-https.conf")
+	legacy := path + ".versions"
+	if err := os.MkdirAll(legacy, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	name := "20260101T000000.000-abcd.conf"
+	if err := os.WriteFile(filepath.Join(legacy, name), []byte("old"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	versions, err := ListVersions(path)
+	if err != nil || len(versions) != 1 {
+		t.Fatalf("迁移后应保留 1 个版本：%v %v", versions, err)
+	}
+	if _, err := os.Stat(legacy); !os.IsNotExist(err) {
+		t.Fatalf("旧版本目录应被移走，避免 nginx include * 命中：%v", err)
+	}
+	data, err := ReadVersion(path, versions[0].Name)
+	if err != nil || string(data) != "old" {
+		t.Fatalf("迁移后版本内容应可读：%q %v", data, err)
+	}
+}