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): boot standalone DeepDoc server before infrastructure init (#21398)
xugangqianged1647acb021
diff --git a/cmd/ragflow_server.go b/cmd/ragflow_server.goindex d64cc1603d..994e5ba152 100644--- a/cmd/ragflow_server.go+++ b/cmd/ragflow_server.go@@ -47,6 +47,32 @@ import ("ragflow/internal/storage")+// isStandaloneDeepDocServer reports whether st is a standalone DeepDoc+// inference server (CPU/GPU/Ascend). These boot the ONNX runtime only and never+// the full RAGFlow infrastructure, so main() returns early for them before+// initializing Redis/DB/engine/cache/storage/MQ. Every other server type — and+// the unknown sentinel — returns false.+func isStandaloneDeepDocServer(st common.ServerType) bool {+ return st == common.ServerTypeDeepDocCPU ||+ st == common.ServerTypeDeepDocGPU ||+ st == common.ServerTypeDeepDocAscend+}++// startPProfIfRequested launches the pprof HTTP server on localhost:6060.+// The blank "net/http/pprof" import above registers the handlers on+// http.DefaultServeMux, so only the listener needs starting. Both boot+// paths (standalone DeepDoc and the regular one) call it right after the+// logger is up, so its startup line lands in the run's log file. A bind+// failure is logged and non-fatal, matching the previous inline behavior.+func startPProfIfRequested() {+ go func() {+ common.Info("Starting pprof server", zap.String("addr", "localhost:6060"))+ if pprofErr := http.ListenAndServe("localhost:6060", nil); pprofErr != nil {+ common.Error("pprof server failed", pprofErr)+ }+ }()+}+// parseArgsFrom parses argv (argv[0] is the program name, mirroring os.Args)// into a bootstrap.ServerArgs using the standard library flag package. The accepted// syntax is exactly the standard one: every flag works as "-flag value",@@ -334,6 +360,47 @@ func main() {os.Exit(1)}+ // The DeepDoc inference server runs standalone: it only needs the ONNX+ // runtime and MODEL_DIR, never the full RAGFlow infrastructure+ // (DB/engine/cache/storage/MQ). Boot it and return before the heavy+ // infrastructure init, so a bare inference container needs no MySQL/Redis.+ if st := bootstrap.GetServerType(arguments); isStandaloneDeepDocServer(st) {+ // SetServerName writes into the package-level local variables that+ // InitLocalVariables allocates; this early boot returns before the+ // shared InitLocalVariables call below, so it must allocate them+ // itself. The initializer constructs the in-memory struct only and+ // touches no external service, so the bare inference container stays+ // free of MySQL/Redis.+ if err = server.InitLocalVariables(); err != nil {+ fmt.Printf("Failed to start %s server: %v\n", *arguments.Mode, err)+ os.Exit(1)+ }+ logLevel := bootstrap.SelectedLogLevel(arguments, "")+ if higherThanInfo := common.LogLevelHigherThanInfo(logLevel); higherThanInfo {+ logLevel = "info"+ }+ if err = common.InitLogger(logLevel, common.FileOutput{}, bootstrap.TempServerName(st, arguments.Name)); err != nil {+ panic("failed to initialize logger: " + err.Error())+ }+ finalName, nameErr := bootstrap.ResolveServerName(*arguments.Mode, arguments.Name, 0)+ if nameErr != nil {+ common.Error("invalid server mode", nameErr)+ os.Exit(1)+ }+ server.SetServerName(finalName)+ // The regular pprof block sits after the infrastructure init this+ // path skips, so --profile must be honored here or the flag the+ // --deepdoc help text advertises would be silently ignored.+ if arguments.EnablePProf {+ startPProfIfRequested()+ }+ if err = runDeepDoc(ctx, finalName, arguments); err != nil {+ fmt.Printf("Failed to start DEEPDOC: %v\n", err)+ os.Exit(1)+ }+ return+ }+// Initialize local variables (runtime variables from Redis)err = server.InitLocalVariables()if err != nil {@@ -448,12 +515,7 @@ func main() {// Start pprof server if requestedif arguments.EnablePProf {- go func() {- common.Info("Starting pprof server", zap.String("addr", "localhost:6060"))- if pprofErr := http.ListenAndServe("localhost:6060", nil); pprofErr != nil {- common.Error("pprof server failed", pprofErr)- }- }()+ startPProfIfRequested()}// Initialize database. The migrate mode stops here: it needs neither the@@ -534,11 +596,6 @@ func main() {fmt.Printf("Failed to start SYNCER: %v\n", err)os.Exit(1)}- case common.ServerTypeDeepDocGPU, common.ServerTypeDeepDocCPU:- if err = runDeepDoc(ctx, serverName, arguments); err != nil {- fmt.Printf("Failed to start DEEPDOC: %v\n", err)- os.Exit(1)- }default:fmt.Printf("Invalid server mode: %v\n", serverType)os.Exit(1)diff --git a/cmd/ragflow_server_earlyboot_test.go b/cmd/ragflow_server_earlyboot_test.gonew file mode 100644index 0000000000..498346fbde--- /dev/null+++ b/cmd/ragflow_server_earlyboot_test.go@@ -0,0 +1,60 @@+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.++package main++import (+ "testing"++ "ragflow/internal/common"+)++// TestIsStandaloneDeepDocServer pins the contract used by main() to decide+// whether a server type is a standalone DeepDoc inference server that must boot+// BEFORE the heavy RAGFlow infrastructure (Redis/DB/engine/cache/storage/MQ) is+// initialized. The standalone DeepDoc types are exactly the three DeepDoc+// variants; every other server type (including the unknown sentinel) must NOT be+// treated as standalone.+//+// The adversarial cases (non-DeepDoc types returning false, and DeepDoc types+// returning true) make the distinguishing condition falsifiable: an+// implementation that returns true for everything, or that forgets one of the+// three DeepDoc variants, fails here.+func TestIsStandaloneDeepDocServer(t *testing.T) {+ standalone := []common.ServerType{+ common.ServerTypeDeepDocCPU,+ common.ServerTypeDeepDocGPU,+ common.ServerTypeDeepDocAscend,+ }+ for _, st := range standalone {+ if !isStandaloneDeepDocServer(st) {+ t.Errorf("isStandaloneDeepDocServer(%q) = false, want true", st)+ }+ }++ notStandalone := []common.ServerType{+ common.ServerTypeAPI,+ common.ServerTypeAdmin,+ common.ServerTypeIngestion,+ common.ServerTypeFileSyncer,+ common.ServerTypeMigrate,+ common.ServerTypeUnknown,+ common.ServerType("some-future-type"),+ }+ for _, st := range notStandalone {+ if isStandaloneDeepDocServer(st) {+ t.Errorf("isStandaloneDeepDocServer(%q) = true, want false", st)+ }+ }+}diff --git a/cmd/ragflow_server_pprof_test.go b/cmd/ragflow_server_pprof_test.gonew file mode 100644index 0000000000..9255069c80--- /dev/null+++ b/cmd/ragflow_server_pprof_test.go@@ -0,0 +1,187 @@+//+// Copyright 2026 The InfiniFlow Authors. All Rights Reserved.+//+// Licensed under the Apache License, Version 2.0 (the "License");+// you may not use this file except in compliance with the License.+// You may obtain a copy of the License at+//+// http://www.apache.org/licenses/LICENSE-2.0+//+// Unless required by applicable law or agreed to in writing, software+// distributed under the License is distributed on an "AS IS" BASIS,+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.+// See the License for the specific language governing permissions and+// limitations under the License.+//++package main++import (+ "context"+ "errors"+ "fmt"+ "net"+ "net/http"+ "os"+ "os/exec"+ "strings"+ "testing"+ "time"+)++// The DeepDoc early boot returns before the regular pprof block (which sits+// after the infrastructure init that the early return skips), so the early+// path must start the profiling endpoint itself. These tests pin that+// contract end-to-end through main(), re-executing the test binary as a+// subprocess (the pattern established by TestMainMigrateReachesConfiguration).++const (+ pprofProbeURL = "http://localhost:6060/debug/pprof/"+ pprofSkipExit = 42 // child exit code: port 6060 held by a stray process+ pprofBootWait = 15 * time.Second // max time for main() to finish its early boot+ pprofProbeWait = 15 * time.Second // max time for the pprof endpoint to come up+ pprofSettleWait = 5 * time.Second // silence window for the negative case+)++// pprofProbeClient dials localhost directly: an ambient HTTP_PROXY must not+// intercept the probe and fake a negative.+var pprofProbeClient = &http.Client{+ Timeout: 2 * time.Second,+ Transport: &http.Transport{Proxy: nil},+}++// pprofReachable reports whether the pprof index endpoint answers with 200.+func pprofReachable() bool {+ resp, err := pprofProbeClient.Get(pprofProbeURL)+ if err != nil {+ return false+ }+ defer resp.Body.Close()+ return resp.StatusCode == http.StatusOK+}++// pprofChildBoot starts main() in the background inside a re-executed test+// binary and returns a channel closed once main() returns. The OSS runDeepDoc+// stub returns immediately, but a pprof goroutine started by main() outlives+// it for the rest of this process, which is what the child assertions observe.+func pprofChildBoot() <-chan struct{} {+ done := make(chan struct{})+ go func() {+ main()+ close(done)+ }()+ return done+}++// runPProfChild re-executes this test binary as a subprocess with envVar set+// so the named test takes its child branch, and maps the exit code:+// 0 → pass, pprofSkipExit → skip (port 6060 held by a stray process),+// anything else → fail with the combined child output. It returns the output+// so callers can add secondary assertions.+func runPProfChild(t *testing.T, testName, envVar string) string {+ t.Helper()+ ctx, cancel := context.WithTimeout(t.Context(), 60*time.Second)+ defer cancel()+ cmd := exec.CommandContext(ctx, os.Args[0], "-test.run=^"+testName+"$", "-test.v")+ cmd.Dir = t.TempDir()+ cmd.Env = append(os.Environ(), envVar+"=1")+ out, err := cmd.CombinedOutput()+ if err != nil {+ var exitErr *exec.ExitError+ if errors.As(err, &exitErr) && exitErr.ExitCode() == pprofSkipExit {+ t.Skip("localhost:6060 is held by another process; cannot test pprof deterministically")+ }+ t.Fatalf("%s child failed: %v\n%s", testName, err, out)+ }+ return string(out)+}++// TestMainDeepDocProfileStartsPProf pins the contract that a standalone+// DeepDoc server booted with --profile serves pprof on localhost:6060. The+// DeepDoc early boot returns before the regular pprof block, so without a+// start in the early path, --deepdoc --profile silently ignores the flag the+// --deepdoc help text advertises. The secondary assertion on the startup log+// line proves the endpoint was opened by this boot path, not by a stray+// listener that slipped past the child's pre-check.+func TestMainDeepDocProfileStartsPProf(t *testing.T) {+ const envVar = "RAGFLOW_TEST_DEEPDOC_PROFILE"+ if os.Getenv(envVar) == "1" {+ if pprofReachable() {+ os.Exit(pprofSkipExit)+ }+ os.Args = []string{os.Args[0], "--deepdoc", "--profile"}+ pprofChildBoot()+ deadline := time.Now().Add(pprofProbeWait)+ for time.Now().Before(deadline) {+ if pprofReachable() {+ os.Exit(0)+ }+ time.Sleep(50 * time.Millisecond)+ }+ fmt.Fprintln(os.Stderr, "pprof endpoint never became reachable")+ os.Exit(1)+ }+ out := runPProfChild(t, "TestMainDeepDocProfileStartsPProf", envVar)+ if !strings.Contains(out, "Starting pprof server") {+ t.Fatalf("pprof startup line missing from child output:\n%s", out)+ }+}++// TestMainDeepDocWithoutProfileDoesNotStartPProf is the adversarial guard for+// the flag gate: --deepdoc WITHOUT --profile must not open the profiling+// port. An implementation that starts pprof unconditionally (ignoring+// arguments.EnablePProf) passes the positive test above but fails here. The+// child waits for main() to finish its early boot first, so a pprof server+// started by that path would already be listening when the silence window+// opens.+func TestMainDeepDocWithoutProfileDoesNotStartPProf(t *testing.T) {+ const envVar = "RAGFLOW_TEST_DEEPDOC_PROFILE_NEGATIVE"+ if os.Getenv(envVar) == "1" {+ if pprofReachable() {+ os.Exit(pprofSkipExit)+ }+ os.Args = []string{os.Args[0], "--deepdoc"}+ select {+ case <-pprofChildBoot():+ case <-time.After(pprofBootWait):+ fmt.Fprintln(os.Stderr, "main() did not return in time")+ os.Exit(1)+ }+ deadline := time.Now().Add(pprofSettleWait)+ for time.Now().Before(deadline) {+ if pprofReachable() {+ fmt.Fprintln(os.Stderr, "pprof endpoint reachable without --profile")+ os.Exit(1)+ }+ time.Sleep(50 * time.Millisecond)+ }+ os.Exit(0)+ }+ runPProfChild(t, "TestMainDeepDocWithoutProfileDoesNotStartPProf", envVar)+}++// TestMainDeepDocProfilePProfBindFailureIsNonFatal pins the error path: when+// the profiling port is already taken, the DeepDoc boot must log the failure+// and keep running — the inference server matters more than profiling. The+// child occupies localhost:6060 itself before booting main(), so main()'s+// listener attempt is guaranteed to fail; the test passes only if main()+// still returns without exiting the process.+func TestMainDeepDocProfilePProfBindFailureIsNonFatal(t *testing.T) {+ const envVar = "RAGFLOW_TEST_DEEPDOC_PROFILE_BINDFAIL"+ if os.Getenv(envVar) == "1" {+ ln, err := net.Listen("tcp", "localhost:6060")+ if err != nil {+ os.Exit(pprofSkipExit)+ }+ defer ln.Close()+ os.Args = []string{os.Args[0], "--deepdoc", "--profile"}+ select {+ case <-pprofChildBoot():+ os.Exit(0)+ case <-time.After(pprofBootWait):+ fmt.Fprintln(os.Stderr, "main() did not return in time")+ os.Exit(1)+ }+ }+ runPProfChild(t, "TestMainDeepDocProfilePProfBindFailureIsNonFatal", envVar)+}