JKTV-online/README.md

YRTV 2.0.0 Beta · Superjacky6 Self-hosted Edition

Created by Superjacky6 · jacky / jk / yr / jacky0987

YRTV 是面向固定 CS2 战队的私人数据站。它不是公共玩家排行榜，而是让队员拥有类似职业选手的个人主页，并为战队提供比赛档案、队内比较、阵容分析、对手情报和战术工具。

当前 Beta 版本已经建立可重复运行的数据流水线、数据库治理、职业主页和可追溯的阵容版本模型，重点服务 active roster。

当前基线

• 208 场比赛
• 1,181 名采集到的玩家
• 2,080 条玩家比赛记录
• 4,315 个回合
• 33,560 条回合事件
• 38,423 条经济记录
• 9 名 active roster 队员
• 885 条 roster 逐场历史
• 76 条地图统计
• 236 条武器统计
• 54 条时间窗口统计
• 54 条个人职业纪录
• 36 个 roster 二人组
• 200 个实际 2-5 人阵容组合
• 208 份赛后报告
• 885 份队员赛后对比
• 203 次职业纪录刷新事件
• 2 个战队赛季
• 111 个日/周/月/季/年度奖项
• 19 条正面/负面/趣味数据发现
• 36 枚地图与 ELO 分段勋章
• 40 项自动化测试通过
• 43 项数据完整性检查通过

数据规模会随导入变化，Admin 数据完整性中心显示的结果是运行时事实。

核心功能

玩家职业主页

• Rating、K/D、ADR、KAST 等生涯数据
• Aim、Clutch、Pistol、Defense、Utility、Stability、Economy、Pace 八维能力
• 生涯、最近 10/20/30 场、最近 30/90 天阶段统计
• 可切换时间窗口的 Rating 趋势
• 最高 Rating、最多击杀、最高 ADR、最高 K/D、最多爆头和最长连胜
• 每项个人纪录可追溯到具体比赛
• 地图表现、比赛历史、Party 信息、队内排名和留言板
• 缺失或尚未实现的指标显示为 N/A，不使用伪造分数

比赛中心

• 比赛列表、地图、比分、平均 ELO 和己方结果
• 自动赛后报告与队内 MVP
• 相对此前 20 场的 Rating、K/D、ADR 变化
• 本场纪录刷新、状态标签和最强二人组
• Active roster 与 Party 识别
• 双方玩家表现和 Rating 排序
• Head-to-head 击杀矩阵
• 回合事件、经济和装备信息
• 原始比赛数据查看

战队与战术

• Active roster 管理
• Roster version 生效区间和历史版本
• Starter、substitute、member 角色管理
• 战队履历、赛季战绩和地图表现
• 实际同队二人组与 2-5 人阵容组合
• 玩家搜索、签入和移出
• 2-5 人同队比赛与 Chemistry 分析
• 对手档案和真实交手记录
• 地图战术板、阵容数据中心和经济工具
• Wiki、玩家标签、备注和评论

赛季与荣誉

• 按日历年度生成战队赛季
• 赛季战绩、Rating、最佳地图和赛季选手
• 单日最佳、星期最佳、月度最佳、季度最佳、年度最佳
• 周/月/季/年奖项使用最低场次门槛
• 个人主页展示荣誉数量和近期奖章
• 每次职业纪录刷新保留时间和对应比赛

发现与勋章

• 独立 /discover/ 发现模块
• 高光、低谷和趣味数据同时展示
• 爆种、尽力局、躺赢、低谷、稳定性、夜间比赛和连胜等发现
• 每张达到门槛的地图评选金银铜
• 每个达到门槛的 ELO 分段评选金银铜
• 勋章最低 5 场，展示 Rating、K/D、ADR、胜率和样本数
• 个人职业主页同步展示已获得勋章

数据运营

