AngusInsight 是什么：产品与用户行为分析-平芜编程栈

AngusInsight 是一个用户行为分析平台，浏览器采集，数据留在自己的库。浏览器 SDK 把页面浏览、自定义事件和前端错误送到这次安装的采集地址，写入你自己的数据库，再在控制台看渠道、漏斗、路径和错误。数据可以留在内网。

解决的主要问题

行为要先送出这次安装，才能看漏斗和路径。浏览器里的 SDK 把page_view、自定义事件和错误送到https://insight.<域名>/pubapi/v1/collect，写入这次安装的库。看板在同一套登录里打开。事件按appCode分开，没有跨应用拼在一起的总表。
页面已经能打开，还不知道有没有人进来。在「应用」里创建一个应用，拿到appCode和以pub_开头的appKey。createAnalytics填上这三项和采集地址，再调用init()。autoTrack.pageView没有关掉时，这次初始化会打出一条page_view。到侧栏「实时」里核对第一条。自定义事件和convert()以后再加。appKey会打进前端包，不要写进仓库。
投放链接带了参数，看板上仍是直接访问。事件写入时，按「管理 → 规则」给每条事件算出channelCode。规则看 UTM、来源域名和常见点击 ID。新租户会带一批默认规则，包含百度、小红书等，默认规则不能删除。优先级数字大的先匹配。对不上的记成direct。控制台没有首次触达、末次触达的切换。
注册、试用、付费掉在哪一步，和当天的前端报错对不上。漏斗在「漏斗」里按事件名排 1 到 10 步，按时间顺序匹配，步骤之间可以夹着别的事件。配好的步骤可以存成模板。路径在「路径」里画同一会话里相邻的page_view，一次请求大约 40 条边。错误在「错误」里按指纹汇总，点进去是这条指纹的详情。漏斗不能按步骤属性过滤，也不能从流失的那一步点进某一个人。

看板说明的是合计。改页面还是改需求，由产品和研发决定。这里没有录屏，也没有 A/B。漏斗和错误的数字不能当成发布门禁。会话存在sessionStorage里，关掉标签页就换新会话。当前 SDK 没有「30 分钟无操作就拆会话」。

主要功能

登录后的第一屏是「数据总览」，用来看访问量、趋势、主要渠道和热门页面。

「实时」是另一页。窗口可以在 5 到 60 分钟之间滑动，大约 15 秒轮询一次。

采集写进自己的库。浏览器包是@anguskit/angusinsight-sdk，当前手册写的版本是1.0.1。必填是appCode、appKey、endpoint。init()之后，页面浏览默认会打一次。SPA 若在路由变化时再调pageView()，应把autoTrack.pageView设为false，否则同一次路由会打出两条。autoTrack.error默认开启，捕获脚本错误、未处理的 Promise 拒绝和资源加载失败。批量上报默认 20 条或 5 秒一次。AES 载荷加密只在 HTTPS 或localhost上可用。纯 HTTP 仍会上报，载荷是明文。

渠道按规则打码。「渠道」按写入时的channelCode汇总。「活动」按utm_campaign对比。SDK 在pageView()时读取当前 URL 上的 UTM，放进事件的归因字段，不用在业务代码里再传一遍。规则在「管理 → 规则」里新建：填channelCode、匹配方式和优先级，然后保存。

漏斗、路径和人。侧栏是「漏斗」，页面标题是「转化漏斗」。左侧是步骤列表，默认示例是page_view、click、conversion，按实际上报的事件名改。点「添加步骤」，最多 10 步，至少留 1 步，再点「运行分析」。点「保存为模板」之后，下面的列表可以加载、删除，或用 JSON 导入导出。换应用或时间范围后，已有步骤会再算一遍。匹配是按用户、按时间的顺序：下一步必须发生在上一步匹配到的事件之后。转化率是这一步人数除以第一步人数。控制台只有这一种算法，没有严格、宽松、无序的切换。「路径」是会话内相邻页面浏览的桑基图，长尾不在这 40 条边里。对不上时可以点「重建预聚合」。「用户」里能看访客列表和时间线。匿名 ID 在localStorage，前缀是anon_。换设备或清掉站点数据之后，这条匿名历史对不上。identify({ subjectUserId })把当前设备绑到业务用户上，同一匿名 ID 只能绑一次。登出之后不要再调identify()，等到下次登录。

