Ente Auth 迁移指南：使用 steamguard-cli 将 Steam 桌面验证器代码安全导入 Ente Auth-创锋一号

Ente Auth 迁移指南：使用 steamguard-cli 将 Steam 桌面验证器代码安全导入 Ente Auth

【免费下载链接】ente💚 End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente

Steam 桌面验证器（Steam Desktop Authenticator / SDA）将 Steam 账号的 2FA 密钥保存在本地 maFiles 文件中，一旦换机或丢失备份就面临账号被锁的风险。本指南基于 steam 迁移文档，给出从 Steam 桌面验证器迁移到 Ente Auth 的完整实操路径：借助第三方命令行工具 steamguard-cli 读取本地密钥并生成 QR 码，再用 Ente Auth 扫描导入。读完本文，你将掌握 steamguard-cli 在 Windows / Linux 下的安装与账号配置、QR 码生成与扫描导入的全流程，并从源码层面理解 Ente Auth 对 Steam 专用 TOTP 算法的底层支持原理。

前置要求与版本警告

[!WARNING] Steam Authenticator 的代码仅在 Ente Authv3.0.3 及以后版本中得到支持。迁移前请先检查应用版本号，若版本过低请先升级，否则扫描导入后会无法正常生成 Steam 验证码。

当前仓库中mobile/apps/auth/pubspec.yaml的版本号为4.4.26+1007，远高于 v3.0.3，因此使用当前版本迁移无需担心此限制；但如果你在使用旧版本应用，务必先升级。

迁移方案总览

Steam 桌面验证器与 Ente Auth 之间没有官方直连的导入通道，但 Steam 的 2FA 密钥本质上是一个 Base32 编码的共享密钥。官方推荐的迁移方式有两种：

使用 steamguard-cli 简化流程：利用 dyc3/steamguard-cli（文档中称 "this tool by dyc3"）读取 Steam 桌面验证器生成的 maFiles，直接导出对应的 2FA 密钥并渲染成 QR 码，随后在 Ente Auth 中扫描导入。
通用导入通道：若你的数据已导出为otpauth://totp/...格式的明文文件，也可以通过 Ente Auth 的通用导入功能完成迁移。Steam 密钥对应的 URI 为otpauth://steam/...（详见下文源码解析）。

本指南以方案 1 为主线展开，因为它无需手动拼接密钥，路径最短、出错率最低。

下载并安装 steamguard-cli

steamguard-cli 提供 Windows 可执行文件、Debian 安装包与通用 Linux 二进制三种分发形态。

Windows

从 steamguard-cli 的 releases 页面下载steamguard.exe。
将steamguard.exe放到任意你喜欢的目录，例如%USERPROFILE%\Desktop。
打开 PowerShell 或命令提示符，确保当前提示符位于%USERPROFILE%（例如C:\Users\<username>）。
使用cd切换到存放steamguard.exe的目录，本例为cd Desktop。
现在即可运行验证安装是否成功：

.\steamguard.exe --help

Linux

Ubuntu / Debian

从 releases 页面下载.deb安装包，然后在终端中安装：

sudo dpkg -i ./steamguard-cli_<version>_amd64.deb

其他 Linux 发行版

从 releases 页面下载steamguard二进制文件。
赋予执行权限，并将steamguard移动到/usr/local/bin或$PATH中的任意其他目录：

chmod +x ./steamguard sudo mv ./steamguard /usr/local/bin

steamguard --help

登录 Steam 账号

在安装好 steamguard-cli 后，需要先让它与你的 Steam 账号建立会话（登录时通常要求输入 Steam 用户名、密码，并完成当前验证器/邮箱的 2FA 确认，以获取刷新令牌并落盘 maFiles）：

steamguard setup # 用 steamguard-cli 新建一个账号配置

执行成功后，steamguard-cli 会在本地（Windows 下位于%USERPROFILE%\maFiles，Linux 下位于~/.config/steamguard-cli/maFiles）保存该账号的 2FA 密钥文件。请妥善保管这些文件——它们是后续生成 QR 码的数据来源，也是 Steam 账号 2FA 的凭证。

生成并导入 QR 码

生成 QR 码

steamguard-cli 可以直接为你的 2FA 密钥生成 QR 码：

steamguard qr # 为 maFiles 中的第一个账号打印 QR 码 steamguard -u <account name> qr # 为指定账号打印 QR 码

