Laravel项目Ubuntu迁移指南

Laravel项目 Ubuntu 迁移指南

一 迁移准备与检查清单

• 在原服务器完成代码与数据的最终一致：提交或暂存变更，导出数据库结构与数据（避免导出敏感数据），记录或导出APP_KEY、队列、调度、第三方服务密钥等配置。
• 梳理运行环境：目标机器的Ubuntu 版本、PHP 版本与扩展、Web 服务器（Nginx/Apache）、数据库（MySQL/MariaDB）版本需满足项目要求。
• 准备目标机器的发布用户与目录结构：建议创建专用用户（如www-data或部署用户），项目放置在**/var/www/**，并确保目录所有权与权限正确。
• 规划迁移方式：优先使用版本控制（如 Git）拉取代码；若使用打包传输，确保排除敏感文件（如 .env、storage/logs、node_modules）并在目标机重新安装依赖。

二 目标服务器环境搭建

• 更新系统并安装基础组件：
  • sudo apt update && sudo apt upgrade -y
  • sudo apt install -y curl wget unzip
• 安装 PHP 与常用扩展（以 PHP 8.3 为例，可按项目需求调整版本）：
  • sudo apt install -y php php-cli php-fpm php-mysql php-zip php-gd php-mbstring php-curl php-xml php-bcmath
• 安装与配置 Composer：
  • curl -sS https://getcomposer.org/installer | php
  • sudo mv composer.phar /usr/local/bin/composer
  • composer --version
• 安装数据库（以 MySQL 8.0 为例）：
  • sudo apt install -y mysql-server
  • sudo mysql_secure_installation
• 说明：以上为在 Ubuntu 24.04 上的常见做法，其他版本或发行版步骤类似，注意 PHP 版本与扩展匹配项目需求。

三 代码与数据迁移

• 代码迁移（推荐 Git 方式）：
  • cd /var/www
  • git clone myproject
  • cd myproject
  • composer install --optimize-autoloader --no-dev
• 代码迁移（打包传输方式）：
  • 打包：tar czf myproject.tar.gz myproject/（排除 .env、storage/logs、node_modules 等）
  • 传输并解压到 /var/www
  • cd /var/www/myproject && composer install --optimize-autoloader --no-dev
• 数据库迁移：
  • 在目标库创建数据库与用户（示例）：
    • CREATE DATABASE laravel CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
    • CREATE USER ‘laravel’@‘localhost’ IDENTIFIED BY ‘StrongPassword!’;
    • GRANT ALL PRIVILEGES ON laravel.* TO ‘laravel’@‘localhost’;
    • FLUSH PRIVILEGES;
  • 导入结构与数据：mysql -u laravel -p laravel < backup.sql
  • 配置 .env：
    • DB_CONNECTION=mysql
    • DB_HOST=127.0.0.1
    • DB_PORT=3306
    • DB_DATABASE=laravel
    • DB_USERNAME=laravel
    • DB_PASSWORD=StrongPassword!
  • 生成应用密钥并迁移：
    • php artisan key:generate
    • php artisan migrate --force
• 说明：迁移后务必核对 .env 配置、执行迁移并确认目录权限，确保应用可正常启动。

四 Web 服务器配置

• Nginx 配置示例（站点配置：/etc/nginx/sites-available/myproject）：
  • server { listen 80; server_name yourdomain.com www.yourdomain.com; root /var/www/myproject/public; index index.php index.html; location / { try_files $uri $uri/ /index.php?$query_string; } location ~ .php$ { include snippets/fastcgi-php.conf; fastcgi_pass unix:/run/php/php8.3-fpm.sock; # 与已安装 PHP 版本一致 fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; include fastcgi_params; } location ~ /.ht { deny all; } }
  • 启用站点并重载：
    • sudo ln -s /etc/nginx/sites-available/myproject /etc/nginx/sites-enabled
    • sudo nginx -t && sudo systemctl reload nginx
• Apache 配置要点（启用重写模块与虚拟主机，DocumentRoot 指向 public）：
  • sudo a2enmod rewrite
  • 虚拟主机示例：DocumentRoot /var/www/myproject/public，<Directory /var/www/myproject/public> 中设置 AllowOverride All
  • sudo systemctl restart apache2
• 说明：Nginx 与 Apache 二选一；确保 DocumentRoot 指向 public，并启用 URL 重写。

五 权限优化与常见问题

• 文件权限与所有权（以 www-data 为例）：
  • sudo chown -R www-data:www-data /var/www/myproject
  • sudo find /var/www/myproject -type f -exec chmod 644 {} ;
  • sudo find /var/www/myproject -type d -exec chmod 755 {} ;
  • sudo chmod -R 775 /var/www/myproject/storage /var/www/myproject/bootstrap/cache
• 常见问题速查：
  • 页面显示 404：确认 DocumentRoot 指向 public，并启用重写（Nginx try_files 或 Apache mod_rewrite）。
  • 白屏或报错：APP_KEY 缺失（执行 php artisan key:generate），检查 .env 配置加载。
  • 数据库连接失败：核对 .env 中 DB_HOST/DB_PORT/DB_DATABASE/DB_USERNAME/DB_PASSWORD，确认数据库服务运行与用户权限。
  • 权限相关警告：确保 storage、bootstrap/cache 对 Web 服务用户可写，目录所有权与权限设置正确。
  • 队列与调度：生产环境启动队列（如 php artisan queue:work --queue=high,default --tries=3）与计划任务（crontab 执行 php /var/www/myproject/artisan schedule:run）。
• 说明：权限设置以安全为先，避免使用 777；生产环境建议仅对必要目录放宽权限，并使用队列工作者与定时任务处理异步与计划任务。