docs: add analytics release runbook and 105 Umami topology
Memind CI / Test, build, and release guards (push) Has been cancelled
Memind CI / Test, build, and release guards (push) Has been cancelled
Cross-repo publish order for memind-analytics, Portal, and memind_adm; update platform and 105 operations docs for systemd artifact deploy. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
john
@@ -0,0 +1,133 @@
|
||||
# Analytics / SEO·GEO 生产发布 Runbook
|
||||
|
||||
跨仓库发布顺序与命令速查。统计平台说明见 [analytics-platform.md](analytics-platform.md)。
|
||||
|
||||
## 架构（2026-08 起）
|
||||
|
||||
```text
|
||||
公开页 / H5
|
||||
-> Memind /analytics/* 代理
|
||||
-> 105 Umami（systemd + 原生 artifact，127.0.0.1:3100）
|
||||
-> PostgreSQL（仅 db 容器，127.0.0.1:55432）
|
||||
|
||||
memind_adm SEO/GEO 看板
|
||||
-> /admin-api/analytics/seo-geo-pages
|
||||
-> 105 Umami memind-pages API（overlay）
|
||||
```
|
||||
|
||||
**已废弃：** Rybbit；105 上 Docker 编译 Umami 镜像；Docker 跑 Umami 应用容器（`docker-umami` profile 仅遗留）。
|
||||
|
||||
## 推荐发布顺序
|
||||
|
||||
| 顺序 | 仓库 | 何时必须发 | 命令 |
|
||||
|------|------|------------|------|
|
||||
| 1 | **memind-analytics** | 改了 `deploy/umami/overlay/`、`memind-pages` API | `bash scripts/release-umami-105.sh --yes` |
|
||||
| 2 | **Memind** | 改了 discovery 埋点、Umami 代理、公开页 delivery | `bash scripts/release-portal-runtime-prod.sh` |
|
||||
| 3 | **memind_adm** | 改了 SEO/GEO 看板、Analytics 配置页、Umami 代理 | `bash scripts/release-prod.sh --yes` |
|
||||
|
||||
只改 overlay / API 时，发 **105** 即可；只改 adm 看板 UI 时，发 **103 gadm** 即可。
|
||||
Memind discovery 字段（`discovery_channel` 等）未上线前，adm 看板可能暂无 SEO/GEO 分列数据。
|
||||
|
||||
## 1. 105 Umami（memind-analytics）
|
||||
|
||||
工作目录：本机 `memind-analytics` 仓库（或 worktree `memind-analytics-release-main`）。
|
||||
|
||||
```bash
|
||||
bash scripts/release-umami-105.sh --yes
|
||||
```
|
||||
|
||||
脚本会：
|
||||
|
||||
1. 打包部署文件上传到 `105:/opt/memind-analytics/incoming/`
|
||||
2. **在 105 原生** `pnpm install`（复用 `node_modules` 缓存）+ `pnpm run build-docker`
|
||||
3. 产出 artifact → `/opt/memind-analytics/releases/umami-<release_id>/`
|
||||
4. `backup/backup.sh` 备份 PostgreSQL
|
||||
5. 切换 `/opt/memind-analytics/live` symlink，`systemctl restart memind-analytics-umami`
|
||||
|
||||
### 监控（SSH 断开不影响构建）
|
||||
|
||||
```bash
|
||||
ssh root@120.26.184.105 tail -f /opt/memind-analytics/.build/build-<release_id>.log
|
||||
# 或
|
||||
ssh root@120.26.184.105 tail -f /opt/memind-analytics/.build/release-<release_id>.log
|
||||
```
|
||||
|
||||
### 验收
|
||||
|
||||
```bash
|
||||
ssh root@120.26.184.105 '
|
||||
systemctl is-active memind-analytics-umami
|
||||
curl -sf http://127.0.0.1:3100/api/heartbeat
|
||||
readlink /opt/memind-analytics/live
|
||||
'
|
||||
```
|
||||
|
||||
公网：`https://fxi.tkmind.cn/api/heartbeat`
|
||||
|
||||
详细路径、回滚与 nginx 见 **memind-analytics** 仓库 [`deploy/105-runbook.md`](https://git.tkmind.cn/tkmind/memind-analytics/src/branch/main/deploy/105-runbook.md)。
|
||||
|
||||
## 2. 103 Portal（Memind）
|
||||
|
||||
```bash
|
||||
cd /Users/john/Project/Memind
|
||||
bash scripts/check-release-ready.sh # 发布闸门
|
||||
bash scripts/release-portal-runtime-prod.sh --yes
|
||||
```
|
||||
|
||||
与 Analytics 相关的 Memind 改动通常包括：
|
||||
|
||||
- `mindspace-analytics-discovery.mjs` — SEO/GEO 分类
|
||||
- `mindspace-analytics.mjs` — 事件维度
|
||||
- Portal `/analytics/*` 反代
|
||||
|
||||
本地环境变量见 [local-analytics.md](local-analytics.md)。
|
||||
|
||||
## 3. 103 管理后台（memind_adm）
|
||||
|
||||
```bash
|
||||
cd /Users/john/Project/memind_adm
|
||||
bash scripts/release-prod.sh --yes
|
||||
```
|
||||
|
||||
### 生产 `.env`（Analytics 相关）
|
||||
|
||||
```env
|
||||
# SEO/GEO 看板拉 Umami memind-pages API 所需
|
||||
UMAMI_ADMIN_PASSWORD=<与 Umami admin 账号一致>
|
||||
UMAMI_URL=https://fxi.tkmind.cn # 可选，默认 http://127.0.0.1:3100
|
||||
UMAMI_WEBSITE_ID=<Memind Generated Pages 的 Website ID>
|
||||
|
||||
# Umami SSO（Analytics 配置页「打开 Umami」）
|
||||
MEMIND_UMAMI_SSO_SECRET=<与 105 .env 一致>
|
||||
UMAMI_SSO_USERNAME=admin
|
||||
```
|
||||
|
||||
103 需能访问 105 Umami（内网或配置的 `UMAMI_URL`）。
|
||||
|
||||
### 验收
|
||||
|
||||
1. gadm → **Analytics 配置** → 「打开 Umami 分析后台」可 SSO 登录
|
||||
2. gadm → **SEO / GEO 流量** → 表格加载无 `未配置 UMAMI_ADMIN_PASSWORD`
|
||||
3. 抽样对比 Umami「所有生成页面明细」与 adm 看板列口径一致
|
||||
|
||||
详见 memind_adm [`docs/analytics-deploy.md`](../memind_adm/docs/analytics-deploy.md)。
|
||||
|
||||
## 常见问题
|
||||
|
||||
| 现象 | 处理 |
|
||||
|------|------|
|
||||
| 105 构建 `check-db` 失败 | 应使用 `build-docker`（已写入 `build-umami-artifact.sh`），勿改回 `pnpm build` |
|
||||
| `Umami database is not running` | 使用 `backup/backup.sh`，不要用根目录旧版 `backup.sh` |
|
||||
| 105 构建很慢 | 首次 install+compile 约 20–40 分钟；后续 overlay 小改可复用 `node_modules` |
|
||||
| adm SEO/GEO 看板空 | 确认 Memind discovery 已发布且有真实 SEO/GEO 流量 |
|
||||
| Rybbit 相关报错 | 已退役，删除遗留 env/文档引用，见 [analytics-platform.md](analytics-platform.md) |
|
||||
|
||||
## 相关文档
|
||||
|
||||
| 文档 | 内容 |
|
||||
|------|------|
|
||||
| [analytics-platform.md](analytics-platform.md) | 平台边界、字段口径、Rybbit 退役 |
|
||||
| [local-analytics.md](local-analytics.md) | 本地 Umami 与 Memind env |
|
||||
| [105-server-operations.md](105-server-operations.md) | 105 运维边界（含 `/opt/memind-analytics`） |
|
||||
| memind-analytics `README.md` | Umami 仓库运维与 overlay |
|
||||
| memind_adm `docs/analytics-deploy.md` | gadm Analytics / SEO·GEO 配置 |
|
||||
Reference in New Issue
Block a user