PHP: 入門指南

如何在 Stackhero 上開始使用 PHP

👋 歡迎來到 Stackhero 文檔！

Stackhero 提供一個即用型的 PHP cloud 解決方案，帶來多種好處，包括：

只需一個簡單的 git push，即可在幾秒鐘內 部署您的應用程式。

使用您自己的域名，並享受 HTTPS 證書的自動配置，以增強安全性。

享受自動備份、一鍵更新，以及簡單、透明且可預測的定價，讓您高枕無憂。

得益於專用的私人 VM，獲得最佳的性能和強大的安全性。

節省時間並簡化您的生活：只需 5 分鐘即可嘗試 Stackhero 的 PHP cloud hosting 解決方案！

在 Stackhero 上部署您的 PHP 應用程式既簡單又強大。只需幾個步驟，您的專案就能上線並隨時可用。本指南將以友善且逐步的方式，帶您完成 PHP 服務的建立、設定及部署。

啟動 PHP 服務

首先，您可以直接在 Stackhero 控制台上建立 PHP 服務。介面設計簡潔直觀，讓您能快速完成設定。

先決條件

在開始之前，請確保您已準備好以下工具：

Git。可於 https://git-scm.com/downloads 下載。
Windows Terminal（Windows 用戶可選）。這個終端機能帶來更佳的操作體驗，可於 Microsoft Store 取得。

設定您的服務

主要需要設定的是您的 SSH 公鑰。您可以透過以下其中一個指令取得您的公鑰：

cat ~/.ssh/id_rsa.pub

或

cat ~/.ssh/id_ed25519.pub

如果您尚未擁有 SSH 金鑰對，可以在 Linux 或 macOS 上使用 ssh-keygen，或在 Windows 上使用 ssh-keygen.exe 來產生。

取得公鑰後，請前往 Stackhero 控制台，選擇您的 PHP 服務，進入設定頁面，並將公鑰貼到指定欄位。

Tip: 如果您希望將 SSH 公鑰預設套用到所有未來建立的服務，可以在全域設定。只需點擊控制台右上角的個人頭像，進入「您的個人檔案」，然後將 SSH 公鑰貼上即可。

複製範例專案

為協助您快速上手，我們準備了一個 PHP 範例應用程式。您可以用以下指令複製專案：

git clone https://github.com/stackhero-io/phpGettingStarted.git stackhero-php-getting-started
cd stackhero-php-getting-started

設定遠端儲存庫伺服器

Stackhero 讓您能輕鬆透過 Git 部署應用程式。請複製控制台 PHP 服務首頁上提供的 git remote 指令，格式如下：

git remote add stackhero ssh://stackhero@<XXXXXX>.stackhero-network.com:222/project.git

部署您的 PHP 程式碼

現在您已準備好部署應用程式。請使用以下指令推送您的程式碼：

git push stackhero main

首次推送時，系統會要求您確認金鑰指紋。請輸入「yes」以繼續。稍等片刻，您的應用程式就會上線。您可於 Stackhero 控制台所提供的網址（通常為 https://<XXXXXX>.stackhero-network.com）檢查服務狀態。

若要更新應用程式，只需修改 www/index.php（或其他需要的檔案），然後重新部署：

git add -A .
git commit -m "Update www/index.php"
git push stackhero main

部署現有應用程式

如果您已有 PHP 應用程式需要部署，只需將遠端儲存庫加入您的專案（請參閱設定遠端儲存庫伺服器），然後推送您的變更：

git push stackhero main

預設情況下，Stackhero 會在 www 目錄尋找您的 PHP 程式碼及靜態檔案。例如，當有人瀏覽 yourdomain.com/myphoto.jpg，系統會從 www/myphoto.jpg 提供檔案。如果您的應用程式使用不同的公開目錄，您可在 PHP 服務設定中調整此選項。

處理錯誤「failed to push some refs to '[...]'」

如果部署時遇到如下錯誤：

error: failed to push some refs to '[...]'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

這表示遠端 Git 儲存庫有您本地端沒有的變更。如果您確定要用本地版本覆蓋遠端，可以強制推送：

git push -f stackhero main

處理錯誤「src refspec main does not match any」

如果看到這個錯誤：

error: src refspec main does not match any
error: failed to push some refs to 'ssh://<XXXXXX>.stackhero-network.com:222/project.git'

通常代表本地端沒有 main 分支。此時，您可以改為推送 master 分支：

git push stackhero master

處理推送時顯示「Everything up-to-date」

如果 Git 顯示 Everything up-to-date，但您未看到變更被部署，通常是因為忘記提交變更。請執行以下指令：

git add -A .
git commit -m "您的提交訊息"
git push stackhero main

如果您沒有修改任何程式碼但仍想觸發部署，可以使用空提交：

git commit --allow-empty -m "Force update"
git push stackhero main

部署非 main 分支

若要部署其他分支（例如 production），請使用：

git push stackhero production:main

部署標籤（tag）

若要部署特定標籤（如 v1.0），請執行：

git push stackhero 'v1.0^{}:main'

^{} 可確保與該標籤相關的 commit 正確推送。

回滾或部署特定 commit

如需部署特定 commit，請先用 git log 查找其 hash，然後強制推送該 commit：

git push -f stackhero <HASH>:main

部署到多個環境

一般會為不同環境（如 production、staging）建立獨立服務。您可以透過重新命名及新增遠端儲存庫來管理。

將現有遠端從 stackhero 重新命名為 stackhero-staging：

git remote rename stackhero stackhero-staging

然後，於控制台建立新的 production PHP 服務，並新增遠端：

git remote add stackhero-production ssh://stackhero@<XXXXXX>.stackhero-network.com:222/project.git

之後，您可選擇部署到不同環境：

git push stackhero-production main

或

git push stackhero-staging main

將 SSH 私鑰密碼儲存到 macOS 鑰匙圈

如果您在 macOS 上每次推送程式碼時都被要求輸入 SSH 金鑰密碼，無需移除密碼，您可以將密碼安全地儲存在 macOS 鑰匙圈。請執行：

/usr/bin/ssh-add --apple-use-keychain ~/.ssh/id_rsa

完成後，macOS 推送程式碼時將不再詢問金鑰密碼。

管理機密資訊（secrets）

在 production 及 staging 環境，建議將敏感資料（如 token、密碼）安全儲存。請勿將機密資訊硬編碼於儲存庫，建議使用環境變數。您可於 Stackhero 控制台新增這些變數，然後在程式碼中存取。例如，若您建立名為 mySecret 的環境變數，可於 PHP 這樣取得：

getenv("mySecret")

管理 PHP 相依套件

當您推送程式碼時，Stackhero 的部署腳本會自動讀取您的 composer.json，並透過 Composer 安裝所需相依套件。

儲存檔案

若您的應用程式需要儲存檔案（如用戶上傳的照片），建議使用物件儲存（object storage）方案。這樣可方便多個服務共用檔案，並將上傳檔案與程式碼分離。您可以考慮 MinIO，這是一個快速、可靠且相容 S3 的解決方案。

如果您偏好使用本地儲存，可利用 PHP 實例內建的持久儲存空間，路徑為 /persistent/storage/。

例如，儲存上傳檔案時，可使用 move_uploaded_file 函式如下：

move_uploaded_file($_FILES['image']['tmp_name'], '/persistent/storage/image.jpg');

如需更多 PHP 檔案上傳資訊，請參閱官方文件：https://www.php.net/manual/en/features.file-upload.php。

注意： 請務必將資料儲存在 /persistent/storage/ 資料夾內。

若您的實例重啟或推送程式碼變更，儲存在持久儲存區以外的資料可能會遺失。