refactor(backend): rename OpenFlare directory to lowercase openflare

backend/openflare/plugins/agent/config/config.go

@@ -0,0 +1,418 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package config loads and persists agent daemon configuration.
+package config
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	pathpkg "path"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"time"
+
+	"Wavelet/openflare/share/edge/nodeip"
+	"Wavelet/openflare/share/ofutil"
+)
+
+const (
+	defaultMainConfigRelativePath          = "etc/nginx/nginx.conf"
+	defaultRouteConfigRelativePath         = "etc/nginx/conf.d/openflare_routes.conf"
+	defaultCertDirRelativePath             = "etc/nginx/certs"
+	defaultLuaDirRelativePath              = "etc/nginx/lua"
+	defaultRuntimeConfigDirRelativePath    = "etc/openflare"
+	defaultPagesDirRelativePath            = "var/lib/openflare/pages"
+	defaultMMDBRelativePath                = "etc/openflare/GeoLite2-Country.mmdb"
+	defaultCityMMDBRelativePath            = "etc/openflare/GeoLite2-City.mmdb"
+	defaultAccessLogRelativePath           = "var/log/openflare/access.log"
+	defaultStateRelativePath               = "var/lib/openflare/agent-state.json"
+	defaultObservabilityBufferRelativePath = "var/lib/openflare/observability-buffer.json"
+	defaultOpenRestyObservabilityPort      = 18081
+	defaultObservabilityReplayMinutes      = 60
+	defaultMMDBUpdateInterval              = 24 * time.Hour
+	defaultMMDBDownloadURL                 = "https://github.com/FyraLabs/geolite2/releases/latest/download/GeoLite2-Country.mmdb"
+	defaultCityMMDBDownloadURL             = "https://github.com/FyraLabs/geolite2/releases/latest/download/GeoLite2-City.mmdb"
+	defaultHeartbeatInterval               = 3 * time.Second
+	defaultRequestTimeout                  = 10 * time.Second
+	configFilePerm                         = 0o600
+)
+
+// Config holds the full runtime configuration for the OpenFlare agent.
+type Config struct {
+	ServerURL                  string              `json:"server_url"`
+	AccessToken                string              `json:"agent_token"`
+	DiscoveryToken             string              `json:"discovery_token"`
+	NodeName                   string              `json:"node_name"`
+	NodeIP                     string              `json:"node_ip"`
+	Version                    string              `json:"-"`
+	ExtVersion                 string              `json:"-"`
+	OpenrestyPath              string              `json:"openresty_path"`
+	OpenrestyResolvers         []string            `json:"openresty_resolvers,omitempty"`
+	DataDir                    string              `json:"data_dir"`
+	MainConfigPath             string              `json:"main_config_path"`
+	RouteConfigPath            string              `json:"route_config_path"`
+	AccessLogPath              string              `json:"access_log_path"`
+	CertDir                    string              `json:"cert_dir"`
+	OpenrestyCertDir           string              `json:"openresty_cert_dir"`
+	LuaDir                     string              `json:"lua_dir"`
+	OpenrestyLuaDir            string              `json:"openresty_lua_dir"`
+	RuntimeConfigDir           string              `json:"runtime_config_dir"`
+	PagesDir                   string              `json:"pages_dir"`
+	MMDBPath                   string              `json:"mmdb_path"`
+	CityMMDBPath               string              `json:"city_mmdb_path"`
+	MMDBUpdateInterval         MillisecondDuration `json:"mmdb_update_interval"`
+	MMDBDownloadURL            string              `json:"mmdb_download_url"`
+	CityMMDBDownloadURL        string              `json:"city_mmdb_download_url"`
+	OpenrestyObservabilityPort int                 `json:"openresty_observability_port"`
+	ObservabilityBufferPath    string              `json:"observability_buffer_path"`
+	ObservabilityReplayMinutes int                 `json:"observability_replay_minutes"`
+	StatePath                  string              `json:"state_path"`
+	HeartbeatInterval          MillisecondDuration `json:"heartbeat_interval"`
+	RequestTimeout             MillisecondDuration `json:"request_timeout"`
+	configPath                 string              `json:"-"`
+	NodeIPConfigured           bool                `json:"-"`
+}
+
+type configFile struct {
+	ServerURL                  string              `json:"server_url"`
+	AccessToken                string              `json:"agent_token"`
+	DiscoveryToken             string              `json:"discovery_token"`
+	NodeName                   string              `json:"node_name"`
+	NodeIP                     string              `json:"node_ip"`
+	OpenrestyPath              string              `json:"openresty_path"`
+	OpenrestyResolvers         []string            `json:"openresty_resolvers"`
+	DataDir                    string              `json:"data_dir"`
+	MainConfigPath             string              `json:"main_config_path"`
+	RouteConfigPath            string              `json:"route_config_path"`
+	AccessLogPath              string              `json:"access_log_path"`
+	CertDir                    string              `json:"cert_dir"`
+	OpenrestyCertDir           string              `json:"openresty_cert_dir"`
+	LuaDir                     string              `json:"lua_dir"`
+	OpenrestyLuaDir            string              `json:"openresty_lua_dir"`
+	RuntimeConfigDir           string              `json:"runtime_config_dir"`
+	PagesDir                   string              `json:"pages_dir"`
+	MMDBPath                   string              `json:"mmdb_path"`
+	CityMMDBPath               string              `json:"city_mmdb_path"`
+	MMDBUpdateInterval         MillisecondDuration `json:"mmdb_update_interval"`
+	MMDBDownloadURL            string              `json:"mmdb_download_url"`
+	CityMMDBDownloadURL        string              `json:"city_mmdb_download_url"`
+	OpenrestyObservabilityPort int                 `json:"openresty_observability_port"`
+	ObservabilityBufferPath    string              `json:"observability_buffer_path"`
+	ObservabilityReplayMinutes int                 `json:"observability_replay_minutes"`
+	StatePath                  string              `json:"state_path"`
+	HeartbeatInterval          MillisecondDuration `json:"heartbeat_interval"`
+	RequestTimeout             MillisecondDuration `json:"request_timeout"`
+}
+
+func transferPersistedConfig(dst, src any) error {
+	data, err := json.Marshal(src)
+	if err != nil {
+		return err
+	}
+	return json.Unmarshal(data, dst)
+}
+
+// Load reads and parses the agent configuration file at the given path.
+func Load(path string) (*Config, error) {
+	data, err := os.ReadFile(path) //nolint:gosec // path is the configured agent config location
+	if err != nil && !os.IsNotExist(err) {
+		return nil, err
+	}
+	file := &configFile{}
+	if err == nil {
+		if err = json.Unmarshal(data, file); err != nil {
+			return nil, err
+		}
+	}
+	if err != nil && !hasEnvConfig() {
+		return nil, err
+	}
+	cfg := &Config{}
+	if err == nil {
+		if err = transferPersistedConfig(cfg, file); err != nil {
+			return nil, err
+		}
+	}
+	cfg.configPath = path
+	applyEnvOverrides(cfg)
+	cfg.NodeIPConfigured = cfg.NodeIP != ""
+	applyDefaults(cfg, filepath.Dir(path))
+	if err = validate(cfg); err != nil {
+		return nil, err
+	}
+	return cfg, nil
+}
+
+func applyDefaults(cfg *Config, baseDir string) {
+	baseDir = filepath.Clean(baseDir)
+	cfg.Version = Version
+	cfg.OpenrestyResolvers = ofutil.UniqueAndCleanStringSlice(cfg.OpenrestyResolvers)
+	applyAgentIdentityDefaults(cfg)
+	applyAgentPathDefaults(cfg, baseDir)
+	applyAgentTimingDefaults(cfg)
+	normalizeManagedPaths(cfg)
+}
+
+func applyAgentIdentityDefaults(cfg *Config) {
+	if cfg.OpenrestyPath == "" {
+		cfg.OpenrestyPath = "openresty"
+	}
+	if cfg.NodeName == "" {
+		cfg.NodeName = detectHostname()
+	}
+	if cfg.NodeIP == "" {
+		cfg.NodeIP = nodeip.Detect()
+	}
+}
+
+func applyAgentPathDefaults(cfg *Config, baseDir string) {
+	if cfg.DataDir == "" {
+		cfg.DataDir = filepath.Join(baseDir, "data")
+	}
+	type managedPathDefault struct {
+		target   *string
+		relative string
+	}
+	pathDefaults := []managedPathDefault{
+		{&cfg.MainConfigPath, defaultMainConfigRelativePath},
+		{&cfg.RouteConfigPath, defaultRouteConfigRelativePath},
+		{&cfg.AccessLogPath, defaultAccessLogRelativePath},
+		{&cfg.StatePath, defaultStateRelativePath},
+		{&cfg.CertDir, defaultCertDirRelativePath},
+		{&cfg.LuaDir, defaultLuaDirRelativePath},
+		{&cfg.RuntimeConfigDir, defaultRuntimeConfigDirRelativePath},
+		{&cfg.PagesDir, defaultPagesDirRelativePath},
+		{&cfg.MMDBPath, defaultMMDBRelativePath},
+		{&cfg.CityMMDBPath, defaultCityMMDBRelativePath},
+		{&cfg.ObservabilityBufferPath, defaultObservabilityBufferRelativePath},
+	}
+	for _, item := range pathDefaults {
+		if strings.TrimSpace(*item.target) == "" {
+			*item.target = joinManagedPath(cfg.DataDir, item.relative)
+		}
+	}
+	if cfg.OpenrestyCertDir == "" {
+		cfg.OpenrestyCertDir = cfg.CertDir
+	}
+	if cfg.OpenrestyLuaDir == "" {
+		cfg.OpenrestyLuaDir = cfg.LuaDir
+	}
+}
+
+func applyAgentTimingDefaults(cfg *Config) {
+	if cfg.MMDBUpdateInterval <= 0 {
+		cfg.MMDBUpdateInterval = MillisecondDuration(defaultMMDBUpdateInterval)
+	}
+	if cfg.MMDBDownloadURL == "" {
+		cfg.MMDBDownloadURL = defaultMMDBDownloadURL
+	}
+	if cfg.CityMMDBDownloadURL == "" {
+		cfg.CityMMDBDownloadURL = defaultCityMMDBDownloadURL
+	}
+	if cfg.OpenrestyObservabilityPort <= 0 {
+		cfg.OpenrestyObservabilityPort = defaultOpenRestyObservabilityPort
+	}
+	if cfg.ObservabilityReplayMinutes <= 0 {
+		cfg.ObservabilityReplayMinutes = defaultObservabilityReplayMinutes
+	}
+	if cfg.HeartbeatInterval <= 0 {
+		cfg.HeartbeatInterval = MillisecondDuration(defaultHeartbeatInterval)
+	}
+	if cfg.RequestTimeout <= 0 {
+		cfg.RequestTimeout = MillisecondDuration(defaultRequestTimeout)
+	}
+}
+
+func normalizeManagedPaths(cfg *Config) {
+	if cfg == nil {
+		return
+	}
+	paths := []*string{
+		&cfg.DataDir,
+		&cfg.MainConfigPath,
+		&cfg.RouteConfigPath,
+		&cfg.AccessLogPath,
+		&cfg.CertDir,
+		&cfg.OpenrestyCertDir,
+		&cfg.LuaDir,
+		&cfg.OpenrestyLuaDir,
+		&cfg.RuntimeConfigDir,
+		&cfg.PagesDir,
+		&cfg.StatePath,
+		&cfg.ObservabilityBufferPath,
+		&cfg.MMDBPath,
+		&cfg.CityMMDBPath,
+	}
+	for _, p := range paths {
+		if usesSlashPath(*p) {
+			*p = filepath.ToSlash(*p)
+		}
+	}
+}
+
+func hasEnvConfig() bool {
+	for _, key := range []string{
+		"OPENFLARE_SERVER_URL",
+		"OPENFLARE_AGENT_TOKEN",
+		"OPENFLARE_DISCOVERY_TOKEN",
+		"OPENFLARE_NODE_NAME",
+		"OPENFLARE_NODE_IP",
+		"OPENFLARE_DATA_DIR",
+		"OPENFLARE_OPENRESTY_PATH",
+		"OPENFLARE_PAGES_DIR",
+		"OPENFLARE_HEARTBEAT_INTERVAL",
+		"OPENFLARE_REQUEST_TIMEOUT",
+		"OPENFLARE_OPENRESTY_OBSERVABILITY_PORT",
+		"OPENFLARE_MMDB_PATH",
+		"OPENFLARE_MMDB_UPDATE_INTERVAL",
+		"OPENFLARE_MMDB_DOWNLOAD_URL",
+		"OPENFLARE_CITY_MMDB_PATH",
+		"OPENFLARE_CITY_MMDB_DOWNLOAD_URL",
+	} {
+		if strings.TrimSpace(os.Getenv(key)) != "" {
+			return true
+		}
+	}
+	return false
+}
+
+func applyEnvOverrides(cfg *Config) {
+	if cfg == nil {
+		return
+	}
+	overrideString := func(key string, target *string) {
+		if value := strings.TrimSpace(os.Getenv(key)); value != "" {
+			*target = value
+		}
+	}
+	overrideString("OPENFLARE_SERVER_URL", &cfg.ServerURL)
+	overrideString("OPENFLARE_AGENT_TOKEN", &cfg.AccessToken)
+	overrideString("OPENFLARE_DISCOVERY_TOKEN", &cfg.DiscoveryToken)
+	overrideString("OPENFLARE_NODE_NAME", &cfg.NodeName)
+	overrideString("OPENFLARE_NODE_IP", &cfg.NodeIP)
+	overrideString("OPENFLARE_DATA_DIR", &cfg.DataDir)
+	overrideString("OPENFLARE_OPENRESTY_PATH", &cfg.OpenrestyPath)
+	overrideString("OPENFLARE_PAGES_DIR", &cfg.PagesDir)
+	overrideString("OPENFLARE_MMDB_PATH", &cfg.MMDBPath)
+	overrideString("OPENFLARE_MMDB_DOWNLOAD_URL", &cfg.MMDBDownloadURL)
+	overrideString("OPENFLARE_CITY_MMDB_PATH", &cfg.CityMMDBPath)
+	overrideString("OPENFLARE_CITY_MMDB_DOWNLOAD_URL", &cfg.CityMMDBDownloadURL)
+	if value := strings.TrimSpace(os.Getenv("OPENFLARE_HEARTBEAT_INTERVAL")); value != "" {
+		if duration, err := parseDurationValue(value); err == nil {
+			cfg.HeartbeatInterval = duration
+		}
+	}
+	if value := strings.TrimSpace(os.Getenv("OPENFLARE_REQUEST_TIMEOUT")); value != "" {
+		if duration, err := parseDurationValue(value); err == nil {
+			cfg.RequestTimeout = duration
+		}
+	}
+	if value := strings.TrimSpace(os.Getenv("OPENFLARE_MMDB_UPDATE_INTERVAL")); value != "" {
+		if duration, err := parseDurationValue(value); err == nil {
+			cfg.MMDBUpdateInterval = duration
+		}
+	}
+	if value := strings.TrimSpace(os.Getenv("OPENFLARE_OPENRESTY_OBSERVABILITY_PORT")); value != "" {
+		var port int
+		if _, err := fmt.Sscanf(value, "%d", &port); err == nil {
+			cfg.OpenrestyObservabilityPort = port
+		}
+	}
+}
+
+func parseDurationValue(value string) (MillisecondDuration, error) {
+	trimmed := strings.TrimSpace(value)
+	if trimmed == "" {
+		return 0, nil
+	}
+	if parsed, err := time.ParseDuration(trimmed); err == nil {
+		return MillisecondDuration(parsed), nil
+	}
+	ms, err := strconv.ParseInt(trimmed, 10, 64)
+	if err != nil {
+		return 0, err
+	}
+	return MillisecondDuration(time.Duration(ms) * time.Millisecond), nil
+}
+
+func usesSlashPath(path string) bool {
+	return strings.HasPrefix(path, "/")
+}
+
+func joinManagedPath(base string, relative string) string {
+	if usesSlashPath(base) {
+		return pathpkg.Join(filepath.ToSlash(base), relative)
+	}
+	return filepath.Join(base, relative)
+}
+
+func validate(cfg *Config) error {
+	if cfg.ServerURL == "" {
+		return errors.New("server_url 不能为空")
+	}
+	if strings.TrimSpace(cfg.AccessToken) == "" && strings.TrimSpace(cfg.DiscoveryToken) == "" {
+		return errors.New("agent_token 和 discovery_token 不能同时为空")
+	}
+	if cfg.NodeName == "" {
+		return errors.New("node_name 不能为空")
+	}
+	if cfg.NodeIP == "" {
+		return errors.New("node_ip 不能为空")
+	}
+	if cfg.OpenrestyObservabilityPort <= 0 || cfg.OpenrestyObservabilityPort > 65535 {
+		return errors.New("openresty_observability_port 必须在 1-65535 之间")
+	}
+	if cfg.ObservabilityReplayMinutes <= 0 {
+		return errors.New("observability_replay_minutes 必须大于 0")
+	}
+	if cfg.MMDBUpdateInterval <= 0 {
+		return errors.New("mmdb_update_interval 必须大于 0")
+	}
+	return nil
+}
+
+// InitialAuthToken returns the agent access token, falling back to the discovery token if absent.
+func (cfg *Config) InitialAuthToken() string {
+	if cfg == nil {
+		return ""
+	}
+	if token := strings.TrimSpace(cfg.AccessToken); token != "" {
+		return token
+	}
+	return strings.TrimSpace(cfg.DiscoveryToken)
+}
+
+func (cfg *Config) toConfigFile() configFile {
+	var file configFile
+	if err := transferPersistedConfig(&file, cfg); err != nil {
+		return configFile{}
+	}
+	return file
+}
+
+// Save persists the current configuration back to its original file path.
+func (cfg *Config) Save() error {
+	if cfg == nil {
+		return errors.New("config 不能为空")
+	}
+	if cfg.configPath == "" {
+		return errors.New("config path 未初始化")
+	}
+	data, err := json.MarshalIndent(cfg.toConfigFile(), "", "  ") //nolint:gosec // agent token must be persisted in local config file
+	if err != nil {
+		return err
+	}
+	return os.WriteFile(cfg.configPath, data, configFilePerm)
+}
+
+func detectHostname() string {
+	host, err := os.Hostname()
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(host)
+}

