From 525f741914ea2f4270b1574ef14eccf41e28d725 Mon Sep 17 00:00:00 2001 From: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> Date: Mon, 2 Nov 2026 16:07:35 +0800 Subject: [PATCH] docs(analytics): document actionable first-time local setup Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com> --- docs/frontend-analytics-integration.md | 22 +-- docs/frontend-analytics.md | 8 +- docs/skillhub/en/guide/frontend-analytics.md | 133 ++++++++++++++++--- docs/skillhub/guide/frontend-analytics.md | 132 +++++++++++++++--- 4 files changed, 240 insertions(+), 55 deletions(-) diff --git a/docs/frontend-analytics-integration.md b/docs/frontend-analytics-integration.md index 00c69021e..9d77b1ca2 100644 --- a/docs/frontend-analytics-integration.md +++ b/docs/frontend-analytics-integration.md @@ -34,18 +34,20 @@ function stop() { stopObserver(); adapter.stop() } 前提：已有能正常使用的 SkillHub Web；已安装 Docker 和 Compose；能使用示例指定的 Umami 3.4.1、Postgres 16、Nginx 1.30.6 镜像；本机 8300 和 8081 端口空闲。所有 shell 命令从仓库根目录运行。示例会创建独立演示网络和临时数据库，不用于生产持久化。请在隔离环境运行。 +启动前先执行 `docker compose ls --all`，确认专用项目名 `skillhub-analytics-demo` 未被其他项目占用。若已占用，选择一个未使用的新名字，并在本文所有命令中一致替换。所有演示命令显式使用 `-p`，防止继承终端已有的 `COMPOSE_PROJECT_NAME` 而误操作其他部署；换一个克隆目录本身不能隔离 Compose 项目。 + 先检查配置，再启动： ```sh -docker compose -f docs/examples/analytics/compose.yaml config -docker compose -f docs/examples/analytics/compose.yaml up -d +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml config +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d ``` 默认上游是 `host.docker.internal:80`，对应 release Compose 的 `WEB_PORT` 默认 80。这里是容器访问宿主机的 Web 入口，不是后端端口，也不是 edge 自己的 8081。若 Web 实际发布在其他端口（比如 18080），先在当前终端导出，再启动。后面所有 compose 命令都要在这个终端里执行，否则重建 edge 时会回到默认的 80： ```sh export SKILLHUB_WEB_UPSTREAM=host.docker.internal:18080 -docker compose -f docs/examples/analytics/compose.yaml up -d +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d ``` 原生 Linux Docker 需要 `host.docker.internal` 映射，示例 edge 已包含 `extra_hosts: ["host.docker.internal:host-gateway"]`。Docker Desktop／OrbStack 已提供这个名字。宿主机 Web 必须监听容器可达的地址；如果防火墙或仅回环监听阻止访问，先调整可达性，或填写容器可以访问的其他 `host:port`。不要填写 `http://` 或 URL 路径。 @@ -62,9 +64,9 @@ docker compose -f docs/examples/analytics/compose.yaml up -d 然后重建 edge，使单文件挂载更新可靠生效： ```sh -docker compose -f docs/examples/analytics/compose.yaml up -d --force-recreate edge -docker compose -f docs/examples/analytics/compose.yaml exec edge nginx -t -docker compose -f docs/examples/analytics/compose.yaml exec edge nginx -T +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d --force-recreate edge +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml exec edge nginx -t +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml exec edge nginx -T ``` 打开 `http://localhost:8081`，不要从原 Web 入口验收注入。 @@ -164,7 +166,7 @@ stop 不能撤回已开始的 fetch。重新获准后才可调用 start()；同 7. **关闭态独立验收**：将入口恢复 `enabled: false`，重新创建 edge： ```sh -docker compose -f docs/examples/analytics/compose.yaml up -d --no-deps --force-recreate edge +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d --no-deps --force-recreate edge ``` 保持「Disable cache」勾选（或换一个新的无痕窗口），刷新页面后搜索：不得加载 script.js、产生采集回调或 send，搜索与技能卡片仍正常。完全不注入时也应零采集。这一步不验证启用态的故障隔离。 @@ -174,7 +176,7 @@ docker compose -f docs/examples/analytics/compose.yaml up -d --no-deps --force-r 保持入口启用和授权有效，仅停止演示 Umami： ```sh -docker compose -f docs/examples/analytics/compose.yaml stop umami +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml stop umami ``` 在已加载 SDK 的页面再次搜索，应观察到采集请求失败，同时搜索结果和技能卡片仍正常。再新开一个禁用缓存的页面：SDK 请求应失败，但业务仍可用，不能出现统计异常导致的未捕获页面错误。记录失败请求和业务结果；不要把关闭态的零请求当成故障隔离通过，也不要把失败请求当作成功入库。 @@ -182,7 +184,7 @@ docker compose -f docs/examples/analytics/compose.yaml stop umami 9. **恢复或清理**：继续演示时执行： ```sh -docker compose -f docs/examples/analytics/compose.yaml start umami +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml start umami ``` 等待 `http://localhost:8300` 恢复可用后，禁用缓存并刷新 edge 页面，再执行一次新动作，确认请求成功且新事件入库。原页面的 SDK 初始化失败不会保证自动恢复，故障期间丢失的事件也不保证补发。结束演示则按第 7 节关闭采集、恢复入口文件，并仅清理该演示项目；不要删除现有 SkillHub 或共享平台的数据。 @@ -208,7 +210,7 @@ docker compose -f docs/examples/analytics/compose.yaml start umami 结束本地演示（会删除演示数据库，先确认无需要保留的数据）： ```sh -docker compose -f docs/examples/analytics/compose.yaml down -v +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml down -v ``` 限制必须一起评估： diff --git a/docs/frontend-analytics.md b/docs/frontend-analytics.md index 6be1b6162..5156ac485 100644 --- a/docs/frontend-analytics.md +++ b/docs/frontend-analytics.md @@ -225,9 +225,11 @@ example is not present in the `web/` Docker build context. Postgres 16 and an optional edge; SkillHub remains your existing web upstream. From the repository root: +Before starting, run `docker compose ls --all` and confirm the dedicated project name `skillhub-analytics-demo` is not used by another project. If occupied, choose an unused name and replace it consistently in every command. Explicit `-p` prevents inheriting an existing terminal `COMPOSE_PROJECT_NAME` and targeting another deployment; cloning into a different directory does not itself isolate the Compose project. + ```sh -docker compose -f docs/examples/analytics/compose.yaml config -docker compose -f docs/examples/analytics/compose.yaml up -d +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml config +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d ``` The default Web upstream is `host.docker.internal:80`, matching the release @@ -247,7 +249,7 @@ Create a synthetic website in Umami, copy its UUID into `enabled` and the consent hook for your local policy. Open SkillHub through `http://localhost:8081` and exercise an enabled action; inspect the request to `/_skillhub-umami/api/send` and Umami's event view. Tear down the local demo with -`docker compose -f docs/examples/analytics/compose.yaml down -v` (demo data is removed). +`docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml down -v` (demo data is removed). [`umami-adapter.mjs`](https://github.com/iflytek/skillhub/blob/main/docs/examples/analytics/observe/v1/umami-adapter.mjs) is the only vendor-specific code. It loads `/script.js` with `data-auto-track="false"`, so diff --git a/docs/skillhub/en/guide/frontend-analytics.md b/docs/skillhub/en/guide/frontend-analytics.md index 8e21802a3..e344cb864 100644 --- a/docs/skillhub/en/guide/frontend-analytics.md +++ b/docs/skillhub/en/guide/frontend-analytics.md @@ -1,30 +1,121 @@ -# Frontend analytics +# Frontend analytics: first local setup -Collection and SDK loading are off by default. The delivered example is a **manual integration**; configuration-only activation through Docker/Compose or Helm has not been merged. Click events express intent, not successful downloads, publishing, or execution. +This walkthrough adds a local demo entry in front of an existing SkillHub Web and verifies events stored in Umami. Collection is off by default. This is a **manual integration example**; configuration-only activation through Docker/Compose or Helm has not been merged. -## Connect a platform +## 1. Prepare Web and the example files -1. **Choose a platform**: reuse one or run the isolated Umami demo. Never use demo credentials in production. -2. **Configure collection**: provide a valid website UUID, selected actions, and an explicit consent check. Deployment owners maintain the entry module, adapter, and proxy. -3. **Verify before enabling access**: check outgoing fields and stored events, then confirm disabled collection and platform failure leave normal business flows working. +Confirm your existing SkillHub Web opens and search works. Not deployed yet? Complete [Docker deployment](./deployment.md) first. This example assumes a local root-path deployment; use the [detailed guide](./frontend-analytics-guide.md) for sub-paths, production proxies, and CSP. Docker, Compose, Git, and unused local ports 8300 and 8081 are required. -The [detailed setup guide (Chinese)](./frontend-analytics-guide.md) contains commands, rules, sub-paths, and recovery steps. The [interface and privacy contract (English)](./frontend-analytics-reference.md) defines event and adapter boundaries. - -## Acceptance checks - -| Scenario | Expected result | +| Address / port | Purpose | | --- | --- | -| Disabled by default | No analytics SDK or events; business flows work | -| Enabled with consent | One corresponding event per action, actually stored; no search terms or identity fields | -| Platform fails while enabled | Collection fails, but search and skill pages still work | -| Platform recovers | Refresh to verify new stored events; lost events are not guaranteed to replay | +| Original SkillHub Web (default 80) | Existing application; this demo does not redeploy it | +| `http://localhost:8300` | Umami administration: create a website and inspect events | +| `http://localhost:8081` | New demo SkillHub entry: edge injects the collector script | -## Common questions +One-click installation directories do not contain the example sources. Get the demo files from the fixed `v0.2.25` tag in a separate working directory: -- **No data?** Check the demo edge entry, consent, website UUID, rules, and cache. HTTP 200 alone does not prove storage. -- **Can any platform work by setting its URL?** No. Other platforms need an adapter and reviewed proxy endpoints. -- **Is collection anonymous?** A small JSON payload is not anonymous transport. IP and User-Agent may still reach the platform. Deployment owners handle access control, retention, and compliance. +```sh +git clone --depth 1 --branch v0.2.25 https://github.com/iflytek/skillhub.git skillhub-analytics-demo +cd skillhub-analytics-demo +``` -## Disable collection +Use an unused destination if that directory exists. This fetches demo assets, not a replacement SkillHub deployment; do not reinstall your existing application. If using an existing checkout, confirm it contains `docs/examples/analytics/compose.yaml`. Run every following shell command from the **repository root in the same terminal**, not the runtime installation directory. -Use `window.skillhubAnalytics.stop()` to stop future dispatch in the current page; already dispatched requests cannot be recalled. For persistent disabling, restore `enabled: false`, recreate edge, and refresh with cache disabled. Remove the injection/edge and return to the original Web entry to remove the integration entirely. Follow the detailed guide to clean up only the isolated demo, never shared platform or business data. +The example connects to the original Web on host port 80 by default. If its actual port is 18080, first set: + +```sh +export SKILLHUB_WEB_UPSTREAM=host.docker.internal:18080 +``` + +Replace `18080` with the actual **Web** port, not the backend port. Do not include `http://` or a path. Web must listen on an address reachable by containers; loopback-only binding or firewall rules can block edge. The example includes the `host-gateway` mapping for native Linux. + +## 2. Start Umami and obtain a website UUID + +Before starting, run `docker compose ls --all` and confirm the dedicated project name `skillhub-analytics-demo` is not used by another project. If occupied, choose an unused name and replace it consistently in every command. Explicit `-p` prevents inheriting an existing terminal `COMPOSE_PROJECT_NAME` and targeting another deployment; cloning into a different directory does not itself isolate the Compose project. + +Check the example configuration, then start only its database and Umami: + +```sh +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml config +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d postgres umami +``` + +Wait for `http://localhost:8300`, sign in with demo credentials **`admin` / `umami`**, and change the password immediately. Create a demo website in website management and copy its **UUID**, not its name, URL, or your password. + +This Compose uses public demo secrets and a temporary database. It does not provide a production persistence, backup, or access-control solution; do not deploy it unchanged in production. + +## 3. Configure the demo actions + +Open `docs/examples/analytics/observe/v1/observer.mjs` in the repository. Preserve the imports, `start()`, `stop()`, and other code; replace only `const config` and `hasConsent()` with: + +```js +const config = Object.freeze({ + enabled: true, + website: 'REPLACE_WITH_YOUR_WEBSITE_UUID', + prefix: '/_skillhub-umami', + rules: DEFAULT_RULES, +}) + +// Only for an isolated demo where you explicitly consent to collection. +// Production integrations must read the actual consent state. +function hasConsent() { return true } +``` + +`DEFAULT_RULES` is already imported and covers existing actions such as search submission and skill cards. The original `skill.example.open` has no corresponding product element, so it is omitted here. Never put administration secrets or personal data in this file, and do not use a fixed `true` for other users. + +## 4. Start the demo entry and verify stored events + +```sh +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d --force-recreate edge +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml exec edge nginx -t +``` + +Expect a successful Nginx check. Open **`http://localhost:8081`**, rather than the original Web URL, to test collection. + +1. In developer tools Network, enable **Disable cache** and **Preserve log**, refresh, and filter `/_skillhub-umami/`. Expect `script.js` to load successfully, without an automatic pageview. +2. Enter test text and click Search: expect one `api/send` POST. Search again with Enter: expect one additional event. +3. Inspect the payload: `name` is `search.query.submit`, and `data.event` is `submit`. Search terms and identity fields must be absent. Open a skill card to check `skill.card.open`. +4. In Umami on port 8300, open the website events view and select the current time range. Confirm matching events and counts. **HTTP 200 alone does not prove storage.** Click events express intent, not successful downloads, publishing, or execution. + +| Additional acceptance check | Expected result | +| --- | --- | +| Disable collection and refresh | No SDK / event requests; application still works | +| Stop demo Umami while collection is enabled | Collection fails; search and skill pages still work | +| Start Umami and refresh | New events are stored; lost events are not guaranteed to replay | + +The [detailed guide](./frontend-analytics-guide.md) provides fault-test controls and recovery steps. Operate only this demo, never stop a shared platform. + +## 5. Disable and clean up + +Run `window.skillhubAnalytics.stop()` in the current page to stop future dispatch; already dispatched requests cannot be recalled. For persistent disabling, restore `enabled: false` and make `hasConsent()` return `false`, then recreate edge and refresh with cache disabled. + + +```sh +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d --no-deps --force-recreate edge +``` + +To pause the demo while keeping its containers for continued use: + +```sh +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml stop +``` + +The demo database is not a production persistence solution. Back up required data first; stopping is not a durability guarantee. Only when demo data is no longer needed, run: + +```sh +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml down -v +``` + +This removes the example containers and volumes; treat demo data as deleted. Do not run cleanup against the existing SkillHub deployment. Return to the original Web URL afterward. + +## Common problems + +| Symptom | Check first | +| --- | --- | +| Compose file not found | Work from the cloned repository root, not the runtime installation directory | +| Ports 8300 / 8081 cannot start | Local port conflicts; inspect `docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml logs` | +| 8081 returns 502 | Web port, container-reachable binding, and firewall; do not use the backend port | +| No collection requests | Visit 8081, verify enabled / consent, recreate after editing, and refresh with cache disabled | +| Requests fail or no stored events | Correct UUID, Umami readiness, matching time range, and the actual Network response | + +Further reading: [complete setup guide (Chinese)](./frontend-analytics-guide.md) · [interface and privacy contract](./frontend-analytics-reference.md). Minimal fields do not mean anonymous transport: IP and User-Agent may still reach the platform. Deployment owners handle retention, access control, and compliance. diff --git a/docs/skillhub/guide/frontend-analytics.md b/docs/skillhub/guide/frontend-analytics.md index d5337fcc2..16d95e83d 100644 --- a/docs/skillhub/guide/frontend-analytics.md +++ b/docs/skillhub/guide/frontend-analytics.md @@ -1,30 +1,120 @@ -# 前端动作统计 +# 前端动作统计：首次本地接入 -默认不采集、不加载统计 SDK。当前提供**手动接入示例**；通过 Docker／Compose 或 Helm 配置直接开启的能力尚未合并。点击事件只表示操作意图，不证明下载、发布或执行成功。 +本文带你在已有 SkillHub 前增加一个本地演示入口，连接 Umami 并确认事件入库。默认不采集；当前是**手动接入示例**，通过 Docker／Compose 或 Helm 配置直接开启的方案尚未合并。 -## 如何接入 +## 1. 准备已有 Web 和示例文件 -1. **选平台**：已有平台可复用；没有平台可先运行隔离的 Umami 演示。不要把演示密码用于生产。 -2. **配置采集**：准备有效网站 UUID、需要采集的动作与明确授权判断；部署方维护采集入口、适配器和代理。 -3. **验收再开放**：检查请求字段和真实入库，并验证关闭与平台故障不影响正常业务。 +先确认 SkillHub Web 可以正常打开、搜索。尚未部署？先完成 [Docker 部署](./deployment.md)，再回来继续。本例适用于本机根路径部署；子路径、生产代理与 CSP 请用[详细指南](./frontend-analytics-guide.md)。需要 Docker、Compose 和 Git，且 8300、8081 未被占用。 -[详细操作指南（中文）](./frontend-analytics-guide.md)提供命令、规则、子路径与恢复步骤；[接口与隐私契约（英文）](./frontend-analytics-reference.md)定义事件及适配器边界。 - -## 验收看什么 - -| 场景 | 应观察到什么 | +| 地址／端口 | 用途 | | --- | --- | -| 默认关闭 | 不加载统计 SDK、不发送事件，业务正常 | -| 已启用且获得授权 | 一次动作一条对应事件，平台确实入库；不传搜索词或身份字段 | -| 启用后平台故障 | 请求失败但搜索、技能页面仍可用 | -| 平台恢复 | 刷新页面后新事件能入库，丢失事件不保证补发 | +| 原 SkillHub Web（默认 80） | 已有业务服务，本例不会重新部署它 | +| `http://localhost:8300` | Umami 管理界面，创建网站和查看事件 | +| `http://localhost:8081` | 本例新增的 SkillHub 访问入口，经过 edge 注入采集脚本 | + +一键安装目录只有部署文件，没有本例源码。从固定的 `v0.2.25` tag 获取演示配套，在另一个工作目录执行： + +```sh +git clone --depth 1 --branch v0.2.25 https://github.com/iflytek/skillhub.git skillhub-analytics-demo +cd skillhub-analytics-demo +``` + +目标目录已存在时换用空目录。这只是获取演示配套，不会替换现有 SkillHub，也不要求重装它。使用已有仓库时先确认包含 `docs/examples/analytics/compose.yaml`。以下所有 shell 命令都在**仓库根目录、同一终端**执行，不能在一键安装目录直接运行。 + +示例默认连接原 Web 的宿主机 80 端口。如果实际是 18080，先设置： + +```sh +export SKILLHUB_WEB_UPSTREAM=host.docker.internal:18080 +``` + +将 `18080` 换成实际 **Web** 端口，不是后端端口；不要填写 `http://` 或路径。Web 必须监听容器可达的地址，仅回环监听或防火墙限制可能阻止 edge 访问。示例已为原生 Linux 配置 `host-gateway` 映射。 + +## 2. 启动 Umami，取得网站 UUID + +启动前先执行 `docker compose ls --all`，确认专用项目名 `skillhub-analytics-demo` 未被其他项目占用。若已占用，选择一个未使用的新名字，并在本文所有命令中一致替换。所有演示命令显式使用 `-p`，防止继承终端已有的 `COMPOSE_PROJECT_NAME` 而误操作其他部署；换一个克隆目录本身不能隔离 Compose 项目。 + +先检查示例，再只启动统计数据库和 Umami： + +```sh +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml config +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d postgres umami +``` + +等待 `http://localhost:8300` 可访问，用演示账号 **`admin` / `umami`** 登录并立即修改密码。在网站管理中创建一个演示网站，复制它的 **UUID**（不是网站名称、网址或登录密码）。 + +此 Compose 使用公开演示密钥和临时数据库，不具备生产持久化、备份与访问控制方案，不要直接用作生产部署。 + +## 3. 配置本次演示要采集的动作 + +打开仓库中的 `docs/examples/analytics/observe/v1/observer.mjs`，保留现有 imports、`start()`、`stop()` 等代码，仅将 `const config` 和 `hasConsent()` 替换为下列内容： + +```js +const config = Object.freeze({ + enabled: true, + website: '替换为上一步的网站 UUID', + prefix: '/_skillhub-umami', + rules: DEFAULT_RULES, +}) + +// 仅用于本人明确同意采集的隔离演示；正式接入必须读取真实授权状态。 +function hasConsent() { return true } +``` + +`DEFAULT_RULES` 已由文件开头导入，包含搜索提交、技能卡片等现有动作。示例原有的 `skill.example.open` 不对应产品元素，这里不使用它。不要将真实管理密钥或个人信息放进该文件，也不要对其他用户直接使用固定的 `true`。 + +## 4. 启动演示入口，检查真实事件 + +```sh +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d --force-recreate edge +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml exec edge nginx -t +``` + +`nginx -t` 应成功。打开 **`http://localhost:8081`**，不要继续使用原 Web 地址验收采集。 + +1. 开发者工具 Network 勾选 **Disable cache** 和 **Preserve log**，刷新页面，筛选 `/_skillhub-umami/`。应成功加载 `script.js`，但不自动发送 pageview。 +2. 搜索框输入测试文字并点击搜索，应有一条 `api/send` POST；再按 Enter 搜索一次，应再增加一条。 +3. 检查 Payload：事件名为 `search.query.submit`，`data.event` 为 `submit`；不得包含搜索词或身份字段。点击技能卡片可检查 `skill.card.open`。 +4. 在 8300 的 Umami 网站事件页选择当前时间范围，确认对应事件及次数。**HTTP 200 本身不能证明已入库**。点击事件只代表意图，不代表下载、发布或执行成功。 + +| 还需验收 | 预期 | +| --- | --- | +| 关闭采集、刷新 | 无 SDK／事件请求，业务正常 | +| 已启用时停止演示 Umami | 采集失败，搜索与技能页面仍可用 | +| 启动 Umami、刷新 | 新事件可入库；不保证补发丢失事件 | + +上述故障测试的完整对照、恢复步骤见[详细指南](./frontend-analytics-guide.md)。只操作本例统计服务，不要停止共享平台。 + +## 5. 关闭与清理 + +当前页执行 `window.skillhubAnalytics.stop()` 可阻止后续派发，已发出的请求不能撤回。持续关闭时，将文件恢复为 `enabled: false`、`hasConsent()` 返回 `false`，再重建 edge 并禁用缓存刷新。 + + +```sh +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d --no-deps --force-recreate edge +``` + +暂时停止演示、保留容器以便继续： + +```sh +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml stop +``` + +演示数据库不是生产持久化方案；需要数据请先备份，不要把停止等同持久化保证。确定不再需要演示数据时才执行： + +```sh +docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml down -v +``` + +该命令删除本示例的容器和卷，演示数据应视为删除；不对现有 SkillHub 部署执行清理。关闭后回到原 Web 地址。 ## 常见问题 -- **没有数据？** 核对是否走了示例 edge 入口、授权、网站 UUID、规则和缓存；HTTP 200 不等于已入库。 -- **任意平台都能只填地址吗？** 不能。其他平台还需适配器和经过审核的代理端点。 -- **算匿名采集吗？** 精简 JSON 不等于匿名；平台仍可能收到 IP、User-Agent 等传输信息。部署方负责访问控制、保留期限与合规。 +| 现象 | 先检查 | +| --- | --- | +| 找不到 Compose 文件 | 当前目录应是克隆仓库根目录，而非 runtime 安装目录 | +| 8300／8081 无法启动 | 本机端口占用；看 `docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml logs` | +| 8081 返回 502 | Web 端口、容器可达监听和防火墙；不要填后端端口 | +| 没有采集请求 | 是否访问 8081，入口是否启用／获得授权，修改后是否重建及禁用缓存刷新 | +| 请求失败或平台无数据 | UUID 是否正确、Umami 是否就绪、时间范围是否匹配；检查 Network 响应 | -## 如何关闭 - -当前页可用 `window.skillhubAnalytics.stop()` 停止后续派发，已发出的请求不能撤回。持续关闭需将入口恢复为 `enabled: false`、重新创建 edge 并禁用缓存刷新；完全撤掉接入则移除注入／edge，回到原 Web 入口。隔离演示的清理步骤见详细指南，不要清理共享平台或业务数据。 +进阶：[完整操作指南](./frontend-analytics-guide.md) · [接口与隐私契约（英文）](./frontend-analytics-reference.md)。字段精简不等于匿名传输：IP、User-Agent 等仍可能到达平台，保留期限、访问控制和合规由部署方负责。