在 ServBay 環境中安裝與配置 OctoberCMS

概述

OctoberCMS 是一款基於強大 Laravel 架構打造的開源內容管理系統（CMS），以其簡潔、靈活及開發者友好的特性廣受好評。本文件旨在指導您如何於 ServBay——專為 macOS 設計的一站式本機 Web 開發環境——內成功安裝並配置 OctoberCMS，讓您能快速啟動以 OctoberCMS 為基礎的專案開發。

什麼是 OctoberCMS？

OctoberCMS 提供直觀的後台介面及強大的前端開發能力，允許開發者透過熟悉的 Laravel 概念（如 Eloquent ORM、Blade 模板引擎等）來建構各式網站，從簡單部落格到複雜企業應用皆可。

前置條件

在開始安裝 OctoberCMS 前，請確認您符合下列條件：

您的 macOS 系統上已安裝並運行 ServBay。
ServBay 內已啟用並運作 PHP（建議 7.4 或更高版本）及 MySQL/MariaDB 軟體包。
ServBay 內已啟用 Composer 軟體包。
具備基礎指令行操作知識。

安裝 OctoberCMS 步驟

以下是在 ServBay 環境內安裝與配置 OctoberCMS 的詳細步驟：

步驟 1：建立專案目錄

首先，前往 ServBay 建議的網站根目錄 /Applications/ServBay/www，並在該位置建立新的資料夾以存放您的 OctoberCMS 專案。

bash

cd /Applications/ServBay/www
mkdir servbay-octobercms-app
cd servbay-octobercms-app

步驟 2：使用 Composer 安裝 OctoberCMS

ServBay 已內建並設定好 Composer，請確認您已在 ServBay 控制面板中啟用 Composer 軟體包。現在，於剛剛創建的專案目錄下執行 Composer 指令，下載並安裝 OctoberCMS 核心檔案：

bash

composer create-project october/october .

此指令會從 OctoberCMS 官方倉庫下載最新版 OctoberCMS 到目前目錄（.）。

步驟 3：建立資料庫與使用者

OctoberCMS 需要一個資料庫存放內容、使用者、設定等資訊。我們將使用 ServBay 內建的 phpMyAdmin 工具來建立資料庫與相關使用者。

進入 ServBay 內建的 phpMyAdmin 資料庫管理工具
開啟瀏覽器，進入 ServBay 的本機開發面板 https://servbay.host/。點選或導航至 ServBay 提供的 phpMyAdmin 連結，一般為 https://servbay.host/phpmyadmin/，進入 phpMyAdmin 管理介面。
建立資料庫與使用者
為確保安全及隔離，建議每個應用各自建立獨立的資料庫與使用者。
1. 前往「使用者帳號」頁面
  於 phpMyAdmin 首頁，點選上方選單中的「使用者帳號」。
2. 新增使用者帳號
  點擊「新增使用者帳號」。填入下列資訊：
  - 使用者名稱：輸入用於 OctoberCMS 連線的資料庫用戶，例如 october_user。
  - 主機名稱：選擇 localhost 或 127.0.0.1，即僅允許該用戶從本機連線，提升安全性。
  - 密碼：輸入一組安全且獨一無二的密碼。請勿於生產環境使用範例密碼 password123。
  - 再輸入一次：再次確認密碼。
  - 在「為使用者建立資料庫」區塊，選擇「以該使用者名稱建立同名資料庫並賦予所有權限」。這將自動建立一個名為 october_user 的資料庫，並授權給該用戶。
  - 確認在「全域權限」下已勾選「授予所有權限」（若上步已勾選建立同名資料庫並授權，這步通常會自動處理或不需另設定）。
  - 點擊頁面下方「執行」按鈕完成用戶及資料庫建立。

步驟 4：設定網站伺服器（於 ServBay 新增網站）

為能以瀏覽器訪問您的 OctoberCMS 應用，需於 ServBay 中設定本機網站。

新增網站
開啟 ServBay 控制面板，點選左側導覽欄的「網站」（注意：舊版可能顯示為「主機」）。點擊「新增網站」按鈕。
填入以下資訊：
- 名稱：為此網站命名，如 My OctoberCMS Site。
- 網域名稱：輸入於本機欲訪問的網域，例如 servbay-octobercms.local。請使用 .local 作結尾，以避免與真實網域衝突。
- 網站類型：選擇 PHP。
- PHP 版本：選定願意給 OctoberCMS 使用之 PHP 版本，請確保與 ServBay 內啟用版本一致，且符合 OctoberCMS 要求。
- 網站根目錄：點選瀏覽按鈕，選擇於步驟 1 建立的 /Applications/ServBay/www/servbay-octobercms-app 專案資料夾。
儲存設定並重啟 ServBay
完成設定後點擊儲存。ServBay 會提示應用變更，通常需重啟相關軟體包（如 Caddy 或 Nginx）及 ServBay 本身。請依指示操作，確保更動生效。ServBay 會自動將 servbay-octobercms.local 網域導向本機（127.0.0.1）。

步驟 5：設定 OctoberCMS 環境變數

OctoberCMS（基於 Laravel）透過 .env 檔案管理應用環境變數，如資料庫連線、應用金鑰等。

複製環境設定檔範本
於您的 OctoberCMS 專案根目錄（/Applications/ServBay/www/servbay-octobercms-app）複製 .env.example 並改名為 .env：
bash
```
cd /Applications/ServBay/www/servbay-octobercms-app
cp .env.example .env
```
1
2

