Index

欢迎来到 GOKZ.TOP 文档

网站发布说明可通过应用侧边栏中的版本号查看。

外部网站可以添加“播放 replay”链接，在托管的播放器中直接打开公开的 GOKZ replay。先创建 https://replays.gokz.top/ URL，再使用 URL.searchParams.set 将 replay_url 查询参数设为 replay 的绝对 HTTPS 下载地址；该 API 会安全地完成所需的百分号编码。下载端点必须允许无需身份验证的 GET 请求、返回受支持的原始 .replay 文件，并允许来自 https://replays.gokz.top 的浏览器 CORS 访问（完全公开的文件也可以使用 Access-Control-Allow-Origin: *）；发生重定向时，最终地址也必须满足这些要求。不要在该参数中放入凭据或秘密签名值，因为它会出现在浏览器历史记录和访问日志中。播放器只使用自身托管的地图导出资源，因此 replay 所用地图必须已经在播放器中可用。replay_url 不能与播放器现有的 replay 或 jump_id 参数同时使用。

根管理员可以在 /admin/settings 中选择将 Discord 社区链接显示在导航栏或页脚。

根管理员还可以在 /admin/settings 中启用或停用当前部署的 GlobalAPI 记录导入。此设置默认启用；请在预发布环境中关闭它以避免重复同步。重新启用后，导入会在调度器下次检查时继续，其他 GlobalAPI 同步任务不受影响。

玩家可以在 /settings/binding-code 生成一个 27 字符的短时有效 QQ 绑定码，并向 QQ 机器人发送 /bind <code> 来绑定 Steam 账号。使用前，根管理员必须打开 /admin/settings 生成 QQ 绑定密钥，并将其复制到机器人的本地验证器中。网站不会保存 QQ 绑定关系。轮换或撤销密钥会立即使所有未过期的绑定码失效；轮换时请同步更新机器人的密钥。

已验证的社交链接可以在 /settings/social-links 中单独设置是否在 GOKZ.TOP 显示直播和视频。关闭后，链接仍会显示在玩家资料页，媒体仍会继续收集，但不会出现在公开媒体列表中，也不会参与直播轮询。

当页面显示的玩家资料尚未从 Steam 初始化或超过七天未更新时，玩家名称、头像、国家/地区和 Steam 自定义 ID 现在会在后台自动刷新。

登录玩家打开自己的 /profile/:identifier/runs 页面时，新记录会自动显示，无需刷新页面。实时连接只会接收该玩家 Steam 账号及当前所选 scope 的记录。零传送的世界纪录用时显示为蓝色，有传送的世界纪录用时显示为黄色；即使零传送纪录显示在 NUB 分组中，也仍使用蓝色。“显示 WR 用时”和“显示 WR 差距”偏好会保存在第一方浏览器 Cookie 中。

根管理员现在可以管理 S/A/B/C 级别的赛事，并为选手分配第 1 至第 4 名。赛事结束日期为可选项；未填写时，该赛事将作为单日赛事创建。玩家资料会显示相应的赛事成就徽章：冠军为金色奖杯，亚军为银色奖杯，第 3 或第 4 名为铜色奖杯。

地图详情页现在包含 WR 历史标签页。该页面只显示创造主关世界纪录的记录，并支持 scope、NUB/PRO 筛选和按纪录保持者着色的时间线。

仪表盘现在默认打开 /dashboard/wrs。不设保留上限的缓存首次填充时使用当前 1000 分 PB；此后每次产生新 WR 都会追加一条事件，而不会删除被其超越的旧 WR。当同一条零传送记录同时获得 NUB 和 PRO 时，会合并展示两项成就，并在地图图片上显示用时、领先时间及上一位纪录保持者。地图和难度筛选旁提供 NUB/PRO 视图切换与全站 scope 选择器；切换视图不会移除合并 WR 卡片中的任一成就。页面首次加载 20 张卡片，滚动时会自动按每批 20 张继续加载，前端最多显示 100 张；数据库不会因此清理 WR 事件。实时更新会刷新第一批；当新 WR 改变列表开头时，已加载的后续批次会被安全重置，避免分页数据重叠。

