docs: clarify admin bootstrap password setup (#21586)

docker/.env

@@ -296,11 +296,13 @@ ADMIN_SVR_HTTP_PORT=9381
 SVR_MCP_PORT=9382
 
 # Password for the default superuser (admin@ragflow.io) 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

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

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 `admin@ragflow.io` 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 `admin@ragflow.io`. 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.

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 `admin@ragflow.io` 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 `admin@ragflow.io`. 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:
 

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 `admin@ragflow.io` 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 `admin@ragflow.io`. 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.