Laravel Auditing 包在 Sanctum 认证下的用户追踪问题解决方案

在 Laravel 应用开发中，使用 Laravel Auditing 包进行模型变更审计时，开发者可能会遇到一个常见问题：当应用采用 Sanctum 进行 API 认证时，审计记录中的 user_id 和 user_type 字段无法正确填充。本文将深入分析问题原因并提供完整的解决方案。

问题现象分析

当使用 Laravel Sanctum 作为 API 认证方式时，虽然请求已通过认证且 auth()->user() 能正确返回用户对象，但审计记录中的用户相关字段仍为 null。这种情况通常发生在以下环境中：

• 采用 Laravel Sanctum 进行 API 认证
• 使用多租户架构（如 Stancl Tenancy）
• PostgreSQL 数据库
• 模型已正确实现 Auditable 接口

根本原因探究

Laravel Auditing 包默认通过 UserResolver 类来解析当前认证用户。该解析器会遍历应用配置中定义的所有认证守卫(guards)，尝试从每个守卫获取用户实例。问题在于：

1. Sanctum 使用特殊的认证机制，不同于传统的 session 或 token 守卫
2. 默认配置中可能未将 Sanctum 守卫包含在审计包的检查范围内
3. 多租户环境下可能需要额外的上下文处理

解决方案实现

方案一：修改配置文件

首先检查并修改 config/audit.php 配置文件，确保 Sanctum 守卫被包含：

'user' => [
    'guards' => ['web', 'api', 'sanctum'], // 添加 sanctum 守卫
    // 其他配置...
],

方案二：自定义用户解析器

对于更复杂的情况，可以创建自定义的用户解析器：

1. 创建新的解析器类：

namespace App\Resolvers;

use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Config;
use OwenIt\Auditing\Contracts\UserResolver;

class SanctumUserResolver implements UserResolver
{
    public static function resolve()
    {
        $guards = Config::get('audit.user.guards', [
            Config::get('auth.defaults.guard'),
        ]);

        foreach ($guards as $guard) {
            try {
                if ($user = Auth::guard($guard)->user()) {
                    return $user;
                }
            } catch (\Exception $e) {
                continue;
            }
        }

        return null;
    }
}

2. 注册自定义解析器：

在 AppServiceProvider 的 boot 方法中添加：

use OwenIt\Auditing\Facades\Auditor;

public function boot()
{
    Auditor::resolveUserUsing(new \App\Resolvers\SanctumUserResolver());
}

方案三：多租户环境适配

在多租户环境下，可能需要额外处理租户上下文。确保在解析用户前租户上下文已正确设置：

public static function resolve()
{
    if (!tenancy()->initialized) {
        return null;
    }

    // 其余解析逻辑...
}

最佳实践建议

1. 守卫顺序：将最常用的守卫放在配置数组前面，提高解析效率
2. 异常处理：妥善处理守卫可能抛出的异常，避免影响主要业务流程
3. 日志记录：在解析器中添加日志记录，便于调试用户解析过程
4. 性能考虑：避免在解析器中执行耗时的操作
5. 测试验证：编写测试用例验证各种认证场景下的审计记录

实现效果验证

实施上述解决方案后，审计记录应能正确记录以下信息：

• 操作用户的 ID 和类型
• 模型变更的完整历史
• 请求的上下文信息（IP、UserAgent 等）

通过本文的解决方案，开发者可以确保 Laravel Auditing 包在 Sanctum 认证环境下正常工作，为应用提供完整的审计追踪能力。