crowdsec-web-ui 上手实操:从创建管理员账号到 TOTP 双因素认证,第一步就做好安全基线
crowdsec-web-ui 上手实操:从创建管理员账号到 TOTP 双因素认证,第一步就做好安全基线
crowdsec-web-ui 是一个自托管的 CrowdSec 安全运营 Dashboard,用一套响应式 Web UI 集中完成告警调查、决策(decisions)管理、运行时指标监控和通知推送。本文按真实部署顺序走一遍上手流程:启动服务、创建初始管理员账号、再启用 TOTP 双因素认证,帮你在第一天就把安全基线搭好。
快速安装与启动:Docker Compose 一键部署
官方提供了一键可用的 docker-compose.yml,只需两步:
- 在 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 容器已有的凭据文件。
- 启动 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 连接正常
进入 Dashboard 后重点看右上角的 CrowdSec LAPI 状态卡片:显示 Online 说明 Web UI 与 CrowdSec 后端连接成功,可以开始同步告警和决策数据。下方的 Activity History 曲线、World Map 攻击地图和 Top Countries / Top Scenarios 等卡片,是日常安全运营的入口。
安全基线关键一步:配置 TOTP 双因素认证
管理员账号创建后,默认只有“用户名 + 密码”一层防护。建议在进入日常使用之前就完成 TOTP 绑定,把账号保护升级为“密码 + 动态验证码”双重校验(设置界面位于 client/src/pages/Settings.tsx 的 Authentication 区块):
- 进入 Settings → Authentication,找到 Authenticator app (TOTP) 区域,点击 Set Up TOTP;
- 弹窗中会生成一个 QR 码,用 Google Authenticator、1Password 等动态口令 App 扫描(扫不了可点 mobile setup link 或手动输入密钥);
- 在 App 中查看 6 位动态码,填入 Authenticator code 输入框,点击 Verify and enable;
- 成功后徽章从
Disabled变为Enabled,此后每次登录都需要输入验证码。
启用 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 的上手路径非常短:注册机器 → Docker 启动 → 创建管理员账号 → 绑定 TOTP,四步之内就能得到一个带双因素认证的自托管安全运营控制台。先做安全基线再投入日常使用,是这个项目值得借鉴的实践顺序。


