pppy/osu-elastic-indexer

ElasticIndexer

用于将osu!分数从MySQL加载到Elasticsearch的组件。

依赖环境

• .NET 6
• Elasticsearch 7
• Redis 6

Elasticsearch 8兼容性

若使用Elasticsearch 8，需至少为8.2版本。需在索引器上设置以下环境变量：

bash
ELASTIC_CLIENT_APIVERSIONING=true

并在Elasticsearch服务器配置elasticsearch.yml中设置：

yml
xpack.security.enabled: false

或在Docker环境中（如docker-compose）：

yml
environment:
  xpack.security.enabled: false

这将启用Elasticsearch的HTTP连接，禁用HTTPS和认证要求，并向客户端返回兼容响应。

使用说明

模式（Schema）

使用字符串值指示当前要使用的模式版本。

队列处理器运行时，会将其处理的版本存储在Redis的集合osu-queue:score-index:${prefix}active-schemas中。

若队列处理器因模式版本更改自动停止，会将其处理的版本从集合中移除；若手动停止或因故障停止，则不会移除，以允许其他服务继续向这些队列推送数据。

添加待索引项

preserve=true且所属用户user_warnings=0的分数将被添加到索引；任一条件不满足的分数将从索引中移除。

将项推送到队列osu-queue:score-index-${schema}。

切换到新模式

运行dotnet run schema set ${schema}，或直接在Redis中设置osu-queue:score-index:${prefix}schema。

配置参数

配置通过环境变量加载，不自动加载环境文件。若需从环境文件读取，可前缀命令：env $(cat {envfile})（注：此方式不支持含空格的值），例如：

env $(cat .env) dotnet run

环境变量说明

BATCH_SIZE

每批处理的最大项数，影响发送到Elasticsearch的_bulk请求大小。

默认值：10000。

BUFFER_SIZE

队列处理期间允许的最大在飞行项数（BATCH_SIZE * BUFFER_SIZE）。

默认值：5（默认共50000项）。

DB_HOST

MySQL主机地址。

默认值：localhost。

DB_USER

数据库用户名。

默认值：root。

ES_INDEX_PREFIX

Elasticsearch索引名的可选前缀。

ES_HOST

Elasticsearch主机URL。

默认值：http://localhost:9200。

REDIS_HOST

Redis连接字符串；配置选项参见https://stackexchange.github.io/StackExchange.Redis/Configuration.html#configuration-options%E3%80%82

默认值：localhost。

SCHEMA

队列的模式版本；参见模式。

DB_CONNECTION_STRING

MySQL连接字符串（Docker部署中使用）。

命令说明

本文档假设可使用dotnet run；若不可用，可直接使用程序集，例如dotnet osu.ElasticIndexer.dll。

监控队列获取新分数

运行queue命令会自动创建索引（若不存在匹配请求模式的开放索引）；若存在，则复用。

SCHEMA=${schema} dotnet run queue watch

示例：

SCHEMA=1 dotnet run queue watch

获取当前模式版本

dotnet run schema get

设置模式版本

dotnet run schema set ${schema}

清除模式版本

用于测试目的清除模式版本：

dotnet run schema clear

手动更改别名指向新索引

可手动更改别名指向的索引：

dotnet run schema alias ${schema}

将更新索引别名至带模式${schema}标签的最新索引。

列出索引

列出所有索引及其状态（模式、别名、开放/关闭）：

dotnet run index list

关闭未使用索引

关闭除活动索引外的所有分数索引，释放Elasticsearch内存：

dotnet run index close

可指定索引名称关闭特定索引，例如关闭index_1：

dotnet run index close index_1

清理已关闭索引

删除所有处于closed状态的索引，释放存储空间：

dotnet run index delete

可指定索引名称删除特定索引：

dotnet run index delete index_1

添加测试项到队列

为测试目的添加假项到队列：

SCHEMA=1 dotnet run queue pump-fake

注意：这些项不存在于数据库中，也不匹配实际数据。

索引特定分数

按ID索引分数：

SCHEMA=${schema} dotnet run queue pump-score ${id}

示例：

SCHEMA=1 dotnet run queue pump-score 1

批量索引现有数据库记录

读取现有solo_scores并添加到队列（仅含对应phpbb_users条目的分数会被 queued）：

SCHEMA=1 dotnet run queue pump-all

额外选项：

• --from {id}：从指定solo_scores.id开始读取
• --switch：最后一项入队后设置模式版本（不等待索引完成，用于测试）

列出当前处理的模式版本

列出已知有队列处理器监听的版本：

dotnet run active-schemas list

手动添加/移除处理版本

用于调试或手动维护：

dotnet run active-schemas add ${schema}
dotnet run active-schemas remove ${schema}

（重新）填充索引

通过向队列推送分数项来填充索引。

Docker部署

构建镜像

docker build -t ${tagname} -f osu.ElasticIndexer/Dockerfile osu.ElasticIndexer

运行容器

docker run -e SCHEMA=1 -e "ES_HOST=[***]" -e "ES_INDEX_PREFIX=docker." -e "REDIS_HOST=host.docker.internal" -e "DB_CONNECTION_STRING=Server=host.docker.internal;Database=osu;Uid=osuweb;SslMode=None;" ${tagname} ${cmd}

其中${cmd}为要运行的命令，例如dotnet osu.ElasticIndexer.dll queue watch。

典型使用场景

从其他客户端队列处理项

向Redis队列osu-queue:score-index-${schema}推送项，例如：

C#示例

csharp
ListLeftPush("osu-queue:score-index-1", "{ \"ScoreId\": 1 }");

Redis-cli示例

bash
LPUSH "osu-queue:score-index-1" "{\"ScoreId\":1}"

按ID索引分数

json
{ "ScoreId": 1 }

队列完整分数对象

json
{
    "Score": {Solo.Score}
}

命令行参数示例

监控队列

docker run -e SCHEMA=1 -e ES_HOST=[***] -e REDIS_HOST=redis ${tagname} dotnet osu.ElasticIndexer.dll queue watch

获取当前模式版本

docker run -e REDIS_HOST=redis ${tagname} dotnet osu.ElasticIndexer.dll schema get