# 修改与重置 root 密码

> FastGPT 自部署 root 管理员密码的首次激活、日常修改与忘记密码重置教程

Source: https://doc.fastgpt.cn/zh-CN/self-host/config/root-password

FastGPT 的系统管理员默认用户名为 `root`。从 `v4.17.3` 版本开始，FastGPT 引入了账号激活机制与内置的密码重置命令行工具，移除了以往每次重启容器通过 `DEFAULT_ROOT_PSW` 环境变量重写密码的旧逻辑（`v4.17.3+` 部署模板中若仍保留 `DEFAULT_ROOT_PSW` 变量，运行期会自动忽略），从而提升管理员账号的安全性。

本文将介绍不同场景下如何修改或重置 `root` 管理员密码。

***

## 场景一：首次部署登录与激活

在 `v4.17.3` 及更高版本中，新创建的 FastGPT 实例默认初始密码固定为 `123456`，账号初始处于待激活状态（`inactive`）。从旧版本升级的实例，如果 `root` 账号没有 `status` 字段，启动时同样会被置为待激活状态，首次登录也会弹出激活窗口，此时使用原密码登录。

1. 打开 FastGPT Web 访问地址。
2. 使用系统管理员账号登录：
   * **用户名**：`root`
   * **初始密码**：`123456`
3. 登录成功后，页面会自动弹出不可关闭的「账号激活」窗口，强制要求设置新密码。
4. 输入并确认新密码（密码长度至少 8 位，且至少包含大写字母、小写字母、数字、特殊字符中的任意两类），点击「确定」完成激活。设置成功后系统进入正常使用状态，请妥善保管好您的新密码。

> 为保障系统安全，首次登录必须完成激活并设置新密码后方可使用系统各项功能。

***

## 场景二：在 Web 界面日常修改密码

如果您已知当前密码并处于正常登录状态，可直接在平台界面中修改密码：

1. 以 `root` 身份登录 FastGPT 平台。
2. 点击左侧导航栏「账号」，进入「个人信息」页面。
3. 在「通用信息」区域的「密码」行点击「变更」，打开修改弹窗。
4. 按提示完成旧密码身份验证并输入符合复杂度要求的新密码（至少 8 位，包含大写字母、小写字母、数字、特殊字符中的任意两类），点击「确定」。
5. 密码修改成功后立即生效。

***

## 场景三：忘记密码时通过 CLI 重置密码

如果您遗忘了 `root` 密码无法登录 Web 界面，可以直接在 FastGPT 容器内运行内置的密码重置脚本。

该操作会连接 MongoDB 并直接更新管理员密码，**无需重启服务容器**，且不会影响系统中已运行的其他任务。

### 1. Docker Compose 部署环境

进入服务器上存放 `docker-compose.yml` 的部署目录，执行以下命令：

```bash
docker compose exec fastgpt-app node /app/scripts/reset-root-password.cjs '你的新密码'
```

*若使用的是旧版本 Docker Compose（独立二进制），请将 `docker compose` 替换为 `docker-compose`：*

```bash
docker-compose exec fastgpt-app node /app/scripts/reset-root-password.cjs '你的新密码'
```

### 2. Docker 单容器独立运行环境

如果使用 `docker run` 单独启动容器，可通过容器名或容器 ID 执行重置：

```bash
docker exec -it <容器名称或ID> node /app/scripts/reset-root-password.cjs '你的新密码'
```

### 3. Kubernetes / Helm 部署环境

在 Kubernetes 集群中，可以通过 `kubectl exec` 在 FastGPT Pod 中执行重置：

```bash
kubectl exec -it <fastgpt-pod-name> -n <namespace> -- node /app/scripts/reset-root-password.cjs '你的新密码'
```

### 执行结果验证

执行成功后，终端将输出：

```text
root 密码已重置
```

重置完成后即可在 Web 界面中使用新密码登录。CLI 脚本只更新数据库中的密码，不清除已有登录会话，已登录的会话仍然有效；如需让其他会话下线，请在 Web 界面中修改一次密码。

CLI 脚本仅校验密码非空，请自行设置符合 Web 端规则的强密码（至少 8 位，包含大写字母、小写字母、数字、特殊字符中的任意两类）。

> 如果设置的新密码中包含特殊字符（例如 `$!#` 等符号），请务必在命令行中使用**单引号** `' '` 包裹密码参数，避免被宿主机的 Shell 提前解析转义。

***

## 场景四：历史版本（v4.17.2 及更早）修改方式

对于 `v4.17.2` 及更早的历史版本，系统尚未内置密码重置 CLI 脚本，root 密码由环境变量控制：

1. 打开部署目录下的 `docker-compose.yml` 文件。
2. 找到 `DEFAULT_ROOT_PSW` 环境变量（或 `x-default-root-psw` YAML 锚点），修改其对应的值为新密码。
3. 重启 FastGPT 服务使配置生效：
   ```bash
   docker compose down
   docker compose up -d
   ```
4. 容器启动时会自动将数据库中的 `root` 密码更新为环境变量中设置的新密码。
