admin: configure maintenance tasks via admin.toml (#9926)

* admin: configure maintenance tasks via admin.toml

Maintenance task settings could only be edited in the admin UI and live
under <dataDir>/conf, so they silently reverted to defaults whenever the
data directory was recreated. An optional admin.toml now declares vacuum,
balance, and erasure coding settings; keys set there are written through
to the persisted task configs at every startup, overriding UI edits, so
the configuration stays declarative. Generate an example with
"weed scaffold -config=admin".

* vacuum: round min volume age up to whole hours

MinVolumeAgeSeconds was truncated by integer division when converted to
the hour-granular protobuf field, so a sub-hour setting silently became
0 and disabled the age guard.

* admin: split and normalize preferred_tags from admin.toml

A comma-separated string, as set via environment variable, came through
viper as a single slice element. Split on commas and reuse
util.NormalizeTagList, matching the plugin config path.

* scaffold: clarify admin.toml wording

weed/command/admin.go

@@ -171,8 +171,17 @@ var cmdAdmin = &Command{
     - Metrics are disabled when -metricsPort is 0 (the default)
     - Example: weed admin -metricsPort=9327 -master="localhost:9333"
 
+  Maintenance Configuration:
+    - An optional admin.toml declares maintenance task settings
+      ([maintenance.vacuum], [maintenance.balance], [maintenance.erasure_coding])
+    - Settings in admin.toml are applied at every startup, overriding values
+      saved from the admin UI, so they can be managed declaratively
+    - Requires -dataDir; values can also be set via WEED_* environment
+      variables, e.g. WEED_MAINTENANCE_VACUUM_GARBAGE_THRESHOLD=0.3
+    - Generate example admin.toml: weed scaffold -config=admin
+
   Configuration File:
-    - The security.toml file is read from ".", "$HOME/.seaweedfs/",
+    - The security.toml and admin.toml files are read from ".", "$HOME/.seaweedfs/",
       "/usr/local/etc/seaweedfs/", or "/etc/seaweedfs/", in that order
     - Generate example security.toml: weed scaffold -config=security
 
@@ -191,6 +200,9 @@ func runAdmin(cmd *Command, args []string) bool {
 	// Load security configuration
 	util.LoadSecurityConfiguration()
 
+	// Optional admin.toml with maintenance task settings
+	util.LoadConfiguration("admin", false)
+
 	// Apply security.toml / env var fallbacks for credential flags.
 	// CLI flags take precedence over security.toml / WEED_* env vars.
 	applyViperFallback(cmd, a.adminUser, "adminUser", "admin.user")
@@ -337,6 +349,12 @@ func startAdminServer(ctx context.Context, options AdminOptions, enableUI bool,
 		glog.Infof("Data directory created/verified: %s", dataDir)
 	}
 
+	// Write maintenance task settings from admin.toml into the persisted
+	// task configs before the server loads them
+	if err := dash.NewConfigPersistence(dataDir).ApplyMaintenanceConfigFromToml(util.GetViper()); err != nil {
+		return fmt.Errorf("apply admin.toml: %w", err)
+	}
+
 	// Detect TLS configuration to set Secure cookie flag
 	cookieSecure := viper.GetString("https.admin.key") != ""
 

weed/command/scaffold.go

@@ -14,7 +14,7 @@ func init() {
 }
 
 var cmdScaffold = &Command{
-	UsageLine: "scaffold -config=[filer|notification|replication|security|master|volume|shell|credential]",
+	UsageLine: "scaffold -config=[filer|notification|replication|security|master|volume|shell|credential|admin]",
 	Short:     "generate basic configuration files",
 	Long: `Generate configuration files with all possible configurations for you to customize.
 
@@ -31,7 +31,7 @@ var cmdScaffold = &Command{
 
 var (
 	outputPath = cmdScaffold.Flag.String("output", "", "if not empty, save the configuration file to this directory")
-	config     = cmdScaffold.Flag.String("config", "filer", "[filer|notification|replication|security|master|volume|shell|credential] the configuration file to generate")
+	config     = cmdScaffold.Flag.String("config", "filer", "[filer|notification|replication|security|master|volume|shell|credential|admin] the configuration file to generate")
 )
 
 func runScaffold(cmd *Command, args []string) bool {
@@ -54,6 +54,8 @@ func runScaffold(cmd *Command, args []string) bool {
 		content = scaffold.Shell
 	case "credential":
 		content = scaffold.Credential
+	case "admin":
+		content = scaffold.Admin
 	}
 	if content == "" {
 		println("need a valid -config option")

weed/command/scaffold/admin.toml

@@ -0,0 +1,47 @@
+# Put this file in one of the locations, with descending priority
+#    ./admin.toml
+#    $HOME/.seaweedfs/admin.toml
+#    /etc/seaweedfs/admin.toml
+# this file is read by "weed admin"
+
+# Maintenance task settings declared here are applied every time the admin
+# server starts, overriding values saved from the admin UI under
+# <dataDir>/conf. Commented-out keys keep their saved or default values.
+# Requires -dataDir.
+# Each value can also be set via environment variable, e.g.
+#    export WEED_MAINTENANCE_VACUUM_GARBAGE_THRESHOLD=0.3
+
+[maintenance.vacuum]
+# enabled = true
+# vacuum volumes with more deleted content than this ratio
+# garbage_threshold = 0.3
+# how often to scan for volumes needing vacuum
+# scan_interval_seconds = 7200
+# max_concurrent = 2
+# only vacuum volumes older than this (rounded up to whole hours)
+# min_volume_age_seconds = 86400
+
+[maintenance.balance]
+# enabled = true
+# trigger balancing when volume distribution exceeds this ratio
+# imbalance_threshold = 0.2
+# scan_interval_seconds = 1800
+# max_concurrent = 1
+# minimum number of volume servers before balancing
+# min_server_count = 2
+
+[maintenance.erasure_coding]
+# enabled = true
+# only erasure code volumes this full
+# fullness_ratio = 0.95
+# only erasure code volumes not modified for this long
+# quiet_for_seconds = 3600
+# scan_interval_seconds = 3600
+# max_concurrent = 1
+# min_size_mb = 30
+# only process volumes from this collection ("" = all collections)
+# collection_filter = ""
+# disk tags preferred for shard placement
+# preferred_tags = ["fast", "ssd"]
+# EC shard placement constraint, e.g. "020"; empty uses the master default replication
+# replica_placement = ""

weed/command/scaffold/example.go

@@ -35,3 +35,6 @@ var Shell string
 
 //go:embed credential.toml
 var Credential string
+
+//go:embed admin.toml
+var Admin string