OpenSEO v0.0.9 深度解析:域关键词服务端分页过滤、一键导出 Google Sheets 与 URL 驱动的可分享搜索状态

原创2026-09-13 13:31:071,359 阅读
文章标签:后端前端MCP 服务AI 应用人工智能数据分析

OpenSEO v0.0.9 深度解析:域关键词服务端分页过滤、一键导出 Google Sheets 与 URL 驱动的可分享搜索状态

本篇文章围绕 OpenSEO(开源版 Semrush / Ahrefs 替代方案)v0.0.9 版本的发布内容展开,逐项拆解「域关键词服务端分页与过滤」「任意数据表导出 Google Sheets」「URL 驱动的搜索状态持久化」三个核心功能在源码中的落地方式,并说明自托管排障文档的改进。读完本文,你将掌握该版本 URL 参数体系、服务端分页请求链路、剪贴板导出机制的确切实现与调用路径,可直接在自己的部署环境中复现与验证。

版本概览:v0.0.9 改了什么

release-notes/v0.0.9.md 对本版本的定位是 "improves domain research + some UX improvements",共包含三处新增与一处改进:

  • 新增:域关键词(domain keywords)的服务端分页与过滤,可检索该域名下的全部关键词,而不再受限于单次拉取;
  • 新增:从每一个数据表格导出到 Google Sheets;
  • 新增:URL 驱动的搜索状态——搜索条件可分享、刷新后不丢失;
  • 改进:澄清了自托管排障文档。

按照 release-notes/README.md 的约定,发布说明以版本号命名的 Markdown 文件存放在 release-notes/ 目录,通常流程是先运行 pnpm -s release:notes 生成草稿,再整理为版本化文件,最终通过 gh release create <tag> --notes-file release-notes/<tag>.md 发布。v0.0.9 即遵循了这一规范。

下文逐项结合源码说明每一项功能的实现原理。

域关键词服务端分页与过滤:突破单页限制

背景:为什么需要服务端分页

在 v0.0.9 之前,域关键词表受数据源单次返回条数的约束,用户只能看到有限的样本。本次改动的核心目标是把「分页、排序、过滤」全部下沉到服务端,让用户能够遍历该域名下排名的全部关键词。

这一功能涉及三层代码:URL 参数解析(客户端路由层)、请求参数校验(服务端函数层)、数据拉取与缓存(服务端业务层)。

第一层:URL 参数即查询条件(客户端路由状态)

域分析页面的所有状态都由 URL 查询参数驱动。参数 schema 定义在 src/types/schemas/domain.ts 的 domainSearchSchema 中,客户端通过 domainRouteState.ts 中的 getDomainRouteState 将查询参数解析为完整的路由状态(含 domain、scope、sort、order、tab、page、pageSize、各类过滤条件等)。

核心 URL 参数如下表:

参数 类型 说明
domain string 目标域名(可带协议,会被规范化为裸主机名)
scope string 研究范围:domain / subdomains / 路径范围
subdomains boolean 旧版遗留参数,编码「是否包含子域」,无 scope 时用于推断范围
sort enum 排序字段:rank / traffic / volume / score / cpc
order enum 排序方向:asc / desc
tab enum 当前标签页:keywords / pages
loc number 地理位置代码(域名分析由 Labs 数据源支撑,仅接受 Labs 位置码)
page number 页码,从 1 开始
size number 每页条数,仅允许 50 / 100 / 200(见 DOMAIN_KEYWORDS_PAGE_SIZES)
include / exclude string 关键词包含/排除文本
minTraffic ~ maxRank number 流量、搜索量、CPC、难度、排名的区间过滤
pInclude ~ pMaxVol string/number Pages 标签页对应的过滤参数(带 p 前缀,避免与关键词过滤冲突)

需要注意 domainRouteState.ts 中的两处防御逻辑:

  • 位置码校验:isLabsLocationCode(search.loc) ? search.loc : defaultLocationCode——无效的 loc 会回落到项目市场对应的默认位置,而不是把非法值传给上游;
  • 页面校验:page 仅在 > 0 时生效,否则回落为 1;size 若不在白名单内则回落到 DEFAULT_DOMAIN_KEYWORDS_PAGE_SIZE(100)。