错误按指纹放在一起。同一条消息和堆栈模式合成一个指纹。列表上的次数和受影响用户是这条指纹的合计。详情路由是/errors/:fingerprint。同一指纹在 5 秒内连续触发，只上报一次。错误页标题是「错误监控」。「Source Map 管理」里按版本和压缩文件名上传，再点「还原源码位置」。没上传对应版本时，看到的是压缩后的行列号。跨域脚本若只收到Script error.，需要脚本带crossorigin，响应头允许来源。

其余明细。「页面」看路径排行。「地理」看地区分布。「租户」是被采集的业务租户。「事件」按时间和应用查单条记录。「访问」是页面浏览明细。筛选条按 UTC 日历日，可选 1 到 365 天。换一个appCode，就是另一份数据。

配置和成员。「管理」下面是应用、规则、埋点、任务、审计。埋点计划的路径是/tracking-plan，用来登记事件名和属性说明，分析页可以显示中文名。导入、导出在任务页的对应标签上，/imports和/exports会转到那里。「管理 → 成员」做邀请、分配本应用角色、暂停、恢复和移除。账号在门户里。手册写明控制台没有数据治理设置页，也没有告警规则页。

应用场景

活动页已经能打开，访问还要等外面的分析后台同步过来。在「应用」里创建这个站点对应的应用，把endpoint设成https://insight.<域名>/pubapi/v1/collect，只改协议时路径保持/pubapi/v1/collect。页面里createAnalytics填上appCode、appKey和这个地址，调用init()。autoTrack.pageView保持默认时，初始化会打出一条page_view。打开「实时」，窗口选在这几分钟里，核对这条事件。SPA 在路由里已经调用pageView()时，把自动页面浏览关掉，避免同一跳记两次。appKey用环境变量，不要提交进仓库。看到这条page_view就停在这里。自定义转化以后再加，不要把「实时里还没有转化」当成活动没有人看。
这次投放的链接写了utm_source，看板上这批访问仍落在direct。打开「管理 → 规则」，看默认规则和自己加的规则，哪一条的优先级先匹配到这条 URL 上的 UTM、来源域名或点击 ID。对不上就保持direct。活动对比走「活动」，按utm_campaign看，不在渠道规则里再造一个活动名。规则保存之后，只对之后写入的事件生效。这里停在事件级的channelCode。控制台没有首次触达、末次触达可以切换，也不能把历史访问改判到另一条规则上。
试用点下去之后，付费那一步少了一截，同一天脚本错误也在涨。在「漏斗」里把步骤改成实际上报的事件名，例如页面浏览、试用点击、付费转化，步数不超过 10。时间范围用页面上的筛选条。看每一步人数和相对上一步的流失，需要下次还用这组步骤时点「保存为模板」。同一天打开「错误」，按指纹看次数和受影响用户，先看落在这条路径上的那一类。个人点了什么，在「用户」里按角色查看。编辑器里的助手只能要回漏斗、路径和错误的合计，个人时间线不在可调用的工具里。数字说明掉在哪一步。改按钮还是改需求，由人决定。漏斗不能从流失步点进某一个人，空着的错误列表也不能当成这版前端没有问题。

一段脚本打出 page_view

浏览器采集是这篇的主路径。包名是@anguskit/angusinsight-sdk。下面这一段在autoTrack.pageView保持默认时，init()会打出一次page_view。步骤的其余配置见手册「Web SDK 接入」。

import{createAnalytics}from"@anguskit/angusinsight-sdk";constclient=createAnalytics({appCode:import.meta.env.VITE_INSIGHT_APP_CODE,appKey:import.meta.env.VITE_INSIGHT_APP_KEY,endpoint:import.meta.env.VITE_INSIGHT_ENDPOINT,});client.init();

采集地址写成https://insight.<域名>/pubapi/v1/collect。服务端渲染的页面不要在服务端调用createAnalytics()或init()，放到客户端挂载之后。privacy.blacklistFields里的字段会在上报前删掉，比较时忽略大小写以及_和-。respectDNT设为true时，浏览器不允许跟踪，init()不会开始采集。

怎么部署

单产品安装包解压后的目录名是AngusInsight-1.0.0。下载地址在安装页，主机是https://repo.anguskit.com。有 Docker 时用 Compose。没有 Docker 时用主机 ZIP。没有公网时按离线材料装。Helm 仍是预览。macOS 不要加sudo。Linux 要装到/opt/angus时，先把目录交给当前用户。

