mirror of
https://github.com/iflytek/skillhub.git
synced 2026-11-16 09:21:18 +00:00
Merge pull request #1046 from iflytek/docs/issue1042-remaining
docs: complete deployment and navigation gaps for issue 1042
This commit is contained in:
commit
d61f70f8e6
19 changed files with 438 additions and 32 deletions
19
README.md
19
README.md
|
|
@ -282,11 +282,28 @@ curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- u
|
|||
| Parameter | Description | Example |
|
||||
|-----------|-------------|---------|
|
||||
| `--public-url <url>` | Public access URL (recommended) | `--public-url https://skill.example.com` |
|
||||
| `--version <tag>` | Specific image tag | `--version v0.2.0` |
|
||||
| `--version <tag>` | Specific image tag | `--version v0.2.25` |
|
||||
| `--ref <git-ref>` | Git ref for deployment files (GitHub raw mode) | `--ref v0.2.25` |
|
||||
| `--aliyun` | Use Aliyun mirror (China) | `--aliyun` |
|
||||
| `--home <dir>` | Runtime directory | `--home /opt/skillhub` |
|
||||
| `--no-scanner` | Disable security scanner | `--no-scanner` |
|
||||
|
||||
`--version` selects image tags; it does not pin the deployment files. By default,
|
||||
those files come from `main`. To pin the installer, Compose file, environment
|
||||
template and application image tag together, use a released Git ref and tag:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/iflytek/skillhub/v0.2.25/scripts/runtime.sh | sh -s -- up --ref v0.2.25 --version v0.2.25 --home /opt/skillhub --public-url https://skillhub.your-company.com
|
||||
```
|
||||
|
||||
This example uses GitHub raw and requires access to it. `--aliyun` switches runtime
|
||||
file downloads to the OSS root, where `--ref` does not select a versioned directory.
|
||||
Likewise, a custom `SKILLHUB_RAW_BASE` takes precedence over the Git-ref URL.
|
||||
Neither should be described as pinning deployment files with `--ref`.
|
||||
The script preserves an existing `.env.release`; record its settings and explicit
|
||||
image overrides separately. Pinning the application tag does not freeze every
|
||||
dependency image or replace a database backup.
|
||||
|
||||
> **Important**: Configure `--public-url` for production deployments to ensure CLI install commands and Agent setup instructions display the correct URLs.
|
||||
|
||||
For sub-path deployments, keep the public URL and runtime base path aligned in
|
||||
|
|
|
|||
16
README_zh.md
16
README_zh.md
|
|
@ -249,11 +249,25 @@ curl -fsSL https://imageless.oss-cn-beijing.aliyuncs.com/runtime.sh | sh -s -- u
|
|||
| 参数 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| `--public-url <url>` | 公网访问地址(推荐配置) | `--public-url https://skill.example.com` |
|
||||
| `--version <tag>` | 指定镜像版本 | `--version v0.2.0` |
|
||||
| `--version <tag>` | 指定镜像版本 | `--version v0.2.25` |
|
||||
| `--ref <git-ref>` | 指定部署文件的 Git ref(GitHub raw 模式) | `--ref v0.2.25` |
|
||||
| `--aliyun` | 使用阿里云镜像(国内推荐) | `--aliyun` |
|
||||
| `--home <dir>` | 指定运行时目录 | `--home /opt/skillhub` |
|
||||
| `--no-scanner` | 禁用安全扫描服务 | `--no-scanner` |
|
||||
|
||||
`--version` 选择镜像标签,不固定部署文件;部署文件默认取自 `main`。
|
||||
如需同时固定安装脚本、Compose 清单、环境模板及应用镜像标签,可使用已发布的 ref 和标签:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/iflytek/skillhub/v0.2.25/scripts/runtime.sh | sh -s -- up --ref v0.2.25 --version v0.2.25 --home /opt/skillhub --public-url https://skillhub.your-company.com
|
||||
```
|
||||
|
||||
此例需要能访问 GitHub raw。`--aliyun` 会改用 OSS 根目录下载部署文件,
|
||||
此时 `--ref` 不会选择版本子目录;自定义 `SKILLHUB_RAW_BASE` 也优先于按 Git ref 生成的地址,
|
||||
不能把这两种情况称为已通过 `--ref` 固定部署文件。
|
||||
脚本保留已有 `.env.release`,请另行记录其中配置及显式镜像覆盖值。
|
||||
固定应用镜像标签不等于冻结全部依赖镜像,也不能代替数据库备份。
|
||||
|
||||
> **重要**:生产环境请务必配置 `--public-url`,确保 CLI 安装命令和 Agent 设置指引显示正确的地址。
|
||||
|
||||
如果通过 `/skillhub/` 这类子路径对外发布,需要让公网地址和前端基础路径保持一致。
|
||||
|
|
|
|||
|
|
@ -95,6 +95,23 @@ Public API 的可见性规则:
|
|||
- 若 `latest_version_id = null`,即使 `visibility=PUBLIC`,skill 也不会对外公开,只有 owner 可访问
|
||||
- `hidden=true` 时,普通访客不可访问;仅 owner 或该 namespace 的 `ADMIN` / `OWNER` 可访问
|
||||
|
||||
### 技能详情的公共页面地址
|
||||
|
||||
`GET /api/v1/skills/{namespace}/{slug}` 的 `data.webUrl` 是可空的 URI 字符串,
|
||||
指向该技能的 SkillHub 网页详情,而非作者自定义外站地址,也不是 CLI `resolve` 响应字段。
|
||||
它只取自部署配置 `skillhub.public.base-url`(环境变量 `SKILLHUB_PUBLIC_BASE_URL`),
|
||||
不根据请求的 Host 或转发头推测地址,不改变技能原有访问权限。
|
||||
|
||||
- 有效配置须为带主机的 HTTP(S) 地址,不能包含用户凭据、查询参数或片段。
|
||||
- 配置缺省、空白或不符合上述校验时返回 `null`;客户端应隐藏该跳转入口,不拼造链接。
|
||||
- 保留公开地址中的子路径,去掉结尾斜杠,再追加 `/space/{namespace}/{slug}`。
|
||||
两个路径段分别按 UTF-8 URL 编码,空格为 `%20`,段内斜杠为 `%2F`。
|
||||
- 例如公开地址 `https://skills.example.com/portal/` 和技能 `team/demo`,
|
||||
返回 `https://skills.example.com/portal/space/team/demo`。
|
||||
|
||||
实现与边界测试:[SkillWebUrls](../server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillWebUrls.java)、
|
||||
[SkillWebUrlsTest](../server/skillhub-app/src/test/java/com/iflytek/skillhub/service/SkillWebUrlsTest.java)。
|
||||
|
||||
`GET /api/v1/skills/{namespace}/{slug}/versions/{version}` 的 `data` 字段除版本基础信息外,还必须包含:
|
||||
|
||||
- `parsedMetadataJson`:`SKILL.md` frontmatter 的完整 JSON 序列化结果
|
||||
|
|
|
|||
|
|
@ -18,6 +18,7 @@ Use the documentation site for user workflows, repository guides for engineering
|
|||
|
||||
- [Docker deployment and upgrades](skillhub/en/guide/deployment.md) / [中文](skillhub/guide/deployment.md)
|
||||
- [Kubernetes](skillhub/en/guide/kubernetes.md) / [中文](skillhub/guide/kubernetes.md)
|
||||
- [Optional frontend analytics](skillhub/en/guide/frontend-analytics.md) / [前端动作统计](skillhub/guide/frontend-analytics.md)
|
||||
- [Deployment reference](09-deployment.md), [object storage](object-storage.md), [SMTP and password reset](19-smtp-password-reset-email-setup.md)
|
||||
- [Security scanning](security-scanning.md), [observability](observability-developer-guide.md), [private SSO integration](12-private-sso-integration-playbook.md)
|
||||
|
||||
|
|
|
|||
|
|
@ -1,10 +1,13 @@
|
|||
# 前端动作统计接入指南
|
||||
|
||||
<!-- #region analytics-body -->
|
||||
## 1. 先了解边界
|
||||
|
||||
当前是手动、本地演示接入,生产一键配置尚未交付;新方案合并并验证后再更新本指南。
|
||||
|
||||
SkillHub 页面只提供被动的 `data-analytics-id` 标签,默认不采集、不加载统计 SDK、不发送事件。可选 helper 把允许的原生交互转换成 `{ id, event }`,再交给部署方选择的 adapter。点击下载只表示下载意图,不表示下载、安装成功;提交发布也不表示发布成功。部署方负责授权、隐私合规、保留期限和平台安全。
|
||||
|
||||
本文对应 PR-1(#1010)的手工接入示例,不是产品内置开关。仅通过 Docker/Compose 或 Helm 配置开启、默认关闭和按需加载的能力计划在 PR-2 交付,见 [OpenSpec 变更](../openspec/changes/add-configurable-frontend-analytics/proposal.md)。Issue #989 要等 PR-2 完成并验证后才关闭。精确接口、事件边界和隐私约束以[英文契约](frontend-analytics.md)为准。
|
||||
本文对应 PR-1(#1010)的手工接入示例,不是产品内置开关。仅通过 Docker/Compose 或 Helm 配置开启、默认关闭和按需加载的能力计划在 PR-2 交付,见 [OpenSpec 变更](https://github.com/iflytek/skillhub/blob/main/openspec/changes/add-configurable-frontend-analytics/proposal.md)。Issue #989 要等 PR-2 完成并验证后才关闭。精确接口、事件边界和隐私约束以[英文契约][analytics-reference]为准。
|
||||
|
||||
## 2. 选择接入路径
|
||||
|
||||
|
|
@ -12,8 +15,8 @@ SkillHub 页面只提供被动的 `data-analytics-id` 标签,默认不采集
|
|||
|
||||
先确认平台接收地址、公开站点标识、授权策略和 CSP。不要把平台管理密钥放到浏览器。平台不受支持时,需要部署方编写自己的 adapter;当前版本不能只填平台名字就接入任意平台。
|
||||
|
||||
1. 复用 [helper](examples/analytics/observe/v1/skillhub-intents.mjs),不要修改业务页面或引入厂商 SDK。
|
||||
2. 参照 [Umami adapter](examples/analytics/observe/v1/umami-adapter.mjs)实现 `send(intent) -> Promise<void>` 和 `stop()`。send 必须消化同步异常和异步拒绝,不向页面抛错;stop 后不能再派发请求,已经开始的 fetch 无法撤回。
|
||||
1. 复用 [helper](https://github.com/iflytek/skillhub/blob/main/docs/examples/analytics/observe/v1/skillhub-intents.mjs),不要修改业务页面或引入厂商 SDK。
|
||||
2. 参照 [Umami adapter](https://github.com/iflytek/skillhub/blob/main/docs/examples/analytics/observe/v1/umami-adapter.mjs)实现 `send(intent) -> Promise<void>` 和 `stop()`。send 必须消化同步异常和异步拒绝,不向页面抛错;stop 后不能再派发请求,已经开始的 fetch 无法撤回。
|
||||
3. 由 adapter 验证平台参数、清洗最终发送字段、管理 SDK 加载和超时。不要只清洗 helper 回调后就信任 SDK 自动附加的 URL、标题或身份字段。
|
||||
4. 在部署方入口中连接 helper 与 adapter,只有策略允许时才初始化:
|
||||
|
||||
|
|
@ -33,18 +36,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 路径。
|
||||
|
|
@ -61,9 +66,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 入口验收注入。
|
||||
|
|
@ -122,7 +127,7 @@ node web/scripts/analytics-manifest.mjs --write
|
|||
node web/scripts/analytics-manifest.mjs
|
||||
```
|
||||
|
||||
审核生成的 [manifest](frontend-analytics-manifest.json) 差异和原生交互测试。部署方再加一条规则即可。ID 必须匹配 `^[a-z]+(?:\.[a-z]+){2,}$`:至少三段小写字母,不含数字、下划线或资源信息。已有 ID 含义冻结,不能把用户、技能名、版本、路径拼进去。manifest 是版本清单,不是运行时封闭枚举。
|
||||
审核生成的 [manifest](https://github.com/iflytek/skillhub/blob/main/docs/frontend-analytics-manifest.json) 差异和原生交互测试。部署方再加一条规则即可。ID 必须匹配 `^[a-z]+(?:\.[a-z]+){2,}$`:至少三段小写字母,不含数字、下划线或资源信息。已有 ID 含义冻结,不能把用户、技能名、版本、路径拼进去。manifest 是版本清单,不是运行时封闭枚举。
|
||||
|
||||
## 4. 部署、子路径和 CSP
|
||||
|
||||
|
|
@ -132,7 +137,7 @@ edge 仅在 UI HTML 注入一个延迟执行的 module,不改变 API、登录
|
|||
|
||||
根路径演示的 CSP 需要允许同源外部 module 和同源连接。保留原有 CSP;nonce-only 或 strict-dynamic 策略不能只靠同源满足。需要部署方协调每响应 nonce 或已批准的 hash/SRI;做不到就不要启用。不要加 unsafe-inline、unsafe-eval 或通配符。还要保留原安全头,注意 Nginx add_header 的 location 继承规则。
|
||||
|
||||
`/skillhub/` 等子路径不是只改一个 URL。先按正常部署方式配置 `SKILLHUB_WEB_BASE_PATH=/skillhub/` 和匹配的同源 API base,再同时调整 UI location、无尾斜线重定向、旁路正则、模块目录/注入 src、两个 Umami 精确端点和 adapter prefix。edge 到 Web 的 proxy_pass 不带尾斜线,保留原 URI,不能再次重写。逐项配置见[英文契约的子路径映射](frontend-analytics.md#supported-sub-path-mapping)。OAuth、公网 HTTPS 和资源地址仍遵守原部署要求。
|
||||
`/skillhub/` 等子路径不是只改一个 URL。先按正常部署方式配置 `SKILLHUB_WEB_BASE_PATH=/skillhub/` 和匹配的同源 API base,再同时调整 UI location、无尾斜线重定向、旁路正则、模块目录/注入 src、两个 Umami 精确端点和 adapter prefix。edge 到 Web 的 proxy_pass 不带尾斜线,保留原 URI,不能再次重写。逐项配置见[英文契约的子路径映射][analytics-subpaths]。OAuth、公网 HTTPS 和资源地址仍遵守原部署要求。
|
||||
|
||||
## 5. 验收:照这个顺序检查
|
||||
|
||||
|
|
@ -160,13 +165,31 @@ window.skillhubAnalytics.stop()
|
|||
|
||||
stop 不能撤回已开始的 fetch。重新获准后才可调用 start();同一个 root 重复初始化保留第一次规则和回调,修改规则需要先 stop 再初始化。
|
||||
|
||||
7. 将入口恢复 `enabled: false`,重新创建 edge。保持「Disable cache」勾选(或换一个新的无痕窗口),刷新页面后再搜索:不得加载 script.js、产生采集回调或 send。完全不注入时也应零采集。最后在隔离演示中停止 Umami,再打开新页面搜索和打开技能卡片,应仍正常,无统计依赖导致的页面错误:
|
||||
7. **关闭态独立验收**:将入口恢复 `enabled: false`,重新创建 edge:
|
||||
|
||||
```sh
|
||||
docker compose -f docs/examples/analytics/compose.yaml stop umami
|
||||
docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml up -d --no-deps --force-recreate edge
|
||||
```
|
||||
|
||||
验收后如需继续演示,使用上面的 up 命令恢复。不要为了测试停止共享平台或生产服务。
|
||||
保持「Disable cache」勾选(或换一个新的无痕窗口),刷新页面后搜索:不得加载 script.js、产生采集回调或 send,搜索与技能卡片仍正常。完全不注入时也应零采集。这一步不验证启用态的故障隔离。
|
||||
|
||||
8. **启用态依赖故障验收**:仅在上述隔离演示中,将入口重新设为 `enabled: true`,保留第 2 节创建的有效网站 UUID,并确认当前授权允许采集;按第 7 步重新创建 edge,禁用缓存并刷新。先重复第 3~5 步,确认一次测试动作确实入库,作为故障前对照。不要为了测试停止共享平台或生产服务。
|
||||
|
||||
保持入口启用和授权有效,仅停止演示 Umami:
|
||||
|
||||
```sh
|
||||
docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml stop umami
|
||||
```
|
||||
|
||||
在已加载 SDK 的页面再次搜索,应观察到采集请求失败,同时搜索结果和技能卡片仍正常。再新开一个禁用缓存的页面:SDK 请求应失败,但业务仍可用,不能出现统计异常导致的未捕获页面错误。记录失败请求和业务结果;不要把关闭态的零请求当成故障隔离通过,也不要把失败请求当作成功入库。
|
||||
|
||||
9. **恢复或清理**:继续演示时执行:
|
||||
|
||||
```sh
|
||||
docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml start umami
|
||||
```
|
||||
|
||||
等待 `http://localhost:8300` 恢复可用后,禁用缓存并刷新 edge 页面,再执行一次新动作,确认请求成功且新事件入库。原页面的 SDK 初始化失败不会保证自动恢复,故障期间丢失的事件也不保证补发。结束演示则按第 7 节关闭采集、恢复入口文件,并仅清理该演示项目;不要删除现有 SkillHub 或共享平台的数据。
|
||||
|
||||
## 6. 故障排查
|
||||
|
||||
|
|
@ -189,7 +212,7 @@ docker compose -f docs/examples/analytics/compose.yaml stop 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
|
||||
```
|
||||
|
||||
限制必须一起评估:
|
||||
|
|
@ -197,4 +220,9 @@ docker compose -f docs/examples/analytics/compose.yaml down -v
|
|||
- 尽力发送,无重试、无持久队列,可能少计。SDK 加载期最多在内存暂存 20 条,默认最多等三秒;超额、失败、超时或 stop 都丢弃。已就绪发送彼此独立,不因一个请求挂起而阻塞后续动作。
|
||||
- 示例固定 Umami 3.4.1。stop 的派发保护依赖此版本在 fetch 前同步序列化的顺序,升级必须重跑适配器测试和真实浏览器验收;不要同时加载第二个 Umami tracker。
|
||||
- JSON 字段少不等于匿名传输。IP、User-Agent、Origin 仍到平台;SDK 还带网站、实际 hostname 和后续会话 cache 头。edge 去掉采集代理的 Cookie、Authorization、Referer,并使用 no-referrer。Umami 仍可能据传输元数据推导浏览器、系统、设备、地域和会话。
|
||||
- SDK 在清洗前仍会在页面内读取标题、URL、referrer 和自身 localStorage 开关;通用 helper 不读取这些内容。平台日志、数据保留和权限需另审计,详见[隐私契约](frontend-analytics.md#privacy-and-integration-modes)。
|
||||
- SDK 在清洗前仍会在页面内读取标题、URL、referrer 和自身 localStorage 开关;通用 helper 不读取这些内容。平台日志、数据保留和权限需另审计,详见[隐私契约][analytics-privacy]。
|
||||
<!-- #endregion analytics-body -->
|
||||
|
||||
[analytics-reference]: frontend-analytics.md
|
||||
[analytics-subpaths]: frontend-analytics.md#supported-sub-path-mapping
|
||||
[analytics-privacy]: frontend-analytics.md#privacy-and-integration-modes
|
||||
|
|
|
|||
|
|
@ -1,9 +1,12 @@
|
|||
# Passive frontend analytics attributes
|
||||
|
||||
For step-by-step setup, see the [Chinese integration guide](frontend-analytics-integration.md).
|
||||
<!-- #region analytics-body -->
|
||||
For step-by-step setup, see the [Chinese integration guide][analytics-guide].
|
||||
This document is the English contract reference. Configuration-only deployment is
|
||||
planned in [PR-2](../openspec/changes/add-configurable-frontend-analytics/proposal.md);
|
||||
the current examples remain deployment-owned and opt-in.
|
||||
planned in [PR-2](https://github.com/iflytek/skillhub/blob/main/openspec/changes/add-configurable-frontend-analytics/proposal.md);
|
||||
the current examples remain deployment-owned and opt-in. They describe a manual,
|
||||
local demo integration; production one-click configuration has not been delivered.
|
||||
The guide will be updated after the new flow is merged and validated.
|
||||
|
||||
SkillHub exposes semantic HTML attributes for separately maintained, optional
|
||||
collectors. It does not collect or send analytics by default. There is no SDK,
|
||||
|
|
@ -57,7 +60,7 @@ The source inventory covers these domains:
|
|||
- Notifications/preferences, account/profile/security/token flows, login,
|
||||
registration/reset/device/CLI authorization, administration and global navigation.
|
||||
|
||||
[The generated manifest](frontend-analytics-manifest.json) is the authoritative
|
||||
[The generated manifest](https://github.com/iflytek/skillhub/blob/main/docs/frontend-analytics-manifest.json) is the authoritative
|
||||
source index: registered routes and their implementations, literal JSX sites,
|
||||
conditional values, static navigation definitions and forwarding sites. Counts
|
||||
are recomputed from the TypeScript AST; they are not quotas. Unique IDs are
|
||||
|
|
@ -166,7 +169,7 @@ incident. Vendor credentials and ingestion endpoints belong outside core.
|
|||
|
||||
## Configure rules and add tags
|
||||
|
||||
[The vendor-neutral helper](examples/analytics/observe/v1/skillhub-intents.mjs)
|
||||
[The vendor-neutral helper](https://github.com/iflytek/skillhub/blob/main/docs/examples/analytics/observe/v1/skillhub-intents.mjs)
|
||||
exports `observeSkillhubIntents({ root, rules, onIntent })`, frozen `DEFAULT_RULES`
|
||||
(the original 12 categories), and pure `resolveRules(rules)`:
|
||||
|
||||
|
|
@ -220,13 +223,15 @@ example is not present in the `web/` Docker build context.
|
|||
|
||||
## Connect a platform: local Umami v3.4.1 demo
|
||||
|
||||
[The Compose example](examples/analytics/compose.yaml) runs Umami v3.4.1 (MIT),
|
||||
[The Compose example](https://github.com/iflytek/skillhub/blob/main/docs/examples/analytics/compose.yaml) runs Umami v3.4.1 (MIT),
|
||||
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
|
||||
|
|
@ -242,13 +247,13 @@ an isolated local Docker environment with available network pools. Open
|
|||
`http://localhost:8300` for local setup only. Umami's default `admin` / `umami`
|
||||
credentials, the public DB password and app secret are DEMO ONLY: change them.
|
||||
Create a synthetic website in Umami, copy its UUID into
|
||||
[`observer.mjs`](examples/analytics/observe/v1/observer.mjs), then explicitly change
|
||||
[`observer.mjs`](https://github.com/iflytek/skillhub/blob/main/docs/examples/analytics/observe/v1/observer.mjs), then explicitly change
|
||||
`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`](examples/analytics/observe/v1/umami-adapter.mjs) is the only
|
||||
[`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
|
||||
v3.4.1 installs no pageview, history hook, click listener or performance observer.
|
||||
`data-host-url` is the same-origin `/_skillhub-umami` prefix, and
|
||||
|
|
@ -315,7 +320,7 @@ HTML is the deployment rollback; default SkillHub never loads any of this.
|
|||
|
||||
Prefer a separately maintained same-origin HTTPS module, optionally inserted by
|
||||
Nginx `sub_filter`, not an app entrypoint modification. Start with
|
||||
[the opt-in edge template](examples/analytics/nginx.conf). It is not loaded by the
|
||||
[the opt-in edge template](https://github.com/iflytek/skillhub/blob/main/docs/examples/analytics/nginx.conf). It is not loaded by the
|
||||
product. Compose substitutes only the two upstream host:port variables. Publish
|
||||
its HTTP listener on loopback behind your HTTPS terminator. Serve the supplied
|
||||
`observer.mjs`, helper and adapter outside the app bundle; only enable the entry
|
||||
|
|
@ -390,3 +395,6 @@ configuration, reload through the normal deployment procedure, and purge cached
|
|||
HTML. Existing cached versioned JS can remain temporarily but must not be referenced
|
||||
or initialized. Verify new HTML has no script, no callback/reporting occurs and
|
||||
SkillHub remains usable. This document does not authorize production changes.
|
||||
<!-- #endregion analytics-body -->
|
||||
|
||||
[analytics-guide]: frontend-analytics-integration.md
|
||||
|
|
|
|||
|
|
@ -81,6 +81,15 @@ Scanner-side optional environment variables:
|
|||
- `SKILLHUB_SCANNER_HARD_TIMEOUT_SECONDS` (default `930`)
|
||||
- `SKILLHUB_SCANNER_MAX_UPLOAD_SIZE_BYTES` (default `110100480`, or 105 MiB)
|
||||
|
||||
For `SKILLHUB_SCANNER_MAX_UPLOAD_SIZE_BYTES`, prefer an integer byte value such as
|
||||
`110100480` (105 MiB). The scanner also accepts scientific notation when the value
|
||||
is an exact finite integer, for example `1.1010048e+08`; this accommodates Helm
|
||||
serialization. Fractional values, non-finite values and invalid text are rejected
|
||||
at scanner startup rather than silently rounded. Zero and negative integer values
|
||||
are clamped to `1` byte, not interpreted as unlimited. Positive scientific-notation
|
||||
values must also fit the platform's supported integer range. This scanner-side limit does
|
||||
not override separate proxy or server upload limits.
|
||||
|
||||
If the LLM variables are absent, the scanner should still run with non-LLM analyzers.
|
||||
The default timeout ordering is server read timeout (900 seconds), scanner hard timeout
|
||||
(930 seconds), then pending-message reclaim (960 seconds). A hard timeout exits the scanner process
|
||||
|
|
|
|||
|
|
@ -70,6 +70,7 @@ export default defineConfig({
|
|||
items: [
|
||||
{ text: 'Docker 部署', link: '/guide/deployment' },
|
||||
{ text: 'Kubernetes 部署', link: '/guide/kubernetes' },
|
||||
{ text: '前端动作统计', link: '/guide/frontend-analytics' },
|
||||
{ text: '技能头像与审核', link: '/guide/skill-avatars' },
|
||||
],
|
||||
},
|
||||
|
|
@ -144,6 +145,7 @@ export default defineConfig({
|
|||
items: [
|
||||
{ text: 'Deploy with Docker', link: '/en/guide/deployment' },
|
||||
{ text: 'Deploy on Kubernetes', link: '/en/guide/kubernetes' },
|
||||
{ text: 'Frontend analytics', link: '/en/guide/frontend-analytics' },
|
||||
{ text: 'Skill avatars and moderation', link: '/en/guide/skill-avatars' },
|
||||
],
|
||||
},
|
||||
|
|
|
|||
12
docs/skillhub/en/guide/frontend-analytics-guide.md
Normal file
12
docs/skillhub/en/guide/frontend-analytics-guide.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
# Detailed setup (Chinese)
|
||||
|
||||
The detailed setup instructions below are currently available in Chinese. Validate the example in an isolated environment first.
|
||||
|
||||
[← Back to overview](./frontend-analytics.md)
|
||||
|
||||
<!-- @include: ../../../frontend-analytics-integration.md#analytics-body -->
|
||||
|
||||
[analytics-guide]: ./frontend-analytics-guide.md
|
||||
[analytics-reference]: ./frontend-analytics-reference.md
|
||||
[analytics-subpaths]: ./frontend-analytics-reference.md#supported-sub-path-mapping
|
||||
[analytics-privacy]: ./frontend-analytics-reference.md#privacy-and-integration-modes
|
||||
12
docs/skillhub/en/guide/frontend-analytics-reference.md
Normal file
12
docs/skillhub/en/guide/frontend-analytics-reference.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
# Interface and privacy contract
|
||||
|
||||
This contract is in English. Detailed setup instructions are currently available in Chinese.
|
||||
|
||||
[← Back to overview](./frontend-analytics.md)
|
||||
|
||||
<!-- @include: ../../../frontend-analytics.md#analytics-body -->
|
||||
|
||||
[analytics-guide]: ./frontend-analytics-guide.md
|
||||
[analytics-reference]: ./frontend-analytics-reference.md
|
||||
[analytics-subpaths]: ./frontend-analytics-reference.md#supported-sub-path-mapping
|
||||
[analytics-privacy]: ./frontend-analytics-reference.md#privacy-and-integration-modes
|
||||
125
docs/skillhub/en/guide/frontend-analytics.md
Normal file
125
docs/skillhub/en/guide/frontend-analytics.md
Normal file
|
|
@ -0,0 +1,125 @@
|
|||
# Frontend analytics: first local setup
|
||||
|
||||
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.
|
||||
|
||||
::: warning Current support scope
|
||||
This page covers the delivered manual, local demo integration, not a production one-click deployment. **Production one-click configuration has not been delivered.** The new Docker/Compose and Helm configuration flow is still in progress; this page will be updated after it is merged and validated.
|
||||
:::
|
||||
|
||||
## 1. Prepare Web and the example files
|
||||
|
||||
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.
|
||||
|
||||
| Address / port | Purpose |
|
||||
| --- | --- |
|
||||
| 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 |
|
||||
|
||||
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:
|
||||
|
||||
```sh
|
||||
git clone --depth 1 --branch v0.2.25 https://github.com/iflytek/skillhub.git skillhub-analytics-demo
|
||||
cd skillhub-analytics-demo
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
|
@ -37,6 +37,7 @@ Read these guides when you need to run your own registry. Choose a deployment me
|
|||
|
||||
- [Deploy with Docker](./deployment.md): installation, configuration, upgrades, and backups.
|
||||
- [Deploy on Kubernetes](./kubernetes.md): cluster and Helm deployment.
|
||||
- [Frontend analytics](./frontend-analytics.md): optional manual integration, consent, and failure acceptance.
|
||||
- [Skill avatars and moderation](./skill-avatars.md): administrator configuration for image moderation providers.
|
||||
|
||||
## Develop and integrate
|
||||
|
|
|
|||
12
docs/skillhub/guide/frontend-analytics-guide.md
Normal file
12
docs/skillhub/guide/frontend-analytics-guide.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
# 详细接入操作(中文)
|
||||
|
||||
以下步骤适用于当前手动接入示例,请先在隔离环境验证。
|
||||
|
||||
[← 返回接入概览](./frontend-analytics.md)
|
||||
|
||||
<!-- @include: ../../frontend-analytics-integration.md#analytics-body -->
|
||||
|
||||
[analytics-guide]: ./frontend-analytics-guide.md
|
||||
[analytics-reference]: ./frontend-analytics-reference.md
|
||||
[analytics-subpaths]: ./frontend-analytics-reference.md#supported-sub-path-mapping
|
||||
[analytics-privacy]: ./frontend-analytics-reference.md#privacy-and-integration-modes
|
||||
12
docs/skillhub/guide/frontend-analytics-reference.md
Normal file
12
docs/skillhub/guide/frontend-analytics-reference.md
Normal file
|
|
@ -0,0 +1,12 @@
|
|||
# 接口与隐私契约(英文)
|
||||
|
||||
本页契约正文为英文,详细操作步骤见中文指南。
|
||||
|
||||
[← 返回接入概览](./frontend-analytics.md)
|
||||
|
||||
<!-- @include: ../../frontend-analytics.md#analytics-body -->
|
||||
|
||||
[analytics-guide]: ./frontend-analytics-guide.md
|
||||
[analytics-reference]: ./frontend-analytics-reference.md
|
||||
[analytics-subpaths]: ./frontend-analytics-reference.md#supported-sub-path-mapping
|
||||
[analytics-privacy]: ./frontend-analytics-reference.md#privacy-and-integration-modes
|
||||
124
docs/skillhub/guide/frontend-analytics.md
Normal file
124
docs/skillhub/guide/frontend-analytics.md
Normal file
|
|
@ -0,0 +1,124 @@
|
|||
# 前端动作统计:首次本地接入
|
||||
|
||||
本文带你在已有 SkillHub 前增加一个本地演示入口,连接 Umami 并确认事件入库。SkillHub 默认不采集。
|
||||
|
||||
::: warning 当前支持范围
|
||||
本文介绍已交付的手动、本地演示接入,不是生产一键部署指南。**生产一键配置接入尚未交付**;通过 Docker/Compose 或 Helm 配置开启的新方案仍在推进,合并并完成验证后再更新本页。
|
||||
:::
|
||||
|
||||
## 1. 准备已有 Web 和示例文件
|
||||
|
||||
先确认 SkillHub Web 可以正常打开、搜索。尚未部署?先完成 [Docker 部署](./deployment.md),再回来继续。本例适用于本机根路径部署;子路径、生产代理与 CSP 请用[详细指南](./frontend-analytics-guide.md)。需要 Docker、Compose 和 Git,且 8300、8081 未被占用。
|
||||
|
||||
| 地址/端口 | 用途 |
|
||||
| --- | --- |
|
||||
| 原 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 地址。
|
||||
|
||||
## 常见问题
|
||||
|
||||
| 现象 | 先检查 |
|
||||
| --- | --- |
|
||||
| 找不到 Compose 文件 | 当前目录应是克隆仓库根目录,而非 runtime 安装目录 |
|
||||
| 8300/8081 无法启动 | 本机端口占用;看 `docker compose -p skillhub-analytics-demo -f docs/examples/analytics/compose.yaml logs` |
|
||||
| 8081 返回 502 | Web 端口、容器可达监听和防火墙;不要填后端端口 |
|
||||
| 没有采集请求 | 是否访问 8081,入口是否启用/获得授权,修改后是否重建及禁用缓存刷新 |
|
||||
| 请求失败或平台无数据 | UUID 是否正确、Umami 是否就绪、时间范围是否匹配;检查 Network 响应 |
|
||||
|
||||
进阶:[完整操作指南](./frontend-analytics-guide.md) · [接口与隐私契约(英文)](./frontend-analytics-reference.md)。字段精简不等于匿名传输:IP、User-Agent 等仍可能到达平台,保留期限、访问控制和合规由部署方负责。
|
||||
|
|
@ -37,6 +37,7 @@
|
|||
|
||||
- [Docker 部署](./deployment.md):安装、配置、升级和备份。
|
||||
- [Kubernetes 部署](./kubernetes.md):集群和 Helm 部署。
|
||||
- [前端动作统计](./frontend-analytics.md):可选手动接入、授权与故障验收。
|
||||
- [技能头像与审核](./skill-avatars.md):管理员配置图片审核服务。
|
||||
|
||||
## 开发与集成
|
||||
|
|
|
|||
|
|
@ -50,6 +50,8 @@ class PageParser(HTMLParser):
|
|||
self.empty_table_count = 0
|
||||
self.ids: set[str] = set()
|
||||
self.duplicate_ids: set[str] = set()
|
||||
self.skip_targets: set[str] = set()
|
||||
self.main_ids: set[str] = set()
|
||||
self.external_assets: list[str] = []
|
||||
self.non_content_depth = 0
|
||||
|
||||
|
|
@ -70,6 +72,12 @@ class PageParser(HTMLParser):
|
|||
if element_id in self.ids:
|
||||
self.duplicate_ids.add(element_id)
|
||||
self.ids.add(element_id)
|
||||
if tag == "main" and element_id:
|
||||
self.main_ids.add(element_id)
|
||||
if tag == "a" and "skip-link" in (values.get("class") or "").split():
|
||||
href = values.get("href") or ""
|
||||
if href.startswith("#"):
|
||||
self.skip_targets.add(href[1:])
|
||||
if tag == "h1":
|
||||
self.h1_count += 1
|
||||
if values.get("role") == "tab":
|
||||
|
|
@ -237,6 +245,9 @@ def validate(root: Path) -> list[str]:
|
|||
)
|
||||
if empty_panels:
|
||||
errors.append(f"{index_path}: panels without modules: {empty_panels}")
|
||||
for target in sorted(parser.skip_targets):
|
||||
if target not in parser.main_ids:
|
||||
errors.append(f"{index_path}: skip link target #{target} must identify main")
|
||||
if parser.duplicate_ids:
|
||||
errors.append(f"{index_path}: duplicate ids: {sorted(parser.duplicate_ids)}")
|
||||
if parser.external_assets:
|
||||
|
|
|
|||
|
|
@ -1246,7 +1246,7 @@ footer {
|
|||
</div>
|
||||
</div>
|
||||
|
||||
<main>
|
||||
<main id="report-content" tabindex="-1">
|
||||
<div class="tab-panel active" id="panel-overview" role="tabpanel" tabindex="0" aria-labelledby="tab-overview" data-panel="overview">
|
||||
<div class="panel-intro"><p>先看仓库规模和协作流转,再看已经交付与仍待验证的内容。</p><p>事件统计覆盖完整的 7 天周期;库存与开放队列取采集快照。</p></div>
|
||||
<section class="report-section" data-module="repository-summary" aria-labelledby="repo-title"><h2 id="repo-title">一、仓库关键信息</h2>
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
{
|
||||
"repository": "https://github.com/XiaoSeS/skillhub-weekly.git",
|
||||
"commit": "6c1e530394585fa11ac9ccab370c6b1b28dc0563"
|
||||
"commit": "13a95bb287e341150e5bd95461a2284a7daf6576"
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue