g0v0-server

简体中文 | English

This is an osu! API server implemented with FastAPI + MySQL + Redis, supporting most features of osu! API v1, v2, and osu!lazer.

Features

• OAuth 2.0 Authentication: Supports password and refresh token flows.
• User Data Management: Complete user information, statistics, achievements, etc.
• Multi-game Mode Support: osu! (RX, AP), taiko (RX), catch (RX), mania.
• Database Persistence: MySQL for storing user data.
• Cache Support: Redis for caching tokens and session information.
• Multiple Storage Backends: Supports local storage, Cloudflare R2, and AWS S3.
• Containerized Deployment: Docker and Docker Compose support.

Quick Start

Using Docker Compose (Recommended)

1. Clone the project

   git clone https://github.com/GooGuTeam/g0v0-server.git
   cd g0v0-server
   

2. Create a .env file

   Please see the server configuration below to modify the .env file.

   cp .env.example .env
   

3. Start the service

   # Standard server
   docker-compose -f docker-compose.yml up -d
   # Enable osu!RX and osu!AP statistics (ppy-sb pp algorithm)
   docker-compose -f docker-compose-osurx.yml up -d
   

4. Connect to the server from the game

   Use a custom osu!lazer client, or use LazerAuthlibInjection, and change the server settings to the server's address.

Configuration

Database Settings

Variable Name	Description	Default Value
MYSQL_HOST	MySQL host address	localhost
MYSQL_PORT	MySQL port	3306
MYSQL_DATABASE	MySQL database name	osu_api
MYSQL_USER	MySQL username	osu_api
MYSQL_PASSWORD	MySQL password	password
MYSQL_ROOT_PASSWORD	MySQL root password	password
REDIS_URL	Redis connection string	redis://127.0.0.1:6379/0

JWT Settings

Variable Name	Description	Default Value
JWT_SECRET_KEY	JWT signing key	your_jwt_secret_here
ALGORITHM	JWT algorithm	HS256
ACCESS_TOKEN_EXPIRE_MINUTES	Access token expiration time (minutes)	1440

Server Settings

Variable Name	Description	Default Value
HOST	Server listening address	0.0.0.0
PORT	Server listening port	8000
DEBUG	Debug mode	false
SERVER_URL	Server URL	http://localhost:8000
CORS_URLS	Additional CORS allowed domain list (JSON format)	[]
FRONTEND_URL	Frontend URL, redirects to this URL when accessing URLs opened from the game. Empty means no redirection.	(null)

OAuth Settings

Variable Name	Description	Default Value
OSU_CLIENT_ID	OAuth client ID	5
OSU_CLIENT_SECRET	OAuth client secret	FGc9GAtyHzeQDshWP5Ah7dega8hJACAJpQtw6OXk
OSU_WEB_CLIENT_ID	Web OAuth client ID	6
OSU_WEB_CLIENT_SECRET	Web OAuth client secret	your_osu_web_client_secret_here

SignalR Server Settings

Variable Name	Description	Default Value
SIGNALR_NEGOTIATE_TIMEOUT	SignalR negotiation timeout (seconds)	30
SIGNALR_PING_INTERVAL	SignalR ping interval (seconds)	15

Fetcher Settings

The Fetcher is used to get data from the official osu! API using OAuth 2.0 authentication.

Variable Name	Description	Default Value
FETCHER_CLIENT_ID	Fetcher client ID	""
FETCHER_CLIENT_SECRET	Fetcher client secret	""
FETCHER_SCOPES	Fetcher scopes	public

Log Settings

Variable Name	Description	Default Value
LOG_LEVEL	Log level	INFO

Sentry Settings

Variable Name	Description	Default Value
SENTRY_DSN	Sentry DSN, empty to disable Sentry	(null)

Game Settings

Variable Name	Description	Default Value
ENABLE_RX	Enable RX mod statistics	false
ENABLE_AP	Enable AP mod statistics	false
ENABLE_ALL_MODS_PP	Enable PP calculation for all mods	false
ENABLE_SUPPORTER_FOR_ALL_USERS	Enable supporter status for all new users	false
ENABLE_ALL_BEATMAP_LEADERBOARD	Enable leaderboards for all beatmaps	false
ENABLE_ALL_BEATMAP_PP	Allow any beatmap to grant PP	false
SUSPICIOUS_SCORE_CHECK	Enable suspicious score check (star>25 & acc<80 or pp>2300)	true
SEASONAL_BACKGROUNDS	List of seasonal background URLs	[]
BANNED_NAME	List of banned usernames	["mrekk", "vaxei", "btmc", "cookiezi", "peppy", "saragi", "chocomint"]

Storage Service Settings

Used for storing replay files, avatars, and other static assets.

Variable Name	Description	Default Value
STORAGE_SERVICE	Storage service type: local, r2, s3	local
STORAGE_SETTINGS	Storage service configuration (JSON format), see below for configuration	{"local_storage_path": "./storage"}

Storage Service Configuration

Local Storage (Recommended for development)

Local storage saves files to the server's local filesystem, suitable for development and small-scale deployments.

STORAGE_SERVICE="local"
STORAGE_SETTINGS='{"local_storage_path": "./storage"}'

Cloudflare R2 Storage (Recommended for production)

STORAGE_SERVICE="r2"
STORAGE_SETTINGS='{
  "r2_account_id": "your_cloudflare_account_id",
  "r2_access_key_id": "your_r2_access_key_id",
  "r2_secret_access_key": "your_r2_secret_access_key",
  "r2_bucket_name": "your_bucket_name",
  "r2_public_url_base": "https://your-custom-domain.com"
}'

AWS S3 Storage

STORAGE_SERVICE="s3"
STORAGE_SETTINGS='{
  "s3_access_key_id": "your_aws_access_key_id",
  "s3_secret_access_key": "your_aws_secret_access_key",
  "s3_bucket_name": "your_s3_bucket_name",
  "s3_region_name": "us-east-1",
  "s3_public_url_base": "https://your-custom-domain.com"
}'

Note

: In a production environment, be sure to change the default keys and passwords!

Updating the Database

Refer to the Database Migration Guide

License

MIT License

Contributing

The project is currently in a state of rapid iteration. Issues and Pull Requests are welcome!

Discussion

• Discord: https://discord.gg/AhzJXXWYfF
• QQ Group: 1059561526