-u参数用于在存在多个账号时指定目标账号，账号名即steamguard setup时录入的名称。

在 Ente Auth 中扫描

打开 Ente Auth；
点击'+'按钮；
选择Scan a QR code；
对准终端中渲染出的 QR 码进行扫描。

扫描完成后，你的 Steam 验证码即已进入 Ente Auth。此后每次打开 Ente Auth 都能直接看到并复制 Steam 登录所需的 6 位（Steam 专用格式，实际为 5 位字母数字）验证码，无需再依赖 Steam 桌面验证器。

源码解析：Ente Auth 如何支持 Steam 验证码

迁移成功后验证码能够正常生成，依赖 Ente Auth 客户端对 Steam 专用 TOTP 算法的完整实现，可从以下源码文件印证：

1. Steam 类型与 URI 解析（code.dart）

Ente Auth 的Code模型将认证类型区分为totp、hotp与steam三种枚举（见enum Type，code.dart）：

enum Type { totp, hotp, steam; bool get isTOTPCompatible => this == totp || this == steam; bool get canShareCodes => this == totp || this == steam; }

当扫描到的 URI 主机名为steam（即otpauth://steam/...）时，解析器将其识别为Type.steam；并且当 URI 未显式声明digits参数时，Steam 类型会自动回退到steamDigits = 5（5 位字母数字码），而非普通 TOTP 的 6 位数字（见 code.dart 与 code.dart 中的_getDigits/_getType）。steamguard-cli 生成的 QR 码正是这种otpauth://steam/形式，因此能被 Ente Auth 直接识别。

2. Steam 验证码生成（totp_util.dart）

代码生成层在 totp_util.dart 中根据类型分流：当code.type == Type.steam或issuer为steam时，走专用路径_getSteamCode，否则才走标准 TOTP/HOTP 分支：

String getOTP(Code code) { if (code.type == Type.steam || code.issuer.toLowerCase() == 'steam') { return _getSteamCode(code); } if (code.type == Type.hotp) { return _getHOTPCode(code); } return otp.OTP.generateTOTPCodeString(...); }

Steam 的 TOTP 实现并非标准 6 位数字：它基于 SHA-1 与 Base32 密钥，但将生成的散列映射到 5 位字母数字字符集。Ente Auth 通过steam_totp依赖（pubspec.yaml 中声明为steam_totp: 0.0.2）实现这一算法，时间步长与普通 TOTP 一致：

String _getSteamCode(Code code, [bool isNext = false]) { final SteamTOTP steamtotp = SteamTOTP(secret: code.secret); return steamtotp.generate( millisecondsSinceEpoch() ~/ 1000 + (isNext ? code.period : 0), ); }

3. 扫码导入入口（scanner_page.dart）

文档中"'+' 按钮 → Scan a QR code"对应的实现位于 scanner_page.dart，该页面借助ente_qr_scanner包持续读取摄像头帧中的二维码文本，并将解析结果交给Code模型完成上述 URI 解析。整个链路为：摄像头捕获 QR 码 → 解析otpauth://steam/URI → 标记为Type.steam→ 调用 SteamTOTP 生成 5 位字母数字码。

验证迁移结果与常见问题

验证码是否能正常刷新：导入后观察验证码是否随时间倒计时刷新。若显示错误或空白，请确认 Ente Auth 版本 ≥ v3.0.3，并确认扫描的是包含完整密钥的 QR 码。
多账号场景：如果你的 maFiles 中存在多个 Steam 账号，务必使用steamguard -u <account name> qr逐个导出、逐个扫描，避免误导。
密钥文件安全：maFiles 与扫描生成的 QR 码都包含等效于账号 2FA 的全部信息，请勿截图上传或外发；迁移完成后可考虑在 Steam 端重置 2FA 或安全删除旧验证器文件。
无法生成 QR 码的替代路径：若 steamguard-cli 在你的平台不可用，可将 Steam 密钥按otpauth://totp/Steam:<account>?secret=<BASE32_SECRET>明文格式整理后，通过 Ente Auth 的通用明文导入导入（Ente Auth 同样支持 2FAS、Aegis、Google Authenticator、Bitwarden、Proton、Raivo OTP 等十余种来源的导入）。

企业官网建设流程全解析