tkmind/memind
1
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

docs: add analytics release runbook and 105 Umami topology
Memind CI / Test, build, and release guards (push) Has been cancelled
Details

Browse Source 
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
2026-08-10 16:21:57 +08:00
parent 2799c808ee
commit 8348ce3625
6 changed files with 177 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+1 -1
View File
@@ -101,7 +101,7 @@ Cursor 额外加载：`.cursor/rules/mindspace-publish-chat-finish-guards.mdc`
## 仓库惯例
- 本地开发：`pnpm dev`（见 [README.md](README.md)）
- 访问统计：**仅 Umami**；Rybbit 已退役，见 [docs/analytics-platform.md](docs/analytics-platform.md) 与 [docs/local-analytics.md](docs/local-analytics.md)
- 访问统计：**仅 Umami**；Rybbit 已退役，见 [docs/analytics-platform.md](docs/analytics-platform.md)、[docs/local-analytics.md](docs/local-analytics.md)、**[docs/analytics-release-runbook.md](docs/analytics-release-runbook.md)**（105 / 103 发布顺序）
- Page Data API：见 [docs/page-data-api-usage.md](docs/page-data-api-usage.md)；改动相关路径后执行 `npm run verify:page-data`
- 生产隔离：[docs/service-isolation-runbook.md](docs/service-isolation-runbook.md)
- 发版须 Git commit，禁止本机直 `rsync` 到 `103/105`
docs/105-server-operations.md
+25
View File
@@ -11,6 +11,7 @@
| 定位 | 云侧入口 / 代理 / 历史链路，不承担可写业务数据主存储 |
| H5 运行目录 | `/root/tkmind_go/ui/h5` |
| Plaza 运行目录 | `/root/tkmind_go/ui/plaza` |
| **Umami Analytics** | `/opt/memind-analytics`（systemd + 原生 artifact，见下节） |
| 数据真身 | 在 `103`（MindSpace、users、data 等），见 [103/105 升级记录](103-105-upgrade-runbook-2026-06-26.md) |
本地开发仓库是 `/Users/john/Project/Memind`；生产 runtime 发布目标是 `103`。
@@ -56,6 +57,29 @@
**不要**使用已停用的 `rsync_to_server.sh` 或直接 rsync 到 `105` 作为常规发布手段（见 `PRODUCTION_RELEASE_RULES.md`）。
## 105 Umami Analytics（`/opt/memind-analytics`）
Memind 访问统计（Umami）独立部署在 105，**不是** Portal H5 目录的一部分。
| 项 | 说明 |
|----|------|
| 公网 | `https://fxi.tkmind.cn` |
| 进程 | `systemctl status memind-analytics-umami` |
| 数据库 | Docker Compose 仅 `db`，`127.0.0.1:55432` |
| 发布 | 在 **memind-analytics** 仓库执行 `bash scripts/release-umami-105.sh --yes` |
| 文档 | memind-analytics `deploy/105-runbook.md`；Memind [analytics-release-runbook.md](analytics-release-runbook.md) |
**禁止** SSH 到 105 手改 `/opt/memind-analytics/live` 内文件或 overlay；变更必须来自 memind-analytics Git 发布。
验收：
```bash
ssh root@120.26.184.105 '
systemctl is-active memind-analytics-umami
curl -sf http://127.0.0.1:3100/api/heartbeat
'
```
## 105 Portal runtime 发布
`105` 上当前 H5 由 `systemd` 服务 `goose-h5` 运行，真实目录是：
@@ -196,5 +220,6 @@ ssh root@120.26.184.105 "sed -i \"s/M广场/M发现/\" /root/tkmind_go/ui/h5/scr
## 相关文档
- [生产 / 测试 / 预览隔离规程](service-isolation-runbook.md)
- [Analytics / SEO·GEO 发布 Runbook](analytics-release-runbook.md)
- [Portal 无源码迁移说明](no-source-portal-migration.md)
- [103/105 一次性升级实施记录](103-105-upgrade-runbook-2026-06-26.md)
docs/analytics-platform.md
+13
View File
@@ -35,3 +35,16 @@ Memind 公开页与生成页的真实用户访问统计 **仅使用 Umami**（`m
| **Memind** | tracker 注入、discovery 分类、Umami 代理 |
| **memind-analytics** | Umami 定制部署、`memind-pages` API（overlay 在 `deploy/umami/overlay/`） |
| **memind_adm** | Analytics 配置、SEO/GEO 看板、Umami SSO |
## 生产发布
跨仓库顺序与命令见 **[analytics-release-runbook.md](analytics-release-runbook.md)**。
| 步骤 | 仓库 | 命令 |
|------|------|------|
| 1 | memind-analytics | `bash scripts/release-umami-105.sh --yes` |
| 2 | Memind（103 Portal） | `bash scripts/release-portal-runtime-prod.sh --yes` |
| 3 | memind_adm（103 gadm） | `bash scripts/release-prod.sh --yes` |
105 Umami 细节见 memind-analytics 仓库 `deploy/105-runbook.md`。
gadm Analytics 环境变量见 memind_adm `docs/analytics-deploy.md`。
docs/analytics-release-runbook.md
+133
View File
@@ -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 配置 |
docs/local-analytics.md
+3
View File
@@ -35,4 +35,7 @@ MEMIND_PRODUCT_ANALYTICS_WEBSITE_ID=<product-website-id>
- **memind_adm → Analytics 配置**：Umami Website ID、密钥、SSO 入口
- **memind_adm → SEO / GEO 流量**：按页监控搜索引擎 / 生成式引擎来源访问
生产发布与环境变量见 memind_adm [`docs/analytics-deploy.md`](../../memind_adm/docs/analytics-deploy.md)。
跨仓库发布顺序见 [analytics-release-runbook.md](analytics-release-runbook.md)。
Analytics 服务 fail-open：未配置或 Umami 不可用时，页面生成与交付不受影响。勿向终端用户暴露 Umami 控制台。
docs/release-deploy.md
+2
View File
@@ -21,6 +21,8 @@
- `105` 与 `103` 的关键差异是：
`105` 为 Linux 环境，**不要携带本机 Mac 的 `node_modules`**；应在 `105` 切换前本机执行 `npm install --omit=dev --no-package-lock`
Umami Analytics（105 `/opt/memind-analytics`）是**独立发布链**，不走 Portal runtime 脚本。见 [analytics-release-runbook.md](analytics-release-runbook.md)。
## 唯一入口
```bash