第二层:服务端函数与请求校验

分页数据通过 TanStack Server Function getDomainKeywordsPage 拉取,定义于 src/serverFunctions/domain.ts。它挂载了 requireProjectContext 中间件(保证只有项目成员可访问),并用 domainKeywordsPageRequestSchema 做输入校验,然后委派给 DomainService.getKeywordsPage。

请求 schema(见 src/types/schemas/domain.ts)包含:

  • page:正整数,默认 1;
  • pageSize:仅允许 50 / 100 / 200,默认 100;
  • sortMode:rank / traffic / volume / score / cpc,默认 traffic;
  • sortOrder:asc / desc,默认 desc;
  • filters:include / exclude 及流量、搜索量、CPC、难度、排名的 min/max 区间;
  • search:可选的关键词文本搜索。

第三层:服务端数据拉取、映射与缓存

真正实现分页逻辑的是 domainKeywordsPage.ts 中的 getKeywordsPage,调用链非常清晰:

  1. parseResearchTargetOrThrow 解析目标(域名/子域/路径范围),buildRankedKeywordsScopeFilter 构建范围过滤;
  2. 计算 offset:offset = (page - 1) * pageSize,这是服务端分页的核心换算;
  3. buildOrderBy(sortMode, sortOrder) 与 buildKeywordFilters(filters, search, scopeFilter) 分别生成 DataForSEO 的排序与过滤条件;
  4. 以 limit: pageSize, offset 调用 dataforseo.domain.rankedKeywords(客户端封装见 src/server/lib/dataforseo);
  5. 通过 mapKeywordItem 将上游返回项映射为统一的关键词行(keyword、position、searchVolume、traffic、cpc、url、keywordDifficulty 等);
  6. 用 computeHasMore(offset, items.length, totalCount, pageSize) 判断是否还有下一页;
  7. 写入 R2 缓存:缓存键由组织、项目、域名、范围、路径、位置码、语言、页码、页大小、排序、过滤与搜索条件共同组成,TTL 为 12 小时(DOMAIN_KEYWORDS_PAGE_TTL_SECONDS)。

值得留意的是缓存写入使用了 waitUntil(setCached(...)) 而非 void,源码注释明确解释了原因:workerd 在响应发送后会取消未注册的挂起 I/O,直接 fire-and-forget 会导致缓存永远写不进去。这是 Cloudflare Workers 环境下一个相当实用的实现细节。

此外,schema 中还有 MAX_DATAFORSEO_FILTER_CONDITIONS = 8 这一常量,对应 DataForSEO 单次过滤条件的数量上限,过滤条件的组合受此约束。

前端分页组件

页面端使用 DomainKeywordsPagination.tsx 渲染分页控件:展示当前范围(如 "1–100")、每页条数选择(50/100/200)、上一页/下一页按钮,并通过 totalCount 计算总页数;当服务端只返回 hasMore 而未返回总数时,也会退化为基于 hasMore 的翻页判断。页码变化会被写回 URL(page === 1 时省略该参数,保持 URL 干净)。

任意数据表一键导出 Google Sheets

v0.0.9 的另一项新增是「从每个数据表格导出到 Google Sheets」。其实现并不是走 OAuth 写入 Google 表格,而是采用**「复制到剪贴板 + 引导粘贴」**的轻量方案,实现位于 exportToSheets.ts 与 clipboard.ts。

导出流程

exportTableToSheets({ headers, rows, feature }) 的流程如下:

  1. 若 rows 为空,直接 toast.error("No data to export"),避免导出空表;
  2. 调用 copyTableToClipboard 写入剪贴板;
  3. 上报 PostHog 事件 data:export_sheets,携带 source_feature 与 result_count,便于统计各模块导出使用情况;
  4. 弹出提示框(useExportToSheetsModalState 管理的全局模态),用户点击后才打开 https://sheets.new(GOOGLE_SHEETS_NEW_URL)——不自动跳转,因为用户需要先意识到数据已在剪贴板中。

剪贴板双格式写入

