故障排查

本文档提供了 Unicode Framework 常见问题的排查和解决方法。

常见错误

500 内部服务器错误

问题：应用返回 500 错误 排查步骤：

检查日志文件

tail -f storage/logs/app.log
tail -f storage/logs/error.log

检查 PHP 错误日志

tail -f /var/log/php-fpm/error.log

检查文件权限

ls -la storage/
ls -la bootstrap/cache/

检查环境配置

<h1 id="确保-env-文件存在且配置正确">确保 .env 文件存在且配置正确</h1>
cat .env

解决方案

<h1 id="设置正确的文件权限">设置正确的文件权限</h1>
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache
<h1 id="清除缓存">清除缓存</h1>
php console route:clear
<h1 id="注意配置缓存由-config-类自动处理不需要-configclear-命令">注意：配置缓存由 Config 类自动处理，不需要 config:clear 命令</h1>
<h1 id="php-console-routeclear-如果需要可以清除路由缓存">php console route:clear  # 如果需要，可以清除路由缓存</h1>
<h1 id="检查-php-错误">检查 PHP 错误</h1>
php -v
php -m  # 查看已安装的扩展

路由未找到

问题

排查步骤

检查路由定义

// 检查 route.php 文件
cat route.php
cat app/index/route.php

检查路由缓存

<h1 id="清除路由缓存">清除路由缓存</h1>
php console route:clear
<h1 id="重新生成路由缓存">重新生成路由缓存</h1>
php console route:cache

检查路由顺序

// 确保具体路由在通用路由之前
Route::get('/users/new', [UserController::class, 'create']);  // 具体路由
Route::get('/users/{id}', [UserController::class, 'show']);   // 通用路由

解决方案

<h1 id="清除路由缓存">清除路由缓存</h1>
rm bootstrap/cache/routes.php
<h1 id="检查路由定义">检查路由定义</h1>
php console route:list

数据库连接失败

问题

排查步骤

检查数据库配置

<h1 id="检查-env-文件">检查 .env 文件</h1>
cat .env | grep DB_

测试数据库连接

mysql -u username -p -h host database_name

检查数据库服务

<h1 id="mysql">MySQL</h1>
sudo systemctl status mysql
<h1 id="postgresql">PostgreSQL</h1>
sudo systemctl status postgresql

解决方案

// 检查数据库配置
// config/database.php
return [
    'connections' => [
        'mysql' => [
            'host' => getenv('DB_HOST'),
            'database' => getenv('DB_DATABASE'),
            'username' => getenv('DB_USERNAME'),
            'password' => getenv('DB_PASSWORD'),
        ],
    ],
];

类未找到

问题

排查步骤

检查命名空间

// 确保命名空间正确
namespace App\Index\Controller;

检查自动加载

<h1 id="重新生成自动加载文件">重新生成自动加载文件</h1>
composer dump-autoload

检查类文件位置

<h1 id="确保文件在正确的位置">确保文件在正确的位置</h1>
ls -la app/Index/Controller/UserController.php

解决方案

<h1 id="重新生成自动加载">重新生成自动加载</h1>
composer dump-autoload --optimize
<h1 id="清除-opcache如果启用">清除 OPcache（如果启用）</h1>
php -r "opcache_reset();"

性能问题

响应缓慢

排查步骤

检查数据库查询

// 启用查询日志
// 检查是否有 N+1 查询

检查缓存

<h1 id="检查缓存是否正常工作">检查缓存是否正常工作</h1>
php -r "echo 'Cache test';"

检查服务器资源

<h1 id="检查-cpu-和内存使用">检查 CPU 和内存使用</h1>
top
htop

解决方案

// 优化数据库查询
// 使用预加载
$users = User::with('posts')->get();
// 使用索引
// 在迁移中创建索引
// 启用缓存
$cache->set('key', 'value', 3600);

内存不足

问题

排查步骤

检查内存使用

echo memory_get_usage() / 1024 / 1024 . " MB\n";
echo memory_get_peak_usage() / 1024 / 1024 . " MB\n";

检查大数据查询

// 避免一次性加载大量数据
// 使用分页
$users = db('users')->offset(0)->limit(20)->get();

解决方案

// 增加 PHP 内存限制
// php.ini
memory_limit = 256M
// 使用分页
$users = db('users')->paginate(20);
// 及时释放变量
unset($largeData);

数据库问题

迁移失败

问题

排查步骤

检查迁移文件

<h1 id="查看迁移文件">查看迁移文件</h1>
ls -la database/migrations/

检查数据库状态