編輯 .env 檔案

使用您偏好的文字編輯器開啟新建立的 .env 檔案。找到資料庫相關設定，並依照步驟 3 建立的資料庫資訊修改：

ini

# ... 其他設定 ...

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=october_user  # 請替換成您建立的資料庫名稱
DB_USERNAME=october_user  # 請替換成您建立的資料庫帳號
DB_PASSWORD=password123   # 請替換成您設置的密碼

# ... 其他設定 ...

重要提示： 請務必將 DB_DATABASE、DB_USERNAME 及 DB_PASSWORD 的值替換為實際設定的資訊。

步驟 6：執行 OctoberCMS 安裝精靈

OctoberCMS 提供網頁版安裝精靈，可完成最終設定，包括資料庫遷移及管理員帳號建立。

進入安裝頁面
打開瀏覽器，進入於步驟 4 設定的本機網域，加上 /install.php 路徑。例如：
https://servbay-octobercms.local/install.php
您應能看到 OctoberCMS 的安裝精靈頁面。
填寫資料庫資訊
安裝過程會請您輸入資料庫連線資訊。請填入 .env 檔內設定的相同內容：
- 資料庫類型：MySQL
- 資料庫主機：localhost 或 127.0.0.1
- 資料庫名稱：october_user
- 資料庫帳號：october_user
- 資料庫密碼：password123
（再次提醒，請務必使用您實際設定的密碼）
填寫管理員資訊
依頁面指示，設定欲用於登入 OctoberCMS 後台的管理員帳號，包括用戶名、密碼、電子信箱等。
完成安裝
點擊安裝精靈頁面的「安裝」或相關按鈕。安裝程式將執行資料庫建立、產生應用金鑰等程序。靜待安裝結束。

步驟 7：安裝插件與主題（選用）

安裝完成後，您可登入 OctoberCMS 管理後台（https://servbay-octobercms.local/backend）。

安裝插件
於後台導覽至「系統」→「更新」→「插件」。您可於 OctoberCMS Marketplace 搜尋並安裝所需插件以擴充功能。
安裝主題
導覽至「系統」→「更新」→「主題」。可瀏覽並安裝符合專案需求的主題。

安裝後的基本設定與操作

成功安裝 OctoberCMS 後，您便可開始建構網站。以下為常見初期操作：

前台訪問： 直接進入本機網域 https://servbay-octobercms.local/，可見網站前台頁面（通常為預設主題）。
後台訪問： 進入 https://servbay-octobercms.local/backend，以安裝時建立的管理員帳號登入。
建立頁面： 後台導覽至「CMS」→「頁面」以建立、編輯網站頁面。
製作內容區塊： 後台導覽至「CMS」→「內容」以建立可重複使用的內容片段。
設定主題： 於「CMS」→「主題」下可管理當前主題設定、佈局、模板片段等。
用戶與權限管理： 於「系統」→「管理」下管理後台用戶及其權限。

常見問題（FAQ）

問：存取 servbay-octobercms.local 顯示 ServBay 預設頁或出現錯誤？
- 答：請確認是否於 ServBay 控制面板成功新增 servbay-octobercms.local 網站，且根目錄正確指向 /Applications/ServBay/www/servbay-octobercms-app。設定後需確認 ServBay 已重啟且套用更動。亦可確認 ServBay 運作狀態及 Caddy/Nginx、PHP 軟體包均正在運行。
問：開啟 https://servbay-octobercms.local/install.php 發現空白頁或錯誤？
- 答：這通常為 PHP 錯誤。請於 ServBay 控制面板查看 PHP 錯誤日誌以獲取詳細訊息。常見原因包含檔案權限不足（請確認 storage、themes、plugins 目錄及其子目錄皆可供網頁伺服器用戶寫入）、PHP 版本不符或套件缺失等。
問：安裝過程中遇到資料庫連線錯誤？
- 答：請仔細檢查 .env 檔中的資料庫連線資訊（DB_HOST、DB_PORT、DB_DATABASE、DB_USERNAME、DB_PASSWORD）是否與 phpMyAdmin 實際建立的用戶與資料庫完全相符。確認 ServBay 中 MySQL/MariaDB 軟體包處於運行狀態。
問：執行 composer create-project 指令失敗？
- 答：請確認已在 ServBay 控制面板啟用 Composer 軟體包，及 PHP 軟體包已開啟且版本無誤。亦請檢查網路連線狀況，Composer 需下載相關檔案。

總結

透過 ServBay 所提供的便捷環境，您可在 macOS 上輕鬆且快速地安裝與設定 OctoberCMS。依本教學指引操作，即能為您的下個 Web 專案打造強大且開發者友善的本地開發平台。現在，就開始探索 OctoberCMS 豐富功能，構建令人驚艷的網站吧！

在 ServBay 環境中安裝與配置 OctoberCMS ​

概述 ​

什麼是 OctoberCMS？ ​

前置條件 ​

安裝 OctoberCMS 步驟 ​

步驟 1：建立專案目錄 ​

步驟 2：使用 Composer 安裝 OctoberCMS ​

步驟 3：建立資料庫與使用者 ​

步驟 4：設定網站伺服器（於 ServBay 新增網站） ​

步驟 5：設定 OctoberCMS 環境變數 ​

步驟 6：執行 OctoberCMS 安裝精靈 ​

步驟 7：安裝插件與主題（選用） ​

安裝後的基本設定與操作 ​

常見問題（FAQ） ​

總結 ​