企业官网建设流程全解析

• 人工智能
• 搜索引擎
• 本地部署
• 后端
• MCP 服务

本文围绕 XERJ 仓库 metrics/README.md 展开，完整解读这套"不依赖遥测的采纳数据体系"：XERJ 二进制从不回传任何数据，只有网站与安装下载这一"分发面"被计量；release-downloads.jsonl每天一条 JSONL 把 GitHub 上无人保留历史的download_count变成可趋势化的时间序列，而 scripts/adoption-snapshot.sh 则把仓库级数字分为"可引用、已污染、根本不存在"三档，替你守住技术可信度的底线。读完本文，你将掌握这套数据文件的格式、采集管道、正确解读规则与整套工具链的使用方法。

一段话讲清隐私姿态：无遥测，只有分发面计量

XERJ 的隐私立场可以浓缩为一句话：二进制不携带任何遥测。无论是首次运行还是日常使用，程序都不会"打电话回家"，而且项目没有计划添加这一功能——这是一个 Apache-2.0 许可、由工程师运行在自己硬件上的工具，静默的回传行为带来的信任损失远大于那点数据价值。

真正被计量的只有"分发面"：网站和安装器下载。理由也很朴素：对 Web 服务器的请求，本来就在服务器运营者的可观测范围内。安装计数器（functions/get.js）为每次/get请求记录四类信息：时间戳、国家（Cloudflare 的两字母国家码）、User-Agent 字符串，以及由 UA 推导出的粗略操作系统猜测。它不记录 IP、不写 Cookie、不生成任何形式的标识符——同一个人的两次安装，与两个不同人的两次安装，在数据上完全无法区分。这不是实现疏漏，而是刻意设计的完整能力边界。

有趣的是，这一边界在仓库里能找到"对照组"：同为 Cloudflare Function 的 functions/lead.js 是会记录ip（cf-connecting-ip）的，代码注释明确写道"这是一个有意的分歧，而非疏忽——leads 是输入了邮箱的人，安装请求不是"。这一对比从侧面印证了/get计数器把"可识别的个体"与"匿名的请求计数"严格区分的设计原则。

release-downloads.jsonl：把标量变成序列

为什么需要这个文件

GitHub 的 Release 资产download_count是一个运行中的累计值，且不保留历史。在引入快照之前，项目唯一一个没有被注水的采纳数字只能被"读一次"，永远无法观察趋势。没人快照它，意味着这个数字只有当下、没有过去。

每天追加一行的release-downloads.jsonl（metrics/release-downloads.jsonl）正是为了解决这个问题：一天一行，把标量变成序列，而且基础设施成本为零——它只读取公共仓库元数据，不需要新增服务或密钥。

一行数据的完整结构

每行是一个 JSON 对象（示例为缩写）：

{ "date": "2026-08-08", "collected_at": "2026-08-08T06:00:12Z", "repo": "xerj-org/xerj", "totals": { "releases": 12, "binary": 88, "checksum": 57, "all": 145 }, "releases": { "v1.0.0-rc.12": { "published_at": "…", "prerelease": false, "assets": { "xerj-1.0.0-rc.12-x86_64-unknown-linux-musl.tar.gz": 1, … } } }, "traffic_14d": { "clones": {"count":…, "uniques":…}, "views": {…} } }

各字段含义：

为什么选 JSONL 而不是 JSON

• 一天就是一行追加，git diff每次只有一行变化；
• 两个并发写者不会互相破坏同一个数组（没有共享的"数组结构"需要竞争）；
• jq -c可以直接流式处理；
• 幂等：同一天重复运行采集脚本，是替换当天那一行，而不是追加第二行——这保证了手动补跑与定时任务之间不会产生重复数据。

从仓库里的实际数据看，序列从 2026-08-08 开始，早期几天的行（如v1.0.0-rc.12那行totals: {releases: 12, binary: 88, checksum: 57, all: 145}）与 README 示例完全对应，随后每天的数字持续增长，忠实记录了这一指标随时间的变化。

采集管道：定时任务 + 幂等写入

release-downloads.jsonl由两个构件共同维护：

1. 调度与提交：.github/workflows/release-metrics.yml
2. 数据采集：.github/scripts/snapshot-release-downloads.sh

调度设计

工作流使用cron: '17 6 * * *'（每天 06:17 UTC）定时触发，刻意避开整点——GitHub 调度器在整点最拥堵，可能让任务延迟 10–30 分钟。同时允许workflow_dispatch手动触发。它还做了三件值得注意的事：

• permissions: contents: write，且限定if: github.repository == 'xerj-org/xerj'——fork 上的定时任务没有可快照的数据；
• 提交信息带[skip ci]标记。虽然默认 GITHUB_TOKEN 的推送本身不会触发工作流（GitHub 会阻止递归），这个标记是"双保险"——如果将来换成 PAT，CI 与 8 目标交叉编译的 release.yml 也不会被误触发；
• 提交前先git pull --rebase --autostash，采集期间若有人推了代码也不会失败。

