Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

refactor(config): resolve CLI/env/file precedence in one place with final-value validation (#20934)

xugangqiangfa1a07196732
diff --git a/cmd/ragflow_server.go b/cmd/ragflow_server.go
index c57cfc319c..1c28fe2f46 100644
--- a/cmd/ragflow_server.go
+++ b/cmd/ragflow_server.go
@@ -72,7 +72,6 @@ import (
"ragflow/internal/engine/kvrocks"
_ "ragflow/internal/ingestion/wire"
"ragflow/internal/server"
- "ragflow/internal/server/config"
"ragflow/internal/utility"
)
@@ -291,60 +290,6 @@ func selectedLogLevel(args *serverArgs, configured string) string {
return configured
}
-// resolveIngestorMaxConcurrentWorkers applies the precedence
-// CLI flag > environment variable > config file > default(1) and returns the
-// resolved ingestor worker count (K), validating it against the inclusive
-// range [MinIngestorWorkers, MaxIngestorWorkers]. An out-of-range or
-// noninteger value at any layer is a fatal startup error.
-func resolveIngestorMaxConcurrentWorkers(args *serverArgs, configured int) (int, error) {
- val := config.MinIngestorWorkers
- if configured > 0 {
- val = configured
- }
- if v := strings.TrimSpace(os.Getenv(common.EnvIngestorMaxConcurrentWorkers)); v != "" {
- n, err := strconv.Atoi(v)
- if err != nil {
- return 0, fmt.Errorf("invalid %s %q: %w", common.EnvIngestorMaxConcurrentWorkers, v, err)
- }
- val = n
- }
- if args.ingestorMaxConcurrentWorkers != nil {
- val = *args.ingestorMaxConcurrentWorkers
- }
- if val < config.MinIngestorWorkers || val > config.MaxIngestorWorkers {
- return 0, fmt.Errorf("ingestor max_concurrent_workers %d out of range [%d, %d]",
- val, config.MinIngestorWorkers, config.MaxIngestorWorkers)
- }
- return val, nil
-}
-
-// resolveIngestorPageConcurrency applies the precedence
-// CLI flag > environment variable > config file > default(2) and returns the
-// resolved per-document page concurrency (N), validating it against the
-// inclusive range [MinPageConcurrency, MaxPageConcurrency]. An out-of-range or
-// noninteger value at any layer is a fatal startup error.
-func resolveIngestorPageConcurrency(args *serverArgs, configured int) (int, error) {
- val := 2 // default page concurrency
- if configured > 0 {
- val = configured
- }
- if v := strings.TrimSpace(os.Getenv(common.EnvIngestorPageConcurrency)); v != "" {
- n, err := strconv.Atoi(v)
- if err != nil {
- return 0, fmt.Errorf("invalid %s %q: %w", common.EnvIngestorPageConcurrency, v, err)
- }
- val = n
- }
- if args.ingestorPageConcurrency != nil {
- val = *args.ingestorPageConcurrency
- }
- if val < config.MinPageConcurrency || val > config.MaxPageConcurrency {
- return 0, fmt.Errorf("ingestor page_concurrency %d out of range [%d, %d]",
- val, config.MinPageConcurrency, config.MaxPageConcurrency)
- }
- return val, nil
-}
-
func printHelp(args *serverArgs) {
switch {
case args.mode == nil || *args.mode == "migrate":
@@ -493,7 +438,20 @@ func main() {
globalConfig := server.GetConfig()
- // override default port if provided
+ // Resolve the effective log level once (CLI > config/env > default) and
+ // validate the final value: an invalid level from the config file or the
+ // environment must abort startup instead of being silently downgraded by
+ // the logger. The early logger above stays CLI-only because the config is
+ // not loaded yet at that point.
+ resolvedLogLevel, err := globalConfig.ResolveLogLevel(arguments.logLevel)
+ if err != nil {
+ fmt.Printf("Failed to resolve log level: %v\n", err)
+ os.Exit(1)
+ }
+ globalConfig.SetLogLevel(resolvedLogLevel)
+
+ // Resolve the effective server port (CLI > config/env > default) and
+ // validate it.
// NOTE: this switch must stay side-effect-free on the LOG (no
// registerNativeDeepDoc here): it runs while only the temporary
// stdout-only logger exists, so anything it logs is lost from the file.
@@ -501,18 +459,27 @@ func main() {
// real file-backed logger is up.
switch *arguments.mode {
case "api":
- apiServerConfig := globalConfig.GetAPIServerConfig()
- port := apiServerConfig.HTTPPort
- if arguments.port != nil {
- port = *arguments.port
- apiServerConfig.HTTPPort = port
+ port, portErr := globalConfig.ResolvePort(globalConfig.GetAPIServerConfig().HTTPPort, arguments.port)
+ if portErr != nil {
+ fmt.Printf("Failed to resolve API server port: %v\n", portErr)
+ os.Exit(1)
+ }
+ globalConfig.SetAPIServerHTTPPort(port)
+ // Disambiguate the log file per bound port when no explicit --name
+ // is given (e.g. two API servers on the same host on different
+ // ports). Restored after the precedence refactor dropped it.
+ if arguments.name == nil {
+ serverName = fmt.Sprintf("api_server_%d", port)
}
case "admin":
- adminServerConfig := globalConfig.GetAdminServerConfig()
- port := adminServerConfig.HTTPPort
- if arguments.port != nil {
- port = *arguments.port
- adminServerConfig.HTTPPort = port
+ port, portErr := globalConfig.ResolvePort(globalConfig.GetAdminServerConfig().HTTPPort, arguments.port)
+ if portErr != nil {
+ fmt.Printf("Failed to resolve admin server port: %v\n", portErr)
+ os.Exit(1)
+ }
+ globalConfig.SetAdminHTTPPort(port)
+ if arguments.name == nil {
+ serverName = fmt.Sprintf("admin_server_%d", port)
}
case "ingestor":
if serverName == "" {
@@ -658,17 +625,16 @@ func main() {
}
}
-func setLogger(serverName string, arguments *serverArgs) {
+func setLogger(serverName string) {
// log filename
logFileName := fmt.Sprintf("%s.log", serverName)
globalConfig := server.GetConfig()
logConfig := globalConfig.GetLogConfig()
- // Reinitialize logger with the configured level and CLI overrides.
- logLevel := selectedLogLevel(arguments, logConfig.Level)
-
- globalConfig.SetLogLevel(logLevel)
+ // The effective level was already resolved (CLI > config/env > default)
+ // and validated in main; read it back instead of re-deciding here.
+ logLevel := logConfig.Level
fileOut := common.FileOutput{
Filename: logFileName,
@@ -795,7 +761,7 @@ func runAdmin(ctx context.Context, serverName string, args *serverArgs) error {
common.Info(fmt.Sprintf("RAGFlow admin version: %s", common.GetRAGFlowVersion()))
// Set log level
- setLogger(serverName, args)
+ setLogger(serverName)
// Start HTTP server in a goroutine
go func() {
@@ -883,7 +849,7 @@ func runIngestor(ctx context.Context, cancel context.CancelFunc, serverName stri
ingestorCfg := globalConfig.GetIngestorConfig()
// Resolve the ingestor worker count (K) from CLI > env > config > default(1)
// and fail fast on an out-of-range value.
- workers, err := resolveIngestorMaxConcurrentWorkers(args, ingestorCfg.MaxConcurrentWorkers)
+ workers, err := globalConfig.GetIngestorMaxConcurrentWorkers(args.ingestorMaxConcurrentWorkers)
if err != nil {
return err
}
@@ -936,7 +902,7 @@ func runIngestor(ctx context.Context, cancel context.CancelFunc, serverName stri
common.Info(fmt.Sprintf("RAGFlow ingestion service version: %s", common.GetRAGFlowVersion()))
// Set log level
- setLogger(serverName, args)
+ setLogger(serverName)
// Start heartbeat reporter to admin server
if hb := startHeartbeat(
@@ -990,7 +956,7 @@ func runSyncer(ctx context.Context, cancel context.CancelFunc, serverName string
common.Info(fmt.Sprintf("RAGFlow file syncer service version: %s", common.GetRAGFlowVersion()))
// Set log level
- setLogger(serverName, args)
+ setLogger(serverName)
// Start heartbeat reporter to admin server
if hb := startHeartbeat(
@@ -1405,7 +1371,7 @@ func startServer(ctx context.Context, serverName string, arguments *serverArgs)
common.Info(fmt.Sprintf("Server starting on port: %d", apiServerConfig.HTTPPort))
// Set log level
- setLogger(serverName, arguments)
+ setLogger(serverName)
// Start server in a goroutine
go func() {
@@ -1588,11 +1554,11 @@ func registerNativeDeepDoc(arguments *serverArgs) error {
// inferenceTotalCores), so a misconfiguration aborts rather than silently
// oversubscribing the box.
cfg := server.GetConfig()
- K, _, errK := cfg.ResolveDeepDocInferenceConcurrency(arguments.deepdocInferenceConcurrency)
+ K, _, errK := cfg.GetDeepDocInferenceConcurrency(arguments.deepdocInferenceConcurrency)
if errK != nil {
common.Fatal("invalid deepdoc inference concurrency", zap.Error(errK))
}
- rawN, explicitN, errN := cfg.ResolveDeepDocInferenceCPUCores(arguments.deepdocInferenceCPUCores)
+ rawN, explicitN, errN := cfg.GetDeepDocInferenceCPUCores(arguments.deepdocInferenceCPUCores)
if errN != nil {
common.Fatal("invalid deepdoc inference cpu cores", zap.Error(errN))
}
@@ -1626,7 +1592,7 @@ func registerNativeDeepDoc(arguments *serverArgs) error {
// Resolve the per-document page concurrency (N) from CLI > env > config >
// default(2) and register it with the shared page worker pool. Fail fast on
// an out-of-range value.
- pageConcurrency, err := resolveIngestorPageConcurrency(arguments, server.GetConfig().GetIngestorConfig().PageConcurrency)
+ pageConcurrency, err := server.GetConfig().GetIngestorPageConcurrency(arguments.ingestorPageConcurrency)
if err != nil {
return err
}
diff --git a/cmd/ragflow_server_deepdoc_test.go b/cmd/ragflow_server_deepdoc_test.go
index aa88311116..bf0f3637b1 100644
--- a/cmd/ragflow_server_deepdoc_test.go
+++ b/cmd/ragflow_server_deepdoc_test.go
@@ -22,7 +22,6 @@ import (
"testing"
"github.com/spf13/viper"
- common "ragflow/internal/common"
native "ragflow/internal/deepdoc/native"
server "ragflow/internal/server/config"
)
@@ -30,7 +29,7 @@ import (
// TestParseArgsDeepDocInferenceConcurrency pins the contract that the CLI parser
// rejects a non-positive or non-integer --deepdoc-inference-concurrency up front
// (both the "--flag=value" and "--flag value" forms), and accepts a positive
-// value. Because the parser guarantees a positive value, ResolveDeepDocInference
+// value. Because the parser guarantees a positive value, GetDeepDocInference
// Concurrency can trust the parsed pointer and needs no extra >0 guard.
func TestParseArgsDeepDocInferenceConcurrency(t *testing.T) {
cases := []struct {
@@ -71,102 +70,6 @@ func TestParseArgsDeepDocInferenceConcurrency(t *testing.T) {
}
}
-// TestResolveIngestorMaxConcurrentWorkers pins the precedence
-// CLI > environment > config file > default(1) and the inclusive [1, 256]
-// range guard. An out-of-range or non-integer value at any layer is a fatal
-// startup error.
-func TestResolveIngestorMaxConcurrentWorkers(t *testing.T) {
- const envKey = common.EnvIngestorMaxConcurrentWorkers
-
- cases := []struct {
- name string
- configured int
- env string // "" means leave unset
- cli *int
- want int
- wantErr bool
- }{
- {"default", 0, "", nil, 1, false},
- {"config only", 5, "", nil, 5, false},
- {"env overrides config", 5, "8", nil, 8, false},
- {"cli overrides env and config", 5, "8", intPtr(12), 12, false},
- {"env invalid errors", 5, "notanint", nil, 0, true},
- {"env only", 0, "9", nil, 9, false},
- {"config above range errors", 300, "", nil, 300, true},
- {"cli below range errors", 0, "", intPtr(0), 0, true},
- {"cli above range errors", 0, "", intPtr(1000), 0, true},
- }
- for _, tc := range cases {
- t.Run(tc.name, func(t *testing.T) {
- // t.Setenv restores the previous value after the subtest.
- t.Setenv(envKey, tc.env)
- args := &serverArgs{ingestorMaxConcurrentWorkers: tc.cli}
- got, err := resolveIngestorMaxConcurrentWorkers(args, tc.configured)
- if tc.wantErr {
- if err == nil {
- t.Fatalf("got nil error, want rejection (configured=%d env=%q cli=%v)",
- tc.configured, tc.env, tc.cli)
- }
- return
- }
- if err != nil {
- t.Fatalf("unexpected error %v", err)
- }
- if got != tc.want {
- t.Fatalf("got %d, want %d (configured=%d env=%q cli=%v)",
- got, tc.want, tc.configured, tc.env, tc.cli)
- }
- })
- }
-}
-
-// TestResolveIngestorPageConcurrency pins the precedence
-// CLI > environment > config file > default(2) and the inclusive [1, 16]
-// range guard. An out-of-range or non-integer value at any layer is a fatal
-// startup error.
-func TestResolveIngestorPageConcurrency(t *testing.T) {
- const envKey = common.EnvIngestorPageConcurrency
-
- cases := []struct {
- name string
- configured int
- env string // "" means leave unset
- cli *int
- want int
- wantErr bool
- }{
- {"default", 0, "", nil, 2, false},
- {"config only", 6, "", nil, 6, false},
- {"env overrides config", 6, "8", nil, 8, false},
- {"cli overrides env and config", 6, "8", intPtr(12), 12, false},
- {"env invalid errors", 6, "notanint", nil, 0, true},
- {"env only", 0, "9", nil, 9, false},
- {"config above range errors", 20, "", nil, 20, true},
- {"cli below range errors", 0, "", intPtr(0), 0, true},
- }
- for _, tc := range cases {
- t.Run(tc.name, func(t *testing.T) {
- t.Setenv(envKey, tc.env)
- args := &serverArgs{ingestorPageConcurrency: tc.cli}
- got, err := resolveIngestorPageConcurrency(args, tc.configured)
- if tc.wantErr {
- if err == nil {
- t.Fatalf("got nil error, want rejection (configured=%d env=%q cli=%v)",
- tc.configured, tc.env, tc.cli)
- }
- return
- }
- if err != nil {
- t.Fatalf("unexpected error %v", err)
- }
- if got != tc.want {
- t.Fatalf("got %d, want %d (configured=%d env=%q cli=%v)",
- got, tc.want, tc.configured, tc.env, tc.cli)
- }
- })
- }
-}
-
// TestParseArgsIngestorMaxConcurrentWorkers pins the contract that the CLI
// parser rejects a non-positive or non-integer --ingestor-max-concurrent-workers
// up front (both the "--flag=value" and "--flag value" forms), and accepts a
@@ -321,13 +224,13 @@ func TestRegisterNativeDeepDocDefaultBootsOnSmallMachine(t *testing.T) {
t.Fatalf("ParseIngestorConfig: %v", err)
}
// No CLI override; both config keys unset.
- K, explicitK, errK := cfg.ResolveDeepDocInferenceConcurrency(nil)
+ K, explicitK, errK := cfg.GetDeepDocInferenceConcurrency(nil)
if errK != nil {
- t.Fatalf("ResolveDeepDocInferenceConcurrency: %v", errK)
+ t.Fatalf("GetDeepDocInferenceConcurrency: %v", errK)
}
- rawN, explicitN, errN := cfg.ResolveDeepDocInferenceCPUCores(nil)
+ rawN, explicitN, errN := cfg.GetDeepDocInferenceCPUCores(nil)
if errN != nil {
- t.Fatalf("ResolveDeepDocInferenceCPUCores: %v", errN)
+ t.Fatalf("GetDeepDocInferenceCPUCores: %v", errN)
}
if explicitK || explicitN {
t.Fatal("default config must report both K and N as not-explicit")
@@ -366,7 +269,3 @@ func TestInferenceTotalCoresIsCgroupAware(t *testing.T) {
t.Fatalf("inferenceTotalCores() = %d, want >= 1", got)
}
}
-
-// intPtr returns a pointer to n, used to build optional CLI override values in
-// the resolver precedence tests.
-func intPtr(n int) *int { return &n }
diff --git a/conf/service_conf.yaml b/conf/service_conf.yaml
index 82745c2877..30a6539dc9 100644
--- a/conf/service_conf.yaml
+++ b/conf/service_conf.yaml
@@ -1,6 +1,6 @@
general:
heartbeat_interval: 3s
-ragflow:
+api:
host: 0.0.0.0
http_port: 9380
# Proxies whose X-Forwarded-For / X-Real-IP headers the Go API server trusts
diff --git a/docker/README.md b/docker/README.md
index 73f4681f18..14e184e112 100644
--- a/docker/README.md
+++ b/docker/README.md
@@ -177,7 +177,7 @@ In the RAGFlow open-source 1.0 release, DeepDoc uses CPU inference.
[service_conf.yaml.template](./service_conf.yaml.template) specifies the system-level configuration for the Go API, Admin, Ingestor, and Syncer services. In a dockerized setup, the generated `service_conf.yaml` file is automatically created from this template (replacing all environment variables by their values).
-- `ragflow`
+- `api`
- `host`: The API server's IP address inside the Docker container. Defaults to `0.0.0.0`.
- `http_port`: The API server's serving port inside the Docker container. Defaults to `9380`.
diff --git a/docker/service_conf.yaml.template b/docker/service_conf.yaml.template
index 0aa225575b..afaef12931 100644
--- a/docker/service_conf.yaml.template
+++ b/docker/service_conf.yaml.template
@@ -1,6 +1,6 @@
general:
heartbeat_interval: 3s
-ragflow:
+api:
host: ${RAGFLOW_HOST:-0.0.0.0}
http_port: 9380
# Proxies whose X-Forwarded-For / X-Real-IP headers the Go API server trusts
diff --git a/docs/administrator/configurations/configurations.md b/docs/administrator/configurations/configurations.md
index 508e780d93..520f08737e 100644
--- a/docs/administrator/configurations/configurations.md
+++ b/docs/administrator/configurations/configurations.md
@@ -159,7 +159,7 @@ If you cannot download the RAGFlow Docker image, try the following mirrors.
[service_conf.yaml.template](https://github.com/infiniflow/ragflow/blob/main/docker/service_conf.yaml.template) specifies the system-level configuration used by the Go API, Admin, Ingestor, and Syncer services.
-### `ragflow`
+### `api`
- `host`: The API server's IP address inside the Docker container. Defaults to `0.0.0.0`.
- `http_port`: The API server's serving port inside the Docker container. Defaults to `9380`.
diff --git a/internal/server/config/admin_config.go b/internal/server/config/admin_config.go
index e9b5d9d5d5..f7f3ddd32b 100644
--- a/internal/server/config/admin_config.go
+++ b/internal/server/config/admin_config.go
@@ -26,24 +26,24 @@ type AdminConfig struct {
}
func (c *Config) ParseAdminConfig(v *viper.Viper) error {
- // Default Admin config
+ // Defaults; overridden from the ROOT viper using the FULL dotted key. The
+ // previous guard `if !v.IsSet("admin") { return }` checked the PARENT
+ // key, which an env var maps to the child key `admin.http_port`, so the
+ // guard was false for a lone env override and the server kept binding
+ // 9381. Reading the full key from the root viper (which carries the
+ // RAGFLOW prefix/replacer/AutomaticEnv from server.Init) honours both the
+ // YAML file and the env layer — including the env-only case. The admin
+ // port env var is RAGFLOW_ADMIN_HTTP_PORT (no prefix doubling, unlike the
+ // ragflow section), so the root read already consults it.
c.admin.Host = "localhost"
c.admin.HTTPPort = 9381
- if !v.IsSet("admin") {
- return nil
- }
- sub := v.Sub("admin")
- if sub == nil {
- return nil
- }
-
- if sub.IsSet("host") {
- c.admin.Host = sub.GetString("host")
+ if v.IsSet("admin.host") {
+ c.admin.Host = v.GetString("admin.host")
}
- if sub.IsSet("http_port") {
- c.admin.HTTPPort = sub.GetInt("http_port")
+ if v.IsSet("admin.http_port") {
+ c.admin.HTTPPort = v.GetInt("admin.http_port")
}
return nil
@@ -52,3 +52,11 @@ func (c *Config) ParseAdminConfig(v *viper.Viper) error {
func (c *Config) GetAdminServerConfig() AdminConfig {
return c.admin
}
+
+// SetAdminHTTPPort stores a resolved admin server port in the global
+// config. GetAdminServerConfig returns a copy, so this setter (not a write
+// into the returned struct) is how a CLI/env override reaches the config
+// the admin server actually binds.
+func (c *Config) SetAdminHTTPPort(port int) {
+ c.admin.HTTPPort = port
+}
diff --git a/internal/server/config/api_server_config.go b/internal/server/config/api_server_config.go
index 1fdb062dc3..017ce9a9f4 100644
--- a/internal/server/config/api_server_config.go
+++ b/internal/server/config/api_server_config.go
@@ -16,7 +16,18 @@
package config
-import "github.com/spf13/viper"
+import (
+ "fmt"
+
+ "github.com/spf13/viper"
+)
+
+// MinPort / MaxPort are the inclusive bounds for a server HTTP port. They
+// are shared by the API and admin server modes.
+const (
+ MinPort = 1
+ MaxPort = 65535
+)
type AuthenticationConfig struct {
DisablePasswordLogin bool `mapstructure:"disable_password_login"`
@@ -43,28 +54,33 @@ func (c *Config) ParseAPIServerConfig(v *viper.Viper) error {
return err
}
- // Default Admin config
+ // Defaults; each is overridden from the ROOT viper using the FULL dotted
+ // key. The previous guard `if !v.IsSet("ragflow") { return }` checked the
+ // PARENT key, which an env var maps to the child key, so the guard was false
+ // for a lone env override and the server kept binding 9380. Reading the full
+ // key from the root viper (which carries the RAGFLOW prefix/replacer/
+ // AutomaticEnv from server.Init) honours both the YAML file and the env
+ // layer — including the env-only case — and stays consistent with the
+ // env-merge fix in ParseLogConfig.
+ //
+ // The section is named `api:`, so viper's AutomaticEnv derives
+ // RAGFLOW_API_HTTP_PORT for the port, mirroring RAGFLOW_ADMIN_HTTP_PORT on
+ // the admin section. The legacy `ragflow:` section name collided with the
+ // RAGFLOW env prefix and produced a doubled RAGFLOW_RAGFLOW_HTTP_PORT, so no
+ // BindEnv is needed and no doubled variable is accepted.
c.apiServer.Host = "localhost"
c.apiServer.HTTPPort = 9380
- if !v.IsSet("ragflow") {
- return nil
- }
- sub := v.Sub("ragflow")
- if sub == nil {
- return nil
- }
-
- if sub.IsSet("host") {
- c.apiServer.Host = sub.GetString("host")
+ if v.IsSet("api.host") {
+ c.apiServer.Host = v.GetString("api.host")
}
- if sub.IsSet("http_port") {
- c.apiServer.HTTPPort = sub.GetInt("http_port")
+ if v.IsSet("api.http_port") {
+ c.apiServer.HTTPPort = v.GetInt("api.http_port")
}
- if sub.IsSet("trusted_proxies") {
- proxies := sub.GetStringSlice("trusted_proxies")
+ if v.IsSet("api.trusted_proxies") {
+ proxies := v.GetStringSlice("api.trusted_proxies")
if proxies == nil {
proxies = []string{}
}
@@ -115,3 +131,34 @@ func (c *Config) EnableRegister() bool {
func (c *Config) GetAPIServerConfig() APIServerConfig {
return c.apiServer
}
+
+// SetAPIServerHTTPPort stores a resolved API server port in the global
+// config. GetAPIServerConfig returns a copy, so this setter (not a write
+// into the returned struct) is how a CLI/env override reaches the config
+// the API server actually binds.
+func (c *Config) SetAPIServerHTTPPort(port int) {
+ c.apiServer.HTTPPort = port
+}
+
+// ResolvePort resolves the effective HTTP port from the precedence
+// CLI flag > the configured port (config file / viper, already merged with
+// env) > the built-in default, and validates the final value against
+// [MinPort, MaxPort]. The configured port is passed by the caller so the
+// SAME validation serves both the API server (apiServer.HTTPPort) and the
+// admin server (admin.HTTPPort) — reading a single receiver field here would
+// make the admin server resolve to the API port and collide with it at
+// startup. The CLI parser still rejects an out-of-range --port up front; this
+// guard owns the config/env layers, where a non-integer value used to reach
+// viper's GetInt as a silent 0 (the server would then listen on a random
+// port).
+func (c *Config) ResolvePort(configured int, cli *int) (int, error) {
+ port := configured
+ if cli != nil {
+ port = *cli
+ }
+ if port < MinPort || port > MaxPort {
+ return 0, fmt.Errorf("invalid port %d: must be in [%d, %d] (check --port or the http_port config key and its environment override)",
+ port, MinPort, MaxPort)
+ }
+ return port, nil
+}
diff --git a/internal/server/config/api_server_config_test.go b/internal/server/config/api_server_config_test.go
index 842951ac8f..0abacabfba 100644
--- a/internal/server/config/api_server_config_test.go
+++ b/internal/server/config/api_server_config_test.go
@@ -18,6 +18,7 @@ package config
import (
"reflect"
+ "strings"
"testing"
"github.com/spf13/viper"
@@ -37,7 +38,7 @@ func TestParseAPIServerConfigTrustedProxies(t *testing.T) {
} {
t.Run(test.name, func(t *testing.T) {
v := viper.New()
- v.Set("ragflow", test.values)
+ v.Set("api", test.values)
cfg := &Config{}
if err := cfg.ParseAPIServerConfig(v); err != nil {
t.Fatalf("ParseAPIServerConfig: %v", err)
@@ -48,3 +49,214 @@ func TestParseAPIServerConfigTrustedProxies(t *testing.T) {
})
}
}
+
+// TestResolvePort pins the precedence CLI flag > config file (viper,
+// already merged with env) > built-in default and the fail-fast range
+// guard [1, 65535] on the FINAL value. The config/env layers used to go
+// unvalidated: a non-integer RAGFLOW_*_HTTP_PORT silently became 0 via
+// viper's GetInt (listening on a random port), and an out-of-range YAML
+// value only failed at ListenAndServe. The CLI parser still rejects an
+// out-of-range --port up front, so a bad CLI value fails with a message
+// naming the flag; this guard owns the config/env layers.
+func TestResolvePort(t *testing.T) {
+ cases := []struct {
+ name string
+ configured int
+ cli *int
+ want int
+ wantErr bool
+ }{
+ {"config default", 9380, nil, 9380, false},
+ {"config custom", 9443, nil, 9443, false},
+ {"cli overrides config", 9380, intPtr(8080), 8080, false},
+ {"cli lower boundary", 9380, intPtr(1), 1, false},
+ {"cli upper boundary", 9380, intPtr(65535), 65535, false},
+ // An explicit zero (e.g. a non-integer env value read as 0 by
+ // viper) or an out-of-range value must fail startup.
+ {"configured zero -> error", 0, nil, 0, true},
+ {"configured above max -> error", 99999, nil, 0, true},
+ {"configured negative -> error", -1, nil, 0, true},
+ {"cli zero -> error", 9380, intPtr(0), 0, true},
+ {"cli above max -> error", 9380, intPtr(65536), 0, true},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ c := &Config{}
+ c.SetAPIServerHTTPPort(tc.configured)
+ got, err := c.ResolvePort(tc.configured, tc.cli)
+ if tc.wantErr {
+ if err == nil {
+ t.Fatalf("ResolvePort(%d, %v) = %d, want error", tc.configured, tc.cli, got)
+ }
+ return
+ }
+ if err != nil {
+ t.Fatalf("ResolvePort(%d, %v) error = %v, want nil", tc.configured, tc.cli, err)
+ }
+ if got != tc.want {
+ t.Fatalf("ResolvePort(%d, %v) = %d, want %d", tc.configured, tc.cli, got, tc.want)
+ }
+ })
+ }
+}
+
+// TestResolvePortHonorsServerSpecificConfig pins that ResolvePort validates
+// the port passed to it rather than always reading the API server's port from
+// the receiver. A regression made ResolvePort read c.apiServer.HTTPPort for
+// every caller, so the admin server (whose configured port is 9381) resolved
+// to 9380 and collided with the API server at startup (CI: "address already in
+// use :9380"). With api=9380 and admin=9381 set independently, resolving the
+// admin's configured port must yield 9381, not 9380.
+func TestResolvePortHonorsServerSpecificConfig(t *testing.T) {
+ c := &Config{}
+ c.SetAPIServerHTTPPort(9380)
+ c.SetAdminHTTPPort(9381)
+
+ // Admin path: caller passes the admin-configured port.
+ got, err := c.ResolvePort(c.GetAdminServerConfig().HTTPPort, nil)
+ if err != nil {
+ t.Fatalf("ResolvePort(admin) error = %v, want nil", err)
+ }
+ if got != 9381 {
+ t.Fatalf("ResolvePort(admin configured) = %d, want 9381 (must not read the API port)", got)
+ }
+
+ // API path: caller passes the api-configured port.
+ got, err = c.ResolvePort(c.GetAPIServerConfig().HTTPPort, nil)
+ if err != nil {
+ t.Fatalf("ResolvePort(api) error = %v, want nil", err)
+ }
+ if got != 9380 {
+ t.Fatalf("ResolvePort(api configured) = %d, want 9380", got)
+ }
+
+ // CLI override must still win regardless of which server calls it.
+ got, err = c.ResolvePort(c.GetAdminServerConfig().HTTPPort, intPtr(9400))
+ if err != nil {
+ t.Fatalf("ResolvePort(admin, --port) error = %v, want nil", err)
+ }
+ if got != 9400 {
+ t.Fatalf("ResolvePort(admin, --port) = %d, want 9400 (CLI must override)", got)
+ }
+}
+
+// TestPortSetterRoundTrip pins the supported write path for a resolved
+// HTTP port. GetAPIServerConfig / GetAdminServerConfig return COPIES, so
+// writing a --port override into the returned struct (as main used to do)
+// silently dropped the override: the server later re-read the port from
+// the global config and bound the unmodified value. The setters are the
+// only way a resolved port reaches the config the servers actually read.
+func TestPortSetterRoundTrip(t *testing.T) {
+ c := &Config{}
+ if err := c.ParseAPIServerConfig(viper.New()); err != nil {
+ t.Fatalf("ParseAPIServerConfig: %v", err)
+ }
+ if err := c.ParseAdminConfig(viper.New()); err != nil {
+ t.Fatalf("ParseAdminConfig: %v", err)
+ }
+ c.SetAPIServerHTTPPort(8080)
+ c.SetAdminHTTPPort(9443)
+ if got := c.GetAPIServerConfig().HTTPPort; got != 8080 {
+ t.Fatalf("API server HTTPPort = %d, want 8080", got)
+ }
+ if got := c.GetAdminServerConfig().HTTPPort; got != 9443 {
+ t.Fatalf("admin server HTTPPort = %d, want 9443", got)
+ }
+}
+
+// TestParseAPIServerConfigReadsEnvOnlyPort pins that a lone RAGFLOW_API_HTTP_PORT
+// (no `api:` YAML section) still reaches the parsed config. The previous guard
+// `if !v.IsSet("ragflow") { return nil }` checked the PARENT key, which an env
+// var maps to the child key, so the guard was false and the env override was
+// silently dropped (the server kept binding 9380). Reading the full dotted key
+// from the root viper (which carries the RAGFLOW prefix/replacer/AutomaticEnv
+// from server.Init) honours the env layer in the env-only case.
+//
+// The section is named `api:`, so viper derives RAGFLOW_API_HTTP_PORT directly.
+// The legacy `ragflow:` section name collided with the RAGFLOW env prefix and
+// made AutomaticEnv resolve the key to a doubled RAGFLOW_RAGFLOW_HTTP_PORT.
+func TestParseAPIServerConfigReadsEnvOnlyPort(t *testing.T) {
+ v := viper.New()
+ v.SetEnvPrefix("RAGFLOW")
+ v.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
+ v.AutomaticEnv()
+
+ t.Setenv("RAGFLOW_API_HTTP_PORT", "9399")
+
+ c := &Config{}
+ if err := c.ParseAPIServerConfig(v); err != nil {
+ t.Fatalf("ParseAPIServerConfig: %v", err)
+ }
+ if got := c.GetAPIServerConfig().HTTPPort; got != 9399 {
+ t.Fatalf("env-only RAGFLOW_API_HTTP_PORT = %d, want 9399 (env layer must reach the config)", got)
+ }
+}
+
+// TestParseAPIServerConfigReadsAPISection pins that the `api:` YAML section
+// reaches the parsed config for host / http_port / trusted_proxies. The section
+// was renamed from the legacy `ragflow:` section, whose name collided with the
+// RAGFLOW env prefix.
+func TestParseAPIServerConfigReadsAPISection(t *testing.T) {
+ v := viper.New()
+ v.Set("api", map[string]interface{}{
+ "host": "0.0.0.0",
+ "http_port": 9443,
+ "trusted_proxies": []string{"10.0.0.0/8"},
+ })
+
+ c := &Config{}
+ if err := c.ParseAPIServerConfig(v); err != nil {
+ t.Fatalf("ParseAPIServerConfig: %v", err)
+ }
+ got := c.GetAPIServerConfig()
+ if got.Host != "0.0.0.0" {
+ t.Fatalf("Host = %q, want %q", got.Host, "0.0.0.0")
+ }
+ if got.HTTPPort != 9443 {
+ t.Fatalf("HTTPPort = %d, want 9443", got.HTTPPort)
+ }
+ if !reflect.DeepEqual(got.TrustedProxies, []string{"10.0.0.0/8"}) {
+ t.Fatalf("TrustedProxies = %#v, want [10.0.0.0/8]", got.TrustedProxies)
+ }
+}
+
+// TestParseAPIServerConfigIgnoresRagflowSection pins the hard rename: the
+// legacy `ragflow:` section (and the doubled RAGFLOW_RAGFLOW_HTTP_PORT env var
+// it produced) is no longer read. A config that still writes `ragflow.http_port`
+// must fall back to the built-in default (9380) rather than silently binding a
+// stale value. The project has not launched yet, so no compatibility shim is
+// kept for the old section name.
+func TestParseAPIServerConfigIgnoresRagflowSection(t *testing.T) {
+ v := viper.New()
+ v.Set("ragflow", map[string]interface{}{"http_port": 9999})
+
+ c := &Config{}
+ if err := c.ParseAPIServerConfig(v); err != nil {
+ t.Fatalf("ParseAPIServerConfig: %v", err)
+ }
+ if got := c.GetAPIServerConfig().HTTPPort; got != 9380 {
+ t.Fatalf("HTTPPort = %d, want 9380 (legacy ragflow: section must be ignored)", got)
+ }
+}
+
+// TestParseAdminConfigReadsEnvOnlyPort mirrors the above for the admin server:
+// a lone RAGFLOW_ADMIN_HTTP_PORT (no `admin:` YAML section) must reach the
+// parsed config instead of being silently dropped by the parent IsSet guard.
+// The admin port env var is RAGFLOW_ADMIN_HTTP_PORT (no prefix doubling), so
+// the root read already consults it.
+func TestParseAdminConfigReadsEnvOnlyPort(t *testing.T) {
+ v := viper.New()
+ v.SetEnvPrefix("RAGFLOW")
+ v.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
+ v.AutomaticEnv()
+
+ t.Setenv("RAGFLOW_ADMIN_HTTP_PORT", "9401")
+
+ c := &Config{}
+ if err := c.ParseAdminConfig(v); err != nil {
+ t.Fatalf("ParseAdminConfig: %v", err)
+ }
+ if got := c.GetAdminServerConfig().HTTPPort; got != 9401 {
+ t.Fatalf("env-only RAGFLOW_ADMIN_HTTP_PORT = %d, want 9401 (env layer must reach the config)", got)
+ }
+}
diff --git a/internal/server/config/deepdoc_config_test.go b/internal/server/config/deepdoc_config_test.go
index 859e5e65fc..cf5d3a3bc3 100644
--- a/internal/server/config/deepdoc_config_test.go
+++ b/internal/server/config/deepdoc_config_test.go
@@ -57,7 +57,7 @@ func TestParseIngestorConfigReadsDeepDocYAML(t *testing.T) {
// TestParseIngestorConfigDeepDocIgnoresEnvVar pins the provenance of the env
// override: ParseIngestorConfig reads ONLY the ingestor.inference_concurrency
// YAML key and does not apply RAGFLOW_DEEPDOC_INFERENCE_CONCURRENCY. The env
-// override is resolved separately by Config.ResolveDeepDocInferenceConcurrency.
+// override is resolved separately by Config.GetDeepDocInferenceConcurrency.
func TestParseIngestorConfigDeepDocIgnoresEnvVar(t *testing.T) {
t.Setenv(common.EnvDeepDocInferenceConcurrency, "9")
@@ -76,7 +76,7 @@ func TestParseIngestorConfigDeepDocIgnoresEnvVar(t *testing.T) {
// override the YAML ingestor.inference_concurrency. viper's Sub() inherits
// AutomaticEnv, so a plain GetInt would consult that variable before the file
// value. The config parse must be file-only; env precedence is applied later by
-// ResolveDeepDocInferenceConcurrency via os.Getenv. This test uses the
+// GetDeepDocInferenceConcurrency via os.Getenv. This test uses the
// production Viper settings (env prefix + replacer + AutomaticEnv) to reproduce
// the real precedence resolution path.
func TestParseIngestorConfigDeepDocIgnoresAutoEnvVar(t *testing.T) {
@@ -99,12 +99,12 @@ func TestParseIngestorConfigDeepDocIgnoresAutoEnvVar(t *testing.T) {
}
}
-// TestResolveDeepDocInferenceConcurrency pins the precedence
+// TestGetDeepDocInferenceConcurrency pins the precedence
// CLI > environment > config file > default(1) and the fail-fast contract: any
// non-integer, non-positive, or otherwise invalid value is an error, never a
// silent fallback. The second return reports whether K was explicitly set by any
// layer (as opposed to the built-in default of 1).
-func TestResolveDeepDocInferenceConcurrency(t *testing.T) {
+func TestGetDeepDocInferenceConcurrency(t *testing.T) {
const envKey = common.EnvDeepDocInferenceConcurrency
cases := []struct {
@@ -112,7 +112,7 @@ func TestResolveDeepDocInferenceConcurrency(t *testing.T) {
configured int
configuredSet bool
env string // "" means leave unset
- cli *int
+ argValue *int
want int
wantExplicit bool
wantErr bool
@@ -138,7 +138,7 @@ func TestResolveDeepDocInferenceConcurrency(t *testing.T) {
}
c.ingestor.deepDocInferenceConcurrency = tc.configured
c.ingestor.deepDocInferenceConcurrencySet = tc.configuredSet
- got, explicit, err := c.ResolveDeepDocInferenceConcurrency(tc.cli)
+ got, explicit, err := c.GetDeepDocInferenceConcurrency(tc.argValue)
if tc.wantErr {
if err == nil {
t.Fatalf("expected error, got %d (explicit=%v)", got, explicit)
@@ -149,8 +149,8 @@ func TestResolveDeepDocInferenceConcurrency(t *testing.T) {
t.Fatalf("unexpected error: %v", err)
}
if got != tc.want {
- t.Fatalf("got %d, want %d (configured=%d configuredSet=%v env=%q cli=%v)",
- got, tc.want, tc.configured, tc.configuredSet, tc.env, tc.cli)
+ t.Fatalf("got %d, want %d (configured=%d configuredSet=%v env=%q argValue=%v)",
+ got, tc.want, tc.configured, tc.configuredSet, tc.env, tc.argValue)
}
if explicit != tc.wantExplicit {
t.Fatalf("explicit = %v, want %v", explicit, tc.wantExplicit)
@@ -159,13 +159,13 @@ func TestResolveDeepDocInferenceConcurrency(t *testing.T) {
}
}
-// TestResolveDeepDocInferenceCPUCores pins the precedence
+// TestGetDeepDocInferenceCPUCores pins the precedence
// CLI > environment > config file > default(0, "derive from K") for the CPU-core
// budget N, and that the second return reports whether N was explicitly set by
// any layer. An explicit 0 means "use all cores" and is returned as 0 (resolved
// against runtime.NumCPU() by the caller); only non-integer or negative values
// error.
-func TestResolveDeepDocInferenceCPUCores(t *testing.T) {
+func TestGetDeepDocInferenceCPUCores(t *testing.T) {
const envKey = common.EnvDeepDocInferenceCPUCores
cases := []struct {
@@ -173,7 +173,7 @@ func TestResolveDeepDocInferenceCPUCores(t *testing.T) {
configured int
configuredSet bool
env string
- cli *int
+ argValue *int
want int
wantExplicit bool
wantErr bool
@@ -200,7 +200,7 @@ func TestResolveDeepDocInferenceCPUCores(t *testing.T) {
}
c.ingestor.deepDocInferenceCPUCores = tc.configured
c.ingestor.deepDocInferenceCPUCoresSet = tc.configuredSet
- got, explicit, err := c.ResolveDeepDocInferenceCPUCores(tc.cli)
+ got, explicit, err := c.GetDeepDocInferenceCPUCores(tc.argValue)
if tc.wantErr {
if err == nil {
t.Fatalf("expected error, got %d (explicit=%v)", got, explicit)
@@ -211,8 +211,8 @@ func TestResolveDeepDocInferenceCPUCores(t *testing.T) {
t.Fatalf("unexpected error: %v", err)
}
if got != tc.want {
- t.Fatalf("got %d, want %d (configured=%d configuredSet=%v env=%q cli=%v)",
- got, tc.want, tc.configured, tc.configuredSet, tc.env, tc.cli)
+ t.Fatalf("got %d, want %d (configured=%d configuredSet=%v env=%q argValue=%v)",
+ got, tc.want, tc.configured, tc.configuredSet, tc.env, tc.argValue)
}
if explicit != tc.wantExplicit {
t.Fatalf("explicit = %v, want %v", explicit, tc.wantExplicit)
@@ -265,3 +265,5 @@ func TestParseIngestorConfigReadsDeepDocCPUCoresYAML(t *testing.T) {
}
func intPtr(n int) *int { return &n }
+
+func strPtr(s string) *string { return &s }
diff --git a/internal/server/config/ingestor_config.go b/internal/server/config/ingestor_config.go
index 87898630a1..fcb540326d 100644
--- a/internal/server/config/ingestor_config.go
+++ b/internal/server/config/ingestor_config.go
@@ -31,7 +31,7 @@ import (
type IngestorConfig struct {
// MaxConcurrentWorkers bounds how many ingestion tasks the ingestor runs in
// parallel — it is the NATS consumer worker count. Valid range [1, 256],
- // enforced at startup by the CLI/env/config resolver (ResolveIngestor*); a
+ // enforced at startup by the CLI/env/config resolver (GetIngestor*); a
// value outside that range is a fatal startup error. Default 1.
MaxConcurrentWorkers int `mapstructure:"max_concurrent_workers"`
// PageConcurrency bounds the total number of PDF pages parsed concurrently
@@ -51,7 +51,7 @@ type IngestorConfig struct {
// cores inference may occupy is at most deepDocInferenceCPUCores. K must be a
// positive integer and may not exceed the machine's CPU core count. Default
// 1. Read from the file-only ingestor.inference_concurrency key; env/CLI
- // precedence is applied later by ResolveDeepDocInferenceConcurrency.
+ // precedence is applied later by GetDeepDocInferenceConcurrency.
deepDocInferenceConcurrency int
// deepDocInferenceConcurrencySet is true when inference_concurrency was
// explicitly present in the config file. It lets the server distinguish
@@ -116,8 +116,8 @@ func (c *Config) ParseIngestorConfig(v *viper.Viper) error {
// sub.GetInt would also consult the auto-derived env vars
// RAGFLOW_INGESTOR_INFERENCE_CONCURRENCY / RAGFLOW_INGESTOR_INFERENCE_CPU_CORES
// and could override or (on a non-integer value) clobber the YAML setting.
- // Env precedence belongs exclusively to ResolveDeepDocInferenceConcurrency /
- // ResolveDeepDocInferenceCPUCores (os.Getenv), so the config tier must be
+ // Env precedence belongs exclusively to GetDeepDocInferenceConcurrency /
+ // GetDeepDocInferenceCPUCores (os.Getenv), so the config tier must be
// the raw file value. Repoint the env prefix at an impossible token to
// deterministically disable AutomaticEnv for this read. A present-but
// non-integer value is a hard error (cast.ToIntE) rather than a silent 0.
@@ -142,14 +142,14 @@ func (c *Config) ParseIngestorConfig(v *viper.Viper) error {
return nil
}
-// ResolveDeepDocInferenceConcurrency resolves the effective DeepDoc inference
+// GetDeepDocInferenceConcurrency resolves the effective DeepDoc inference
// concurrency K. Precedence (highest wins): CLI flag > environment variable
// RAGFLOW_DEEPDOC_INFERENCE_CONCURRENCY > ingestor.inference_concurrency
// (config file) > default (1). It returns the resolved value, whether it was
// explicitly set by any layer (config, env, or CLI) as opposed to the built-in
// default, and any error. An explicit value that is non-integer, non-positive,
// or otherwise invalid is reported as an error rather than silently ignored.
-func (c *Config) ResolveDeepDocInferenceConcurrency(cli *int) (int, bool, error) {
+func (c *Config) GetDeepDocInferenceConcurrency(argValue *int) (int, bool, error) {
val := c.ingestor.deepDocInferenceConcurrency
explicit := c.ingestor.deepDocInferenceConcurrencySet
if explicit && val <= 0 {
@@ -172,21 +172,21 @@ func (c *Config) ResolveDeepDocInferenceConcurrency(cli *int) (int, bool, error)
}
// The CLI parser rejects a non-positive --deepdoc-inference-concurrency up
// front, so the parsed value is already positive; no extra >0 guard needed.
- if cli != nil && *cli > 0 {
- val = *cli
+ if argValue != nil && *argValue > 0 {
+ val = *argValue
explicit = true
}
return val, explicit, nil
}
-// ResolveDeepDocInferenceCPUCores resolves the requested CPU-core budget N for
+// GetDeepDocInferenceCPUCores resolves the requested CPU-core budget N for
// DeepDoc in-process inference. Precedence (highest wins): CLI flag > environment
// variable RAGFLOW_DEEPDOC_INFERENCE_CPU_CORES > ingestor.inference_cpu_cores
// (config file) > default (0, meaning "derive from K"). It returns the raw value
// (0 still means "all cores" when explicit), whether N was explicitly set by any
// layer, and any error. A non-integer or negative value is reported as an error;
// an explicit 0 is valid and means "use all available cores".
-func (c *Config) ResolveDeepDocInferenceCPUCores(cli *int) (int, bool, error) {
+func (c *Config) GetDeepDocInferenceCPUCores(argValue *int) (int, bool, error) {
val := c.ingestor.deepDocInferenceCPUCores
explicit := c.ingestor.deepDocInferenceCPUCoresSet
if explicit && val < 0 {
@@ -205,13 +205,67 @@ func (c *Config) ResolveDeepDocInferenceCPUCores(cli *int) (int, bool, error) {
}
// The CLI parser accepts a non-negative --deepdoc-inference-cpu-cores (0 =
// all cores), so the parsed value is already >= 0.
- if cli != nil {
- val = *cli
+ if argValue != nil {
+ val = *argValue
explicit = true
}
return val, explicit, nil
}
+// GetIngestorMaxConcurrentWorkers applies the precedence
+// CLI flag > environment variable > config file > default(1) and returns
+// the resolved ingestor worker count (K), validating it against the
+// inclusive range [MinIngestorWorkers, MaxIngestorWorkers]. An out-of-range
+// or noninteger value at any layer is a fatal startup error.
+func (c *Config) GetIngestorMaxConcurrentWorkers(argValue *int) (int, error) {
+ val := MinIngestorWorkers
+ if c.ingestor.MaxConcurrentWorkers > 0 {
+ val = c.ingestor.MaxConcurrentWorkers
+ }
+ if v := strings.TrimSpace(os.Getenv(common.EnvIngestorMaxConcurrentWorkers)); v != "" {
+ n, err := strconv.Atoi(v)
+ if err != nil {
+ return 0, fmt.Errorf("invalid %s %q: %w", common.EnvIngestorMaxConcurrentWorkers, v, err)
+ }
+ val = n
+ }
+ if argValue != nil {
+ val = *argValue
+ }
+ if val < MinIngestorWorkers || val > MaxIngestorWorkers {
+ return 0, fmt.Errorf("ingestor max_concurrent_workers %d out of range [%d, %d]",
+ val, MinIngestorWorkers, MaxIngestorWorkers)
+ }
+ return val, nil
+}
+
+// GetIngestorPageConcurrency applies the precedence
+// CLI flag > environment variable > config file > default(2) and returns
+// the resolved per-document page concurrency (N), validating it against
+// the inclusive range [MinPageConcurrency, MaxPageConcurrency]. An
+// out-of-range or noninteger value at any layer is a fatal startup error.
+func (c *Config) GetIngestorPageConcurrency(argValue *int) (int, error) {
+ val := 2 // default page concurrency
+ if c.ingestor.PageConcurrency > 0 {
+ val = c.ingestor.PageConcurrency
+ }
+ if v := strings.TrimSpace(os.Getenv(common.EnvIngestorPageConcurrency)); v != "" {
+ n, err := strconv.Atoi(v)
+ if err != nil {
+ return 0, fmt.Errorf("invalid %s %q: %w", common.EnvIngestorPageConcurrency, v, err)
+ }
+ val = n
+ }
+ if argValue != nil {
+ val = *argValue
+ }
+ if val < MinPageConcurrency || val > MaxPageConcurrency {
+ return 0, fmt.Errorf("ingestor page_concurrency %d out of range [%d, %d]",
+ val, MinPageConcurrency, MaxPageConcurrency)
+ }
+ return val, nil
+}
+
func (c *Config) GetIngestorConfig() *IngestorConfig {
return &c.ingestor
}
diff --git a/internal/server/config/ingestor_config_test.go b/internal/server/config/ingestor_config_test.go
index aa67f40405..4da4bc074b 100644
--- a/internal/server/config/ingestor_config_test.go
+++ b/internal/server/config/ingestor_config_test.go
@@ -20,6 +20,8 @@ import (
"testing"
"github.com/spf13/viper"
+
+ "ragflow/internal/common"
)
func TestParseIngestorConfigReadsWorkerAndCompilerSettings(t *testing.T) {
@@ -129,3 +131,107 @@ func TestParseIngestorConfigToleratesOutOfRangePageConcurrency(t *testing.T) {
})
}
}
+
+// TestGetIngestorMaxConcurrentWorkers pins the precedence
+// CLI > environment > config file > default(1) and the inclusive [1, 256]
+// range guard on the FINAL value. An out-of-range or non-integer value at
+// any layer is a fatal startup error.
+func TestGetIngestorMaxConcurrentWorkers(t *testing.T) {
+ const envKey = common.EnvIngestorMaxConcurrentWorkers
+
+ cases := []struct {
+ name string
+ configured int
+ env string // "" means leave unset
+ argValue *int
+ want int
+ wantErr bool
+ }{
+ {"default", 0, "", nil, 1, false},
+ {"config only", 5, "", nil, 5, false},
+ {"env overrides config", 5, "8", nil, 8, false},
+ {"cli overrides env and config", 5, "8", intPtr(12), 12, false},
+ {"env invalid errors", 5, "notanint", nil, 0, true},
+ {"env only", 0, "9", nil, 9, false},
+ {"config above range errors", 300, "", nil, 0, true},
+ {"cli below range errors", 0, "", intPtr(0), 0, true},
+ {"cli above range errors", 0, "", intPtr(1000), 0, true},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ // t.Setenv restores the previous value after the subtest.
+ t.Setenv(envKey, tc.env)
+ c := &Config{}
+ if err := c.ParseIngestorConfig(viper.New()); err != nil {
+ t.Fatalf("ParseIngestorConfig: %v", err)
+ }
+ c.ingestor.MaxConcurrentWorkers = tc.configured
+ got, err := c.GetIngestorMaxConcurrentWorkers(tc.argValue)
+ if tc.wantErr {
+ if err == nil {
+ t.Fatalf("got nil error, want rejection (configured=%d env=%q argValue=%v)",
+ tc.configured, tc.env, tc.argValue)
+ }
+ return
+ }
+ if err != nil {
+ t.Fatalf("unexpected error %v", err)
+ }
+ if got != tc.want {
+ t.Fatalf("got %d, want %d (configured=%d env=%q argValue=%v)",
+ got, tc.want, tc.configured, tc.env, tc.argValue)
+ }
+ })
+ }
+}
+
+// TestGetIngestorPageConcurrency pins the precedence
+// CLI > environment > config file > default(2) and the inclusive [1, 16]
+// range guard on the FINAL value. An out-of-range or non-integer value at
+// any layer is a fatal startup error.
+func TestGetIngestorPageConcurrency(t *testing.T) {
+ const envKey = common.EnvIngestorPageConcurrency
+
+ cases := []struct {
+ name string
+ configured int
+ env string // "" means leave unset
+ argValue *int
+ want int
+ wantErr bool
+ }{
+ {"default", 0, "", nil, 2, false},
+ {"config only", 6, "", nil, 6, false},
+ {"env overrides config", 6, "8", nil, 8, false},
+ {"cli overrides env and config", 6, "8", intPtr(12), 12, false},
+ {"env invalid errors", 6, "notanint", nil, 0, true},
+ {"env only", 0, "9", nil, 9, false},
+ {"config above range errors", 20, "", nil, 0, true},
+ {"cli below range errors", 0, "", intPtr(0), 0, true},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Setenv(envKey, tc.env)
+ c := &Config{}
+ if err := c.ParseIngestorConfig(viper.New()); err != nil {
+ t.Fatalf("ParseIngestorConfig: %v", err)
+ }
+ c.ingestor.PageConcurrency = tc.configured
+ got, err := c.GetIngestorPageConcurrency(tc.argValue)
+ if tc.wantErr {
+ if err == nil {
+ t.Fatalf("got nil error, want rejection (configured=%d env=%q argValue=%v)",
+ tc.configured, tc.env, tc.argValue)
+ }
+ return
+ }
+ if err != nil {
+ t.Fatalf("unexpected error %v", err)
+ }
+ if got != tc.want {
+ t.Fatalf("got %d, want %d (configured=%d env=%q argValue=%v)",
+ got, tc.want, tc.configured, tc.env, tc.argValue)
+ }
+ })
+ }
+}
diff --git a/internal/server/config/log_config.go b/internal/server/config/log_config.go
index da07b807b9..3b217906b4 100644
--- a/internal/server/config/log_config.go
+++ b/internal/server/config/log_config.go
@@ -17,6 +17,8 @@
package config
import (
+ "fmt"
+
"github.com/spf13/viper"
"ragflow/internal/common"
@@ -60,41 +62,40 @@ func (c *Config) ParseLogConfig(v *viper.Viper) error {
c.log.MaxAge = common.DefaultLogMaxAgeDays
c.log.Compress = boolPtr(common.DefaultLogCompress)
- if !v.IsSet("log") {
- return nil
- }
- sub := v.Sub("log")
- if sub == nil {
- return nil
+ // Read each log.* key from the ROOT viper (which carries the
+ // prefix/replacer/AutomaticEnv configured in server.Init) rather than
+ // from v.Sub("log"). viper's Sub returns nil for an env-only key, so a
+ // lone RAGFLOW_LOG_LEVEL (no `log:` YAML section) would otherwise be
+ // silently dropped. Reading from the root honours the env override in
+ // both the config-file and env-only cases, and env wins over the file
+ // (AutomaticEnv precedence).
+ if v.IsSet("log.level") {
+ c.log.Level = v.GetString("log.level")
}
- if sub.IsSet("level") {
- c.log.Level = sub.GetString("level")
+ if v.IsSet("log.format") {
+ c.log.Format = v.GetString("log.format")
}
- if sub.IsSet("format") {
- c.log.Format = sub.GetString("format")
+ if v.IsSet("log.path") {
+ c.log.Path = v.GetString("log.path")
}
- if sub.IsSet("path") {
- c.log.Path = sub.GetString("path")
+ if v.IsSet("log.max_size") {
+ c.log.MaxSize = v.GetInt("log.max_size")
}
- if sub.IsSet("max_size") {
- c.log.MaxSize = sub.GetInt("max_size")
+ if v.IsSet("log.max_backups") {
+ c.log.MaxBackups = v.GetInt("log.max_backups")
}
- if sub.IsSet("max_backups") {
- c.log.MaxBackups = sub.GetInt("max_backups")
+ if v.IsSet("log.max_age") {
+ c.log.MaxAge = v.GetInt("log.max_age")
}
- if sub.IsSet("max_age") {
- c.log.MaxAge = sub.GetInt("max_age")
- }
-
- if sub.IsSet("compress") {
- v := sub.GetBool("compress")
- c.log.Compress = &v
+ if v.IsSet("log.compress") {
+ compress := v.GetBool("log.compress")
+ c.log.Compress = &compress
}
return nil
@@ -113,3 +114,27 @@ func (c *Config) GetLogConfig() LogConfig {
func (c *Config) SetLogLevel(level string) {
c.log.Level = level
}
+
+// ResolveLogLevel resolves the effective log level from the precedence
+// CLI flag > config file (viper, already merged with the environment) >
+// default ("warn"), and validates the final value against the supported
+// set. An invalid level from any layer is a fatal startup error rather
+// than a silent downgrade: common.InitLogger falls back to info for
+// unknown levels, which would hide the misconfiguration. The CLI parser
+// still rejects an invalid --log-level up front, so a bad CLI value fails
+// with a message naming the flag; this check owns the config/env layers.
+func (c *Config) ResolveLogLevel(cli *string) (string, error) {
+ level := c.log.Level
+ if cli != nil {
+ level = *cli
+ }
+ if level == "" {
+ level = "warn"
+ }
+ switch level {
+ case "debug", "info", "warn", "error":
+ return level, nil
+ default:
+ return "", fmt.Errorf("invalid log level %q: must be debug, info, warn, or error (check --log-level or the log.level config key)", level)
+ }
+}
diff --git a/internal/server/config/log_config_test.go b/internal/server/config/log_config_test.go
new file mode 100644
index 0000000000..0f21739687
--- /dev/null
+++ b/internal/server/config/log_config_test.go
@@ -0,0 +1,174 @@
+//
+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+package config
+
+import (
+ "strings"
+ "testing"
+
+ "github.com/spf13/viper"
+)
+
+// TestResolveLogLevel pins the precedence CLI flag > config file (viper,
+// already merged with env) > default ("warn") and the fail-fast contract:
+// the FINAL resolved value is validated once, so an invalid level reaching
+// startup from the config file or the environment is rejected instead of
+// being silently downgraded by the logger.
+func TestResolveLogLevel(t *testing.T) {
+ cases := []struct {
+ name string
+ configLevel string // "" means do not set log.level in the config
+ cli *string
+ want string
+ wantErr bool
+ }{
+ {"default when nothing configured", "", nil, "warn", false},
+ {"config only", "debug", nil, "debug", false},
+ {"cli overrides config", "debug", strPtr("error"), "error", false},
+ {"cli only", "", strPtr("info"), "info", false},
+ {"warn from config", "warn", nil, "warn", false},
+ // An invalid level at the config layer must fail startup, not fall
+ // back silently (common.InitLogger downgrades unknown levels to info).
+ {"config invalid -> error", "verbose", nil, "", true},
+ {"cli invalid -> error", "debug", strPtr("verbose"), "", true},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ v := viper.New()
+ if tc.configLevel != "" {
+ v.Set("log", map[string]any{"level": tc.configLevel})
+ }
+ c := &Config{}
+ if err := c.ParseLogConfig(v); err != nil {
+ t.Fatalf("ParseLogConfig: %v", err)
+ }
+ got, err := c.ResolveLogLevel(tc.cli)
+ if tc.wantErr {
+ if err == nil {
+ t.Fatalf("ResolveLogLevel() = %q, want error", got)
+ }
+ return
+ }
+ if err != nil {
+ t.Fatalf("ResolveLogLevel() error = %v, want nil", err)
+ }
+ if got != tc.want {
+ t.Fatalf("ResolveLogLevel() = %q, want %q", got, tc.want)
+ }
+ })
+ }
+}
+
+// TestResolveLogLevelZeroValueConfigDefaults pins the defensive default: a
+// Config that never ran ParseLogConfig (empty Level) resolves to the
+// documented default "warn" rather than failing on an empty string.
+func TestResolveLogLevelZeroValueConfigDefaults(t *testing.T) {
+ c := &Config{}
+ got, err := c.ResolveLogLevel(nil)
+ if err != nil {
+ t.Fatalf("ResolveLogLevel() error = %v, want nil", err)
+ }
+ if got != "warn" {
+ t.Fatalf("ResolveLogLevel() = %q, want %q", got, "warn")
+ }
+}
+
+// newEnvViper mirrors the production viper wiring in server.Init: env prefix
+// RAGFLOW, "." -> "_" key replacer, and AutomaticEnv. Without this, an
+// env-only key (e.g. RAGFLOW_LOG_LEVEL with no `log:` YAML section) is not
+// visible to the parser and the override is silently dropped.
+func newEnvViper() *viper.Viper {
+ v := viper.New()
+ v.SetEnvPrefix("RAGFLOW")
+ v.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
+ v.AutomaticEnv()
+ return v
+}
+
+// TestResolveLogLevelEnvOverride pins the ENVIRONMENT layer of the log-level
+// precedence (the layer the config-file-only tests above do not exercise).
+// RAGFLOW_LOG_LEVEL must reach ResolveLogLevel so an invalid value aborts
+// startup instead of being silently downgraded by common.InitLogger, and a
+// valid value wins over the built-in default. The CLI flag still overrides
+// the env value.
+func TestResolveLogLevelEnvOverride(t *testing.T) {
+ cases := []struct {
+ name string
+ envVal string // RAGFLOW_LOG_LEVEL; "" means unset
+ cli *string
+ want string
+ wantErr bool
+ }{
+ {"env only", "debug", nil, "debug", false},
+ {"env warn", "warn", nil, "warn", false},
+ {"cli overrides env", "debug", strPtr("error"), "error", false},
+ // An invalid level arriving from the environment must fail startup,
+ // not fall back silently (common.InitLogger downgrades unknown
+ // levels to info).
+ {"env invalid -> error", "verbose", nil, "", true},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ v := newEnvViper()
+ if tc.envVal != "" {
+ t.Setenv("RAGFLOW_LOG_LEVEL", tc.envVal)
+ }
+ c := &Config{}
+ if err := c.ParseLogConfig(v); err != nil {
+ t.Fatalf("ParseLogConfig: %v", err)
+ }
+ got, err := c.ResolveLogLevel(tc.cli)
+ if tc.wantErr {
+ if err == nil {
+ t.Fatalf("ResolveLogLevel() = %q, want error", got)
+ }
+ return
+ }
+ if err != nil {
+ t.Fatalf("ResolveLogLevel() error = %v, want nil", err)
+ }
+ if got != tc.want {
+ t.Fatalf("ResolveLogLevel() = %q, want %q", got, tc.want)
+ }
+ })
+ }
+}
+
+// TestParseLogConfigReadsEnv pins that an env-only override (no `log:` YAML
+// section) reaches the parsed config for every log.* key. viper's v.Sub("log")
+// returns nil for an env-only key, so the parser must read each key from the
+// root viper (which honours AutomaticEnv) rather than from a Sub view.
+func TestParseLogConfigReadsEnv(t *testing.T) {
+ v := newEnvViper()
+ t.Setenv("RAGFLOW_LOG_LEVEL", "error")
+ t.Setenv("RAGFLOW_LOG_PATH", "/var/log/ragflow")
+ t.Setenv("RAGFLOW_LOG_MAX_SIZE", "200")
+
+ c := &Config{}
+ if err := c.ParseLogConfig(v); err != nil {
+ t.Fatalf("ParseLogConfig: %v", err)
+ }
+ if got := c.GetLogConfig().Level; got != "error" {
+ t.Fatalf("Level = %q, want %q (env override dropped?)", got, "error")
+ }
+ if got := c.GetLogConfig().Path; got != "/var/log/ragflow" {
+ t.Fatalf("Path = %q, want %q (env override dropped?)", got, "/var/log/ragflow")
+ }
+ if got := c.GetLogConfig().MaxSize; got != 200 {
+ t.Fatalf("MaxSize = %d, want 200 (env override dropped?)", got)
+ }
+}