如何在 ServBay 中編譯 PostgreSQL 模組

在使用 ServBay 本地 Web 開發環境進行 PostgreSQL 開發時，可能會需要編譯並安裝額外的 PostgreSQL 模組（又稱擴充功能），以增強或擴展資料庫的功能。這些模組可以帶來新的資料型別、函式、運算子、索引存取方法等。

本文將詳細說明如何在 ServBay 環境下編譯並安裝 PostgreSQL 模組，並以編譯常用的 postgis（地理資訊系統支援）與 pg_jieba（中文斷詞）模組作為範例。

概述

ServBay 提供靈活且功能完整的開發環境，讓開發者可以在其集成的軟體包基礎上進行二次開發或編譯擴充元件。編譯 PostgreSQL 模組通常包括下載模組原始碼、設定編譯參數，使用特定的建構工具（如 make 或 cmake）進行編譯安裝，最後在 PostgreSQL 資料庫中啟用該模組。

成功的關鍵在於正確配置編譯環境，讓系統能尋找到 ServBay 內特定 PostgreSQL 版本的標頭檔、程式庫以及相關相依套件。

前置條件

在開始編譯任何 PostgreSQL 模組之前，務必依照 ServBay 指示初始化編譯環境。這個步驟很關鍵，會設定好編譯所需的工具鏈（編譯器、連結器等）、環境變數（如 $PATH, $CFLAGS, $LDFLAGS 等）與 ServBay 專屬的建構配置路徑。

詳盡步驟請參考 ServBay 官方文件中的 使用 ServBay 進行二次編譯 章節。請務必先完成該環境準備，通常會在 ServBay 終端內執行特定的環境初始化腳本。

指定 PostgreSQL 版本的重要性

ServBay 支援安裝與運行多個版本的 PostgreSQL 軟體包。由於 PostgreSQL 模組的編譯與運行會與資料庫特定版本相關（如依賴該版的標頭、函式庫和內部 API），因此在啟用編譯工具時，必須明確指定你要為哪一個 PostgreSQL 版本建構模組，以及對應的設定路徑。

選對 PostgreSQL 版本的組態路徑，才能保證編譯期間抓取到正確的相依元件，產生與目標 PostgreSQL 版本相容的模組檔案，避免編譯失敗、載入錯誤或執行時發生不可預期的問題。

本文將以 ServBay 已安裝的 PostgreSQL 15 版本（如 15.7）為例。請根據實際使用的 PostgreSQL 版本，調整路徑設定。