采集脚本的工程细节

snapshot-release-downloads.sh支持--out FILE、--repo OWNER/NAME、--dry-run三个参数，依赖gh（已认证）与jq。脚本里有几个值得一提的实现要点：

• API 载荷走文件而非 argv：完整的/releases响应有数百 KB（每个资产都内嵌 uploader 对象），直接--argjson会撑爆ARG_MAX，所以先用jq把响应裁剪成{tag_name, published_at, prerelease, assets:[{name, download_count}]}再落盘；
• 分页归一化：gh api --paginate在不同 gh 版本下可能输出"单个合并数组"或"每页一个数组"，jq -s 'flatten(1)'把两种情况都归一为单一数组；
• traffic 接口的诚实降级：/traffic/clones、/traffic/views需要 push 权限，令牌没有该权限时接口失败，脚本把值写成null而不是猜一个数——从 metrics/release-downloads.jsonl 里可以看到，2026-08-10 之后的多行traffic_14d都是null，序列因此保持诚实；
• 写回是"过滤 + 追加"：jq -c 'select(.date != $date)'先滤掉当天旧行，再追加新行，实现同一天幂等替换。

如何正确解读这些数字：三条硬规则

规则一：totals.binary是资产抓取数，不是安装数

totals.binary统计的是资产被 fetch 的次数，其中包括 CI、镜像、扫描器和重复下载。它绝不等于安装次数。

规则二：binary与checksum的比值是最有用的"指纹"

安装器（landing/get）每次运行会恰好抓取一个二进制和一个对应的.sha256校验和文件，而且顺序刻意固定为先二进制后校验和。因此：

• 安装器形态的流量会呈现1:1的 binary:checksum 配对；
• binary明显高于checksum的流量，就是不是安装器的流量（直接抓取、镜像、扫描器）。

这是一条被写进代码里的"约定"：README 特别警告，不要重排landing/get里这两次抓取的顺序，除非先替换掉这个指纹判断逻辑。

规则三：traffic_14d是 14 天滚动窗口，绝不可相加

• 它是滚动窗口，不是日值，也不是终身累计；
• 连续两次快照重叠 13 天，直接相加会严重重复计数；
• GitHub 会过期这些窗口数据——一天没被快照，就永远消失，这是必须每天跑采集的最强理由；
• 当采集令牌缺 push 权限时，该字段为null，这是诚实的缺失而非错误。

最后别忘了：这里没有任何信息能说明"下载的二进制是否真的运行过"。这一点没人能知道。

什么数据不在这个目录里

安装计数器的原始记录不放在 git 里，而是存放在 Cloudflare R2 的xerj-installsbucket（绑定关系见 wrangler.toml 与 functions/get.js）。原因很实际：它们是请求日志，每次请求增长一条，本来就不属于仓库。

需要读取时，通过带 token 防护的导出接口：

curl -s "https://xerj.org/get?token=$INSTALLS_TOKEN&days=30" | jq .

这条导出返回的是聚合数据，并自带一段 caveat 文案。它的短版本是：对/get的一次请求只是"一次请求"，不能证明下载成功、校验和匹配、或二进制被真正执行过。

在 functions/get.js 的源码里可以看到导出实现的细节：?days=默认 30、上限 365（Math.min(Math.max(parseInt(...), 1), 365)），防止遍历无限大的 bucket；?format=raw可以拿到逐行明细以便自行重新聚合；token 校验要求"调用方 token 与已配置的INSTALLS_TOKEN同时存在"，未配置密钥时导出永远不会被打开。

获取诚实漏斗：adoption-snapshot.sh

仓库级的总数——stars、forks、clones——在这个项目上被一个合成化的账号群体严重注水，不能当作采纳信号。因此 scripts/adoption-snapshot.sh 的核心价值不是展示数字，而是按顺序输出三档：

第一档：可以引用的数字

• release 资产下载量（binary + checksum，全历史），以及 binary:checksum 比值；
• 安装器运行次数（上限）：脚本用min(每个二进制的下载量, 其对应校验和的下载量)求和，因为一次安装 = 一次二进制 + 一次校验和，所以"配对的上限"才是安装器运行次数的上界——注意，上限不是计数；
• 减去全平台扫描：如果某个 Release 的 8 个平台压缩包和 8 个校验和都被下载过，那更可能是自动化的全平台扫描而非 8 个真人（没有机器会同时是 8 个平台），每个这样的 Release 减去一次扫描的 8 个资产；
• 源自 metrics/release-downloads.jsonl 的趋势行（最新日期、latest totals、相较前一天的变化）；
• 外部真实贡献者：用FIRST_PARTY='["xerj-org","xerj-team"]'名单排除自有账号后，统计非 bot 的外部 PR/issue 作者去重数。脚本注释还提醒：xerj-org 是个人账号而非 Organization，/orgs/.../members会 404，所以这个名单必须人工维护，否则"外部贡献者"数字会悄悄漂移。

