Skip to content

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

docs: clarify admin bootstrap password setup (#21586)

buua43679e84ebb9c7a
diff --git a/docker/.env b/docker/.env
index b9e3d64fc0..45050e4aa4 100644
--- a/docker/.env
+++ b/docker/.env
@@ -296,11 +296,13 @@ ADMIN_SVR_HTTP_PORT=9381
SVR_MCP_PORT=9382
# Password for the default superuser ([email protected]) that the admin server
-# creates on first start when no superuser exists. When unset (and
-# DEFAULT_SUPERUSER_PASSWORD is also unset), a random password is generated and
+# creates on first start when no superuser exists. Replace this sample value
+# with a deployment-specific secret before starting a network-accessible
+# deployment. This value only initializes the first superuser; changing it
+# later does not reset an existing password. If this and
+# DEFAULT_SUPERUSER_PASSWORD are unset, a random password is generated and
# written once to logs/admin_bootstrap_password.txt (mode 0600, the container's
-# /ragflow/logs volume) - read it there and change it immediately after the
-# first login.
+# /ragflow/logs volume).
ADMIN_DEFAULT_PASSWORD=admin
# Development-only: set to 1 to allow private database and connector hosts
diff --git a/docker/README.md b/docker/README.md
index 5938f32dc5..ef6914effe 100644
--- a/docker/README.md
+++ b/docker/README.md
@@ -27,6 +27,13 @@ The Go image runs the API, Admin, Ingestor, and Syncer modes from the single `bi
Run the Go release deployment from the repository checkout:
+Before first startup, replace `ADMIN_DEFAULT_PASSWORD` in `docker/.env` with a
+deployment-specific secret if the Admin Service can be reached by other hosts.
+The checked-in value is `admin`, and Docker publishes the Admin port `9381` on
+the host by default. Restrict access to that port to trusted administrators.
+The password setting is used only when the first superuser is created; changing
+it later does not change an existing account's password.
+
```bash
# Enter the Docker deployment directory.
cd ragflow/docker
diff --git a/docs/administrator/management/admin_ui/before_you_begin.md b/docs/administrator/management/admin_ui/before_you_begin.md
index 9aa155edd3..c3f1b1ac92 100644
--- a/docs/administrator/management/admin_ui/before_you_begin.md
+++ b/docs/administrator/management/admin_ui/before_you_begin.md
@@ -18,8 +18,21 @@ Regular users do not need to enter the Admin UI when they use business features
## Initial Administrator Account
-When the Admin service starts with `--init-superuser` and no superuser exists, it creates the default administrator account `[email protected]` with the initial password `admin`. The option does not change an existing superuser account or reset its password.
+When the Admin service starts with `--init-superuser` and no superuser exists,
+it creates the administrator account `[email protected]`. The initial password
+comes from `DEFAULT_SUPERUSER_PASSWORD` or `ADMIN_DEFAULT_PASSWORD`; if neither
+is set, RAGFlow generates a random password and writes it to
+`logs/admin_bootstrap_password.txt`.
+
+The checked-in Docker configuration sets `ADMIN_DEFAULT_PASSWORD=admin`. If
+other hosts can reach the Admin Service, replace that value with a unique secret
+in `docker/.env` before the first startup, and restrict the published Admin port
+to trusted administrators. This setting only initializes the first
+superuser—it does not reset an existing account's password.
This account is used to initialize the system and create subsequent administrator accounts. It is not recommended as a long-term shared daily operations account.
-After the first login, reset the default password as soon as possible and create separate accounts for different administrators. In daily administration, grant the `Superuser` identity only to users who actually need Admin UI responsibilities.
+If you used the sample `admin` password, change it immediately after login and
+create separate accounts for different administrators. In daily administration,
+grant the `Superuser` identity only to users who actually need Admin UI
+responsibilities.
diff --git a/docs/administrator/management/ragflow_cli.md b/docs/administrator/management/ragflow_cli.md
index 7debba14d0..846f9c2fc4 100644
--- a/docs/administrator/management/ragflow_cli.md
+++ b/docs/administrator/management/ragflow_cli.md
@@ -75,7 +75,13 @@ For a source-development checkout, start the Admin Service with `RAGFLOW_DEV_MOD
RAGFLOW_DEV_MODE=true ./bin/ragflow_server --admin --init-superuser
```
-If this creates the first superuser, its email is `[email protected]` and its initial password is `admin`. Change that password immediately after the first login. The option does not reset an existing superuser's password.
+If this creates the first superuser, its email is `[email protected]`. Its initial
+password comes from `DEFAULT_SUPERUSER_PASSWORD` or `ADMIN_DEFAULT_PASSWORD`; if
+neither is set, RAGFlow generates a random password and writes it to
+`logs/admin_bootstrap_password.txt`. For Docker deployments, replace the sample
+`ADMIN_DEFAULT_PASSWORD=admin` in `docker/.env` before first startup whenever
+other hosts can reach the Admin Service. Changing the setting after the
+superuser exists does not reset its password.
Then start the CLI in Admin mode. If `--host` is omitted, it connects to `127.0.0.1:9381` by default:
diff --git a/docs/administrator/setup/admin_service.md b/docs/administrator/setup/admin_service.md
index f565966e3b..ef69cc39b7 100644
--- a/docs/administrator/setup/admin_service.md
+++ b/docs/administrator/setup/admin_service.md
@@ -57,7 +57,11 @@ To initialize the default superuser when starting Admin, add `--init-superuser`
RAGFLOW_DEV_MODE=true ./bin/ragflow_server --admin --init-superuser
```
-If no superuser exists, this option currently creates `[email protected]` with the initial password `admin`. Change that password immediately after the first login. It does not reset the password of an existing superuser.
+If no superuser exists, this option creates `[email protected]`. Set
+`DEFAULT_SUPERUSER_PASSWORD` or `ADMIN_DEFAULT_PASSWORD` before initialization
+to choose its initial password. If neither variable is set, RAGFlow generates
+a random password and writes it to `logs/admin_bootstrap_password.txt`.
+Changing either variable after a superuser exists does not reset its password.
To change the Admin listening port, set `admin.http_port` in the server configuration.
@@ -71,7 +75,16 @@ For the Go deployment, use `docker/docker-compose.yml` and its `.env` file. The
docker compose --env-file docker/.env -f docker/docker-compose.yml --profile cpu up -d
```
-The Go Compose deployment exposes the Admin Service on `9381` and the API server on `9380` by default. Use `ADMIN_SVR_HTTP_PORT` and `SVR_HTTP_PORT` to change the corresponding published host ports.
+Before first startup, replace `ADMIN_DEFAULT_PASSWORD` in `docker/.env` with a
+deployment-specific secret when the Admin Service is reachable by other hosts.
+The checked-in value is `admin`. The Go Compose deployment publishes the Admin
+Service on host port `9381` by default, so restrict that port to trusted
+administrators. Changing the password setting after the first superuser has
+been created does not change the account password.
+
+The API server is published on host port `9380` by default. Use
+`ADMIN_SVR_HTTP_PORT` and `SVR_HTTP_PORT` to change the corresponding published
+host ports.
Use the Go Compose entry point documented in [Go Docker deployment](../../../docker/README.md). Initialize the first superuser with `--init-superuser` only when initial account setup is required.