backend/openflare/plugins/agent/config/config_test.go

@@ -0,0 +1,559 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package config
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"Wavelet/openflare/share/edge/nodeip"
+	"Wavelet/openflare/share/geoip"
+	"Wavelet/openflare/share/geoip/iputil"
+)
+
+func TestLoadDefaultsToManagedBinaryPaths(t *testing.T) {
+	dir := t.TempDir()
+	configPath := filepath.Join(dir, "agent.json")
+	payload := map[string]any{
+		"server_url":  "http://127.0.0.1:3000",
+		"agent_token": "token",
+		"node_name":   "edge-01",
+		"node_ip":     "10.0.0.8",
+	}
+	data, err := json.Marshal(payload)
+	if err != nil {
+		t.Fatalf("failed to marshal config: %v", err)
+	}
+	if err = os.WriteFile(configPath, data, 0o644); err != nil {
+		t.Fatalf("failed to write config: %v", err)
+	}
+
+	cfg, err := Load(configPath)
+	if err != nil {
+		t.Fatalf("Load failed: %v", err)
+	}
+
+	if cfg.DataDir != filepath.Join(dir, "data") {
+		t.Fatalf("unexpected data dir: %s", cfg.DataDir)
+	}
+	if cfg.OpenrestyPath != "openresty" {
+		t.Fatalf("unexpected openresty path: %s", cfg.OpenrestyPath)
+	}
+	if cfg.MainConfigPath != filepath.Join(dir, "data", defaultMainConfigRelativePath) {
+		t.Fatalf("unexpected main config path: %s", cfg.MainConfigPath)
+	}
+	if cfg.RouteConfigPath != filepath.Join(dir, "data", defaultRouteConfigRelativePath) {
+		t.Fatalf("unexpected route config path: %s", cfg.RouteConfigPath)
+	}
+	if cfg.AccessLogPath != filepath.Join(dir, "data", defaultAccessLogRelativePath) {
+		t.Fatalf("unexpected access log path: %s", cfg.AccessLogPath)
+	}
+	if cfg.CertDir != filepath.Join(dir, "data", defaultCertDirRelativePath) {
+		t.Fatalf("unexpected cert dir: %s", cfg.CertDir)
+	}
+	if cfg.LuaDir != filepath.Join(dir, "data", defaultLuaDirRelativePath) {
+		t.Fatalf("unexpected lua dir: %s", cfg.LuaDir)
+	}
+	if cfg.RuntimeConfigDir != filepath.Join(dir, "data", defaultRuntimeConfigDirRelativePath) {
+		t.Fatalf("unexpected runtime config dir: %s", cfg.RuntimeConfigDir)
+	}
+	if cfg.CityMMDBPath != filepath.Join(dir, "data", defaultCityMMDBRelativePath) {
+		t.Fatalf("unexpected city mmdb path: %s", cfg.CityMMDBPath)
+	}
+	if cfg.CityMMDBDownloadURL != defaultCityMMDBDownloadURL {
+		t.Fatalf("unexpected city mmdb download URL: %s", cfg.CityMMDBDownloadURL)
+	}
+	if cfg.OpenrestyCertDir != cfg.CertDir {
+		t.Fatalf("unexpected openresty cert dir: %s", cfg.OpenrestyCertDir)
+	}
+	if cfg.OpenrestyLuaDir != cfg.LuaDir {
+		t.Fatalf("unexpected openresty lua dir: %s", cfg.OpenrestyLuaDir)
+	}
+	if cfg.StatePath != filepath.Join(dir, "data", defaultStateRelativePath) {
+		t.Fatalf("unexpected state path: %s", cfg.StatePath)
+	}
+	if cfg.ObservabilityBufferPath != filepath.Join(dir, "data", defaultObservabilityBufferRelativePath) {
+		t.Fatalf("unexpected observability buffer path: %s", cfg.ObservabilityBufferPath)
+	}
+	if cfg.OpenrestyObservabilityPort != defaultOpenRestyObservabilityPort {
+		t.Fatalf("unexpected openresty observability port: %d", cfg.OpenrestyObservabilityPort)
+	}
+	if cfg.ObservabilityReplayMinutes != defaultObservabilityReplayMinutes {
+		t.Fatalf("unexpected observability replay minutes: %d", cfg.ObservabilityReplayMinutes)
+	}
+}
+
+func TestLoadPathModeKeepsExplicitPaths(t *testing.T) {
+	dir := t.TempDir()
+	configPath := filepath.Join(dir, "agent.json")
+	payload := map[string]any{
+		"server_url":        "http://127.0.0.1:3000",
+		"agent_token":       "token",
+		"node_name":         "edge-01",
+		"node_ip":           "10.0.0.8",
+		"openresty_path":    "/usr/local/openresty/nginx/sbin/openresty",
+		"main_config_path":  "/tmp/nginx.conf",
+		"route_config_path": "/tmp/routes.conf",
+		"state_path":        "/tmp/agent-state.json",
+	}
+	data, err := json.Marshal(payload)
+	if err != nil {
+		t.Fatalf("failed to marshal config: %v", err)
+	}
+	if err = os.WriteFile(configPath, data, 0o644); err != nil {
+		t.Fatalf("failed to write config: %v", err)
+	}
+
+	cfg, err := Load(configPath)
+	if err != nil {
+		t.Fatalf("Load failed: %v", err)
+	}
+
+	if cfg.MainConfigPath != "/tmp/nginx.conf" {
+		t.Fatalf("unexpected main config path: %s", cfg.MainConfigPath)
+	}
+	if cfg.RouteConfigPath != "/tmp/routes.conf" {
+		t.Fatalf("unexpected route config path: %s", cfg.RouteConfigPath)
+	}
+	if cfg.StatePath != "/tmp/agent-state.json" {
+		t.Fatalf("unexpected state path: %s", cfg.StatePath)
+	}
+	if cfg.ObservabilityBufferPath != filepath.Join(dir, "data", defaultObservabilityBufferRelativePath) {
+		t.Fatalf("unexpected observability buffer path: %s", cfg.ObservabilityBufferPath)
+	}
+	if cfg.OpenrestyCertDir != cfg.CertDir {
+		t.Fatalf("expected path mode openresty cert dir to equal cert dir, got %s / %s", cfg.OpenrestyCertDir, cfg.CertDir)
+	}
+	if cfg.OpenrestyLuaDir != cfg.LuaDir {
+		t.Fatalf("expected path mode openresty lua dir to equal lua dir, got %s / %s", cfg.OpenrestyLuaDir, cfg.LuaDir)
+	}
+	if cfg.OpenrestyObservabilityPort != defaultOpenRestyObservabilityPort {
+		t.Fatalf("unexpected path mode openresty observability port: %d", cfg.OpenrestyObservabilityPort)
+	}
+}
+
+func TestLoadNormalizesExplicitResolvers(t *testing.T) {
+	dir := t.TempDir()
+	configPath := filepath.Join(dir, "agent.json")
+	payload := map[string]any{
+		"server_url":          "http://127.0.0.1:3000",
+		"agent_token":         "token",
+		"node_name":           "edge-01",
+		"node_ip":             "10.0.0.8",
+		"openresty_resolvers": []string{" 10.0.0.2 ", "10.0.0.2", "", "1.1.1.1"},
+	}
+	data, err := json.Marshal(payload)
+	if err != nil {
+		t.Fatalf("failed to marshal config: %v", err)
+	}
+	if err = os.WriteFile(configPath, data, 0o644); err != nil {
+		t.Fatalf("failed to write config: %v", err)
+	}
+
+	cfg, err := Load(configPath)
+	if err != nil {
+		t.Fatalf("Load failed: %v", err)
+	}
+
+	expected := []string{"10.0.0.2", "1.1.1.1"}
+	if len(cfg.OpenrestyResolvers) != len(expected) {
+		t.Fatalf("unexpected resolver count: %#v", cfg.OpenrestyResolvers)
+	}
+	for index, value := range expected {
+		if cfg.OpenrestyResolvers[index] != value {
+			t.Fatalf("unexpected resolver at %d: got %q want %q", index, cfg.OpenrestyResolvers[index], value)
+		}
+	}
+}
+
+func TestLoadUsesCustomDataDirForGeneratedFiles(t *testing.T) {
+	dir := t.TempDir()
+	configPath := filepath.Join(dir, "agent.json")
+	payload := map[string]any{
+		"server_url":  "http://127.0.0.1:3000",
+		"agent_token": "token",
+		"node_name":   "edge-01",
+		"node_ip":     "10.0.0.8",
+		"data_dir":    "/srv/openflare",
+	}
+	data, err := json.Marshal(payload)
+	if err != nil {
+		t.Fatalf("failed to marshal config: %v", err)
+	}
+	if err = os.WriteFile(configPath, data, 0o644); err != nil {
+		t.Fatalf("failed to write config: %v", err)
+	}
+
+	cfg, err := Load(configPath)
+	if err != nil {
+		t.Fatalf("Load failed: %v", err)
+	}
+
+	if cfg.RouteConfigPath != "/srv/openflare/"+defaultRouteConfigRelativePath {
+		t.Fatalf("unexpected route config path: %s", cfg.RouteConfigPath)
+	}
+	if cfg.MainConfigPath != "/srv/openflare/"+defaultMainConfigRelativePath {
+		t.Fatalf("unexpected main config path: %s", cfg.MainConfigPath)
+	}
+	if cfg.AccessLogPath != "/srv/openflare/"+defaultAccessLogRelativePath {
+		t.Fatalf("unexpected access log path: %s", cfg.AccessLogPath)
+	}
+	if cfg.StatePath != "/srv/openflare/"+defaultStateRelativePath {
+		t.Fatalf("unexpected state path: %s", cfg.StatePath)
+	}
+	if cfg.ObservabilityBufferPath != "/srv/openflare/"+defaultObservabilityBufferRelativePath {
+		t.Fatalf("unexpected observability buffer path: %s", cfg.ObservabilityBufferPath)
+	}
+	if cfg.CertDir != "/srv/openflare/"+defaultCertDirRelativePath {
+		t.Fatalf("unexpected cert dir: %s", cfg.CertDir)
+	}
+	if cfg.LuaDir != "/srv/openflare/"+defaultLuaDirRelativePath {
+		t.Fatalf("unexpected lua dir: %s", cfg.LuaDir)
+	}
+	if cfg.RuntimeConfigDir != "/srv/openflare/"+defaultRuntimeConfigDirRelativePath {
+		t.Fatalf("unexpected runtime config dir: %s", cfg.RuntimeConfigDir)
+	}
+}
+
+func TestLoadUsesEnvConfigWhenFileIsMissing(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("OPENFLARE_SERVER_URL", "http://127.0.0.1:3000")
+	t.Setenv("OPENFLARE_AGENT_TOKEN", "token")
+	t.Setenv("OPENFLARE_NODE_NAME", "edge-env")
+	t.Setenv("OPENFLARE_NODE_IP", "10.0.0.9")
+	t.Setenv("OPENFLARE_DATA_DIR", "/srv/openflare-env")
+	t.Setenv("OPENFLARE_OPENRESTY_PATH", "/usr/bin/openresty")
+	t.Setenv("OPENFLARE_HEARTBEAT_INTERVAL", "45s")
+	t.Setenv("OPENFLARE_REQUEST_TIMEOUT", "2500")
+	t.Setenv("OPENFLARE_OPENRESTY_OBSERVABILITY_PORT", "19091")
+
+	cfg, err := Load(filepath.Join(dir, "missing-agent.json"))
+	if err != nil {
+		t.Fatalf("Load failed: %v", err)
+	}
+	if cfg.ServerURL != "http://127.0.0.1:3000" || cfg.AccessToken != "token" {
+		t.Fatalf("unexpected env auth config: %#v", cfg)
+	}
+	if cfg.OpenrestyPath != "/usr/bin/openresty" {
+		t.Fatalf("unexpected openresty path: %s", cfg.OpenrestyPath)
+	}
+	if cfg.DataDir != "/srv/openflare-env" {
+		t.Fatalf("unexpected data dir: %s", cfg.DataDir)
+	}
+	if cfg.HeartbeatInterval.Duration() != 45*time.Second {
+		t.Fatalf("unexpected heartbeat interval: %s", cfg.HeartbeatInterval)
+	}
+	if cfg.RequestTimeout.Duration() != 2500*time.Millisecond {
+		t.Fatalf("unexpected request timeout: %s", cfg.RequestTimeout)
+	}
+	if cfg.OpenrestyObservabilityPort != 19091 {
+		t.Fatalf("unexpected observability port: %d", cfg.OpenrestyObservabilityPort)
+	}
+}
+
+func TestLoadDetectsOutboundIPWhenNodeIPMissing(t *testing.T) {
+	nodeip.ResetCacheForTest()
+	previousLookup := nodeip.LookupOutboundIP
+	nodeip.LookupOutboundIP = func(ctx context.Context, strategies ...geoip.OutboundIPStrategy) (net.IP, error) {
+		return net.ParseIP("8.8.8.8"), nil
+	}
+	defer func() {
+		nodeip.LookupOutboundIP = previousLookup
+		nodeip.ResetCacheForTest()
+	}()
+
+	dir := t.TempDir()
+	configPath := filepath.Join(dir, "agent.json")
+	payload := map[string]any{
+		"server_url":  "http://127.0.0.1:3000",
+		"agent_token": "token",
+		"node_name":   "edge-01",
+	}
+	data, err := json.Marshal(payload)
+	if err != nil {
+		t.Fatalf("failed to marshal config: %v", err)
+	}
+	if err = os.WriteFile(configPath, data, 0o644); err != nil {
+		t.Fatalf("failed to write config: %v", err)
+	}
+
+	cfg, err := Load(configPath)
+	if err != nil {
+		t.Fatalf("Load failed: %v", err)
+	}
+	if cfg.NodeIP != "8.8.8.8" {
+		t.Fatalf("expected outbound IP, got %s", cfg.NodeIP)
+	}
+}
+
+func TestLoadFallsBackToLocalIPWhenOutboundLookupFails(t *testing.T) {
+	nodeip.ResetCacheForTest()
+	previousOutboundLookup := nodeip.LookupOutboundIP
+	previousLocalLookup := nodeip.LookupLocalIP
+	nodeip.LookupOutboundIP = func(ctx context.Context, strategies ...geoip.OutboundIPStrategy) (net.IP, error) {
+		return nil, errors.New("realip.cc unavailable")
+	}
+	nodeip.LookupLocalIP = func() string {
+		return "9.9.9.9"
+	}
+	defer func() {
+		nodeip.LookupOutboundIP = previousOutboundLookup
+		nodeip.LookupLocalIP = previousLocalLookup
+		nodeip.ResetCacheForTest()
+	}()
+
+	dir := t.TempDir()
+	configPath := filepath.Join(dir, "agent.json")
+	payload := map[string]any{
+		"server_url":  "http://127.0.0.1:3000",
+		"agent_token": "token",
+		"node_name":   "edge-01",
+	}
+	data, err := json.Marshal(payload)
+	if err != nil {
+		t.Fatalf("failed to marshal config: %v", err)
+	}
+	if err = os.WriteFile(configPath, data, 0o644); err != nil {
+		t.Fatalf("failed to write config: %v", err)
+	}
+
+	cfg, err := Load(configPath)
+	if err != nil {
+		t.Fatalf("Load failed: %v", err)
+	}
+	if cfg.NodeIP != "9.9.9.9" {
+		t.Fatalf("expected local fallback IP, got %s", cfg.NodeIP)
+	}
+}
+
+func TestLoadEnvOverridesConfigFile(t *testing.T) {
+	dir := t.TempDir()
+	configPath := filepath.Join(dir, "agent.json")
+	if err := os.WriteFile(configPath, []byte(`{"server_url":"http://old:3000","agent_token":"old","node_name":"edge-01","node_ip":"10.0.0.8","openresty_path":"/old/openresty"}`), 0o644); err != nil {
+		t.Fatalf("failed to write config: %v", err)
+	}
+	t.Setenv("OPENFLARE_SERVER_URL", "http://new:3000")
+	t.Setenv("OPENFLARE_AGENT_TOKEN", "new-token")
+	t.Setenv("OPENFLARE_OPENRESTY_PATH", "/new/openresty")
+	t.Setenv("OPENFLARE_CITY_MMDB_PATH", "/new/GeoLite2-City.mmdb")
+	t.Setenv("OPENFLARE_CITY_MMDB_DOWNLOAD_URL", "https://geo.example/GeoLite2-City.mmdb")
+
+	cfg, err := Load(configPath)
+	if err != nil {
+		t.Fatalf("Load failed: %v", err)
+	}
+	if cfg.ServerURL != "http://new:3000" {
+		t.Fatalf("expected server url from env, got %s", cfg.ServerURL)
+	}
+	if cfg.AccessToken != "new-token" {
+		t.Fatalf("expected token from env, got %s", cfg.AccessToken)
+	}
+	if cfg.OpenrestyPath != "/new/openresty" {
+		t.Fatalf("expected openresty path from env, got %s", cfg.OpenrestyPath)
+	}
+	if cfg.CityMMDBPath != "/new/GeoLite2-City.mmdb" || cfg.CityMMDBDownloadURL != "https://geo.example/GeoLite2-City.mmdb" {
+		t.Fatalf("unexpected City MMDB env overrides: %s / %s", cfg.CityMMDBPath, cfg.CityMMDBDownloadURL)
+	}
+}
+
+func TestLoadKeepsExplicitCityMMDBConfig(t *testing.T) {
+	dir := t.TempDir()
+	configPath := filepath.Join(dir, "agent.json")
+	payload := `{"server_url":"http://127.0.0.1:3000","agent_token":"token","node_name":"edge-01","node_ip":"10.0.0.8","city_mmdb_path":"/custom/GeoLite2-City.mmdb","city_mmdb_download_url":"https://custom.example/GeoLite2-City.mmdb"}`
+	if err := os.WriteFile(configPath, []byte(payload), 0o644); err != nil {
+		t.Fatalf("failed to write config: %v", err)
+	}
+	cfg, err := Load(configPath)
+	if err != nil {
+		t.Fatalf("Load failed: %v", err)
+	}
+	if cfg.CityMMDBPath != "/custom/GeoLite2-City.mmdb" || cfg.CityMMDBDownloadURL != "https://custom.example/GeoLite2-City.mmdb" {
+		t.Fatalf("explicit City MMDB config changed: %s / %s", cfg.CityMMDBPath, cfg.CityMMDBDownloadURL)
+	}
+}
+
+func TestLoadUsesMillisecondsForIntervals(t *testing.T) {
+	dir := t.TempDir()
+	configPath := filepath.Join(dir, "agent.json")
+	payload := map[string]any{
+		"server_url":         "http://127.0.0.1:3000",
+		"agent_token":        "token",
+		"node_name":          "edge-01",
+		"node_ip":            "10.0.0.8",
+		"heartbeat_interval": 30000,
+		"request_timeout":    1500,
+	}
+	data, err := json.Marshal(payload)
+	if err != nil {
+		t.Fatalf("failed to marshal config: %v", err)
+	}
+	if err = os.WriteFile(configPath, data, 0o644); err != nil {
+		t.Fatalf("failed to write config: %v", err)
+	}
+
+	cfg, err := Load(configPath)
+	if err != nil {
+		t.Fatalf("Load failed: %v", err)
+	}
+
+	if cfg.HeartbeatInterval.Duration() != 30*time.Second {
+		t.Fatalf("unexpected heartbeat interval: %s", cfg.HeartbeatInterval)
+	}
+	if cfg.RequestTimeout.Duration() != 1500*time.Millisecond {
+		t.Fatalf("unexpected request timeout: %s", cfg.RequestTimeout)
+	}
+}
+
+func TestSavePersistsMillisecondsAndOmitsRuntimeVersions(t *testing.T) {
+	dir := t.TempDir()
+	configPath := filepath.Join(dir, "agent.json")
+	if err := os.WriteFile(configPath, []byte(`{"server_url":"http://127.0.0.1:3000","agent_token":"token","node_name":"edge-01","node_ip":"10.0.0.8"}`), 0o644); err != nil {
+		t.Fatalf("failed to write config: %v", err)
+	}
+
+	cfg, err := Load(configPath)
+	if err != nil {
+		t.Fatalf("Load failed: %v", err)
+	}
+	cfg.ExtVersion = "1.27.1.2"
+	cfg.HeartbeatInterval = MillisecondDuration(5 * time.Second)
+	cfg.RequestTimeout = MillisecondDuration(7 * time.Second)
+	cfg.OpenrestyResolvers = []string{"10.0.0.2", "1.1.1.1"}
+
+	if err = cfg.Save(); err != nil {
+		t.Fatalf("Save failed: %v", err)
+	}
+
+	data, err := os.ReadFile(configPath)
+	if err != nil {
+		t.Fatalf("failed to read saved config: %v", err)
+	}
+	var decoded map[string]any
+	if err = json.Unmarshal(data, &decoded); err != nil {
+		t.Fatalf("failed to decode saved config: %v", err)
+	}
+	if _, ok := decoded["agent_version"]; ok {
+		t.Fatal("agent_version should not be persisted")
+	}
+	if _, ok := decoded["nginx_version"]; ok {
+		t.Fatal("nginx_version should not be persisted")
+	}
+	if decoded["heartbeat_interval"] != float64(5000) {
+		t.Fatalf("unexpected heartbeat interval: %#v", decoded["heartbeat_interval"])
+	}
+	if decoded["request_timeout"] != float64(7000) {
+		t.Fatalf("unexpected request timeout: %#v", decoded["request_timeout"])
+	}
+	resolvers, ok := decoded["openresty_resolvers"].([]any)
+	if !ok || len(resolvers) != 2 || resolvers[0] != "10.0.0.2" || resolvers[1] != "1.1.1.1" {
+		t.Fatalf("unexpected resolvers: %#v", decoded["openresty_resolvers"])
+	}
+	if decoded["openresty_observability_port"] != float64(defaultOpenRestyObservabilityPort) {
+		t.Fatalf("unexpected observability port: %#v", decoded["openresty_observability_port"])
+	}
+	if decoded["observability_replay_minutes"] != float64(defaultObservabilityReplayMinutes) {
+		t.Fatalf("unexpected observability replay minutes: %#v", decoded["observability_replay_minutes"])
+	}
+	if decoded["city_mmdb_path"] != cfg.CityMMDBPath || decoded["city_mmdb_download_url"] != cfg.CityMMDBDownloadURL {
+		t.Fatalf("City MMDB config was not persisted: %#v", decoded)
+	}
+	if _, ok := decoded["nginx_path"]; ok {
+		t.Fatal("legacy nginx_path should not be persisted")
+	}
+}
+
+func TestInitialAuthToken(t *testing.T) {
+	tests := []struct {
+		name           string
+		agentToken     string
+		discoveryToken string
+		expected       string
+	}{
+		{
+			name:           "prefer agent token",
+			agentToken:     "agent-token",
+			discoveryToken: "discovery-token",
+			expected:       "agent-token",
+		},
+		{
+			name:           "fallback to discovery token",
+			agentToken:     "   ",
+			discoveryToken: "discovery-token",
+			expected:       "discovery-token",
+		},
+		{
+			name:           "nil config returns empty string",
+			agentToken:     "",
+			discoveryToken: "",
+			expected:       "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var cfg *Config
+			if tt.name != "nil config returns empty string" {
+				cfg = &Config{
+					AccessToken:    tt.agentToken,
+					DiscoveryToken: tt.discoveryToken,
+				}
+			}
+			if token := cfg.InitialAuthToken(); token != tt.expected {
+				t.Fatalf("unexpected initial auth token: %q", token)
+			}
+		})
+	}
+}
+
+func TestNodeIPPriority(t *testing.T) {
+	tests := []struct {
+		name     string
+		ip       string
+		expected int
+	}{
+		{
+			name:     "public ipv4 preferred",
+			ip:       "8.8.8.8",
+			expected: 2,
+		},
+		{
+			name:     "private ipv4 fallback",
+			ip:       "10.0.0.8",
+			expected: 1,
+		},
+		{
+			name:     "link local ignored",
+			ip:       "169.254.1.10",
+			expected: -1,
+		},
+		{
+			name:     "loopback ignored",
+			ip:       "127.0.0.1",
+			expected: -1,
+		},
+		{
+			name:     "nil ignored",
+			ip:       "",
+			expected: -1,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var parsed net.IP
+			if tt.ip != "" {
+				parsed = net.ParseIP(tt.ip)
+			}
+			if got := iputil.Score(parsed); got != tt.expected {
+				t.Fatalf("unexpected priority for %q: got %d want %d", tt.ip, got, tt.expected)
+			}
+		})
+	}
+}

backend/openflare/plugins/agent/config/duration.go

@@ -0,0 +1,9 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package config
+
+import edgeconfig "Wavelet/openflare/share/edge/config"
+
+// MillisecondDuration is an alias for the edge config millisecond-precision duration type.
+type MillisecondDuration = edgeconfig.MillisecondDuration

backend/openflare/plugins/agent/config/version.go

@@ -0,0 +1,7 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package config
+
+// Version is the current agent version string, overridden at build time.
+var Version = "dev"