向导提示	推荐输入	说明
Install mode	回车	Compose。没有 Docker 时不要改这一项，改用主机 ZIP。
Access	`2`	用安装包里的反向代理，按子域名访问。回车会留在按端口访问。
Proxy engine	回车	Caddy。Let’s Encrypt 只配 Caddy。
TLS certificate	按证书选	没有默认值。`1`已有 PEM，`2`自签，`3`Let’s Encrypt，`4`只用 HTTP。
Database	回车	本机 MySQL 8。安装包里的 PostgreSQL 是`3`。已有库时 MySQL 选`2`，PostgreSQL 选`4`。
Install directory	回车	当前解压目录，也就是`$ANGUS_HOME`。
Public DNS name	根域名	只填根域名。填 IP、`localhost`或已经带`gm.`的名字，向导会停。
Admin password	至少 8 位	记下来。不要沿用安装说明里的公开默认口令。

本机 80 要空着。启用 HTTPS 时 443 也要空着。8808和8801是内部端口，反向代理转发，不必对公网开放。成功时输出里有doctor: OK和Install finished.。日志在$ANGUS_HOME/logs/install.log。装完先打开gm.<域名>，再打开insight.<域名>。选了 HTTPS 用https://，选了只用 HTTP 用http://，不要写成带:443。

接上编辑器里的助手

MCP 默认关着。管理员把angus.mcp.enabled设为true之后，助手才能连。令牌放在ANGUS_INSIGHT_TOKEN，不要写进仓库。网关地址是https://<gateway-host>/insight/mcp。私有化直连进程时是https://<insight-host>/mcp。只支持 stdio 的宿主用npx -y @anguskit/mcp --product insight转到同一个 HTTP 端点。Insight 只接受本产品签发的令牌（xcan_op）。拿 Tester 或其他产品的令牌会 401。未带身份时，服务端不返回工具列表。

{"mcpServers":{"angus-insight":{"url":"https://<gateway-host>/insight/mcp","headers":{"Authorization":"Bearer ${ANGUS_INSIGHT_TOKEN}"}}}}

助手用的是这个账号的权限，而且只返回合计。注册的只读工具是insight_query_metrics、insight_funnel_analysis、insight_list_events、insight_query_paths、insight_query_errors。漏斗走insight_funnel_analysis，步骤 1 到 10 个事件名。insight_invoke_read只支持 GET 和 HEAD，不要拿它去拼漏斗。个人接口（例如用户列表和时间线）在拒绝列表里。没有写工具，不能用助手改看板、改规则或建漏斗。把angus.mcp.enabled设回false只关掉 MCP，采集和看板还在。

官方 SDK

浏览器采集和 REST 调用是两个包。上面的page_view用@anguskit/angusinsight-sdk。控制台接口用 REST SDK，目录里的版本是1.0.0。Java 构件angus-insight-sdk，包名cloud.xcan.angus.sdk.insight。npm 是@anguskit/angus-insight-sdk。PyPI 是angus-insight-sdk。Go 模块是github.com/anguskit/angus-sdk-insight。没有官方 NuGet。安装源是 AngusRepo 上的公开仓。云上网关是https://bj-c1-prod-apis.anguskit.com/insight。私有化换成自己的网关主机，路径仍是/insight。鉴权是Authorization: Bearer <访问令牌>。冒烟可以GET /api/v1/apps，看这个账号能看到的应用。/innerapi不在这份官方 SDK 里。

常见问题

实时里没有 page_view。先核对endpoint是否以/pubapi/v1/collect结尾，应用是否就是这个appCode。SPA 若关掉了自动页面浏览，又没有在路由里调用pageView()，初始化不会留下这一条。respectDNT打开且浏览器不允许跟踪时，init()不会采集。

同一页记了两次。autoTrack.pageView仍是true，路由里又调用了pageView()。SPA 只保留一种。

渠道全是 direct。链接上没有匹配到的 UTM、来源或点击 ID，或者规则优先级被另一条先匹配走了。默认规则不能删。保存只影响之后的事件。

漏斗人数是 0。步骤名必须和上报的event一致。下一步发生在上一步之前的用户，不计入后面的步骤。时间范围跟筛选条。不能按page_path再滤一步。

助手看不到某个用户点了什么。个人时间线在控制台「用户」。MCP 只返回合计。令牌必须是本产品的xcan_op，并且angus.mcp.enabled=true。