第二档：不可引用的数字，每条都附原因

• stars（原始值）：某一天出现了合成化形态的批量到达。脚本调用Accept: application/vnd.github.star+json拉取每个 star 的时间戳，计算"最繁忙单日"；如果该日到达数超过总数的 25%，就把该日之前的天数作为可辩护的 star 数给出。README 明确说：该群体的构成分析见内部文档，它不构成"滥用"定性，但它也不是采纳；
• forks：fork 免费且随时可弃。唯一有价值的是"fork 后有过提交"的数字——上次审计时 351 个 fork 中只有 4 个满足条件（98.9% 从未动过）；
• clones / views：14 天滚动窗口、包含自家 CI 和索引运行的克隆，重叠 13 天不可相加；views 还有自引注水问题。

第三档：根本不存在、也不该编造的数字

• 已安装的二进制是否被运行过——刻意留白，因为二进制无遥测；
• 站点访问量——Cloudflare RUM beacon 自 2026-07-22 起停止记录，在重新注入前分析面板读到的零是假零；
• 安装失败数——在不支持的平台上、缺 curl、或（2026-08-08 之后）缺 SHA-256 工具而失败的运行不留任何痕迹，所有安装数字都只统计成功，分母未知；
• 归因——没有任何东西能把一次访问、克隆、下载、安装关联起来，据此计算的漏斗转化率是虚构的。

运行方式：scripts/adoption-snapshot.sh（需要已认证的gh与jq），可选--no-stars跳过 star 队列扫描（约省 13 次 API 调用），或用--repo o/n换成其他仓库。

安装计数器的源码级隐私实现

functions/get.js 是这套体系"分发面计量"的具体落地，值得单独拆解：

• UA 分类（classify）：维护一个刻意保持精简的 bot 关键词表（bot、crawler、spider、python-requests、headlesschrome、axios 等）。判定顺序有讲究：curl|wget|fetch与 PowerShell 先检查，但仅当不含 bot 特征时才判为 installer——因为很多扫描器会同时宣传自己是 curl 和 bot；无法匹配的统一归为unknown，绝不静默算作人类；
• OS/架构猜测（platform）：仅从 UA 提取，宁可返回unknown。注释坦白：最常见的安装 UAcurl/8.5.0根本不含平台信息，所以大多数安装行是 unknown/unknown——真正重要的平台分布来自逐资产的 release 下载计数（即 metrics/release-downloads.jsonl），而不是这里；
• fail-open 规则：安装绝不能被计数器拖垮。脚本体先解析、Response 先构建，R2 写入交给waitUntil()在响应发出后执行，且所有失败路径（无绑定、抛错、超时）都被吞掉——计数器坏掉只会退化为"我们什么也学不到"，绝不会变成"安装失败"；
• 无缓存：cache-control: no-store。注释说明安装器之前是public, max-age=300，但缓存命中的请求根本到不了这个函数，等于按未知的缓存命中率漏计数——no-store 是"要计数就必须付的代价"，而脚本体约 8KB、每次安装只抓一次；
• HEAD 请求不计：链接检查器与部分代理会发 HEAD，函数只回头部不计数；
• 每请求一个不可变记录：R2 key 是installs/{day}/{ts}_{uuid}.json，不做 read-modify-write，并发安装互不丢失；uuid 只是防止并发写互相覆盖的"键"，服务端生成、永不回给客户端，不能用来关联两次请求。

盲区即边界：这套体系知道什么、不知道什么

把整条链路放回全景：

• 知道：每天有多少资产被抓取、多少安装器形态的请求到达了/get、14 天窗口内的克隆/浏览趋势、star 的时间分布；
• 不知道（且有意不知道）：二进制是否运行、谁运行了它、安装是否成功、以及任何能跨请求关联个体的信息。

这套体系的全部技术含量，在于精心设计的已知与未知边界：用 GitHub 公共元数据与 Web 请求日志这种"本就可观测"的数据，做出一个不被注水、可趋势化、可辩护的采纳漏斗，同时把隐私成本压到最低。相关的完整实现分散在 metrics/README.md、.github/workflows/release-metrics.yml、.github/scripts/snapshot-release-downloads.sh、functions/get.js、scripts/adoption-snapshot.sh 与 metrics/release-downloads.jsonl 中，读者可以直接进入这些文件逐行核对本文的每一个结论。

• 人工智能
• 搜索引擎
• 本地部署
• 后端
• MCP 服务