OpenSEO 自託管教程：Docker 部署、DataForSEO 與 MCP 接入

OpenSEO 是一個面向個人和團隊的開源 SEO 工具，定位為 Semrush、Ahrefs 等商業套件的輕量替代方案。它提供關鍵詞研究、排名跟蹤、競品分析、反向連結、站點審計和 AI Visibility，並透過 MCP 把 SEO 資料交給 Codex、Claude Code 等 AI Agent 使用。

OpenSEO 可以使用官方託管版，也可以自行部署。自託管能控制應用和專案資料，但不等於所有 SEO 資料免費：關鍵詞、SERP、反向連結等資料來自 DataForSEO，仍需要自己的 API 憑據並按呼叫付費。

快速答案

個人電腦上體驗 OpenSEO，推薦使用 Docker：

1
2
3


git clone https://github.com/every-app/open-seo.git
cd open-seo
cp .env.example .env

在 .env 中設定：

1

DATAFORSEO_API_KEY=YOUR_BASE64_CREDENTIALS

啟動服務：

1

docker compose up -d

預設訪問地址是：

1

http://localhost:3001

重要提醒：Docker 自託管模式預設使用 AUTH_MODE=local_noauth，沒有應用級登入檢查。它適合本機或可信私網，不能直接把埠暴露到公網。遠端訪問必須放在帶認證的反向代理、隧道或私有網路之後。

OpenSEO 能做什麼

OpenSEO 把常用 SEO 工作拆成較聚焦的流程：

工作流	可解決的問題
Keyword Research	查詢搜尋量、難度、CPC、意圖和趨勢
Rank Tracking	儲存關鍵詞並跟蹤最新排名
Competitor Insights	查詢競品自然關鍵詞、頁面與流量線索
Backlinks	檢視反向連結和引用域概況
Site Audits	檢查站點技術問題和頁面狀態
AI Visibility	觀察品牌或頁面在 AI 搜尋場景中的可見度

MCP 還可以讀取 Google Search Console 的點選、展示、CTR 和平均排名，並檢查指定 URL 的索引、抓取和 canonical 狀態。實際能呼叫哪些資料取決於當前版本、連線的資料來源和賬戶許可權。

自託管之前要理解成本

OpenSEO 本身採用 MIT License，但它依賴第三方 DataForSEO 獲取 SEO 資料。自託管時，呼叫費用由使用者直接支付給 DataForSEO。

官方文件說明，DataForSEO 新賬戶可獲得少量測試額度，並設有最低充值金額；這些價格政策可能變化，註冊前應檢視 DataForSEO 當前計費頁面。不要把生產 API 憑據提交到 Git，也不要把完整 Base64 字串貼進日誌、工單或聊天記錄。

DataForSEO 提供的憑據是賬號郵箱與 API 密碼組合後的 Base64 值，格式來源是：

1

email:password

Base64 只是編碼，不是加密。拿到 DATAFORSEO_API_KEY 的人可能消耗賬戶餘額或訪問允許的資料，因此應把它當作密碼管理。

使用 Docker 自託管

1. 克隆專案

1
2


git clone https://github.com/every-app/open-seo.git
cd open-seo

2. 建立環境變數檔案

1

cp .env.example .env

編輯 .env，至少加入 DataForSEO 憑據：

1

DATAFORSEO_API_KEY=YOUR_BASE64_CREDENTIALS

可選配置包括：

1
2
3


PORT=3001
ALLOWED_HOST=seo.example.com
OPENSEO_TELEMETRY_DISABLED=1

PORT 預設是 3001。ALLOWED_HOST 用於允許一個反向代理主機名。若不希望傳送匿名遙測，可設定 OPENSEO_TELEMETRY_DISABLED=1，也可以使用 DO_NOT_TRACK=1。

3. 啟動並檢查

1
2
3


docker compose up -d
docker compose ps
docker compose logs -f open-seo

確認 Compose 實際讀取的配置：

1

docker compose config

