这个网站是什么,数据从哪来
本文说明对局看板的数据来源、每个模块的数据含义,以及对外 HTTP API 的用法。页面内容会随后续功能更新。
01这个网站是什么
这是一个「英雄联盟对局看板」:把一台运行游戏的主机(采集端)看到的对局信息,实时同步到网页上,让其他人也能看到房间成员、BP 选人、对局战况和赛后数据。
- 采集端:运行在开黑主机上的 Node 程序,读取 League Akari 内存、英雄联盟客户端 LCU 接口与实时对局接口。
- 服务端:接收采集端上传的数据,持久化保存,并通过 SSE 推送给浏览器。
- 前端:静态页面,不直接接触游戏客户端,只读取服务端接口。
本站是只读展示工具:不会登录或操作任何游戏账号,也不会修改 League Akari 的数据。
02数据链路
采集端 ──GET /api/history-ids?puuids=…(先比对已有场次)──▶ 服务端
├─POST /api/ingest(对局快照,X-Api-Key)──▶ 内存 + DATA_DIR/archive.jsonl
├─POST /api/details(对局详情,400KB 分片)──▶ DATA_DIR/details.json
└─POST /api/histories(只推新局,服务端按 gameId 合并累积)──▶ DATA_DIR/histories.json
浏览器 ──GET /api/stream(SSE:state / archive / presence)──▶ 服务端
├─GET /api/game/:gameId(点开某局详情)
├─GET /api/history/self 或 /api/history/:puuid(侧栏 / 个人主页)
├─POST /api/request-detail(详情缺失时点「重新加载」,服务端转交采集端补取)
├─POST /api/request-history(个人主页无战绩时点「点击采集」,采集端按 puuid 拉取后上传)
└─GET /api/archive、/api/presence/list(回放、在线详情)
03数据来源
League Akari(本机进程,CDP 9223)
Akari 启动时带上 --remote-debugging-port=9223,采集端就能连进它的渲染进程,读取它已经算好的分析结果。只读内存,不做任何写入。
| Akari 数据 | 内容 | 页面用途 |
|---|---|---|
analysis.players | 场次、胜率、场均 KDA / 补兵 / 视野 / 参团 / 伤害转化、Akari 评分、英雄池、打野偏好、KDA 离群 | 玩家卡片、场均胶囊、个人主页 |
inferredPremadeTeams 等 | 开黑分组推断结果 | 同队开黑字母与配色 |
matchHistory | 每名玩家最近对局与单局详情 | 最近对局列表、对局详情弹窗 |
summoner | 等级、Riot ID、头像、生涯隐藏(privacy) | 卡片头部、生涯隐藏标签 |
rankedStats | 单双排 / 灵活段位、LP、上赛季、历史最高、晋级赛进度 | 段位行与悬停提示 |
championMastery | 英雄熟练度等级与点数 | 头像熟练度角标 |
settings | 标签开关等展示设置 | 标签是否显示,与 Akari 保持一致 |
英雄联盟客户端 LCU
通过客户端 lockfile 找到本地端口与令牌,读取当前阶段、房间、BP、战绩与召唤师资料。常用接口:
/lol-gameflow/v1/session、/lol-lobby/v2/lobby、/lol-matchmaking/v1/ready-check:房间中 / 排队中 / 接受对局。/lol-champ-select/v1/session:BP 选人、禁用、选人顺序。/lol-match-history/v1/products/lol/{puuid}/matches:最近 50 场战绩。/lol-champion-mastery-v1/champion-mastery-by-puuid/{puuid}:当前版本可用的熟练度接口。
Live Client Data API
对局进行中读取 https://127.0.0.1:2999/liveclientdata/allgamedata,提供实时等级、KDA、补兵、视野分、阵亡倒计时与游戏时间。
服务端持久化
数据目录由环境变量 DATA_DIR 指定(默认 server/data)。重启服务不会丢失以下数据:
| 文件 | 内容 | 保留策略 |
|---|---|---|
archive.jsonl | 每场对局结束后的完整快照,用于「回放」 | 追加写,内存保留最近 200 场 |
details.json | 对局详情(10 名玩家完整统计) | 最多 600 局,临时文件 + rename 原子写 |
histories.json | 每名玩家的历史战绩 | 按 gameId 合并累积(同一局不重复,旧局不会因为新的 50 场窗口被挤掉),每人最多 500 条 |
visitors.json | 历史观看记录(离线后归档) | 最多 500 条,按 IP + 设备聚合 |
04页面模块与数据口径
| 模块 | 数据来源 | 说明 |
|---|---|---|
| 顶栏连接状态 | 快照心跳 | 反映「采集端」是否在线:60 秒内收到过快照算在线;服务端 120 秒无上传会清空当前对局并标记离线。 |
| 房间玩家 | LCU lobby + Akari 补全 | 房间中 / 排队中 / 接受对局三个阶段都会展示;排队阶段统一显示「排队中」。 |
| BP 选人 | LCU champ-select + Akari | 按真实选人顺序排列;禁用英雄走三级兜底;悬停可看胜率与熟练度。 |
| 对局中 | Live Client Data | 双方实时等级、KDA、补兵、视野、阵亡倒计时;实时播报为击杀、推塔等事件。 |
| 赛后复盘 | 结束快照 + 详情 | 比分、团队数据对比、双方对比面板与 MVP。 |
| 侧栏 · 战绩 | histories.json | 本人历史战绩(服务端累积保留,可超过 50 条);点击某行打开对局详情,采集端离线时仍可访问。 |
| 侧栏 · 好友 | Akari 好友列表(CDP) | 在线 / 游戏中 / 排队中 / 离开 / 勿扰状态与所在队列、英雄;数据不落盘,随快照实时刷新。 |
| 侧栏 · 回放 | archive.jsonl | 采集端记录过的赛后归档,按会话查看。 |
| 个人主页 | Akari 分析 + 完整 50 场 | 段位、生涯趋势、英雄池、连胜小结、打法细节;点击战绩行可继续看详情。 |
| 个人主页 · 点击采集 | request-history 队列 + LCU | 主页显示「暂无该玩家的历史战绩数据」时,可点「点击采集」让采集端立刻按 puuid 去客户端拉取战绩并上传;按钮会显示采集进度,成功后主页自动刷新出战绩。 |
| 在线人数 | presence 心跳 | 同一浏览器多标签只算 1 人;点击可看在线访客 IP、在线时长、设备与历史观看。 |
| 对局详情 · 重新加载 | request-detail 队列 | 显示「完整详情缺失」的离线概要时,可点「重新加载」让服务端通知采集端立刻补取这一局;按钮会显示补全进度,最快几秒替换为完整详情。 |
05HTTP API
线上地址:https://lol.loveb.xyz。读取类接口无需鉴权;写入接口需要请求头 X-Api-Key,值等于服务端环境变量 INGEST_KEY(未配置时写入接口返回 503)。
接口一览
| 方法 | 路径 | 作用 | 返回 |
|---|---|---|---|
| GET | /api/health | 健康检查 | { ok, phase, updatedAt } |
| GET | /api/state | 当前对局快照(轮询兜底) | 完整快照对象 |
| GET | /api/stream?v=&t= | SSE 实时推送;事件:state / archive / presence | text/event-stream |
| GET | /api/game/:gameId | 单局详情(总览 + 详情表) | 详情对象;完整详情缺失时返回 fallback: true 的离线概要 |
| GET | /api/history/self | 本人历史战绩(服务端累积保留) | { puuid, rows, updatedAt } |
| GET | /api/history/:puuid | 指定玩家的历史战绩 | 同上 |
| GET | /api/history-ids?puuids=a,b | 查询服务端已保存的 gameId(采集端上传前比对用) | { ids: { puuid: ["gameId", …] } } |
| POST | /api/request-detail | 请求补取某局完整详情(前端「重新加载」调用) | { ok, queued } 或 { ok, ready };请求体 { gameId } |
| GET | /api/detail-requests | 采集端轮询待补取的对局(取走即消费) | { gameIds: [...] },需 X-Api-Key |
| POST | /api/request-history | 请求补采某玩家的战绩(个人主页「点击采集」调用) | { ok, queued } 或 { ok, ready, rows };请求体 { puuid, gameName?, tagLine? } |
| GET | /api/history-requests | 采集端轮询待补采的玩家(取走即消费) | { players: [{ puuid, gameName, tagLine }] },需 X-Api-Key |
| GET | /api/archive?limit=30 | 赛后归档列表 | { items: [...] } |
| GET | /api/archive/:sessionId | 某场归档的完整快照 | 快照对象 |
| GET | /api/presence | 当前在线人数 | { online } |
| GET | /api/presence/list | 在线访客明细 + 历史观看 | { online, tabs, visitors, history, now } |
| POST | /api/presence/ping | 访客心跳(前端自动调用) | { online };请求体 { v, t } |
| POST | /api/presence/leave | 标签页关闭立即下线 | { online } |
| POST | /api/ingest | 采集端上传当前快照 | { ok: true },需 X-Api-Key |
| POST | /api/details | 上传对局详情(按约 400KB 分片) | { ok, stored },需 X-Api-Key |
| POST | /api/histories | 上传玩家战绩(服务端按 gameId 合并,只补新局) | { ok, players, rows, added },需 X-Api-Key |
| GET | /skins · /skins/:path | 皮肤等静态资源(JSON 目录列表 / 原始文件) | JSON 或文件字节;需环境变量 SKINS_TOKEN 配置口令 |
调用示例
# 当前状态
curl https://lol.loveb.xyz/api/state
# 本人历史战绩
curl https://lol.loveb.xyz/api/history/self
# 某局详情(gameId 来自战绩行)
curl https://lol.loveb.xyz/api/game/601010877507
# 服务端已保存哪些对局(采集端增量上传前比对)
curl "https://lol.loveb.xyz/api/history-ids?puuids=puuid1,puuid2"
# 手动请求补取某局完整详情(前端「重新加载」等价调用)
curl -X POST https://lol.loveb.xyz/api/request-detail \
-H "Content-Type: application/json" \
-d '{"gameId":"601010877507"}'
# 手动请求补采某玩家的战绩(前端「点击采集」等价调用)
curl -X POST https://lol.loveb.xyz/api/request-history \
-H "Content-Type: application/json" \
-d '{"puuid":"玩家的puuid","gameName":"游戏名","tagLine":"84831"}'
# 实时事件流(Ctrl+C 结束)
curl -N https://lol.loveb.xyz/api/stream
# 采集端上传快照(需要密钥)
curl -X POST https://lol.loveb.xyz/api/ingest \
-H "Content-Type: application/json" \
-H "X-Api-Key: $env:INGEST_KEY" \
--data-binary "@snapshot.json"
补采接口(前端按钮触发)
前端的「重新加载 / 点击采集」不会直接访问游戏客户端,而是先往服务端登记一条请求,采集端每 8 秒轮询取走并执行。请求取走即消费,未取走的请求 30 分钟后自动过期;同一目标 5 秒内重复登记会被去重。采集端离线时请求会留在队列里,直到过期。
// POST /api/request-detail —— 请求补取某局完整详情
{ "gameId": "601010877507" }
// 已在服务端有完整详情:无需补取
{ "ok": true, "ready": true }
// 已入队,等待采集端补取
{ "ok": true, "queued": true }
// 5 秒内重复点击,已去重
{ "ok": true, "queued": false, "reason": "recent" }
// POST /api/request-history —— 请求补采某玩家最近战绩
{ "puuid": "玩家的puuid", "gameName": "游戏名", "tagLine": "84831" }
// 服务端已有该玩家战绩(rows 为条数),前端直接刷新即可
{ "ok": true, "ready": true, "rows": 50 }
// 服务端没有该玩家战绩,已入队
{ "ok": true, "queued": true }
// GET /api/detail-requests(需 X-Api-Key)→ 取走即消费
{ "gameIds": ["601010877507"] }
// GET /api/history-requests(需 X-Api-Key)→ 取走即消费
{ "players": [ { "puuid": "…", "gameName": "游戏名", "tagLine": "84831" } ] }
写入接口的请求体
// POST /api/ingest —— 采集端归一化快照
{
"v": 1,
"phase": "champ-select | in-game | end-of-game | none",
"client": { "online": true, "lcuPhase": "Lobby" },
"queue": { "queueId": 420, "name": "排位赛 单排/双排" },
"gameTime": 512,
"selfPuuid": "…",
"teams": { "ORDER": [ … ], "CHAOS": [ … ] },
"friends": [ { "gameName": "…", "tagLine": "…", "availability": "online", "lol": { "gameStatus": "inGame", "queueId": "420" } } ],
"live": { "events": [ … ] }
}
// POST /api/details —— 对局详情(可分批)
{ "v": 1, "selfPuuid": "…", "details": { "601010877507": { "participants": [ … ] } } }
// POST /api/histories —— 每名玩家的历史战绩(只需推服务端还没有的局)
// 服务端按 gameId 合并累积,重复局自动去重、旧局永久保留(每人最多 500 条)
{ "v": 1, "selfPuuid": "…", "histories": { "puuid": [ { "gameId": "…", "k": 8, "d": 4, "a": 10 } ] } }
SSE 事件格式:每条事件都是 event: 名称 + data: JSON。state 是当前快照,archive 是归档列表,presence 是最新在线人数。
06字段解释
| 字段 / 文案 | 含义 |
|---|---|
| 评分 | League Akari 的对局表现评分(akariScore),越高代表近期表现越好。 |
| 胜率 | 最近场次中的胜场数 / 场次总数。 |
| 场均 KDA | (击杀 + 助攻) / 死亡;死亡为 0 时按 1 计算。 |
| 补兵 | 正补 + 野怪击杀。界面统一使用中文「补兵」,不再显示英文 CS。 |
| 视野 / 分 | 视野得分 ÷ 对局分钟数。 |
| 参团率 | (击杀 + 助攻) / 队伍总击杀,按队伍计算。 |
| 伤害转化 | 对英雄伤害 / 获得金币,衡量经济转化为输出的效率。 |
| 段位 | 按队列展示 tier + 小段位 + LP;悬停可看上赛季、历史最高与晋级赛进度(WLN,W 胜 / L 负 / N 未打)。 |
| 熟练度角标 | 本局英雄的熟练度等级与点数;等级 ≥ 4 显示角标(4 绿 / 5 蓝 / 6 紫 / 7 金 / 8+ 红)。 |
| 开黑分组 | Akari 推断的同队开黑玩家,字母编号 + 同色描边。 |
| 玩家标签 | 高胜率、连胜 / 连败、生涯隐藏、容易被抓、单杀多、视野高等;显示哪些由 Akari 设置决定。 |
| 蓝方 / 红方 | 游戏内的 TEAM-100(蓝)与 TEAM-200(红),统一翻译为中文。 |
| 离线概要 | 完整详情没有上传时,用已保存的战绩行拼出的概要详情,会带黄色提示;可点「重新加载」让采集端立刻补取,采集端上线后也会自动补全。 |
| 好友在线状态 | 取自 Akari 好友列表的 availability:在线(绿)、游戏中(金)、排队中、离开(橙)、勿扰(红)、离线(灰);游戏中还会显示队列与英雄。 |
| 好友游戏状态 | Akari 的 lol.gameStatus:inGame / inQueue / outOfGame;云顶之弈(TFT)队列单独标注,不会误显示为召唤师峡谷。 |
| 遇到过 | Akari 记录的 saved.lastMetAt,显示「遇到过」或「N 天前」,代表之前和该玩家匹配过。 |
07隐私与限制
- 采集端只读本机游戏客户端与 League Akari 的公开数据,不接触账号密码,不执行游戏操作。
- 页面展示的召唤师名、Riot ID、段位与战绩来自对局本身,属于游戏内公开信息。
- 在线统计使用浏览器本地生成的匿名访客 ID(同一浏览器多标签只算 1 人)。为了展示「在线详情 / 历史观看」,服务端会记录请求 IP、User-Agent、语言与时区,并按 IP + 设备聚合,最多保留 500 条历史记录。
- 采集端离线或游戏客户端未启动时,实时模块会停更;已保存的最近对局、详情与回放仍可访问。
- 好友列表只随快照即时展示、不写入磁盘;
/skins资源接口需要服务端配置SKINS_TOKEN,未配置时直接返回 503,响应带Referrer-Policy: no-referrer避免口令通过 Referer 泄露。 - 详情上传有 30 秒节流并按分片重试;从未上传成功的对局只会显示离线概要,不代表该局不存在。
08常见问题
采集端离线后还能看详情吗?
可以。最近对局列表、对局详情、回放都保存在服务端磁盘上;完整详情缺失时会自动显示离线概要,不会出现空白弹窗。
详情缺失时能手动补全吗?
可以。离线概要的提示条右侧有「重新加载」按钮,点击后服务端会把这一局放进补取队列,采集端在几秒内取走并直接从客户端重新读取详情上传;按钮下方会显示补全进度,成功时弹窗自动替换为完整详情。若采集端不在线,约 32 秒后会提示重试。
个人主页没有历史战绩数据怎么办?
主页显示「暂无该玩家的历史战绩数据(采集端未采集到)」时,下方有「点击采集」按钮。点击后服务端会把该玩家放进补采队列,采集端取走后按 puuid 从英雄联盟客户端拉取最近 50 场并上传,页面每 4 秒检查一次,成功后自动刷新出战绩列表(最多等待约 32 秒)。若提示「服务端异常(HTTP 405):补采接口不可用」,说明线上服务端仍是旧代码,需要更新 server/src/index.js 并重启 Node 项目;若提示「采集端未返回数据」,请确认采集端已重启、且游戏客户端在线。
战绩每次都会重新上传吗?
不会。采集端上传前先调 /api/history-ids 比对服务端已有的 gameId,只提交新局,通常每次只有几 KB。服务端按 gameId 合并累积,之前上传过的对局会一直保留,不会因为客户端只给最近 50 场而被清掉。
为什么有些对局的详情只有概要?
采集端只会在上线期间补传详情,且按约 400KB 分片上传。某局从未成功上传完整详情时,服务端会用已保存的战绩行拼出概要(模式、时间、时长、英雄、KDA、胜负等)。
为什么有的玩家没有 Akari 评分或标签?
需要 League Akari 以 --remote-debugging-port=9223 启动,并且加载过对局页。读不到时采集端会降级为本地近似算法,部分标签会缺失。
数据多久更新一次?
对局中常见 1–5 秒一帧;非对局阶段每 5 秒心跳。服务端 120 秒收不到上传会清空当前状态,顶栏显示「采集端已离线」。
段位为什么是空白?
该玩家在这个队列未定级,或 Akari / LCU 暂时没有返回段位数据。玩家卡片仍会显示胜率、场均等其它数据。
可以接入我自己的采集端吗?
可以。按上文的请求体格式向 /api/ingest、/api/details、/api/histories 发送数据,并携带正确的 X-Api-Key 即可。服务端环境变量:PORT(默认 8080)、INGEST_KEY(写入密钥,必填)、DATA_DIR(数据目录)。若要开启 /skins 资源接口,还需配置 SKINS_TOKEN(访问口令,未配置时该接口返回 503)与可选的 SKINS_DIR(资源目录,默认自动探测 public/skins)。