docs(analytics): document actionable first-time local setup

Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
2026-11-14 09:01:16 +00:00 · 2026-11-02 16:07:35 +08:00 · 2026-11-02 16:07:35 +08:00 · 525f741914
commit 525f741914
parent 00a7b8679c
4 changed files with 240 additions and 55 deletions
--- 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
 ```

 限制必须一起评估：
--- 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
--- 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.
--- 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 等仍可能到达平台，保留期限、访问控制和合规由部署方负责。