OpenSEO v0.1.0 发布解读：项目 Dashboard、自托管匿名遥测与 Prompt Explorer 引用来源修复-育师

OpenSEO v0.1.0 发布解读：项目 Dashboard、自托管匿名遥测与 Prompt Explorer 引用来源修复

【免费下载链接】open-seoOpen source alternative to Semrush and Ahrefs项目地址: https://gitcode.com/GitHub_Trending/op/open-seo

本文基于仓库 release-notes/v0.1.0.md 编写，系统梳理 OpenSEO 从 v0.0.28 升级到 v0.1.0 的关键变更：全新项目 Dashboard、自托管环境下的匿名使用遥测机制，以及一批社区贡献的 Bug 修复。读者通过本文可以了解 Dashboard 的卡片构成与数据刷新逻辑、遥测开关的完整语义（含OPENSEO_TELEMETRY_DISABLED与DO_NOT_TRACK的边界行为）、以及 Prompt Explorer 引用来源在前后端的实现链路。

版本概览

v0.1.0 是 OpenSEO 从 0.0.x 阶段迈入 0.1.x 的重要里程碑，主题可概括为三件事：

新增项目 Dashboard：将 Search Console、站点审计（site audit）与外链（backlink）数据汇总到统一面板；
新增自托管匿名遥测：向自托管实例提供默认开启、可一键关闭的匿名使用数据上报；
修复一批影响日常使用的缺陷：包括 Domain Overview 筛选器冻结、搜索标签页切换、Prompt Explorer 引用来源丢失以及 SAM 对话在未配置自定义模型时的异常。

其中大部分修复来自外部贡献者（@bookingseo 等），体现了项目的社区协作节奏。发布说明的完整比对范围对应v0.0.28...v0.1.0，仓库中另有完整的 release-notes 目录记录每个版本。

新功能一：项目 Dashboard 汇总 Search Console、站点审计与外链数据

面板的数据来源与卡片编排

v0.1.0 引入的项目 Dashboard 位于 DashboardPage.tsx，其数据获取依赖两个 TanStack Query 查询：

getDashboardActivation：返回项目的激活状态（是否已配置域名、GSC 是否连接、GA4 是否连接等），驱动 onboarding 引导与卡片显隐；
getDashboardOverview：返回审计健康度、外链快照等聚合数据。

两个查询的 Server Function 定义在 dashboard.ts，均通过requireProjectContext中间件校验项目上下文后，再委托给服务端的DashboardService执行。

面板按数据是否就绪对卡片排序渲染（有数据的卡片优先展示，空状态与引导卡片排在后面）。卡片集合是条件组合的：

GscCard：仅在 GSC 已连接时渲染；
Ga4Card：已连接或尚未被用户主动关闭时渲染；
AuditHealthCard：始终渲染，展示最近一次站点审计的健康评分；
BacklinkPulseCard：仅在项目配置了域名时渲染。

卡片实现分散在 DashboardCards.tsx 与 Ga4Card.tsx 中，统一由DashboardOnboarding组件负责配置引导清单。

访问触发的外链快照刷新

值得注意的一个细节是「访问即刷新」机制：当overview报告外链快照缺失或过期、且项目已绑定域名时，客户端会通过useRef保证每次页面访问只触发一次refreshDashboardBacklinkSnapshot调用（见 DashboardPage.tsx）。对应服务端函数ensureBacklinkSnapshot在 dashboard.ts 中再次做新鲜度校验，并按照组织额度（credits）计费，同一项目每天最多触发一次——客户端即使重复触发，服务端也会兜底拦截。

新功能二：自托管匿名遥测与退出机制

遥测收集什么、不收集什么

v0.1.0 为自托管实例引入了匿名遥测。根据部署文档 SELF_HOSTING_DOCKER.md 与 SELF_HOSTING_CLOUDFLARE_OPERATIONS.md 的描述，其数据边界为：

以随机生成的安装 ID（install ID）关联的心跳事件（heartbeat），附带聚合计数（安装数、用户数、项目数、功能使用情况）；
安装后前两小时每 5 分钟发送一次，此后每天最多一次；
遥测只包含失败的安装检查项名称与状态（如dataforseo:error），绝不包含错误详情值或错误消息；
不收集 URL、关键词、提示词、邮箱或基于 IP 的地理位置；空闲实例不会发送任何数据。

该实现位于 self-host-telemetry.ts，其中SELF_HOST_POSTHOG_KEY与SELF_HOST_POSTHOG_HOST是自托管专用的 PostHog 采集端点常量，与托管（hosted）模式的数据通道完全隔离。

退出开关的完整语义

发布说明给出的两个环境变量是：

OPENSEO_TELEMETRY_DISABLED=1 DO_NOT_TRACK=1

其底层语义定义在 selfhost-checks.ts 的isTelemetryOptOutValue中，规则值得特别注意：除显式的 "off" 字符串之外，任何值都会关闭遥测（隐私优先 fail-toward-privacy），但 "0" / "false" / "no" / "off" 表示操作者明确要求保持开启。

也就是说：

设置值	遥测状态
`OPENSEO_TELEMETRY_DISABLED=1`	关闭
`DO_NOT_TRACK=1`	关闭
`OPENSEO_TELEMETRY_DISABLED=0`	保持开启（显式撤销）
`DO_NOT_TRACK=false`	保持开启（显式撤销）

该行为在测试 self-host-telemetry.test.ts 中有明确覆盖：设置"0"或"false"时仍会正常发送心跳。此外遥测还存在两道前置闸门：

