這篇文章的操作順序按風險排列：先做不碰 prod 的盤點（零風險），再建本地開發環境（只動本機），然後才是碰 prod 的部署與資料庫紀律。

拍下完整現況（不動 prod）

接手後的第一個工作日只做一件事：把 prod 的完整狀態拍一份下來存到本地。這一步不改 prod 的任何東西，目的是讓自己手上有一份可對照的快照。

環境不同，拍照的工具和流程不同。先判斷自己的情境：

• 有 cPanel / Plesk 完整備份功能 → 用主機面板一次打包
• 只有 FTP 存取 → 用 FTP 逐層拍照
• 有 SSH 存取（部分 VPS 或獨立主機）→ 改讀有 SSH 但沒有 IaC 的雲端環境接管

用主機面板一次打包

如果主機有 cPanel，「備份精靈（Backup Wizard）」可以一次打包程式碼 + 資料庫 + email 設定 + cron jobs，是最快的完整快照方式。Plesk 的對應功能在「工具與設定 → 備份管理員」。

面板備份通常包含：網站檔案（含隱藏檔）、所有 MySQL 資料庫、email 帳戶與轉寄規則、cron job 設定、DNS zone 記錄。下載打包檔後解壓到本地、用 Git 初始化（見下方「初始化 Git repo」段）。

面板備份可能不包含的：SSL 憑證的私鑰（Let’s Encrypt 自動續期的通常不需要手動備份）、PHP 版本與模組設定（需要另外記錄，見環境設定的拍照）、.htaccess 以外的 Apache/LiteSpeed 自訂設定。拿到面板備份後仍然要跑「環境設定的拍照」段，因為面板備份拍的是檔案、不是環境設定。

用 FTP 逐層拍照

沒有主機面板（或面板不提供完整備份）時，要用 FTP 和 phpMyAdmin 分別拍程式碼和資料庫。

程式碼與靜態資源：用 FTP client 把整個網站目錄鏡像到本地。FileZilla 的操作路徑：站台管理員連線後，在遠端面板對根目錄按右鍵 → 「下載」，或用「伺服器 → 同步瀏覽」模式讓本地與遠端目錄結構保持對齊。WinSCP 提供「保持更新（Keep Remote Directory up to Date）」功能，但接手階段只需要一次性的完整下載，不需要持續同步。下載前確認 FTP client 的設定有勾選「顯示隱藏檔案」——.htaccess、.env、.user.ini 這類隱藏檔經常包含關鍵設定。

資料庫：用 phpMyAdmin 的「匯出」功能匯出完整資料庫（詳見下方「資料庫」段）。FTP 只拍程式碼，資料庫要另外匯出。

初始化 Git repo

不論用面板備份還是 FTP 逐層拍，拿到檔案後都初始化成 Git repo：

1mkdir project-takeover && cd project-takeover
2# FTP 下載完整站台到此目錄後
3git init
4git add -A
5git commit -m "initial snapshot from production FTP"

這個 commit 是接手的基準線。之後任何改動都能 diff 回這個起點，知道自己改了什麼。

資料庫

用 phpMyAdmin 的「匯出」功能：選「自訂」模式 → 勾選所有資料表 → 格式選 SQL → 勾選「加入 DROP TABLE / VIEW / PROCEDURE / FUNCTION / EVENT / TRIGGER 敘述」（讓匯入時能乾淨覆蓋）→ 壓縮選 gzip（大型資料庫避免瀏覽器逾時）→ 編碼選 UTF-8 → 執行。

phpMyAdmin 的匯出在資料庫超過幾百 MB 時容易因 PHP max_execution_time 或記憶體限制中斷。替代方案：如果主機有 cPanel，「phpMyAdmin → 匯出」旁邊通常有「MySQL 資料庫備份」或透過 cPanel API 的 mysqldump 介面，比 phpMyAdmin 的 PHP 層匯出更可靠。另一個選項是本地安裝 DBeaver（免費、跨平台）或 TablePlus（macOS/Windows），用主機提供的遠端 MySQL 連線（cPanel → 遠端 MySQL → 加入本機 IP 白名單）直接從本機執行 mysqldump。HeidiSQL（Windows 免費）也支援同樣的遠端連線匯出。

把匯出的 .sql 檔存進 repo：

1mkdir db-snapshots
2# 把 phpMyAdmin 匯出的檔案存到這裡
3mv ~/Downloads/production-dump.sql db-snapshots/$(date +%Y%m%d)-initial.sql
4git add db-snapshots/
5git commit -m "initial database snapshot from phpMyAdmin"

如果主機面板有提供 mysqldump 的 web 介面（部分 cPanel 有），用那個比 phpMyAdmin 的匯出更可靠——phpMyAdmin 在大資料庫上容易因為 PHP 記憶體限制而中斷。

環境資訊記錄

在 repo 根目錄建一份 ENVIRONMENT.md，記錄以下資訊：

 1## Production 環境
 2
 3- **主機商**：[名稱]、方案：[方案名稱]
 4- **PHP 版本**：cPanel/Plesk 的 PHP 設定頁直接顯示；沒有控制面板時，FTP 上傳一個 `phpinfo.php`（內容 `<?php phpinfo();`）到站台根目錄、瀏覽器開啟後記錄版本、確認後立刻刪除（phpinfo 會暴露伺服器完整設定）
 5- **MySQL 版本**：phpMyAdmin 首頁顯示
 6- **Web server**：Apache / LiteSpeed / Nginx（控制面板或 response header）
 7- **域名 / DNS**：誰管的、nameserver 指向哪裡
 8- **SSL**：Let's Encrypt 自動續期 / 主機商代管 / 手動上傳
 9- **Cron jobs**：控制面板 → Cron Jobs 頁面截圖或列表
10- **Email**：有沒有用主機的 email 服務、轉寄規則
11- **.htaccess**：已包含在 FTP 下載中（注意隱藏檔有沒有漏）

掃描 hardcoded credential

PHP 專案常見的做法是把資料庫密碼、API key 直接寫在 config.php 或 wp-config.php 裡。在本地 repo 跑一次掃描：

1grep -rn "password\|passwd\|secret\|api_key\|apikey\|api_secret" \
2  --include="*.php" --include="*.ini" --include="*.env" .

把找到的每一筆記錄下來：哪個檔案、什麼 credential、用在哪裡。這份清單是後續 credential 輪替的輸入。

第三方整合清單

翻 code 找出所有對外部服務的呼叫——金流（綠界、藍新、Stripe）、簡訊（Twilio、三竹）、Email（SendGrid、SMTP）、社群登入（Facebook、Google）、CDN、Analytics。每一個整合都有對應的 API key 或 webhook URL，這些都是接手後需要確認存取權的項目。

環境設定的拍照

程式碼和資料庫之外，伺服器的執行環境本身也要記錄。非 container 環境沒有 docker commit 可以一次打包整台機器，要逐層拍：

PHP 設定：在站台根目錄上傳一個 phpinfo.php（內容 <?php phpinfo();），用瀏覽器打開後把完整輸出另存為 HTML 檔。記錄完立刻刪掉這個檔案——phpinfo 會暴露伺服器的完整設定與路徑。需要記錄的關鍵項：PHP 版本、載入的模組（mysqli、curl、mbstring、gd、imagick）、upload_max_filesize、post_max_size、max_execution_time、memory_limit、error_reporting、session.save_handler。這些值直接影響程式碼能不能在本地環境重現相同的行為。

Cron jobs：cPanel 的 Cron Jobs 頁面或 Plesk 的排程工作清單，截圖或逐條抄到 ENVIRONMENT.md。每一條 cron 記錄三項：排程時間、執行的指令（通常是 /usr/local/bin/php /home/user/public_html/cron.php）、這條 cron 的業務用途（如果能從指令或檔案名推斷）。

SSL 憑證：記錄域名、簽發者（Let’s Encrypt / 自購 / 主機商代管）、到期日。瀏覽器的鎖頭圖示可以查看憑證詳情。從本機也可以用 CLI 確認：

1echo | openssl s_client -connect example.com:443 2>/dev/null | openssl x509 -noout -dates -issuer

如果是 Let’s Encrypt 自動續期，要確認續期機制是 cPanel 內建（AutoSSL）還是某個自訂 cron。手動購買的憑證要記錄到期日並設日曆提醒——過期後站台會直接出現瀏覽器安全警告。

.htaccess 規則：.htaccess 可能散在多個目錄（根目錄、uploads/、wp-admin/、api/）。FTP 下載時已包含在內（前提是 FTP client 有設定顯示隱藏檔案），確認一下這些檔案都在 repo 裡。

外部服務連線：除了前一節的第三方整合清單，用 grep 掃程式碼找出所有對外 URL。這些連線在未來遷移時要同步處理——搬了伺服器但 callback URL 沒改，金流通知就收不到。

1grep -rn "https\?://" --include="*.php" . \
2  | grep -v "localhost\|127\.0\.0\.1\|example\.com" \
3  | sort -u > _environment/external-urls.txt

檔案權限：FileZilla 的遠端檔案清單有權限欄。記錄 uploads/、cache/、sessions/、config 檔案的權限。777 的目錄是安全風險（任何使用者都能寫入），在多租戶的主機上尤其危險——同台主機的其他帳戶也能存取。

把以上資料存進 repo 的 _environment/ 目錄：

1_environment/
2├── phpinfo-20260626.html      # phpinfo 完整輸出
3├── cron-jobs.md               # cron 清單
4├── ssl-cert-info.txt          # 憑證資訊
5├── external-urls.txt          # 外部連線清單
6└── file-permissions.txt       # 目錄權限記錄

_environment/ 可加進 .gitignore（phpinfo 含敏感資訊），或只 ignore HTML 檔、其餘進 Git。

建立本地開發環境

本地能跑起來，才有安全的測試空間。目標是在本機重現 prod 的 PHP + MySQL 版本組合。

選型：Docker vs 本地堆疊

選型判準：如果 prod 的 PHP 版本是 5.6 或 7.0 這類已停止維護的舊版，Docker 是唯一能精確對齊的選項——MAMP/XAMPP 通常只提供仍在維護的版本。常見版本（7.4、8.0、8.1、8.2）用 MAMP/Laragon 會比 Docker 更快跑起來。

Docker 方式

Docker Compose V2（docker compose 指令）不需要 version 欄位。如果使用舊版 docker-compose CLI，在檔案開頭加 version: '3.8'。

 1# docker-compose.yml
 2services:
 3  web:
 4    image: php:8.1-apache
 5    volumes:
 6      - ./:/var/www/html
 7    ports:
 8      - "8080:80"
 9  db:
