diff --git a/AGENTS.md b/AGENTS.md index 34639ab..d25f821 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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` diff --git a/docs/105-server-operations.md b/docs/105-server-operations.md index 2b1ab3e..d04742c 100644 --- a/docs/105-server-operations.md +++ b/docs/105-server-operations.md @@ -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) diff --git a/docs/analytics-platform.md b/docs/analytics-platform.md index 23886b7..04811d6 100644 --- a/docs/analytics-platform.md +++ b/docs/analytics-platform.md @@ -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`。 diff --git a/docs/analytics-release-runbook.md b/docs/analytics-release-runbook.md new file mode 100644 index 0000000..bf32b49 --- /dev/null +++ b/docs/analytics-release-runbook.md @@ -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-/` +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-.log +# 或 +ssh root@120.26.184.105 tail -f /opt/memind-analytics/.build/release-.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= + +# 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 配置 | diff --git a/docs/local-analytics.md b/docs/local-analytics.md index 31fdf33..ae25861 100644 --- a/docs/local-analytics.md +++ b/docs/local-analytics.md @@ -35,4 +35,7 @@ MEMIND_PRODUCT_ANALYTICS_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 控制台。 diff --git a/docs/release-deploy.md b/docs/release-deploy.md index 0318e0f..c53f1f7 100644 --- a/docs/release-deploy.md +++ b/docs/release-deploy.md @@ -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