Skip to content

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

refactor(cmd): boot standalone DeepDoc server before infrastructure init (#21398)

xugangqianged1647acb021
diff --git a/cmd/ragflow_server.go b/cmd/ragflow_server.go
index 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 requested
if 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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)
+}