10    image: mysql:8.0
11    environment:
12      MYSQL_ROOT_PASSWORD: localdev
13      MYSQL_DATABASE: project
14    volumes:
15      - ./db-snapshots/initial.sql:/docker-entrypoint-initdb.d/init.sql
16    ports:
17      - "3306:3306"
18  phpmyadmin:
19    image: phpmyadmin/phpmyadmin
20    environment:
21      PMA_HOST: db
22    ports:
23      - "8081:80"

PHP 版本要對齊 prod。如果 prod 是 PHP 7.4，本地用 php:7.4-apache。版本差異會導致函式行為不同（str_contains 在 8.0 才有、mysql_* 系列在 7.0 移除），測試通過但 prod 壞掉。phpmyadmin service 讓本地也有跟 prod 相同的資料庫操作介面，方便驗證 phpMyAdmin 上要執行的操作。

匯入資料庫

Docker 啟動後匯入初始快照：

1docker exec -i project-db-1 mysql -uroot -plocaldev project < db-snapshots/20260626-initial.sql

MAMP/Laragon/XAMPP 的匯入方式：開啟對應的 phpMyAdmin（通常在 localhost/phpmyadmin）→ 選資料庫 → 匯入 → 選 .sql 檔案 → 執行。或用 DBeaver/TablePlus 連本地 MySQL 後執行 SQL 檔。

常見的「本地跑不起來」原因

本地能完整跑起來之後，這個環境就是所有變更的測試場。任何改動都先在這裡驗證。

資料庫變更紀律

phpMyAdmin 讓修改 prod DB 只需要幾次點擊，這正是它危險的原因——沒有 preview、沒有 undo、沒有 review。紀律要靠流程補上。

變更流程

1. 在本地 DB 寫好 SQL 並執行，確認結果正確
2. 把 SQL 存進 repo 的 migrations/ 目錄，檔名帶日期：

1# migrations/2026-06-26-add-status-column.sql
2ALTER TABLE orders ADD COLUMN status VARCHAR(20) DEFAULT 'pending';

3. 在 phpMyAdmin 上對要改的資料表做匯出（只匯出該表的結構 + 資料），存進 db-snapshots/ 作為回退依據
4. 在 phpMyAdmin 的 SQL 頁籤貼上已驗證的 SQL 執行
5. 在 repo 的 CHANGELOG.md 記錄：時間、操作者、改了什麼、為什麼

高風險操作的額外防護

修改欄位型別、刪除欄位、刪除資料表、批次更新資料——這些操作在 phpMyAdmin 上執行就生效，沒有乾淨的 undo。額外防護是在執行前先確認：

• 有沒有剛做的該資料表備份（不是上週的，是剛剛做的）
• 這張表有沒有 foreign key 或觸發器會連帶影響其他表
• 如果改錯了，回退的具體步驟是什麼（從備份 SQL 重建整張表？還是用 UPDATE 改回來？）

部署紀律

FTP 部署沒有 CI pipeline 的自動化保護，但不代表不能有流程。流程的目標是讓每次部署都可追溯、可回退。

部署步驟

11. git diff HEAD~1 --name-only          # 確認這次改了哪些檔案
22. 本地測試通過
33. FTP client 開兩個窗格：左邊本地、右邊 prod
44. 用 FileZilla 的目錄比較功能確認差異
55. 只上傳有變更的檔案（不要整站覆蓋）
66. 上傳完在瀏覽器驗證功能
77. git tag deploy-20260626 && git push   # 標記這次部署的版本

備份策略

無 SSH 的主機環境通常不提供自動快照。備份要自己做：

如果主機面板有自動備份功能（cPanel 的 Backup Wizard），確認它有開並且能還原。但不要把它當唯一備份——主機商的備份可能在主機出問題時一起不見。

備份自動化（沒 SSH 也能做）

無 SSH 的環境沒有 cron + CLI 的組合，但可以用本機排程 + FTP client 的 CLI 模式達成自動化備份。

用 lftp（macOS/Linux 可透過 Homebrew 或 apt 安裝）做定期站台鏡像：

1# backup.sh — 加入本機的 cron 或 launchd 每日執行
2lftp -e "mirror --verbose /public_html/ /local/backup/site/; quit" \
3  -u username,password ftp.example.com

rclone 是另一個選項，支援 FTP/SFTP 且有更好的增量同步（只傳有變更的檔案）：

1# 設定 rclone remote（首次）
2rclone config  # 選 FTP、填入主機資訊
3
4# 同步（之後每次只傳差異）
5rclone sync myhost:/public_html/ /local/backup/site/ --progress

macOS 用 launchd plist、Windows 用工作排程器（Task Scheduler）排定每日執行這些腳本，讓備份不再依賴人工記得。

資料庫的自動備份較受限——phpMyAdmin 沒有 CLI 介面。如果主機允許遠端 MySQL 連線，可以在本機 cron 裡加一條 mysqldump：

1mysqldump -h mysql.example.com -u dbuser -p'password' dbname | gzip > /local/backup/db/$(date +%Y%m%d).sql.gz

不允許遠端連線時，退而求其次：每週手動從 phpMyAdmin 匯出一次、存進 repo。

回退方式

FTP 部署沒有 rollback 按鈕。回退的方式是：

1git checkout deploy-20260625 -- path/to/changed/file.php
2# 把特定檔案回到上一次部署的版本，再 FTP 上傳

整站回退則是 checkout 到上一個 deploy tag，再整批 FTP 上傳。這就是為什麼 deploy tag 重要——沒有 tag 就不知道要回退到哪個版本。

credential 盤點與保護

接手後要回答的問題是：有哪些 credential、誰有存取權、哪些需要輪替。

盤點清單

最高優先輪替的是前人可能仍持有存取權的 credential：主機面板密碼、資料庫密碼。如果前人的離開不是善意的（被解僱、爭端），這些應該在接手的第一天就改。

從 hardcode 到 config 分離

長期目標是把 credential 從 code 裡搬出來。即使在沒有 SSH 的環境也能做：

1// 改前：password 直接寫在 code 裡
2$db_password = 'p@ssw0rd123';
3
4// 改後：從 .env 讀取（用 vlucas/phpdotenv 或手寫 parse）
5$db_password = getenv('DB_PASSWORD') ?: parse_ini_file(__DIR__ . '/.env')['DB_PASSWORD'];

.env 放在 webroot 之外（如果主機允許）或在 .htaccess 裡禁止存取：

1<Files ".env">
2    Require all denied
3</Files>

外部監控（prod 不用裝東西）

無 SSH 的環境裝不了監控 agent，但可以用外部 HTTP 檢查服務從外面看。這類服務從多個地理位置定期對網站發送 HTTP request，回應異常時通知。

UptimeRobot 的免費方案提供 50 個 monitor、每 5 分鐘檢查一次，夠用於一個站台的首頁 + 幾個關鍵頁面（登入頁、API endpoint、金流回呼 URL）。Better Stack（原 Better Uptime）提供類似功能並附帶 status page。兩者都只需要填入 URL 和通知方式（email / Slack / webhook），不需要在 server 上裝任何東西。

設定後至少加三個 monitor：首頁（網站是否活著）、登入或後台入口（PHP 是否正常執行）、以及任何有外部依賴的頁面（金流 callback、API endpoint）。這不是完整的可觀測性，但至少讓「網站掛了」這件事從「使用者打電話來」變成「手機收到通知」。

時程參考

完整走完盤點（FTP mirror + DB dump + 環境記錄）約需半天到一天。本地環境建立與驗證約需半天到一天（取決於 PHP 版本對齊的難度）。紀律建立（changelog + 部署流程）是持續的、但框架搭建約需 2-3 小時。CI 化 FTP 部署約需半天。整體從接手到穩定維運約 2-3 個工作天。

升級路徑的切入點

接手穩定後，逐步脫離無 SSH 環境的約束。每一步都獨立且可回退。

最低成本的第一步：CI 化 FTP 部署

在 GitHub repo 設定 GitHub Actions，推到 main 時自動跑測試（如果有的話）+ 自動 FTP 部署。FTP credential 存在 GitHub Secrets 裡，不在 code 裡。

 1# .github/workflows/deploy.yml
 2name: Deploy via FTP
 3on:
 4  push:
 5    branches: [main]
 6jobs:
 7  deploy:
 8    runs-on: ubuntu-latest
 9    steps:
10      - uses: actions/checkout@v4
11      - uses: SamKirkland/FTP-Deploy-Action@v4
12        with:
13          server: ${{ secrets.FTP_HOST }}
14          username: ${{ secrets.FTP_USER }}
15          password: ${{ secrets.FTP_PASS }}
16          server-dir: /public_html/

這一步的價值是部署從「開 FileZilla 手動上傳」變成「push to main 自動部署」，人為失誤的空間顯著縮小。Prod 伺服器不需要任何改動。

下一步：遷移到有 SSH 的 VPS

當以下任一條件出現時，無 SSH 環境的約束會變成瓶頸：

• 需要 SSH 存取（裝 Git、跑 CLI 工具、設排程）
• 需要自訂 PHP extension 或 PHP 版本
• 需要更多的運算資源或記憶體
• 需要環境分離（dev / staging / prod）

遷移到 VPS（DigitalOcean、Linode、AWS Lightsail）後，SSH 存取讓所有雲端環境的工具鏈成為可用——Git on server、composer、artisan、mysqldump CLI、cron 的完整控制。這一步之後，接手維運的環境開始對齊模組負一：還沒有 infra 的環境的操作紀律，後續可以按成熟度階梯逐步往 IaC 推進。

跨分類引用

• → 有 SSH 但沒有 IaC 的雲端環境接管：搬到 VPS 或雲端後的接管流程
• → 模組負一：還沒有 infra 的環境：接手完成、環境穩定後，操作紀律對齊這裡
• → 模組零：infra 是什麼：成熟度階梯作為接手後評估現況的座標
• → 模組二：身分與憑證地基：credential 盤點與輪替的系統性設計
• → 模組八：治理好習慣：tagging、secret 管理、成本可見性

本篇以 PHP 為主要範例（legacy 升級最常見的情境），Node.js 和 Python 的對應工具在各段併列。

相容性評估

升級前要先知道「現有程式碼跟新版本有多少不相容」。不相容的類型分四種：

PHP 相容性掃描

PHPCompatibility 是 PHP_CodeSniffer 的規則集，可以自動掃描程式碼裡哪些寫法在目標版本不相容：