/maps 页面现在默认按“最佳评分”排序。该置信度校正评分会将每张地图的整体平均分和评论数与全站平均分结合，并采用相当于 6 条评论的先验权重：（评论数 * 地图平均分 + 6 * 全站平均分）/（评论数 + 6）。原始整体平均分仍会显示，也可单独用于排序。

带小数的竞技评分会按显示精度向下取值，因此显示值不会高于底层原始值。玩家 Rating 和校正后的地图评分显示两位小数，地图评论平均分显示一位小数。排序、筛选、Rating 等级和 Rating 阶梯位置仍使用未改动的底层原始值。

/maps 的地图技能分布来自导入后端的分析数据。尚未导入分析数据的地图显示为 100% Unknown。运维人员可在后端目录手动运行 python -m app.import_map_skills /path/to/index.json 导入版本 3 的分析文件；常规地图 API 只返回汇总技能占比，按顺序保存的分析分段不会公开，供未来功能使用。

服务器运营者可以安装 gokz-top-ljroom，将玩家传送到地图分析器检测出的 Long Jump 方块。插件会在地图开始时从 GOKZ.TOP 下载当前地图的房间和位置坐标。使用 !lj [距离] 或 !ljroom [距离] 传送到完全匹配或最接近的方块，使用 !ljdefault <距离> 保存默认距离。与 GOKZ 的 !goto 一样，启用保护模式时，有效计时期间禁止传送；其他情况下，传送前会停止正在运行的计时器。后端运维人员可运行 python -m app.import_lj_rooms /path/to/gokz-lj-rooms.json 手动刷新数据；导出的 JSON 文件不会随应用一起发布。

玩家资料会利用这些分析数据展示 Boxtech、加速、Bhop、Climb、梯子和滑坡评分。每项技能会按地图中的技能占比对玩家最强的 PB 积分表现进行加权，并在当前 scope 的合格玩家中独立校准。资料页目前只显示相对雷达图：最强项保持其全局大小，同时放大该玩家各技能之间的差异；每条轴旁的数字仍然是全局校准评分。技能评分与其他竞技评分一样向下保留两位小数，且最高人群的转换值仍低于 11，因此最高显示值为 10.99。玩家排行榜提供一个可选择的技能列，可显示并按六项技能中的任意一项排序。

部署技能评分迁移，或修改评分公式、导入的地图分析后，运维人员必须为 OVR、KZT、SKZ 和 VNL 四个 scope 明确执行原始技能评分重建，并保存全新的转换模型。在后端环境中运行 kztop build skill-ratings 重建全部 scope，使用 kztop build skill-converters 预览各项分布，审核后再运行 kztop build skill-converters --save 保存。API 读取和夜间排行榜重建不会自动重新校准这些百分位曲线。

/servers 页面现在会在每个在线服务器的地图上显示 GlobalAPI 状态徽章。徽章报告服务器针对 GlobalAPI 的 gokz-global 检查结果；悬停后可以查看 API 密钥、插件、设置、地图以及 KZT/SKZ/VNL 模式的结果。由于玩家有效性与具体玩家有关，服务器状态不会检查它。服务器详情还会在最近一次 gokz-top-servers 心跳提供数据时显示玩家延迟，以及服务器网络图风格的 SV 和 VAR 帧性能指标；使用旧版插件的服务器仍可正常工作，只是不显示这些新字段。

服务器运营者可以在 /admin/servers/public-server 中将每台服务器的“可见性”设置为“公开”或“隐藏”。可见性与“已启用”“无效”和“已禁用”等运行状态相互独立。隐藏的服务器仍会发送心跳并接受健康检查，但不会出现在公开服务器浏览器、服务器详情、历史记录、服务器组数量或实时更新中。

服务器白名单集成可以调用 GET /v1/servers/{server_id}/players/{identifier}/activity-summary。first_seen_at 表示玩家在任意服务器首次创建记录的时间，first_server_record_at 表示玩家在请求的服务器组首次创建记录的时间。active_days 统计玩家在该服务器组创建过记录的不同 UTC 日历日数量。传入 recent_days=365 时，只统计截至 generated_at 前 365 天区间内创建的记录；省略时返回全历史统计。独立的 recent_hours 参数只控制 recent_playtime 使用的记录用时窗口。

