对局看板 · 说明
返回看板 API 测试

这个网站是什么,数据从哪来

本文说明对局看板的数据来源、每个模块的数据含义,以及对外 HTTP API 的用法。页面内容会随后续功能更新。

01这个网站是什么

这是一个「英雄联盟对局看板」:把一台运行游戏的主机(采集端)看到的对局信息,实时同步到网页上,让其他人也能看到房间成员、BP 选人、对局战况和赛后数据。

本站是只读展示工具:不会登录或操作任何游戏账号,也不会修改 League Akari 的数据。

02数据链路

采集端(兵哥电脑)每秒读取 Akari / LCU / Live Client Data,归一化成快照;对局详情与战绩走独立通道(战绩只推服务端还没有的新局)。需要密钥鉴权
服务端接收快照与归档,落盘到 DATA_DIR;维护当前状态、历史对局、详情、战绩、在线人数。SSE 推送
浏览器订阅 /api/stream 渲染页面;点击战绩时按需拉取 /api/game/:id。无需登录
采集端 ──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、战绩与召唤师资料。常用接口:

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 / presencetext/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)。