1# 安裝
2composer global require phpcompatibility/php-compatibility
3
4# 掃描：目標版本 8.0
5phpcs --standard=PHPCompatibility \
6  --runtime-set testVersion 8.0 \
7  --extensions=php \
8  -p \
9  src/

掃描結果會列出每一處不相容的位置、原因和嚴重度。常見的命中包括：

1FILE: src/legacy/Database.php
2----------------------------------------------------------------------
3FOUND 3 ERRORS:
4 42 | ERROR | Function mysql_connect() is removed since PHP 7.0
5 89 | ERROR | Function each() is removed since PHP 8.0
6156 | ERROR | Curly brace access syntax is deprecated since PHP 7.4
7----------------------------------------------------------------------

php -l 可以做基本的語法檢查，但它只抓語法錯誤、抓不到 deprecated 函式和行為變更。PHPCompatibility 掃描的覆蓋面更廣。

PHP 升級的高頻修改項

Node.js 相容性掃描

1# 用 nvm 切換版本後跑測試
2nvm install 20
3nvm use 20
4npm test
5
6# 檢查 package.json 的 engines 欄位
7cat package.json | jq '.engines'

Node.js 的 breaking change 集中在 V8 引擎行為（Buffer 建構式、fs 的 callback 簽章）和原生模組的 ABI 相容性。如果專案用了原生模組（node-gyp 編譯的），版本升級後要重新 npm rebuild。

Python 相容性掃描

1# Python 2→3：用 2to3 掃描
22to3 --no-diffs -w src/
3
4# Python 3.x 小版本：用 pyupgrade
5pip install pyupgrade
6pyupgrade --py310-plus src/**/*.py

Python 2→3 的修改量通常很大（print 語法、unicode 處理、dict 方法），是接近重寫等級的升級。Python 3.x 之間的升級相對溫和，主要是 deprecation 移除和 typing 語法的演進。

本地驗證

相容性掃描找出的是靜態分析能偵測的不相容。執行期的行為變更（如字串比較規則改變、排序穩定性改變）只有跑起來才看得到。

建立目標版本的本地環境

用 Docker 建一個精確匹配目標版本的環境：

 1services:
 2  app:
 3    image: php:8.2-apache
 4    volumes:
 5      - ./src:/var/www/html
 6    ports:
 7      - "8080:80"
 8  db:
 9    image: mysql:8.0
10    environment:
11      MYSQL_ROOT_PASSWORD: localdev
12      MYSQL_DATABASE: app

如果不用 Docker，MAMP Pro 或 Laragon 可以切換 PHP 版本。關鍵是本地環境的 runtime 版本要跟升級目標完全一致——PHP 8.0 跟 8.2 之間也有差異。

驗證策略

有測試套件的專案跑測試套件。沒有測試套件的專案（legacy 專案的常態）按照這個優先序手動驗證：

1. 首頁能載入：最基本的 smoke test，確認 PHP 不 fatal error
2. 登入流程：session 處理是版本升級最常出問題的區域
3. 資料庫操作：CRUD 的每一種至少各跑一次
4. 金流 / 第三方 API：callback URL 和 API 呼叫是否正常
5. 表單提交：file upload、驗證邏輯

PHP 升級時把 error_reporting 開到最大：

1// 開發環境設定（不要在 prod 開）
2error_reporting(E_ALL);
3ini_set('display_errors', '1');

所有 notice、warning、deprecation 都要修——它們在下一個版本可能升級為 error。

第三方依賴相容性

1# Composer：檢查哪些套件需要更新
2composer outdated
3
4# 檢查各套件是否支援目標 PHP 版本
5composer why-not php 8.2

composer why-not 會列出哪些套件的 require.php 限制不允許目標版本。這些套件要先升級到支援新版本的版號，才能升 PHP。

如果某個套件已經不再維護且不支援新 PHP 版本，要評估替代方案或 fork 修改。這個評估的工作量可能佔整個升級的大部分時間。

分批部署策略

有獨立環境控制的情境（VPS / 雲端）

最安全的策略是建一套平行環境跑新版本：

1. 用新 PHP 版本建一台新的 VM 或容器
2. 部署相同的程式碼
3. 匯入 prod 資料庫的副本
4. 在新環境跑完整驗證
5. DNS 或 load balancer 切換流量到新環境
6. 舊環境保留一段時間作為 rollback 目標

rollback 是把流量切回舊環境。舊環境在確認新環境穩定之前不要關——保留期至少一週。

面板管理主機（無 SSH）的情境

面板管理主機（cPanel / Plesk）的 PHP 版本切換通常是 per-domain 的設定：

• cPanel：MultiPHP Manager，選域名 → 選 PHP 版本 → Apply
• Plesk：PHP Settings → PHP version 下拉選單

切換是即時生效的，rollback 也是即時的（選回舊版本）。但沒有「平行環境驗證」的能力——除非主機商提供 staging subdomain 可以先測。

面板管理主機的升級策略：

1. 如果有 staging subdomain：先在 staging 切換版本、驗證、再切 prod
2. 如果沒有：選流量最低的時段切換（如凌晨），切換後立刻驗證關鍵流程，出問題立刻切回
3. 切換前備份（FTP mirror + DB dump），確認 rollback 路徑存在

WordPress / 框架的版本矩陣

WordPress 和主流框架有明確的 PHP 版本支援矩陣。升級 PHP 前要先確認框架版本是否支援目標 PHP 版本：

如果框架不支援目標 PHP 版本，要先升級框架。框架升級和 PHP 升級不要同時做——先升框架、驗證穩定、再升 PHP，每一步都有獨立的 rollback 點。

常見的升級陷阱

Session 序列化格式

PHP 的 session 序列化格式在某些版本之間有變更。版本切換後舊 session 檔案可能無法反序列化，使用者會被強制登出。處理方式：

• 在維護窗口切換版本（使用者預期重新登入）
• 或在切換前清除所有 session 檔案

opcache 快取

PHP 的 opcache 會快取編譯後的 bytecode。版本切換後如果 opcache 沒清，可能用舊版本編譯的 bytecode 跑在新版本上。切換後的第一件事：

1# CLI 方式清除（如果有 SSH）
2php -r "opcache_reset();"
3
4# 或重啟 PHP-FPM / Apache
5systemctl restart php8.2-fpm

Composer 的 PHP 版本鎖定

composer.lock 裡的套件版本是根據當時的 PHP 版本解析的。PHP 版本變了之後，要重新 composer update 讓 Composer 用新版本重新解析依賴。但 composer update 可能升級其他套件——較安全的做法是 composer update --lock 只更新 lock file 的 metadata、不升級套件版本。

隱性的行為變更

PHP 8.0 起，字串跟數字的比較規則改了（0 == "foo" 從 true 變 false）。這類變更不會報錯、不會拋例外，程式碼照跑但行為不同。靜態分析抓不到，只有業務邏輯測試能覆蓋。

如果沒有測試套件，至少在切換後的一週內密切監控錯誤日誌和業務指標（訂單數、登入數、API 錯誤率），用業務指標的異常作為行為變更的偵測手段。

時程與管理層溝通

向管理層溝通時要說明：「升級 runtime 版本不只是在伺服器改一個設定。程式碼裡用到的函式和行為在新版本有不同的定義，需要逐一修改和驗證。時程取決於程式碼用了多少舊版本的專屬功能。」

成本參考：PHP 版本升級本身的工具和環境不花錢（PHPCompatibility 開源、Docker 免費、cPanel 版本切換內建）。成本全在工程師時間。

跨分類引用

• → 升級的共通操作框架：四階段模型（評估 → 平行環境 → 切換 → 退役）
• → Legacy PHP 的安全盤點：PHP 版本風險評估與漏洞掃描
• → 程式碼版控與 FTP 部署紀律：升級前的 Git 基準線與 rollback 策略

本篇是無 SSH 的 FTP / 面板管理環境接管的延伸，聚焦在資料庫層面。程式碼與部署紀律見主文。

phpMyAdmin 的限制與對策

phpMyAdmin 是多數無 SSH 環境預裝的資料庫管理介面，匯出功能涵蓋完整 SQL dump，但它跑在 PHP 執行環境裡，受限於 max_execution_time 和記憶體上限。資料庫超過 50MB 時，匯出經常在執行到一半就因 timeout 中斷，產出不完整的 SQL 檔案——而不完整的 dump 在還原時只會匯入前半段的表、後面的表靜靜消失。

大資料庫的匯出對策

第一個選項是分表匯出。phpMyAdmin 的匯出頁面允許選擇要匯出的資料表，把一次完整匯出拆成 3-5 批，每批在 timeout 之前完成。缺點是匯出不是原子操作——不同批次之間如果有寫入，表之間的參照關係可能不一致（例如訂單表引用的商品 ID 在商品表的那一批裡還沒匯出）。對多數讀取為主的站台，這個不一致窗口可接受；對交易密集的站台，需要在低流量時段操作。

第二個選項是調整 phpMyAdmin 的 timeout。部分主機允許在 phpMyAdmin 的設定目錄放自訂的 config.inc.php：

1$cfg['ExecTimeLimit'] = 600; // 從預設 300 秒增加到 600 秒

cPanel 主機通常在「軟體」區塊的 phpMyAdmin 設定裡有對應的 UI 選項。Plesk 的路徑是「資料庫」→「phpMyAdmin 設定」。能不能改取決於主機商的權限政策，改之前先確認。

第三個選項是繞過 phpMyAdmin。如果主機允許遠端 MySQL 連線（在 cPanel 的「遠端 MySQL」頁面加白名單 IP），就能用桌面工具直連資料庫匯出：

桌面工具直連 MySQL 比 phpMyAdmin 穩定，因為匯出跑在本機、不受主機的 PHP timeout 限制。mysqldump 是最可靠的選項：

1mysqldump -h db-host.example.com -u dbuser -p \
2  --single-transaction --routines --triggers \
3  dbname > backup_$(date +%Y%m%d_%H%M).sql

--single-transaction 對 InnoDB 表做一致性快照，不需要鎖表。--routines 和 --triggers 確保 stored procedure 和觸發器也被包含在 dump 裡——phpMyAdmin 匯出預設也包含，但容易在手動選項時漏勾。

匯出後的驗證

匯出完成後檢查 SQL 檔案的結尾。完整的 mysqldump 結尾會有 -- Dump completed on YYYY-MM-DD HH:MM:SS。phpMyAdmin 匯出的結尾會有 -- phpMyAdmin SQL Dump 的對應結尾標記。如果檔案在某個 INSERT INTO 語句中間斷掉，這份 dump 就是不完整的，還原時會靜靜丟失後面的資料。

