数据库文档

📋 目录

数据库概述
支持的数据库类型
数据库配置
数据库表结构
数据存储策略
数据库迁移
数据库备份与恢复
数据库优化
常见问题与排查

🔍 数据库概述

鍏夎氨Spectrum反作弊插件需要数据库来存储玩家数据、违规记录、惩罚信息和统计数据等。良好的数据库配置和管理对于插件的性能和稳定性至关重要。本文档详细介绍了鍏夎氨Spectrum支持的数据库类型、配置方法、表结构和优化建议。

🗄️ 支持的数据库类型

鍏夎氨Spectrum反作弊插件支持以下三种数据库类型：

1. SQLite

SQLite是鍏夎氨Spectrum反作弊插件的默认数据库选项，它是一个轻量级的文件数据库，不需要额外的服务器软件。

优点：

安装简单，无需额外配置
适合小型服务器和单机测试
文件格式便于备份和迁移

缺点：

并发性能较差
不适合大型服务器或高并发环境
数据量大时查询速度可能下降

2. MySQL

MySQL是一种流行的关系型数据库管理系统，适合中大型服务器使用。

优点：

并发性能良好
适合中大型服务器
支持高级查询和索引优化
数据量大时仍能保持较好性能

缺点：

需要额外安装和配置MySQL服务器
配置相对复杂
占用系统资源较多

3. MongoDB

MongoDB是一种NoSQL文档数据库，适合处理大量非结构化数据。

优点：

高性能的数据写入和查询
适合存储大量日志和记录数据
灵活的数据模型，便于扩展
分布式架构，支持横向扩展

缺点：

需要额外安装和配置MongoDB服务器
学习曲线较陡峭
事务支持不如关系型数据库完善

⚙️ 数据库配置

数据库配置位于plugins/鍏夎氨Spectrum/config.yml文件中的database部分。下面是各种数据库类型的详细配置方法。

SQLite配置

yaml

# SQLite数据库配置
database:
  type: sqlite
  sqlite:
    file: 鍏夎氨Spectrum.db
    journal_mode: WAL  # 预写式日志模式，提高性能
    synchronous: NORMAL  # 同步级别，NORMAL平衡了性能和安全性

配置参数说明：

type: 数据库类型，设置为sqlite
file: 数据库文件名，默认为鍏夎氨Spectrum.db，存储在插件数据文件夹中
journal_mode: 日志模式，建议使用WAL（预写式日志）以提高性能
synchronous: 同步级别，可选值为FULL（最安全）、NORMAL（平衡）、OFF（最高性能但不安全）

MySQL配置

yaml

# MySQL数据库配置
database:
  type: mysql
  mysql:
    host: localhost
    port: 3306
    database: 鍏夎氨Spectrum
    username: root
    password: password
    prefix: 鍏夎氨Spectrum_
    ssl: false
    pool_size: 10
    connection_timeout: 30
    query_timeout: 10

配置参数说明：

type: 数据库类型，设置为mysql
host: MySQL服务器地址，默认为localhost
port: MySQL服务器端口，默认为3306
database: 数据库名称，需要预先创建
username: MySQL用户名，需要有足够的权限
password: MySQL密码
prefix: 表前缀，避免表名冲突
ssl: 是否使用SSL连接，默认为false
pool_size: 数据库连接池大小，根据服务器规模调整
connection_timeout: 连接超时时间（秒）
query_timeout: 查询超时时间（秒）

MongoDB配置

yaml

# MongoDB数据库配置
database:
  type: mongodb
  mongodb:
    uri: mongodb://localhost:27017
    database: 鍏夎氨Spectrum
    collection_prefix: 鍏夎氨Spectrum_
    connection_timeout: 30
    socket_timeout: 10
    max_pool_size: 50

配置参数说明：

type: 数据库类型，设置为mongodb
uri: MongoDB连接字符串，包含服务器地址、端口等信息
database: 数据库名称
collection_prefix: 集合前缀，避免集合名冲突
connection_timeout: 连接超时时间（秒）
socket_timeout: 套接字超时时间（秒）
max_pool_size: 最大连接池大小

