RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
refactor(cmd): extract server runners into internal/server/* packages (#20883)
xugangqiangfa1494d70356
diff --git a/cmd/args_flag_test.go b/cmd/args_flag_test.goindex 043e74a2d6..9c83b80f60 100644--- a/cmd/args_flag_test.go+++ b/cmd/args_flag_test.go@@ -125,7 +125,7 @@ func TestParseArgsBoolFlagForms(t *testing.T) {if err != nil {t.Fatalf("parseArgsFrom(%q) error = %v", form, err)}- if !args.enablePProf {+ if !args.EnablePProf {t.Errorf("%q enablePProf = false, want true", form)}}@@ -134,7 +134,7 @@ func TestParseArgsBoolFlagForms(t *testing.T) {if err != nil {t.Fatalf("parseArgsFrom(%q) error = %v", form, err)}- if args.enablePProf {+ if args.EnablePProf {t.Errorf("%q enablePProf = true, want false", form)}}@@ -143,13 +143,13 @@ func TestParseArgsBoolFlagForms(t *testing.T) {if err != nil {t.Fatalf("parseArgsFrom(%q) error = %v", form, err)}- if !args.initSuperUser {+ 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 {+ } else if args.InitSuperUser {t.Error("--init-superuser=false initSuperUser = true, want false")}// Non-boolean values are rejected, matching standard flag semantics.@@ -169,8 +169,8 @@ func TestParseArgsModeFlags(t *testing.T) {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)+ if args.Mode == nil || *args.Mode != mode {+ t.Errorf("parseArgsFrom(%q) mode = %v, want %s", form, args.Mode, mode)}}}@@ -191,8 +191,8 @@ func TestParseArgsModeFlags(t *testing.T) {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)+ if args.Mode == nil || *args.Mode != c.want {+ t.Errorf("parseArgsFrom(%v) mode = %v, want %s", c.argv, args.Mode, c.want)}}@@ -201,8 +201,8 @@ func TestParseArgsModeFlags(t *testing.T) {if err != nil {t.Fatalf("--api=false error = %v", err)}- if args.mode != nil {- t.Errorf("--api=false mode = %v, want nil", args.mode)+ 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"} {@@ -219,16 +219,16 @@ func TestParseArgsDoubleDashTerminator(t *testing.T) {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)+ 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)+ if args.Mode != nil {+ t.Errorf("bare -- mode = %v, want nil", args.Mode)}for _, argv := range [][]string{@@ -287,8 +287,8 @@ func TestParseArgsValueEdgeCases(t *testing.T) {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)+ 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@@ -297,11 +297,11 @@ func TestParseArgsValueEdgeCases(t *testing.T) {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.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)+ 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.@@ -309,15 +309,15 @@ func TestParseArgsValueEdgeCases(t *testing.T) {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)+ 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)+ if args.ConfigPath == nil || *args.ConfigPath != "" {+ t.Errorf("--config= configPath = %v, want empty string", args.ConfigPath)}// Empty values still fail validation for constrained flags.@@ -374,8 +374,8 @@ func TestParseArgsNumericValidation(t *testing.T) {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)+ 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"} {@@ -398,11 +398,11 @@ func TestParseArgsAdminHost(t *testing.T) {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.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)+ 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", ""} {@@ -413,22 +413,22 @@ func TestParseArgsAdminHost(t *testing.T) {}// TestParseArgsPresenceSemantics guards the "unspecified vs explicit zero"-// contract: only flags present on the command line populate serverArgs.+// contract: only flags present on the command line populate bootstrap.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,+ "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)@@ -439,14 +439,14 @@ func TestParseArgsPresenceSemantics(t *testing.T) {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.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.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)+ if args.DeepdocInferenceCPUCores == nil || *args.DeepdocInferenceCPUCores != 0 {+ t.Errorf("deepdocInferenceCPUCores = %v, want explicit 0", args.DeepdocInferenceCPUCores)}}@@ -458,11 +458,11 @@ func TestParseArgsHelpVersion(t *testing.T) {if err != nil {t.Fatalf("parseArgsFrom(%q) error = %v", form, err)}- if !args.helpFlag {+ 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)+ 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"} {@@ -470,7 +470,7 @@ func TestParseArgsHelpVersion(t *testing.T) {if err != nil {t.Fatalf("parseArgsFrom(%q) error = %v", form, err)}- if !args.versionFlag {+ if !args.VersionFlag {t.Errorf("%q versionFlag = false, want true", form)}}@@ -478,7 +478,7 @@ func TestParseArgsHelpVersion(t *testing.T) {if err != nil {t.Fatalf("--help=false error = %v", err)}- if args.helpFlag {+ if args.HelpFlag {t.Error("--help=false helpFlag = true, want false")}}@@ -504,8 +504,8 @@ func TestParseArgsEmptyArgv(t *testing.T) {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)+ if args.Mode != nil {+ t.Errorf("parseArgsFrom(%v) mode = %v, want nil", argv, args.Mode)}}}@@ -530,8 +530,8 @@ func TestParseArgsDashValues(t *testing.T) {if err != nil {t.Fatalf("--name -- error = %v", err)}- if args.name == nil || *args.name != "--" {- t.Errorf("--name -- name = %v, want --", args.name)+ if args.Name == nil || *args.Name != "--" {+ t.Errorf("--name -- name = %v, want --", args.Name)}}@@ -542,22 +542,22 @@ func TestParseArgsRepeatedFlagLastWins(t *testing.T) {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)+ 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)+ 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)+ if args.ConfigPath == nil || *args.ConfigPath != "b.yaml" {+ t.Errorf("configPath = %v, want b.yaml (last wins)", args.ConfigPath)}}@@ -572,8 +572,8 @@ func TestParseArgsBoolDoesNotConsumePositional(t *testing.T) {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)+ if !args.EnablePProf || !args.InitSuperUser {+ t.Errorf("enablePProf = %v, initSuperUser = %v, want both true", args.EnablePProf, args.InitSuperUser)}}@@ -613,8 +613,8 @@ func TestParseArgsModeBoolSynonyms(t *testing.T) {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)+ if args.Mode == nil || *args.Mode != c.want {+ t.Errorf("parseArgsFrom(%v) mode = %v, want %s", c.argv, args.Mode, c.want)}}@@ -624,8 +624,8 @@ func TestParseArgsModeBoolSynonyms(t *testing.T) {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)+ if args.Mode != nil {+ t.Errorf("parseArgsFrom(%q) mode = %v, want nil (falsy boolean selects no mode)", argv, args.Mode)}}}diff --git a/cmd/deepdoc_server_ee.go b/cmd/deepdoc_server_ee.goindex ee68db3dd1..4542c59a3c 100644--- a/cmd/deepdoc_server_ee.go+++ b/cmd/deepdoc_server_ee.go@@ -18,10 +18,12 @@ package mainimport ("context"+"ragflow/internal/common"+ "ragflow/internal/server/bootstrap")-func runDeepDoc(ctx context.Context, serverName string, args *serverArgs) error {+func runDeepDoc(ctx context.Context, serverName string, args *bootstrap.ServerArgs) error {common.Info("DeepDoc server is not implemented")return nil}diff --git a/cmd/ragflow_server.go b/cmd/ragflow_server.goindex 1c28fe2f46..a3caba239b 100644--- a/cmd/ragflow_server.go+++ b/cmd/ragflow_server.go@@ -22,100 +22,45 @@ import ("flag""fmt""io"- "net""net/http"_ "net/http/pprof""os""os/signal"- "path/filepath"- "ragflow/internal/admin"- "ragflow/internal/agent/audio"- "ragflow/internal/agent/canvas"- "ragflow/internal/agent/retrievalbridge"- "ragflow/internal/agent/runtime"- agenttool "ragflow/internal/agent/tool"- smartagentic "ragflow/internal/agentic_rag"- "ragflow/internal/channels"- "ragflow/internal/deepdoc/native"- "ragflow/internal/deepdoc/parser/pdf"- modelModule "ragflow/internal/entity/models"- "ragflow/internal/handler"- "ragflow/internal/ingestion/knowledge_compile"- ingestion "ragflow/internal/ingestion/service"- "ragflow/internal/router"- "ragflow/internal/server/local"- "ragflow/internal/service"- "ragflow/internal/service/chunk"- "ragflow/internal/service/dataset"- "ragflow/internal/service/document"- "ragflow/internal/service/file"- "ragflow/internal/service/nav"- "ragflow/internal/service/nlp"- "ragflow/internal/service/wikisearch"- "ragflow/internal/storage"- "ragflow/internal/syncer"- "ragflow/internal/tokenizer"- goruntime "runtime""strconv""strings""syscall"- "time"- "github.com/gin-gonic/gin""go.uber.org/zap"- "ragflow/internal/agent/component""ragflow/internal/common""ragflow/internal/dao"- infnative "ragflow/internal/deepdoc/parser/pdf/inference/native_analyzer""ragflow/internal/engine""ragflow/internal/engine/kvrocks"_ "ragflow/internal/ingestion/wire""ragflow/internal/server"- "ragflow/internal/utility"+ "ragflow/internal/server/admin"+ apipkg "ragflow/internal/server/api"+ "ragflow/internal/server/bootstrap"+ deepdocpkg "ragflow/internal/server/deepdoc"+ ingestorpkg "ragflow/internal/server/ingestor"+ syncerpkg "ragflow/internal/server/syncer"+ "ragflow/internal/storage")-type serverArgs struct {- mode *string // admin | api | ingestor | syncer | deepdoc | migrate- helpFlag bool- versionFlag bool- logLevel *string- configPath *string // Used by admin, api; user defined config path- initSuperUser bool // Used by admin;- port *int // Used by admin, api- adminHost *string // Used by api, ingestor, syncer, deepdoc for heartbeat- adminPort *int // Used by api, ingestor, syncer, deepdoc for heartbeat, "ip:port"- name *string // server name- enablePProf bool // enable pprof-- // deepdocInferenceConcurrency, when set, overrides the DeepDoc inference- // concurrency from env/config. nil means "unspecified".- deepdocInferenceConcurrency *int- // ingestorMaxConcurrentWorkers, when set, overrides the ingestor worker- // count (NATS consumer count K) from env/config. nil means "unspecified".- ingestorMaxConcurrentWorkers *int- // ingestorPageConcurrency, when set, overrides the per-document page- // concurrency (N) from env/config. nil means "unspecified".- ingestorPageConcurrency *int- // deepdocInferenceCPUCores, when set, overrides the DeepDoc inference CPU-core- // budget from env/config. nil means "unspecified" (0 means "all cores").- deepdocInferenceCPUCores *int-}-// parseArgsFrom parses argv (argv[0] is the program name, mirroring os.Args)-// into a serverArgs using the standard library flag package. The accepted+// into a bootstrap.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,+// "=true"/"=false". Flags absent from argv leave their bootstrap.ServerArgs field nil,// which callers use to distinguish "unspecified" from an explicit zero value.-func parseArgsFrom(argv []string) (*serverArgs, error) {+func parseArgsFrom(argv []string) (*bootstrap.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{}+ args := &bootstrap.ServerArgs{}var (logLevel string@@ -174,29 +119,29 @@ func parseArgsFrom(argv []string) (*serverArgs, error) {seen[f.Name] = trueswitch f.Name {case "log-level":- args.logLevel = &logLevel+ args.LogLevel = &logLevelcase "config", "f":- args.configPath = &configPath+ args.ConfigPath = &configPathcase "name":- args.name = &name+ args.Name = &namecase "port", "p":- args.port = &port+ args.Port = &portcase "deepdoc-inference-concurrency":- args.deepdocInferenceConcurrency = &deepdocConcurrency+ args.DeepdocInferenceConcurrency = &deepdocConcurrencycase "ingestor-max-concurrent-workers":- args.ingestorMaxConcurrentWorkers = &ingestorWorkers+ args.IngestorMaxConcurrentWorkers = &ingestorWorkerscase "ingestor-page-concurrency":- args.ingestorPageConcurrency = &pageConcurrency+ args.IngestorPageConcurrency = &pageConcurrencycase "deepdoc-inference-cpu-cores":- args.deepdocInferenceCPUCores = &cpuCores+ args.DeepdocInferenceCPUCores = &cpuCorescase "init-superuser":- args.initSuperUser = initSuperUser+ args.InitSuperUser = initSuperUsercase "profile":- args.enablePProf = enablePProf+ args.EnablePProf = enablePProfcase "help", "h":- args.helpFlag = helpFlag+ args.HelpFlag = helpFlagcase "version", "v":- args.versionFlag = versionFlag+ args.VersionFlag = versionFlag}})@@ -209,41 +154,41 @@ func parseArgsFrom(argv []string) (*serverArgs, error) {if convErr != nil {return nil, fmt.Errorf("failed to parse admin port: %w", convErr)}- args.adminHost = &parts[0]- args.adminPort = &adminPort+ 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+ args.Mode = &mode}- if args.logLevel != nil {- if err := validateLogLevel(*args.logLevel); err != nil {+ 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.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.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.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.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)+ 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) {+func parseArgs() (*bootstrap.ServerArgs, error) {return parseArgsFrom(os.Args)}@@ -278,21 +223,9 @@ func validateLogLevel(level string) error {}}-func selectedLogLevel(args *serverArgs, configured string) string {- if args.logLevel != nil {- return *args.logLevel- }-- if configured == "" {- return "info"- }-- return configured-}--func printHelp(args *serverArgs) {+func printHelp(args *bootstrap.ServerArgs) {switch {- case args.mode == nil || *args.mode == "migrate":+ case args.Mode == nil || *args.Mode == "migrate":fmt.Fprintf(os.Stderr, "Usage: %s --api|--admin|--ingestor|--syncer|--deepdoc [OPTIONS]\n", os.Args[0])fmt.Fprintf(os.Stderr, " %s --migrate [OPTIONS]\n\n", os.Args[0])fmt.Fprintf(os.Stderr, "RAGFlow Server - Open-source RAG engine based on deep document understanding\n\n")@@ -322,7 +255,7 @@ func printHelp(args *serverArgs) {fmt.Fprintf(os.Stderr, "Run '%s --ingestor --help' for ingester options.\n", os.Args[0])fmt.Fprintf(os.Stderr, "Run '%s --syncer --help' for syncer options.\n", os.Args[0])fmt.Fprintf(os.Stderr, "Run '%s --deepdoc --help' for DeepDoc server options.\n", os.Args[0])- case *args.mode == "api":+ case *args.Mode == "api":fmt.Fprintf(os.Stderr, "Usage: %s --api [OPTIONS]\n\n", os.Args[0])fmt.Fprintf(os.Stderr, "RAGFlow API Server\n\n")fmt.Fprintf(os.Stderr, "Options:\n")@@ -333,7 +266,7 @@ func printHelp(args *serverArgs) {fmt.Fprintf(os.Stderr, " --profile \t\tEnable pprof server\n")fmt.Fprintf(os.Stderr, " -h, --help \tShow this help message and exit\n")fmt.Fprintln(os.Stderr, "\nMCP settings: service_conf.yaml mcp section or RAGFLOW_MCP_* environment variables.")- case *args.mode == "admin":+ case *args.Mode == "admin":fmt.Fprintf(os.Stderr, "Usage: %s --admin [OPTIONS]\n\n", os.Args[0])fmt.Fprintf(os.Stderr, "RAGFlow Admin Server\n\n")fmt.Fprintf(os.Stderr, "Options:\n")@@ -344,7 +277,7 @@ func printHelp(args *serverArgs) {fmt.Fprintf(os.Stderr, " --log-level string\t\tLog level: debug, info, warn, error (default: warn)\n")fmt.Fprintf(os.Stderr, " --profile \t\t\tEnable pprof server\n")fmt.Fprintf(os.Stderr, " -h, --help \t\t\tShow this help message and exit\n")- case *args.mode == "ingestor":+ case *args.Mode == "ingestor":fmt.Fprintf(os.Stderr, "Usage: %s --ingestor [OPTIONS]\n\n", os.Args[0])fmt.Fprintf(os.Stderr, "RAGFlow Ingestion Worker - Document ingestion processing\n\n")fmt.Fprintf(os.Stderr, "Options:\n")@@ -357,7 +290,7 @@ func printHelp(args *serverArgs) {fmt.Fprintf(os.Stderr, " --log-level string\tLog level: debug, info, warn, error (default: warn)\n")fmt.Fprintf(os.Stderr, " --profile \t\tEnable pprof server\n")fmt.Fprintf(os.Stderr, " -h, --help \t\tShow this help message and exit\n")- case *args.mode == "syncer":+ case *args.Mode == "syncer":fmt.Fprintf(os.Stderr, "Usage: %s --syncer [OPTIONS]\n\n", os.Args[0])fmt.Fprintf(os.Stderr, "RAGFlow Sync Service - Sync files from source to RAGFlow\n\n")fmt.Fprintf(os.Stderr, "Options:\n")@@ -368,7 +301,7 @@ func printHelp(args *serverArgs) {fmt.Fprintf(os.Stderr, " --log-level string\tLog level: debug, info, warn, error (default: warn)\n")fmt.Fprintf(os.Stderr, " --profile \t\tEnable pprof server\n")fmt.Fprintf(os.Stderr, " -h, --help \t\tShow this help message and exit\n")- case *args.mode == "deepdoc":+ case *args.Mode == "deepdoc":fmt.Fprintf(os.Stderr, "Usage: %s --deepdoc [OPTIONS]\n\n", os.Args[0])fmt.Fprintf(os.Stderr, "RAGFlow DeepDoc Inference Service - DeepDoc model inference service\n\n")fmt.Fprintf(os.Stderr, "Options:\n")@@ -391,12 +324,12 @@ func main() {os.Exit(1)}- if arguments.helpFlag || arguments.mode == nil {+ if arguments.HelpFlag || arguments.Mode == nil {printHelp(arguments)os.Exit(1)}- if arguments.versionFlag {+ if arguments.VersionFlag {fmt.Printf("RAGFlow version: %s\n", common.GetRAGFlowVersion())os.Exit(1)}@@ -404,19 +337,16 @@ func main() {// Initialize local variables (runtime variables from Redis)err = server.InitLocalVariables()if err != nil {- fmt.Printf("Failed to start %s server: %v\n", *arguments.mode, err)+ fmt.Printf("Failed to start %s server: %v\n", *arguments.Mode, err)os.Exit(1)}- // Temporary logger initialization- var serverName string- if arguments.name != nil {- serverName = *arguments.name- } else {- serverName = fmt.Sprintf("%s_server", *arguments.mode)- }+ // Temporary logger name (pre-config): explicit --name wins, else+ // "<mode>_server". The final name (with the resolved port for api/admin)+ // is derived below after the configuration is loaded.+ serverName := bootstrap.TempServerName(*arguments.Mode, arguments.Name)- logLevel := selectedLogLevel(arguments, "")+ logLevel := bootstrap.SelectedLogLevel(arguments, "")if higherThanInfo := common.LogLevelHigherThanInfo(logLevel); higherThanInfo {logLevel = "info"}@@ -427,8 +357,8 @@ func main() {// Initialize configurationvar configPath string- if arguments.configPath != nil {- configPath = *arguments.configPath+ if arguments.ConfigPath != nil {+ configPath = *arguments.ConfigPath}if err = server.Init(configPath); err != nil {@@ -443,69 +373,58 @@ func main() {// 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)+ 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.- // Side effects that log (DeepDoc registration) move below, after the- // real file-backed logger is up.- switch *arguments.mode {+ // Resolve the effective server port (CLI > config/env > default) and set it+ // on the config so the server binds the right port. This block 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. Side effects that log (DeepDoc registration) move+ // below, after the real file-backed logger is up. The dead UUID branch for+ // ingestor/syncer/deepdoc (serverName was already pre-filled above) is+ // dropped: ResolveServerName resolves them to "<mode>_server", matching the+ // original no-name behavior.+ var resolvedPort int+ switch *arguments.Mode {case "api":- port, portErr := globalConfig.ResolvePort(globalConfig.GetAPIServerConfig().HTTPPort, arguments.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)- }+ resolvedPort = portcase "admin":- port, portErr := globalConfig.ResolvePort(globalConfig.GetAdminServerConfig().HTTPPort, arguments.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 == "" {- uuid := common.GenerateUUID()- serverName = fmt.Sprintf("ingestor_server_%s", uuid)- }- case "syncer":- if serverName == "" {- uuid := common.GenerateUUID()- serverName = fmt.Sprintf("syncer_server_%s", uuid)- }- case "deepdoc":- if serverName == "" {- uuid := common.GenerateUUID()- serverName = fmt.Sprintf("deepdoc_server_%s", uuid)- }- case "migrate":- if arguments.name == nil {- serverName = "migrate"- }+ resolvedPort = port+ case "ingestor", "syncer", "deepdoc", "migrate":+ // No port embedding; the final name is derived below.default:- err = errors.New(*arguments.mode)+ err = errors.New(*arguments.Mode)common.Error("invalid server mode", err)os.Exit(1)}+ // Final server name: explicit --name wins; api/admin embed the resolved+ // port; ingestor/syncer/deepdoc/migrate use their fixed forms. An unknown+ // mode is rejected by the switch above.+ finalName, nameErr := bootstrap.ResolveServerName(*arguments.Mode, arguments.Name, resolvedPort)+ if nameErr != nil {+ common.Error("invalid server mode", nameErr)+ os.Exit(1)+ }+ serverName = finalName+// set server name and log file pathserver.SetServerName(serverName)@@ -513,9 +432,9 @@ func main() {// logger exists: its registration lines (and the Fatal abort on a missing// backend) must land in the run's log file, not in the pre-config// stdout-only window.- switch *arguments.mode {+ switch *arguments.Mode {case "api", "ingestor":- if err = registerNativeDeepDoc(arguments); err != nil {+ if err = deepdocpkg.RegisterNativeDeepDoc(arguments); err != nil {common.Error("Failed to register in-process DeepDoc backend", err)os.Exit(1)}@@ -523,11 +442,11 @@ func main() {}// Print all configuration settings- common.Info(fmt.Sprintf("Starting %s server: %s, mode: %s", *arguments.mode, serverName, globalConfig.GetMode()))+ common.Info(fmt.Sprintf("Starting %s server: %s, mode: %s", *arguments.Mode, serverName, globalConfig.GetMode()))server.PrintAll()// Start pprof server if requested- if arguments.enablePProf {+ if arguments.EnablePProf {go func() {common.Info("Starting pprof server", zap.String("addr", "localhost:6060"))if pprofErr := http.ListenAndServe("localhost:6060", nil); pprofErr != nil {@@ -540,7 +459,7 @@ func main() {// downgrade check nor any of the engines started below, so it can run// before any server mode boots (see docker/entrypoint.sh and// docker/launch_backend_service.sh).- migrate := *arguments.mode == "migrate"+ migrate := *arguments.Mode == "migrate"if migrate {common.Info("Running database migrations")}@@ -589,28 +508,28 @@ func main() {}defer server.ShutdownServer(ctx)- if arguments.name == nil {- arguments.name = &serverName+ if arguments.Name == nil {+ arguments.Name = &serverName}- switch *arguments.mode {+ switch *arguments.Mode {case "api":- if err = runAPI(ctx, serverName, arguments); err != nil {+ if err = apipkg.Run(ctx, serverName, arguments); err != nil {fmt.Printf("Failed to start API server: %v\n", err)os.Exit(1)}case "admin":- if err = runAdmin(ctx, serverName, arguments); err != nil {+ if err = admin.Run(ctx, serverName, arguments); err != nil {fmt.Printf("Failed to start ADMIN server: %v\n", err)os.Exit(1)}case "ingestor":- if err = runIngestor(ctx, cancel, serverName, arguments); err != nil {+ if err = ingestorpkg.Run(ctx, cancel, serverName, arguments); err != nil {fmt.Printf("Failed to start INGESTION worker: %v\n", err)os.Exit(1)}case "syncer":- if err = runSyncer(ctx, cancel, serverName, arguments); err != nil {+ if err = syncerpkg.Run(ctx, cancel, serverName, arguments); err != nil {fmt.Printf("Failed to start SYNCER: %v\n", err)os.Exit(1)}@@ -620,49 +539,11 @@ func main() {os.Exit(1)}default:- fmt.Printf("Invalid server mode: %s\n", *arguments.mode)+ fmt.Printf("Invalid server mode: %s\n", *arguments.Mode)os.Exit(1)}}-func setLogger(serverName string) {- // log filename- logFileName := fmt.Sprintf("%s.log", serverName)-- globalConfig := server.GetConfig()- logConfig := globalConfig.GetLogConfig()-- // 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,- Path: logConfig.Path,- MaxSize: logConfig.MaxSize,- MaxBackups: logConfig.MaxBackups,- MaxAge: logConfig.MaxAge,- Compress: logConfig.Compress,- }-- common.SyncLog()- if err := common.InitLogger(logLevel, fileOut, serverName); err != nil {- common.Error("Failed to reinitialize logger with configured level", err)- }-}--// checkDatabaseVersion refuses to run a server when the running code is older-// than the version recorded in the system_settings migration marker. Migrating-// the database forward is a one-way operation, so an older binary would read and-// write a schema it does not understand.-//-// A missing marker, or a version on either side that cannot be parsed, never-// blocks startup: without a usable comparison there is no evidence that the-// database is ahead of the code.-//-// RAGFLOW_DEV_MODE turns the check off entirely. A development build can carry-// a marker for a release that is not tagged yet, in which case the comparison-// would reject the build that wrote the marker.func checkDatabaseVersion(ctx context.Context) error {if common.DevModeEnabled() {common.Warn("Development mode is enabled, skipping the database downgrade check",@@ -696,975 +577,3 @@ func checkDatabaseVersion(ctx context.Context) error {zap.String("database_version", databaseVersion))return nil}--func runAdmin(ctx context.Context, serverName string, args *serverArgs) error {-- globalConfig := server.GetConfig()- serverMode := globalConfig.GetMode()-- // Set Gin mode- if serverMode == "debug" {- gin.SetMode(gin.DebugMode)- } else {- gin.SetMode(gin.ReleaseMode)- }-- adminService := admin.NewService()- adminHandler := admin.NewHandler(adminService)-- if err := admin.InitLicense(); err != nil {- common.Warn("Failed to initialize license", zap.Error(err))- }-- if args.initSuperUser {- // Initialize default admin user- if err := adminService.InitDefaultAdmin(); err != nil {- common.Error("Failed to initialize default admin user", err)- }- }-- // Initialize router- r := admin.NewRouter(adminHandler)-- // Create Gin engine- ginEngine := gin.New()- // Mirror Quart's merge_slashes: collapse duplicate slashes before routing.- ginEngine.RemoveExtraSlash = true- // Only honor X-Forwarded-For / X-Real-IP from the configured proxies- // (default: the loopback nginx bundled in the image), never from every peer.- if err := common.ConfigureTrustedProxies(ginEngine, globalConfig.GetAPIServerConfig().TrustedProxies); err != nil {- common.Fatal("Failed to configure trusted proxies", zap.Error(err))- }-- // Middleware- ginEngine.Use(common.GinLogger())- ginEngine.Use(gin.Recovery())-- // Setup routes- r.Setup(ginEngine)-- adminConfig := globalConfig.GetAdminServerConfig()- addr := fmt.Sprintf(":%d", adminConfig.HTTPPort)- srv := &http.Server{- Addr: addr,- Handler: ginEngine,- }- // Print RAGFlow Admin logo- common.Info("" +- "\n ____ ___ ______________ ___ __ _ \n" +- " / __ \\/ | / ____/ ____/ /___ _ __ / | ____/ /___ ___ (_)___ \n" +- " / /_/ / /| |/ / __/ /_ / / __ \\ | /| / / / /| |/ __ / __ `__ \\/ / __ \\ \n" +- " / _, _/ ___ / /_/ / __/ / / /_/ / |/ |/ / / ___ / /_/ / / / / / / / / / /\n" +- " /_/ |_/_/ |_\\____/_/ /_/\\____/|__/|__/ /_/ |_\\__,_/_/ /_/ /_/_/_/ /_/ \n")-- // Print RAGFlow version- common.Info(fmt.Sprintf("RAGFlow admin version: %s", common.GetRAGFlowVersion()))-- // Set log level- setLogger(serverName)-- // Start HTTP server in a goroutine- go func() {- common.Info(fmt.Sprintf("Starting RAGFlow admin HTTP server on port: %d", adminConfig.HTTPPort))- if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {- common.Fatal("Failed to start server", zap.Error(err))- }- }()-- // Wait for shutdown signal from main's signal.NotifyContext- <-ctx.Done()-- common.Info("Received shutdown signal")- common.Info("Shutting down RAGFlow HTTP server...")-- // Create context with timeout for graceful shutdown- quitCtx, quitCancel := context.WithTimeout(context.Background(), 30*time.Second)- defer quitCancel()-- // Shutdown HTTP server- if err := srv.Shutdown(quitCtx); err != nil {- common.Fatal("Server forced to shutdown", zap.Error(err))- }-- common.Info("Admin HTTP server exited")- return nil-}--// startHeartbeat initializes and starts the heartbeat reporter to the admin server.-// It is shared by API, ingestion, and syncer server modes.-// The caller must defer the returned *utility.ScheduledTask's Stop() method.-func startHeartbeat(serverType common.ServerType, serverID string, port int, heartBeatInterval time.Duration) *utility.ScheduledTask {- localIP, err := utility.GetLocalIP()- if err != nil {- common.Fatal("fail to get local ip address")- }-- service.AdminServiceClient = service.NewAdminClient(- serverType,- serverID,- localIP,- port,- )- if err = service.AdminServiceClient.InitHTTPClient(); err != nil {- common.Warn("Failed to initialize heartbeat service", zap.Error(err))- return nil- }-- heartbeatReporter := utility.NewScheduledTask("Heartbeat reporter", heartBeatInterval, func() {- if err = service.AdminServiceClient.SendHeartbeat(); err == nil {- local.SetAdminStatus(0, "")- } else {- local.SetAdminStatus(1, err.Error())- }- })- heartbeatReporter.Start()- return heartbeatReporter-}--func runIngestor(ctx context.Context, cancel context.CancelFunc, serverName string, args *serverArgs) error {- // Initialize tokenizer (rag_analyzer)- // tokenizer.Init handles DictPath fallback: env var → /usr/share/infinity/resource- if err := tokenizer.Init(&tokenizer.PoolConfig{}); err != nil {- common.Fatal("Failed to initialize tokenizer", zap.Error(err))- }- defer tokenizer.Close()-- // Fail fast if the cl100k_base BPE table is missing. NumTokensFromString /- // TrimContentToTokenLimit now panic rather than degrading silently, so this- // trades a mid-request panic for a clear startup failure.- if err := tokenizer.InitCL100KEncoder(); err != nil {- common.Fatal("Failed to initialize cl100k_base tokenizer", zap.Error(err))- }- logTokenizerCounters()-- // The dataset-level post-processing consumer cluster (§11) is owned and run by- // the Ingestor: it is started inside ingestor.Start() and joined inside- // ingestor.Stop(), so its lifecycle matches the ingestor. The configured- // default LLM/embedding ids are passed so the LLM deduper is used (instead- // of the noop fallback that still emits merged products). Best-effort: a- // provisioning error is logged by the Ingestor and the pipeline still- // writes available_int=0 compiled chunks; they just won't be merged until- // the consumer is available.- globalConfig := server.GetConfig()- 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 := globalConfig.GetIngestorMaxConcurrentWorkers(args.ingestorMaxConcurrentWorkers)- if err != nil {- return err- }- // Apply the configured compiler pool size (no-op when 0; the pool keeps its- // vCPU default, overridable via KC_COMPILE_CONCURRENCY).- knowledge_compile.SetCompilerConcurrency(ingestorCfg.CompilerPoolSize)- ingestor := ingestion.NewIngestor(*args.name, int32(workers), []string{"pdf", "docx", "txt"})- ingestor.SetKnowledgeCompileModelConfig(- globalConfig.GetDefaultChatModel().Name,- globalConfig.GetDefaultEmbeddingModel().Name,- )- // The dataset-level knowledge-compile consumer (tree/structure products) upserts- // into the dataset-nav tree, so the Ingestor must install the same ES-backed- // NavService the API server installs. Without this, nav.GetNavService() returns- // nil and tree/structure products are dropped (the consumer logs "nav service- // unavailable, skipping dataset-nav upsert"), leaving the dataset tree empty.- // The embedder resolves the tenant's embedding model on demand, so both- // Search and UpsertDoc can embed queries/summaries automatically.- navService := nlp.NewNavService(service.NewNavEmbedder(service.NewModelFactory(), ""))- // The cluster namer/merger is the counterpart of Python's- // _llm_create_summary / _llm_merge: a new cluster is named after the model's- // topic title and an existing cluster's description is fused with the joining- // document. Passing an empty model ref resolves each tenant's default chat- // model on demand; without one the nav service keeps its deterministic- // behavior.- navService.SetNavMergeLLM(service.NewNavMergeLLM(service.NewModelFactory(), ""))- nav.SetNavService(navService)- // Memory extraction runs on the Ingestor's shared NATS consumer + worker- // pool (task_type="memory" dispatched by handleAndExecute -> executeMemoryTask),- // so there is no longer a dedicated Redis memory consumer to start.- ingestor.SetMemoryMessageService(service.NewMemoryMessageService(service.NewMemoryService()))-- // Start returns immediately (it launches the owned consume/compile- // goroutines and joins them via Stop); a provisioning failure here must- // fail the server (main's os.Exit(1) path) instead of reporting a- // healthy ingestor that can never consume.- if err = ingestor.Start(); err != nil {- common.Error("Failed to initialize ingestor", err)- return err- }-- common.Info("\n ____ __ _\n" +- " / _/___ ____ ____ _____/ /_(_)___ ____ ________ ______ _____ _____\n" +- " / // __ \\/ __ `/ _ \\/ ___/ __/ / __ \\/ __ \\ / ___/ _ \\/ ___/ | / / _ \\/ ___/\n" +- " _/ // / / / /_/ / __(__ ) /_/ / /_/ / / / / (__ ) __/ / | |/ / __/ /\n" +- "/___/_/ /_/\\__, /\\___/____/\\__/_/\\____/_/ /_/ /____/\\___/_/ |___/\\___/_/\n" +- " /____/\n")-- // Print RAGFlow version- common.Info(fmt.Sprintf("RAGFlow ingestion service version: %s", common.GetRAGFlowVersion()))-- // Set log level- setLogger(serverName)-- // Start heartbeat reporter to admin server- if hb := startHeartbeat(- common.ServerTypeIngestion,- fmt.Sprintf("ingestor-%s", ingestor.ID()[:8]),- 0,- globalConfig.GetHeartbeatInterval(),- ); hb != nil {- defer hb.Stop()- }-- // Wait for either an OS shutdown signal or a shutdown command from the admin- select {- case <-ctx.Done():- common.Info("Received shutdown signal")- common.Info(fmt.Sprintf("Shutting down RAGFlow ingestor %s ...", *args.name))- case <-ingestor.ShutdownCh:- common.Info(fmt.Sprintf("Received shutdown command from admin, stopping ingestor %s ...", *args.name))- cancel()- }-- // Create context with timeout for graceful shutdown- shutdownCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)- defer cancel()-- ingestor.Stop(shutdownCtx)-- common.Info(fmt.Sprintf("Ingestor %s shutdown complete", *args.name))-- return nil-}--func runSyncer(ctx context.Context, cancel context.CancelFunc, serverName string, args *serverArgs) error {- globalConfig := server.GetConfig()- syncerConfig := globalConfig.GetSyncerConfig()- fileSyncer := syncer.NewSyncer(syncerConfig.MaxConcurrentSyncs)-- if err := fileSyncer.StartContext(ctx); err != nil {- common.Error("Failed to initialize file syncer", err)- return err- }-- common.Info("\n _______ __ _____\n" +- " / ____(_) /__ / ___/__ ______ ________ _____\n" +- " / /_ / / / _ \\ \\__ \\/ / / / __ \\/ ___/ _ \\/ ___/\n" +- " / __/ / / / __/ ___/ / /_/ / / / / /__/ __/ /\n" +- " /_/ /_/_/\\___/ /____/\\__, /_/ /_/\\___/\\___/_/\n" +- " /____/ \n")-- // Print RAGFlow version- common.Info(fmt.Sprintf("RAGFlow file syncer service version: %s", common.GetRAGFlowVersion()))-- // Set log level- setLogger(serverName)-- // Start heartbeat reporter to admin server- if hb := startHeartbeat(- common.ServerTypeFileSyncer,- fmt.Sprintf("syncer-%s", fileSyncer.ID()[:8]),- 0,- globalConfig.GetHeartbeatInterval(),- ); hb != nil {- defer hb.Stop()- }-- // Wait for either an OS shutdown signal or a shutdown command from the admin- select {- case <-ctx.Done():- common.Info("Received shutdown signal")- common.Info(fmt.Sprintf("Shutting down RAGFlow file syncer %s ...", *args.name))- case <-fileSyncer.ShutdownCh:- common.Info(fmt.Sprintf("Received shutdown command from admin, stopping file syncer %s ...", *args.name))- cancel()- }-- fileSyncer.Stop()- common.Info(fmt.Sprintf("File syncer %s shutdown complete", *args.name))-- return nil-}--func runAPI(ctx context.Context, serverName string, args *serverArgs) error {- // Initialize admin status (default: unavailable=1)- local.InitAdminStatus(1, "admin server not connected")-- // Initialize tokenizer (rag_analyzer)- // tokenizer.Init fills DictPath from env var or default, so- // tokenizerCfg.DictPath carries the resolved path for downstream use.- tokenizerCfg := &tokenizer.PoolConfig{}- if err := tokenizer.Init(tokenizerCfg); err != nil {- common.Fatal("Failed to initialize tokenizer", zap.Error(err))- }- defer tokenizer.Close()-- // Fail fast if the cl100k_base BPE table is missing. NumTokensFromString /- // TrimContentToTokenLimit now panic rather than degrading silently, so this- // trades a mid-request panic for a clear startup failure.- if err := tokenizer.InitCL100KEncoder(); err != nil {- common.Fatal("Failed to initialize cl100k_base tokenizer", zap.Error(err))- }-- // Initialize global QueryBuilder using tokenizer's DictPath- // This ensures the Synonym uses the same wordnet directory as tokenizer- if err := nlp.InitQueryBuilderFromTokenizer(tokenizerCfg.DictPath); err != nil {- common.Fatal("Failed to initialize query builder", zap.Error(err))- }-- if err := startServer(ctx, serverName, args); err != nil {- return err- }-- common.Info("Server exited")-- return nil-}--func startServer(ctx context.Context, serverName string, arguments *serverArgs) error {-- globalConfig := server.GetConfig()- serverMode := globalConfig.GetMode()- // Set Gin mode- if serverMode == "debug" {- gin.SetMode(gin.DebugMode)- } else {- gin.SetMode(gin.ReleaseMode)- }-- // Initialize service layer- userService := service.NewUserService()- documentService := document.NewDocumentService()- datasetsService := dataset.NewDatasetService()- metadataService := service.NewMetadataService()- chunkService := chunk.NewChunkService()- tenantService := service.NewTenantService()- chatService := service.NewChatService()- chatChannelService := service.NewChatChannelService()- langfuseService := service.NewLangfuseService()- chatSessionService := service.NewChatSessionService()- openaiChatService := service.NewOpenAIChatService()- systemService := service.NewSystemService()- statsService := service.NewStatsService()- connectorService := service.NewConnectorService()- searchService := service.NewSearchService()- searchService.SetTenantService(tenantService)- fileService := file.NewFileService(documentService)- memoryService := service.NewMemoryService()- mcpService := service.NewMCPService()- modelProviderService := service.NewModelProviderService()- modelFactory := service.NewModelFactory()- modelCallService := service.NewModelCallServiceWithProviderService(modelProviderService, modelFactory)-- // Wire the real MemorySaver so the Message component can persist- // conversation turns to memory stores declared in the canvas DSL.- component.SetMemorySaver(service.NewMemorySaverAdapter(memoryService))-- // Initialize doc engine for skill search- docEngine := engine.Get()- documentDAO := dao.NewDocumentDAO()- retrievalEnhancer := retrievalbridge.NewEnhancer(docEngine, metadataService)- // Keep the concrete adapter: it is both the canvas/agent-tool backend and the- // target of the agentic-RAG bridge wired below. The bridge must hold it- // directly (not look it up in the registry) because the registry is shared —- // agenttool.SetRetrievalService and runtime.SetRetrievalService write the same- // singleton, so a bridge that resolved its target per call would find itself.- retrievalAdapter := agenttool.NewNLPRetrievalAdapterFromDeps(- docEngine,- documentDAO,- agenttool.RetrievalModelConstructors{- Embedding: func(ctx context.Context, tenantID, modelRef string) (*modelModule.EmbeddingModel, error) {- access := service.ModelAccess{TenantID: tenantID}- if strings.TrimSpace(modelRef) == "" {- return modelFactory.NewDefaultEmbeddingModel(ctx, access)- }- return modelFactory.NewEmbeddingModel(ctx, access, modelRef)- },- Chat: func(ctx context.Context, tenantID, modelRef string) (*modelModule.ChatModel, error) {- access := service.ModelAccess{TenantID: tenantID}- if strings.TrimSpace(modelRef) == "" {- return modelFactory.NewDefaultChatModel(ctx, access)- }- return modelFactory.NewChatModel(ctx, access, modelRef)- },- Rerank: func(ctx context.Context, tenantID, modelRef string) (*modelModule.RerankModel, error) {- return modelFactory.NewRerankModel(ctx, service.ModelAccess{TenantID: tenantID}, modelRef)- },- },- retrievalEnhancer,- )- agenttool.SetRetrievalService(retrievalAdapter)- agenttool.SetMemoryRetrievalService(retrievalbridge.NewMemoryAdapter(memoryService, retrievalEnhancer))- common.Info("agent: retrieval service adapter installed")-- // The smart-reasoning agent's corpus tools (internal/agentic_rag): regex- // pushdown and lexical BM25 over the same doc engine the retrieval adapter- // wraps. The locate tools resolve these services per call, so they must be- // registered before the server starts serving.- runtime.SetGrepService(smartagentic.NewGrepAdapter(docEngine))- bm25Adapter := smartagentic.NewBm25Adapter(docEngine)- bm25Adapter.SetQueryBuilder(nlp.GetQueryBuilder())- runtime.SetBm25Service(bm25Adapter)- common.Info("agent: smart-reasoning corpus services installed (grep + bm25)")-- // The compiled-knowledge graph walk (graph_explore) resolves its service per- // call the same way. Without this registration GetKgService() returns the- // failing stub, so the tool could only ever report an infrastructure error.- // The seed encoder is left unset: the walk then seeds by keyword match on the- // entity rows, the documented fallback on a deployment without an embedder.- smartagentic.SetKgService(smartagentic.NewKgAdapter(docEngine))- common.Info("agent: smart-reasoning compiled-knowledge graph service installed")- // The smart-reasoning agent's corpus tools resolve the shared retrieval- // service per call, so the production adapter must be registered before the- // server starts serving.- runtime.SetRetrievalService(retrievalbridge.NewRuntimeAdapter(retrievalAdapter))- common.Info("agent: runtime retrieval service wired")-- // Initialize handler layer- authHandler := handler.NewAuthHandler()- userHandler := handler.NewUserHandler(userService)- tenantHandler := handler.NewTenantHandler(tenantService, userService, datasetsService)- documentHandler := handler.NewDocumentHandler(documentService, datasetsService, fileService)- datasetsHandler := handler.NewDatasetsHandler(datasetsService, metadataService)- systemHandler := handler.NewSystemHandler(systemService)- statsHandler := handler.NewStatsHandler(statsService)- chunkHandler := handler.NewChunkHandler(chunkService, userService)- chatHandler := handler.NewChatHandler(chatService, userService)- chatChannelHandler := handler.NewChatChannelHandler(chatChannelService)- langfuseHandler := handler.NewLangfuseHandler(langfuseService)- chatSessionHandler := handler.NewChatSessionHandler(chatSessionService, userService)- openaiChatHandler := handler.NewOpenAIChatHandler(openaiChatService)- connectorHandler := handler.NewConnectorHandler(connectorService, userService)- searchHandler := handler.NewSearchHandler(searchService, userService)- fileHandler := handler.NewFileHandler(fileService, userService)- memoryHandler := handler.NewMemoryHandler(memoryService)- mcpHandler := handler.NewMCPHandler(mcpService)-- // MCP server endpoint — exposes RAGFlow capabilities as MCP tools- // (ragflow_retrieval, ragflow_list_datasets, ragflow_list_chats) to- // external AI clients via JSON-RPC over HTTP.- mcpServerHandler := handler.NewMCPServerHandler(datasetsService, chatService)- skillSearchHandler := handler.NewSkillSearchHandler(docEngine, documentService)- providerHandler := handler.NewProviderHandler(userService, modelProviderService, modelCallService)- // Install the agent service's Kvrocks-backed run infrastructure- // (CheckPointStore / StateSerializer / RunTracker). When Redis- // is unreachable (degraded boot, stand-alone mode, no-redis CI)- // the constructors return errors, and we fall through to the- // in-memory / no-tracking path: the agent service treats nil- // options as the in-memory test path, so graceful degradation- // is a 1-line if-not-nil pass-through — no separate "boot" mode- // required.- agentOpts := buildAgentRunOptions()- agentService := service.NewAgentServiceWithOptions(- agentOpts.checkpointStore,- agentOpts.stateSerializer,- agentOpts.runTracker,- )- agentHandler := handler.NewAgentHandler(ctx, agentService, fileService)-- // Public chatbot/agentbot endpoints (api/v1/chatbots/...,- // api/v1/agentbots/...) and the agent attachment download.- // BotService delegates the agentBot completion to agentService so- // both paths share the same canvas runner.- botService := service.NewBotService(agentService)- botHandler := handler.NewBotHandler(botService)-- // Wire the TTS synthesizer to the per-tenant model-provider- // dispatch. SynthesizeRequest is routed through- // ModelProviderService.AudioSpeech, which fans out to the- // tenant's configured TTS model driver. When the model- // provider is unconfigured, the synthesizer falls back to a- // no-op echo (the audio package contract), so this is always- // safe to call.- configureTTSSynthesizer(modelCallService)- searchBotHandler := handler.NewSearchBotHandler(- searchService,- tenantService,- modelFactory,- chunkService,- )- askService := service.NewAskService(chunkService, nil, 0, 0)- searchBotHandler.SetAskService(askService)- chatHandler.SetMindMapDependencies(searchService, tenantService, modelFactory, chunkService)- searchHandler.SetCompletionDependencies(modelFactory, askService)- pluginHandler := handler.NewPluginHandler(service.NewPluginService())- modelHandler := handler.NewModelHandler(service.NewModelProviderService())- fileCommitHandler := handler.NewFileCommitHandler(file.NewFileCommitService())-- // Dify retrieval handler- retrievalService := nlp.NewRetrievalService(docEngine, documentDAO)- difyRetrievalHandler := handler.NewDifyRetrievalHandler(- datasetsService,- modelFactory,- metadataService,- retrievalService,- documentDAO,- docEngine,- )- componentsSvc := service.NewComponentsService()- componentsHandler := handler.NewComponentsHandler(componentsSvc)- pipelineHandler := handler.NewPipelineHandler()- compilationTemplateHandler := handler.NewCompilationTemplateHandler(service.NewCompilationTemplateService())- compilationTemplateGroupHandler := handler.NewCompilationTemplateGroupHandler(service.NewCompilationTemplateGroupService())- datasetArtifactHandler := handler.NewDatasetArtifactHandler(service.NewDatasetArtifactService(), datasetsService, file.NewFileCommitService())-- // Install the production eino-based chat invoker as the shared chat default,- // so agentic-search runtime LLM calls work in production. Without this,- // chat.GetDefaultInvoker() stays nil and the runtime falls back gracefully.- component.InstallDefaultChatInvoker()-- // Install the dataset-nav ES-backed service (internal/service/nav +- // internal/service/nlp). The embedder resolves the tenant's embedding model- // on demand so Search/UpsertDoc can embed queries/summaries automatically,- // and the cluster namer/merger resolves the tenant's default chat model the- // same way (see the ingestor's wrapping of SetNavMergeLLM).- apiNavService := nlp.NewNavService(service.NewNavEmbedder(modelFactory, ""))- apiNavService.SetNavMergeLLM(service.NewNavMergeLLM(modelFactory, ""))- nav.SetNavService(apiNavService)-- // Install the compiled-wiki search service. It is backed directly by the- // document engine: QueryPages filters the tenant-scoped index to- // compile_kwd="wiki_page" (+ supported kinds) so ordinary source chunks are- // never relabeled as wiki pages, and BackfillChunks fetches original chunks- // by id. When the engine is unavailable the service degrades to empty so the- // agent falls back to hybrid search (no failing call).- wikisearch.SetService(wikisearch.NewEngineService(engine.Get()))-- // Initialize router- r := router.NewRouter(authHandler,- userHandler,- tenantHandler,- documentHandler,- datasetsHandler,- systemHandler,- statsHandler,- chunkHandler,- chatHandler,- chatChannelHandler,- langfuseHandler,- chatSessionHandler,- connectorHandler,- searchHandler,- fileHandler,- memoryHandler,- mcpHandler,- mcpServerHandler,- skillSearchHandler,- providerHandler,- agentHandler,- searchBotHandler,- difyRetrievalHandler,- pluginHandler,- modelHandler,- fileCommitHandler,- openaiChatHandler,- botHandler,- componentsHandler,- pipelineHandler,- compilationTemplateHandler,- compilationTemplateGroupHandler,- datasetArtifactHandler)-- // Create Gin engine- ginEngine := gin.New()- // Mirror Quart's merge_slashes: collapse duplicate slashes before routing.- ginEngine.RemoveExtraSlash = true- // Only honor X-Forwarded-For / X-Real-IP from the configured proxies- // (default: the loopback nginx bundled in the image), never from every- // peer. c.ClientIP() feeds the agent webhook ip_whitelist gate and the- // login audit records, so gin's trust-everything default would let any- // caller pick its own address.- if err := common.ConfigureTrustedProxies(ginEngine, globalConfig.GetAPIServerConfig().TrustedProxies); err != nil {- common.Fatal("Failed to configure trusted proxies", zap.Error(err))- }-- // Middleware- // Note: common.GinLogger() is registered inside router.Setup so the- // HTTP request log captures every endpoint the router owns (including- // those registered by Setup itself). Registering it here would run- // it twice for those endpoints and double every access-log line.- ginEngine.Use(gin.Recovery())-- // Setup routes- r.Setup(ginEngine)-- _, err := channels.Start(ctx)- if err != nil {- return fmt.Errorf("start chat-channel: %w", err)- }-- apiServerConfig := globalConfig.GetAPIServerConfig()-- // Create HTTP server with timeouts to prevent slow clients from blocking shutdown- addr := fmt.Sprintf(":%d", apiServerConfig.HTTPPort)- srv := &http.Server{- Addr: addr,- Handler: ginEngine,- BaseContext: func(net.Listener) context.Context { return ctx },- ReadHeaderTimeout: 10 * time.Second,- ReadTimeout: 60 * time.Second,- // WriteTimeout spans "request header read → response written", so it is a- // ceiling on the WHOLE request, not on a slow client's reads. Measured- // (2026-09-15, FRAMES 20q): three multi-hop questions take 150–225s to reach- // their response, and at 120s the server closed the connection with no- // response at all — the client reports- // `RemoteDisconnected('Remote end closed connection without response')` and- // the benchmark re-runs the whole question (max_retries: 2), so one slow- // question cost three full pipelines. 180s clears the measured distribution's- // middle; questions whose composition alone runs past it still need streaming- // or a larger budget.- WriteTimeout: 180 * time.Second,- IdleTimeout: 120 * time.Second,- }- apiListener, err := net.Listen("tcp", addr)- if err != nil {- return fmt.Errorf("listen API server on %s: %w", addr, err)- }- defer apiListener.Close()-- serveErr := make(chan error, 2)- serve := func(name string, srv *http.Server, listener net.Listener) {- if err := srv.Serve(listener); err != nil && !errors.Is(err, http.ErrServerClosed) {- serveErr <- fmt.Errorf("%s server failed: %w", name, err)- }- }-- var mcpSrv *http.Server- var mcpCloser interface{ Close() error }- var mcpListener net.Listener- mcpConfig := apiServerConfig.MCP- if mcpConfig.Enabled {- mcpHandler, err := mcpServerHandler.NewStandalone(ctx, authHandler, mcpConfig)- if err != nil {- return err- }-- mcpCloser = mcpHandler- defer mcpHandler.Close()- mcpAddr := net.JoinHostPort(strings.Trim(mcpConfig.Host, "[]"), strconv.Itoa(mcpConfig.Port))- mcpListener, err = net.Listen("tcp", mcpAddr)- if err != nil {- return fmt.Errorf("listen MCP server on %s: %w", mcpAddr, err)- }- defer mcpListener.Close()- mcpSrv = &http.Server{- Addr: mcpAddr,- Handler: mcpHandler,- BaseContext: func(net.Listener) context.Context { return ctx },- ReadHeaderTimeout: 10 * time.Second,- ReadTimeout: 60 * time.Second,- WriteTimeout: 0, // SSE streams outlive individual tool deadlines- IdleTimeout: 120 * time.Second,- }- go func() {- common.Info(fmt.Sprintf("MCP server starting on %s", mcpSrv.Addr))- serve("MCP", mcpSrv, mcpListener)- }()- }-- common.Info(- "\n ____ ___ ______ ______ __\n" +- " / __ \\ / | / ____// ____// /____ _ __\n" +- " / /_/ // /| | / / __ / /_ / // __ \\| | /| / /\n" +- " / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ /\n" +- " /_/ |_|/_/ |_|\\____//_/ /_/ \\____/ |__/|__/\n",- )- common.Info(fmt.Sprintf("RAGFlow Go Version: %s", common.GetRAGFlowVersion()))- common.Info(fmt.Sprintf("Server starting on port: %d", apiServerConfig.HTTPPort))-- // Set log level- setLogger(serverName)-- // Start server in a goroutine- go func() {- serve(serverName, srv, apiListener)- }()-- // Start heartbeat reporter to admin server- if hb := startHeartbeat(- common.ServerTypeAPI,- fmt.Sprintf("ragflow-server-%s", common.GenerateUUID()[:8]),- apiServerConfig.HTTPPort,- globalConfig.GetHeartbeatInterval(),- ); hb != nil {- defer hb.Stop()- }-- // Wait for either shutdown signal or serving failure.- var runErr error- select {- case <-ctx.Done():- common.Info("Received shutdown signal")- case err := <-serveErr:- runErr = err- common.Error("Server failed; shutting down", err)- }- common.Info("Shutting down server...")-- shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 30*time.Second)- defer shutdownCancel()-- if mcpCloser != nil {- if err = mcpCloser.Close(); err != nil {- common.Warn("Failed to close MCP handler", zap.Error(err))- }- }- if err = shutdownHTTPServer(shutdownCtx, "API", srv); err != nil {- return err- }- if mcpSrv != nil {- if err = shutdownHTTPServer(shutdownCtx, "MCP", mcpSrv); err != nil {- return err- }- }- return runErr-}--func shutdownHTTPServer(ctx context.Context, name string, srv *http.Server) error {- if err := srv.Shutdown(ctx); err != nil {- _ = srv.Close()- return fmt.Errorf("shutdown %s server: %w", name, err)- }- return nil-}--// agentRunOptions bundles the three optional injection slots the-// agent service accepts via NewAgentServiceWithOptions: the Redis--// backed CheckPointStore, StateSerializer, and RunTracker. The-// fields stay nil when the underlying constructors fail (Redis-// unreachable, etc.); the agent service treats nil as "in-memory-// / no-tracking" so the server continues to serve traffic without-// requiring Redis to be up.-type agentRunOptions struct {- checkpointStore canvas.CheckPointStore- stateSerializer canvas.StateSerializer- runTracker *canvas.RunTracker-}--// buildAgentRunOptions installs the Kvrocks-backed run infrastructure-// when Redis is available. The Redis client is the one already-// initialized at the top of main; the TTL is a conservative 24h for-// both the checkpoint store and the run tracker. On any error-// (Redis down at boot, constructor panic, nil-Redis fallback) we-// log and return a zero-value struct — the agent service falls back-// to the in-memory path transparently.-func buildAgentRunOptions() agentRunOptions {- var out agentRunOptions- if !kvrocks.IsEnabled() || kvrocks.Get() == nil {- common.Info("agent: redis client not initialised; agent run infra in in-memory mode (no checkpoints, no run tracker)")- return out- }- cp := canvas.NewKvrocksCheckPointStore(24 * time.Hour)- out.checkpointStore = cp- // stateSerializer is intentionally left nil. eino's default- // InternalSerializer (used when no compose.WithSerializer is- // passed at compile time) already knows how to round-trip- // runtime.CanvasState because the runtime package registers- // it via compose.RegisterSerializableType[CanvasState] in- // init(). Overriding with RAGFlow's plain-JSON- // CanvasStateSerializer (json.Marshal/Unmarshal) produces- // bytes the InternalSerializer cannot decode on the resume- // pass — the UserFillUp two-node pattern surfaces this as- // "load checkpoint from store fail: cannot unmarshal object- // into Go struct field checkpoint.Channels of type- // compose.channel". Rely on eino's default instead.- rt := canvas.NewRunTracker(24 * time.Hour)- out.runTracker = rt- common.Info("agent: redis-backed run infra installed (24h TTL on checkpoint store + run tracker; eino default serializer)")- return out-}--// configureTTSSynthesizer installs the audio.ModelProviderFunc-// that dispatches Synthesize requests through the project's-// ModelProviderService. The model provider's AudioSpeech method-// (internal/service/model_service.go) resolves the per-tenant TTS-// model driver, sends the request upstream, and returns-// synthesized audio bytes.-//-// The audio package's NewTTSDispatchFunc helper converts the-// audio.SynthesizeRequest shape into the model's dispatch shape-// (audioContent = req.Text, voice/lang → TTSConfig.Params,-// ModelName from req.Engine). When the model provider is-// unconfigured (nil dispatcher) the helper returns nil, which-// reverts the audio package to its default stub.-func configureTTSSynthesizer(modelCallService *service.ModelCallService) {- if modelCallService == nil {- common.Info("agent: model call service not initialised; TTS in no-op echo mode")- audio.SetModelProviderSynthesizer(nil)- return- }- audio.SetModelProviderSynthesizer(audio.NewTTSDispatchFunc(modelCallService))- common.Info("agent: TTS model-call dispatch installed (audio.Synthesize → ModelCallService.AudioSpeech)")-}--// inferenceTotalCores returns the CPU budget the DeepDoc inference config is-// validated against. It uses runtime.GOMAXPROCS(0) instead of runtime.NumCPU()-// so the budget reflects the cgroup CPU quota inside containers: Go 1.25+ derives-// GOMAXPROCS from the quota (CGroups v2 cpu.max / v1 cpu.cfs_quota_us), whereas-// runtime.NumCPU() reports the host's affinity-mask core count and ignores a-// container's CPU limit. Without this, a 2-CPU-limit pod on a 64-core host would-// "resolve" inference_cpu_cores: 0 to 64 and let inference_concurrency: 16 pass-// validation, oversubscribing the box the fail-fast guard in-// native.ValidateInferenceConfig exists to prevent.-func inferenceTotalCores() int {- n := goruntime.GOMAXPROCS(0)- if n < 1 {- return 1- }- return n-}--// registerNativeDeepDoc wires the in-process (Go) DeepDoc backend as the local-// inference backend. The server is built with -tags cgo and links ONNX Runtime-// statically (libonnxruntime.a, resolved at runtime via dlopen(NULL) from the-// running binary — see github.com/infiniflow/onnxruntime_go, the org mirror of-// yalue/onnxruntime_go), so there is no external-// DeepDoc HTTP service and no dynamic .so deployment.-//-// Fail-fast contract (P0): the in-process backend must be available at startup-// (ORT + models present). There is NO silent degradation to an empty analyzer:-// if the backend is not serving, the server aborts.-func registerNativeDeepDoc(arguments *serverArgs) error {- modelDir := resolveDeepDocModelDir()- dropScore := resolveDeepDocDropScore()-- if err := infnative.Register(modelDir, dropScore); err != nil {- common.Warn("in-process DeepDoc backend unavailable",- zap.String("reason", err.Error()))- }-- // The in-process (Go) DeepDoc backend is the ONLY production backend. Fail- // fast rather than silently parsing without layout/table/OCR if the local- // backend cannot serve (ORT + models must be present when built with -tags- // cgo).- if !infnative.Serving() {- common.Fatal("no in-process DeepDoc backend serving: provide the local ORT "+- "runtime + models and build with -tags cgo",- zap.String("model_dir", modelDir),- zap.String("ort_lib", "static (libonnxruntime.a via dlopen(NULL))"))- }- common.Info("in-process DeepDoc backend registered (production backend)",- zap.String("model_dir", modelDir))-- // Resolve the DeepDoc in-process inference configuration: the concurrency- // budget K (max in-flight Runs) and the CPU-core budget N (max cores- // inference may occupy). Both resolve from CLI > env > config > default. K- // defaults to 1; N defaults to "unset", which is derived from K so each Run- // stays single-threaded by default (the prior behaviour). An explicit N = 0- // means "all cores". All values are fail-fast validated against the process's- // cgroup-aware CPU budget at startup (see native.ValidateInferenceConfig and- // inferenceTotalCores), so a misconfiguration aborts rather than silently- // oversubscribing the box.- cfg := server.GetConfig()- K, _, errK := cfg.GetDeepDocInferenceConcurrency(arguments.deepdocInferenceConcurrency)- if errK != nil {- common.Fatal("invalid deepdoc inference concurrency", zap.Error(errK))- }- rawN, explicitN, errN := cfg.GetDeepDocInferenceCPUCores(arguments.deepdocInferenceCPUCores)- if errN != nil {- common.Fatal("invalid deepdoc inference cpu cores", zap.Error(errN))- }- // When N is unset, derive it from K so each Run opens with a single intra-op- // thread (coresPerInference = max(1, K/K) = 1), preserving the prior- // single-core-per-run semantics. An explicit N (including 0 = all cores) is- // honoured as-is below.- resolvedN := rawN- if !explicitN {- resolvedN = K- }- totalCores := inferenceTotalCores()- // Validate K and N against the process's CPU budget (cgroup-aware) and- // derive the per-Run intra-op thread count (max(1, N/K)). N == 0 resolves to- // all cores here.- coresPerInference, totalCPUCores, errV := native.ValidateInferenceConfig(totalCores, resolvedN, K)- if errV != nil {- common.Fatal("invalid deepdoc inference configuration", zap.Error(errV))- }- // Register the per-session intra-op thread count before any model session is- // created (the native package reads it on every SessionOptions build).- native.SetIntraOpThreads(coresPerInference)- pdf.SetDeepDocConcurrency(K)- native.SetInferenceLimit(K)- common.Info("in-process DeepDoc inference limit registered",- zap.Int("max_concurrent_inference", K),- zap.Int("cpu_cores_per_inference", coresPerInference),- zap.Int("total_cpu_cores_budget", totalCPUCores),- zap.Int("gomaxprocs", goruntime.GOMAXPROCS(0)))-- // 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 := server.GetConfig().GetIngestorPageConcurrency(arguments.ingestorPageConcurrency)- if err != nil {- return err- }- pdf.SetPageConcurrency(pageConcurrency)- common.Info("in-process DeepDoc page worker pool registered",- zap.Int("page_concurrency", pageConcurrency))- return nil-}--// logTokenizerCounters reports, once at startup, which embedding tokenizers this process-// can count with. An unavailable counter is not fatal here: the process still starts, and-// untagged models keep counting with the calibrated estimate by design. But the models that-// declare it cannot be ingested - the embedder refuses to substitute the calibrated count --// so this report is what tells an operator which asset to restore before documents fail.-func logTokenizerCounters() {- var available, unavailable []string- for _, status := range tokenizer.CounterStatuses() {- if status.Available {- available = append(available, status.ID)- continue- }- unavailable = append(unavailable, status.ID)- }- common.Info("embedding tokenizer counters", zap.Strings("available", available))- if len(unavailable) > 0 {- common.Warn("embedding tokenizers unavailable; models that declare them cannot be ingested until the asset is restored",- zap.Strings("unavailable", unavailable),- zap.String("hint", "run `uv run ragflow_deps/download_deps.py`, or set "+common.EnvModelAssetsDir+" to a directory holding them"))- }-}--// resolveDeepDocModelDir picks the model directory: the explicit DEEPDOC_MODEL_DIR-// env, else the RAGFlow default model dir (internal/rag/res/deepdoc),-// else the assets fetched by ragflow_deps/download_deps.py. The first-// candidate that actually contains the required weights wins.-func resolveDeepDocModelDir() string {- if v := strings.TrimSpace(common.GetEnv(common.EnvDeepDocModelDir)); v != "" {- return v- }- wd, _ := os.Getwd()- // MODEL_ASSETS_DIR first: the shared model-asset root keeps this layout too, so one- // variable can point at the DeepDoc weights as well as the embedding tokenizers.- candidates := append([]string(nil), common.ModelAssetCandidates("huggingface.co/InfiniFlow/deepdoc")...)- candidates = append(candidates,- filepath.Join(wd, "internal", "rag", "res", "deepdoc"),- filepath.Join(wd, "huggingface.co", "InfiniFlow", "deepdoc"),- )- for _, c := range candidates {- if dirHasModels(c) {- return c- }- }- // None verified; return the canonical default so any error message points- // at the conventional location.- return filepath.Join(wd, "internal", "rag", "res", "deepdoc")-}--// resolveDeepDocDropScore returns the explicit DEEPDOC_DROP_SCORE env, else the-// in-process backend's default (infnative.DefaultDropScore, which mirrors-// the Python inference service's Recognizer.drop_score).-func resolveDeepDocDropScore() float64 {- if v := strings.TrimSpace(common.GetEnv(common.EnvDeepDocDropScore)); v != "" {- if f, err := strconv.ParseFloat(v, 64); err == nil {- return f- }- common.Warn("invalid DEEPDOC_DROP_SCORE, using default",- zap.String("value", v), zap.Float64("default", infnative.DefaultDropScore))- }- return infnative.DefaultDropScore-}--// dirHasModels reports whether dir contains every required model file.-func dirHasModels(dir string) bool {- return common.HasModelFiles(dir)-}diff --git a/cmd/ragflow_server_deepdoc_test.go b/cmd/ragflow_server_deepdoc_test.goindex bf0f3637b1..5b96b1ebac 100644--- a/cmd/ragflow_server_deepdoc_test.go+++ b/cmd/ragflow_server_deepdoc_test.go@@ -18,7 +18,6 @@ package mainimport ("os"- goruntime "runtime""testing""github.com/spf13/viper"@@ -63,8 +62,8 @@ func TestParseArgsDeepDocInferenceConcurrency(t *testing.T) {if err != nil {t.Fatalf("parseArgs() error = %v, want nil for %v", err, tc.args)}- if got.deepdocInferenceConcurrency == nil || *got.deepdocInferenceConcurrency != tc.want {- t.Fatalf("deepdocInferenceConcurrency = %v, want %d for %v", got.deepdocInferenceConcurrency, tc.want, tc.args)+ if got.DeepdocInferenceConcurrency == nil || *got.DeepdocInferenceConcurrency != tc.want {+ t.Fatalf("deepdocInferenceConcurrency = %v, want %d for %v", got.DeepdocInferenceConcurrency, tc.want, tc.args)}})}@@ -106,8 +105,8 @@ func TestParseArgsIngestorMaxConcurrentWorkers(t *testing.T) {if err != nil {t.Fatalf("parseArgs() error = %v, want nil for %v", err, tc.args)}- if got.ingestorMaxConcurrentWorkers == nil || *got.ingestorMaxConcurrentWorkers != tc.want {- t.Fatalf("ingestorMaxConcurrentWorkers = %v, want %d for %v", got.ingestorMaxConcurrentWorkers, tc.want, tc.args)+ if got.IngestorMaxConcurrentWorkers == nil || *got.IngestorMaxConcurrentWorkers != tc.want {+ t.Fatalf("ingestorMaxConcurrentWorkers = %v, want %d for %v", got.IngestorMaxConcurrentWorkers, tc.want, tc.args)}})}@@ -146,8 +145,8 @@ func TestParseArgsDeepDocInferenceCPUCores(t *testing.T) {if err != nil {t.Fatalf("parseArgs() error = %v, want nil for %v", err, tc.args)}- if got.deepdocInferenceCPUCores == nil || *got.deepdocInferenceCPUCores != tc.want {- t.Fatalf("deepdocInferenceCPUCores = %v, want %d for %v", got.deepdocInferenceCPUCores, tc.want, tc.args)+ if got.DeepdocInferenceCPUCores == nil || *got.DeepdocInferenceCPUCores != tc.want {+ t.Fatalf("deepdocInferenceCPUCores = %v, want %d for %v", got.DeepdocInferenceCPUCores, tc.want, tc.args)}})}@@ -187,8 +186,8 @@ func TestParseArgsIngestorPageConcurrency(t *testing.T) {if err != nil {t.Fatalf("parseArgs() error = %v, want nil for %v", err, tc.args)}- if got.ingestorPageConcurrency == nil || *got.ingestorPageConcurrency != tc.want {- t.Fatalf("ingestorPageConcurrency = %v, want %d for %v", got.ingestorPageConcurrency, tc.want, tc.args)+ if got.IngestorPageConcurrency == nil || *got.IngestorPageConcurrency != tc.want {+ t.Fatalf("ingestorPageConcurrency = %v, want %d for %v", got.IngestorPageConcurrency, tc.want, tc.args)}})}@@ -250,22 +249,3 @@ func TestRegisterNativeDeepDocDefaultBootsOnSmallMachine(t *testing.T) {t.Fatalf("default config on %d-core host must validate, got: %v", totalCores, err)}}--// TestInferenceTotalCoresIsCgroupAware pins that the DeepDoc inference core-// budget passed to native.ValidateInferenceConfig is derived from-// runtime.GOMAXPROCS(0) (cgroup-quota aware in Go 1.25+) rather than-// runtime.NumCPU() (host affinity mask, which ignores a container's CPU limit).-// This keeps the fail-fast oversubscription guard effective under container CPU-// quotas: with NumCPU(), a 2-CPU-limit pod on a 64-core host would "resolve"-// inference_cpu_cores: 0 to 64 and let inference_concurrency: 16 pass validation,-// oversubscribing the box the check exists to prevent.-func TestInferenceTotalCoresIsCgroupAware(t *testing.T) {- got := inferenceTotalCores()- want := goruntime.GOMAXPROCS(0)- if got != want {- t.Fatalf("inferenceTotalCores() = %d, want runtime.GOMAXPROCS(0) = %d (cgroup-aware budget)", got, want)- }- if got < 1 {- t.Fatalf("inferenceTotalCores() = %d, want >= 1", got)- }-}diff --git a/cmd/ragflow_server_test.go b/cmd/ragflow_server_test.goindex 6ba870d4eb..9ab32512ba 100644--- a/cmd/ragflow_server_test.go+++ b/cmd/ragflow_server_test.go@@ -21,12 +21,13 @@ import ("os""os/exec""path/filepath"+ "ragflow/internal/server/bootstrap""strings""testing""time")-func parseArgsForTest(t *testing.T, argv ...string) (*serverArgs, error) {+func parseArgsForTest(t *testing.T, argv ...string) (*bootstrap.ServerArgs, error) {t.Helper()orig := os.Argsos.Args = append([]string{"ragflow_server"}, argv...)@@ -39,8 +40,8 @@ func TestParseArgsMigrateSelectsMode(t *testing.T) {if err != nil {t.Fatalf("parseArgs(--migrate) error = %v", err)}- if args.mode == nil || *args.mode != "migrate" {- t.Fatalf("mode = %v, want migrate", args.mode)+ if args.Mode == nil || *args.Mode != "migrate" {+ t.Fatalf("mode = %v, want migrate", args.Mode)}}@@ -51,7 +52,7 @@ func TestParseArgsLogLevel(t *testing.T) {if err != nil {t.Fatalf("parseArgs(%v) error = %v", argv, err)}- if got := selectedLogLevel(args, "info"); got != level {+ if got := bootstrap.SelectedLogLevel(args, "info"); got != level {t.Errorf("selectedLogLevel(%v) = %q, want %q", argv, got, level)}}@@ -69,10 +70,10 @@ func TestSelectedLogLevelPrecedence(t *testing.T) {if err != nil {t.Fatalf("parseArgs(--api) error = %v", err)}- if got := selectedLogLevel(args, ""); got != "info" {+ if got := bootstrap.SelectedLogLevel(args, ""); got != "info" {t.Errorf("default log level = %q, want info", got)}- if got := selectedLogLevel(args, "info"); got != "info" {+ if got := bootstrap.SelectedLogLevel(args, "info"); got != "info" {t.Errorf("configured log level = %q, want info", got)}@@ -80,7 +81,7 @@ func TestSelectedLogLevelPrecedence(t *testing.T) {if err != nil {t.Fatalf("parseArgs with --log-level error = %v", err)}- if got := selectedLogLevel(args, "info"); got != "error" {+ if got := bootstrap.SelectedLogLevel(args, "info"); got != "error" {t.Errorf("--log-level log level = %q, want error", got)}if _, err = parseArgsForTest(t, "--api", "--debug"); err == nil {@@ -103,16 +104,16 @@ func TestParseArgsMigrateFollowsLastModeWins(t *testing.T) {if err != nil {t.Fatalf("parseArgs(%s --migrate) error = %v", mode, err)}- if args.mode == nil || *args.mode != "migrate" {- t.Errorf("parseArgs(%s --migrate) mode = %v, want migrate", mode, args.mode)+ if args.Mode == nil || *args.Mode != "migrate" {+ t.Errorf("parseArgs(%s --migrate) mode = %v, want migrate", mode, args.Mode)}args, err = parseArgsForTest(t, "--migrate", mode)if err != nil {t.Fatalf("parseArgs(--migrate %s) error = %v", mode, err)}- if args.mode == nil || *args.mode != want {- t.Errorf("parseArgs(--migrate %s) mode = %v, want %s", mode, args.mode, want)+ if args.Mode == nil || *args.Mode != want {+ t.Errorf("parseArgs(--migrate %s) mode = %v, want %s", mode, args.Mode, want)}}}diff --git a/internal/server/admin/server.go b/internal/server/admin/server.gonew file mode 100644index 0000000000..720fb79506--- /dev/null+++ b/internal/server/admin/server.go@@ -0,0 +1,129 @@+//+// 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 admin wires and runs the RAGFlow admin HTTP server. It was extracted+// from package main so that main stays a thin dispatch layer.+package admin++import (+ "context"+ "errors"+ "fmt"+ "net/http"+ "time"++ "github.com/gin-gonic/gin"+ "go.uber.org/zap"++ adminapi "ragflow/internal/admin"+ "ragflow/internal/common"+ "ragflow/internal/server"+ "ragflow/internal/server/bootstrap"+)++// Run starts the RAGFlow admin HTTP server. It blocks until ctx is cancelled,+// then gracefully shuts the HTTP server down.+func Run(ctx context.Context, serverName string, args *bootstrap.ServerArgs) error {+ globalConfig := server.GetConfig()+ serverMode := globalConfig.GetMode()++ // Set Gin mode+ if serverMode == "debug" {+ gin.SetMode(gin.DebugMode)+ } else {+ gin.SetMode(gin.ReleaseMode)+ }++ adminService := adminapi.NewService()+ adminHandler := adminapi.NewHandler(adminService)++ if err := adminapi.InitLicense(); err != nil {+ common.Warn("Failed to initialize license", zap.Error(err))+ }++ if args.InitSuperUser {+ // Initialize default admin user+ if err := adminService.InitDefaultAdmin(); err != nil {+ common.Error("Failed to initialize default admin user", err)+ }+ }++ // Initialize router+ r := adminapi.NewRouter(adminHandler)++ // Create Gin engine+ ginEngine := gin.New()+ // Mirror Quart's merge_slashes: collapse duplicate slashes before routing.+ ginEngine.RemoveExtraSlash = true+ // Only honor X-Forwarded-For / X-Real-IP from the configured proxies+ // (default: the loopback nginx bundled in the image), never from every peer.+ if err := common.ConfigureTrustedProxies(ginEngine, globalConfig.GetAPIServerConfig().TrustedProxies); err != nil {+ common.Fatal("Failed to configure trusted proxies", zap.Error(err))+ }++ // Middleware+ ginEngine.Use(common.GinLogger())+ ginEngine.Use(gin.Recovery())++ // Setup routes+ r.Setup(ginEngine)++ adminConfig := globalConfig.GetAdminServerConfig()+ addr := fmt.Sprintf(":%d", adminConfig.HTTPPort)+ srv := &http.Server{+ Addr: addr,+ Handler: ginEngine,+ }+ // Print RAGFlow Admin logo+ common.Info("" ++ "\n ____ ___ ______________ ___ __ _ \n" ++ " / __ \\/ | / ____/ ____/ /___ _ __ / | ____/ /___ ___ (_)___ \n" ++ " / /_/ / /| |/ / __/ /_ / / __ \\ | /| / / / /| |/ __ / __ `__ \\/ / __ \\ \n" ++ " / _, _/ ___ / /_/ / __/ / / /_/ / |/ |/ / / ___ / /_/ / / / / / / / / / /\n" ++ " /_/ |_/_/ |_\\____/_/ /_/\\____/|__/|__/ /_/ |_\\__,_/_/ /_/ /_/_/_/ /_/ \n")++ // Print RAGFlow version+ common.Info(fmt.Sprintf("RAGFlow admin version: %s", common.GetRAGFlowVersion()))++ // Set log level+ bootstrap.SetLogger(serverName, args)++ // Start HTTP server in a goroutine+ go func() {+ common.Info(fmt.Sprintf("Starting RAGFlow admin HTTP server on port: %d", adminConfig.HTTPPort))+ if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {+ common.Fatal("Failed to start server", zap.Error(err))+ }+ }()++ // Wait for shutdown signal from main's signal.NotifyContext+ <-ctx.Done()++ common.Info("Received shutdown signal")+ common.Info("Shutting down RAGFlow HTTP server...")++ // Create context with timeout for graceful shutdown+ quitCtx, quitCancel := context.WithTimeout(context.Background(), 30*time.Second)+ defer quitCancel()++ // Shutdown HTTP server+ if err := srv.Shutdown(quitCtx); err != nil {+ common.Fatal("Server forced to shutdown", zap.Error(err))+ }++ common.Info("Admin HTTP server exited")+ return nil+}diff --git a/internal/server/api/server.go b/internal/server/api/server.gonew file mode 100644index 0000000000..fdfdf9e4fd--- /dev/null+++ b/internal/server/api/server.go@@ -0,0 +1,572 @@+//+// 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 api++import (+ "context"+ "errors"+ "fmt"+ "net"+ "net/http"+ _ "net/http/pprof"+ "ragflow/internal/agent/audio"+ "ragflow/internal/agent/canvas"+ "ragflow/internal/agent/retrievalbridge"+ "ragflow/internal/agent/runtime"+ agenttool "ragflow/internal/agent/tool"+ agentic_rag "ragflow/internal/agentic_rag"+ "ragflow/internal/channels"+ modelModule "ragflow/internal/entity/models"+ "ragflow/internal/handler"+ "ragflow/internal/router"+ "ragflow/internal/server/local"+ "ragflow/internal/service"+ "ragflow/internal/service/chunk"+ "ragflow/internal/service/dataset"+ "ragflow/internal/service/document"+ "ragflow/internal/service/file"+ "ragflow/internal/service/nav"+ "ragflow/internal/service/nlp"+ "ragflow/internal/service/wikisearch"+ "ragflow/internal/tokenizer"+ "strconv"+ "strings"+ "time"++ "github.com/gin-gonic/gin"+ "go.uber.org/zap"++ "ragflow/internal/agent/component"+ "ragflow/internal/common"+ "ragflow/internal/dao"+ "ragflow/internal/engine"+ "ragflow/internal/engine/kvrocks"+ _ "ragflow/internal/ingestion/wire"+ "ragflow/internal/server"+ "ragflow/internal/server/bootstrap"+)++func Run(ctx context.Context, serverName string, args *bootstrap.ServerArgs) error {+ // Initialize admin status (default: unavailable=1)+ local.InitAdminStatus(1, "admin server not connected")++ // Initialize tokenizer (rag_analyzer)+ // tokenizer.Init fills DictPath from env var or default, so+ // tokenizerCfg.DictPath carries the resolved path for downstream use.+ tokenizerCfg := &tokenizer.PoolConfig{}+ if err := tokenizer.Init(tokenizerCfg); err != nil {+ common.Fatal("Failed to initialize tokenizer", zap.Error(err))+ }+ defer tokenizer.Close()++ // Fail fast if the cl100k_base BPE table is missing. NumTokensFromString /+ // TrimContentToTokenLimit now panic rather than degrading silently, so this+ // trades a mid-request panic for a clear startup failure.+ if err := tokenizer.InitCL100KEncoder(); err != nil {+ common.Fatal("Failed to initialize cl100k_base tokenizer", zap.Error(err))+ }++ // Initialize global QueryBuilder using tokenizer's DictPath+ // This ensures the Synonym uses the same wordnet directory as tokenizer+ if err := nlp.InitQueryBuilderFromTokenizer(tokenizerCfg.DictPath); err != nil {+ common.Fatal("Failed to initialize query builder", zap.Error(err))+ }++ if err := startServer(ctx, serverName, args); err != nil {+ return err+ }++ common.Info("Server exited")++ return nil+}++func startServer(ctx context.Context, serverName string, arguments *bootstrap.ServerArgs) error {++ globalConfig := server.GetConfig()+ serverMode := globalConfig.GetMode()+ // Set Gin mode+ if serverMode == "debug" {+ gin.SetMode(gin.DebugMode)+ } else {+ gin.SetMode(gin.ReleaseMode)+ }++ // Initialize service layer+ userService := service.NewUserService()+ documentService := document.NewDocumentService()+ datasetsService := dataset.NewDatasetService()+ metadataService := service.NewMetadataService()+ chunkService := chunk.NewChunkService()+ tenantService := service.NewTenantService()+ chatService := service.NewChatService()+ chatChannelService := service.NewChatChannelService()+ langfuseService := service.NewLangfuseService()+ chatSessionService := service.NewChatSessionService()+ openaiChatService := service.NewOpenAIChatService()+ systemService := service.NewSystemService()+ statsService := service.NewStatsService()+ connectorService := service.NewConnectorService()+ searchService := service.NewSearchService()+ searchService.SetTenantService(tenantService)+ fileService := file.NewFileService(documentService)+ memoryService := service.NewMemoryService()+ mcpService := service.NewMCPService()+ modelProviderService := service.NewModelProviderService()+ modelFactory := service.NewModelFactory()+ modelCallService := service.NewModelCallServiceWithProviderService(modelProviderService, modelFactory)++ // Wire the real MemorySaver so the Message component can persist+ // conversation turns to memory stores declared in the canvas DSL.+ component.SetMemorySaver(service.NewMemorySaverAdapter(memoryService))++ // Initialize doc engine for skill search+ docEngine := engine.Get()+ documentDAO := dao.NewDocumentDAO()+ retrievalEnhancer := retrievalbridge.NewEnhancer(docEngine, metadataService)+ // Keep the concrete adapter: it is both the canvas/agent-tool backend and the+ // target of the agentic-RAG bridge wired below. The bridge must hold it+ // directly (not look it up in the registry) because the registry is shared —+ // agenttool.SetRetrievalService and runtime.SetRetrievalService write the same+ // singleton, so a bridge that resolved its target per call would find itself.+ retrievalAdapter := agenttool.NewNLPRetrievalAdapterFromDeps(+ docEngine,+ documentDAO,+ agenttool.RetrievalModelConstructors{+ Embedding: func(ctx context.Context, tenantID, modelRef string) (*modelModule.EmbeddingModel, error) {+ access := service.ModelAccess{TenantID: tenantID}+ if strings.TrimSpace(modelRef) == "" {+ return modelFactory.NewDefaultEmbeddingModel(ctx, access)+ }+ return modelFactory.NewEmbeddingModel(ctx, access, modelRef)+ },+ Chat: func(ctx context.Context, tenantID, modelRef string) (*modelModule.ChatModel, error) {+ access := service.ModelAccess{TenantID: tenantID}+ if strings.TrimSpace(modelRef) == "" {+ return modelFactory.NewDefaultChatModel(ctx, access)+ }+ return modelFactory.NewChatModel(ctx, access, modelRef)+ },+ Rerank: func(ctx context.Context, tenantID, modelRef string) (*modelModule.RerankModel, error) {+ return modelFactory.NewRerankModel(ctx, service.ModelAccess{TenantID: tenantID}, modelRef)+ },+ },+ retrievalEnhancer,+ )+ agenttool.SetRetrievalService(retrievalAdapter)+ agenttool.SetMemoryRetrievalService(retrievalbridge.NewMemoryAdapter(memoryService, retrievalEnhancer))+ common.Info("agent: retrieval service adapter installed")++ // The smart-reasoning agent's corpus tools (internal/agentic_rag): regex+ // pushdown and lexical BM25 over the same doc engine the retrieval adapter+ // wraps. The locate tools resolve these services per call, so they must be+ // registered before the server starts serving.+ runtime.SetGrepService(agentic_rag.NewGrepAdapter(docEngine))+ bm25Adapter := agentic_rag.NewBm25Adapter(docEngine)+ bm25Adapter.SetQueryBuilder(nlp.GetQueryBuilder())+ runtime.SetBm25Service(bm25Adapter)+ common.Info("agent: smart-reasoning corpus services installed (grep + bm25)")++ // The compiled-knowledge graph walk (graph_explore) resolves its service per+ // call the same way. Without this registration GetKgService() returns the+ // failing stub, so the tool could only ever report an infrastructure error.+ // The seed encoder is left unset: the walk then seeds by keyword match on the+ // entity rows, the documented fallback on a deployment without an embedder.+ agentic_rag.SetKgService(agentic_rag.NewKgAdapter(docEngine))+ common.Info("agent: smart-reasoning compiled-knowledge graph service installed")+ // The smart-reasoning agent's corpus tools resolve the shared retrieval+ // service per call, so the production adapter must be registered before the+ // server starts serving.+ runtime.SetRetrievalService(retrievalbridge.NewRuntimeAdapter(retrievalAdapter))+ common.Info("agent: runtime retrieval service wired")++ // Initialize handler layer+ authHandler := handler.NewAuthHandler()+ userHandler := handler.NewUserHandler(userService)+ tenantHandler := handler.NewTenantHandler(tenantService, userService, datasetsService)+ documentHandler := handler.NewDocumentHandler(documentService, datasetsService, fileService)+ datasetsHandler := handler.NewDatasetsHandler(datasetsService, metadataService)+ systemHandler := handler.NewSystemHandler(systemService)+ statsHandler := handler.NewStatsHandler(statsService)+ chunkHandler := handler.NewChunkHandler(chunkService, userService)+ chatHandler := handler.NewChatHandler(chatService, userService)+ chatChannelHandler := handler.NewChatChannelHandler(chatChannelService)+ langfuseHandler := handler.NewLangfuseHandler(langfuseService)+ chatSessionHandler := handler.NewChatSessionHandler(chatSessionService, userService)+ openaiChatHandler := handler.NewOpenAIChatHandler(openaiChatService)+ connectorHandler := handler.NewConnectorHandler(connectorService, userService)+ searchHandler := handler.NewSearchHandler(searchService, userService)+ fileHandler := handler.NewFileHandler(fileService, userService)+ memoryHandler := handler.NewMemoryHandler(memoryService)+ mcpHandler := handler.NewMCPHandler(mcpService)++ // MCP server endpoint — exposes RAGFlow capabilities as MCP tools+ // (ragflow_retrieval, ragflow_list_datasets, ragflow_list_chats) to+ // external AI clients via JSON-RPC over HTTP.+ mcpServerHandler := handler.NewMCPServerHandler(datasetsService, chatService)+ skillSearchHandler := handler.NewSkillSearchHandler(docEngine, documentService)+ providerHandler := handler.NewProviderHandler(userService, modelProviderService, modelCallService)+ // Install the agent service's Kvrocks-backed run infrastructure+ // (CheckPointStore / StateSerializer / RunTracker). When Redis+ // is unreachable (degraded boot, stand-alone mode, no-redis CI)+ // the constructors return errors, and we fall through to the+ // in-memory / no-tracking path: the agent service treats nil+ // options as the in-memory test path, so graceful degradation+ // is a 1-line if-not-nil pass-through — no separate "boot" mode+ // required.+ agentOpts := buildAgentRunOptions()+ agentService := service.NewAgentServiceWithOptions(+ agentOpts.checkpointStore,+ agentOpts.stateSerializer,+ agentOpts.runTracker,+ )+ agentHandler := handler.NewAgentHandler(ctx, agentService, fileService)++ // Public chatbot/agentbot endpoints (api/v1/chatbots/...,+ // api/v1/agentbots/...) and the agent attachment download.+ // BotService delegates the agentBot completion to agentService so+ // both paths share the same canvas runner.+ botService := service.NewBotService(agentService)+ botHandler := handler.NewBotHandler(botService)++ // Wire the TTS synthesizer to the per-tenant model-provider+ // dispatch. SynthesizeRequest is routed through+ // ModelProviderService.AudioSpeech, which fans out to the+ // tenant's configured TTS model driver. When the model+ // provider is unconfigured, the synthesizer falls back to a+ // no-op echo (the audio package contract), so this is always+ // safe to call.+ configureTTSSynthesizer(modelCallService)+ searchBotHandler := handler.NewSearchBotHandler(+ searchService,+ tenantService,+ modelFactory,+ chunkService,+ )+ askService := service.NewAskService(chunkService, nil, 0, 0)+ searchBotHandler.SetAskService(askService)+ chatHandler.SetMindMapDependencies(searchService, tenantService, modelFactory, chunkService)+ searchHandler.SetCompletionDependencies(modelFactory, askService)+ pluginHandler := handler.NewPluginHandler(service.NewPluginService())+ modelHandler := handler.NewModelHandler(service.NewModelProviderService())+ fileCommitHandler := handler.NewFileCommitHandler(file.NewFileCommitService())++ // Dify retrieval handler+ retrievalService := nlp.NewRetrievalService(docEngine, documentDAO)+ difyRetrievalHandler := handler.NewDifyRetrievalHandler(+ datasetsService,+ modelFactory,+ metadataService,+ retrievalService,+ documentDAO,+ docEngine,+ )+ componentsSvc := service.NewComponentsService()+ componentsHandler := handler.NewComponentsHandler(componentsSvc)+ pipelineHandler := handler.NewPipelineHandler()+ compilationTemplateHandler := handler.NewCompilationTemplateHandler(service.NewCompilationTemplateService())+ compilationTemplateGroupHandler := handler.NewCompilationTemplateGroupHandler(service.NewCompilationTemplateGroupService())+ datasetArtifactHandler := handler.NewDatasetArtifactHandler(service.NewDatasetArtifactService(), datasetsService, file.NewFileCommitService())++ // Install the production eino-based chat invoker as the shared chat default,+ // so agentic-search runtime LLM calls work in production. Without this,+ // chat.GetDefaultInvoker() stays nil and the runtime falls back gracefully.+ component.InstallDefaultChatInvoker()++ // Install the dataset-nav ES-backed service (internal/service/nav ++ // internal/service/nlp). The embedder resolves the tenant's embedding model+ // on demand so Search/UpsertDoc can embed queries/summaries automatically,+ // and the cluster namer/merger resolves the tenant's default chat model the+ // same way (see the ingestor's wrapping of SetNavMergeLLM).+ apiNavService := nlp.NewNavService(service.NewNavEmbedder(modelFactory, ""))+ apiNavService.SetNavMergeLLM(service.NewNavMergeLLM(modelFactory, ""))+ nav.SetNavService(apiNavService)++ // Install the compiled-wiki search service. It is backed directly by the+ // document engine: QueryPages filters the tenant-scoped index to+ // compile_kwd="wiki_page" (+ supported kinds) so ordinary source chunks are+ // never relabeled as wiki pages, and BackfillChunks fetches original chunks+ // by id. When the engine is unavailable the service degrades to empty so the+ // agent falls back to hybrid search (no failing call).+ wikisearch.SetService(wikisearch.NewEngineService(engine.Get()))++ // Initialize router+ r := router.NewRouter(authHandler,+ userHandler,+ tenantHandler,+ documentHandler,+ datasetsHandler,+ systemHandler,+ statsHandler,+ chunkHandler,+ chatHandler,+ chatChannelHandler,+ langfuseHandler,+ chatSessionHandler,+ connectorHandler,+ searchHandler,+ fileHandler,+ memoryHandler,+ mcpHandler,+ mcpServerHandler,+ skillSearchHandler,+ providerHandler,+ agentHandler,+ searchBotHandler,+ difyRetrievalHandler,+ pluginHandler,+ modelHandler,+ fileCommitHandler,+ openaiChatHandler,+ botHandler,+ componentsHandler,+ pipelineHandler,+ compilationTemplateHandler,+ compilationTemplateGroupHandler,+ datasetArtifactHandler)++ // Create Gin engine+ ginEngine := gin.New()+ // Mirror Quart's merge_slashes: collapse duplicate slashes before routing.+ ginEngine.RemoveExtraSlash = true+ // Only honor X-Forwarded-For / X-Real-IP from the configured proxies+ // (default: the loopback nginx bundled in the image), never from every+ // peer. c.ClientIP() feeds the agent webhook ip_whitelist gate and the+ // login audit records, so gin's trust-everything default would let any+ // caller pick its own address.+ if err := common.ConfigureTrustedProxies(ginEngine, globalConfig.GetAPIServerConfig().TrustedProxies); err != nil {+ common.Fatal("Failed to configure trusted proxies", zap.Error(err))+ }++ // Middleware+ // Note: common.GinLogger() is registered inside router.Setup so the+ // HTTP request log captures every endpoint the router owns (including+ // those registered by Setup itself). Registering it here would run+ // it twice for those endpoints and double every access-log line.+ ginEngine.Use(gin.Recovery())++ // Setup routes+ r.Setup(ginEngine)++ _, err := channels.Start(ctx)+ if err != nil {+ return fmt.Errorf("start chat-channel: %w", err)+ }++ apiServerConfig := globalConfig.GetAPIServerConfig()++ // Create HTTP server with timeouts to prevent slow clients from blocking shutdown+ addr := fmt.Sprintf(":%d", apiServerConfig.HTTPPort)+ srv := &http.Server{+ Addr: addr,+ Handler: ginEngine,+ BaseContext: func(net.Listener) context.Context { return ctx },+ ReadHeaderTimeout: 10 * time.Second,+ ReadTimeout: 60 * time.Second,+ // WriteTimeout spans "request header read → response written", so it is a+ // ceiling on the WHOLE request, not on a slow client's reads. Measured+ // (2026-09-15, FRAMES 20q): three multi-hop questions take 150–225s to reach+ // their response, and at 120s the server closed the connection with no+ // response at all — the client reports+ // `RemoteDisconnected('Remote end closed connection without response')` and+ // the benchmark re-runs the whole question (max_retries: 2), so one slow+ // question cost three full pipelines. 180s clears the measured distribution's+ // middle; questions whose composition alone runs past it still need streaming+ // or a larger budget.+ WriteTimeout: 180 * time.Second,+ IdleTimeout: 120 * time.Second,+ }+ apiListener, err := net.Listen("tcp", addr)+ if err != nil {+ return fmt.Errorf("listen API server on %s: %w", addr, err)+ }+ defer apiListener.Close()++ serveErr := make(chan error, 2)+ serve := func(name string, srv *http.Server, listener net.Listener) {+ if err := srv.Serve(listener); err != nil && !errors.Is(err, http.ErrServerClosed) {+ serveErr <- fmt.Errorf("%s server failed: %w", name, err)+ }+ }++ var mcpSrv *http.Server+ var mcpCloser interface{ Close() error }+ var mcpListener net.Listener+ mcpConfig := apiServerConfig.MCP+ if mcpConfig.Enabled {+ mcpHandler, err := mcpServerHandler.NewStandalone(ctx, authHandler, mcpConfig)+ if err != nil {+ return err+ }++ mcpCloser = mcpHandler+ defer mcpHandler.Close()+ mcpAddr := net.JoinHostPort(strings.Trim(mcpConfig.Host, "[]"), strconv.Itoa(mcpConfig.Port))+ mcpListener, err = net.Listen("tcp", mcpAddr)+ if err != nil {+ return fmt.Errorf("listen MCP server on %s: %w", mcpAddr, err)+ }+ defer mcpListener.Close()+ mcpSrv = &http.Server{+ Addr: mcpAddr,+ Handler: mcpHandler,+ BaseContext: func(net.Listener) context.Context { return ctx },+ ReadHeaderTimeout: 10 * time.Second,+ ReadTimeout: 60 * time.Second,+ WriteTimeout: 0, // SSE streams outlive individual tool deadlines+ IdleTimeout: 120 * time.Second,+ }+ go func() {+ common.Info(fmt.Sprintf("MCP server starting on %s", mcpSrv.Addr))+ serve("MCP", mcpSrv, mcpListener)+ }()+ }++ common.Info(+ "\n ____ ___ ______ ______ __\n" ++ " / __ \\ / | / ____// ____// /____ _ __\n" ++ " / /_/ // /| | / / __ / /_ / // __ \\| | /| / /\n" ++ " / _, _// ___ |/ /_/ // __/ / // /_/ /| |/ |/ /\n" ++ " /_/ |_|/_/ |_|\\____//_/ /_/ \\____/ |__/|__/\n",+ )+ common.Info(fmt.Sprintf("RAGFlow Go Version: %s", common.GetRAGFlowVersion()))+ common.Info(fmt.Sprintf("Server starting on port: %d", apiServerConfig.HTTPPort))++ // Set log level+ bootstrap.SetLogger(serverName, arguments)++ // Start server in a goroutine+ go func() {+ serve(serverName, srv, apiListener)+ }()++ // Start heartbeat reporter to admin server+ if hb := bootstrap.StartHeartbeat(+ common.ServerTypeAPI,+ fmt.Sprintf("ragflow-server-%s", common.GenerateUUID()[:8]),+ apiServerConfig.HTTPPort,+ globalConfig.GetHeartbeatInterval(),+ ); hb != nil {+ defer hb.Stop()+ }++ // Wait for either shutdown signal or serving failure.+ var runErr error+ select {+ case <-ctx.Done():+ common.Info("Received shutdown signal")+ case err := <-serveErr:+ runErr = err+ common.Error("Server failed; shutting down", err)+ }+ common.Info("Shutting down server...")++ shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 30*time.Second)+ defer shutdownCancel()++ if mcpCloser != nil {+ if err = mcpCloser.Close(); err != nil {+ common.Warn("Failed to close MCP handler", zap.Error(err))+ }+ }+ if err = shutdownHTTPServer(shutdownCtx, "API", srv); err != nil {+ return err+ }+ if mcpSrv != nil {+ if err = shutdownHTTPServer(shutdownCtx, "MCP", mcpSrv); err != nil {+ return err+ }+ }+ return runErr+}++func shutdownHTTPServer(ctx context.Context, name string, srv *http.Server) error {+ if err := srv.Shutdown(ctx); err != nil {+ _ = srv.Close()+ return fmt.Errorf("shutdown %s server: %w", name, err)+ }+ return nil+}++// agentRunOptions bundles the three optional injection slots the+// agent service accepts via NewAgentServiceWithOptions: the Redis-+// backed CheckPointStore, StateSerializer, and RunTracker. The+// fields stay nil when the underlying constructors fail (Redis+// unreachable, etc.); the agent service treats nil as "in-memory+// / no-tracking" so the server continues to serve traffic without+// requiring Redis to be up.+type agentRunOptions struct {+ checkpointStore canvas.CheckPointStore+ stateSerializer canvas.StateSerializer+ runTracker *canvas.RunTracker+}++// buildAgentRunOptions installs the Kvrocks-backed run infrastructure+// when Redis is available. The Redis client is the one already+// initialized at the top of main; the TTL is a conservative 24h for+// both the checkpoint store and the run tracker. On any error+// (Redis down at boot, constructor panic, nil-Redis fallback) we+// log and return a zero-value struct — the agent service falls back+// to the in-memory path transparently.+func buildAgentRunOptions() agentRunOptions {+ var out agentRunOptions+ if !kvrocks.IsEnabled() || kvrocks.Get() == nil {+ common.Info("agent: redis client not initialised; agent run infra in in-memory mode (no checkpoints, no run tracker)")+ return out+ }+ cp := canvas.NewKvrocksCheckPointStore(24 * time.Hour)+ out.checkpointStore = cp+ // stateSerializer is intentionally left nil. eino's default+ // InternalSerializer (used when no compose.WithSerializer is+ // passed at compile time) already knows how to round-trip+ // runtime.CanvasState because the runtime package registers+ // it via compose.RegisterSerializableType[CanvasState] in+ // init(). Overriding with RAGFlow's plain-JSON+ // CanvasStateSerializer (json.Marshal/Unmarshal) produces+ // bytes the InternalSerializer cannot decode on the resume+ // pass — the UserFillUp two-node pattern surfaces this as+ // "load checkpoint from store fail: cannot unmarshal object+ // into Go struct field checkpoint.Channels of type+ // compose.channel". Rely on eino's default instead.+ rt := canvas.NewRunTracker(24 * time.Hour)+ out.runTracker = rt+ common.Info("agent: redis-backed run infra installed (24h TTL on checkpoint store + run tracker; eino default serializer)")+ return out+}++// configureTTSSynthesizer installs the audio.ModelProviderFunc+// that dispatches Synthesize requests through the project's+// ModelProviderService. The model provider's AudioSpeech method+// (internal/service/model_service.go) resolves the per-tenant TTS+// model driver, sends the request upstream, and returns+// synthesized audio bytes.+//+// The audio package's NewTTSDispatchFunc helper converts the+// audio.SynthesizeRequest shape into the model's dispatch shape+// (audioContent = req.Text, voice/lang → TTSConfig.Params,+// ModelName from req.Engine). When the model provider is+// unconfigured (nil dispatcher) the helper returns nil, which+// reverts the audio package to its default stub.+func configureTTSSynthesizer(modelCallService *service.ModelCallService) {+ if modelCallService == nil {+ common.Info("agent: model call service not initialised; TTS in no-op echo mode")+ audio.SetModelProviderSynthesizer(nil)+ return+ }+ audio.SetModelProviderSynthesizer(audio.NewTTSDispatchFunc(modelCallService))+ common.Info("agent: TTS model-call dispatch installed (audio.Synthesize → ModelCallService.AudioSpeech)")+}diff --git a/internal/server/bootstrap/args.go b/internal/server/bootstrap/args.gonew file mode 100644index 0000000000..869515772f--- /dev/null+++ b/internal/server/bootstrap/args.go@@ -0,0 +1,62 @@+//+// 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 bootstrap++// ServerArgs holds the parsed command-line arguments shared by every server+// mode. It lives in this package (rather than package main) so the mode+// runners and the API server wiring can be moved into their own packages and+// still receive the parsed arguments.+type ServerArgs struct {+ Mode *string // admin | api | ingestor | syncer | deepdoc | migrate+ HelpFlag bool+ VersionFlag bool+ LogLevel *string+ ConfigPath *string // Used by admin, api; user defined config path+ InitSuperUser bool // Used by admin;+ Port *int // Used by admin, api+ AdminHost *string // Used by api, ingestor, syncer, deepdoc for heartbeat+ AdminPort *int // Used by api, ingestor, syncer, deepdoc for heartbeat, "ip:port"+ Name *string // server name+ EnablePProf bool // enable pprof++ // DeepdocInferenceConcurrency, when set, overrides the DeepDoc inference+ // concurrency from env/config. nil means "unspecified".+ DeepdocInferenceConcurrency *int+ // IngestorMaxConcurrentWorkers, when set, overrides the ingestor worker+ // count (NATS consumer count K) from env/config. nil means "unspecified".+ IngestorMaxConcurrentWorkers *int+ // IngestorPageConcurrency, when set, overrides the per-document page+ // concurrency (N) from env/config. nil means "unspecified".+ IngestorPageConcurrency *int+ // DeepdocInferenceCPUCores, when set, overrides the DeepDoc inference CPU-core+ // budget from env/config. nil means "unspecified" (0 means "all cores").+ DeepdocInferenceCPUCores *int+}++// SelectedLogLevel resolves the effective log level: an explicit --log-level+// (non-nil) wins, otherwise the configured level, otherwise "info".+func SelectedLogLevel(args *ServerArgs, configured string) string {+ if args.LogLevel != nil {+ return *args.LogLevel+ }++ if configured == "" {+ return "info"+ }++ return configured+}diff --git a/internal/server/bootstrap/bootstrap.go b/internal/server/bootstrap/bootstrap.gonew file mode 100644index 0000000000..59ba902f1e--- /dev/null+++ b/internal/server/bootstrap/bootstrap.go@@ -0,0 +1,72 @@+//+// 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 bootstrap holds the pure, side-effect-free helpers that the server+// entrypoint uses to derive its identity before the mode-specific runners take+// over. Keeping them here lets cmd/ragflow_server.go stay a thin dispatcher and+// makes the naming rules unit-testable without booting any subsystem.+package bootstrap++import "fmt"++// TempServerName returns the placeholder server name used for the temporary,+// stdout-only logger that exists before the configuration is loaded. An+// explicit --name (non-nil pointer) wins; otherwise the name is+// "<mode>_server".+//+// This is intentionally distinct from ResolveServerName: the final name for+// api/admin additionally embeds the resolved HTTP port, which is only known+// after the configuration is initialized.+func TempServerName(mode string, nameFlag *string) string {+ if nameFlag != nil {+ return *nameFlag+ }+ return mode + "_server"+}++// ResolveServerName derives the final server name for a mode, preserving the+// precedence and per-mode rules that cmd/ragflow_server.go previously inlined:+//+// - An explicit --name (non-nil pointer, including an empty string) always+// wins.+// - api/admin embed the resolved HTTP port: "<mode>_server_<port>".+// - ingestor/syncer/deepdoc fall back to the "<mode>_server" placeholder+// (the port is not part of their name).+// - migrate uses the fixed literal "migrate".+//+// An unrecognized mode is a hard error, independent of whether a name was+// supplied.+func ResolveServerName(mode string, nameFlag *string, port int) (string, error) {+ switch mode {+ case "api", "admin":+ if nameFlag != nil {+ return *nameFlag, nil+ }+ return fmt.Sprintf("%s_server_%d", mode, port), nil+ case "ingestor", "syncer", "deepdoc":+ if nameFlag != nil {+ return *nameFlag, nil+ }+ return mode + "_server", nil+ case "migrate":+ if nameFlag != nil {+ return *nameFlag, nil+ }+ return "migrate", nil+ default:+ return "", fmt.Errorf("unsupported server mode %q", mode)+ }+}diff --git a/internal/server/bootstrap/bootstrap_test.go b/internal/server/bootstrap/bootstrap_test.gonew file mode 100644index 0000000000..5dee46a838--- /dev/null+++ b/internal/server/bootstrap/bootstrap_test.go@@ -0,0 +1,153 @@+//+// 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 bootstrap++import (+ "strings"+ "testing"+)++func strPtr(s string) *string { return &s }++// TestResolveServerNameDefaults pins the no-name default for every known mode.+// api/admin embed the port; ingestor/syncer/deepdoc use the pre-config+// "<mode>_server" placeholder (port is NOT part of the name); migrate is a+// fixed literal.+func TestResolveServerNameDefaults(t *testing.T) {+ tests := []struct {+ mode string+ port int+ want string+ }{+ {"api", 9380, "api_server_9380"},+ {"api", 0, "api_server_0"},+ {"admin", 9381, "admin_server_9381"},+ {"ingestor", 0, "ingestor_server"},+ {"syncer", 0, "syncer_server"},+ {"deepdoc", 0, "deepdoc_server"},+ {"migrate", 0, "migrate"},+ }+ for _, tc := range tests {+ got, err := ResolveServerName(tc.mode, nil, tc.port)+ if err != nil {+ t.Errorf("ResolveServerName(%q, nil, %d) error = %v", tc.mode, tc.port, err)+ continue+ }+ if got != tc.want {+ t.Errorf("ResolveServerName(%q, nil, %d) = %q, want %q", tc.mode, tc.port, got, tc.want)+ }+ }+}++// TestResolveServerNamePortIgnoredForNonHTTPModes verifies the port argument+// only affects api/admin; it must not leak into ingestor/syncer/deepdoc/migrate+// names.+func TestResolveServerNamePortIgnoredForNonHTTPModes(t *testing.T) {+ for _, mode := range []string{"ingestor", "syncer", "deepdoc", "migrate"} {+ got, err := ResolveServerName(mode, nil, 65535)+ if err != nil {+ t.Fatalf("ResolveServerName(%q, nil, 65535) error = %v", mode, err)+ }+ if got == "api_server_65535" || got == "admin_server_65535" {+ t.Errorf("mode %q unexpectedly embedded the port: %q", mode, got)+ }+ }+}++// TestResolveServerNameNameOverrideWins verifies an explicit --name overrides+// the derived default for every known mode.+func TestResolveServerNameNameOverrideWins(t *testing.T) {+ for _, mode := range []string{"api", "admin", "ingestor", "syncer", "deepdoc", "migrate"} {+ got, err := ResolveServerName(mode, strPtr("custom_name"), 1234)+ if err != nil {+ t.Fatalf("ResolveServerName(%q, name, 1234) error = %v", mode, err)+ }+ if got != "custom_name" {+ t.Errorf("ResolveServerName(%q, name) = %q, want custom_name", mode, got)+ }+ }+}++// TestResolveServerNameEmptyNameOverride: an explicit empty --name (pointer to+// "") must be honored as an empty name, not fall through to the default. This+// mirrors the original precedence where a non-nil pointer always wins.+func TestResolveServerNameEmptyNameOverride(t *testing.T) {+ got, err := ResolveServerName("api", strPtr(""), 9380)+ if err != nil {+ t.Fatalf("error = %v", err)+ }+ if got != "" {+ t.Errorf("ResolveServerName(api, \"\") = %q, want empty", got)+ }+}++// TestResolveServerNameUnknownModeErrors verifies an unrecognized mode is a hard+// error regardless of whether a name was supplied (matching the original+// default branch, which always exits).+func TestResolveServerNameUnknownModeErrors(t *testing.T) {+ for _, name := range []*string{nil, strPtr("whatever")} {+ got, err := ResolveServerName("bogus", name, 0)+ if err == nil {+ t.Errorf("ResolveServerName(bogus, %v) error = nil, want error (got %q)", name, got)+ }+ }+ // Empty mode is also invalid.+ if _, err := ResolveServerName("", nil, 0); err == nil {+ t.Error("ResolveServerName(\"\") error = nil, want error")+ }+}++// TestResolveServerNameWorkerModesStableNoUUID guards the contract that+// ingestor/syncer/deepdoc without --name resolve to the stable "<mode>_server"+// literal. The historical code had a UUID branch keyed on `if serverName == ""`+// that was dead (the name was already pre-filled), so those servers must never+// get a per-boot UUID suffix in their log filename. This test fails (and must+// stay failing) if anyone reintroduces UUID generation for these modes.+func TestResolveServerNameWorkerModesStableNoUUID(t *testing.T) {+ for _, mode := range []string{"ingestor", "syncer", "deepdoc"} {+ got, err := ResolveServerName(mode, nil, 0)+ if err != nil {+ t.Fatalf("ResolveServerName(%q, nil, 0) error = %v", mode, err)+ }+ want := mode + "_server"+ if got != want {+ t.Errorf("ResolveServerName(%q, nil, 0) = %q, want stable literal %q", mode, got, want)+ }+ // A UUID suffix looks like a 8-4-4-4-12 hex run; assert it is absent.+ if strings.Contains(got, "-") {+ t.Errorf("ResolveServerName(%q, nil, 0) = %q contains '-' (UUID suffix leaked into worker server name)", mode, got)+ }+ }+}++// TestTempServerName verifies the pre-config placeholder used for the temporary+// stdout logger: explicit name wins, otherwise "<mode>_server".+func TestTempServerName(t *testing.T) {+ if got := TempServerName("api", strPtr("named")); got != "named" {+ t.Errorf("TempServerName(api, named) = %q, want named", got)+ }+ for _, mode := range []string{"api", "admin", "ingestor", "syncer", "deepdoc", "migrate"} {+ got := TempServerName(mode, nil)+ if want := mode + "_server"; got != want {+ t.Errorf("TempServerName(%q, nil) = %q, want %q", mode, got, want)+ }+ }+ // Empty-name override is honored as empty (non-nil pointer wins).+ if got := TempServerName("api", strPtr("")); got != "" {+ t.Errorf("TempServerName(api, \"\") = %q, want empty", got)+ }+}diff --git a/internal/server/bootstrap/runtime.go b/internal/server/bootstrap/runtime.gonew file mode 100644index 0000000000..4cd6e6611e--- /dev/null+++ b/internal/server/bootstrap/runtime.go@@ -0,0 +1,92 @@+//+// 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 bootstrap++import (+ "fmt"+ "time"++ "go.uber.org/zap"++ "ragflow/internal/common"+ "ragflow/internal/server"+ "ragflow/internal/server/local"+ "ragflow/internal/service"+ "ragflow/internal/utility"+)++// SetLogger (re)initializes the process logger for the given server name using+// the configured log settings plus any CLI overrides carried by args. It was+// previously a private helper in package main; it lives here so the per-mode+// runners (now in their own packages) can call it without reaching into main.+func SetLogger(serverName string, arguments *ServerArgs) {+ // 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)++ fileOut := common.FileOutput{+ Filename: logFileName,+ Path: logConfig.Path,+ MaxSize: logConfig.MaxSize,+ MaxBackups: logConfig.MaxBackups,+ MaxAge: logConfig.MaxAge,+ Compress: logConfig.Compress,+ }++ common.SyncLog()+ if err := common.InitLogger(logLevel, fileOut, serverName); err != nil {+ common.Error("Failed to reinitialize logger with configured level", err)+ }+}++// StartHeartbeat initializes and starts the heartbeat reporter to the admin+// server. It is shared by the API, ingestor, and syncer server modes. The+// caller must defer the returned *utility.ScheduledTask's Stop() method.+func StartHeartbeat(serverType common.ServerType, serverID string, port int, heartBeatInterval time.Duration) *utility.ScheduledTask {+ localIP, err := utility.GetLocalIP()+ if err != nil {+ common.Fatal("fail to get local ip address")+ }++ service.AdminServiceClient = service.NewAdminClient(+ serverType,+ serverID,+ localIP,+ port,+ )+ if err = service.AdminServiceClient.InitHTTPClient(); err != nil {+ common.Warn("Failed to initialize heartbeat service", zap.Error(err))+ return nil+ }++ heartbeatReporter := utility.NewScheduledTask("Heartbeat reporter", heartBeatInterval, func() {+ if err = service.AdminServiceClient.SendHeartbeat(); err == nil {+ local.SetAdminStatus(0, "")+ } else {+ local.SetAdminStatus(1, err.Error())+ }+ })+ heartbeatReporter.Start()+ return heartbeatReporter+}diff --git a/internal/server/deepdoc/server.go b/internal/server/deepdoc/server.gonew file mode 100644index 0000000000..de5791a1a4--- /dev/null+++ b/internal/server/deepdoc/server.go@@ -0,0 +1,190 @@+//+// 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 deepdoc wires and runs the RAGFlow in-process (Go) DeepDoc backend and+// the DeepDoc server dispatch. It was extracted from package main so that main+// stays a thin dispatch layer.+package deepdoc++import (+ "os"+ "path/filepath"+ goruntime "runtime"+ "strconv"+ "strings"++ "go.uber.org/zap"++ "ragflow/internal/common"+ "ragflow/internal/deepdoc/native"+ pdf "ragflow/internal/deepdoc/parser/pdf"+ infnative "ragflow/internal/deepdoc/parser/pdf/inference/native_analyzer"+ "ragflow/internal/server"+ "ragflow/internal/server/bootstrap"+ "ragflow/internal/server/ingestor"+)++// inferenceTotalCores returns the CPU budget the DeepDoc inference config is+// validated against. It uses runtime.GOMAXPROCS(0) instead of runtime.NumCPU()+// so the budget reflects the cgroup CPU quota inside containers: Go 1.25+ derives+// GOMAXPROCS from the quota (CGroups v2 cpu.max / v1 cpu.cfs_quota_us), whereas+// runtime.NumCPU() reports the host's affinity-mask core count and ignores a+// container's CPU limit. Without this, a 2-CPU-limit pod on a 64-core host would+// "resolve" inference_cpu_cores: 0 to 64 and let inference_concurrency: 16 pass+// validation, oversubscribing the box the fail-fast guard in+// native.ValidateInferenceConfig exists to prevent.+func inferenceTotalCores() int {+ n := goruntime.GOMAXPROCS(0)+ if n < 1 {+ return 1+ }+ return n+}++// RegisterNativeDeepDoc wires the in-process (Go) DeepDoc backend as the local+// inference backend. The server is built with -tags cgo and links ONNX Runtime+// statically (libonnxruntime.a, resolved at runtime via dlopen(NULL) from the+// running binary — see github.com/infiniflow/onnxruntime_go, the org mirror of+// yalue/onnxruntime_go), so there is no external+// DeepDoc HTTP service and no dynamic .so deployment.+//+// Fail-fast contract (P0): the in-process backend must be available at startup+// (ORT + models present). There is NO silent degradation to an empty analyzer:+// if the backend is not serving, the server aborts.+func RegisterNativeDeepDoc(arguments *bootstrap.ServerArgs) error {+ modelDir := resolveDeepDocModelDir()+ dropScore := resolveDeepDocDropScore()++ if err := infnative.Register(modelDir, dropScore); err != nil {+ common.Warn("in-process DeepDoc backend unavailable",+ zap.String("reason", err.Error()))+ }++ // The in-process (Go) DeepDoc backend is the ONLY production backend. Fail+ // fast rather than silently parsing without layout/table/OCR if the local+ // backend cannot serve (ORT + models must be present when built with -tags+ // cgo).+ if !infnative.Serving() {+ common.Fatal("no in-process DeepDoc backend serving: provide the local ORT "++ "runtime + models and build with -tags cgo",+ zap.String("model_dir", modelDir),+ zap.String("ort_lib", "static (libonnxruntime.a via dlopen(NULL))"))+ }+ common.Info("in-process DeepDoc backend registered (production backend)",+ zap.String("model_dir", modelDir))++ // Resolve the DeepDoc in-process inference configuration: the concurrency+ // budget K (max in-flight Runs) and the CPU-core budget N (max cores+ // inference may occupy). Both resolve from CLI > env > config > default. K+ // defaults to 1; N defaults to "unset", which is derived from K so each Run+ // stays single-threaded by default (the prior behaviour). An explicit N = 0+ // means "all cores". All values are fail-fast validated against the process's+ // cgroup-aware CPU budget at startup (see native.ValidateInferenceConfig and+ // inferenceTotalCores), so a misconfiguration aborts rather than silently+ // oversubscribing the box.+ cfg := server.GetConfig()+ K, _, errK := cfg.GetDeepDocInferenceConcurrency(arguments.DeepdocInferenceConcurrency)+ if errK != nil {+ common.Fatal("invalid deepdoc inference concurrency", zap.Error(errK))+ }+ rawN, explicitN, errN := cfg.GetDeepDocInferenceCPUCores(arguments.DeepdocInferenceCPUCores)+ if errN != nil {+ common.Fatal("invalid deepdoc inference cpu cores", zap.Error(errN))+ }+ // When N is unset, derive it from K so each Run opens with a single intra-op+ // thread (coresPerInference = max(1, K/K) = 1), preserving the prior+ // single-core-per-run semantics. An explicit N (including 0 = all cores) is+ // honoured as-is below.+ resolvedN := rawN+ if !explicitN {+ resolvedN = K+ }+ totalCores := inferenceTotalCores()+ // Validate K and N against the process's CPU budget (cgroup-aware) and+ // derive the per-Run intra-op thread count (max(1, N/K)). N == 0 resolves to+ // all cores here.+ coresPerInference, totalCPUCores, errV := native.ValidateInferenceConfig(totalCores, resolvedN, K)+ if errV != nil {+ common.Fatal("invalid deepdoc inference configuration", zap.Error(errV))+ }+ // Register the per-session intra-op thread count before any model session is+ // created (the native package reads it on every SessionOptions build).+ native.SetIntraOpThreads(coresPerInference)+ pdf.SetDeepDocConcurrency(K)+ native.SetInferenceLimit(K)+ common.Info("in-process DeepDoc inference limit registered",+ zap.Int("max_concurrent_inference", K),+ zap.Int("cpu_cores_per_inference", coresPerInference),+ zap.Int("total_cpu_cores_budget", totalCPUCores),+ zap.Int("gomaxprocs", goruntime.GOMAXPROCS(0)))++ // 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 := ingestor.ResolveIngestorPageConcurrency(arguments, server.GetConfig().GetIngestorConfig().PageConcurrency)+ if err != nil {+ return err+ }+ pdf.SetPageConcurrency(pageConcurrency)+ common.Info("in-process DeepDoc page worker pool registered",+ zap.Int("page_concurrency", pageConcurrency))+ return nil+}++// resolveDeepDocModelDir picks the model directory: the explicit DEEPDOC_MODEL_DIR+// env, else the RAGFlow default model dir (internal/rag/res/deepdoc),+// else the assets fetched by ragflow_deps/download_deps.py. The first+// candidate that actually contains the required weights wins.+func resolveDeepDocModelDir() string {+ if v := strings.TrimSpace(common.GetEnv(common.EnvDeepDocModelDir)); v != "" {+ return v+ }+ wd, _ := os.Getwd()+ // MODEL_ASSETS_DIR first: the shared model-asset root keeps this layout too, so one+ // variable can point at the DeepDoc weights as well as the embedding tokenizers.+ candidates := append([]string(nil), common.ModelAssetCandidates("huggingface.co/InfiniFlow/deepdoc")...)+ candidates = append(candidates,+ filepath.Join(wd, "internal", "rag", "res", "deepdoc"),+ filepath.Join(wd, "huggingface.co", "InfiniFlow", "deepdoc"),+ )+ for _, c := range candidates {+ if dirHasModels(c) {+ return c+ }+ }+ // None verified; return the canonical default so any error message points+ // at the conventional location.+ return filepath.Join(wd, "internal", "rag", "res", "deepdoc")+}++// resolveDeepDocDropScore returns the explicit DEEPDOC_DROP_SCORE env, else the+// in-process backend's default (infnative.DefaultDropScore, which mirrors+// the Python inference service's Recognizer.drop_score).+func resolveDeepDocDropScore() float64 {+ if v := strings.TrimSpace(common.GetEnv(common.EnvDeepDocDropScore)); v != "" {+ if f, err := strconv.ParseFloat(v, 64); err == nil {+ return f+ }+ common.Warn("invalid DEEPDOC_DROP_SCORE, using default",+ zap.String("value", v), zap.Float64("default", infnative.DefaultDropScore))+ }+ return infnative.DefaultDropScore+}++// dirHasModels reports whether dir contains every required model files.+func dirHasModels(dir string) bool {+ return common.HasModelFiles(dir)+}diff --git a/internal/server/deepdoc/server_test.go b/internal/server/deepdoc/server_test.gonew file mode 100644index 0000000000..27b0131688--- /dev/null+++ b/internal/server/deepdoc/server_test.go@@ -0,0 +1,42 @@+//+// 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 deepdoc++import (+ "testing"++ goruntime "runtime"+)++// TestInferenceTotalCoresIsCgroupAware pins that the DeepDoc inference core+// budget passed to native.ValidateInferenceConfig is derived from+// runtime.GOMAXPROCS(0) (cgroup-quota aware in Go 1.25+) rather than+// runtime.NumCPU() (host affinity mask, which ignores a container's CPU limit).+// This keeps the fail-fast oversubscription guard effective under container CPU+// quotas: with NumCPU(), a 2-CPU-limit pod on a 64-core host would "resolve"+// inference_cpu_cores: 0 to 64 and let inference_concurrency: 16 pass validation,+// oversubscribing the box the check exists to prevent.+func TestInferenceTotalCoresIsCgroupAware(t *testing.T) {+ got := inferenceTotalCores()+ want := goruntime.GOMAXPROCS(0)+ if got != want {+ t.Fatalf("inferenceTotalCores() = %d, want runtime.GOMAXPROCS(0) = %d (cgroup-aware budget)", got, want)+ }+ if got < 1 {+ t.Fatalf("inferenceTotalCores() = %d, want >= 1", got)+ }+}diff --git a/internal/server/ingestor/server.go b/internal/server/ingestor/server.gonew file mode 100644index 0000000000..d6e3d4c491--- /dev/null+++ b/internal/server/ingestor/server.go@@ -0,0 +1,229 @@+//+// 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 ingestor wires and runs the RAGFlow ingestion worker. It was+// extracted from package main so that main stays a thin dispatch layer.+package ingestor++import (+ "context"+ "fmt"+ "os"+ "strconv"+ "strings"+ "time"++ "go.uber.org/zap"++ "ragflow/internal/common"+ "ragflow/internal/ingestion/knowledge_compile"+ ingestion "ragflow/internal/ingestion/service"+ "ragflow/internal/server"+ "ragflow/internal/server/bootstrap"+ "ragflow/internal/server/config"+ "ragflow/internal/service"+ "ragflow/internal/service/nav"+ "ragflow/internal/service/nlp"+ "ragflow/internal/tokenizer"+)++// 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 *bootstrap.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 *bootstrap.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 logTokenizerCounters() {+ var available, unavailable []string+ for _, status := range tokenizer.CounterStatuses() {+ if status.Available {+ available = append(available, status.ID)+ continue+ }+ unavailable = append(unavailable, status.ID)+ }+ common.Info("embedding tokenizer counters", zap.Strings("available", available))+ if len(unavailable) > 0 {+ common.Warn("embedding tokenizers unavailable; models that declare them cannot be ingested until the asset is restored",+ zap.Strings("unavailable", unavailable),+ zap.String("hint", "run `uv run ragflow_deps/download_deps.py`, or set "+common.EnvModelAssetsDir+" to a directory holding them"))+ }+}++// Run starts the RAGFlow ingestion worker. It blocks until ctx is cancelled+// (OS shutdown signal) or the ingestor receives a shutdown command from the+// admin, then gracefully stops the ingestor.+func Run(ctx context.Context, cancel context.CancelFunc, serverName string, args *bootstrap.ServerArgs) error {+ // Initialize tokenizer (rag_analyzer)+ // tokenizer.Init handles DictPath fallback: env var → /usr/share/infinity/resource+ if err := tokenizer.Init(&tokenizer.PoolConfig{}); err != nil {+ common.Fatal("Failed to initialize tokenizer", zap.Error(err))+ }+ defer tokenizer.Close()++ // Fail fast if the cl100k_base BPE table is missing. NumTokensFromString /+ // TrimContentToTokenLimit now panic rather than degrading silently, so this+ // trades a mid-request panic for a clear startup failure.+ if err := tokenizer.InitCL100KEncoder(); err != nil {+ common.Fatal("Failed to initialize cl100k_base tokenizer", zap.Error(err))+ }+ logTokenizerCounters()++ // The dataset-level post-processing consumer cluster (§11) is owned and run by+ // the Ingestor: it is started inside ingestor.Start() and joined inside+ // ingestor.Stop(), so its lifecycle matches the ingestor. The configured+ // default LLM/embedding ids are passed so the LLM deduper is used (instead+ // of the noop fallback that still emits merged products). Best-effort: a+ // provisioning error is logged by the Ingestor and the pipeline still+ // writes available_int=0 compiled chunks; they just won't be merged until+ // the consumer is available.+ globalConfig := server.GetConfig()+ 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)+ if err != nil {+ return err+ }+ // Apply the configured compiler pool size (no-op when 0; the pool keeps its+ // vCPU default, overridable via KC_COMPILE_CONCURRENCY).+ knowledge_compile.SetCompilerConcurrency(ingestorCfg.CompilerPoolSize)+ ingestor := ingestion.NewIngestor(*args.Name, int32(workers), []string{"pdf", "docx", "txt"})+ ingestor.SetKnowledgeCompileModelConfig(+ globalConfig.GetDefaultChatModel().Name,+ globalConfig.GetDefaultEmbeddingModel().Name,+ )+ // The dataset-level knowledge-compile consumer (tree/structure products) upserts+ // into the dataset-nav tree, so the Ingestor must install the same ES-backed+ // NavService the API server installs. Without this, nav.GetNavService() returns+ // nil and tree/structure products are dropped (the consumer logs "nav service+ // unavailable, skipping dataset-nav upsert"), leaving the dataset tree empty.+ // The embedder resolves the tenant's embedding model on demand, so both+ // Search and UpsertDoc can embed queries/summaries automatically.+ navService := nlp.NewNavService(service.NewNavEmbedder(service.NewModelFactory(), ""))+ // The cluster namer/merger is the counterpart of Python's+ // _llm_create_summary / _llm_merge: a new cluster is named after the model's+ // topic title and an existing cluster's description is fused with the joining+ // document. Passing an empty model ref resolves each tenant's default chat+ // model on demand; without one the nav service keeps its deterministic+ // behavior.+ navService.SetNavMergeLLM(service.NewNavMergeLLM(service.NewModelFactory(), ""))+ nav.SetNavService(navService)+ // Memory extraction runs on the Ingestor's shared NATS consumer + worker+ // pool (task_type="memory" dispatched by handleAndExecute -> executeMemoryTask),+ // so there is no longer a dedicated Redis memory consumer to start.+ ingestor.SetMemoryMessageService(service.NewMemoryMessageService(service.NewMemoryService()))++ // Start returns immediately (it launches the owned consume/compile+ // goroutines and joins them via Stop); a provisioning failure here must+ // fail the server (main's os.Exit(1) path) instead of reporting a+ // healthy ingestor that can never consume.+ if err = ingestor.Start(); err != nil {+ common.Error("Failed to initialize ingestor", err)+ return err+ }++ common.Info("\n ____ __ _\n" ++ " / _/___ ____ ____ _____/ /_(_)___ ____ ________ ______ _____ _____\n" ++ " / // __ \\/ __ `/ _ \\/ ___/ __/ / __ \\/ __ \\ / ___/ _ \\/ ___/ | / / _ \\/ ___/\n" ++ " _/ // / / / /_/ / __(__ ) /_/ / /_/ / / / / (__ ) __/ / | |/ / __/ /\n" ++ "/___/_/ /_/\\__, /\\___/____/\\__/_/\\____/_/ /_/ /____/\\___/_/ |___/\\___/_/\n" ++ " /____/\n")++ // Print RAGFlow version+ common.Info(fmt.Sprintf("RAGFlow ingestion service version: %s", common.GetRAGFlowVersion()))++ // Set log level+ bootstrap.SetLogger(serverName, args)++ // Start heartbeat reporter to admin server+ if hb := bootstrap.StartHeartbeat(+ common.ServerTypeIngestion,+ fmt.Sprintf("ingestor-%s", ingestor.ID()[:8]),+ 0,+ globalConfig.GetHeartbeatInterval(),+ ); hb != nil {+ defer hb.Stop()+ }++ // Wait for either an OS shutdown signal or a shutdown command from the admin+ select {+ case <-ctx.Done():+ common.Info("Received shutdown signal")+ common.Info(fmt.Sprintf("Shutting down RAGFlow ingestor %s ...", *args.Name))+ case <-ingestor.ShutdownCh:+ common.Info(fmt.Sprintf("Received shutdown command from admin, stopping ingestor %s ...", *args.Name))+ cancel()+ }++ // Create context with timeout for graceful shutdown+ shutdownCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)+ defer cancel()++ ingestor.Stop(shutdownCtx)++ common.Info(fmt.Sprintf("Ingestor %s shutdown complete", *args.Name))++ return nil+}diff --git a/internal/server/ingestor/server_test.go b/internal/server/ingestor/server_test.gonew file mode 100644index 0000000000..15a79a3675--- /dev/null+++ b/internal/server/ingestor/server_test.go@@ -0,0 +1,118 @@+//+// 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 ingestor++import (+ "testing"++ "ragflow/internal/common"+ "ragflow/internal/server/bootstrap"+)++func intPtr(n int) *int { return &n }++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 := &bootstrap.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 := &bootstrap.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)+ }+ })+ }+}diff --git a/internal/server/syncer/server.go b/internal/server/syncer/server.gonew file mode 100644index 0000000000..5edf392f5a--- /dev/null+++ b/internal/server/syncer/server.go@@ -0,0 +1,81 @@+//+// 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 syncer wires and runs the RAGFlow file syncer. It was extracted from+// package main so that main stays a thin dispatch layer.+package syncer++import (+ "context"+ "fmt"++ "ragflow/internal/common"+ "ragflow/internal/server"+ "ragflow/internal/server/bootstrap"+ "ragflow/internal/syncer"+)++// Run starts the RAGFlow file syncer. It blocks until ctx is cancelled (OS+// shutdown signal) or the syncer receives a shutdown command from the admin,+// then gracefully stops the syncer.+func Run(ctx context.Context, cancel context.CancelFunc, serverName string, args *bootstrap.ServerArgs) error {+ globalConfig := server.GetConfig()+ syncerConfig := globalConfig.GetSyncerConfig()+ fileSyncer := syncer.NewSyncer(syncerConfig.MaxConcurrentSyncs)++ if err := fileSyncer.StartContext(ctx); err != nil {+ common.Error("Failed to initialize file syncer", err)+ return err+ }++ common.Info("\n _______ __ _____\n" ++ " / ____(_) /__ / ___/__ ______ ________ _____\n" ++ " / /_ / / / _ \\ \\__ \\/ / / / __ \\/ ___/ _ \\/ ___/\n" ++ " / __/ / / / __/ ___/ / /_/ / / / / /__/ __/ /\n" ++ " /_/ /_/_/\\___/ /____/\\__, /_/ /_/\\___/\\___/_/\n" ++ " /____/ \n")++ // Print RAGFlow version+ common.Info(fmt.Sprintf("RAGFlow file syncer service version: %s", common.GetRAGFlowVersion()))++ // Set log level+ bootstrap.SetLogger(serverName, args)++ // Start heartbeat reporter to admin server+ if hb := bootstrap.StartHeartbeat(+ common.ServerTypeFileSyncer,+ fmt.Sprintf("syncer-%s", fileSyncer.ID()[:8]),+ 0,+ globalConfig.GetHeartbeatInterval(),+ ); hb != nil {+ defer hb.Stop()+ }++ // Wait for either an OS shutdown signal or a shutdown command from the admin+ select {+ case <-ctx.Done():+ common.Info("Received shutdown signal")+ common.Info(fmt.Sprintf("Shutting down RAGFlow file syncer %s ...", *args.Name))+ case <-fileSyncer.ShutdownCh:+ common.Info(fmt.Sprintf("Received shutdown command from admin, stopping file syncer %s ...", *args.Name))+ cancel()+ }++ fileSyncer.Stop()+ common.Info(fmt.Sprintf("File syncer %s shutdown complete", *args.Name))++ return nil+}