1tail -5 backup_20260626_1430.sql
2# 預期看到 "Dump completed" 或完整的結尾註解

備份策略：頻率與保留

備份頻率由資料的變更速率決定。一個每天只有幾筆訂單的小型電商，每週備份加上每次變更前備份就夠用。一個每天有數百筆交易的服務，需要每日備份。判斷依據是：如果最新的備份丟了、要用上一份還原，能接受丟失多少資料？這個時間差就是實際的 RPO（Recovery Point Objective）。

保留策略

命名用時間戳避免覆蓋：dbname_20260626_1430.sql.gz。壓縮用 gzip（gzip backup.sql），50MB 的 SQL dump 通常壓到 5-10MB。

儲存位置

本機是第一份副本，但本機磁碟故障時備份也跟著消失。至少再推一份到雲端儲存：

1# rclone 同步到 Google Drive（事先用 rclone config 設定 remote）
2rclone copy /local/backups/db/ gdrive:project-backups/db/ --max-age 7d
3
4# 或推到 S3
5aws s3 sync /local/backups/db/ s3://my-project-backups/db/ --storage-class STANDARD_IA

備份驗證

備份存在不等於備份可用。每月至少做一次驗證：把最新的 dump 匯入本地 MySQL，檢查關鍵表的 row count 跟 prod 一致、應用程式能正常啟動。如果匯入報錯或 row count 差異超過預期，備份流程有問題要立刻排查。

1mysql -u root -p local_testdb < backup_20260626_1430.sql
2mysql -u root -p -e "SELECT COUNT(*) FROM orders;" local_testdb

自動化備份（無 SSH 環境的限制下）

無 SSH 環境的自動化受限程度取決於主機提供的能力。三個層級由好到差：

主機有 cron + mysqldump 路徑：部分主機在 cPanel 的「cron 工作」裡允許設定排程指令。mysqldump 通常安裝在 /usr/bin/mysqldump，可以直接用：

1# cPanel cron job（每天凌晨 3 點）
20 3 * * * /usr/bin/mysqldump -u dbuser -p'password' dbname | gzip > /home/user/backups/db_$(date +\%Y\%m\%d).sql.gz

密碼寫在 cron 指令裡不理想但在無 SSH 環境選擇有限。用 .my.cnf 檔案存密碼（chmod 600）較安全，但不是所有主機都支援。

主機有遠端 MySQL 但沒 cron：用本機排程（macOS launchd / Windows Task Scheduler / Linux cron）跑 mysqldump 遠端連線：

 1#!/bin/bash
 2# local-backup.sh — 本機排程每天跑
 3BACKUP_DIR="$HOME/backups/myproject/db"
 4mkdir -p "$BACKUP_DIR"
 5mysqldump -h db-host.example.com -u dbuser -p'password' \
 6  --single-transaction dbname \
 7  | gzip > "$BACKUP_DIR/db_$(date +%Y%m%d_%H%M).sql.gz"
 8
 9# 推到雲端
10rclone copy "$BACKUP_DIR" gdrive:project-backups/db/ --max-age 7d
11
12# 清理超過 30 天的本地備份
13find "$BACKUP_DIR" -name "*.sql.gz" -mtime +30 -delete

沒有 cron 也沒有遠端 MySQL：只能靠手動的 phpMyAdmin 匯出，加上 cPanel 的「備份精靈」（如果主機方案包含）。cPanel 備份精靈可以設定每日或每週的完整備份（含資料庫 + 檔案），但免費方案通常不支援排程。這是最受限的情境——如果連手動匯出都嫌麻煩，最高優先的升級路徑是開通遠端 MySQL 存取。

資料庫變更的 migration 紀律

Schema 變更（加欄位、改索引、拆表）在沒有 migration 工具的 legacy PHP 專案裡，全靠手動在 phpMyAdmin 執行 SQL。migration 紀律的目標是讓每一次 schema 變更有紀錄、可重播、可回退。

Migration 檔案格式

每次 schema 變更寫成一個獨立的 SQL 檔案，存在 repo 的 migrations/ 目錄：

 1-- migrations/2026-06-26-001-add-users-email-verified.sql
 2-- 目的：新增 email 驗證欄位，支援 email 驗證流程
 3-- 回退：ALTER TABLE users DROP COLUMN email_verified;
 4
 5-- UP
 6ALTER TABLE users ADD COLUMN email_verified TINYINT(1) NOT NULL DEFAULT 0 AFTER email;
 7CREATE INDEX idx_users_email_verified ON users (email_verified);
 8
 9-- DOWN（回退用，不自動執行）
10-- DROP INDEX idx_users_email_verified ON users;
11-- ALTER TABLE users DROP COLUMN email_verified;

檔名的結構是 日期-序號-描述，序號處理同一天多次變更的排序。UP 段是要執行的 SQL，DOWN 段是回退 SQL（註解掉，手動需要時才用）。

追蹤哪些 migration 已執行

在資料庫建一張追蹤表：

1CREATE TABLE IF NOT EXISTS migrations_log (
2    id INT AUTO_INCREMENT PRIMARY KEY,
3    filename VARCHAR(255) NOT NULL,
4    applied_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
5    applied_by VARCHAR(100)
6);

每次在 prod 執行完一個 migration，手動插入一筆紀錄：

1INSERT INTO migrations_log (filename, applied_by) VALUES ('2026-06-26-001-add-users-email-verified.sql', 'alice');

查哪些 migration 還沒跑：比對 migrations/ 目錄的檔案清單跟 migrations_log 表的 filename 欄。這不是自動化的 migration runner（像 Laravel 的 artisan migrate），但在沒有框架支援的 legacy 專案裡，一張表加一個目錄就能達到可追蹤的最低標準。

執行流程

高風險的 migration（改大表結構、刪欄位、改資料類型）在步驟 2 要做完整的資料庫 dump 而非只備份受影響的表，因為外鍵和觸發器可能讓影響範圍超出目標表。

還原演練

備份的價值在還原成功的那一刻才被驗證。沒有演練過的備份等同於不存在——匯出可能不完整、SQL 版本可能不相容、匯入順序可能因為外鍵而失敗。

演練流程

在本地用最新的備份還原一次完整的資料庫：

1# 建一個測試用的空資料庫
2mysql -u root -p -e "CREATE DATABASE restore_test;"
3
4# 匯入備份
5mysql -u root -p restore_test < backup_20260626_1430.sql
6
7# 驗證
8mysql -u root -p -e "SHOW TABLES;" restore_test
9mysql -u root -p -e "SELECT COUNT(*) FROM orders;" restore_test

驗證三件事：表結構完整（SHOW TABLES 的表數量跟 prod 一致）、資料完整（關鍵表的 row count 一致）、應用程式能跑（把本地應用指向 restore_test 資料庫、打開首頁和幾個關鍵流程）。

還原時間的量測

記錄從開始匯入到驗證完成的時間。這個數字就是事故時的最快恢復時間。如果一個 500MB 的資料庫匯入需要 40 分鐘，加上排查原因和決策的時間，實際恢復可能超過一小時。知道這個數字，才能在事故時給管理層一個實際的時間預期。

無 SSH 環境沒有 PITR

無 SSH 的主機環境的 MySQL 通常不提供 binlog 層級的 point-in-time recovery。能還原到的最近時間點就是最新備份的時間點——備份是每天凌晨做的、下午三點出事，那就是丟失當天的所有寫入。這是備份頻率需要跟資料變更速率對齊的根本原因。交易密集的站台如果無法接受一天的資料丟失，升級到有 binlog / PITR 的環境（VPS 或 managed MySQL）是必要的投資。

大資料庫的特殊處理

資料庫超過 500MB 時，備份和還原的操作時間和失敗風險都會上升。需要針對大表做特殊處理。

超過 1GB 的單表通常是 log 表、歷史紀錄表、或含有二進位大物件（BLOB）的表。對這類表的備份策略跟業務表不同：

• log / 歷史表：備份時可以加 --where="created_at > DATE_SUB(NOW(), INTERVAL 90 DAY)" 只匯出近期資料，歷史資料另做一次性歸檔
• BLOB 欄位（圖片、PDF）：用 --no-data 單獨匯出 schema，BLOB 內容如果已經搬到檔案系統或 CDN，資料庫裡只需要保留路徑參考
• InnoDB 大表：--single-transaction 避免鎖表，但匯出期間的記憶體消耗跟表大小成正比，本機如果記憶體不足可以加 --quick（逐行讀取、不緩衝整張表）

1# 大表匯出：逐行讀取 + 一致性快照 + 壓縮
2mysqldump -h db-host.example.com -u dbuser -p \
3  --single-transaction --quick \
4  dbname large_table | gzip > large_table_$(date +%Y%m%d).sql.gz

資料庫規模成長到備份時間超過維護視窗（例如匯出要兩小時但只有一小時的低流量時段），代表這類環境的備份能力已經到頂，需要評估升級到有 automated snapshot 的 managed MySQL 或 VPS。

跨分類引用

• → 無 SSH 的 FTP / 面板管理環境接管：主文，涵蓋程式碼備份、部署紀律與整體接管流程
• → 程式碼版控與 FTP 部署紀律：DB migration 跟 code deploy 要同步——schema 改了但 code 沒跟上會讓服務壞掉
• → Legacy PHP 的安全盤點：DB credential 的掃描與保護、SQL injection 風險評估
• → Stateful 資源保護與跨服務依賴：IaC 環境裡的備份、deletion protection 與 PITR 設計
• → 治理好習慣：tagging、secret 管理與成本可見性的長期治理

從 FTP 拉下來建立 Git repo

用 FTP client 把整個站台完整下載到本地目錄，這份下載就是 production 的快照。下載完成後在該目錄初始化 Git：

1cd /path/to/downloaded-site
2git init

在第一次 commit 之前先處理 .gitignore。PHP 專案需要排除的檔案分三類：套件依賴（由 Composer 或 npm 管理、可重建）、執行期產物（快取、session、上傳檔案）、以及含有機密值的設定檔。

 1# 套件依賴
 2vendor/
 3node_modules/
 4
 5# 執行期產物
 6cache/
 7tmp/
 8sessions/
 9*.log
10
11# 使用者上傳內容（通常很大、且屬於資料不屬於程式碼）
12uploads/
13media/
14wp-content/uploads/
15
16# 機密設定（下一節處理）
17.env
18config.local.php
19wp-config.php