這裡的輸出可能包含敏感環境變數，不要直接複製到公開問題或 CI 日誌。檢查完成後，開啟 http://localhost:3001。

4. 修改配置後重建容器

修改 .env 後執行：

1

docker compose up -d --force-recreate open-seo

僅執行普通重啟不一定會重新應用所有環境變數，強制重建更容易排除舊配置殘留。

Docker 模式為什麼不能直接暴露公網

官方 Compose 使用 AUTH_MODE=local_noauth，本地管理員為 admin@localhost，不會執行正常的身份認證。如果直接把 3001 埠對映到公網，任何能訪問地址的人都可能進入應用並使用已配置的 DataForSEO 憑據。

安全的遠端訪問方案至少應滿足一項：

只允許透過 WireGuard、Tailscale 等私有網路訪問；
放在具有強認證的反向代理後；
使用帶身份驗證和訪問策略的安全隧道；
改用官方提供的 Cloudflare 自託管方案。

配置反向代理域名時，在 .env 中設定：

1

ALLOWED_HOST=seo.example.com

然後重建服務：

1

docker compose up -d --force-recreate open-seo

僅配置 ALLOWED_HOST 不能代替認證，它只是主機名限制的一部分。

更新、固定版本與回滾

拉取最新映象並重啟：

1
2


docker compose pull
docker compose up -d

生產環境不建議長期使用浮動的 latest。可以在 .env 中固定經過驗證的映象標籤：

1

OPEN_SEO_IMAGE=ghcr.io/every-app/open-seo:v1.2.3

示例標籤僅用於展示配置格式，實際應從官方 Releases 選擇存在且已驗證的版本。更新前備份持久資料並記錄舊標籤；發生問題時恢復舊映象和相容的資料版本。

停止容器：

1

docker compose down

下面的命令會連卷一起刪除，不要在沒有備份時執行：

1

docker compose down -v

關閉匿名遙測

官方文件說明，OpenSEO 會用隨機安裝 ID 傳送核心使用事件和聚合數量。文件宣告不收集 URL、關鍵詞、Prompt、郵箱或基於 IP 推斷的位置，空閒例項不會傳送資料。

如需關閉，在 .env 中設定：

1

OPENSEO_TELEMETRY_DISABLED=1

然後重建容器：

1

docker compose up -d --force-recreate open-seo

對合規要求嚴格的環境，仍應自行檢查當前版本程式碼、網路出口和隱私說明，而不是隻依賴摘要描述。

使用 Cloudflare 自託管

需要跨裝置或團隊從公網訪問時，OpenSEO 還提供 Cloudflare 部署路徑，可使用 Cloudflare 免費計劃。官方流程大致為：

透過倉庫提供的 Deploy to Cloudflare 入口建立 Worker；
連線 GitHub 或 GitLab；
在 Worker 的 Domains & Routes 中啟用 Cloudflare Access；
在 Variables & Secrets 中新增認證和 DataForSEO 配置；
開啟 Worker URL，驗證登入與 OpenSEO 頁面。

需要配置的 Secret 包括：

1
2
3


POLICY_AUD
TEAM_DOMAIN
DATAFORSEO_API_KEY

POLICY_AUD 和 TEAM_DOMAIN 來自 Cloudflare Access 設定。不要把它們寫入倉庫的普通變數檔案。

DataForSEO 響應會快取在 R2 的 dataforseo-cache/ 字首下。官方建議設定生命週期規則，自動清理過期快取：

1

npx wrangler r2 bucket lifecycle add open-seo dataforseo-cache-expiry dataforseo-cache/ --expire-days 7

如果部署時改過 R2 Bucket 名稱，需要把命令中的 open-seo 換成實際名稱。未配置生命週期規則時，快取物件會持續積累並增加儲存成本。

把 OpenSEO MCP 接入 Claude Code

官方託管 MCP 地址是：

1

https://app.openseo.so/mcp

在 Claude Code 中新增使用者級 MCP：

1

claude mcp add --transport http --scope user openseo https://app.openseo.so/mcp

