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