使用者上傳的內容（uploads/、media/）不進 Git 的理由是它屬於資料層：檔案數量可能成千上萬、總容量可能數 GB，Git 不適合管理這類大量二進位檔案。這些檔案的備份策略跟程式碼不同——用 FTP mirror 或 rclone 定期同步到本地即可。

設好 .gitignore 後做第一次 commit：

1git add -A
2git commit -m "production snapshot $(date +%Y-%m-%d)"

這個 commit 就是「接手時 production 長什麼樣」的基準線。後續所有改動都從這裡開始有版本歷史。

Config 分離：讓 Git repo 不含機密值

無 SSH 環境的 PHP 專案常把資料庫密碼、API key、SMTP 憑證直接寫在 config.php 或 wp-config.php 裡。這些檔案如果進了 Git，機密值就跟著 repo 走——推到 GitHub 就等於公開。

分離的模式是把設定拆成兩份：一份進 Git（結構與預設值）、一份不進 Git（實際機密值）。

模式一：.env 檔案

使用 vlucas/phpdotenv 套件或手動解析，讓程式碼從 .env 檔案讀取環境變數：

1// config.php — 進 Git
2$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
3$dotenv->load();
4
5$db_host = $_ENV['DB_HOST'];
6$db_name = $_ENV['DB_NAME'];
7$db_user = $_ENV['DB_USER'];
8$db_pass = $_ENV['DB_PASS'];

1# .env — 不進 Git（.gitignore 已排除）
2DB_HOST=localhost
3DB_NAME=mysite_prod
4DB_USER=mysite_user
5DB_PASS=actual-password-here

同時在 repo 裡放一份 .env.example（進 Git），列出所有需要的環境變數但不填實際值：

1# .env.example — 進 Git，作為範本
2DB_HOST=
3DB_NAME=
4DB_USER=
5DB_PASS=
6SMTP_HOST=
7SMTP_USER=
8SMTP_PASS=

模式二：config.local.php

如果專案不使用 Composer、引入 phpdotenv 成本太高，用 PHP include 分離：

1// config.php — 進 Git
2if (file_exists(__DIR__ . '/config.local.php')) {
3    require __DIR__ . '/config.local.php';
4} else {
5    die('config.local.php not found. Copy config.local.example.php and fill in values.');
6}

1// config.local.php — 不進 Git
2$db_host = 'localhost';
3$db_name = 'mysite_prod';
4$db_user = 'mysite_user';
5$db_pass = 'actual-password-here';

WordPress 的處理

WordPress 的 wp-config.php 同時包含機密值和非機密設定。把整份排除再 include 一份 local 版是最簡單的做法，但也可以只把機密值抽到 .env、wp-config.php 本身保留在 Git 裡：

1// wp-config.php — 進 Git（機密值從 .env 讀）
2$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
3$dotenv->load();
4
5define('DB_NAME', $_ENV['DB_NAME']);
6define('DB_USER', $_ENV['DB_USER']);
7define('DB_PASSWORD', $_ENV['DB_PASSWORD']);
8define('DB_HOST', $_ENV['DB_HOST'] ?? 'localhost');

分離完成後，用 grep 確認 repo 裡沒有殘留的明文密碼：

1git grep -in "password\|passwd\|secret\|api_key\|smtp" -- '*.php' ':!*.example*'

任何命中都要評估：是真的機密值（要移到 .env）還是變數名稱（可以保留）。

FTP 部署的風險控制

FTP 上傳是逐檔覆寫，沒有交易性——上傳到一半斷線、或上傳了有語法錯誤的 PHP 檔案，站台會立刻出問題。風險控制的核心是「每次上傳前知道在改什麼、上傳後知道改了什麼」。

上傳前的比對

FileZilla 的目錄比較功能（「檢視 → 目錄比較 → 啟用」）可以在上傳前看到本地與遠端的差異：哪些檔案是本地較新、哪些是遠端較新、哪些只存在於一邊。上傳前先跑比較、確認差異清單符合預期——如果出現預期外的「遠端較新」檔案，代表有人在伺服器上直接改了東西，要先下載回來合併再上傳。

只上傳改過的檔案

一次上傳整個站台目錄既慢又危險。只上傳 Git diff 顯示的改動檔案：

1# 列出相對於上次部署 tag 改了哪些檔案
2git diff --name-only deploy-2026-06-25 HEAD

把這份清單對照 FileZilla 的比較結果，逐一上傳。量大時用 lftp 的 mirror 指令加 --only-newer flag 只傳新檔。

關鍵檔案的額外保護

index.php、.htaccess、設定檔這類檔案壞掉會讓整個站台無法存取。上傳這些檔案之前，先從伺服器下載一份當前版本存到本地的 _backup/ 目錄（gitignored）。如果上傳後站台出問題，可以立刻把備份版本傳回去。

部署前後的驗證

部署前檢查

部署後驗證

上傳完成後立刻驗證：

1. 首頁能正常載入（HTTP 200、頁面內容正確）
2. 本次改動涉及的功能可正常操作
3. 如果是電商站：結帳流程、金流 callback 測試
4. 檢查 PHP error log（cPanel → 錯誤日誌、或 FTP 下載 error_log 檔案）

如果驗證失敗，回退方式是從 Git 歷史取出上一個版本的受影響檔案重新上傳：

1# 取出上一個部署 tag 的特定檔案
2git show deploy-2026-06-25:path/to/file.php > _rollback/file.php
3# 用 FTP 上傳 _rollback/file.php 覆蓋 prod

CI 化 FTP 部署

手動 FTP 部署的問題是它依賴特定人的 FTP client 和操作紀律。用 GitHub Actions 把 FTP 上傳自動化，可以讓部署變成「push 到 main → CI 跑測試 → CI 上傳到伺服器」的流程，不依賴任何人的本地環境。

 1name: Deploy via FTP
 2on:
 3  push:
 4    branches: [main]
 5
 6jobs:
 7  deploy:
 8    runs-on: ubuntu-latest
 9    steps:
10      - uses: actions/checkout@v4
11        with:
12          fetch-depth: 2
13
14      - name: Deploy to FTP
15        uses: SamKirkland/FTP-Deploy-Action@v4
16        with:
17          server: ${{ secrets.FTP_HOST }}
18          username: ${{ secrets.FTP_USER }}
19          password: ${{ secrets.FTP_PASS }}
20          server-dir: /public_html/
21          exclude: |
22            **/.git*
23            **/.git*/**
24            **/node_modules/**
25            **/.env
26            **/config.local.php

FTP 憑證存在 GitHub repo 的 Secrets 裡（Settings → Secrets and variables → Actions），不寫在 workflow 檔案裡。

CI 化後的改變

限制

FTP 部署沒有原子性（atomic deployment）——檔案逐一上傳的過程中，伺服器上同時存在新舊版本的檔案混合狀態。如果上傳的檔案之間有依賴關係（新的 A.php 引用新的 B.php，但 B.php 還沒上傳完），短暫的錯誤窗口無法避免。流量高的站台如果需要零停機部署，需要升級到 SSH + symlink 切換的部署方式，那屬於 VPS 遷移之後的能力。

Git tagging 部署紀錄

每次部署前在 Git 打一個 tag，讓「這次部署的是哪個版本」有明確的錨點：

1git tag deploy-$(date +%Y-%m-%d-%H%M)
2git push origin --tags

tag 的命名用日期時間戳而非版號，因為這類專案通常沒有語意化版號的概念。tag 的作用是：

• 回退時知道要退到哪個版本（git diff deploy-previous deploy-current 看這次改了什麼）
• 多次部署之間的差異可追蹤
• CI 化後可以用 tag 觸發部署而非每次 push 都部署

資料庫變更的回退跟程式碼獨立處理——程式碼可以靠 Git 回退，資料庫要靠 SQL dump 回退，兩者的回退點要對齊但機制不同。資料庫的備份策略見資料庫備份與變更管理。

跨分類引用

• → 無 SSH 的 FTP / 面板管理環境接管：本篇的母文章，涵蓋接手的完整流程
• → 資料庫備份與變更管理：資料庫端的備份、migration 紀律與回退策略
• → Legacy PHP 的安全盤點：credential 分離之後的存取控制與安全掃描
• → 無 SSH 環境的監控與告警：部署後用外部監控驗證服務正常
• → 模組七：infra 走 PR 流程：從 FTP CI 化進一步演進到完整的 PR review 流程

Credential 掃描與處理

寫死在程式碼裡的 credential 是接手後最先要掌握的風險面。資料庫密碼、API key、SMTP 帳號這些值如果散落在多個 PHP 檔案裡，每一個都是外洩路徑。

掃描方式

用 grep 對整個 codebase 搜尋常見的 credential 關鍵字：

1grep -rn "password\|passwd\|secret\|api_key\|app_key\|mysql_connect\|mysqli_connect\|PDO(" \
2  --include="*.php" .

常見的集中位置是 config.php、wp-config.php、database.php、settings.php，以及專案根目錄的 .env。但 legacy 專案的 credential 經常散落在意想不到的地方——寫在某個 helper function 的預設參數裡、硬編碼在 cron job 的 PHP 檔案裡、或藏在某個很久沒改的 email 發送模組裡。grep 的涵蓋範圍應該是整個專案目錄，不只是已知的 config 檔案。

如果專案已經在本地 Git repo（見主文的快照步驟），檢查 Git 歷史裡有沒有曾經存在但後來被刪除的 credential：

1git log --all -p -- '*.php' | grep -i "password\|secret\|api_key" | head -30

歷史裡的 credential 無法從 Git 裡真正移除（rewrite history 可以但成本高），所以找到的 credential 都要列入輪替清單。

處理方式

掃描結果彙整成一張清單，每筆記錄：credential 類型、所在檔案、用途、是否可輪替。處理優先序：

把 credential 從 code 移到 .env 後，用 getenv('DB_PASSWORD') 或框架的 config 機制讀取。.env 加進 .gitignore，prod 的 .env 透過 FTP 單獨上傳、不進版本控制。

PHP 版本與已知漏洞

PHP 版本決定了這個專案暴露在什麼層級的平台風險下。已結束安全支援（EOL）的 PHP 版本不代表「馬上會被攻擊」，但代表任何未來被發現的漏洞都不會得到官方修補。

版本確認

在站台放一個 phpinfo.php，瀏覽後記錄版本號，完成後立刻刪除（phpinfo() 輸出含伺服器路徑與配置細節，留在 prod 上是資訊外洩）：

1<?php phpinfo(); ?>

或在 cPanel / Plesk 的 PHP 設定頁面直接查看。

版本風險對照

