Files

T

john a67d5a137a docs: add analytics deploy guide for SEO/GEO and Umami SSO

Document gadm env vars, release order, and links to Memind runbook.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-08-10 16:22:10 +08:00

4.0 KiB

Raw Permalink Blame History

Analytics / SEO·GEO 部署说明

管理后台 Analytics 配置 与 SEO / GEO 流量 看板的生产配置与发布。

平台边界与字段口径见 Memind docs/analytics-platform.md。
跨仓库发布顺序见 Memind docs/analytics-release-runbook.md。

功能入口（gadm 5174）

路由	页面	说明
`/analytics`	Analytics 配置	Umami Website ID、域名、SSO 进入 Umami
`/analytics/seo-geo`	SEO / GEO 流量	按页展示搜索引擎 / 生成式引擎来源访问

Rybbit 已退役 — 相关 SSO 接口返回 410；勿再配置 MEMIND_RYBBIT_*。

依赖关系

SeoGeoAnalyticsPage
  -> GET /admin-api/analytics/seo-geo-pages
  -> server/umami-analytics.mjs
  -> 105 Umami API /api/websites/:id/memind-pages?discoveryChannel=seo|geo
     （memind-analytics overlay）

Analytics 配置 / Umami SSO
  -> GET /admin-api/analytics/sso
  -> Memind 共享 SSO 逻辑 + MEMIND_UMAMI_SSO_SECRET

adm 不直连浏览器到 Umami 写库；读统计通过服务端用 Umami 登录态拉 API。

生产环境变量（103 `.env`）

在 /Users/john/Project/memind_adm/.env 增加或确认：

# SEO/GEO 看板（必填）
UMAMI_ADMIN_PASSWORD=<Umami admin 密码>

# 可选：覆盖默认
UMAMI_URL=https://fxi.tkmind.cn
UMAMI_WEBSITE_ID=<Memind Generated Pages 的 Website ID>
UMAMI_SSO_USERNAME=admin

# Umami SSO（Analytics 配置页）
MEMIND_UMAMI_SSO_SECRET=<与 105 /opt/memind-analytics/.env 一致>

说明：

UMAMI_ADMIN_PASSWORD 未配置时，SEO/GEO 看板 API 会报错「未配置 UMAMI_ADMIN_PASSWORD」
websiteId 也可在 gadm Analytics 配置 页面保存（写入 MindSpace admin 配置），服务端优先读库内配置
103 必须能访问 UMAMI_URL（内网或公网，依网络拓扑）

发布

仅改 adm 前端或 server/umami-analytics.mjs 时：

cd /Users/john/Project/memind_adm
bash scripts/release-prod.sh --yes

若改了 Umami memind-pages API 或 overlay，需先发 memind-analytics（105），再发 adm。

若改了 Memind discovery 埋点，需先发 Memind Portal（103），再有 SEO/GEO 分列数据。

完整顺序见 Memind docs/analytics-release-runbook.md。

发布后验收

# Admin API 健康
ssh john@10.10.0.2 'curl -sf http://127.0.0.1:8085/health'

# SEO/GEO API（需替换 cookie 或在内网浏览器登录后测）
# 期望 200 + pages 数组，而非 500 / 未配置 UMAMI_ADMIN_PASSWORD

浏览器：

https://gadm.tkmind.cn/analytics → 「打开 Umami 分析后台」跳转成功
https://gadm.tkmind.cn/analytics/seo-geo → 表格加载；SEO / GEO Tab 切换正常
列口径与 Umami「所有生成页面明细 / public page」一致（页面、PV、UV、点击/表单/参与率等）

本地开发

pnpm dev   # 5174

本地 .env 可指向本机或 105 Umami：

UMAMI_URL=http://127.0.0.1:3100
UMAMI_ADMIN_PASSWORD=umami
UMAMI_WEBSITE_ID=<local website id>
MEMIND_UMAMI_SSO_SECRET=<local secret>

Memind 本地 analytics 变量见 local-analytics.md。

故障排查

现象	检查
SEO/GEO 看板 500	103 `adm-api.log`；`UMAMI_ADMIN_PASSWORD`；105 Umami 是否 active
Umami SSO 失败	`MEMIND_UMAMI_SSO_SECRET` 与 105 `.env` 是否一致
看板无 SEO/GEO 行	Memind discovery 是否已发布；Umami 是否有带 `discovery_channel` 的事件
Rybbit 链接/报错	清理旧书签；代码已移除 Rybbit SSO

路径	说明
`src/admin/pages/SeoGeoAnalyticsPage.tsx`	SEO/GEO 看板 UI
`src/admin/pages/AnalyticsConfigPage.tsx`	Analytics 配置
`server/umami-analytics.mjs`	Umami memind-pages 代理
`server/app.mjs`	`/admin-api/analytics/*` 路由

4.0 KiB Raw Permalink Blame History Unescape Escape