# 用網頁精靈安裝

適用於一般 PHP 虛擬主機、cPanel／Plesk／寶塔等主機面板，或自管 Apache / Nginx。需要 PHP 8.2+、MySQL 8.0+ / MariaDB 10.6+，以及 HTTPS 網域。這是既有 PHP 主機的網站安裝精靈，不會替電腦安裝 PHP 或資料庫伺服器。

## 安裝只需五步

1. **上傳整個 `facebook-monitor-v1` 資料夾**，將網域的網站根目錄設定為其中的 **`public` 資料夾**。不要把其他檔案一起放到可公開下載的網站根目錄。
2. **在主機面板建立一個空白資料庫與專用資料庫帳號**，記下主機、連接埠、名稱、帳號和密碼。給這個帳號該資料庫的建表、索引、讀寫權限。
3. **開啟 `https://你的網域/install.php`**。不要事先複製 `.env.example` 成 `.env`；精靈會自動建立。若環境檢查未通過，先依頁面提示開啟 PHP 擴充或調整目錄權限。
4. **開啟安裝包根目錄的 `INSTALL-KEY.txt`，複製安裝碼到精靈**。接著填寫網站網址、資料庫連線、管理員姓名／Email／密碼、團隊名稱。Facebook App ID 與 App Secret 可以先留白。
5. 點選 **「檢查連線並完成安裝」**。完成後點「登入」，使用剛建立的管理員帳號。

精靈會自動建立 31 張應用資料表與 migration 記錄、團隊 owner、`.env`、隨機加密金鑰、Webhook 驗證碼與安裝鎖。密碼採雜湊保存，不會在完成頁重新顯示。

## 主機目錄權限

安裝期間，PHP 執行帳號必須能讀取 `INSTALL-KEY.txt`，並可寫入**專案根目錄**與 **`storage`**。請透過主機面板設定目錄擁有者／群組，不要把整個網站改成 777。

`.env` 由 PHP 建立，權限為 600。背景工作請使用相同作業系統帳號；若 CLI 使用其他帳號，需由管理員以專用群組提供 `.env` 讀取權限。

完成後：

- 備份 `.env`；裡面的 `APP_KEY` 遺失將無法解密 Token。
- 取消網站程序對專案根目錄的寫入權限，保留 PHP session 目錄的必要權限。
- 精靈會移除安裝碼檔案並建立 `storage/installed.lock`；即使刪除鎖，只要 `.env` 存在仍拒絕重裝。
- 不需要自行執行 migrations 或建立管理員的指令。

## 開啟背景同步

在主機面板「排程任務 / Cron」加入以下兩項，頻率**每分鐘一次**。路徑換成實際專案位置，PHP 也必須使用 8.2+ 的 CLI 版本。

```sh
php /你的專案路徑/bin/console.php cron
php /你的專案路徑/bin/console.php queue:drain
```

每日一次清理過期原始資料：

```sh
php /你的專案路徑/bin/console.php prune
```

`queue:drain` 會於 50 秒內持續領取工作，已領取的工作會執行至結束，因此總執行時間可能超過 50 秒。工作有資料庫領取鎖，可避免多個 cron 同時處理同一筆。大量資料或主機有嚴格執行時間限制時，請改用 README 的常駐 `queue:work` / systemd 方式；不要同時設置兩套工作模式。

## 稍後連結 Facebook

若安裝時略過 Facebook，使用主機檔案管理器編輯 **public 以外的 `.env`**，填入 `META_APP_ID` 與 `META_APP_SECRET`。保留原本 `APP_KEY`。

在 Meta 後台設定：

- OAuth callback：`https://你的網域/facebook/callback`
- Webhook URL：`https://你的網域/webhooks/facebook`
- Verify token：`.env` 的 `META_WEBHOOK_VERIFY_TOKEN` 值
- Page Webhook 欄位：`feed`

完成權限設定後，於網站後台「授權與同步」連結 Facebook，再選擇粉專加入監控。Meta App 審核與權限說明見 README。

## 常見問題

**顯示「安裝精靈已鎖定」**  
已有 `.env`、安裝鎖或外部注入的 DB 設定。這是防止重裝的保護。既有網站請登入，不要刪檔重裝。若僅手動複製了尚未使用的 `.env` 範本，先移走該範本，再開啟精靈。

**環境檢查一直顯示 HTTPS 未通過**  
若 TLS 由反向代理終止，請由主機管理員在該 HTTPS 虛擬主機設定 Apache `SetEnv HTTPS on` 或 PHP-FPM `fastcgi_param HTTPS on`。僅可在確定外部入口強制 HTTPS 的虛擬主機使用。精靈刻意不信任客戶端可偽造的 `X-Forwarded-Proto`。

**主機只允許上傳 public_html**  
必須把 `.env`、安裝碼、app 與其他非公開檔案放在網站根目錄之外，並讓網站根目錄指向專案 public。若主機方案無法做到，需調整主機配置後才能安全安裝。

**資料庫連線或初始化失敗**  
確認資料庫存在、帳號權限正確、版本符合要求。一般錯誤可用相同資料庫重新送出，精靈會保留無密碼的安裝進度並安全補建缺少的表。密碼不會回填，需重新輸入。

**安裝時主機突然斷電 / 程序被強制終止**  
若留下 `.env` 或安裝鎖且畫面顯示安裝未完成，精靈會停止，避免覆蓋。請先備份並由管理員查核 `users`、`team_users` 與 migration 是否完成，不要直接清空資料庫。只有確認沒有任何既有業務資料時，才能清理該次安裝遺留的 `.env.install-*`、進度檔與空白初始化資料後重新開始。

**需要更換安裝碼**  
尚未安裝前可在主機上執行 `php bin/console.php secret:generate`，把產生的 64 字元十六進位內容存入 public 之外的 `INSTALL-KEY.txt`。不要自行設定簡短密碼，也不要把安裝碼貼進 URL。

**使用 Docker Compose**  
原本的 Compose 由環境變數管理設定，請繼續用 README 的容器安裝方式。網頁精靈不會修改容器注入的設定，也不會把設定寫進會隨容器刪除而消失的位置。

## 既有版本升級

不要重新執行安裝精靈；請依 [升級說明](升級說明.md) 保留設定、備份資料並執行 migration。新版須讓網站與背景程序可讀寫 `storage/uploads/`。