版本升級是獨立的工程專案——可能會觸發函式棄用警告、行為變更、甚至語法不相容。盤點階段的任務是記錄版本和風險等級，升級規劃放在穩定維運之後。

常見的 PHP 安全漏洞模式

Legacy PHP 專案最常見的四類漏洞都可以用 grep 做初步掃描。掃描結果是候選清單、不是確認的漏洞——每個命中都需要讀上下文確認是否有防護。

SQL injection

任何把使用者輸入直接拼接到 SQL 查詢裡的寫法都是 SQL injection 的候選：

1# 找使用 mysql_query / mysqli_query 但沒有 prepare/bind 的查詢
2grep -rn "mysql_query\|mysqli_query" --include="*.php" . | grep -v "prepare\|bind_param"
3
4# 找字串拼接的 SQL 查詢
5grep -rn "query.*\\\$_GET\|query.*\\\$_POST\|query.*\\\$_REQUEST" --include="*.php" .

修法是改用 prepared statement（PDO 或 mysqli 的 prepare + bind_param）。如果 codebase 大量使用 mysql_* 函式（PHP 7.0 已移除），這本身就是版本升級的阻礙——需要同時處理。

XSS（跨站腳本）

把使用者輸入直接輸出到 HTML 而沒有跳脫：

1# 找直接 echo/print 使用者輸入的地方
2grep -rn "echo.*\\\$_GET\|echo.*\\\$_POST\|echo.*\\\$_REQUEST\|echo.*\\\$_COOKIE" --include="*.php" .
3
4# 找 PHP 短標籤輸出
5grep -rn "<?=.*\\\$_" --include="*.php" .

修法是所有輸出都經過 htmlspecialchars($var, ENT_QUOTES, 'UTF-8')。模板引擎（如 Twig、Blade）預設會做跳脫，使用模板引擎的專案 XSS 風險較低。

檔案包含（File Inclusion）

把使用者輸入當作 include 或 require 的路徑：

1grep -rn "include.*\\\$_\|require.*\\\$_\|include_once.*\\\$_\|require_once.*\\\$_" --include="*.php" .

這類寫法讓攻擊者可以指定載入任意檔案（本地或遠端）。修法是用白名單限制可載入的檔案路徑。

檔案上傳

檢查上傳處理的三個面向：副檔名驗證（只允許白名單）、上傳目錄是否可執行 PHP（不應該）、檔案大小限制。

1# 找上傳處理程式碼
2grep -rn "move_uploaded_file\|\\\$_FILES" --include="*.php" .

每個命中的上傳處理都要確認：有沒有驗證副檔名（黑名單不夠、要白名單）、上傳目錄有沒有 .htaccess 禁止 PHP 執行（見下節）、有沒有重新命名上傳的檔案（避免覆寫攻擊）。

Session 管理

1# 找 session 相關設定
2grep -rn "session_start\|session_regenerate_id\|session\.cookie_httponly\|session\.cookie_secure" --include="*.php" .

確認：登入成功後有沒有呼叫 session_regenerate_id(true) 防止 session fixation、session.cookie_httponly 是否為 on（防止 JavaScript 讀取 session cookie）、session.cookie_secure 在 HTTPS 站台是否為 on。

.htaccess 安全設定

無 SSH 的 Apache 環境中 .htaccess 是可用的伺服器端安全防線。盤點時確認這些設定是否存在，缺少的補上。

基礎安全設定

 1# 禁止目錄列表 — 防止瀏覽上傳目錄的檔案清單
 2Options -Indexes
 3
 4# 阻擋敏感檔案的 HTTP 存取
 5<FilesMatch "\.(env|local|bak|sql|log|ini|conf|yml|json|lock|md)$">
 6    Require all denied
 7</FilesMatch>
 8
 9# 阻擋隱藏檔案與目錄（.git、.env 等）
10<IfModule mod_rewrite.c>
11    RewriteEngine On
12    RewriteRule (^\.|/\.) - [F]
13</IfModule>
14
15# 強制 HTTPS
16<IfModule mod_rewrite.c>
17    RewriteCond %{HTTPS} off
18    RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
19</IfModule>

上傳目錄的 PHP 執行禁令

在上傳目錄（如 uploads/、wp-content/uploads/）放一個獨立的 .htaccess：

1# 禁止此目錄下的 PHP 執行
2php_flag engine off
3
4# 只允許靜態檔案類型
5<FilesMatch "\.(?!jpg|jpeg|png|gif|pdf|webp|svg|css|js)">
6    Require all denied
7</FilesMatch>

這條設定讓即使攻擊者成功上傳了 .php 檔案，也無法透過 HTTP 請求觸發執行。

安全 header

 1# 防止 MIME type sniffing
 2Header set X-Content-Type-Options "nosniff"
 3
 4# 防止 clickjacking
 5Header set X-Frame-Options "SAMEORIGIN"
 6
 7# XSS 防護（現代瀏覽器多已內建、但舊站加上無害）
 8Header set X-XSS-Protection "1; mode=block"
 9
10# Referrer 資訊控制
11Header set Referrer-Policy "strict-origin-when-cross-origin"

檔案權限

無 SSH 環境的權限控制能力有限——多數情況下透過 FTP client 檢查和調整。

777 權限（所有人可讀寫執行）在多租戶主機上等於同一台伺服器的其他租戶也能讀寫這些檔案。如果發現任何目錄或檔案是 777，立刻改回 755/644。FileZilla 在檔案上按右鍵 → 「File permissions」可以查看和修改。

外部依賴的安全性

Composer 管理的依賴

如果專案使用 Composer，在本地跑一次已知漏洞檢查：

1composer audit

這條指令比對 composer.lock 裡的每個套件版本與 Packagist 的安全公告資料庫，列出有已知 CVE 的套件。

手動管理的依賴

沒有 Composer 的 legacy 專案可能直接把第三方程式碼複製進專案目錄。常見的高風險依賴：

JavaScript CDN 引用

檢查 HTML 裡引用的外部 JavaScript CDN 連結，確認：使用 integrity 屬性（Subresource Integrity）防止 CDN 被竄改、引用的 CDN 是否仍在維護。

掃描工具

除了手動 grep，可以用工具做自動化掃描。這些工具都從本地或外部執行，不需要在 prod 伺服器上安裝任何東西。

WordPress 站台的掃描指令：

1# WPScan 掃描（從本地執行、掃描遠端站台）
2wpscan --url https://example.com --enumerate vp,vt,u
3# vp = vulnerable plugins, vt = vulnerable themes, u = users

所有掃描結果存進 repo 的 security-audit/ 目錄，標上日期。這份報告是後續修補計畫的輸入，也是向管理層說明安全狀態的依據。

跨分類引用

• → 無 SSH 的 FTP / 面板管理環境接管：本文的前置步驟（程式碼與資料庫快照）
• → 資料庫備份與變更管理：SQL injection 修復前先備份，避免修補過程造成資料遺失
• → 無 SSH 環境的監控與告警：安全事件的持續偵測與錯誤追蹤
• → 模組二：身分與憑證地基：credential 管理的系統性設計
• → Backend 模組七：資安與資料保護：應用層安全的完整討論

可用性監控（外部 HTTP check）

外部 HTTP check 的運作方式是從第三方伺服器定期對目標 URL 發 HTTP 請求，驗證回應狀態碼、回應時間、以及頁面內容是否包含預期的文字。服務掛了或回應異常時觸發告警。

工具選型

UptimeRobot 的免費方案對多數無 SSH 環境的站台足夠——50 個 monitor 可以覆蓋一個站台的主要入口。

該監控哪些 URL

選監控目標的判準是「這個 URL 掛了代表哪一層出問題」：

每個 monitor 設兩層閾值：回應時間 >3 秒為警告（效能劣化的早期訊號）、>10 秒或非 200 狀態碼為嚴重（服務已不可用）。

告警通道

免費方案通常支援 email 與 webhook（可串 Slack）。付費方案加 SMS 和電話。接手初期用 email + Slack 即可，等確認告警不會誤報後再決定要不要升級到 SMS。頻繁誤報會讓團隊學會忽略通知——閾值要設在「真的有問題才響」的水位。

錯誤追蹤（不需要 server agent）

PHP 的錯誤追蹤在無 SSH 環境有兩條路徑：server 端用 PHP 內建的 error_log、client 端用不需要安裝的 SaaS 服務。

PHP error_log（server 端、不需 SSH）

PHP 可以把錯誤寫進檔案，設定方式是在 .htaccess 或 php.ini（如果主機允許）加入：

1# .htaccess — 啟用錯誤記錄、關閉畫面顯示
2php_flag display_errors off
3php_flag log_errors on
4php_value error_log /home/user/logs/php_errors.log

error_log 的路徑要指向 web root 之外的目錄，避免錯誤訊息被外部存取。設定後透過 FTP 定期下載這個檔案、用 grep 篩選嚴重等級：

1# 篩選 Fatal 和 Warning（過濾掉 Notice / Deprecated）
2grep -E "Fatal|Warning" php_errors.log | tail -50

Sentry（PHP + JavaScript、不需 server agent）

Sentry 的 PHP SDK 不需要系統層 agent，只需要在應用程式碼裡初始化：

1composer require sentry/sentry

1// 在應用程式進入點（如 index.php 最前面）加入
2\Sentry\init([
3    'dsn' => 'https://examplekey@o0.ingest.sentry.io/0',
4    'traces_sample_rate' => 0.1,
5]);

這段程式碼會在 PHP 拋出未捕捉的例外或觸發 error 時，把錯誤資訊（stack trace、request context、使用者資訊）透過 HTTP 送到 Sentry 的 SaaS 平台。免費方案每月 5,000 個事件，對流量不大的流量不大的站台通常足夠。

前端的 JavaScript 錯誤追蹤更簡單——在 HTML 的 <head> 加一行 Sentry 的 CDN script，不需要修改 server 設定：

1<script
2  src="https://browser.sentry-cdn.com/8.x/bundle.tracing.min.js"
3  crossorigin="anonymous"
4></script>
5<script>
6  Sentry.init({ dsn: "https://examplekey@o0.ingest.sentry.io/0" });
7</script>

JavaScript SDK 捕捉的是瀏覽器端的錯誤——DOM 操作失敗、AJAX 請求異常、未處理的 Promise rejection。跟 PHP 端的 SDK 各抓不同層的問題。

error_log vs Sentry 的分工