<h1 id="查看迁移表">查看迁移表</h1>
mysql -u username -p -e "SELECT * FROM migrations;"

解决方案

<h1 id="回滚迁移">回滚迁移</h1>
php console migrate:rollback
<h1 id="重新运行迁移">重新运行迁移</h1>
php console migrate
<h1 id="检查迁移文件语法">检查迁移文件语法</h1>
php -l database/migrations/CreateUsersTable.php

查询超时

问题

排查步骤

检查查询语句

// 查看生成的 SQL
$query = db('users')->where('status', 'active');
echo $query->toSql();

检查索引

-- 查看表索引
SHOW INDEX FROM users;

解决方案

// 创建索引
public function up(): void
{
    $this->schema()->table('users', function($table) {
        $table->index('status');
    });
}
// 优化查询
$users = db('users')
    ->where('status', 'active')
    ->select(['id', 'name', 'email'])
    ->limit(100)
    ->get();

路由问题

路由冲突

问题

排查步骤

检查路由定义顺序

// 确保具体路由在通用路由之前
Route::get('/users/new', [UserController::class, 'create']);
Route::get('/users/{id}', [UserController::class, 'show']);

检查路由缓存

<h1 id="清除路由缓存">清除路由缓存</h1>
php console route:clear

解决方案

// 调整路由顺序
// 具体路由在前，通用路由在后

中间件不生效

问题

排查步骤

检查中间件注册

// 检查中间件是否正确注册
Route::middleware([JwtMiddleware::class], function() {
    Route::get('/profile', [UserController::class, 'profile']);
});

检查中间件类

// 确保中间件实现 MiddlewareInterface
class JwtMiddleware implements MiddlewareInterface
{
    public function handle(Request $request, callable $next): Response
    {
        // 中间件逻辑
    }
}

解决方案

// 确保中间件正确实现接口
// 检查中间件是否被正确调用

缓存问题

缓存不生效

问题

排查步骤

检查缓存配置

// 检查缓存驱动配置
config('cache.driver');

测试缓存

$cache->set('test', 'value', 60);
$value = $cache->get('test');
echo $value;  // 应该输出 'value'

解决方案

<h1 id="清除缓存">清除缓存</h1>
php console cache:clear
<h1 id="检查缓存目录权限">检查缓存目录权限</h1>
chmod -R 775 storage/cache

Redis 连接失败

问题

排查步骤

检查 Redis 服务

sudo systemctl status redis

测试 Redis 连接

redis-cli ping

检查 Redis 配置

// 检查 Redis 配置
config('cache.redis');

解决方案

<h1 id="启动-redis">启动 Redis</h1>
sudo systemctl start redis
<h1 id="检查-redis-配置">检查 Redis 配置</h1>
redis-cli CONFIG GET *

部署问题

文件权限问题

问题

排查步骤

检查文件权限

ls -la storage/
ls -la bootstrap/cache/

检查文件所有者

ls -l storage/

解决方案

<h1 id="设置正确的文件权限">设置正确的文件权限</h1>
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

环境变量未加载

问题

排查步骤

检查 .env 文件

cat .env

检查环境变量加载

echo getenv('APP_ENV');

解决方案

<h1 id="确保-env-文件存在">确保 .env 文件存在</h1>
cp .env.example .env
<h1 id="重新加载环境变量">重新加载环境变量</h1>
<h1 id="重启-php-fpm">重启 PHP-FPM</h1>
sudo systemctl restart php8.1-fpm

调试技巧

启用调试模式

// .env APP_DEBUG=true

// 查看详细错误信息

使用 dump 函数

// 使用框架提供的 dump 函数
dump($variable);
dump($var1, $var2, $var3);

查看日志

<h1 id="实时查看日志">实时查看日志</h1>
tail -f storage/logs/app.log
<h1 id="查看错误日志">查看错误日志</h1>
tail -f storage/logs/error.log

检查配置

// 检查配置值
echo config('app.name');
echo config('database.default');

获取帮助

如果问题仍未解决，可以：

查看框架日志
检查 PHP 错误日志
查看相关文档
提交 Issue

故障排查

故障排查

常见错误

500 内部服务器错误

路由未找到

数据库连接失败

类未找到

性能问题

响应缓慢

内存不足

数据库问题

迁移失败

查询超时

路由问题

路由冲突

中间件不生效

缓存问题

缓存不生效

Redis 连接失败

部署问题

文件权限问题

环境变量未加载

调试技巧

启用调试模式

使用 dump 函数

查看日志

检查配置

获取帮助

相关文档