使用指南
账户与登录
控制台的唯一账户：创建、登录方式、账户安全、会话、个人设置与控制台导航。
账户
控制台只有一个账户，由初始化向导（/setup，创建账户）创建。
| 项目 | 说明 |
|---|---|
| 初始化字段 | 初始化令牌（控制台日志中打印的一次性 setup token）、姓名（1–100 字符）、邮箱（登录邮箱）、密码（12–128 字符）。步骤见 快速上手 |
| 其他账户 | 不开放注册；控制台没有用户管理，不能添加第二个账户 |
| 姓名与邮箱 | 控制台不提供修改入口 |
| 密码 | 在 账户安全 修改；Web 界面不提供找回或重置密码的入口，忘记密码时在服务器上重置，见 找回账户 |
| API | AccessKey（ewk_ 开头）以该账户身份调用 /api/v1，在 个人设置 中创建 |
登录
页面：/login。
| 方式 | 说明 |
|---|---|
| 密码 | 填写 邮箱 与 密码，点击 登录 |
| 两步验证 | 账户启用 TOTP 后，密码正确时进入 两步验证：输入 6 位验证码，或点击 使用备用码 输入备用码。该步骤 10 分钟内有效 |
| 通行密钥 | 点击 使用通行密钥登录，不进入两步验证步骤。浏览器不支持 WebAuthn 时不显示 |
| 项目 | 说明 |
|---|---|
| 跳转 | 登录后回到登录前打开的页面，否则进入 概览 |
| 登录限速 | 登录、两步验证与修改密码：每个客户端 IP 每 10 秒 3 次，生产环境（NODE_ENV=production）启用。客户端 IP 的取值见 可信代理与客户端 IP |
| 审计 | 登录成功（auth.sign_in，含登录方式）与失败（auth.sign_in_failed）写入 审计日志 |
会话
| 项目 | 说明 |
|---|---|
| 有效期 | 7 天；使用期间每 24 小时最多顺延一次（better-auth 默认值） |
| 退出 | 侧边栏底部用户菜单 → 退出登录 |
| 其他设备 | 控制台不列出会话；修改密码时其他设备上的会话退出登录，找回账户 时全部会话退出登录 |
账户安全
页面：用户菜单 → 账户安全（/security）。
密码
| 项目 | 说明 |
|---|---|
| 修改 | 填写 当前密码、新密码、确认新密码，点击 修改密码 |
| 长度 | 12–128 字符 |
| 其他会话 | 修改后其他设备退出登录 |
两步验证（TOTP）
- 在 两步验证（TOTP） 中填写 当前密码，点击 启用。
- 用验证器扫描二维码，或手动输入 密钥。
- 输入 6 位 验证码，点击 验证。
- 保存 备用码（仅显示一次）。
| 项目 | 说明 |
|---|---|
| 状态 | 卡片标题旁显示 已启用 / 未启用 |
| TOTP 参数 | 6 位，30 秒，签发方 Edgeweir |
| 备用码 | 10 个，格式 xxxxx-xxxxx，每个仅可使用一次 |
| 重新生成备用码 | 停用后重新启用两步验证 |
| 停用 | 填写 当前密码，点击 停用 |
通行密钥
| 项目 | 说明 |
|---|---|
| 添加 | 填写 名称（可选，最多 64 字符），点击 添加通行密钥，按浏览器提示完成注册。浏览器不支持 WebAuthn 时按钮不可用 |
| 删除 | 在列表中删除，需确认 |
| 绑定 | 通行密钥绑定 EDGEWEIR_PUBLIC_URL 的主机名；更换控制台主机名后，已注册的通行密钥无法使用 |
修改密码、启用与停用两步验证、添加与删除通行密钥写入 审计日志（account.*）。
个人设置
页面：用户菜单 → 个人设置（/settings）。
| 卡片 | 内容 |
|---|---|
| 偏好 | 语言（简体中文 / English）与 主题（浅色 / 深色 / 跟随系统），保存在当前浏览器 |
| AccessKey | 创建与吊销 AccessKey：名称、权限范围（只读 / 读写）；密钥仅显示一次。只读密钥只能调用 GET 接口与 rules.validate。只能在已登录的控制台中创建，用 AccessKey 创建返回 403 ACCESS_KEY_SESSION_REQUIRED |
AccessKey 的用法与吊销见 访问日志与 AccessKey，请求格式见 API 与端点。
控制台导航
侧边栏顶部的 新建网站 打开新建网站表单；还没有节点时它是 添加节点，打开添加节点对话框。⌘K / Ctrl+K 打开命令菜单，用方向键选择、回车执行：
| 项目 | 行为 |
|---|---|
| 网站 | 输入网站名或域名搜索网站，回车打开；未输入时列出已加星标和最近访问的网站 |
| 网站操作 | 搜到的前 3 个网站各有「Under Attack：（网站）」（确认后切换该网站的 Under Attack）和「清除缓存：（网站）」（确认后创建全站刷新任务） |
| 导航 | 打开任一页面（含 账户安全、个人设置、系统设置的 监控 页签，以及打开所在页面的 区域 与 服务账号） |
| 操作 | 新建网站、添加节点、封禁 IP…（打开封禁对话框，在网站页面时预填该网站）、刷新 URL…（打开 刷新预热）、全局 Under Attack（确认后切换）、切换语言、切换深浅色 |
侧边栏
| 分组 | 菜单 | 路径 | 内容 |
|---|---|---|---|
| — | 概览 | /overview | 见 概览；有 待处理 事项时旁边显示其数量 |
| — | 网站 | /sites | 网站列表与详情；启用与停用见 网站启停。列表上方的「网站 | 四层转发」切换到 L4 应用列表（/l4），见 四层转发 |
| — | 证书 | /certificates | 证书与 DNS 凭据，见 HTTPS 与证书 |
| — | 刷新预热 | /purge | URL、目录与全站刷新，URL 预热与任务，见 源站与缓存 |
| 访问控制 | 全局规则 | /rules | 作用于所有网站的规则，见 规则、IP 名单与 GeoIP |
| 访问控制 | IP 名单与封禁 | /ip-lists、/bans | 页面上方的「IP 名单 | 封禁」切换两个列表：供规则引用的名单与放行、拦截名单，见 规则、IP 名单与 GeoIP；网站封禁与全局封禁，见 封禁。/bans?site=<网站 ID> 只显示该网站的封禁，网站「安全」页签的「本站封禁」链接到这里 |
| 访问控制 | 防护设置 | /protection | 全局 Under Attack、CC 模板、封禁设置与 GeoIP 数据库，见 防护设置 |
| 基础设施 | 集群与节点 | /clusters | 集群、节点组、节点、配置金丝雀、节点升级、配置版本，集群的 DNS 绑定与智能调度，见 集群与节点。页面上方的「集群 | 区域」切换到区域（/clusters?view=regions），见 区域 |
| 基础设施 | DNS 调度 | /dns | DNS 服务商账号、各集群的 DNS 绑定与大面积摘除保护，见 配置 DNS 调度 |
| 系统 | 告警 | /alerts | 告警渠道、SMTP、告警订阅、近期告警与告警规则，见 告警页面 |
| 系统 | 审计日志 | /audit | 见 审计日志 |
| 系统 | 系统设置 | /system | 页签 通用、监控（/system?tab=probes，区域探针与探测设置，见 区域探针）与 服务账号（/system?tab=service-accounts，见 服务账号），见 系统设置 |
用户菜单
侧边栏底部显示账户的姓名与邮箱，点击打开用户菜单。
概览
概览（/overview）是登录后的首页。
| 区块 | 内容 |
|---|---|
| 待处理 | 需要处理的事项，每行带集群名称并链接到该集群；没有事项时不显示，见 待处理 |
| 网站 | 网站总数；先列加星标的网站，再按创建时间列出其他网站，最多 5 个。星标在 网站 列表或网站页面中设置 |
| 节点 | 在线节点数 / 节点总数；需要处理的节点在前：离线、应用失败、数据面异常、落后、待应用配置、等待心跳、已停用、已同步。无节点时显示 添加节点 |
| 最近发布 | 全部集群最近的配置版本及原因 |
| 最近访问 | 当前浏览器中最近打开的页面与网站，最多 5 个 |
| 统计 | 流量统计，时间范围 1 小时至 30 天（默认 24 小时）；指标卡片打开按网站、节点与状态码划分的明细。流量最高的网站、流量最高的节点 显示所属集群 |
待处理、节点与最近发布每 10 秒刷新，统计每分钟刷新。
其他路径
| 路径 | 说明 |
|---|---|
/ | 无页面：未初始化跳转 /setup，已登录跳转 /overview，否则跳转 /login |
/login | 登录 |
/setup | 初始化向导；初始化完成后跳转 /login |
/regions | 跳转 /clusters?view=regions；/regions?tab=probes 跳转 /system?tab=probes |
/service-accounts | 跳转 /system?tab=service-accounts |
故障排查
| 现象 | 原因 | 处理 |
|---|---|---|
| 验证码错误 | 两步验证的验证码不正确 | 核对验证器设备的时间后重试，或改用备用码 |
| 验证已过期，请重新登录 | 两步验证步骤超过 10 分钟 | 重新登录 |
| 请求太频繁，请稍后再试 | 触发登录限速 | 10 秒后重试 |
| 密码错误 | 修改密码、启用或停用两步验证时 当前密码 不正确 | 重新填写当前密码 |
| 通行密钥无法登录 | 控制台主机名已更换 | 用密码登录，删除旧通行密钥后重新添加 |
| 忘记密码 | Web 界面没有找回密码的入口 | 在服务器上重置密码，见 找回账户 |
| 验证器设备与备用码都已丢失 | 无法完成两步验证 | 在服务器上停用两步验证，见 找回账户；登录后重新启用 |
更换 BETTER_AUTH_SECRET 后两步验证一直失败 | TOTP 密钥与备用码用原来的 secret 加密，新 secret 无法解密 | 改回原来的 BETTER_AUTH_SECRET；原值已丢失时在服务器上停用两步验证，见 找回账户，登录后重新启用 |
找回账户
无法登录时，在运行控制台的服务器上执行 recover.js，为唯一的账户重置密码、停用两步验证，或两者都做。命令不经过 Web 界面，读取控制台容器的环境变量直接修改数据库。
-
执行命令；只需其中一项时去掉另一个选项：
docker compose exec console node dist/server/recover.js --reset-password --disable-two-factor宝塔 / aaPanel 部署的容器名为
edgeweir-console：docker exec -it edgeweir-console node dist/server/recover.js --reset-password --disable-two-factor -
命令输出账户的姓名与邮箱。带
--reset-password时，按提示输入两次新密码（12–128 字符），输入时不显示。 -
命令输出完成的操作后，用账户邮箱登录；重置了密码时用新密码。
-
停用了两步验证时，在 账户安全 重新启用，保存新的备用码。
| 项目 | 说明 |
|---|---|
| 会话 | 该账户的全部会话退出登录；已输入密码、尚未完成两步验证的登录失效 |
| 不变 | 姓名、邮箱、通行密钥与 AccessKey；怀疑账户被他人使用时，登录后检查并删除不认识的通行密钥与 AccessKey |
| 审计 | 写入 审计日志：account.recover，操作者为 系统（recover） |
选项、从文件读取密码、输出与退出码见 命令行。