📊 数据库表结构

SQLite/MySQL表结构

1. 玩家表（players）

存储玩家的基本信息和状态。

sql

CREATE TABLE IF NOT EXISTS {prefix}players (
    id INTEGER PRIMARY KEY AUTO_INCREMENT,
    uuid VARCHAR(36) NOT NULL UNIQUE,
    name VARCHAR(16) NOT NULL,
    first_join TIMESTAMP NOT NULL,
    last_join TIMESTAMP NOT NULL,
    last_leave TIMESTAMP,
    total_joins INT DEFAULT 0,
    whitelisted BOOLEAN DEFAULT FALSE,
    bypass BOOLEAN DEFAULT FALSE,
    staff BOOLEAN DEFAULT FALSE,
    violations INT DEFAULT 0,
    PRIMARY KEY (id),
    UNIQUE KEY (uuid)
);

2. 违规记录表（violations）

存储玩家的违规记录。

sql

CREATE TABLE IF NOT EXISTS {prefix}violations (
    id INTEGER PRIMARY KEY AUTO_INCREMENT,
    player_id INT NOT NULL,
    check_type VARCHAR(50) NOT NULL,
    check_name VARCHAR(100) NOT NULL,
    confidence DOUBLE NOT NULL,
    message TEXT,
    server VARCHAR(50) NOT NULL,
    world VARCHAR(50) NOT NULL,
    x DOUBLE,
    y DOUBLE,
    z DOUBLE,
    timestamp TIMESTAMP NOT NULL,
    FOREIGN KEY (player_id) REFERENCES {prefix}players(id)
);

3. 惩罚记录表（punishments）

存储对玩家的惩罚记录。

sql

CREATE TABLE IF NOT EXISTS {prefix}punishments (
    id INTEGER PRIMARY KEY AUTO_INCREMENT,
    player_id INT NOT NULL,
    type VARCHAR(20) NOT NULL,
    reason TEXT NOT NULL,
    staff_id INT,
    staff_name VARCHAR(16),
    start_time TIMESTAMP NOT NULL,
    end_time TIMESTAMP,
    active BOOLEAN DEFAULT TRUE,
    ip_ban BOOLEAN DEFAULT FALSE,
    FOREIGN KEY (player_id) REFERENCES {prefix}players(id),
    FOREIGN KEY (staff_id) REFERENCES {prefix}players(id)
);

4. 统计数据表（statistics）

存储插件的统计数据。

sql

CREATE TABLE IF NOT EXISTS {prefix}statistics (
    id INTEGER PRIMARY KEY AUTO_INCREMENT,
    date DATE NOT NULL UNIQUE,
    warnings INT DEFAULT 0,
    kicks INT DEFAULT 0,
    tempbans INT DEFAULT 0,
    bans INT DEFAULT 0,
    detections INT DEFAULT 0,
    false_positives INT DEFAULT 0
);

5. 调试日志表（debug_logs）

存储调试模式下的日志信息。

sql

CREATE TABLE IF NOT EXISTS {prefix}debug_logs (
    id INTEGER PRIMARY KEY AUTO_INCREMENT,
    timestamp TIMESTAMP NOT NULL,
    player_id INT,
    message TEXT NOT NULL,
    level VARCHAR(20) NOT NULL,
    category VARCHAR(50),
    FOREIGN KEY (player_id) REFERENCES {prefix}players(id)
);

MongoDB集合结构

MongoDB使用集合（collections）代替表，使用文档（documents）代替行。以下是鍏夎氨Spectrum在MongoDB中使用的主要集合及其结构。

1. 玩家集合（players）

json

{
  "_id": ObjectId("60d5ec8a6d2b1c001f2e3a4b"),
  "uuid": "8667ba71-b85a-4004-af54-457a9734eed7",
  "name": "Notch",
  "firstJoin": ISODate("2023-06-25T10:30:00Z"),
  "lastJoin": ISODate("2023-07-01T14:22:35Z"),
  "lastLeave": ISODate("2023-07-01T15:45:12Z"),
  "totalJoins": 42,
  "whitelisted": false,
  "bypass": false,
  "staff": false,
  "violations": 5
}

