Skip to content

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

refactor(cmd): parse CLI flags with the stdlib flag package (#20876)

xugangqiang0bdba864b962
diff --git a/cmd/args_flag_test.go b/cmd/args_flag_test.go
new file mode 100644
index 0000000000..043e74a2d6
--- /dev/null
+++ b/cmd/args_flag_test.go
@@ -0,0 +1,631 @@
+//
+// 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 main
+
+import (
+ "os"
+ "reflect"
+ "strings"
+ "testing"
+)
+
+// TestParseArgsStandardSyntaxMatrix is the core contract of the stdlib flag
+// migration: every value-taking flag must parse identically in all four
+// standard forms — "--flag value", "--flag=value", "-flag value" and
+// "-flag=value" (the flag package treats one and two dashes the same, and
+// accepts the equals form for both).
+func TestParseArgsStandardSyntaxMatrix(t *testing.T) {
+ cases := []struct {
+ flag string
+ value string
+ }{
+ {"--log-level", "debug"},
+ {"--config", "cfg.yaml"},
+ {"--name", "worker-1"},
+ {"--port", "8080"},
+ {"--admin-host", "1.2.3.4:5678"},
+ {"--deepdoc-inference-concurrency", "4"},
+ {"--ingestor-max-concurrent-workers", "8"},
+ {"--ingestor-page-concurrency", "4"},
+ {"--deepdoc-inference-cpu-cores", "2"},
+ }
+ for _, c := range cases {
+ long := c.flag
+ short := "-" + strings.TrimPrefix(c.flag, "-")
+ forms := [][]string{
+ {"ragflow_server", "--api", long, c.value},
+ {"ragflow_server", "--api", long + "=" + c.value},
+ {"ragflow_server", "--api", short, c.value},
+ {"ragflow_server", "--api", short + "=" + c.value},
+ }
+ want, err := parseArgsFrom(forms[0])
+ if err != nil {
+ t.Fatalf("parseArgsFrom(%v) error = %v", forms[0], err)
+ }
+ for _, form := range forms[1:] {
+ got, err := parseArgsFrom(form)
+ if err != nil {
+ t.Fatalf("parseArgsFrom(%v) error = %v", form, err)
+ }
+ if !reflect.DeepEqual(got, want) {
+ t.Errorf("form %v parsed differently from %v:\n got = %+v\n want = %+v", form, forms[0], got, want)
+ }
+ }
+ }
+}
+
+// TestParseArgsShortAliases covers the short spellings -f/--config and
+// -p/--port, which must also accept the equals form (the hand-rolled parser
+// rejected "-p=80").
+func TestParseArgsShortAliases(t *testing.T) {
+ forms := [][]string{
+ {"ragflow_server", "--api", "--config", "cfg.yaml"},
+ {"ragflow_server", "--api", "--config=cfg.yaml"},
+ {"ragflow_server", "--api", "-f", "cfg.yaml"},
+ {"ragflow_server", "--api", "-f=cfg.yaml"},
+ {"ragflow_server", "--api", "-config", "cfg.yaml"},
+ {"ragflow_server", "--api", "-config=cfg.yaml"},
+ }
+ want, err := parseArgsFrom(forms[0])
+ if err != nil {
+ t.Fatalf("parseArgsFrom(%v) error = %v", forms[0], err)
+ }
+ for _, form := range forms[1:] {
+ got, err := parseArgsFrom(form)
+ if err != nil {
+ t.Fatalf("parseArgsFrom(%v) error = %v", form, err)
+ }
+ if !reflect.DeepEqual(got, want) {
+ t.Errorf("form %v parsed differently:\n got = %+v\n want = %+v", form, got, want)
+ }
+ }
+
+ portForms := [][]string{
+ {"ragflow_server", "--api", "--port", "8080"},
+ {"ragflow_server", "--api", "--port=8080"},
+ {"ragflow_server", "--api", "-p", "8080"},
+ {"ragflow_server", "--api", "-p=8080"},
+ {"ragflow_server", "--api", "-port", "8080"},
+ {"ragflow_server", "--api", "-port=8080"},
+ }
+ want, err = parseArgsFrom(portForms[0])
+ if err != nil {
+ t.Fatalf("parseArgsFrom(%v) error = %v", portForms[0], err)
+ }
+ for _, form := range portForms[1:] {
+ got, err := parseArgsFrom(form)
+ if err != nil {
+ t.Fatalf("parseArgsFrom(%v) error = %v", form, err)
+ }
+ if !reflect.DeepEqual(got, want) {
+ t.Errorf("form %v parsed differently:\n got = %+v\n want = %+v", form, got, want)
+ }
+ }
+}
+
+// TestParseArgsBoolFlagForms covers the standard boolean spellings: bare,
+// "=true" and "=false". A "=false" boolean is off, not an error.
+func TestParseArgsBoolFlagForms(t *testing.T) {
+ for _, form := range []string{"--profile", "--profile=true", "-profile", "-profile=true"} {
+ args, err := parseArgsFrom([]string{"ragflow_server", "--api", form})
+ if err != nil {
+ t.Fatalf("parseArgsFrom(%q) error = %v", form, err)
+ }
+ if !args.enablePProf {
+ t.Errorf("%q enablePProf = false, want true", form)
+ }
+ }
+ for _, form := range []string{"--profile=false", "-profile=false"} {
+ args, err := parseArgsFrom([]string{"ragflow_server", "--api", form})
+ if err != nil {
+ t.Fatalf("parseArgsFrom(%q) error = %v", form, err)
+ }
+ if args.enablePProf {
+ t.Errorf("%q enablePProf = true, want false", form)
+ }
+ }
+ for _, form := range []string{"--init-superuser", "--init-superuser=true", "-init-superuser"} {
+ args, err := parseArgsFrom([]string{"ragflow_server", "--admin", form})
+ if err != nil {
+ t.Fatalf("parseArgsFrom(%q) error = %v", form, err)
+ }
+ if !args.initSuperUser {
+ t.Errorf("%q initSuperUser = false, want true", form)
+ }
+ }
+ if args, err := parseArgsFrom([]string{"ragflow_server", "--admin", "--init-superuser=false"}); err != nil {
+ t.Fatalf("--init-superuser=false error = %v", err)
+ } else if args.initSuperUser {
+ t.Error("--init-superuser=false initSuperUser = true, want false")
+ }
+ // Non-boolean values are rejected, matching standard flag semantics.
+ for _, form := range []string{"--profile=maybe", "--init-superuser=1.5"} {
+ if _, err := parseArgsFrom([]string{"ragflow_server", "--api", form}); err == nil {
+ t.Errorf("parseArgsFrom(%q) error = nil, want rejection", form)
+ }
+ }
+}
+
+// TestParseArgsModeFlags covers every mode flag in both dash forms and the
+// last-one-wins rule across dash forms.
+func TestParseArgsModeFlags(t *testing.T) {
+ for _, mode := range []string{"admin", "api", "ingestor", "syncer", "deepdoc", "migrate"} {
+ for _, form := range []string{"--" + mode, "-" + mode} {
+ args, err := parseArgsFrom([]string{"ragflow_server", form})
+ if err != nil {
+ t.Fatalf("parseArgsFrom(%q) error = %v", form, err)
+ }
+ if args.mode == nil || *args.mode != mode {
+ t.Errorf("parseArgsFrom(%q) mode = %v, want %s", form, args.mode, mode)
+ }
+ }
+ }
+
+ lastWins := []struct {
+ argv []string
+ want string
+ }{
+ {[]string{"--api", "--admin"}, "admin"},
+ {[]string{"--admin", "--api"}, "api"},
+ {[]string{"-api", "-admin"}, "admin"},
+ {[]string{"--api", "-migrate"}, "migrate"},
+ {[]string{"--api=false", "--admin"}, "admin"},
+ {[]string{"--api", "--migrate=false", "--syncer"}, "syncer"},
+ }
+ for _, c := range lastWins {
+ args, err := parseArgsFrom(append([]string{"ragflow_server"}, c.argv...))
+ if err != nil {
+ t.Fatalf("parseArgsFrom(%v) error = %v", c.argv, err)
+ }
+ if args.mode == nil || *args.mode != c.want {
+ t.Errorf("parseArgsFrom(%v) mode = %v, want %s", c.argv, args.mode, c.want)
+ }
+ }
+
+ // "=false" selects nothing; a lone false mode is not a mode at all.
+ args, err := parseArgsFrom([]string{"ragflow_server", "--api=false"})
+ if err != nil {
+ t.Fatalf("--api=false error = %v", err)
+ }
+ if args.mode != nil {
+ t.Errorf("--api=false mode = %v, want nil", args.mode)
+ }
+ // Non-boolean mode values are rejected.
+ for _, form := range []string{"--api=maybe", "-migrate=1.5"} {
+ if _, err := parseArgsFrom([]string{"ragflow_server", form}); err == nil {
+ t.Errorf("parseArgsFrom(%q) error = nil, want rejection", form)
+ }
+ }
+}
+
+// TestParseArgsDoubleDashTerminator covers the standard "--" terminator: it
+// ends flag parsing, and anything after it is positional (rejected here).
+func TestParseArgsDoubleDashTerminator(t *testing.T) {
+ args, err := parseArgsFrom([]string{"ragflow_server", "--api", "--"})
+ if err != nil {
+ t.Fatalf("--api -- error = %v", err)
+ }
+ if args.mode == nil || *args.mode != "api" {
+ t.Errorf("--api -- mode = %v, want api", args.mode)
+ }
+
+ args, err = parseArgsFrom([]string{"ragflow_server", "--"})
+ if err != nil {
+ t.Fatalf("bare -- error = %v", err)
+ }
+ if args.mode != nil {
+ t.Errorf("bare -- mode = %v, want nil", args.mode)
+ }
+
+ for _, argv := range [][]string{
+ {"--api", "--", "--port", "80"},
+ {"--api", "--", "extra"},
+ {"--", "--api"},
+ } {
+ if _, err := parseArgsFrom(append([]string{"ragflow_server"}, argv...)); err == nil {
+ t.Errorf("parseArgsFrom(%v) error = nil, want rejection", argv)
+ }
+ }
+}
+
+// TestParseArgsPositionalRejected: the flag package silently stops at the
+// first positional argument, which would hide a mistyped mode. This binary
+// has no positional arguments, so they must be rejected.
+func TestParseArgsPositionalRejected(t *testing.T) {
+ for _, argv := range [][]string{
+ {"apii"},
+ {"--api", "leftover"},
+ {"--api", "42"},
+ {"--migrate", "--config", "cfg.yaml", "trailing"},
+ } {
+ if _, err := parseArgsFrom(append([]string{"ragflow_server"}, argv...)); err == nil {
+ t.Errorf("parseArgsFrom(%v) error = nil, want rejection", argv)
+ }
+ }
+}
+
+// TestParseArgsUnknownFlagRejected covers unknown long/short flags in every
+// spelling, including the equals form and the degenerate "-" and "--=x".
+func TestParseArgsUnknownFlagRejected(t *testing.T) {
+ for _, argv := range [][]string{
+ {"--bogus"},
+ {"--bogus=value"},
+ {"-bogus"},
+ {"-bogus=value"},
+ {"-x"},
+ {"-"},
+ {"--=value"},
+ {"--api", "--debug"},
+ {"--api", "--enable-mcpserver"},
+ {"--api", "--mcp-port=9382"},
+ } {
+ if _, err := parseArgsFrom(append([]string{"ragflow_server"}, argv...)); err == nil {
+ t.Errorf("parseArgsFrom(%v) error = nil, want rejection", argv)
+ }
+ }
+}
+
+// TestParseArgsValueEdgeCases covers adversarial values around the "=" split
+// and the space form.
+func TestParseArgsValueEdgeCases(t *testing.T) {
+ // A value containing '=' keeps everything after the first '='.
+ args, err := parseArgsFrom([]string{"ragflow_server", "--name=foo=bar"})
+ if err != nil {
+ t.Fatalf("--name=foo=bar error = %v", err)
+ }
+ if args.name == nil || *args.name != "foo=bar" {
+ t.Errorf("--name=foo=bar name = %v, want foo=bar", args.name)
+ }
+
+ // In the space form the next argument is consumed literally even when it
+ // looks like a flag, and must not be re-parsed as a mode.
+ args, err = parseArgsFrom([]string{"ragflow_server", "--name", "--api"})
+ if err != nil {
+ t.Fatalf("--name --api error = %v", err)
+ }
+ if args.name == nil || *args.name != "--api" {
+ t.Errorf("--name --api name = %v, want --api", args.name)
+ }
+ if args.mode != nil {
+ t.Errorf("--name --api mode = %v, want nil", args.mode)
+ }
+
+ // An explicitly empty string value is a valid (if odd) string value.
+ args, err = parseArgsFrom([]string{"ragflow_server", "--api", "--name="})
+ if err != nil {
+ t.Fatalf("--name= error = %v", err)
+ }
+ if args.name == nil || *args.name != "" {
+ t.Errorf("--name= name = %v, want empty string", args.name)
+ }
+ args, err = parseArgsFrom([]string{"ragflow_server", "--api", "--config="})
+ if err != nil {
+ t.Fatalf("--config= error = %v", err)
+ }
+ if args.configPath == nil || *args.configPath != "" {
+ t.Errorf("--config= configPath = %v, want empty string", args.configPath)
+ }
+
+ // Empty values still fail validation for constrained flags.
+ for _, argv := range [][]string{{"--api", "--log-level="}, {"--api", "--port="}, {"--api", "--deepdoc-inference-cpu-cores="}} {
+ if _, err := parseArgsFrom(append([]string{"ragflow_server"}, argv...)); err == nil {
+ t.Errorf("parseArgsFrom(%v) error = nil, want rejection", argv)
+ }
+ }
+}
+
+// TestParseArgsMissingValue: every value-taking flag at the end of argv must
+// be reported as needing a value, in both dash forms.
+func TestParseArgsMissingValue(t *testing.T) {
+ valueFlags := []string{
+ "--log-level", "--config", "--name", "--port", "--admin-host",
+ "--deepdoc-inference-concurrency", "--ingestor-max-concurrent-workers",
+ "--ingestor-page-concurrency", "--deepdoc-inference-cpu-cores",
+ }
+ for _, flag := range valueFlags {
+ for _, spelling := range []string{flag, "-" + strings.TrimPrefix(flag, "-")} {
+ argv := append([]string{"ragflow_server", "--api"}, spelling)
+ if _, err := parseArgsFrom(argv); err == nil {
+ t.Errorf("parseArgsFrom(%v) error = nil, want rejection", argv)
+ }
+ }
+ }
+ for _, short := range []string{"-f", "-p"} {
+ argv := append([]string{"ragflow_server", "--api"}, short)
+ if _, err := parseArgsFrom(argv); err == nil {
+ t.Errorf("parseArgsFrom(%v) error = nil, want rejection", argv)
+ }
+ }
+}
+
+// TestParseArgsNumericValidation covers boundary and malformed inputs for the
+// integer flags, preserving the pre-migration validation rules.
+func TestParseArgsNumericValidation(t *testing.T) {
+ positiveInvalid := []string{"0", "-1", "abc", "1.5"}
+ for _, flag := range []string{"--deepdoc-inference-concurrency", "--ingestor-max-concurrent-workers", "--ingestor-page-concurrency"} {
+ for _, v := range positiveInvalid {
+ if _, err := parseArgsFrom([]string{"ragflow_server", "--api", flag + "=" + v}); err == nil {
+ t.Errorf("%s=%s error = nil, want rejection", flag, v)
+ }
+ }
+ }
+ cpuInvalid := []string{"-1", "abc", "1.5"}
+ for _, v := range cpuInvalid {
+ if _, err := parseArgsFrom([]string{"ragflow_server", "--api", "--deepdoc-inference-cpu-cores=" + v}); err == nil {
+ t.Errorf("--deepdoc-inference-cpu-cores=%s error = nil, want rejection", v)
+ }
+ }
+ // cpu-cores=0 means "all cores" and must be accepted.
+ args, err := parseArgsFrom([]string{"ragflow_server", "--api", "--deepdoc-inference-cpu-cores=0"})
+ if err != nil {
+ t.Fatalf("--deepdoc-inference-cpu-cores=0 error = %v", err)
+ }
+ if args.deepdocInferenceCPUCores == nil || *args.deepdocInferenceCPUCores != 0 {
+ t.Errorf("--deepdoc-inference-cpu-cores=0 = %v, want 0 (all cores)", args.deepdocInferenceCPUCores)
+ }
+
+ for _, port := range []string{"0", "70000", "-1", "abc"} {
+ if _, err := parseArgsFrom([]string{"ragflow_server", "--api", "--port=" + port}); err == nil {
+ t.Errorf("--port=%s error = nil, want rejection", port)
+ }
+ }
+ for _, port := range []string{"1", "80", "65535"} {
+ if _, err := parseArgsFrom([]string{"ragflow_server", "--api", "--port=" + port}); err != nil {
+ t.Errorf("--port=%s error = %v, want nil", port, err)
+ }
+ }
+}
+
+// TestParseArgsAdminHost covers the ip:port split and its failure modes,
+// preserving the pre-migration behavior (including IPv6 rejection, which the
+// SplitN(":", 2) contract implies).
+func TestParseArgsAdminHost(t *testing.T) {
+ args, err := parseArgsFrom([]string{"ragflow_server", "--ingestor", "--admin-host=127.0.0.1:8000"})
+ if err != nil {
+ t.Fatalf("--admin-host=127.0.0.1:8000 error = %v", err)
+ }
+ if args.adminHost == nil || *args.adminHost != "127.0.0.1" {
+ t.Errorf("adminHost = %v, want 127.0.0.1", args.adminHost)
+ }
+ if args.adminPort == nil || *args.adminPort != 8000 {
+ t.Errorf("adminPort = %v, want 8000", args.adminPort)
+ }
+
+ for _, v := range []string{"127.0.0.1", ":8000", "127.0.0.1:", "127.0.0.1:abc", "::1:80", ""} {
+ if _, err := parseArgsFrom([]string{"ragflow_server", "--ingestor", "--admin-host=" + v}); err == nil {
+ t.Errorf("--admin-host=%q error = nil, want rejection", v)
+ }
+ }
+}
+
+// TestParseArgsPresenceSemantics guards the "unspecified vs explicit zero"
+// contract: only flags present on the command line populate serverArgs.
+func TestParseArgsPresenceSemantics(t *testing.T) {
+ args, err := parseArgsFrom([]string{"ragflow_server", "--api"})
+ if err != nil {
+ t.Fatalf("parseArgsFrom error = %v", err)
+ }
+ for name, got := range map[string]bool{
+ "logLevel": args.logLevel != nil,
+ "configPath": args.configPath != nil,
+ "port": args.port != nil,
+ "adminHost": args.adminHost != nil,
+ "name": args.name != nil,
+ "deepdocInferenceConcurrency": args.deepdocInferenceConcurrency != nil,
+ "ingestorMaxConcurrentWorkers": args.ingestorMaxConcurrentWorkers != nil,
+ "ingestorPageConcurrency": args.ingestorPageConcurrency != nil,
+ "deepdocInferenceCPUCores": args.deepdocInferenceCPUCores != nil,
+ } {
+ if got {
+ t.Errorf("%s set with no flag on the command line", name)
+ }
+ }
+
+ args, err = parseArgsFrom([]string{"ragflow_server", "--api", "-p", "9380", "-f", "conf.yaml", "--deepdoc-inference-cpu-cores", "0"})
+ if err != nil {
+ t.Fatalf("parseArgsFrom error = %v", err)
+ }
+ if args.port == nil || *args.port != 9380 {
+ t.Errorf("port = %v, want 9380", args.port)
+ }
+ if args.configPath == nil || *args.configPath != "conf.yaml" {
+ t.Errorf("configPath = %v, want conf.yaml", args.configPath)
+ }
+ if args.deepdocInferenceCPUCores == nil || *args.deepdocInferenceCPUCores != 0 {
+ t.Errorf("deepdocInferenceCPUCores = %v, want explicit 0", args.deepdocInferenceCPUCores)
+ }
+}
+
+// TestParseArgsHelpVersion covers both dash forms of the help and version
+// flags, including that they combine with a mode (printHelp switches on it).
+func TestParseArgsHelpVersion(t *testing.T) {
+ for _, form := range []string{"-h", "--help", "-help"} {
+ args, err := parseArgsFrom([]string{"ragflow_server", "--api", form})
+ if err != nil {
+ t.Fatalf("parseArgsFrom(%q) error = %v", form, err)
+ }
+ if !args.helpFlag {
+ t.Errorf("%q helpFlag = false, want true", form)
+ }
+ if args.mode == nil || *args.mode != "api" {
+ t.Errorf("%q mode = %v, want api (help must not clear the mode)", form, args.mode)
+ }
+ }
+ for _, form := range []string{"-v", "--version", "-version"} {
+ args, err := parseArgsFrom([]string{"ragflow_server", form})
+ if err != nil {
+ t.Fatalf("parseArgsFrom(%q) error = %v", form, err)
+ }
+ if !args.versionFlag {
+ t.Errorf("%q versionFlag = false, want true", form)
+ }
+ }
+ args, err := parseArgsFrom([]string{"ragflow_server", "--api", "--help=false"})
+ if err != nil {
+ t.Fatalf("--help=false error = %v", err)
+ }
+ if args.helpFlag {
+ t.Error("--help=false helpFlag = true, want false")
+ }
+}
+
+// TestParseArgsDoesNotMutateInput: parseArgsFrom must not rewrite the caller's
+// argv slice (parseArgs passes os.Args straight through).
+func TestParseArgsDoesNotMutateInput(t *testing.T) {
+ in := []string{"ragflow_server", "--api", "--port=80", "--name=a=b"}
+ want := append([]string(nil), in...)
+ if _, err := parseArgsFrom(in); err != nil {
+ t.Fatalf("parseArgsFrom error = %v", err)
+ }
+ if !reflect.DeepEqual(in, want) {
+ t.Errorf("parseArgsFrom mutated its input: in = %v, want %v", in, want)
+ }
+}
+
+// TestParseArgsEmptyArgv: an empty (or program-name-only) argv must parse as
+// "no flags given" rather than panicking on the argv[1:] slice.
+func TestParseArgsEmptyArgv(t *testing.T) {
+ for _, argv := range [][]string{nil, {}, {"ragflow_server"}} {
+ args, err := parseArgsFrom(argv)
+ if err != nil {
+ t.Fatalf("parseArgsFrom(%v) error = %v", argv, err)
+ }
+ if args.mode != nil {
+ t.Errorf("parseArgsFrom(%v) mode = %v, want nil", argv, args.mode)
+ }
+ }
+}
+
+// TestParseArgsDashValues locks in standard flag semantics for values that
+// look like flags or terminators: the space form consumes the next argument
+// literally, so validation — not re-parsing — decides their fate.
+func TestParseArgsDashValues(t *testing.T) {
+ // Negative numbers are taken as the value, then rejected by validation.
+ for _, argv := range [][]string{{"--api", "--port", "-1"}, {"--api", "--port=-1"}} {
+ if _, err := parseArgsFrom(append([]string{"ragflow_server"}, argv...)); err == nil {
+ t.Errorf("parseArgsFrom(%v) error = nil, want rejection", argv)
+ }
+ }
+ // A dash-looking value for a string flag is consumed literally and then
+ // fails the log-level whitelist.
+ if _, err := parseArgsFrom([]string{"ragflow_server", "--api", "--log-level", "-x"}); err == nil {
+ t.Error("--log-level -x error = nil, want rejection")
+ }
+ // "--" as a value is consumed literally, not treated as the terminator.
+ args, err := parseArgsFrom([]string{"ragflow_server", "--name", "--"})
+ if err != nil {
+ t.Fatalf("--name -- error = %v", err)
+ }
+ if args.name == nil || *args.name != "--" {
+ t.Errorf("--name -- name = %v, want --", args.name)
+ }
+}
+
+// TestParseArgsRepeatedFlagLastWins: repeating a flag keeps the last value,
+// matching both the old parser and standard flag behavior.
+func TestParseArgsRepeatedFlagLastWins(t *testing.T) {
+ args, err := parseArgsFrom([]string{"ragflow_server", "--api", "--port", "80", "--port", "90"})
+ if err != nil {
+ t.Fatalf("repeated --port error = %v", err)
+ }
+ if args.port == nil || *args.port != 90 {
+ t.Errorf("port = %v, want 90 (last wins)", args.port)
+ }
+ args, err = parseArgsFrom([]string{"ragflow_server", "--api", "--log-level", "debug", "--log-level", "error"})
+ if err != nil {
+ t.Fatalf("repeated --log-level error = %v", err)
+ }
+ if args.logLevel == nil || *args.logLevel != "error" {
+ t.Errorf("logLevel = %v, want error (last wins)", args.logLevel)
+ }
+ args, err = parseArgsFrom([]string{"ragflow_server", "--api", "-f", "a.yaml", "--config", "b.yaml"})
+ if err != nil {
+ t.Fatalf("repeated -f/--config error = %v", err)
+ }
+ if args.configPath == nil || *args.configPath != "b.yaml" {
+ t.Errorf("configPath = %v, want b.yaml (last wins)", args.configPath)
+ }
+}
+
+// TestParseArgsBoolDoesNotConsumePositional: boolean flags never consume the
+// next argument, so a stray token after them is a positional (rejected).
+func TestParseArgsBoolDoesNotConsumePositional(t *testing.T) {
+ if _, err := parseArgsFrom([]string{"ragflow_server", "--api", "--profile", "--init-superuser", "stray"}); err == nil {
+ t.Error("stray token after boolean flags error = nil, want rejection")
+ }
+ // Both booleans still parse when no stray token follows.
+ args, err := parseArgsFrom([]string{"ragflow_server", "--api", "--profile", "--init-superuser"})
+ if err != nil {
+ t.Fatalf("error = %v", err)
+ }
+ if !args.enablePProf || !args.initSuperUser {
+ t.Errorf("enablePProf = %v, initSuperUser = %v, want both true", args.enablePProf, args.initSuperUser)
+ }
+}
+
+// TestParseArgsDoesNotMutateOsArgs is the os.Args-level version of the same
+// guard, exercised through the parseArgs adapter.
+func TestParseArgsDoesNotMutateOsArgs(t *testing.T) {
+ orig := os.Args
+ defer func() { os.Args = orig }()
+ os.Args = []string{"ragflow_server", "--api", "--port=80"}
+ snapshot := append([]string(nil), os.Args...)
+ if _, err := parseArgs(); err != nil {
+ t.Fatalf("parseArgs error = %v", err)
+ }
+ if !reflect.DeepEqual(os.Args, snapshot) {
+ t.Errorf("parseArgs mutated os.Args: got %v, want %v", os.Args, snapshot)
+ }
+}
+
+// TestParseArgsModeBoolSynonyms locks in the fact that mode flags route
+// through strconv.ParseBool (via modeFlag.IsBoolFlag): the standard boolean
+// truthy spellings 1/t/T select the mode, and the falsy spellings 0/f/F do
+// not. This is stdlib flag behavior, not something the parser special-cases.
+func TestParseArgsModeBoolSynonyms(t *testing.T) {
+ truthy := []struct {
+ argv []string
+ want string
+ }{
+ {[]string{"--api=1"}, "api"},
+ {[]string{"-api=1"}, "api"},
+ {[]string{"--api=t"}, "api"},
+ {[]string{"--api=T"}, "api"},
+ {[]string{"--api=true"}, "api"},
+ {[]string{"--migrate=1"}, "migrate"},
+ }
+ for _, c := range truthy {
+ args, err := parseArgsFrom(append([]string{"ragflow_server"}, c.argv...))
+ if err != nil {
+ t.Fatalf("parseArgsFrom(%v) error = %v", c.argv, err)
+ }
+ if args.mode == nil || *args.mode != c.want {
+ t.Errorf("parseArgsFrom(%v) mode = %v, want %s", c.argv, args.mode, c.want)
+ }
+ }
+
+ falsy := []string{"--api=0", "-api=0", "--api=f", "--api=F", "--api=false"}
+ for _, argv := range falsy {
+ args, err := parseArgsFrom([]string{"ragflow_server", argv})
+ if err != nil {
+ t.Fatalf("parseArgsFrom(%q) error = %v", argv, err)
+ }
+ if args.mode != nil {
+ t.Errorf("parseArgsFrom(%q) mode = %v, want nil (falsy boolean selects no mode)", argv, args.mode)
+ }
+ }
+}
diff --git a/cmd/ragflow_server.go b/cmd/ragflow_server.go
index eadf6130f9..4571c3d425 100644
--- a/cmd/ragflow_server.go
+++ b/cmd/ragflow_server.go
@@ -19,7 +19,9 @@ package main
import (
"context"
"errors"
+ "flag"
"fmt"
+ "io"
"net"
"net/http"
_ "net/http/pprof"
@@ -102,204 +104,173 @@ type serverArgs struct {
deepdocInferenceCPUCores *int
}
-func parseArgs() (*serverArgs, error) {
+// parseArgsFrom parses argv (argv[0] is the program name, mirroring os.Args)
+// into a serverArgs using the standard library flag package. The accepted
+// syntax is exactly the standard one: every flag works as "-flag value",
+// "-flag=value", "--flag value" and "--flag=value"; boolean flags also accept
+// "=true"/"=false". Flags absent from argv leave their serverArgs field nil,
+// which callers use to distinguish "unspecified" from an explicit zero value.
+func parseArgsFrom(argv []string) (*serverArgs, error) {
+ fs := flag.NewFlagSet("ragflow_server", flag.ContinueOnError)
+ // Suppress the standard usage/error dump: main prints its own one-line
+ // error and printHelp owns the usage text.
+ fs.SetOutput(io.Discard)
+ fs.Usage = func() {}
+
args := &serverArgs{}
- // Mode flags share one variable, so the last one passed wins.
- var serverMode string
- var configPath string
- for i := 1; i < len(os.Args); i++ {
- arg := os.Args[i]
- if key, value, ok := strings.Cut(arg, "="); ok {
- switch key {
- case "--log-level":
- if err := validateLogLevel(value); err != nil {
- return nil, err
- }
- args.logLevel = &value
- continue
- case "--deepdoc-inference-concurrency":
- n, convErr := strconv.Atoi(value)
- if convErr != nil {
- return nil, fmt.Errorf("invalid --deepdoc-inference-concurrency: %w", convErr)
- }
- if n <= 0 {
- return nil, fmt.Errorf("invalid --deepdoc-inference-concurrency %d: must be positive", n)
- }
- args.deepdocInferenceConcurrency = &n
- continue
- case "--ingestor-max-concurrent-workers":
- n, convErr := strconv.Atoi(value)
- if convErr != nil {
- return nil, fmt.Errorf("invalid --ingestor-max-concurrent-workers: %w", convErr)
- }
- if n <= 0 {
- return nil, fmt.Errorf("invalid --ingestor-max-concurrent-workers %d: must be positive", n)
- }
- args.ingestorMaxConcurrentWorkers = &n
- continue
- case "--ingestor-page-concurrency":
- n, convErr := strconv.Atoi(value)
- if convErr != nil {
- return nil, fmt.Errorf("invalid --ingestor-page-concurrency: %w", convErr)
- }
- if n <= 0 {
- return nil, fmt.Errorf("invalid --ingestor-page-concurrency %d: must be positive", n)
- }
- args.ingestorPageConcurrency = &n
- continue
- case "--deepdoc-inference-cpu-cores":
- n, convErr := strconv.Atoi(value)
- if convErr != nil {
- return nil, fmt.Errorf("invalid --deepdoc-inference-cpu-cores: %w", convErr)
- }
- if n < 0 {
- return nil, fmt.Errorf("invalid --deepdoc-inference-cpu-cores %d: must be >= 0 (0 means all cores)", n)
- }
- args.deepdocInferenceCPUCores = &n
- continue
- }
- }
+ var (
+ logLevel string
+ configPath string
+ adminHost string
+ name string
+ port int
+ deepdocConcurrency int
+ ingestorWorkers int
+ pageConcurrency int
+ cpuCores int
+ initSuperUser bool
+ enablePProf bool
+ helpFlag bool
+ versionFlag bool
+ modes []string
+ )
- switch arg {
- case "--admin":
- serverMode = "admin"
- args.mode = &serverMode
- case "--ingestor":
- serverMode = "ingestor"
- args.mode = &serverMode
- case "--api":
- serverMode = "api"
- args.mode = &serverMode
- case "--syncer":
- serverMode = "syncer"
- args.mode = &serverMode
- case "--deepdoc":
- serverMode = "deepdoc"
- args.mode = &serverMode
- case "--migrate":
- serverMode = "migrate"
- args.mode = &serverMode
- case "-h", "--help":
- args.helpFlag = true
- case "-v", "--version":
- args.versionFlag = true
- case "--log-level":
- if i+1 >= len(os.Args) {
- return nil, errors.New("--log-level requires a value")
- }
- i++
- level := os.Args[i]
- if err := validateLogLevel(level); err != nil {
- return nil, err
- }
- args.logLevel = &level
- case "-f", "--config":
- if i+1 >= len(os.Args) {
- return nil, fmt.Errorf("%s requires a value", arg)
- }
- i++
- configPath = os.Args[i]
+ fs.StringVar(&logLevel, "log-level", "", "")
+ fs.StringVar(&configPath, "config", "", "")
+ fs.StringVar(&configPath, "f", "", "")
+ fs.StringVar(&adminHost, "admin-host", "", "")
+ fs.StringVar(&name, "name", "", "")
+ fs.IntVar(&port, "port", 0, "")
+ fs.IntVar(&port, "p", 0, "")
+ fs.IntVar(&deepdocConcurrency, "deepdoc-inference-concurrency", 0, "")
+ fs.IntVar(&ingestorWorkers, "ingestor-max-concurrent-workers", 0, "")
+ fs.IntVar(&pageConcurrency, "ingestor-page-concurrency", 0, "")
+ fs.IntVar(&cpuCores, "deepdoc-inference-cpu-cores", 0, "")
+ fs.BoolVar(&initSuperUser, "init-superuser", false, "")
+ fs.BoolVar(&enablePProf, "profile", false, "")
+ fs.BoolVar(&helpFlag, "help", false, "")
+ fs.BoolVar(&helpFlag, "h", false, "")
+ fs.BoolVar(&versionFlag, "version", false, "")
+ fs.BoolVar(&versionFlag, "v", false, "")
+ for _, mode := range []string{"admin", "api", "ingestor", "syncer", "deepdoc", "migrate"} {
+ fs.Var(modeFlag{name: mode, seen: &modes}, mode, "")
+ }
+
+ if len(argv) > 0 {
+ if err := fs.Parse(argv[1:]); err != nil {
+ return nil, err
+ }
+ }
+ // The flag package silently stops at the first positional argument, which
+ // would hide a mistyped mode (e.g. "ragflow_server apii" starting with no
+ // mode). This binary has no positional arguments, so reject them.
+ if fs.NArg() > 0 {
+ return nil, fmt.Errorf("unexpected argument: %s", fs.Arg(0))
+ }
+
+ // Visit visits exactly the flags present on the command line, which
+ // preserves the "unspecified" (nil) vs explicit-zero distinction.
+ seen := map[string]bool{}
+ fs.Visit(func(f *flag.Flag) {
+ seen[f.Name] = true
+ switch f.Name {
+ case "log-level":
+ args.logLevel = &logLevel
+ case "config", "f":
args.configPath = &configPath
- case "--init-superuser":
- args.initSuperUser = true
- case "-p", "--port":
- if i+1 >= len(os.Args) {
- return nil, errors.New("--port requires a value")
- }
- i++
- port, convErr := strconv.Atoi(os.Args[i])
- if convErr != nil {
- return nil, fmt.Errorf("invalid port: %w", convErr)
- }
+ case "name":
+ args.name = &name
+ case "port", "p":
args.port = &port
- if port <= 0 || port > 65535 {
- return nil, fmt.Errorf("invalid port: %d", port)
- }
- case "--admin-host":
- if i+1 >= len(os.Args) {
- return nil, errors.New("--admin-host requires a value")
- }
- i++
- parts := strings.SplitN(os.Args[i], ":", 2)
- if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
- return nil, errors.New("--admin-host must be in the form 'ip:port'")
- }
- ip, portStr := parts[0], parts[1]
- port, convErr := strconv.Atoi(portStr)
- if convErr != nil {
- return nil, fmt.Errorf("failed to parse admin port: %w", convErr)
- }
- args.adminHost = &ip
- args.adminPort = &port
- case "--name":
- if i+1 >= len(os.Args) {
- return nil, errors.New("--name requires a value")
- }
- i++
- args.name = &os.Args[i]
- case "--profile":
- args.enablePProf = true
- case "--deepdoc-inference-concurrency":
- if i+1 >= len(os.Args) {
- return nil, errors.New("--deepdoc-inference-concurrency requires a value")
- }
- i++
- n, convErr := strconv.Atoi(os.Args[i])
- if convErr != nil {
- return nil, fmt.Errorf("invalid --deepdoc-inference-concurrency: %w", convErr)
- }
- if n <= 0 {
- return nil, fmt.Errorf("invalid --deepdoc-inference-concurrency %d: must be positive", n)
- }
- args.deepdocInferenceConcurrency = &n
- case "--ingestor-max-concurrent-workers":
- if i+1 >= len(os.Args) {
- return nil, errors.New("--ingestor-max-concurrent-workers requires a value")
- }
- i++
- n, convErr := strconv.Atoi(os.Args[i])
- if convErr != nil {
- return nil, fmt.Errorf("invalid --ingestor-max-concurrent-workers: %w", convErr)
- }
- if n <= 0 {
- return nil, fmt.Errorf("invalid --ingestor-max-concurrent-workers %d: must be positive", n)
- }
- args.ingestorMaxConcurrentWorkers = &n
- case "--ingestor-page-concurrency":
- if i+1 >= len(os.Args) {
- return nil, errors.New("--ingestor-page-concurrency requires a value")
- }
- i++
- n, convErr := strconv.Atoi(os.Args[i])
- if convErr != nil {
- return nil, fmt.Errorf("invalid --ingestor-page-concurrency: %w", convErr)
- }
- if n <= 0 {
- return nil, fmt.Errorf("invalid --ingestor-page-concurrency %d: must be positive", n)
- }
- args.ingestorPageConcurrency = &n
- case "--deepdoc-inference-cpu-cores":
- if i+1 >= len(os.Args) {
- return nil, errors.New("--deepdoc-inference-cpu-cores requires a value")
- }
- i++
- n, convErr := strconv.Atoi(os.Args[i])
- if convErr != nil {
- return nil, fmt.Errorf("invalid --deepdoc-inference-cpu-cores: %w", convErr)
- }
- if n < 0 {
- return nil, fmt.Errorf("invalid --deepdoc-inference-cpu-cores %d: must be >= 0 (0 means all cores)", n)
- }
- args.deepdocInferenceCPUCores = &n
- default:
- return nil, fmt.Errorf("unknown parameter: %s", arg)
+ case "deepdoc-inference-concurrency":
+ args.deepdocInferenceConcurrency = &deepdocConcurrency
+ case "ingestor-max-concurrent-workers":
+ args.ingestorMaxConcurrentWorkers = &ingestorWorkers
+ case "ingestor-page-concurrency":
+ args.ingestorPageConcurrency = &pageConcurrency
+ case "deepdoc-inference-cpu-cores":
+ args.deepdocInferenceCPUCores = &cpuCores
+ case "init-superuser":
+ args.initSuperUser = initSuperUser
+ case "profile":
+ args.enablePProf = enablePProf
+ case "help", "h":
+ args.helpFlag = helpFlag
+ case "version", "v":
+ args.versionFlag = versionFlag
+ }
+ })
+
+ if seen["admin-host"] {
+ parts := strings.SplitN(adminHost, ":", 2)
+ if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
+ return nil, errors.New("--admin-host must be in the form 'ip:port'")
+ }
+ adminPort, convErr := strconv.Atoi(parts[1])
+ if convErr != nil {
+ return nil, fmt.Errorf("failed to parse admin port: %w", convErr)
}
+ args.adminHost = &parts[0]
+ args.adminPort = &adminPort
+ }
+
+ // Mode flags share one slot; the last one on the command line wins.
+ if len(modes) > 0 {
+ mode := modes[len(modes)-1]
+ args.mode = &mode
+ }
+
+ if args.logLevel != nil {
+ if err := validateLogLevel(*args.logLevel); err != nil {
+ return nil, err
+ }
+ }
+ if args.port != nil && (*args.port <= 0 || *args.port > 65535) {
+ return nil, fmt.Errorf("invalid port: %d", *args.port)
+ }
+ if args.deepdocInferenceConcurrency != nil && *args.deepdocInferenceConcurrency <= 0 {
+ return nil, fmt.Errorf("invalid --deepdoc-inference-concurrency %d: must be positive", *args.deepdocInferenceConcurrency)
+ }
+ if args.ingestorMaxConcurrentWorkers != nil && *args.ingestorMaxConcurrentWorkers <= 0 {
+ return nil, fmt.Errorf("invalid --ingestor-max-concurrent-workers %d: must be positive", *args.ingestorMaxConcurrentWorkers)
+ }
+ if args.ingestorPageConcurrency != nil && *args.ingestorPageConcurrency <= 0 {
+ return nil, fmt.Errorf("invalid --ingestor-page-concurrency %d: must be positive", *args.ingestorPageConcurrency)
+ }
+ if args.deepdocInferenceCPUCores != nil && *args.deepdocInferenceCPUCores < 0 {
+ return nil, fmt.Errorf("invalid --deepdoc-inference-cpu-cores %d: must be >= 0 (0 means all cores)", *args.deepdocInferenceCPUCores)
}
return args, nil
}
+func parseArgs() (*serverArgs, error) {
+ return parseArgsFrom(os.Args)
+}
+
+// modeFlag is a boolean flag that records which mode flag was set and in what
+// order, so the last mode on the command line wins (matching the previous
+// hand-rolled parser). "=false" selects nothing.
+type modeFlag struct {
+ name string
+ seen *[]string
+}
+
+func (m modeFlag) String() string { return "" }
+func (m modeFlag) IsBoolFlag() bool { return true }
+
+func (m modeFlag) Set(value string) error {
+ on, err := strconv.ParseBool(value)
+ if err != nil {
+ return err
+ }
+ if on {
+ *m.seen = append(*m.seen, m.name)
+ }
+ return nil
+}
+
func validateLogLevel(level string) error {
switch level {
case "debug", "info", "warn", "error":
@@ -458,7 +429,7 @@ func printHelp(args *serverArgs) {
fmt.Fprintf(os.Stderr, "RAGFlow DeepDoc Inference Service - DeepDoc model inference service\n\n")
fmt.Fprintf(os.Stderr, "Options:\n")
fmt.Fprintf(os.Stderr, " -f --config string\tPath to config file\n")
- fmt.Fprintf(os.Stderr, " --name string\t\t\tSync service server name (default: \"default_syncer\")\n")
+ fmt.Fprintf(os.Stderr, " --name string\t\t\tDeepDoc server name (default: \"deepdoc_server\")\n")
fmt.Fprintf(os.Stderr, " --admin-host string\tAdmin server host:port (overrides config file)\n")
fmt.Fprintf(os.Stderr, " -v, --version \t\tPrint version information and exit\n")
fmt.Fprintf(os.Stderr, " --profile \t\tEnable pprof server\n")
diff --git a/cmd/ragflow_server_test.go b/cmd/ragflow_server_test.go
index 072087ec50..6ba870d4eb 100644
--- a/cmd/ragflow_server_test.go
+++ b/cmd/ragflow_server_test.go
@@ -84,7 +84,11 @@ func TestSelectedLogLevelPrecedence(t *testing.T) {
t.Errorf("--log-level log level = %q, want error", got)
}
if _, err = parseArgsForTest(t, "--api", "--debug"); err == nil {
- t.Error("parseArgs(--debug) error = nil, want unknown parameter error")
+ t.Error("parseArgs(--api --debug) error = nil, want rejection")
+ } else if !strings.Contains(err.Error(), "flag provided but not defined") {
+ // The stdlib flag package owns unknown-flag errors now; the old
+ // "unknown parameter" string no longer applies.
+ t.Errorf("parseArgs(--api --debug) error = %q, want \"flag provided but not defined\"", err)
}
}
@@ -144,3 +148,35 @@ func TestMainMigrateReachesConfiguration(t *testing.T) {
t.Fatalf("migration did not reach config: %v\n%s", err, output)
}
}
+
+// TestPrintHelpDeepdoc guards the DeepDoc help text. It must describe the
+// DeepDoc server (not the Sync service) and show the real --name default
+// (deepdoc_server). The hand-rolled help text previously copied the syncer
+// case verbatim, printing "Sync service server name (default: "default_syncer")"
+// under --deepdoc.
+func TestPrintHelpDeepdoc(t *testing.T) {
+ if os.Getenv("RAGFLOW_TEST_DEEPDOC_HELP") == "1" {
+ os.Args = append([]string{os.Args[0]}, os.Args[len(os.Args)-2:]...)
+ main()
+ return
+ }
+ ctx, cancel := context.WithTimeout(t.Context(), 15*time.Second)
+ defer cancel()
+ dir := t.TempDir()
+ cmd := exec.CommandContext(ctx, os.Args[0], "-test.run=^TestPrintHelpDeepdoc$", "--", "--deepdoc", "--help")
+ cmd.Dir = dir
+ cmd.Env = append(os.Environ(), "RAGFLOW_TEST_DEEPDOC_HELP=1")
+ output, err := cmd.CombinedOutput()
+ if err == nil {
+ t.Fatalf("deepdoc --help did not exit non-zero: %s", output)
+ }
+ if !strings.Contains(string(output), "DeepDoc server name") {
+ t.Errorf("deepdoc help missing the DeepDoc server name line:\n%s", output)
+ }
+ if !strings.Contains(string(output), `default: "deepdoc_server"`) {
+ t.Errorf("deepdoc help missing the correct --name default (want deepdoc_server):\n%s", output)
+ }
+ if strings.Contains(string(output), "Sync service server name") {
+ t.Errorf("deepdoc help still shows the syncer's text:\n%s", output)
+ }
+}