首次連線會進入 OpenSEO 登入和授權流程。若只希望當前倉庫使用，可以根據 Claude Code 當前版本改用本地 scope。

把 OpenSEO MCP 接入 Codex

Codex CLI 使用：

1

codex mcp add openseo --url https://app.openseo.so/mcp

隨後按提示完成登入授權。Codex Desktop 使用者可以進入 Settings、Integrations & MCP，選擇新增自定義服務，再貼上同一個 URL。

連線成功後，先讓 Agent 列出 OpenSEO 專案並取得專案 ID，再執行關鍵詞研究或排名分析。不要一開始只說“幫我做 SEO”，更有效的請求應包含網站、市場、語言、目標和輸出範圍。

例如：

1
2
3


列出我的 OpenSEO 项目，选择 example.com。
找出近 28 天展示量高、CTR 低且平均排名 4-15 的查询，
只返回对应页面、查询词和一个优先级理由，不要直接修改页面。

MCP 與 Agent Skills 的區別

MCP 給 Agent 提供查詢和寫入 OpenSEO 資料的工具；Agent Skills 則規定如何組合這些工具完成一項工作。前者解決“能訪問什麼”，後者解決“按什麼流程做”。

官方列出的 MCP 能力包括：

查詢關鍵詞搜尋量、難度、CPC 和意圖；
獲取實時 Google 自然搜尋結果；
分析域名或頁面的排名關鍵詞；
比較關鍵詞集合中的 SERP 競爭者；
查詢反向連結和引用域概況；
讀取 Search Console 表現與 URL 索引狀態。

為 AI Agent 授權時，應限制賬戶與專案範圍。讓 Agent 寫入儲存關鍵詞或更改專案資料之前，先用只讀查詢驗證所選專案是否正確。

常見問題

頁面能開啟，但查詢 SEO 資料失敗

先檢查 DATAFORSEO_API_KEY 是否為 DataForSEO 提供的完整 Base64 憑據、賬戶是否有餘額，再用以下命令確認 Compose 已讀取環境變數：

1

docker compose config

不要在排障截圖中暴露憑據。修改 .env 後強制重建 open-seo 容器。

反向代理後提示主機不允許

在 .env 中把 ALLOWED_HOST 設定為實際公開主機名，不要包含路徑，然後重建容器。與此同時必須在代理層配置身份認證。

MCP 無法連線

確認地址完全是：

1

https://app.openseo.so/mcp

授權失敗時，先從客戶端移除 OpenSEO MCP，再重新新增並完成登入。Agent 找不到專案時，先呼叫專案列表並在後續請求中使用返回的專案 ID。

自託管是否完全免費？

應用程式碼可以自行執行，但 SEO 資料由 DataForSEO 提供，需要按其價格付費。Cloudflare、伺服器、域名、備份和網路也可能產生額外成本。

OpenSEO 適合哪些使用者

OpenSEO 適合希望按使用量購買 SEO 資料、需要關鍵詞與排名等集中工作流，或想讓 AI Agent 直接使用 SEO 資料的個人站長和小團隊。Docker 模式適合本機體驗，Cloudflare 方案更適合多裝置和團隊訪問。

如果需要龐大的歷史資料庫、成熟的企業許可權、完整審計和大量現成報告，應先用真實專案比較 OpenSEO 與商業平臺的資料覆蓋、更新頻率和總成本，不要只根據“開源替代”這一定位直接遷移。

總結

OpenSEO 把關鍵詞研究、排名、競品、連結、站點審計和 Search Console 資料放到一個開源介面中，並透過 MCP 供 Codex、Claude 等 Agent 呼叫。個人體驗可從 Docker 開始，但必須記住本地模式沒有應用認證；團隊或公網部署應使用 Cloudflare Access 或自建的強認證邊界。自託管能控制應用和流程，DataForSEO 呼叫費用仍需單獨承擔。

專案地址：every-app/open-seo

官方文件：openseo.so/docs