copyTableToClipboard 通过 navigator.clipboard.write 一次性写入两种 MIME 类型:

  • text/plain:TSV(制表符分隔),便于 Google Sheets 直接粘贴解析成列;单元格中的 \t\r\n 会被替换为空格以防破坏列结构;
  • text/html:一个带 <table> 结构的 HTML 表格,URL 类型的单元格会被转成可点击的 <a> 链接,粘贴到富文本场景时可保留格式与链接。

代码中对 Safari < 17.4 做了兼容:ClipboardItem 的 Blob 值用 Promise.resolve 包裹——旧版 Safari 要求 Promise<Blob>,现代浏览器两者皆可。HTML 与 TSV 中的单元格内容均经过 HTML 转义(escapeHtml),避免粘贴时注入 HTML。

哪些表格接入了导出

搜索源码可见该工具已被广泛接入(各模块统一调用 exportTableToSheets):

由于接入点统一收敛在 exportTableToSheets,后续若需要更换导出策略(如改为直连 Sheets API 写入),只需改动这一个函数。

URL 驱动的搜索状态:可分享、可刷新

「URL 驱动的搜索状态」意味着搜索表单中的每个条件都有对应的 URL 查询参数,页面刷新或把链接发给他人后,界面能完整还原搜索现场。

关键词研究模块的参数体系

关键词研究模块的参数定义与归一化在 keywordSearchParams.ts:

参数 含义
q 搜索关键词(种子词,可多个)
loc 地理位置代码
kLimit 结果条数:150 / 300 / 500
mode 研究模式:auto / related / suggestions / ideas
cs 是否使用 clickstream 数据
sort / order 排序字段与方向
minVol ~ maxKd 搜索量、CPC、难度的区间过滤
include / exclude 包含/排除词

旧参数归一化:保持分享链接向后兼容

normalizeLegacyKeywordSearch 会把旧版 URL 中冗余的「默认值参数」从 URL 中剥离,例如 kLimit=150、mode=auto、sort=searchVolume、order=desc 都会在归一化后置为 undefined——因为这些本就是默认值,保留只会让 URL 变长且不可读。同时,域名分析模块在 domainRouteState.ts 中也对旧版 subdomains 布尔参数做了兼容映射:无 scope 参数时,依据 subdomains 推断研究范围,保证老链接打开后语义不变。

与本地搜索历史的边界

需要区分的是:useDomainSearchHistory.ts 维护的是本地历史记录(按项目 ID 隔离、上限 20 条、存于 localStorage 并做 Zod 校验与版本迁移),它负责「最近搜索过的域名」列表;而 URL 参数负责的是当前搜索现场的持久化。两者职责不同、相互独立。

改进:自托管排障文档澄清

v0.0.9 的改进项是澄清自托管相关排障文档。仓库 docs/ 目录下沉淀了完整的自托管文档集,包括:

配套的部署资产位于仓库根目录:compose.yaml、Dockerfile.selfhost、docker-entrypoint.sh,以及部署前检查脚本 selfhost-preflight.ts(含测试 selfhost-preflight.test.ts)和 selfhost-deploy-preflight.mjs。若你正计划自托管,建议按 Cloudflare 或 Docker 对应的主文档逐步配置,遇到问题时可对照本仓库中的部署脚本逐项排查环境变量与数据库连接。

小结与验证建议

v0.0.9 的三个新增项共同指向同一个目标:让域研究与关键词研究在大数据量下依然可用、可导出、可分享。你可以按以下方式在本地验证本版本能力:

  1. 分页:打开域分析页面,切换每页条数(50/100/200)并翻页,观察 URL 中 page、size 参数的变化,以及服务端请求体中的 page/pageSize/sortMode/sortOrder/filters 字段;
  2. 导出:在任一数据表点击导出,粘贴到 Google Sheets,确认列结构与链接是否完整;
  3. 分享状态:调整过滤条件后复制 URL 在新标签页打开,确认排序、分页、过滤条件完全还原。

依赖本版本核心能力的关键文件路径汇总:请求与 URL 参数 schema、路由状态解析、服务端分页实现、导出工具 与 剪贴板实现。

登录后查看全文
open-seo