callmebeachy/jokerz-builds

Joker Builds - 《流放之路》Build分析系统

一款针对《流放之路》build的综合数据收集与分析系统，具备自动梯子跟踪、build分类、有效生命值（EHP）计算及Web仪表盘监控等功能。

!https://img.shields.io/docker/pulls/callmebeachy/jokerz-builds !https://img.shields.io/docker/image-size/callmebeachy/jokerz-builds !https://github.com/mufasadb/jokerz-builds/workflows/Build%20and%20Push%20Docker%20Image/badge.svg !https://img.shields.io/github/stars/mufasadb/jokerz-builds

核心功能

• 🔄 每日自动收集 - 从多个联赛收集梯子快照
• 📊 Build分类 - 按伤害类型、防御风格和成本分类build
• 🛡️ EHP计算 - 计算针对所有伤害类型的有效生命值
• 🌐 Web仪表盘 - 带图表和统计数据的实时监控
• 🤖 机器人支持 - 集成机器人的接口
• 🔍 高级搜索 - 按坦克度等多条件查询build
• 🧹 自动清理 - 可配置的历史数据保留策略

快速开始

Docker Hub拉取

bash
docker pull callmebeachy/jokerz-builds:latest

Docker Compose（推荐）

bash
# 创建目录
mkdir -p /mnt/user/appdata/joker-builds

# 进入目录并创建docker-compose.yml（见下文）
cd /mnt/user/appdata/joker-builds

# 启动服务
docker-compose up -d

Unraid设置指南

方法1：社区应用（即将推出）

在社区应用中搜索"Joker Builds"

方法2：Docker模板

1. 进入Unraid的Docker标签页
2. 点击"Add Container"
3. 切换到"Advanced View"
4. 填写以下内容：

容器设置：

• 名称: joker-builds
• 仓库: callmebeachy/jokerz-builds:latest
• Docker Hub URL: https://hub.docker.com/r/callmebeachy/jokerz-builds
• 图标URL: https://web.poecdn.com/image/Art/2DItems/Currency/CurrencyRerollRare.png

网络设置：

• 网络类型: bridge
• 控制台shell命令: Shell

端口映射（添加端口）：

路径映射（添加路径）：

变量映射（添加变量）：

额外参数：

--restart=unless-stopped

方法3：Docker Compose（推荐）

创建 /mnt/user/appdata/joker-builds/docker-compose.yml：

yaml
version: '3.8'

services:
  joker-builds-collector:
    image: callmebeachy/jokerz-builds:latest
    container_name: joker-builds-collector
    restart: unless-stopped
    
    environment:
      - COLLECTION_TIME=02:00  # 2 AM UTC = 9 PM EST / 6 PM PST
      - CLEANUP_TIME=03:00
      - CLEANUP_DAYS=90
      - LOG_LEVEL=INFO
      
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
    
    command: python -m src.scheduler.daily_collector

  dashboard:
    image: callmebeachy/jokerz-builds:latest
    container_name: joker-builds-dashboard
    restart: unless-stopped
    
    environment:
      - FLASK_ENV=production
    
    volumes:
      - ./data:/app/data  # 与收集器共享
    
    ports:
      - "5000:5000"
    
    command: python web_dashboard.py
    
    depends_on:
      - joker-builds-collector

然后运行：

bash
cd /mnt/user/appdata/joker-builds
docker-compose up -d

配置

环境变量

时区参考

收集时间使用UTC时间，常见转换：

• 02:00 UTC = 前一天晚上9点（EST）/ 下午6点（PST）
• 14:00 UTC = 上午9点（EST）/ 上午6点（PST）

Web仪表盘

访问地址：http://[UNRAID-IP]:5000

仪表盘功能

1. 概览卡片

   • 总API请求数（24小时/7天）及成功率
   • 数据库中的角色总数
   • ***机器人使用统计
   • 最近请求时间戳

2. 图表

   • 7天内按API类型的请求时间线
   • 请求分布饼图
   • 每30秒自动刷新

3. 活动 feed

   • 最新成功的数据拉取
   • 角色 profile 直接链接
   • 带时间戳的最近错误

4. API监控

   • 按类型的请求计数
   • 成功/失败率
   • 响应时间

5. 手动数据收集

   • 按需启动收集
   • 实时进度监控
   • 联赛选择选项
   • 通过WebSocket的实时状态更新

数据收集

收集内容

