PHP Laravel 網站應用
以下以 **Ubuntu + Nginx + PHP-FPM + MySQL + Composer** 為例，說明透過 SSH 登入後，建置並啟動 Laravel 網站應用。假設網站放在：
```bash
/var/www/my-laravel-app
```
以下指令請依你的 Laravel 版本、PHP 版本與網域名稱調整。
---
## 1. 透過 SSH 登入 Ubuntu
在本機執行：
```bash
ssh username@SERVER_IP
```
例如：
```bash
ssh ubuntu@203.0.113.10
```
若使用指定金鑰：
```bash
ssh -i ~/.ssh/my-server.pem ubuntu@203.0.113.10
```
登入後先更新套件：
```bash
sudo apt update
sudo apt upgrade -y
```
建議使用一般帳號操作，不要長期以 `root` 執行 Laravel。
---
## 2. 安裝必要套件
### 安裝 Nginx、Git、Unzip、資料庫
```bash
sudo apt install -y nginx git unzip curl mysql-server
```
### 安裝 PHP 與常用擴充套件
以下以 PHP 8.2 為例：
```bash
sudo apt install -y \
php8.2 \
php8.2-fpm \
php8.2-cli \
php8.2-mysql \
php8.2-mbstring \
php8.2-xml \
php8.2-curl \
php8.2-zip \
php8.2-bcmath \
php8.2-intl \
php8.2-gd
```
確認 PHP 版本：
```bash
php -v
```
確認 PHP-FPM 是否啟動：
```bash
sudo systemctl status php8.2-fpm
```
若未啟動：
```bash
sudo systemctl enable --now php8.2-fpm
```
> Laravel 不同版本對 PHP 有不同要求，請先確認 `composer.json` 的 PHP 版本需求。
---
## 3. 安裝 Composer
建議使用官方安裝方式：
```bash
cd /tmp
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php
sudo mv composer.phar /usr/local/bin/composer
composer --version
```
---
## 4. 建立網站目錄並取得 Laravel 程式碼
建立目錄：
```bash
sudo mkdir -p /var/www/my-laravel-app
sudo chown -R $USER:$USER /var/www/my-laravel-app
```
### 從 Git 儲存庫下載
```bash
cd /var/www
git clone https://github.com/your-account/your-laravel-project.git my-laravel-app
cd /var/www/my-laravel-app
```
若是私人 Git 儲存庫，可以使用 SSH 金鑰或部署金鑰：
```bash
git clone git@github.com:your-account/your-laravel-project.git
```
也可以使用既有程式碼上傳方式，例如 `scp` 或 `rsync`。
---
## 5. 安裝 Laravel PHP 套件
在 Laravel 專案目錄執行：
```bash
cd /var/www/my-laravel-app
composer install --no-dev --optimize-autoloader
```
正式環境通常使用：
```bash
composer install --no-dev --classmap-authoritative
```
如果專案沒有 `composer.lock`，建議先在開發環境產生並提交該檔案，再部署到伺服器。
---
## 6. 設定環境變數 `.env`
Laravel 通常不會將 `.env` 放進 Git，因此先建立：
```bash
cp .env.example .env
```
編輯設定：
```bash
nano .env
```
常見設定如下：
```dotenv
APP_NAME="My Laravel App"
APP_ENV=production
APP_KEY=
APP_DEBUG=false
APP_URL=https://example.com
LOG_CHANNEL=stack
LOG_LEVEL=error
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=laravel_user
DB_PASSWORD=strong-password
CACHE_STORE=file
SESSION_DRIVER=file
QUEUE_CONNECTION=database
```
正式環境務必注意：
```dotenv
APP_ENV=production
APP_DEBUG=false
```
不要將 `.env` 提交到公開 Git 儲存庫。
---
## 7. 建立資料庫與資料庫使用者
登入 MySQL：
```bash
sudo mysql
```
建立資料庫與使用者：
```sql
CREATE DATABASE laravel CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'laravel_user'@'localhost'
IDENTIFIED BY 'strong-password';
GRANT ALL PRIVILEGES ON laravel.* TO 'laravel_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;
```
然後回到 Laravel 專案執行資料庫 migration：
```bash
php artisan migrate --force
```
若專案需要預設資料：
```bash
php artisan db:seed --force
```
或：
```bash
php artisan migrate --seed --force
```
---
## 8. 產生 Laravel Application Key
若 `.env` 中的 `APP_KEY` 尚未設定：
```bash
php artisan key:generate
```
確認：
```bash
grep APP_KEY .env
```
不要在已經有正式資料的環境隨意重新執行 `key:generate`，否則可能導致既有加密資料、Cookie 或登入 Session 無法解密。
---
## 9. 建立 Storage 符號連結
Laravel 上傳檔案通常存放於：
```text
storage/app/public
```
要讓瀏覽器可以存取，執行：
```bash
php artisan storage:link
```
這會建立：
```text
public/storage -> storage/app/public
```
---
## 10. 設定檔案權限
Nginx/PHP-FPM 通常使用 `www-data` 使用者。
```bash
sudo chown -R www-data:www-data /var/www/my-laravel-app
```
Laravel 需要寫入 `storage` 與 `bootstrap/cache`：
```bash
sudo chmod -R 775 /var/www/my-laravel-app/storage
sudo chmod -R 775 /var/www/my-laravel-app/bootstrap/cache
```
不要為了排除權限問題而使用：
```bash
chmod -R 777
```
這會造成安全風險。
若需要讓部署使用者也能修改程式，可使用群組設定，而不是將所有檔案開放寫入。
---
## 11. Laravel 正式環境快取
在程式碼與 `.env` 設定完成後執行：
```bash
php artisan optimize
```
也可以分別執行：
```bash
php artisan config:cache
php artisan route:cache
php artisan view:cache
```
如果修改了 `.env`，要重新建立設定快取：
```bash
php artisan config:clear
php artisan config:cache
```
若要清除所有 Laravel 快取：
```bash
php artisan optimize:clear
```
---
## 12. 設定 Nginx
建立網站設定檔：
```bash
sudo nano /etc/nginx/sites-available/my-laravel-app
```
範例內容：
```nginx
server {
listen 80;
listen [::]:80;
server_name example.com www.example.com;
root /var/www/my-laravel-app/public;
index index.php index.html;
charset utf-8;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
location = /favicon.ico {
access_log off;
log_not_found off;
}
location = /robots.txt {
access_log off;
log_not_found off;
}
location ~ \.php$ {
include snippets/fastcgi-php.conf;
fastcgi_pass unix:/run/php/php8.2-fpm.sock;
}
location ~ /\.(?!well-known).* {
deny all;
}
access_log /var/log/nginx/my-laravel-app-access.log;
error_log /var/log/nginx/my-laravel-app-error.log;
}
```
啟用設定：
```bash
sudo ln -s /etc/nginx/sites-available/my-laravel-app \
/etc/nginx/sites-enabled/my-laravel-app
```
若不再使用預設網站：
```bash
sudo rm -f /etc/nginx/sites-enabled/default
```
測試 Nginx 設定：
```bash
sudo nginx -t
```
重新載入：
```bash
sudo systemctl reload nginx
```
確認服務狀態：
```bash
sudo systemctl status nginx
```
> `root` 必須指向 Laravel 的 `public` 目錄，不能指向專案根目錄，否則可能暴露 `.env` 或其他敏感檔案。
---
## 13. 啟用防火牆
若使用 UFW：
```bash
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
sudo ufw status
```
這會開放：
- SSH：22
- HTTP：80
- HTTPS：443
建議限制 SSH 僅使用金鑰登入，並停用密碼登入，需依伺服器管理政策設定 `/etc/ssh/sshd_config`。
---
## 14. 設定 HTTPS
可使用 Certbot 取得 Let's Encrypt 憑證：
```bash
sudo apt install -y certbot python3-certbot-nginx
```
執行：
```bash
sudo certbot --nginx -d example.com -d www.example.com
```
測試自動續期：
```bash
sudo certbot renew --dry-run
```
DNS 必須先將網域指向伺服器 IP，且 80、443 Port 必須可連線。
---
## 15. 啟動 Laravel Queue Worker
如果 `.env` 使用：
```dotenv
QUEUE_CONNECTION=database
```
需要建立 Queue 資料表：
```bash
php artisan queue:table
php artisan migrate --force
```
測試執行 Worker：
```bash
php artisan queue:work
```
正式環境不建議只用 SSH 前景執行，因為登出後程序會停止。可以使用 Supervisor：
```bash
sudo apt install -y supervisor
```
建立設定檔：
```bash
sudo nano /etc/supervisor/conf.d/laravel-worker.conf
```
內容：
```ini
[program:laravel-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/my-laravel-app/artisan queue:work --sleep=3 --tries=3 --timeout=90
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/my-laravel-app/storage/logs/worker.log
stopwaitsecs=3600
```
套用設定：
```bash
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start laravel-worker:*
```
查看狀態：
```bash
sudo supervisorctl status
```
部署新版本後，重新啟動 Worker 讓它載入新程式碼：
```bash
sudo supervisorctl restart laravel-worker:*
```
---
## 16. 設定 Laravel Scheduler
Laravel Scheduler 通常需要每分鐘執行：
```bash
sudo crontab -u www-data -e
```
加入：
```cron
* * * * * cd /var/www/my-laravel-app && php artisan schedule:run >> /dev/null 2>&1
```
確認排程內容：
```bash
php artisan schedule:list
```
---
## 17. 常見部署更新流程
日後從 Git 更新程式時，可以使用：
```bash
cd /var/www/my-laravel-app
git pull origin main
composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan storage:link
php artisan optimize
sudo supervisorctl restart laravel-worker:*
sudo systemctl reload php8.2-fpm
sudo systemctl reload nginx
```
若採用更安全的部署方式，建議：
1. 在新目錄下載新版本。
2. 安裝 Composer 套件。
3. 執行 migration。
4. 更新符號連結至新版本。
5. 重新載入 PHP-FPM 與 Queue Worker。
6. 保留上一版，以便快速回滾。
---
## 18. 問題排查指令
### 查看 Laravel Log
```bash
tail -f /var/www/my-laravel-app/storage/logs/laravel.log
```
### 查看 Nginx 錯誤
```bash
sudo tail -f /var/log/nginx/my-laravel-app-error.log
```
### 查看 PHP-FPM Log
```bash
sudo journalctl -u php8.2-fpm -f
```
### 查看 Nginx Log
```bash
sudo journalctl -u nginx -f
```
### 檢查目錄權限
```bash
ls -la /var/www/my-laravel-app
ls -la /var/www/my-laravel-app/storage
```
### 測試 Laravel 基本狀態
```bash
php artisan about
php artisan route:list
php artisan config:show app
```
### 常見錯誤處理
若出現 `500 Internal Server Error`，依序檢查：
```bash
php artisan optimize:clear
php artisan key:generate
sudo chown -R www-data:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache
tail -f storage/logs/laravel.log
```
若出現資料庫連線錯誤，檢查：
```bash
php artisan config:clear
grep '^DB_' .env
```
若出現 `502 Bad Gateway`，通常是 PHP-FPM Socket、PHP-FPM 服務或 Nginx 設定錯誤：
```bash
ls -l /run/php/
sudo systemctl status php8.2-fpm
sudo nginx -t
```
---
## 最基本的完整部署順序
可以將整體流程簡化為：
```bash
ssh username@SERVER_IP
sudo apt update
sudo apt install -y nginx git unzip mysql-server
cd /var/www
git clone <REPOSITORY_URL> my-laravel-app
cd my-laravel-app
composer install --no-dev --optimize-autoloader
cp .env.example .env
nano .env
php artisan key:generate
php artisan migrate --force
php artisan storage:link
php artisan optimize
sudo chown -R www-data:www-data /var/www/my-laravel-app
sudo chmod -R 775 storage bootstrap/cache
sudo nginx -t
sudo systemctl reload nginx
```
完成後，使用瀏覽器開啟：
```text
http://example.com
```
正式上線時，應額外設定 HTTPS、資料庫備份、Log 監控、Queue Supervisor、Scheduler，以及適當的 SSH 與防火牆安全設定。
相關學習地圖、教學課程
Python 後端工程、資料庫