• Admin 上传 iframe_network.json
• 自动识别唯一 g161-* 比赛 ID
• JSON 结构、必要接口、哈希和重复比赛校验
• 后台执行 L1 → L2 → L3
• 实时查看作业阶段、进度、日志和耗时
• 数据完整性中心与 JSON 报告
• 独立运营总览、比赛导入、作业中心、数据质量、查询控制台和系统信息
• 数据库对象目录与只读 SQL 执行耗时
• L1/L2/L3/Web 文件状态和回滚快照可视化
• 后台写操作使用 CSRF 防护

Docker 自托管

推荐给其他战队使用 Docker Compose：

cp .env.example .env
# 修改 SECRET_KEY、ADMIN_TOKEN、VIEWER_TOKEN

docker compose up -d --build

默认访问 http://127.0.0.1:5001。首次空安装：

1. 使用 .env 中的 ADMIN_TOKEN 登录 /admin/。
2. 首次启动向导创建战队和 roster。
3. 从 /admin/import-match 上传自己的 iframe_network.json。

运行数据保存在 YRTV_DATA_PATH，默认是 Git 忽略的 ./runtime-data。git pull 或重建镜像不会覆盖该目录。

迁移当前数据

当前仓库内已有数据迁移到外置目录：

make prepare-data
cp .env.example .env
docker compose up -d --build

迁移使用 SQLite Backup API，不修改源数据库，并生成 runtime-data/migration-manifest.json、SHA256 和 quick_check 结果。

Python 开发模式

环境要求：

• macOS/Linux
• Python 3.9+
• SQLite 3

安装并启动：

make install

export SECRET_KEY='replace-with-a-random-secret'
export ADMIN_TOKEN='replace-with-an-admin-token'

make run

默认地址：

• 应用：http://127.0.0.1:5000
• Admin：/admin/
• 比赛导入：/admin/import-match
• 数据完整性：/admin/data-integrity

生产进程入口：

.venv/bin/gunicorn wsgi:app

常用命令

make run       # 启动 Flask
make check     # 编译检查 + 自动化测试
make pipeline  # 备份后执行完整 L1 -> L2 -> L3
make bootstrap # 初始化空运行时数据库
make prepare-data # 复制现有数据到 runtime-data
make docker-up # 构建并启动容器
make docker-logs # 查看容器日志

make l1        # 仅构建 L1
make l2        # 仅构建 L2
make l3        # 仅构建 active roster L3
make l3-all    # 为全部采集玩家构建 L3

正常维护优先使用 make pipeline。单层命令主要用于开发和排错。

比赛导入

推荐从 Admin 页面上传完整的 iframe_network.json。

导入流程：

1. 验证 UTF-8 和 JSON 结构。
2. 从网络 URL 中提取唯一比赛 ID。
3. 检查 match 和 round 必要接口。
4. 计算 SHA256，拒绝相同数据重复导入。
5. 保存到 output_arena/<match_id>/iframe_network.json。
6. 创建 etl_jobs 作业。
7. 备份 L1/L2/L3。
8. 串行执行三个 Builder。
9. 验证目标比赛具有 10 名玩家和回合事实。
10. 成功提交；失败自动恢复备份。

仓库当前不包含自动访问 5E 网页的下载器，因此首页 URL 输入不会抓取数据。

数据架构

iframe_network.json
        |
        v
L1 raw capture
        |
        v
L2 normalized facts
        |
        v
L3 roster features and profile marts
        |
        v
Flask services and player profiles

L1：原始层

• 数据库：database/L1/L1.db
• Builder：database/L1/L1_Builder.py
• Grain：每场比赛一份完整网络抓包
• 核心表：raw_iframe_network

L2：事实层

• 数据库：database/L2/L2.db
• Schema：database/L2/schema.sql
• Builder：database/L2/L2_Builder.py
• 核心表：
  • dim_players
  • dim_maps
  • fact_matches
  • fact_match_teams
  • fact_match_players
  • fact_match_players_t
  • fact_match_players_ct
  • fact_rounds
  • fact_round_events
  • fact_round_player_economy

L3：特征与主页集市