2. 违规记录集合（violations）

json

{
  "_id": ObjectId("60d5ec8a6d2b1c001f2e3a4c"),
  "playerId": "8667ba71-b85a-4004-af54-457a9734eed7",
  "checkType": "MOVEMENT_FLIGHT",
  "checkName": "Flight",
  "confidence": 0.9,
  "message": "检测到飞行作弊",
  "server": "lobby",
  "world": "world",
  "location": {
    "x": 123.45,
    "y": 67.89,
    "z": -45.67
  },
  "timestamp": ISODate("2023-07-01T14:30:15Z")
}

3. 惩罚记录集合（punishments）

json

{
  "_id": ObjectId("60d5ec8a6d2b1c001f2e3a4d"),
  "playerId": "8667ba71-b85a-4004-af54-457a9734eed7",
  "type": "BAN",
  "reason": "使用飞行作弊",
  "staff": {
    "id": "12345678-1234-5678-abcd-1234567890ab",
    "name": "Admin"
  },
  "startTime": ISODate("2023-07-01T14:35:00Z"),
  "endTime": null,  // 永久封禁
  "active": true,
  "ipBan": false
}

4. 统计数据集合（statistics）

json

{
  "_id": ObjectId("60d5ec8a6d2b1c001f2e3a4e"),
  "date": ISODate("2023-07-01T00:00:00Z"),
  "warnings": 15,
  "kicks": 3,
  "tempbans": 2,
  "bans": 1,
  "detections": 124,
  "falsePositives": 2
}

5. 调试日志集合（debug_logs）

json

{
  "_id": ObjectId("60d5ec8a6d2b1c001f2e3a4f"),
  "timestamp": ISODate("2023-07-01T14:25:30Z"),
  "playerId": "8667ba71-b85a-4004-af54-457a9734eed7",
  "message": "[Movement] 位置: 123.45, 67.89, -45.67",
  "level": "INFO",
  "category": "MOVEMENT"
}

💾 数据存储策略

数据保留策略

鍏夎氨Spectrum反作弊插件提供了数据保留策略配置，允许服务器管理员控制各种数据的保留时间。

yaml

# 数据保留策略配置
storage:
  cleanup:
    enabled: true
    interval: 86400  # 清理间隔（秒），默认为24小时
    retention:
      violations: 30  # 违规记录保留天数
      punishments: 90  # 惩罚记录保留天数
      debug_logs: 7  # 调试日志保留天数
      stats: 365  # 统计数据保留天数

自动清理机制

鍏夎氨Spectrum会定期执行自动清理任务，删除超过保留期限的数据。自动清理任务在服务器空闲时运行，以减少对服务器性能的影响。

重要数据保护

永久封禁记录不会被自动清理
玩家基本信息（如UUID、名称等）不会被自动清理
清理操作前会进行数据备份，以防意外丢失

🔄 数据库迁移

当需要从一种数据库类型迁移到另一种数据库类型时，可以使用鍏夎氨Spectrum提供的数据库迁移工具。

迁移步骤

备份当前数据库：在进行任何迁移操作之前，务必先备份当前数据库。

启用迁移模式：在config.yml中配置迁移设置。

yaml

# 数据库迁移配置
migration:
  enabled: true
  source:
    type: sqlite
    # 源数据库的具体配置
  target:
    type: mysql
    # 目标数据库的具体配置

执行迁移命令：使用/鍏夎氨Spectrum migration start命令开始迁移过程。
监控迁移进度：迁移过程中可以使用/鍏夎氨Spectrum migration status命令查看进度。
验证迁移结果：迁移完成后，使用/鍏夎氨Spectrum migration verify命令验证数据是否完整迁移。
禁用迁移模式：迁移完成并验证成功后，在config.yml中禁用迁移模式。

迁移注意事项