1. 监控的联赛（自动检测）

   • 标准与 hardcore（永久）
   • 当前挑战联赛及所有变体（SC/HC/SSF）

2. 每个联赛的数据

   • 前2000个角色
   • 角色 stats、技能、物品
   • Build分类
   • EHP计算

3. 收集计划

   • 每日在 COLLECTION_TIME 运行
   • 每天增强800+角色profile
   • 自动限速（尊重GGG的API）

API速率限制

为尊重GGG服务器设置保守限制：

• 梯子API: 4次/分钟，15次/小时
• 角色API: 3次/分钟，12次/小时
• 失败时自动指数退避

***机器人集成

基础设置

python
from discord_bot_interface import DiscordBotInterface

interface = DiscordBotInterface()

# 搜索build
@bot.command()
async def tanky_fire(ctx):
    results = interface.search_builds(
        damage_type='fire',
        tankiness='Extremely Tanky',
        user_id=ctx.author.id,
        limit=5
    )
    # 格式化并发送结果

可用方法

• search_builds() - 按伤害类型、坦克度、EHP搜索
• get_character_details() - 获取特定角色信息
• get_top_builds() - 获取排行榜build

所有***查询都会自动记录到仪表盘统计中。

数据库访问

SQLite数据库位置

/mnt/user/appdata/joker-builds/data/ladder_snapshots.db

查询示例

python
from src.storage.database import DatabaseManager

db = DatabaseManager()

# 查找极坦克的build
tanky = db.search_builds_by_category(
    tankiness_rating='Extremely Tanky',
    min_ehp=20000
)

# 查找经济型火焰build
budget_fire = db.search_builds_by_category(
    damage_type='fire',
    cost_tier='budget'
)

直接SQL访问

bash
# 进入容器
docker exec -it joker-builds-collector /bin/bash

# 查询数据库
sqlite3 /app/data/ladder_snapshots.db

# 示例查询
SELECT COUNT(*) FROM characters;
SELECT league, COUNT(*) FROM characters GROUP BY league;
SELECT tankiness_rating, COUNT(*) FROM characters 
  WHERE tankiness_rating IS NOT NULL 
  GROUP BY tankiness_rating;

维护

手动操作

通过Web仪表盘（推荐）：

• 导航到 http://[UNRAID-IP]:5000
• 使用"数据收集控制"面板
• 选择联赛和选项
• 点击"开始收集"
• 监控实时进度

通过命令行：

bash
# 检查收集状态
docker exec joker-builds-collector python -m src.scheduler.daily_collector --status

# 强制立即收集
docker exec joker-builds-collector python -m src.scheduler.daily_collector --once

# 手动清理
docker exec joker-builds-collector python -m src.scheduler.daily_collector --cleanup

监控

bash
# 查看日志
docker logs joker-builds-collector -f
docker logs joker-builds-dashboard -f

# 检查健康状态
docker ps | grep joker-builds

备份

数据库存储位置： /mnt/user/appdata/joker-builds/data/ladder_snapshots.db

定期备份或使用Unraid的appdata备份功能。

故障排除

容器无法启动

bash
# 检查日志
docker logs joker-builds-collector

# 验证权限
ls -la /mnt/user/appdata/joker-builds/

# 重新创建目录
mkdir -p /mnt/user/appdata/joker-builds/{data,logs}
chmod -R 755 /mnt/user/appdata/joker-builds

无数据显示

• 等待 COLLECTION_TIME 到来
• 检查日志中的API错误
• 验证网络连接
• 确保理解正确的时区（UTC）

仪表盘无法加载

• 检查端口5000是否空闲：netstat -tulpn | grep 5000
• 验证仪表盘容器是否运行
• 检查防火墙设置
• 从Unraid终端尝试 http://localhost:5000

内存占用过高

• 减少 CLEANUP_DAYS 以存储更少历史数据
• 检查是否有失控的收集进程
• 重启容器

开发

本地设置

bash
git clone https://github.com/mufasadb/jokerz-builds.git
cd jokerz-builds
pip install -r requirements.txt
python -m pytest tests/

本地构建

bash
docker build -t jokerz-builds:local .

支持

• 问题反馈: https://github.com/mufasadb/jokerz-builds/issues
• Docker Hub: https://hub.docker.com/r/callmebeachy/jokerz-builds

许可证

MIT许可证 - 详见LICENSE文件

致谢

• Grinding Gear Games提供的《流放之路》API
• PoE Ninja的数据洞察
• 《流放之路》社区的build多样性