Skip to content

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

refactor(cmd): extract server runners into internal/server/* packages (#20883)

xugangqiangfa1494d70356
diff --git a/cmd/args_flag_test.go b/cmd/args_flag_test.go
index 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.go
index ee68db3dd1..4542c59a3c 100644
--- a/cmd/deepdoc_server_ee.go
+++ b/cmd/deepdoc_server_ee.go
@@ -18,10 +18,12 @@ package main
import (
"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.go
index 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] = true
switch f.Name {
case "log-level":
- args.logLevel = &logLevel
+ args.LogLevel = &logLevel
case "config", "f":
- args.configPath = &configPath
+ args.ConfigPath = &configPath
case "name":
- args.name = &name
+ args.Name = &name
case "port", "p":
- args.port = &port
+ args.Port = &port
case "deepdoc-inference-concurrency":
- args.deepdocInferenceConcurrency = &deepdocConcurrency
+ args.DeepdocInferenceConcurrency = &deepdocConcurrency
case "ingestor-max-concurrent-workers":
- args.ingestorMaxConcurrentWorkers = &ingestorWorkers
+ args.IngestorMaxConcurrentWorkers = &ingestorWorkers
case "ingestor-page-concurrency":
- args.ingestorPageConcurrency = &pageConcurrency
+ args.IngestorPageConcurrency = &pageConcurrency
case "deepdoc-inference-cpu-cores":
- args.deepdocInferenceCPUCores = &cpuCores
+ args.DeepdocInferenceCPUCores = &cpuCores
case "init-superuser":
- args.initSuperUser = initSuperUser
+ args.InitSuperUser = initSuperUser
case "profile":
- args.enablePProf = enablePProf
+ args.EnablePProf = enablePProf
case "help", "h":
- args.helpFlag = helpFlag
+ args.HelpFlag = helpFlag
case "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 configuration
var 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 = port
case "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 path
server.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.go
index bf0f3637b1..5b96b1ebac 100644
--- a/cmd/ragflow_server_deepdoc_test.go
+++ b/cmd/ragflow_server_deepdoc_test.go
@@ -18,7 +18,6 @@ package main
import (
"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.go
index 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.Args
os.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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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
+}