迁移过程可能需要较长时间，具体取决于数据量大小
迁移期间建议暂时关闭服务器或限制玩家活动
迁移完成后，确保更新主配置文件中的数据库设置
保留原数据库备份一段时间，直到确认新数据库正常工作

🛡️ 数据库备份与恢复

手动备份

SQLite数据库：直接复制鍏夎氨Spectrum.db文件到安全位置。

MySQL数据库：使用mysqldump工具导出数据库。

bash

mysqldump -u username -p password 鍏夎氨Spectrum > 鍏夎氨Spectrum_backup.sql

MongoDB数据库：使用mongodump工具导出数据库。

bash

mongodump --db 鍏夎氨Spectrum --out 鍏夎氨Spectrum_backup

自动备份

鍏夎氨Spectrum提供了自动备份功能，可以定期备份数据库。

yaml

# 自动备份配置
backup:
  enabled: true
  interval: 43200  # 备份间隔（秒），默认为12小时
  retention: 7  # 保留备份数量
  path: backups/  # 备份文件存储路径
  compression: true  # 是否压缩备份文件

数据库恢复

SQLite数据库：关闭服务器，替换鍏夎氨Spectrum.db文件，然后重启服务器。

MySQL数据库：使用mysql命令导入备份文件。

bash

mysql -u username -p password 鍏夎氨Spectrum < 鍏夎氨Spectrum_backup.sql

MongoDB数据库：使用mongorestore工具恢复数据库。

bash

mongorestore --db 鍏夎氨Spectrum 鍏夎氨Spectrum_backup/鍏夎氨Spectrum

⚡ 数据库优化

SQLite优化

使用WAL模式：设置journal_mode: WAL以提高并发性能。
调整同步级别：设置 synchronous: NORMAL以平衡性能和安全性。

定期压缩数据库：使用VACUUM命令回收未使用的空间。

yaml

# 在config.yml中启用定期VACUUM
sqlite:
  auto_vacuum: true
  vacuum_interval: 604800  # 每7天执行一次VACUUM

避免频繁事务：减少小事务的数量，合并相关操作。

MySQL优化

调整连接池：根据服务器规模调整pool_size参数。
优化索引：确保常用查询字段有合适的索引。
定期维护：执行OPTIMIZE TABLE命令优化表结构。
配置缓存：调整MySQL的缓存设置以提高性能。
使用InnoDB引擎：确保表使用InnoDB引擎以获得更好的并发性能。

MongoDB优化

调整连接池：根据服务器规模调整max_pool_size参数。
优化查询：使用索引和投影优化查询性能。
分片集群：对于大型服务器，考虑使用MongoDB分片集群。
预分配空间：减少数据文件的动态增长。
定期维护：执行db.repairDatabase()命令修复和优化数据库。

通用优化建议

合理设置数据保留期限：不要保留过多不需要的历史数据。
优化查询语句：避免使用复杂的、低效的查询语句。
监控数据库性能：定期检查数据库性能指标，及时发现问题。
分离热点数据：将频繁访问的数据与历史数据分离。
考虑服务器资源：确保服务器有足够的CPU、内存和磁盘空间。

❓ 常见问题与排查

连接问题

症状：插件无法连接到数据库，日志中显示连接错误。

排查步骤：

检查数据库服务是否正在运行
验证连接参数（主机名、端口、用户名、密码等）是否正确
检查防火墙设置是否阻止了连接
确认数据库用户是否有足够的权限

解决方案：

yaml

# 增加连接超时时间
mysql:
  connection_timeout: 60

# 启用连接重试
connection_retry:
  enabled: true
  max_retries: 3
  retry_delay: 5000  # 毫秒

性能问题

症状：数据库查询缓慢，导致插件延迟或服务器卡顿。

排查步骤：

检查数据库服务器的资源使用情况（CPU、内存、磁盘）
分析慢查询日志，找出性能瓶颈
检查索引是否正确创建和使用
确认数据量是否超过了当前数据库类型的最佳处理能力

解决方案：

yaml

# 优化查询超时设置
mysql:
  query_timeout: 15

