最佳选择：spomky-labs/otphp（RFC 标准，活跃维护）做 TOTP，lbuchs/WebAuthn 做 Passkey。 ┌─────────────────────────────┬───────────────────┬────────────┐ │ 方式 │ 库 │ 场景 │ ├─────────────────────────────┼───────────────────┼────────────┤ ────────────────────── │ TOTP(Google Authenticator)│ spomky-labs/otphp │ 主流 MFA │ ├─────────────────────────────┼───────────────────┼────────────┤ │ WebAuthn/Passkey │ lbuchs/WebAuthn │ 无密码登录 │ ├─────────────────────────────┼───────────────────┼────────────┤ │ 备用码 │ 原生实现 │ 兜底方案 │ └─────────────────────────────┴───────────────────┴────────────┘ --- 安装composerrequire spomky-labs/otphp bacon/bacon-qr-code ---1. TOTP 绑定与验证<?php namespace App\Service;use OTPHP\TOTP;use BaconQrCode\Renderer\ImageRenderer;use BaconQrCode\Renderer\Image\SvgImageBackEnd;use BaconQrCode\Renderer\RendererStyle\RendererStyle;use BaconQrCode\Writer;class MfaService{// 生成密钥 + 二维码 publicfunctionsetup(string$userEmail): array{$totp=TOTP::generate();$totp->setLabel($userEmail);$totp->setIssuer(env('APP_NAME','MyApp'));$writer=new Writer(new ImageRenderer(new RendererStyle(200), new SvgImageBackEnd()));$qrCode=base64_encode($writer->writeString($totp->getProvisioningUri()));return['secret'=>$totp->getSecret(),'qr_svg'=>$qrCode,];}// 验证 OTP publicfunctionverify(string$secret, string$code): bool{$totp=TOTP::createFromSecret($secret);return$totp->verify($code, null,1);// 允许前后1个时间窗口}// 生成备用码 publicfunctiongenerateBackupCodes(): array{returnarray_map(fn()=>strtoupper(bin2hex(random_bytes(4))).'-'.strtoupper(bin2hex(random_bytes(4))), range(1,8));}}---2. MFA 控制器<?php namespace App\Controller;use App\Service\MfaService;use Hyperf\HttpServer\Annotation\Controller;use Hyperf\HttpServer\Annotation\PostMapping;use Hyperf\HttpServer\Annotation\GetMapping;#[Controller(prefix: '/api/mfa')]class MfaController{publicfunction__construct(private MfaService$mfa){}// 初始化绑定#[GetMapping(path: 'setup')]publicfunctionsetup(): array{$user=auth()->user();$data=$this->mfa->setup($user->email);// 临时存 session，确认后再持久化 session(['mfa_secret_pending'=>$data['secret']]);return['qr_svg'=>$data['qr_svg']];}// 确认绑定#[PostMapping(path: 'confirm')]publicfunctionconfirm(): array{$secret=session('mfa_secret_pending');$code=$this->request->input('code');if(!$secret||!$this->mfa->verify($secret,$code)){return$this->response->json(['error'=>'Invalid code'],422);}$backupCodes=$this->mfa->generateBackupCodes();auth()->user()->update(['mfa_secret'=>encrypt($secret),'mfa_enabled'=>true,'mfa_backup_codes'=>encrypt(json_encode(array_map('password_hash',$backupCodes, array_fill(0,8, PASSWORD_BCRYPT)))),]);return['backup_codes'=>$backupCodes];// 仅展示一次}// 登录时验证#[PostMapping(path: 'verify')]publicfunctionverify(): array{$user=auth()->user();$code=$this->request->input('code');$secret=decrypt($user->mfa_secret);if($this->mfa->verify($secret,$code)){session(['mfa_passed'=>true]);return['verified'=>true];}// 尝试备用码if($this->verifyBackupCode($user,$code)){session(['mfa_passed'=>true]);return['verified'=>true,'backup_used'=>true];}return$this->response->json(['error'=>'Invalid code'],401);}privatefunctionverifyBackupCode($user, string$input): bool{$codes=json_decode(decrypt($user->mfa_backup_codes),true);foreach($codesas$i=>$hash){if(password_verify(strtoupper($input),$hash)){$codes[$i]='USED';// 一次性消费$user->update(['mfa_backup_codes'=>encrypt(json_encode($codes))]);returntrue;}}returnfalse;}}---3. MFA 中间件（强制二步验证）<?php namespace App\Middleware;use Psr\Http\Message\ResponseInterface;use Psr\Http\Message\ServerRequestInterface;use Psr\Http\Server\MiddlewareInterface;use Psr\Http\Server\RequestHandlerInterface;class MfaMiddleware implements MiddlewareInterface{publicfunctionprocess(ServerRequestInterface$request, RequestHandlerInterface$handler): ResponseInterface{$user=auth()->user();if($user?->mfa_enabled&&!session('mfa_passed')){return$this->response->json(['error'=>'MFA required','redirect'=>'/mfa/verify'],403);}return$handler->handle($request);}}路由注册： Router::addGroup('/api/admin',function(){Router::get('/dashboard',[DashboardController::class,'index']);},['middleware'=>[AuthMiddleware::class, MfaMiddleware::class]]);---4. Migration Schema::table('users',function(Blueprint$table){$table->boolean('mfa_enabled')->default(false);$table->text('mfa_secret')->nullable();$table->text('mfa_backup_codes')->nullable();});--- 核心要点： - 密钥用 encrypt()存储，不明文入库 - 备用码用 password_hash 存哈希，使用后标记 USED - verify()第三参数1=允许30秒时钟偏差 - MFA 状态存 session，敏感路由加 MfaMiddleware
