求助：Secureye S-FB3K考勤机与Laravel自定义考勤系统集成方案

核心前提：获取设备通信协议 #

首先必须拿到Secureye S-FB3K的官方通信协议文档（HTTP接口说明/TCP数据包格式），如果官网找不到，直接联系厂商技术支持索要——这是所有集成工作的基础，没有协议文档后续都是瞎试。

方案一：Laravel主动拉取考勤数据 #

适合设备无主动推送功能，或你希望控制数据同步节奏的场景：

• 步骤1：配置设备网络
  确保考勤机和Laravel服务器在同一局域网（或设备能访问到服务器公网地址），记录设备的IP地址、通信端口（通常默认是80或专门的考勤端口，比如5000）。
• 步骤2：编写Laravel数据拉取逻辑
  创建自定义Artisan命令，通过HTTP请求或Socket连接设备拉取数据：

  // app/Console/Commands/PullAttendance.php
  namespace App\Console\Commands;
  
  use Illuminate\Console\Command;
  use GuzzleHttp\Client;
  
  class PullAttendance extends Command
  {
      protected $signature = 'attendance:pull';
      protected $description = 'Pull attendance records from Secureye S-FB3K';
  
      public function handle()
      {
          $client = new Client();
          // 假设设备提供HTTP接口获取考勤记录
          $response = $client->get('http://{DEVICE_IP}/api/attendance', [
              'query' => [
                  'start_time' => now()->subHour()->toDateTimeString(),
                  'end_time' => now()->toDateTimeString()
              ]
          ]);
  
          $records = json_decode($response->getBody(), true);
          foreach ($records as $record) {
              // 解析数据并存储到数据库，注意去重
              \App\Models\Attendance::updateOrCreate(
                  ['device_record_id' => $record['id'], 'employee_id' => $record['emp_id']],
                  ['check_time' => $record['time'], 'type' => $record['type']]
              );
          }
  
          $this->info('Attendance records pulled successfully');
      }
  }
  

• 步骤3：设置定时任务
  在app/Console/Kernel.php中添加定时任务，定期执行拉取命令：

  protected function schedule(Schedule $schedule)
  {
      $schedule->command('attendance:pull')->everyFifteenMinutes();
  }
  

方案二：考勤机主动推送数据到Laravel #

适合需要实时同步考勤记录的场景：

• 步骤1：创建Laravel接收接口
  编写API接口接收设备推送的考勤数据，同时做IP白名单验证确保安全：

  // app/Http/Controllers/AttendanceWebhookController.php
  namespace App\Http\Controllers;
  
  use Illuminate\Http\Request;
  use App\Models\Attendance;
  
  class AttendanceWebhookController extends Controller
  {
      public function store(Request $request)
      {
          // 验证请求来源IP是否为考勤机IP
          $allowedIps = ['192.168.1.100']; // 替换为你的考勤机IP
          if (!in_array($request->ip(), $allowedIps)) {
              return response()->json(['status' => 'error'], 403);
          }
  
          $validated = $request->validate([
              'emp_id' => 'required|exists:employees,id',
              'check_time' => 'required|date',
              'type' => 'required|in:IN,OUT'
          ]);
  
          Attendance::create($validated);
          return response()->json(['status' => 'success']);
      }
  }
  

  在routes/api.php中注册路由：

  Route::post('/attendance/webhook', [AttendanceWebhookController::class, 'store']);
  

• 步骤2：配置考勤机推送设置
  登录考勤机的Web管理后台（通常是访问设备IP），找到“数据推送”或“Webhook”设置项：
  • 填写推送URL为你的Laravel接口地址（比如http://your-server.com/api/attendance/webhook）
  • 设置推送格式为JSON或表单（根据接口适配）
  • 开启实时推送或按固定间隔推送
• 步骤3：调试与验证
  在Laravel的storage/logs/laravel.log中查看请求日志，确认设备推送的数据是否被正确接收和存储。

关键注意事项 #

• 员工ID映射：确保考勤机内的员工ID与Laravel系统中的员工ID完全一致，可通过批量导入/导出功能完成同步。
• 数据去重：无论拉取还是推送，都要通过设备记录ID或员工ID+打卡时间来避免重复存储数据。
• 网络安全：如果服务器暴露在公网，一定要做IP白名单限制，避免恶意请求；接口可添加token验证进一步加固。
• 抓包调试：如果没有协议文档，可使用Wireshark抓取设备与测试工具的通信数据包，分析数据格式。

内容的提问来源于stack exchange，提问作者Amit Kumar