Skip to content

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

fix(admin): honor ADMIN_DEFAULT_PASSWORD for the first superuser (#20562)

leilei31677763d0b2ef7e
diff --git a/internal/admin/default_admin_password_test.go b/internal/admin/default_admin_password_test.go
new file mode 100644
index 0000000000..8ed1971264
--- /dev/null
+++ b/internal/admin/default_admin_password_test.go
@@ -0,0 +1,185 @@
+//
+// 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
+
+import (
+ "os"
+ "strings"
+ "testing"
+
+ "ragflow/internal/common"
+)
+
+func TestConfiguredSuperuserNickname(t *testing.T) {
+ tests := []struct {
+ name string
+ env string
+ want string
+ }{
+ {name: "unset", want: "admin"},
+ {name: "blank", env: " \t", want: "admin"},
+ {name: "configured", env: " ops ", want: "ops"},
+ }
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Setenv(common.EnvDefaultSuperuserNickname, tt.env)
+ if got := configuredSuperuserNickname(); got != tt.want {
+ t.Fatalf("configuredSuperuserNickname() = %q, want %q", got, tt.want)
+ }
+ })
+ }
+}
+
+func TestConfiguredSuperuserEmail(t *testing.T) {
+ tests := []struct {
+ name string
+ env string
+ want string
+ }{
+ {name: "unset", want: "[email protected]"},
+ {name: "blank", env: " \n", want: "[email protected]"},
+ {name: "configured", env: " [email protected] ", want: "[email protected]"},
+ }
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Setenv(common.EnvDefaultSuperuserEmail, tt.env)
+ if got := configuredSuperuserEmail(); got != tt.want {
+ t.Fatalf("configuredSuperuserEmail() = %q, want %q", got, tt.want)
+ }
+ })
+ }
+}
+
+func TestConfiguredSuperuserPassword(t *testing.T) {
+ tests := []struct {
+ name string
+ canonical string
+ adminAlias string
+ want string
+ ok bool
+ }{
+ {name: "both unset"},
+ {name: "docker alias", adminAlias: "from-dotenv", want: "from-dotenv", ok: true},
+ {name: "canonical name", canonical: "from-config", want: "from-config", ok: true},
+ {name: "canonical wins when both are set", canonical: "from-config", adminAlias: "from-dotenv", want: "from-config", ok: true},
+ {name: "blank alias is unset", adminAlias: " "},
+ {name: "blank canonical uses alias", canonical: " \t", adminAlias: "from-dotenv", want: "from-dotenv", ok: true},
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Setenv(common.EnvDefaultSuperuserPassword, tt.canonical)
+ t.Setenv(common.EnvAdminDefaultPassword, tt.adminAlias)
+ got, ok := configuredSuperuserPassword()
+ if ok != tt.ok || got != tt.want {
+ t.Fatalf("configuredSuperuserPassword() = %q, %v, want %q, %v", got, ok, tt.want, tt.ok)
+ }
+ })
+ }
+}
+
+func TestUnsetSuperuserPasswordWritesBootstrapFile(t *testing.T) {
+ t.Chdir(t.TempDir())
+ t.Setenv(common.EnvDefaultSuperuserPassword, "")
+ t.Setenv(common.EnvAdminDefaultPassword, " ")
+
+ got, err := superuserPasswordForNewAdmin()
+ if err != nil {
+ t.Fatalf("superuserPasswordForNewAdmin() error = %v", err)
+ }
+ if got == "" || got == "admin" {
+ t.Fatalf("superuserPasswordForNewAdmin() = %q, want a generated password", got)
+ }
+
+ data, err := os.ReadFile(adminBootstrapPasswordFile)
+ if err != nil {
+ t.Fatalf("read bootstrap password: %v", err)
+ }
+ if strings.TrimSpace(string(data)) != got {
+ t.Fatalf("bootstrap file = %q, want %q", data, got)
+ }
+ info, err := os.Stat(adminBootstrapPasswordFile)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if info.Mode().Perm() != 0o600 {
+ t.Fatalf("bootstrap file mode = %o, want 600", info.Mode().Perm())
+ }
+
+ again, err := superuserPasswordForNewAdmin()
+ if err != nil {
+ t.Fatalf("second superuserPasswordForNewAdmin() error = %v", err)
+ }
+ if again != got {
+ t.Fatalf("second password = %q, want the password already written", again)
+ }
+}
+
+func TestExistingBootstrapPasswordIsReused(t *testing.T) {
+ t.Chdir(t.TempDir())
+ t.Setenv(common.EnvDefaultSuperuserPassword, "")
+ t.Setenv(common.EnvAdminDefaultPassword, "")
+ if err := os.MkdirAll("logs", 0o755); err != nil {
+ t.Fatal(err)
+ }
+ const stored = "already-generated-secret"
+ if err := os.WriteFile(adminBootstrapPasswordFile, []byte(stored+"\n"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+
+ got, err := superuserPasswordForNewAdmin()
+ if err != nil {
+ t.Fatal(err)
+ }
+ if got != stored {
+ t.Fatalf("superuserPasswordForNewAdmin() = %q, want %q", got, stored)
+ }
+}
+
+func TestConfiguredPasswordSkipsBootstrapFile(t *testing.T) {
+ t.Chdir(t.TempDir())
+ t.Setenv(common.EnvDefaultSuperuserPassword, "")
+ t.Setenv(common.EnvAdminDefaultPassword, "from-dotenv")
+
+ got, err := superuserPasswordForNewAdmin()
+ if err != nil {
+ t.Fatal(err)
+ }
+ if got != "from-dotenv" {
+ t.Fatalf("superuserPasswordForNewAdmin() = %q, want from-dotenv", got)
+ }
+ if _, err := os.Stat(adminBootstrapPasswordFile); !os.IsNotExist(err) {
+ t.Fatalf("bootstrap file stat err = %v, want not exist", err)
+ }
+}
+
+func TestBootstrapPasswordWriteFailureRefusesAdmin(t *testing.T) {
+ t.Chdir(t.TempDir())
+ t.Setenv(common.EnvDefaultSuperuserPassword, "")
+ t.Setenv(common.EnvAdminDefaultPassword, "")
+ if err := os.WriteFile("logs", []byte("not-a-directory"), 0o600); err != nil {
+ t.Fatal(err)
+ }
+
+ got, err := superuserPasswordForNewAdmin()
+ if err == nil {
+ t.Fatal("expected an error when the bootstrap password file cannot be written")
+ }
+ if got != "" {
+ t.Fatalf("superuserPasswordForNewAdmin() = %q, want no password", got)
+ }
+}
diff --git a/internal/admin/service.go b/internal/admin/service.go
index fe4e017265..ece3f5e173 100644
--- a/internal/admin/service.go
+++ b/internal/admin/service.go
@@ -26,6 +26,8 @@ import (
"fmt"
"net"
"net/url"
+ "os"
+ "path/filepath"
"ragflow/internal/agent/sandbox"
"ragflow/internal/common"
"ragflow/internal/dao"
@@ -39,6 +41,7 @@ import (
servicepkg "ragflow/internal/service"
"ragflow/internal/storage"
"regexp"
+ "strings"
"time"
"go.uber.org/zap"
@@ -1338,13 +1341,133 @@ func (s *Service) HandleHeartbeat(message *common.BaseMessage) (common.ErrorCode
return UpdateServer(message.ServerName, status)
}
-// InitDefaultAdmin initialize default admin user
-// This matches Python's init_default_admin behavior
+// adminBootstrapPasswordFile is where a generated first-superuser password is
+// stored when neither DEFAULT_SUPERUSER_PASSWORD nor ADMIN_DEFAULT_PASSWORD
+// is set. docker/.env documents this path on the container logs volume.
+const adminBootstrapPasswordFile = "logs/admin_bootstrap_password.txt"
+
+// configuredSuperuserNickname returns DEFAULT_SUPERUSER_NICKNAME when it is
+// non-empty after trim, and "admin" otherwise. The unset default matches
+// Python's init_default_admin.
+func configuredSuperuserNickname() string {
+ if nickname := strings.TrimSpace(common.GetEnv(common.EnvDefaultSuperuserNickname)); nickname != "" {
+ return nickname
+ }
+ return "admin"
+}
+
+// configuredSuperuserEmail returns DEFAULT_SUPERUSER_EMAIL when it is
+// non-empty after trim, and "[email protected]" otherwise. The unset default
+// matches Python's init_default_admin.
+func configuredSuperuserEmail() string {
+ if email := strings.TrimSpace(common.GetEnv(common.EnvDefaultSuperuserEmail)); email != "" {
+ return email
+ }
+}
+
+// configuredSuperuserPassword reads the password for a new superuser.
+// DEFAULT_SUPERUSER_PASSWORD is canonical. ADMIN_DEFAULT_PASSWORD is used
+// when the canonical name is empty. The boolean is false when both are empty.
+func configuredSuperuserPassword() (string, bool) {
+ if password := strings.TrimSpace(common.GetEnv(common.EnvDefaultSuperuserPassword)); password != "" {
+ return password, true
+ }
+ if password := strings.TrimSpace(common.GetEnv(common.EnvAdminDefaultPassword)); password != "" {
+ return password, true
+ }
+ return "", false
+}
+
+// superuserPasswordForNewAdmin returns the configured password, or a generated
+// password written once to adminBootstrapPasswordFile. It does not fall back
+// to a public default. A write failure refuses creation of the first superuser.
+func superuserPasswordForNewAdmin() (string, error) {
+ if password, ok := configuredSuperuserPassword(); ok {
+ return password, nil
+ }
+ password, err := bootstrapSuperuserPassword(adminBootstrapPasswordFile)
+ if err != nil {
+ return "", fmt.Errorf("refuse to create the first superuser: %w", err)
+ }
+ return password, nil
+}
+
+func bootstrapSuperuserPassword(path string) (string, error) {
+ existing, err := readBootstrapPassword(path)
+ if err != nil {
+ return "", err
+ }
+ if existing != "" {
+ return existing, nil
+ }
+ if err := os.Remove(path); err != nil && !os.IsNotExist(err) {
+ return "", fmt.Errorf("replace empty bootstrap password file: %w", err)
+ }
+
+ buf := make([]byte, 32)
+ if _, err := rand.Read(buf); err != nil {
+ return "", fmt.Errorf("generate bootstrap password: %w", err)
+ }
+ password := hex.EncodeToString(buf)
+ if err := writeBootstrapPassword(path, password); err != nil {
+ if stored, readErr := readBootstrapPassword(path); readErr == nil && stored != "" {
+ return stored, nil
+ }
+ return "", err
+ }
+ common.Info("Wrote generated superuser password", zap.String("file", path))
+ return password, nil
+}
+
+func readBootstrapPassword(path string) (string, error) {
+ data, err := os.ReadFile(path)
+ if err != nil {
+ if os.IsNotExist(err) {
+ return "", nil
+ }
+ return "", fmt.Errorf("read bootstrap password: %w", err)
+ }
+ return strings.TrimSpace(string(data)), nil
+}
+
+func writeBootstrapPassword(path, password string) error {
+ if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+ return fmt.Errorf("create bootstrap password directory: %w", err)
+ }
+ file, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
+ if err != nil {
+ return fmt.Errorf("write bootstrap password: %w", err)
+ }
+ remove := true
+ defer func() {
+ _ = file.Close()
+ if remove {
+ _ = os.Remove(path)
+ }
+ }()
+ if err := file.Chmod(0o600); err != nil {
+ return fmt.Errorf("restrict bootstrap password file: %w", err)
+ }
+ if _, err := file.WriteString(password + "\n"); err != nil {
+ return fmt.Errorf("write bootstrap password: %w", err)
+ }
+ if err := file.Close(); err != nil {
+ return fmt.Errorf("write bootstrap password: %w", err)
+ }
+ remove = false
+ return nil
+}
+
+// InitDefaultAdmin creates the first superuser when none is active.
+// When DEFAULT_SUPERUSER_NICKNAME and DEFAULT_SUPERUSER_EMAIL are unset,
+// the nickname and email still match Python's init_default_admin
+// ("admin" and "[email protected]"). The password path does not: it uses
+// DEFAULT_SUPERUSER_PASSWORD or ADMIN_DEFAULT_PASSWORD, or a generated
+// secret, and it does not use Python's literal "admin".
func (s *Service) InitDefaultAdmin() error {
- // Default superuser settings (matching Python's DEFAULT_SUPERUSER_* defaults)
- defaultNickname := "admin"
- defaultEmail := "[email protected]"
- defaultPassword := "admin"
+ defaultNickname := configuredSuperuserNickname()
+ defaultEmail := configuredSuperuserEmail()
// Query superusers
var users []*entity.User
@@ -1354,6 +1477,11 @@ func (s *Service) InitDefaultAdmin() error {
}
if len(users) == 0 {
+ defaultPassword, err := superuserPasswordForNewAdmin()
+ if err != nil {
+ return err
+ }
+
userID := common.GenerateToken()
accessToken := common.GenerateToken()
status := "1"
diff --git a/internal/common/environments.go b/internal/common/environments.go
index 4f17013ed8..bb8a1d8db1 100644
--- a/internal/common/environments.go
+++ b/internal/common/environments.go
@@ -76,6 +76,7 @@ const (
EnvDefaultSuperuserEmail = "DEFAULT_SUPERUSER_EMAIL"
EnvDefaultSuperuserNickname = "DEFAULT_SUPERUSER_NICKNAME"
EnvDefaultSuperuserPassword = "DEFAULT_SUPERUSER_PASSWORD"
+ EnvAdminDefaultPassword = "ADMIN_DEFAULT_PASSWORD" // docker/.env alias of DEFAULT_SUPERUSER_PASSWORD
EnvDBType = "DB_TYPE"
EnvDevice = "DEVICE"
EnvStorageImpl = "STORAGE_IMPL"
diff --git a/internal/server/config/environments.go b/internal/server/config/environments.go
index 5af19a6690..51e22b9c0f 100644
--- a/internal/server/config/environments.go
+++ b/internal/server/config/environments.go
@@ -212,12 +212,18 @@ func (c *Config) GetEnvironments() error {
c.environments.DefaultSuperUser.Email = superUserEmail
}
- superUserPassword := common.GetEnv(common.EnvDefaultSuperuserPassword)
+ // DEFAULT_SUPERUSER_PASSWORD is canonical. ADMIN_DEFAULT_PASSWORD is the
+ // same alias creation uses when the canonical name is empty. A generated
+ // bootstrap-file password is not filled in here.
+ superUserPassword := strings.TrimSpace(common.GetEnv(common.EnvDefaultSuperuserPassword))
+ if superUserPassword == "" {
+ superUserPassword = strings.TrimSpace(common.GetEnv(common.EnvAdminDefaultPassword))
+ }
if superUserPassword != "" {
c.environments.DefaultSuperUser.Password = superUserPassword
}
- superUserNickname := common.GetEnv(common.EnvDefaultSuperuserNickname)
+ superUserNickname := strings.TrimSpace(common.GetEnv(common.EnvDefaultSuperuserNickname))
if superUserNickname != "" {
c.environments.DefaultSuperUser.Nickname = superUserNickname
}
@@ -624,7 +630,7 @@ func (c *Config) GetEnvDefaultSuperUserEmail() string {
}
func (c *Config) GetEnvDefaultSuperUserNick() string {
- return c.environments.DefaultSuperUser.Email
+ return c.environments.DefaultSuperUser.Nickname
}
func (c *Config) GetEnvDictionaryPath() string {