服务器运营者还可以在 /admin/servers/globalapi-server 中选择一个或多个自己拥有的 GlobalAPI 服务器，然后点击 Export records。下载的 .sql.gz 文件是针对标准 GOKZ LocalDB Players、Maps、MapCourses 和 Times 表生成的流式 MySQL 导入脚本。脚本会导出有效的 VNL、SKZ 和 KZT 记录，将 SteamID64 与跑图用时转换为 GOKZ 本地格式，保留数据库中已有的玩家和地图行，并追加用时记录。请只将该文件导入一次，且目标数据库必须已经存在 GOKZ LocalDB 表；例如可运行 gzip -dc gokz-localdb-records-*.sql.gz | mysql -u USER -p DATABASE。导入前请先备份数据库；重复导入同一文件会追加重复用时。

后端运维人员可以运行 kztop export records --server-id 1683 --server-id 1633 --output /exports/axe-records.csv.gz 创建信息更完整的 gzip 压缩 CSV 归档，也可以将服务器 ID 替换为可重复传入的 --server-group 服务器组 UUID、自定义 ID 或精确名称。可选的 --after 和 --before 接受 ISO 8601 时间，并以包含边界的方式筛选记录创建时间。CSV 会包含 Steam ID 兼容的有效 VNL、SKZ、KZT 和 NKZ 记录，允许任意长度的地图名并保留重复跑图；表头为 record_uuid,globalapi_record_id,server_id,steamid64,steamid32,player_name,player_country,map_id,map_name,stage,mode,local_mode,style,runtime_seconds,runtime_ms,teleports,created_at,updated_at,replay_id,is_valid。玩家别名优先于原始名称。除非传入 --force，命令不会覆盖已有文件，并会输出成功导出及排除记录的数量。

使用 kztop export players 并传入相同的服务器或服务器组、日期、输出及覆盖选项，可以导出这些有效记录所涉及的、不存在 Steam ID 兼容问题的去重玩家。压缩 CSV 表头为 steamid32,steamid64,alias,cheater,ip,last_played_at,country,created_at。显示名称优先使用玩家别名，否则回退到 Steam 名称；只有存在永久封禁时 cheater 才为 1；IP 来自该玩家在所有服务器中的最新会话。首次和最近活动时间会综合所选服务器记录，以及该玩家在所有服务器中的最早连接和最新已结束会话的断开时间。

/leaderboards/countries 页面现在按每个国家评分最高的 10 名合格玩家的平均评分进行排名。页面会显示上榜玩家数、30 天内的活跃玩家数、各国前三名玩家以及评级中位数。少于 10 名合格玩家的国家仍会显示，但不会获得排名。

/compare 页面可对比当前 scope 下的两位玩家。可通过玩家搜索选择双方，或在登录后右键另一位玩家并选择“Compare”，直接与自己的账号对比。页面会展示 Rating、全球 Rating 排名、积分、Rating E/H、WR 和高价值 PB 总数、按难度统计的主关完成进度，以及 NUB/PRO 主关 PB。奖励关和已失效地图不会显示；跑图行按玩家 1 的 PB 积分排序，也可以只显示两人都完成的地图。

/media 页面只显示已验证 YouTube 和 Bilibili 账号发布的 KZ 相关视频。满足以下任一条件即可收录：平台标签精确匹配 KZ、GOKZ、Kreedz 或 CS2KZ；标题或简介中以独立词语出现上述关键词；标题或简介中包含以 kz_、bkz_、kzpro_ 或 xc_ 开头的独立地图名称形式。地图名称不必已经存在于当前地图目录中。不匹配的视频仍会按正常的 90 天保留期保存在内部缓存中，以便平台元数据修改后重新判定，但不会公开显示，也不会将其缩略图缓存到 R2。

运营人员可以设置仅在服务器端使用的 BILIBILI_COOKIE 环境变量，并填入包含 SESSDATA 的专用 Bilibili 浏览器 Cookie，以帮助上传视频轮询器通过 Bilibili 的反爬检查。请勿使用个人账号 Cookie，也不要将此值暴露给浏览器。部署媒体分类迁移后，请先在预发布环境、再在生产环境运行 kztop sync media --reclassify-existing，重新获取标准元数据并分类保留期内的视频；可使用 --platform、--limit 和 --dry-run 进行受控验证或恢复。