OpenSerp

概述

OpenSerp 係一款開源、可自託管嘅搜尋結果 API，主要用途係取代付費嘅 SerpAPI。傳統上，開發者要整合 Google、Bing 等搜尋引擎結果，通常要使用第三方 SaaS API，但呢啲服務有查詢額度限制、成本偏高，而且會將查詢記錄交畀外部供應商。

OpenSerp 將「向搜尋引擎發送查詢、接收回應、解析成結構化 JSON」嘅過程包裝成一個 Docker 服務。部署咗之後，內部系統就可以好似呼叫一般 REST API 咁取得搜尋結果，適合 SEO 監察、市場分析、學術研究，以致大型語言模型（LLM）嘅 Retrieval-Augmented Generation 工作流。

架構

呢個部署採用單一容器架構，鏡像為 karust/openserp:latest，容器名稱係 openserp。容器啟動時直接執行：

serve -a 0.0.0.0 -p 7000

因此 API 服務會監聽容器內嘅 7000 埠，而環境變數 OPENSERP_SERVER_HOST 同 OPENSERP_SERVER_PORT 亦明確指定相同數值，避免設定不一致。

OpenSerp 使用 Docker volume openserp_data 掛載到 /usr/src/app/data，用作持久化資料儲存。實際內容會因版本而異，通常包括快取、任務佇列或設定檔。由於有獨立 volume，容器升級或者重建後資料仍會保留。

網絡方面，OpenSerp 接入外部 Docker network cf_network，並使用固定 IPv4 位址 172.21.0.20。cf_network 喺 compose 檔案內標記為 external: true，即係話網絡由其他部署或系統管理員預先建立，OpenSerp 本身唔會嘗試建立新網絡。呢個做法令 OpenSerp 可以同 Cloudflare Tunnel、API Gateway、LiteLLM 等其他容器直接以內部網絡溝通，而唔需要將埠暴露到宿主機。

部署

喺 wiki.benhoweb.com 嘅 Docker 主機上，只要將包含上述 OpenSerp service 嘅 compose 檔案放置好，然後執行：

docker compose up -d openserp

若 cf_network 尚未存在，就需要先建立：

docker network create cf_network

值得注意，呢個 compose 片段冇 ports: 對應，所以宿主機唔會直接開啟 7000 埠。對外存取通常會由另一個喺 cf_network 內嘅 Cloudflare Tunnel 容器負責，將外部 HTTPS 請求轉發到 http://172.21.0.20:7000，或者直接使用 Docker DNS 名稱 http://openserp:7000。

配置

主要設定可以分為三層：

• 時區：TZ: Asia/Hong_Kong 令容器內日誌同排程使用香港時間。
• 伺服器監聽：OPENSERP_SERVER_HOST=0.0.0.0 表示接受容器內所有網絡介面嘅連線；OPENSERP_SERVER_PORT=7000 定義 API 埠。
• 指令參數：command 中嘅 -a 0.0.0.0 同 -p "7000" 同環境變數互相呼應。

如果日後要改埠，必須同時更改環境變數同 command，否則 OpenSerp 可能出現設定衝突。由於 compose 內未見 API key 或認證環境變數，建議唔好直接將呢個服務公開到互聯網，而應該放喺 Cloudflare Tunnel 或 API Gateway 後面，加上額外驗證。

維運與監控

Compose 定義咗健康檢查：

wget --quiet --tries=1 --spider http://127.0.0.1:7000/health

Docker 每 30 秒執行一次，timeout 係 10 秒，連續失敗 5 次就會將容器標記為 unhealthy。日常維運可以執行：

docker compose logs -f openserp

檢查有冇異常請求或者上游搜尋引擎嘅錯誤。若需要手動確認服務健康狀態：

docker exec openserp wget --quiet --tries=1 --spider http://127.0.0.1:7000/health

另外，因為 openserp_data 可能儲存咗有價值嘅快取資料，備份時可以用：

docker run --rm -v openserp_data:/data -v $(pwd):/backup alpine tar czf /backup/openserp_data.tgz -C /data .

常見問題

點解 Healthcheck 用 wget？
因為 karust/openserp 鏡像內建咗 wget，用 --spider 模式只檢查 URL 是否可達，唔會下載成個回應。

點樣從另一個容器呼叫 OpenSerp？
只要對方容器都連接 cf_network，就可以用 http://openserp:7000 或 http://172.21.0.20:7000 訪問。

點樣升級 OpenSerp？
執行：

docker compose pull openserp
docker compose up -d openserp

升級前最好先備份 volume。

搜尋引擎會封鎖 OpenSerp 嗎？
OpenSerp 本身只係 API 包裝器，實際請求仍然會受到目標搜尋引擎嘅使用條款同反爬蟲機制限制。生產環境應該控制查詢頻率，並考慮使用代理伺服器或輪換 IP。

相關鏈接

docker、SerpAPI、cloudflare-tunnel、litellm、API Gateway、SEO

來源

自動生成（2026-08-19 容器覆蓋率補完第二批）