memind_adm/docs/analytics-deploy.md

# Analytics / SEO·GEO 部署说明

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

平台边界与字段口径见 Memind [docs/analytics-platform.md](https://git.tkmind.cn/tkmind/Memind/src/branch/main/docs/analytics-platform.md)。  
跨仓库发布顺序见 Memind [docs/analytics-release-runbook.md](https://git.tkmind.cn/tkmind/Memind/src/branch/main/docs/analytics-release-runbook.md)。

## 功能入口（md.tkmind.cn · 103 进程 · 105 反代）

生产 URL：**https://md.tkmind.cn/analytics/seo-geo**

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

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

## 依赖关系

```text
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` 增加或确认：

```env
# 管理后台公网域名（会话 cookie 绑定 md 域名）
H5_PUBLIC_BASE_URL=https://md.tkmind.cn

# SEO/GEO 看板 + Umami SSO（必填，与 105 Umami .env 一致）
MEMIND_UMAMI_SSO_SECRET=<与 /opt/memind-analytics/.env 一致>
UMAMI_SSO_USERNAME=admin

# 可选：覆盖默认
UMAMI_URL=https://fxi.tkmind.cn
UMAMI_WEBSITE_ID=<Memind 公共页面 Website ID>
```

说明：

- 105 生产 Umami 启用 `MEMIND_UMAMI_SSO_ONLY=1` 时，须配置 `MEMIND_UMAMI_SSO_SECRET`；勿依赖 `UMAMI_ADMIN_PASSWORD`
- `websiteId` 也可在 **Analytics 配置** 页面保存（写入 MindSpace admin 配置），服务端优先读库内配置
- 103 必须能访问 `UMAMI_URL`（内网或公网，依网络拓扑）

## 发布

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

```bash
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`。

## 发布后验收

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

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

浏览器：

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

## 本地开发

```bash
pnpm dev   # 5174
```

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

```env
UMAMI_URL=http://127.0.0.1:3100
UMAMI_WEBSITE_ID=<local website id>
MEMIND_UMAMI_SSO_SECRET=<local secret>
```

Memind 本地 analytics 变量见 [local-analytics.md](https://git.tkmind.cn/tkmind/Memind/src/branch/main/docs/local-analytics.md)。

## 故障排查

| 现象 | 检查 |
|------|------|
| SEO/GEO 看板 500 | 103 `adm-api.log`；`MEMIND_UMAMI_SSO_SECRET`；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/*` 路由 |