托管模式不采集：AUTH_MODE=hosted时直接跳过（测试见 self-host-telemetry.test.ts）；
仅生产构建上报：import.meta.env.MODE !== "production"时跳过，从而排除vite dev、vitest 以及按 PR 构建的 preview 部署——否则每个预览环境数据库都会被误登记为一个新的自托管安装（见 self-host-telemetry.ts）。

心跳节奏：从 5 分钟到每日

心跳节奏按安装时长分两档（常量定义在 self-host-telemetry.ts，逻辑在getHeartbeatIntervalMs/getCheckIntervalMs）：

安装后2 小时内（onboarding 窗口）：每5 分钟发送一次心跳，用于捕捉「安装后前几天」的上手进度快照；
2 小时之后：每天最多一次。

内存侧还有一层 DB 检查节流：onboarding 期间每 60 秒检查一次（必须能整除 5 分钟心跳间隔，避免别名效应拉长实际节奏），进入稳态后每 15 分钟检查一次。这些边界在测试 self-host-telemetry.test.ts 中被逐项验证，包括「24 小时内不重复发送」「超过 24 小时才发送」等。

并发与数据完整性设计

遥测实现里有两个值得自托管运维者了解的工程细节：

心跳认领（CAS）：通过telemetryState表（固定id = TELEMETRY_STATE_ID）以条件更新方式实现「单实例认领」，保证多个并发 isolate 同时启动时只有一次心跳被发送（测试见 self-host-telemetry.test.ts）；
MCP 工具调用计数：incrementSelfHostMcpToolCallCount以幂等累加方式记录 MCP 工具调用次数，并在markHeartbeatSent中仅扣减本次事件已上报的数量，避免并发写入导致计数丢失（见 self-host-telemetry.ts）。

心跳属性还包含version/prevVersion（版本升级时附带上一版本）、firstRun、minutesSinceInstall、deployTarget（cloudflare/docker，依据AUTH_MODE推断）与dbBackend（d1/postgres）。这些字段与安装检查摘要setupIssues一起，帮助维护者判断自托管实例的健康状况。

修复项详解

Domain Overview Pages 标签页：清空全部筛选器不再冻结

此前在 Domain Overview 的 Pages 标签页中一次性清除全部筛选器会导致应用无响应。该修复解决了筛选状态全量重置时的重渲染卡顿问题。相关筛选器交互可在 domain-overview-filters.spec.ts 中找到端到端覆盖，配套的 domain-overview-test-utils.ts 提供了测试所需的筛选操作辅助函数。

搜索标签页：关闭当前标签时智能选中右侧标签

关闭一个处于激活状态的搜索标签页后，应用现在会优先切换到其右侧的相邻标签页（存在时）。该行为属于搜索标签页状态管理逻辑的改进，源码实现位于 search-tabs 目录。

Prompt Explorer 引用来源恢复显示

v0.1.0 修复了 Prompt Explorer 不再展示引用来源（cited sources）的问题。引用展示的完整链路现在为：

服务端在 promptExplorer.ts 中生成结构化结果，包含每条引用的url、title与品牌命中标记，配套测试见 promptExplorer.test.ts；
客户端在 PromptExplorerResults.tsx 中渲染「Cited sources (N)」区块：默认展示前 3 条，超出部分通过「+N more」按钮展开；命中查询品牌的引用会以品牌徽标高亮，并对外链使用rel="noreferrer"安全打开。

引用 URL 的安全性由 safeUrl.ts 统一把关，防止模型输出被用于构造危险链接。

SAM 对话：未配置自定义 AI 模型时恢复正常

此前当用户没有配置自定义 AI 模型时，SAM（Search Analytics & Marketing 助手）聊天功能无法工作。v0.1.0 修复了该场景下的降级路径，使 SAM 在默认配置下即可正常对话。SAM 相关能力位于 src/server/features/sam 与 src/serverFunctions/sam.ts。

升级与验证建议

对于自托管用户，升级到 v0.1.0 后建议做以下检查：

确认遥测状态符合预期：默认情况下遥测开启（仅发送聚合计数，见上文数据边界）；如需关闭，在.env/.env.selfhost中设置OPENSEO_TELEMETRY_DISABLED=1，Docker 部署可执行docker compose up -d --force-recreate open-seo使配置生效（详见 SELF_HOSTING_DOCKER.md）；
验证 Dashboard：确认项目已绑定域名并连接 GSC/GA4 后，Dashboard 会依次出现外链脉冲卡、GSC 卡、GA4 卡与审计健康卡；
回归搜索标签页与 Prompt Explorer：关闭标签的右侧选中行为、以及 AI 回答下方的引用来源列表，都应如常工作。

小结

v0.1.0 把「看得见」的功能（项目 Dashboard）与「看不见但关乎信任」的基础设施（自托管遥测）结合在一起：Dashboard 让 GSC、站点审计与外链数据首次在同一视图内汇总；遥测则通过明确的隐私边界与一键退出机制，为维护者提供自托管实例的运行健康度反馈。对于想要深入源码的读者，建议从 DashboardPage.tsx、self-host-telemetry.ts 以及 self-host-telemetry.test.ts 三处入手，它们分别对应本版本三大主题的完整实现与验证闭环。

【免费下载链接】open-seoOpen source alternative to Semrush and Ahrefs项目地址: https://gitcode.com/GitHub_Trending/op/open-seo

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考