• 数据库：database/L3/L3.db
• Schema：database/L3/schema.sql
• Builder：database/L3/L3_Builder.py
• 核心表：
  • dm_player_features
  • dm_player_match_history
  • dm_player_map_stats
  • dm_player_weapon_stats
  • dm_player_period_stats
  • dm_player_records
  • dm_duo_stats
  • dm_lineup_stats
  • dm_match_reports
  • dm_match_player_reports
  • dm_player_record_events
  • dm_team_season_stats
  • dm_player_awards
  • dm_discovery_insights
  • dm_performance_medals

Web：应用状态

• 数据库：database/Web/Web_App.sqlite
• Schema：database/Web/schema.sql
• 当前 schema version：3
• 保存 lineup、玩家备注、评论、Wiki、战术板、导入登记和 ETL 作业

数据库治理

• 所有运行路径集中定义在 database/paths.py
• YRTV_DATA_DIR 可将数据库、备份、锁和导入文件移出代码仓库
• 未设置 YRTV_DATA_DIR 时继续兼容原 database/ 数据路径
• 完整编排入口为 database/pipeline.py
• 同一时间只允许一个 pipeline
• Pipeline 运行前备份 L1/L2/L3
• 失败时恢复三层数据库，Web 作业日志继续保留
• 备份位于 database/backups/
• 自动保留最近 3 组备份
• Web schema 使用 schema_migrations 记录版本
• 高频玩家历史、Party、事件和经济查询具有专用索引
• 数据库和目录规则详见 database/README.md

访问模式

• SITE_VISIBILITY=public：前台公开，Admin 仍需令牌。
• SITE_VISIBILITY=private：前台需要 VIEWER_TOKEN。
• /healthz 始终开放给 Docker 和反向代理健康检查。
• 后台写操作具有 CSRF 防护。

Docker 示例默认使用 private。

品牌与许可证

• 主品牌：Superjacky6
• 项目签名：jacky / jk / yr / jacky0987
• 页面、报告、后台、元数据、CLI 和容器镜像保留品牌署名
• 比赛事实和统计指标中不写入水印
• 许可证：AGPL-3.0-or-later
• 署名规则：NOTICE.md

数据质量

Admin 数据完整性中心检查：

• 四个 SQLite 数据库的 quick_check
• 必要表和 Web schema version
• 玩家比赛、回合事件的引用完整性
• 每场比赛玩家数量
• 玩家身份覆盖
• 高频查询索引
• Active roster 的 L3 特征覆盖
• 逐场历史与总场次一致性
• 真实队内 percentile
• 地图、武器、时间窗口和职业纪录集市
• 占位空间指标
• Web 外键、active lineup 和 pipeline 并发
• 备份数量与存储规模

运行测试：

make check

目录结构

yrtv/
├── database/
│   ├── L1/                 # 原始抓包与 Builder
│   ├── L2/                 # 事实层、Schema、Processor
│   ├── L3/                 # 特征层、Schema、Processor
│   ├── Web/                # 应用数据库 Schema
│   ├── paths.py            # 统一路径
│   ├── maintenance.py      # 备份、恢复、健康检查
│   ├── job_store.py        # ETL 作业状态
│   └── pipeline.py         # 完整流水线
├── docker/
│   └── entrypoint.sh
├── tests/                  # 自动化测试
├── utils/                  # JSON 结构分析工具
├── web/
│   ├── routes/
│   ├── services/
│   ├── templates/
│   └── static/
├── Makefile
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── requirements.txt
└── wsgi.py

Beta 限制

• 当前主要数据源为 5E iframe 网络响应。
• 不包含自动网页下载器和 Demo parser。
• 支持独立 Viewer Token 和 Admin Token，但不提供开放注册或多用户权限系统。
• SQLite 适合当前单战队规模，不面向高并发多租户。
• 部分高级空间能力需要地图边界、路径和 Demo 数据，当前显示 N/A。
• StatsService 仍保留部分兼容逻辑；新功能已拆入 Player Profile、Team Performance、Roster Version 等领域服务。

版本

当前版本：2.0.0 Beta

这一版本的目标是建立可信、可恢复、可持续导入的私人战队 HLTV 基线，而不是冻结产品功能。