# 增加连接池大小（根据服务器规模调整）
mysql:
  pool_size: 20

数据一致性问题

症状：数据库中存在不一致的数据，或部分数据丢失。

排查步骤：

检查服务器是否有意外关机或崩溃的情况
验证数据库完整性约束是否被违反
检查是否有并发操作导致的数据冲突

解决方案：

yaml

# 启用事务支持
mysql:
  use_transactions: true

# 增加同步级别（牺牲性能换取数据安全性）
sqlite:
  synchronous: FULL

存储空间问题

症状：数据库文件过大，占用过多磁盘空间。

排查步骤：

检查数据保留策略是否合理
确认是否有大量冗余数据
检查是否有未清理的临时数据或日志

解决方案：

yaml

# 调整数据保留策略
storage:
  cleanup:
    enabled: true
    retention:
      violations: 15  # 减少违规记录保留天数
      debug_logs: 3   # 减少调试日志保留天数

# 启用自动压缩
mysql:
  auto_optimize: true
  optimize_interval: 86400  # 每天执行一次优化

SQLite锁定问题

症状：SQLite数据库出现锁定错误，导致操作失败。

排查步骤：

检查是否有多个进程同时访问数据库
确认事务处理是否得当
验证数据库连接是否正确关闭

解决方案：

yaml

# 使用WAL模式
sqlite:
  journal_mode: WAL

# 调整锁定超时
sqlite:
  busy_timeout: 3000  # 毫秒

最后更新时间：2025年10月2日

数据库文档 ​

📋 目录 ​

🔍 数据库概述 ​

🗄️ 支持的数据库类型 ​

1. SQLite ​

2. MySQL ​

3. MongoDB ​

⚙️ 数据库配置 ​

SQLite配置 ​

MySQL配置 ​

MongoDB配置 ​

📊 数据库表结构 ​

SQLite/MySQL表结构 ​

1. 玩家表（players） ​

2. 违规记录表（violations） ​

3. 惩罚记录表（punishments） ​

4. 统计数据表（statistics） ​

5. 调试日志表（debug_logs） ​

MongoDB集合结构 ​

1. 玩家集合（players） ​

2. 违规记录集合（violations） ​

3. 惩罚记录集合（punishments） ​

4. 统计数据集合（statistics） ​

5. 调试日志集合（debug_logs） ​

💾 数据存储策略 ​

数据保留策略 ​

自动清理机制 ​

重要数据保护 ​

🔄 数据库迁移 ​

迁移步骤 ​

迁移注意事项 ​

🛡️ 数据库备份与恢复 ​

手动备份 ​

自动备份 ​

数据库恢复 ​

⚡ 数据库优化 ​

SQLite优化 ​

MySQL优化 ​

MongoDB优化 ​

通用优化建议 ​

❓ 常见问题与排查 ​

连接问题 ​

性能问题 ​

数据一致性问题 ​

存储空间问题 ​

SQLite锁定问题 ​

数据库文档

📋 目录

🔍 数据库概述

🗄️ 支持的数据库类型

1. SQLite

2. MySQL

3. MongoDB

⚙️ 数据库配置

SQLite配置

MySQL配置

MongoDB配置

📊 数据库表结构

SQLite/MySQL表结构

1. 玩家表（players）

2. 违规记录表（violations）

3. 惩罚记录表（punishments）

4. 统计数据表（statistics）

5. 调试日志表（debug_logs）

MongoDB集合结构

1. 玩家集合（players）

2. 违规记录集合（violations）

3. 惩罚记录集合（punishments）

4. 统计数据集合（statistics）

5. 调试日志集合（debug_logs）

💾 数据存储策略

数据保留策略

自动清理机制

重要数据保护

🔄 数据库迁移

迁移步骤

迁移注意事项

🛡️ 数据库备份与恢复

手动备份

自动备份

数据库恢复

⚡ 数据库优化

SQLite优化

MySQL优化

MongoDB优化

通用优化建议

❓ 常见问题与排查

连接问题

性能问题

数据一致性问题

存储空间问题

SQLite锁定问题