PiKVM 双因素认证（2FA/TOTP）配置指南：为 KVMD 3.196+ 的 Web 界面、API 与 VNC 登录增加一次性密码保护

PiKVM 双因素认证2FA/TOTP配置指南为 KVMD 3.196 的 Web 界面、API 与 VNC 登录增加一次性密码保护【免费下载链接】pikvmOpen and inexpensive DIY IP-KVM based on Raspberry Pi项目地址: https://gitcode.com/gh_mirrors/pi/pikvm本文基于 PiKVM 官方发布公告KVMD 3.196 版本引入 2FA 支持与认证文档系统讲解在 PiKVM 上启用基于 TOTP基于时间的一次性密码的双因素认证的完整流程——从系统更新、NTP 校时、kvmd-totp命令行工具的使用到 Web 登录页、HTTP API 与 VNC 三种接入场景下的密码组合规则并补充仓库源码与配置层面的实现佐证。读完本文你将能把任何一台 KVMD ≥ 3.196 的 PiKVM 设备V1/V2 DIY、V3、V4 均适用安全地暴露到不可信网络如公网中同时为 Linuxroot账户、KVM 账户建立一套完整的凭据加固方案。背景KVMD 3.196 带来了什么PiKVM 是一个基于 Raspberry Pi 的开源 DIY IP-KVM 项目项目主页通过 Web 界面、VNC 或 IPMI 等方式远程管理服务器的键盘、视频与鼠标。长期以来PiKVM 的认证体系只依赖用户名 密码默认 KVM 用户为admin/admin一旦密码泄露攻击者即可完全控制被管服务器。2023-01-23 发布的 KVMD 3.196 首次为 PiKVM 加入了**双因素认证2FA**支持对应发布公告见 docs/blog/posts/2023/2023-01-23/index.md。其实现基于标准的TOTPRFC 6238基于时间的一次性密码算法与主流身份验证器 AppGoogle Authenticator、Authy 等完全兼容。官方在发布公告中特别指出如果计划将 PiKVM 暴露到公网或部署在不受信任的网络中强烈建议启用 2FA。启用后KVM 的 Web 登录页会新增一个2FA code输入框所有 Web UI 用户登录时都必须同时提供密码与 6 位一次性验证码。2FA 的适用边界与账户体系在动手之前需要先理清 PiKVM 的认证实体因为2FA 只保护 KVM 相关的接入通道不保护 Linux 系统级账户。根据 docs/auth.md 的说明PiKVM 存在以下认证主体认证主体默认凭据用途是否受 2FA 保护Linux OS 级管理员rootroot/rootSSH、串口控制台、Web Terminal 提权❌ 不受保护需自行设置强密码或 SSH 密钥KVM 用户adminadmin/adminWeb UI 登录、HTTP API、VNC 等✅ 受 2FA 保护OS 用户kvmd-webterm无不可登录仅用于 Web Terminal禁用sudo与密码访问—VNCAuth key默认禁用VNC 认证—IPMI 密码默认禁用IPMI 接入—两个账户是相互独立的。设备到手后第一件事就是同时修改这两套默认密码否则仅开启 2FA 并不会阻止攻击者通过 SSH 以root/root直接登录系统。在 Web Terminal 中获取 root 权限大多数管理命令需要 root 权限。Web Terminal 默认运行在受限用户kvmd-webterm下通过su -并输入 root 密码即可提升[kvmd-webtermpikvm ~]$ su - ... [rootpikvm kvmd-webterm]#如果你希望彻底关闭 Web Terminal 的控制台访问例如设备的实际使用者和拥有者不是同一人可以执行[rootpikvm ~]# rw [rootpikvm ~]# systemctl disable --now kvmd-webterm [rootpikvm ~]# ro此时你依然可以通过 SSH 访问 PiKVM 系统。启用 2FA 的完整操作步骤官方文档docs/auth.md#two-factor-authentication给出了六步启用流程以下结合 docs/_update_os.md 与仓库命令约定逐条展开。第 1 步更新系统并重启2FA 功能自 KVMD 3.196 起可用因此首先要确保 KVMD 版本满足要求。PiKVM OS 默认以只读文件系统运行所有写操作前需要先执行rw切换为可写操作结束后再ro切回[rootpikvm ~]# rw [rootpikvm ~]# pacman -Syu [rootpikvm ~]# reboot官方发布公告中给出的正是这一组命令rw→pacman -Syu→reboot。对于较新的 PiKVM OS更推荐使用封装好的pikvm-update一键更新脚本如果提示bash: pikvm-update: command not found说明 OS 版本过旧需先执行pacman -Syy pacman -S pikvm-os-updater安装更新器后再运行pikvm-update详见 docs/_update_os.md。第 2 步确认 NTP 时间同步TOTP 的核心是对时间的依赖——验证码由“当前时间 共享密钥”推导而来时间偏差会导致验证码校验失败。因此必须确保 NTP 服务正在运行[rootpikvm ~]# timedatectl重点确认系统时间已同步System clock synchronized: yes。时区不影响 TOTP 正确性无需修改。第 3 步在手机安装身份验证器 App在移动设备上安装Google AuthenticatoriOS / Android 均可它将负责在登录时生成 6 位一次性验证码。任何兼容 TOTP 的验证器如 Authy、Microsoft Authenticator也可以使用。第 4 步在 PiKVM 上初始化 TOTP 密钥执行以下命令生成共享密钥[rootpikvm ~]# rw [rootpikvm ~]# kvmd-totp init [rootpikvm ~]# rokvmd-totp是 KVMD 提供的 TOTP 管理命令行工具其完整子命令如下命令功能kvmd-totp init初始化/重新生成共享密钥并在终端以 ASCII 艺术形式渲染出 QR 码kvmd-totp show再次显示当前密钥对应的 QR 码方便多设备扫码或找回kvmd-totp del删除密钥即关闭 2FA小彩蛋正如发布公告中所提到的kvmd-totp init会在终端里直接用 ASCII 字符绘制 QR 码——在纯文本终端SSH、Web Terminal中也能完成扫码无需图形界面。第 5 步扫码绑定验证器打开 Google Authenticator选择“添加账户”→“扫描二维码”扫描上一步在终端中输出的 QR 码。绑定完成后App 会每 30 秒滚动生成一个 6 位验证码。第 6 步登录时输入验证码绑定完成后PiKVM 登录页会出现2FA code输入框如上方界面截图所示。所有 Web UI 用户登录时都必须在输入密码之后再填写当前验证码。需要特别注意的是共享密钥对所有用户是同一个kvmd-totp管理的是一份全局密钥默认存放在/etc/kvmd/totp.secret即所有 KVM 用户共用同一套一次性验证码2FA 只负责“你是否持有这个密钥载体”的二次验证并不区分具体用户。API 与 VNC 场景下的 2FA密码拼接规则2FA 并不只在 Web 登录页生效。对于 API 或 VNC 认证VNCAuth 模式除外需要将一次性验证码直接追加到密码后面中间不留空格。例如密码为foobar当前验证码为123456则实际提交的密码为foobar123456这一规则同样适用于脚本化接入 HTTP API 的场景。docs/api.md中给出了使用 Pythonpyotp库自动计算验证码并发起 API 请求的完整示例import requests import pyotp user admin passwd admin secret 3OBBOGSJRYRBZH35PGXURM4CMWTH3WSU # 可在 /etc/kvmd/totp.secret 中找到 print(requests.get( urlhttps://pikvm/api/info, verifyFalse, # 默认安装使用自签名证书 headers{ X-KVMD-User: user, X-KVMD-Passwd: passwd pyotp.TOTP(secret).now(), }, ).text)对应命令行curl写法使用X-KVMD-User/X-KVMD-Passwd请求头进行单次请求认证$ curl -k -H X-KVMD-User:admin -H X-KVMD-Passwd:admin6位验证码 https://pikvm-ip/api/auth/check由于存在“验证码恰好处于 30 秒有效期边界”的边界情况文档建议在代码中处理 403 错误时自动重试或更稳妥地在发起请求前主动检查验证码剩余有效期totp pyotp.TOTP(secret) now int(time.time()) remaining now - (now % totp.interval)密码管理与安全加固修改 Linux root 密码2FA 不覆盖系统账户因此 root 必须使用高强度密码或配置 SSH 密钥登录[rootpikvm ~]# rw [rootpikvm ~]# passwd root [rootpikvm ~]# ro修改 KVM 密码htpasswd 体系KVM 用户默认采用类似 Apache Server 的认证方式用户与密码加密存储在/etc/kvmd/htpasswd中通过kvmd-htpasswd工具管理[rootpikvm ~]# rw [rootpikvm ~]# kvmd-htpasswd set admin [rootpikvm ~]# ro也可以创建多个 KVM 用户注意所有 KVM 用户拥有相同权限目前无法为不同用户配置 ACL[rootpikvm ~]# kvmd-htpasswd add user # 新增用户并设置密码 [rootpikvm ~]# kvmd-htpasswd list # 列出所有用户 [rootpikvm ~]# kvmd-htpasswd del user # 删除用户补充加固会话过期与按需禁用认证配置会话过期时间从 KVMD 4.53 起Web 登录页可选择会话时长1 小时 / 12 小时 / 无限。你还可以通过配置文件设置全局默认的会话上限此限制仅对 Web UI 生效VNC 会话始终为无限期。编辑/etc/kvmd/override.yamlkvmd: auth: expire: 21600 # 21600 秒 6 小时然后重启服务并验证[rootpikvm ~]# systemctl restart kvmd [rootpikvm ~]# journalctl -u kvmd -g Maximum user session ... INFO --- Maximum user session time is limited: 6:00:00关于会话过期的两个实现细节docs/auth.md#session-expiration 原文说明PiKVM 的视频流大量依赖 WebSocket 与长连接 HTTP。会话过期会使授权 cookie 失效新连接无法建立但已建立的长连接不会立即中断直到用户关闭浏览器标签页——该机制主要防止用户关闭浏览器却不点击 Logout 时留下无限会话点击主页面上的Logout按钮会注销该用户在所有浏览器中的全部会话。完全禁用认证谨慎如果确实需要例如纯内网环境可以关闭 KVM 接入Web UI、VNC 等SSH 除外的认证。官方明确警告不要在不受信任的网络中这样做否则可能把被管服务器直接暴露给潜在攻击者kvmd: auth: enabled: false应用配置并建议同时关闭 Web Terminal[rootpikvm ~]# systemctl restart kvmd [rootpikvm ~]# systemctl disable --now kvmd-webterm # 可选若你保留 SSH 访问 [rootpikvm ~]# ro从源码与配置看实现细节密钥存储TOTP 共享密钥默认保存在/etc/kvmd/totp.secretkvmd-totp工具负责其生成、展示与删除。该路径在 docs/auth_advanced.md 的totp配置项中亦有印证且可在 KVMD 配置中自定义。可插拔认证架构2FA/TOTP 并非独立的认证后端而是叠加在htpasswd、PAM、LDAP、RADIUS 等认证方法之上的全局附加层见 docs/auth_advanced.md 中的说明“2FA/TOTP is always available, works locally and is compatible with all the methods listed here”。无论你为 PiKVM 配置了何种内部/外部认证方式TOTP 验证码都会在密码之后参与校验。与认证配置的关系/etc/kvmd/override.yaml中kvmd.auth.enabled全局开关与kvmd.auth.expire会话过期等键位在 docs/auth_advanced.md 中有完整参数说明修改后统一通过systemctl restart kvmd生效。结语公网暴露前的安全检查清单将 PiKVM 暴露到公网之前建议按顺序完成以下加固完整清单与更多细节见 docs/auth.md 与 docs/cheatsheet.md更新系统至 KVMD ≥ 3.196推荐pikvm-update并确认 NTP 已同步修改root密码或配置 SSH 密钥修改 KVM 用户admin密码执行kvmd-totp init并用 Google Authenticator 扫码绑定为 Web 登录页配置合理的会话过期时间kvmd.auth.expire若需要脚本/API 接入牢记“密码 验证码直接拼接”的规则妥善保管/etc/kvmd/totp.secret丢失密钥载体将需要重新执行kvmd-totp init或使用kvmd-totp del彻底关闭 2FA。2FA 不能替代强密码但结合上述全部措施PiKVM 即便部署在公网攻击者也需要同时窃取密码与持有验证器设备才能进入管理界面——这正是 KVMD 3.196 发布公告所说的“提升 PiKVM 安全性的机会”。【免费下载链接】pikvmOpen and inexpensive DIY IP-KVM based on Raspberry Pi项目地址: https://gitcode.com/gh_mirrors/pi/pikvm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考