# 寶塔面板（BT Panel）安裝指南 — 勞工與宿舍管理系統

> 適用：寶塔 Linux 面板 7.x / 8.x（若是國際版 aaPanel，介面為英文，步驟相同）

---

## 一、安裝基礎環境（軟體商店）

登入寶塔面板（`http://伺服器IP:面板埠`）→ 左側【軟體商店】，依序安裝：

| 軟體 | 版本建議 |
|---|---|
| **Nginx** | 1.22 或以上 |
| **MySQL** | 8.0 |
| **PHP** | **8.3**（必須 ≥ 8.3，本系統不支援更舊版本） |
| **phpMyAdmin** | 可選（管理資料庫用） |
| **進程守護管理器** | 可選（建議，用來常駐 queue worker） |

> 若軟體商店看不到 PHP 8.3：先把面板升級到最新版（面板設定 → 更新）。

### PHP 8.3 必裝擴充
軟體商店 → PHP 8.3 → 設定 → 【安裝擴充】，確認已安裝：
`fileinfo`、`opcache`（其餘 pdo_mysql / mbstring / gd / zip 寶塔預設已帶）

### PHP 8.3 【禁用函數】調整
PHP 8.3 → 設定 → 【禁用函數】，從列表中**移除**以下三個（Laravel 需要）：
`putenv`、`proc_open`、`symlink`

---

## 二、建立資料庫

左側【資料庫】→ 添加資料庫：
- 資料庫名：`worker_system`
- 用戶名／密碼：自訂（記下來，等下填 .env）
- 訪問權限：本地伺服器

---

## 三、上傳與解壓部署包

1. 左側【文件】→ 進入 `/www/wwwroot/`
2. 上傳 `worker-system-deploy.zip`
3. 右鍵 → 解壓 → 解壓到目前資料夾
4. 得到資料夾 `/www/wwwroot/worker-system`（內含 `artisan`、`public/`、`vendor/` 等）

> 若解壓出來多了一層資料夾（如 `worker-system/` 內再一層），把內層內容搬到 `/www/wwwroot/worker-system/`。

---

## 四、建立網站

左側【網站】→ 添加站點：
- 域名：你的測試域名或 IP（例如 `test.xxx.com`）
- 根目錄：`/www/wwwroot/worker-system`
- PHP 版本：**8.3**
- 資料庫：不建立（上面已建）

建好後進入 網站設定：
1. 【網站目錄】→ 運行目錄選 **`/public`** → 儲存
2. 若之後出現 500 且日誌提到 open_basedir，到網站目錄頁把「防跨站攻擊（open_basedir）」取消勾選
3. 【偽靜態】→ 其實 Laravel 的 `public/.htaccess` 已內建；Nginx 需手動加入以下 rewrite：

```nginx
location / {
    try_files $uri $uri/ /index.php?$query_string;
}
```

---

## 五、設定 .env 與初始化

左側【終端】（或 SSH 登入），依序執行：

```bash
cd /www/wwwroot/worker-system

# 複製環境設定
cp .env.example .env

# 生成應用金鑰（全新資料庫才這樣做）
/www/server/php/83/bin/php artisan key:generate
```

> ⚠️ 注意：寶塔的 `php` 預設可能不是 8.3，**一律用完整路徑** `/www/server/php/83/bin/php`。

用【文件】管理器編輯 `.env`，修改這幾行：

```
APP_NAME=WorkerSystem
APP_ENV=production
APP_DEBUG=false
APP_URL=http://你的域名

DB_DATABASE=worker_system
DB_USERNAME=寶塔建立的資料庫用戶名
DB_PASSWORD=資料庫密碼
```

繼續初始化：

```bash
/www/server/php/83/bin/php artisan migrate --force
/www/server/php/83/bin/php artisan storage:link
/www/server/php/83/bin/php artisan config:cache
/www/server/php/83/bin/php artisan route:cache
/www/server/php/83/bin/php artisan view:cache

# 建立管理員（會輸出自動密碼，記下）
/www/server/php/83/bin/php artisan app:provision-admin
```

---

## 六、權限設定

```bash
cd /www/wwwroot/worker-system
chown -R www:www .
chmod -R 775 storage bootstrap/cache
```

---

## 七、背景程序（必要！不做以下功能不會動）

### 1. Queue worker（智能分配距離更新用）

**方法 A — 進程守護管理器（推薦）**：
軟體商店 → 進程守護管理器 → 添加進程：
- 名稱：`worker-system-queue`
- 啟動用戶：`www`
- 運行目錄：`/www/wwwroot/worker-system`
- 啟動命令：`/www/server/php/83/bin/php artisan queue:work --tries=3`

**方法 B — 不裝外掛**：排程任務已內建每分鐘消化 queue（見下），效果相同。

### 2. 排程任務（到期提醒 + queue 消化）

左側【計劃任務】→ 添加任務：
- 任務類型：Shell 腳本
- 任務名稱：`laravel-scheduler`
- 執行週期：**N 分鐘 → 1 分鐘**
- 腳本內容：

```bash
cd /www/wwwroot/worker-system && /www/server/php/83/bin/php artisan schedule:run >> /dev/null 2>&1
```

---

## 八、SSL（建議）

網站設定 → 【SSL】→ Let's Encrypt → 勾選域名 → 申請 → 開啟「強制 HTTPS」。
開啟後把 `.env` 的 `APP_URL` 改成 `https://` 開頭，再執行：
```bash
/www/server/php/83/bin/php artisan config:cache
```

---

## 九、部署後驗證

1. 瀏覽器開啟網址 → 應導向登入頁
2. 用管理員帳號登入 → 儀表板正常
3. 【Demo 資料】→ 按「生成 Demo 資料」→ 試用帳號已建立
4. 工人詳情頁 PDF 可預覽
5. 會計 → 月結報告 → 下載 PDF → 中文正常（約 5MB）
6. 智能宿位分配 → 更新距離資料 → 約 1 分鐘後有結果
7. **安全檢查**：瀏覽器直接開 `http://你的域名/.env` → 必須是 404！

---

## 十、常見問題

| 症狀 | 解法 |
|---|---|
| 500 錯誤 | 看 `storage/logs/laravel.log`；多為 .env 未設好或權限 |
| 頁面樣式全亂 | 運行目錄沒設成 `/public`，或偽靜態沒加 |
| PDF 中文方框 | 確認 `public/fonts/NotoSansTC-Regular.ttf` 存在；刪 `storage/fonts/*` 快取後重試 |
| 距離更新沒反應 | 進程守護 / 排程任務沒有運行 |
| artisan 報 putenv 被禁 | PHP 8.3 禁用函數列表移除 putenv/proc_open/symlink |
| 匯入 Excel 報 419/過大 | Nginx 上傳限制：網站設定 → 配置檔，加 `client_max_body_size 50m;` |
| 忘記管理員密碼 | `/www/server/php/83/bin/php artisan app:provision-admin --password=新密碼` |