crowdsec-web-ui 上手实操:从创建管理员账号到 TOTP 双因素认证,第一步就做好安全基线

原创2026-10-26 15:47:112,187 阅读

crowdsec-web-ui 上手实操:从创建管理员账号到 TOTP 双因素认证,第一步就做好安全基线

crowdsec-web-ui 是一个自托管的 CrowdSec 安全运营 Dashboard,用一套响应式 Web UI 集中完成告警调查、决策(decisions)管理、运行时指标监控和通知推送。本文按真实部署顺序走一遍上手流程:启动服务、创建初始管理员账号、再启用 TOTP 双因素认证,帮你在第一天就把安全基线搭好。

快速安装与启动:Docker Compose 一键部署

官方提供了一键可用的 docker-compose.yml,只需两步:

  1. 在 CrowdSec 侧注册 Web UI 这台“机器”(生成随机密码并登记):
openssl rand -hex 32
sudo cscli machines add crowdsec-web-ui --password 'replace-with-generated-password' -f /dev/null

⚠️ 务必保留 -f /dev/null 参数,它表示只注册而不覆盖 CrowdSec 容器已有的凭据文件。

  1. 启动 Web UI 容器,把生成的密码填入 CONFIG_INSTANCE_LAPI_AUTH_PASSWORD:
docker compose up -d

浏览器打开 http://localhost:3000,就会看到初始安装页。更多连接方式(如 agent mTLS)见 README.md 的 Quick Start 章节。

第一步:创建初始管理员账号

首次访问 http://localhost:3000 时,crowdsec-web-ui 会强制进入 “Initial setup” 页面——这是内置的安全设计:在管理员账号存在之前,任何人都无法访问控制台(对应 client/src/pages/Setup.tsx 中的 Setup 页面逻辑)。

创建账号时有两条硬性要求:

要求 说明
用户名 任意非空字符串,建议用 admin
密码 至少 8 位,且必须同时包含大写字母、小写字母和数字

密码规则由前端的 validatePassword 函数强制校验,不满足会直接报错,无法提交。点击 Create Account 后,账号即创建完成并自动登录进入控制台,左侧导航会看到 Dashboard、Alerts、Decisions、Notifications、Metrics、Settings 六大模块。

登录后先看仪表盘:确认 LAPI 连接正常

crowdsec-web-ui 仪表盘概览

进入 Dashboard 后重点看右上角的 CrowdSec LAPI 状态卡片:显示 Online 说明 Web UI 与 CrowdSec 后端连接成功,可以开始同步告警和决策数据。下方的 Activity History 曲线、World Map 攻击地图和 Top Countries / Top Scenarios 等卡片,是日常安全运营的入口。

安全基线关键一步:配置 TOTP 双因素认证

管理员账号创建后,默认只有“用户名 + 密码”一层防护。建议在进入日常使用之前就完成 TOTP 绑定,把账号保护升级为“密码 + 动态验证码”双重校验(设置界面位于 client/src/pages/Settings.tsx 的 Authentication 区块):

  1. 进入 Settings → Authentication,找到 Authenticator app (TOTP) 区域,点击 Set Up TOTP;
  2. 弹窗中会生成一个 QR 码,用 Google Authenticator、1Password 等动态口令 App 扫描(扫不了可点 mobile setup link 或手动输入密钥);
  3. 在 App 中查看 6 位动态码,填入 Authenticator code 输入框,点击 Verify and enable;
  4. 成功后徽章从 Disabled 变为 Enabled,此后每次登录都需要输入验证码。

crowdsec-web-ui 设置页 TOTP 双因素认证配置

启用 TOTP 后的登录流程会在 client/src/pages/Login.tsx 中体现:提交账号密码后,后端会返回 requiresTotp 标志,登录页随即追加动态码输入框,两步都通过才放行。

进阶加固建议

  • 关闭纯密码登录:当账号已配置 passkey 或 OIDC 单点登录后,可在 Authentication 区域勾选 Disable password login,只允许更强的认证方式;
  • 配置密钥保护:服务端用 auth.totpSecret(可通过环境变量 CONFIG_AUTH_TOTP_SECRET 注入)对每个账号的 TOTP seed 做加密存储,生产环境建议从密钥管理而非配置文件明文提供,参考 config.example.yaml;
  • 注册 Passkey:同页面下方支持注册硬件安全密钥 / 平台通行密钥,实现无密码登录。

顺手验证:告警列表已可用

安全基线搭好后,点进左侧 Alerts 模块,可以看到同步过来的 CrowdSec 告警:每行展示 Scenario、来源国家、AS、IP 段、目标(如 ssh、firewall)以及当前生效的决策数,支持直接对告警执行操作。

crowdsec-web-ui 告警列表界面

小结

crowdsec-web-ui 的上手路径非常短:注册机器 → Docker 启动 → 创建管理员账号 → 绑定 TOTP,四步之内就能得到一个带双因素认证的自托管安全运营控制台。先做安全基线再投入日常使用,是这个项目值得借鉴的实践顺序。

更多功能细节(多实例管理、OIDC 配置、只读模式等)可查阅 README.md 与 API.md。

登录后查看全文
crowdsec-web-ui