error_log 是 server 端的文字紀錄，需要手動下載和篩選；Sentry 有搜尋、聚合、告警和 stack trace 視覺化。兩者互補：error_log 保留完整紀錄作為備份、Sentry 提供可操作的告警和分析介面。error_log 在 PHP 嚴重到 Sentry SDK 自己也掛掉的情況下仍然有紀錄。

效能基線

效能基線的責任是回答「正常狀態下回應時間是多少」，讓異常浮現時有比對的參考。沒有基線時，回應時間從 200ms 劣化到 2 秒、但因為「好像一直都這麼慢」而沒人察覺。

量測方式

最簡單的量測是從本機或 CI 環境定期 curl：

1# 量測回應時間（秒），只看 time_total
2curl -o /dev/null -s -w "%{time_total}\n" https://example.com

把這段做成 GitHub Actions 的 scheduled workflow，每小時跑一次、把結果追加到 repo 的 CSV 檔案，就有了一條回應時間的趨勢線：

 1on:
 2  schedule:
 3    - cron: '0 * * * *'
 4jobs:
 5  perf-check:
 6    runs-on: ubuntu-latest
 7    steps:
 8      - uses: actions/checkout@v4
 9      - run: |
10          TIME=$(curl -o /dev/null -s -w "%{time_total}" https://example.com)
11          echo "$(date -u +%Y-%m-%dT%H:%M:%SZ),$TIME" >> perf-log.csv
12      - run: git add perf-log.csv && git commit -m "perf check" && git push

這條趨勢線本身就是監控：回應時間連續幾個小時上升，代表某個東西在劣化（DB 查詢變慢、磁碟快滿、PHP process 卡住）。

頁面效能

Google PageSpeed Insights（免費、不需安裝）分析前端載入效能，包含 LCP、CLS、FID 等 Core Web Vitals。對 legacy PHP 站台有用的是它會指出渲染阻塞的 CSS/JS、未壓縮的圖片、缺少快取 header 這類不需要動後端就能改善的問題。

資料庫效能（需改 code）

如果能修改 PHP 程式碼，在資料庫查詢前後加計時、超過閾值就寫 error_log：

1$start = microtime(true);
2$result = $pdo->query($sql);
3$elapsed = microtime(true) - $start;
4if ($elapsed > 1.0) {
5    error_log(sprintf("Slow query (%.2fs): %s", $elapsed, substr($sql, 0, 200)));
6}

累積一段時間後，從 error_log 裡 grep Slow query 就能看出哪些查詢是效能瓶頸。這不是完整的 APM，但在沒有 agent 的環境裡是最接近 slow query log 的替代方案。

帳單與流量異常偵測

這類主機通常按流量或磁碟空間計費，異常流量（bot 掃描、DDoS、爬蟲）會讓帳單飆高或觸發主機商的流量限制。

流量監控

主機控制面板（cPanel 的 AWStats 或 Webalizer）提供基本的流量分析——top referrer、top page、bot 流量佔比。每月檢查一次，重點看：

• bot 流量佔比是否異常高（>50% 通常代表有爬蟲）
• 單一 IP 的請求量是否異常集中
• 帶寬使用量的趨勢（月增超過 20% 且沒有對應的業務成長要查原因）

客戶端分析（不需 server 安裝）

Google Analytics 或 Plausible（隱私友善替代品）只需要在頁面加一段 JavaScript。它們追蹤的是真實使用者的瀏覽行為（page view、session、referrer），跟 server 端的 access log 互補：server log 看所有請求（含 bot），GA/Plausible 只看真實瀏覽器。

Cloudflare 免費方案

如果 DNS 可以切換，把 domain 接上 Cloudflare（免費方案）提供三個能力而不需要動 server：

• 流量分析：比 AWStats 更即時、有地理分佈和 bot 過濾
• DDoS 保護：基本的 Layer 3/4 防護免費
• CDN 快取：靜態資源（CSS/JS/圖片）由 Cloudflare 快取、減輕 origin 負擔

設定只需要把 domain 的 nameserver 改成 Cloudflare 提供的 NS、原始 DNS record 在 Cloudflare 重建。對無 SSH 環境的站台來說這是投資報酬率最高的單一改善動作——不動 server、不改 code、但同時拿到流量可見性和基本防護。

整合成最低成本監控方案

按投入程度分三層，每一層都包含上一層：

Tier 1 在接手當天就能建好（30 分鐘設定 UptimeRobot + Sentry + GA），零成本提供基本的「服務掛了會知道、程式碼出錯會收到、流量異常看得到」的覆蓋。Tier 2 適合站台有營收或合約 SLA 要求時。Tier 3 是離開無 SSH 環境後的正規化路徑，監控從外部觀測升級為 server 端全面可觀測性，見模組六：可觀測性與 log。

跨分類引用

• → 無 SSH 的 FTP / 面板管理環境接管：本篇的母篇，監控建立在盤點與本地環境之後
• → 程式碼版控與 FTP 部署紀律：部署後的驗證用監控確認服務正常
• → Legacy PHP 的安全盤點：錯誤追蹤可能暴露安全問題（未捕捉的 SQL error、路徑洩漏）
• → 模組六：可觀測性與 log：Tier 3 升級路徑的目標——有 server 存取後的 IaC 監控
• → Monitoring 監控體系：客戶端行為訊號（SDK / Collector）的完整討論

概念位置

接手 PHP 專案時，Composer 是判斷「專案依賴了什麼、版本有沒有已知漏洞」的入口。專案根目錄通常有三個 Composer 相關的檔案：

可觀察訊號

接手專案時如果根目錄有 composer.json 但沒有 vendor/，代表需要先跑 composer install 才能讓專案運作。如果連 composer.lock 都沒有，代表套件版本沒有鎖定——每次安裝可能拿到不同版本。

設計責任

兩個常用指令的差別：

• composer install：按 composer.lock 安裝確切版本。用於部署和接手——確保每台機器安裝的版本一致。
• composer update：重新解析 composer.json 的版本範圍、更新到最新的符合版本、改寫 composer.lock。用於主動升級依賴。

接手時的關鍵操作：

• composer audit：掃描已安裝套件的已知安全漏洞
• composer outdated：列出可更新的套件及其最新版本

鄰卡

• .env：Composer 管套件、.env 管設定值，兩者都是 PHP 專案的基礎設施
• php.ini / .user.ini：Composer 需要 PHP CLI 執行，php.ini 的 memory_limit 和 max_execution_time 會影響 Composer 能不能跑完

Sanctum PAT 的核心設計是把「找 row」與「比對 secret」拆成兩個責任。Laravel Sanctum 的 Personal Access Token（簡稱 PAT）長這樣：

11|abc123def456ghi789jkl012mno345pqr678stu
2↑           ↑
3DB 主鍵     真正的祕密

豎線前的數字是 personal_access_tokens 資料表的 primary key、豎線後是高熵隨機字串。這個設計在 Laravel 生態裡很常見、但常被誤解為「業界標準 token 格式」 — 實際上是 Sanctum 特定的設計選擇、跟 GitHub PAT（ghp_...）、Stripe API Key（sk_live_...）的設計取捨完全不同。

本文拆解 Sanctum PAT 三個關鍵設計決策：

1. 為什麼把 PK 公開放進 token
2. DB 為什麼只存 hash 不存原文
3. constant-time 比對為什麼放在應用層、不放在 DB

讀完後，你可以用 token 的傳播範圍、撤銷需求與洩漏偵測需求，判斷自己的 application 適合 Sanctum 風格還是其他 token format，並把 hash 儲存與 constant-time 比對原則套用到非 Laravel 環境。

本文位置：本文是 API 認證的三層信任邊界 Layer 1 的深入篇。主文聚焦「為什麼要分層」的心智模型、本文聚焦「Sanctum 這個特定實作怎麼設計、為什麼」。

Sanctum 在 Laravel 認證生態的位置

Laravel 官方提供三套認證套件、各自解的問題不同：

Sanctum 的設計目標是「比 Passport 簡單、比手刻 token 嚴謹」 — 不引入 OAuth 的完整 flow，但解決 token issue、storage、revoke 的常見坑。{PK}|{secret} 是這個設計目標下的具體 trade-off。

設計決策一：為什麼把 PK 公開放進 token

驗證 token 的兩個責任

Server 收到 client 傳來的 token、要做兩件事：

1. 找到 DB 裡對應的 row（這個 token 是哪個 user 的）
2. 比對 確認 token 沒被偽造

如果 token 只是純隨機字串（沒有 PK 前綴），validation 的 SQL 常會被設計成：

1SELECT * FROM personal_access_tokens WHERE token = ?

這要求 token 欄位有 index，且 server 要讓 DB 同時負責 lookup 與 secret 比對。效能通常不是瓶頸，真正的設計問題是 secret 比對落在應用層控制範圍之外。

DB 比對的 timing 不可控

DB 查詢適合處理索引搜尋，不適合承擔機密字串的 timing-safe 比對。當 WHERE token = ? 在 DB 執行時，執行時間可能洩漏：

• B-tree index 的查找路徑長度（同 prefix 的 row 多時、走的 page 不同）
• 字串比對的短路行為（多數 DB 引擎不保證 constant-time 比對）
• Buffer pool hit / miss 造成的時間差

攻擊者透過大量探測，可能推斷出有效 token 的部分結構。雖然實務上利用這個 leak 攻擊成本很高，但更穩健的設計原則是：安全機制應放在 application 能明確控制的比對函式，而不是依賴 DB 引擎的實作細節。

Sanctum 的解法：用 PK 收斂搜尋、把比對搬到應用層

{PK}|{secret} 的設計把驗證拆成兩步：

 1client 傳來: "1|abc123..."
 2       ↓
 3   server 拆解
 4       ↓
 5   ┌──────────────┐
 6   │ PK = 1       │ ──→ SELECT * FROM tokens WHERE id = 1
 7   │ secret = abc │      （O(log N)、行為穩定）
 8   └──────────────┘
 9       ↓
10   拿到該 row 的 hash
11       ↓
12   hash_equals(stored_hash, sha256(secret))
13       ↓
14   constant-time 比對、不洩漏 timing

關鍵在於 DB 只負責「找到單一 row」、不負責「比對機密」：

常見誤解：「PK 讓查詢變 O(1)」

PK 前綴的主要價值是安全責任切分，不是把查詢從慢變快。很多 Sanctum 教學文章寫「PK 把查詢變 O(1)、避免 full scan」，這個說法忽略了 hash 欄位也能被索引：

• hash 欄位也能 index — WHERE token_hash = ? 用 B-tree index 是 O(log N)、不是 full scan
• 兩條路都是 B-tree index lookup — token 規模下都不會是效能瓶頸；clustered（PK）跟 secondary（hash）的 IO cost 微差在多數場景可忽略

PK 設計的主要價值在安全可預測性、效能差距在多數場景可忽略：把比對機密的責任明確劃在「應用層 constant-time 函式」、不依賴 DB 引擎不保證的 timing 行為。

效能差異反而出現在「hash 欄位是否要 index」 — 如果用 hash lookup、token_hash 欄位需要 unique index、寫入成本變高；用 PK lookup、token_hash 不需要 index、寫入更輕量。但這在 token 規模通常不是 bottleneck。

設計決策二：DB 只存 hash 的威脅模型

威脅模型：DB 被攻陷

Token 是 capability credential — 持有即授權。如果 DB 直接存 plaintext token、任何能讀取 DB 的人（SQL injection、備份外流、運維 dump 不小心 push 到 GitHub）都能直接拿 token 假冒使用者發 request。

Sanctum 的做法：

1// 發放 token
2$plaintext = Str::random(40);  // Sanctum 預設 40 char、base62 字元集
3$hash = hash('sha256', $plaintext);
4DB::table('personal_access_tokens')->insert([
5    'token' => $hash,           // DB 只存 hash
6    'tokenable_id' => $userId,
7]);
8return $tokenId . '|' . $plaintext;  // 只此一次回給 client、之後再也拿不到

意義：DB 被 dump 時，攻擊者拿到的是不可直接使用的 hash。攻擊者要還原 plaintext 需要對 SHA-256 做 preimage attack；對 40 字元高熵隨機字串而言，計算成本實務上不可行。

SHA-256 與 bcrypt 的適用差異

密碼儲存用 bcrypt / Argon2 是因為密碼通常熵低（人類記得住的東西、entropy 通常 < 40 bit）、要刻意慢、抵抗 offline brute-force。

Token 是高熵隨機字串（40 char base62 ≈ 238 bit entropy、比一般人類記得住的 password 高約 6 個數量級的熵）— 攻擊者就算拿到 hash、暴力枚舉 plaintext 的搜尋空間是 62^40 ≈ 10^71、宇宙年齡內試不完。在這個前提下：

在高熵 token 的前提下，SHA-256 的速度是優點，因為每次 API request 都需要驗證 token。bcrypt 的慢速設計主要服務低熵 password，套到高熵 token 會增加延遲而沒有對應的安全收益。

Salt 的適用邊界

bcrypt 用 salt 是為了防 rainbow table 攻擊（預算好常見密碼的 hash、查表）。Rainbow table 對「人類選的密碼」有效、對「40 char 高熵 token」無效（搜尋空間太大、預算表的成本超過直接 brute-force）。

所以 Sanctum 對 token 用 unsalted SHA-256，是符合「高熵隨機 token」威脅模型的選擇。若 credential 來源改成人類可記憶密碼，威脅模型就會改變，儲存策略也要回到 password hashing。

設計決策三：constant-time 比對放在應用層

Constant-time 比對在解什麼

== 或 strcmp 比對字串時、會「短路」 — 一發現不同就回傳 false：

1// 偽程式碼：strcmp 的典型實作
2for (i = 0; i < len; i++) {
3    if (a[i] != b[i]) return false;  // ← 在這裡 return、不跑完
4}
5return true;

攻擊者可量測「server 從收到 request 到回 401」的時間、推斷「前幾個 byte 是對的」：

實務上單次 request 的網路抖動遠大於這幾 μs、但攻擊者可重複幾百萬次取平均、把雜訊濾掉、最終推出整個 hash。這就是 timing attack。

Constant-time 函式的實作策略

Constant-time 比對的核心是「不論輸入長什麼樣、都跑完整個比對長度」：

1// 偽程式碼：constant-time 比對
2result = 0;
3for (i = 0; i < len; i++) {
4    result |= a[i] ^ b[i];  // 用 XOR 累積差異、不 return
5}
6return result == 0;

每次呼叫都跑完整個 loop、結果用 bitwise OR 累積、最後一次性比對。執行時間不依輸入內容變化。

各語言的 constant-time 比對函式

失效模式：用 ==、===、strcmp、String.equals 比對 hash，會讓執行時間受到第一個不同 byte 的位置影響。判讀訊號是驗證邏輯直接使用語言的一般字串相等運算；下一步路由是改用標準庫或框架提供的 constant-time 函式。

為什麼不放在 DB 層

DB 引擎大多不保證 constant-time 比對。MySQL、PostgreSQL 的字串比對為了效能，底層仍可能走短路邏輯；因此「WHERE hash = ?」即使加 index，也不適合被當成 timing-safe 的安全邊界。

Sanctum 的設計把 secret 比對完全搬到應用層用 hash_equals — DB 只負責「用 PK 找到單一 row」、應用層負責「比對 hash」。職責清楚、安全可預測。

Sanctum vs GitHub PAT vs Stripe API Key

三者都是 opaque token（隨機字串、server lookup）、但 format 設計取捨完全不同：

各自的設計動機

Sanctum：使用情境是「單一 Laravel application 自己發、自己驗」。Token 不會散落在公開 repo（除非開發者犯錯）、洩漏偵測不是首要需求。把 PK 直接放進 token、換 timing 安全與設計簡潔。

GitHub PAT：使用情境是「使用者把 token 寫進 CI config、push 到 public repo」。GitHub 把 ghp_ 前綴標準化、自家服務（Push Protection、Secret Scanning）會主動 scan 公開 repo、發現 ghp_... pattern 就通知 user 並 revoke。Token 的可辨識性是洩漏偵測 infrastructure 的一環、不是浪費字元。

Stripe API Key：使用情境跨 live 跟 test 環境、且有 public / secret 兩種 key。前綴設計：

• sk_live_ — secret key、live 環境（會收真錢）
• sk_test_ — secret key、test 環境
• pk_live_ — publishable key、live 環境（可放 client）
• pk_test_ — publishable key、test 環境

工程師看一眼就知道「這把 key 能幹嘛」、避免把 live key 寫進 test config。

怎麼選

表格的判準是 token 會不會離開受控環境。單一 Laravel app 內部使用時，Sanctum 的 PK 前綴足以支撐 lookup 與撤銷；對外 API、第三方整合或多環境部署時，prefix 可提供洩漏掃描與人工辨識訊號。也可以混用成 {prefix}|{PK}|{secret}，同時保留 lookup 收斂與語意辨識。

在非 Laravel 環境怎麼套用

Sanctum 的三個原則跨語言通用：

1. DB 只存 hash — 用任何語言的 SHA-256 / SHA-512 即可。Python: hashlib.sha256、Go: crypto/sha256、Node: crypto.createHash('sha256')
2. Lookup 用穩定字段 — 把「找到 row」跟「比對機密」分開、WHERE id = ? 是穩定的、WHERE hash = ? 在 timing 上不可控
3. 應用層 constant-time 比對 — 用本文上面表格列的函式、絕不用 ==

非 Laravel 框架的等效實作：

 1# Python + SQLAlchemy 範例
 2import secrets, hashlib, hmac
 3
 4def issue_token(user_id):
 5    plaintext = secrets.token_urlsafe(32)
 6    hash_value = hashlib.sha256(plaintext.encode()).hexdigest()
 7    token = PersonalAccessToken(user_id=user_id, hash=hash_value)
 8    db.session.add(token)
 9    db.session.commit()
10    return f"{token.id}|{plaintext}"  # 只此一次回給 client
11
12def verify_token(raw_token):
13    # production 範例需多一層 try-except 涵蓋 int() 轉型與 DB 例外
14    try:
15        token_id, plaintext = raw_token.split('|', 1)
16        token = PersonalAccessToken.query.get(int(token_id))
17    except (ValueError, TypeError):
18        return None
19    if not token:
20        return None
21    expected_hash = hashlib.sha256(plaintext.encode()).hexdigest()
22    if not hmac.compare_digest(token.hash, expected_hash):
23        return None
24    return token.user

 1// Go + sqlx 範例
 2func IssueToken(ctx context.Context, userID int64) (string, error) {
 3    plaintext := generateRandomString(40)
 4    hash := sha256.Sum256([]byte(plaintext))
 5    var tokenID int64
 6    err := db.QueryRowContext(ctx,
 7        "INSERT INTO personal_access_tokens (user_id, hash) VALUES ($1, $2) RETURNING id",
 8        userID, hex.EncodeToString(hash[:]),
 9    ).Scan(&tokenID)
10    if err != nil {
11        return "", err
12    }
13    return fmt.Sprintf("%d|%s", tokenID, plaintext), nil
14}
15
16func VerifyToken(ctx context.Context, raw string) (*Token, error) {
17    parts := strings.SplitN(raw, "|", 2)
18    if len(parts) != 2 {
19        return nil, ErrInvalidFormat
20    }
21    tokenID, err := strconv.ParseInt(parts[0], 10, 64)
22    if err != nil {
23        return nil, ErrInvalidFormat
24    }
25    var token Token
26    err = db.GetContext(ctx, &token, "SELECT * FROM personal_access_tokens WHERE id = $1", tokenID)
27    if err != nil {
28        return nil, err
29    }
30    expectedHash := sha256.Sum256([]byte(parts[1]))
31    storedHash, _ := hex.DecodeString(token.Hash)
32    if subtle.ConstantTimeCompare(storedHash, expectedHash[:]) != 1 {
33        return nil, ErrInvalidToken
34    }
35    return &token, nil
36}

兩者的關鍵都是：SELECT WHERE id = ? + 應用層 compare_digest / ConstantTimeCompare、不依賴 DB 比對 hash。

收尾

Sanctum 的 {PK}|{secret} 是一個特定情境下的設計取捨，不是業界通用標準：

• 它假設 token 不會散落到公開環境、所以不需要 prefix-based 洩漏偵測
• 它把比對機密的責任明確劃在應用層、不依賴 DB 引擎的 timing 行為
• 它用 SHA-256 + 不加 salt、因為 token 高熵時這個選擇符合威脅模型

如果你的場景符合這些假設，Sanctum 的設計可以直接使用。若場景是對外 API、需要洩漏偵測、多環境或多 token type，prefix-based format 會提供更好的操作訊號；儲存原則（hash + constant-time）則跨設計通用。

延伸閱讀：

• API 認證的三層信任邊界 — 本文的主篇、Sanctum 在「Layer 1 使用者層」的位置
• Shared Secret 安全輪替設計 — Layer 2 系統間 secret 的輪替議題
• mTLS 實際怎麼設定與運維 — Layer 2 進階方案的部署細節