Cola-CSGO-API

简体中文 | English | Русский

本项目是一个高性能的 CSGO 社区服务器状态查询后端，基于 FastAPI 构建。它旨在为前端提供实时、准确的服务器信息。

通过本 API，您可以获取以下详细数据：

• 服务器基础信息: 获取每个服务器的 主机名、IP地址、端口号、当前地图 以及 在线状态。
• 实时流量统计: 精确掌握服务器的 当前在线人数 和 最大玩家容量，方便流量监控。
• 深层玩家洞察: 不仅仅是人数，您可以获取每位玩家的 游戏昵称 和 在线时长。
• 社交互动增强: 独家集成 Steam 社交数据，自动匹配并返回玩家的 Steam 32位/64位 ID、个人资料主页链接 以及 高清头像 (Avatar)，极大地丰富了前端展示效果。

🌐 已使用本项目的网站: HVH.ONE Servers

🚀 极速上手 (One-Click Start)

无需繁琐配置，自动管理环境依赖。

• Windows 用户: 双击直接运行 cola.bat
• Linux 用户: 运行终端命令 bash cola.sh

脚本会自动执行：创建虚拟环境 -> 安装依赖 -> 启动服务 (默认端口 6969)。

💖 项目支持者

**UAPI**        **HVH.ONE 社区**

✨ 核心特性

• 轻量高效：使用 Python 3.10+ 和 FastAPI，支持高并发查询。
• 多服管理：通过 JSON 配置文件轻松管理多个服务器组和节点。
• 协议支持：
  • A2S 查询：获取服务器实时人数、地图、标签。
  • RCON 支持：自动获取详细玩家列表（得分、在线时长）。
• 智能缓存：
  • 优先使用 Redis 进行持久化缓存。
  • 自动降级：若未配置 Redis 或连接失败，自动切换为内存缓存。
• 头像获取：内置 Steam 头像获取服务（对接 UAPI），大幅减少前端请求压力。
• 全自动部署：内置 Windows/Linux 一键启动脚本。

⚙️ 配置文件说明 (servers.json)

请在项目根目录创建 servers.json (参考 servers.example.json)。

{
    "groups": [
        {
            "label": "大组名称 (如: 北京机房)",
            "server_ip": "服务器共用公网IP",
            "rcon_password": "RCON密码",
            "servers": [ 
                {
                    "port": 27015,
                    "name": "显示在前端的服务器名",
                    "tags": ["标签1", "标签2"]
                }
            ]
        }
    ]
}

🔌 前端对接指南

本 API 提供标准的 JSON 接口，前端请求以下地址即可获取完整数据：

GET /api/servers

响应参数说明

服务器信息 (data 数组)

字段	说明
id	组内排序 ID
group	分组名称
name	服务器名称
host	服务器 IP
port	服务器端口
online	在线状态 (true/false)
map	当前地图
players	在线人数
max	最大人数
player_list	玩家列表详情

玩家信息 (player_list 数组)

字段	说明
name	玩家昵称
connected	在线时长 (e.g. 00:30:15)
steam_id	Steam ID
avatar	头像 URL (高清)
profile_url	个人主页链接

响应数据示例:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "group": "北京机房",
      "name": "竞技服务器",
      "host": "123.1.1.1",
      "port": 27015,
      "online": true,
      "map": "de_mirage",
      "players": 10,
      "max": 64,
      "player_list": [
        {
          "name": "Player1",
          "connected": "00:45:00",
          "steam_id": "STEAM_1:0:123456",
          "avatar": "https://steamcdn.../avatar.jpg",
          "profile_url": "https://steamcommunity.com/id/..."
        }
      ]
    }
  ]
}

🛠️ 手动部署指南

如果你想手动控制部署流程：

1. 环境准备：

   • Python 3.10+
   • (可选) Redis

2. 配置：

   • env.example -> .env
   • servers.example.json -> servers.json

3. 运行：

   # 安装依赖
   pip install -r requirements.txt
   # 启动
   python -m uvicorn main:app --host 0.0.0.0 --port 6969

   • API Docs: http://localhost:6969/docs

📂 目录结构

• main.py: 程序入口。
• servers.json: 服务器列表数据。
• routers/: API 路由。
• services/: 业务逻辑。
• utils/: 工具类。

📝 贡献

欢迎提交 Issue 或 Pull Request。

📜 开源协议

本项目采用 GNU General Public License v3.0 开源协议。