Laravel Stats Tracker 项目升级指南

项目概述

Laravel Stats Tracker 是一个功能强大的用户行为追踪系统，可以帮助开发者记录和分析用户在网站上的各种行为数据。本文将详细介绍该项目的各个版本升级注意事项，帮助开发者顺利完成版本迁移。

从 2.0.x 升级到 3.0.0

主要变更

在配置文件中新增了缓存启用选项，这是3.0.0版本的核心改进之一。

升级步骤

1. 打开配置文件 config/tracker.php
2. 添加以下配置项：

/*
 * 是否启用缓存
 */
'cache_enabled' => true,

技术说明

启用缓存可以显著提高系统性能，特别是在高并发场景下。建议在生产环境中开启此选项。

从 2.0.x 升级到 2.0.4 或 2.0.9

数据库迁移问题处理

标准升级流程

1. 执行表结构生成命令：

   php artisan tracker:tables
   

2. 执行数据库迁移：

   php artisan migrate
   

外键约束错误处理

如果遇到"1215 Cannot add foreign key constraint"错误，请按以下步骤解决：

1. 回滚上次操作：

   php artisan tracker:tables
   

2. 删除以下迁移文件：

   • 2015_11_23_311097_create_tracker_languages_table.php
   • 2015_11_23_311098_add_language_id_column_to_sessions.php
   • 2015_11_23_311099_add_tracker_language_foreign_key_to_sessions.php
   • 2015_11_23_311100_add_nullable_to_tracker_error.php

3. 重新生成表结构：

   php artisan tracker:tables
   

4. 执行迁移：

   php artisan migrate
   

升级到 0.6.0

前端模板更新

由于前端模板进行了大规模更新，需要重新下载并替换：

1. 删除旧模板：

   rm -rf public/templates/sb-admin-v2
   

2. 下载新模板：

   wget --output-document=/tmp/sba2.zip 下载地址
   

3. 解压到指定目录：

   unzip /tmp/sba2.zip -d public/templates/
   

升级到 0.5.1

数据库结构调整

tracker_route_paths.route_id 列类型需要从字符串改为整型：

PostgreSQL 调整

ALTER TABLE "tracker_route_paths" ALTER COLUMN route_id TYPE BIGINT 
    USING CAST(CASE route_id WHEN '' THEN NULL ELSE route_id END AS BIGINT)

MySQL 调整

ALTER TABLE tracker_route_paths CHANGE route_id route_id bigint unsigned NULL;

新增配置项

在配置文件中添加以下内容：

'log_exceptions' => true,
'authenticated_user_username_column' => 'email',
'do_not_track_routes' => array(
    'tracker.stats.*',
),

升级到 0.5.0

统计面板更新

1. 下载新版统计面板：

   wget --output-document=/tmp/sba2.zip 下载地址
   unzip /tmp/sba2.zip -d public/templates/
   

2. 添加以下配置项：

/**
 * 是否启用统计面板
 */
'stats_panel_enabled' => false,

/**
 * 统计面板路由前置过滤器
 * 建议在此处添加 'auth' 过滤器
 */
'stats_routes_before_filter' => '',

/**
 * 统计面板模板路径
 */
'stats_template_path' => '/templates/sb-admin-v2',

/**
 * 统计面板基础URI
 * 例如设置为 'stats' 后，访问地址将为：http://yourdomain.com/stats
 */
'stats_base_uri' => 'stats',

/**
 * 统计面板布局视图
 */
'stats_layout' => 'pragmarx/tracker::layout',

/**
 * 统计面板控制器命名空间
 */
'stats_controllers_namespace' => 'PragmaRX\Tracker\Vendor\Laravel\Controllers',

3. 启用统计面板：

'stats_panel_enabled' => true,

升级到 0.4.0

新增日志配置

添加以下日志记录选项：

'log_geoip' => true,
'log_user_agents' => true,
'log_users' => true,
'log_devices' => true,
'log_referers' => true,
'log_paths' => true,
'log_queries' => true,
'log_routes' => true,

数据库结构调整

1. 修改 tracker_sessions 表，使 device_id 和 agent_id 列可为空
2. 修改 tracker_log 表，使 path_id 列可为空

升级到 0.3.2

机器人检测功能

1. 添加机器人标识列：

   ALTER TABLE tracker_sessions ADD is_robot BOOL;
   

2. 添加配置项：

   'do_not_track_robots' => true, // 或 false
   

3. 修改 tracker_events_log.class_id 列为可空

升级建议

1. 在升级前，务必备份数据库和重要配置文件
2. 建议在测试环境验证升级过程后再应用到生产环境
3. 关注各版本间的兼容性变化，特别是数据库结构调整
4. 对于大型项目，考虑分阶段升级，先升级次要版本再升级主要版本

通过遵循本指南，您可以顺利完成 Laravel Stats Tracker 的版本升级，获得新版本带来的功能改进和性能提升。