ServBay 會透過環境變數與 pg_config 工具協助你尋找正確路徑。${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/pg_config 是一個關鍵工具，能回報指定 PostgreSQL 版本的安裝路徑、編譯配置、函式庫、標頭目錄等。編譯外掛模組時，pg_config 能提供相依資訊，是指定依賴的關鍵。

編譯 postgis 模組

postgis 是 PostgreSQL 最受歡迎也最強大的擴充功能之一，能帶來地理空間資料型別與運算支援，讓 PostgreSQL 可存儲、查詢、分析空間資料。以下說明如何編譯 postgis-3.4.2 模組：

步驟 1：下載原始碼

首先，從 PostGIS 官方網站下載 postgis-3.4.2 的原始碼套件。請確認下載的是源碼（通常是 .tar.gz 或 .zip 格式）。

wget https://download.osgeo.org/postgis/source/postgis-3.4.2.tar.gz

wget 是常用的指令列下載工具，可從指定 URL 下載檔案。

步驟 2：解壓原始碼套件

將下載的 postgis-3.4.2.tar.gz 解壓，並進入源碼目錄：

tar zxvf postgis-3.4.2.tar.gz
cd postgis-3.4.2

tar zxvf 可解壓 .tar.gz 檔案；cd 變更目前目錄至 postgis-3.4.2 原始碼根目錄。

步驟 3：設定編譯選項

PostGIS 採用 GNU Autotools 為建構系統。這個設定步驟會檢查依賴、決定編譯特性並產生 Makefile。你需以設定參數指定 ServBay 內特定 PostgreSQL 版本的安裝路徑與其他必要的套件路徑。

./configure \
  --prefix=${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7 \
  --bindir=${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin \
  --datarootdir=${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/share \
  --with-protobufdir=${SERVBAY_BIN_PATH} \
  --disable-nls \
  --without-raster \
  --without-topology \
  --with-pgconfig=${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/pg_config \
  CFLAGS="${CFLAGS} -I${SERVBAY_COMMON_INCLUDE_PATH}/libxml2 -I${SERVBAY_COMMON_INCLUDE_PATH}" \
  CXXFLAGS="${CXXFLAGS} -std=c++17 -I${SERVBAY_COMMON_INCLUDE_PATH}/libxml2 -I${SERVBAY_COMMON_INCLUDE_PATH}" \
  LDFLAGS="${LDFLAGS} -L${SERVBAY_COMMON_LIB_PATH} -lxml2 -lz -lpthread -liconv -licui18n -licuuc -licudata -lm"

• ./configure：執行設定腳本。
• --prefix、--bindir、--datarootdir：指定 PostGIS 安裝位置於 ServBay 內對應 PostgreSQL 版本的目錄結構，讓 PostgreSQL 在標準搜尋路徑內找到擴充功能。${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7 是 ServBay 下 PostgreSQL 15.7 的安裝根路徑，這個路徑通常由 ServBay 編譯環境的初始化腳本自動設定。
• --with-protobufdir：指定 Protobuf 函式庫路徑，PostGIS 可能需要用到它。${SERVBAY_BIN_PATH} 為 ServBay 套件二進位路徑。
• --disable-nls：停用國際語言支援，開發環境通常不需要。
• --without-raster、--without-topology：停用 PostGIS 的 Raster 與 Topology 支援，以簡化編譯。如有需求可選擇啟用，可能需要額外依賴。
• --with-pgconfig：最重要選項，指定目標 PostgreSQL 版本的 pg_config 工具位置。pg_config 提供 PostgreSQL 標頭與函式庫資訊給 PostGIS 設定腳本，確保相容。
• CFLAGS、CXXFLAGS、LDFLAGS：這些為標準環境變數，向 C/C++ 編譯器與連結器傳遞參數。${CFLAGS}、${CXXFLAGS}、${LDFLAGS} 繼承自 ServBay 編譯環境。
  • -I${SERVBAY_COMMON_INCLUDE_PATH}/libxml2 -I${SERVBAY_COMMON_INCLUDE_PATH}：增加 ServBay 通用包含目錄，保證能找到 libxml2 等標頭檔。${SERVBAY_COMMON_INCLUDE_PATH} 為 ServBay 提供的通用 header 路徑。
  • -L${SERVBAY_COMMON_LIB_PATH} -lxml2 -lz ...：增加 ServBay 通用函式庫路徑、連結所需標準庫（如 libxml2, zlib, pthread, iconv, icu 等）。${SERVBAY_COMMON_LIB_PATH} 為 ServBay 通用函式庫目錄。這些函式庫是 PostGIS 常見依賴，ServBay 通常已包含。
  • -std=c++17：指定 C++ 編譯器標準版本（C++17），為現代 C++ 專案常見要求。

步驟 4：編譯與安裝

設定完成後，透過 make 指令編譯源碼，並以 make install 安裝至指定的 ServBay PostgreSQL 目錄：

make -j ${CPU_NUMBER}
make install

• make -j ${CPU_NUMBER}：開始編譯；-j ${CPU_NUMBER} 會平行編譯，活用多核心 CPU（${CPU_NUMBER} 由 ServBay 環境指定），大幅提升速度。
• make install：將編譯產生的檔案（如 PostGIS 共享庫、SQL 腳本等）複製到 ServBay 下 PostgreSQL 15.7 的對應路徑（通常是 lib/postgresql 與 share/postgresql/extension 等）。

步驟 5：驗證模組載入

完成編譯與安裝後，需在 PostgreSQL 資料庫中啟用 postgis 擴充。透過 ServBay 命令列或您習慣的 PostgreSQL 客戶端連線，執行下列 SQL：

請以 ServBay 終端下 psql 工具驗證，務必確保 ServBay 編譯環境已正確載入。

# 執行 CREATE EXTENSION 指令啟用 PostGIS
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION postgis;"

若執行順利，PostGIS 擴充即已建立。你也可進一步查詢版本資訊：

# 查詢 PostGIS 版本
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT PostGIS_Version();"

如一切正常，應會看到 PostGIS 版本號，表示模組已成功編譯、安裝並在資料庫中載入。

編譯 pg_jieba 模組

pg_jieba 是基於 C++ 函式庫 cppjieba 的 PostgreSQL 擴充功能，能在資料庫中提供中文斷詞（分詞），常用於全文檢索等場景。pg_jieba 採用 CMake 作為建構系統。以下說明編譯步驟：

步驟 1：取得原始碼

首先，從 GitHub 下載 pg_jieba 原始碼倉庫。因 pg_jieba 依賴 cppjieba 作為 Git 子模組，也要同步取得子模組：

git clone https://github.com/jaiminpan/pg_jieba.git
cd pg_jieba
git submodule update --init --recursive

• git clone ...：複製 pg_jieba 倉庫至當前目錄。
• git submodule update --init --recursive：初始化並下載所有子模組。pg_jieba 以子模組方式集成 cppjieba，這一步確保 cppjieba 原始碼也同步更新到正確位置。

步驟 2：設定編譯選項（CMake）

pg_jieba 採 CMake 建構。與 Autotools 的 ./configure 類似，CMake 由 cmake 指令設定並產生目標文件（如 Unix Makefiles 或 Ninja）。你需要指明 PostgreSQL 路徑及 ServBay 的編譯目標。

cmake -S . -B builddir \
  -DCMAKE_PREFIX_PATH=${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7 \
  -DCMAKE_OSX_DEPLOYMENT_TARGET=${BUILD_OS_MIN_VERSION} \
  -DCMAKE_OSX_ARCHITECTURES=${BUILD_CPU_ARCH_CMAKE}

• cmake -S . -B builddir：執行 CMake 設定，將原始碼目錄（.）指定為來源，並在本目錄下建立 builddir 為建構目錄。分離建構目錄是 CMake 推薦做法。
• -DCMAKE_PREFIX_PATH：關鍵選項，指定 CMake 搜尋依賴及標頭檔的路徑（尤其是 PostgreSQL），這裡指向 ServBay PostgreSQL 15.7 根目錄。CMake 會偵測這個路徑下的 lib/cmake、share/cmake 等子目錄，並輔以 pg_config 提供的資訊來完成設定。
• -DCMAKE_OSX_DEPLOYMENT_TARGET：設定 macOS 最低支援版本，確保編譯的二進檔能相容特定或更高的 macOS 版本。${BUILD_OS_MIN_VERSION} 由 ServBay 編譯環境指定。
• -DCMAKE_OSX_ARCHITECTURES：指定目標 CPU 架構（如 x86_64 或 arm64），${BUILD_CPU_ARCH_CMAKE} 由 ServBay 環境指定。這些 macOS 選項確保模組可在對應系統平台運行。

步驟 3：編譯與安裝（CMake）

設定完成後，透過 cmake --build 編譯，cmake --install 完成安裝：

cmake --build builddir -j ${CPU_NUMBER}
cmake --install builddir

• cmake --build builddir：從 builddir 建構模組。
• -j ${CPU_NUMBER}：同樣支援多核心平行編譯（${CPU_NUMBER} 由 ServBay 指定）。
• cmake --install builddir：將產生的二進檔安裝至前面 -DCMAKE_PREFIX_PATH （配合 CMake 與 PostgreSQL pg_config 設定）對應的 ServBay PostgreSQL 路徑（通常是 lib/postgresql 與 share/postgresql/extension）。

步驟 4：驗證模組載入

完成編譯與安裝後，同樣需在 PostgreSQL 資料庫啟用 pg_jieba 擴充。連接資料庫後執行下列 SQL：

請以 ServBay 下的 psql 工具檢查，並確認已載入正確的 ServBay 環境變數。

# 執行 CREATE EXTENSION 指令啟用 pg_jieba
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "CREATE EXTENSION pg_jieba;"

若成功，pg_jieba 擴充即可用。你可透過查詢 pg_available_extensions 檢視模組資訊：

# 查詢已安裝的擴充功能
${SERVBAY_PACKAGE_FULL_PATH}/postgresql/15/15.7/bin/psql -c "SELECT * FROM pg_available_extensions WHERE name = 'pg_jieba';"

只要模組成功載入並列於結果，即已正確編譯、安裝與啟用。

常見問題 (FAQ)

• 編譯失敗，顯示找不到標頭檔或函式庫？
  • 請確認是否已正確初始化 ServBay 編譯環境。確保在 ServBay 終端執行過初始化腳本，且相關環境變數（如 $CFLAGS, $LDFLAGS, ${SERVBAY_COMMON_INCLUDE_PATH}, ${SERVBAY_COMMON_LIB_PATH} 等）都已設妥指向 ServBay 目錄。
  • 確認設定指令裡的 --with-pgconfig（Autotools）或 -DCMAKE_PREFIX_PATH（CMake）路徑是否正確，且路徑下的 pg_config 存在且可執行。
  • 有些模組可能需要 ServBay 通用函式庫以外的系統依賴（如 PostGIS 啟用 Raster/Topology 功能時需 GEOS、GDAL 等）。ServBay 編譯環境已囊括多數常用函式庫，如缺特定相依，請手動安裝或關閉相依功能。
• CREATE EXTENSION 失敗，顯示無法找到模組檔案？
  • 請確定 make install（Autotools）或 cmake --install（CMake）執行順利且無錯誤。檢查安裝紀錄，確認檔案已正確複製至目標目錄。
  • 檢查 --prefix（Autotools）或 -DCMAKE_PREFIX_PATH（CMake）在設定階段是否正確指定至目標 PostgreSQL 版本目錄。模組檔應會被安裝在該路徑下的 lib/postgresql 子目錄。
  • 嘗試重新啟動 PostgreSQL 服務。有些狀況下必須重啟資料庫，才會辨識新安裝的模組。可於 ServBay 應用內快速操作。
  • 檢查 PostgreSQL 的 shared_preload_libraries 設定。大多數一般擴充功能（CREATE EXTENSION 方式載入）不需修改此設定；某些特殊模組（需注入 PostgreSQL 核心）則必須於這裡加入模組名稱並於啟動時載入。請參考目標模組官方說明。
• 如何為不同版本 PostgreSQL 編譯模組？
  • 重複上述步驟，但在設定時（./configure 或 cmake）務必將 --with-pgconfig（Autotools）或 -DCMAKE_PREFIX_PATH（CMake）參數指向目標 PostgreSQL 版本專屬的 pg_config。例如，為 ServBay 下 PostgreSQL 14 編譯則需修改為 ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/14/14.x/bin/pg_config 或 ${SERVBAY_PACKAGE_FULL_PATH}/postgresql/14/14.x（其中 14.x 是 ServBay 內實際安裝的 14 版號）。

總結

依照上述步驟，善用 ServBay 的編譯環境和工具，你可以於 ServBay 本地開發環境順利編譯並安裝所需的 PostgreSQL 擴充功能，用來提升資料庫能力，滿足各種開發需求。全程正確初始化 ServBay 編譯環境、指定對應 PostgreSQL 版本並細心檢查設定與安裝路徑，是確保成功的關鍵。

希望本文能協助你在 ServBay 平台上順利定制 PostgreSQL 環境。如遇進階問題，建議參閱 ServBay 其他官方文檔或社群資源。