原创 前置/API 工具 WebItem | Web管理插件 2.1.7

# 插件配置文件

lang: "zh-CN" # 语言配置

# ==========================================
# 运行模式配置
# ==========================================
# mode 有三种：
#   "standalone" - 单端模式（默认）：Bukkit 插件自带 HTTP/WebSocket 服务器
#   "worker"     - Worker 模式：HTTP/WebSocket 由 Velocity 插件承载，Bukkit 仅响应 Plugin Message
#   "hybrid"     - 混合模式：同时启用本地 HTTP/WS 服务器和 Plugin Message 通道
#                  适用于：Velocity 网关统一入口 + 各子服也可直接调用
mode: "standalone"

# 全局数据库配置（供在线时长、交易记录等模块使用）
database:
  type: "sqlite" # 数据库类型：sqlite（默认，零配置）、mysql
  table-prefix: "webitem_" # 表名前缀
  # MySQL 配置（仅 type: mysql 时生效）
  mysql:
    host: "localhost"
    port: 3306
    database: "minecraft"
    username: "root"
    password: "CHANGE_ME"
    use-ssl: false # 是否启用 SSL 连接（生产环境建议设为 true）
  # SQLite 配置（仅 type: sqlite 时生效）
  sqlite:
    file: "webitem.db" # 数据库文件名（相对于插件目录）

# http配置
http:
  enabled: true # 是否启用HTTP服务（worker 模式下自动忽略）
  ip: 0.0.0.0 # ip地址
  port: 25566 # 端口号
 
  # TLS/SSL 加密配置
  ssl:
    enabled: false # 是否启用 HTTPS（需提供 keystore）
    port: 25568 # HTTPS 独立端口（仅 ssl.disable-http: false 时生效）
    disable-http: false # 是否禁用纯 HTTP（启用后 HTTPS 使用 http.port，ssl.port 忽略）
    keystore-path: "keystore.jks" # Java Keystore 文件路径（相对于插件目录）
    keystore-password: "CHANGE_ME_STRONG_PASSWORD" # Keystore 密码
    key-password: "CHANGE_ME_STRONG_PASSWORD" # 密钥密码（通常与 keystore 密码相同）
    # 使用场景：
    # 仅 HTTP:  ssl.enabled: false
    # HTTP + HTTPS 并存:  ssl.enabled: true, ssl.disable-http: false → HTTP 用 http.port, HTTPS 用 ssl.port
    # 仅 HTTPS:  ssl.enabled: true, ssl.disable-http: true → HTTPS 用 http.port, ssl.port 忽略
    # 生成 keystore 文件的命令（仅在需要时执行），CN=127.0.0.1 为服务器 IP 或域名
    # & "C:\Program Files\Java\jdk-21\bin\keytool.exe" -genkeypair -alias http -keyalg RSA -keysize 2048 -keystore keystore.jks -validity 365 -storepass CHANGE_ME_STRONG_PASSWORD -keypass CHANGE_ME_STRONG_PASSWORD -dname "CN=127.0.0.1"
 
  # api认证配置
  api:
    token: "CHANGE_ME_TO_A_STRONG_RANDOM_TOKEN"

html:
  enabled: true # 是否启用HTML示例页面

# 自定义端点配置
endpoints:
  enabled: true # 是否允许外部插件通过 EndpointRegistry 注册自定义 API 端点

# 安全配置
security:
  cors-origin: "*" # CORS 允许的来源域名。警告：默认值 "*" 会允许所有域名跨站访问，生产环境务必改为具体的域名！
  expose-version: false # 是否在HTML页面中暴露服务器版本号
  rate-limit:
    enabled: false # 是否启用IP速率限制
    max-requests-per-minute: 60 # 每分钟最大请求数
  ip-filter:
    enabled: false # 是否启用IP过滤（同时作用于HTTP和WebSocket）
    mode: "blacklist" # 过滤模式：blacklist（黑名单，禁止列表中的IP）、whitelist（白名单，只允许列表中的IP）
    ips:           # IP列表，支持三种格式：
      - "192.168.1.100"      # 单IP
      - "10.0.0.0/8"         # CIDR子网
      - "172.16.*.*"         # 通配符

# WebSocket推送配置（可选，禁用不影响HTTP接口）
websocket:
  enabled: true # 是否启用WebSocket实时推送（worker 模式下自动忽略）
  port: 25567 # WebSocket服务端口
  token: "CHANGE_ME_TO_A_STRONG_RANDOM_TOKEN" # WebSocket认证Token（留空则不验证，建议设置强随机字符串）
  # 连接限制（防止资源耗尽攻击）
  max-connections: 50 # 最大同时连接数（0=不限制）
  max-connections-per-ip: 3 # 单IP最大连接数（0=不限制）
 
  # 推送事件开关
  push:
    chat: true # 是否推送玩家聊天消息
    chat_formatted: true # 聊天推送是否包含格式化消息（适配聊天插件自定义格式如 [世界][频道]玩家名: 内容）
    join_quit: true # 是否推送玩家加入/退出事件

  # TLS/SSL 加密配置
  ssl:
    enabled: false # 是否启用 WSS（需提供 keystore）
    port: 25569 # WSS 独立端口（仅 ssl.disable-plain: false 时生效）
    disable-plain: false # 是否禁用纯 WS（启用后 WSS 使用 websocket.port，ssl.port 忽略）
    keystore-path: "keystore.jks" # Java Keystore 文件路径（相对于插件目录）
    keystore-password: "CHANGE_ME_STRONG_PASSWORD" # Keystore 密码
    key-password: "CHANGE_ME_STRONG_PASSWORD" # 密钥密码（通常与 keystore 密码相同）
    # 使用场景：
    # 仅 WS:   ssl.enabled: false
    # WS + WSS 并存:  ssl.enabled: true, ssl.disable-plain: false → WS 用 port, WSS 用 ssl.port
    # 仅 WSS:  ssl.enabled: true, ssl.disable-plain: true → WSS 用 port, ssl.port 忽略
    # 生成 keystore 文件的命令（仅在需要时执行），CN=127.0.0.1 为服务器 IP 或域名
    # & "C:\Program Files\Java\jdk-21\bin\keytool.exe" -genkeypair -alias websocket -keyalg RSA -keysize 2048 -keystore keystore.jks -validity 365 -storepass CHANGE_ME_STRONG_PASSWORD -keypass CHANGE_ME_STRONG_PASSWORD -dname "CN=127.0.0.1"

# ==========================================
# 跨服 Plugin Message 配置（Worker/Hybrid 模式）
# ==========================================
cross-server:
  # 子服标识名称（Worker/Hybrid 模式下必须配置，用于区分不同子服）
  # 示例：survival、lobby、creative、hub 等
  server-id: ""
  # Plugin Message 通道名称（需与 Velocity 端一致）
  channel: "webitem:main"

# give接口配置（物品操作，需要玩家在线）
give:
  enabled: true # 是否启用给予物品功能
  require-permission: false # 是否需要权限才能给予物品
  batch:
    enabled: false # 是否启用批量物品操作接口 /api/item/batch
    max-operations: 100 # 单次批量请求最大操作数量

# reg接口配置 前置：AuthMe插件
reg:
  enabled: true # 是否启用玩家注册和查询接口

# currency接口配置 前置：XConomy插件
currency:
  enabled: true # 是否启用货币操作接口
  batch:
    enabled: false # 是否启用批量货币操作接口 /api/currency/batch
    max-operations: 100 # 单次批量请求最大操作数量

# exp接口配置（经验操作，需要玩家在线）
exp:
  enabled: true # 是否启用经验操作接口
  batch:
    enabled: false # 是否启用批量经验操作接口 /api/exp/batch
    max-operations: 100 # 单次批量请求最大操作数量

# online接口配置（在线玩家查询）
online:
  enabled: true # 是否启用在线玩家查询接口

# tps接口配置（服务器性能查询）
tps:
  enabled: true # 是否启用TPS/MSPT查询接口

# memory接口配置（JVM内存使用查询）
memory:
  enabled: true # 是否启用内存使用查询接口

# whitelist接口配置
whitelist:
  enabled: true # 是否启用白名单操作接口
  batch:
    enabled: false # 是否启用批量白名单操作接口 /api/whitelist/batch
    max-operations: 100 # 单次批量请求最大操作数量

# inventory接口配置（玩家背包查询，需要玩家在线）
inventory:
  enabled: true # 是否启用背包查询接口
  batch:
    enabled: false # 是否启用批量背包查询接口 /api/inventory/batch
    max-operations: 100 # 单次批量请求最大操作数量

# playerinfo接口配置（玩家信息查询）
playerinfo:
  enabled: true # 是否启用玩家信息查询接口
  batch:
    enabled: false # 是否启用批量玩家信息查询接口 /api/playerinfo/batch
    max-operations: 100 # 单次批量请求最大操作数量

# enderchest接口配置（玩家末影箱操作，需要玩家在线）
enderchest:
  enabled: true # 是否启用末影箱查询接口
  operation-enabled: true # 是否启用末影箱物品给予/扣除接口

# transactions接口配置（交易记录查询）
transactions:
  enabled: true # 是否启用交易记录查询接口
  batch:
    enabled: false # 是否启用批量交易记录查询接口 /api/transactions/batch
    max-operations: 100 # 单次批量请求最大操作数量

# onlinetime接口配置（在线时长统计）
onlinetime:
  enabled: true # 是否启用在线时长统计接口（/api/onlinetime）
  auto-save-interval-seconds: 300 # 自动保存间隔（秒），默认5分钟
  # 存储后端配置
  storage:
    type: "database" # 存储类型：yaml（本地YAML文件）、database（使用全局数据库配置）
  batch:
    enabled: false # 是否启用批量在线时长查询接口 /api/onlinetime/batch
    max-operations: 100 # 单次批量请求最大操作数量

# flight接口配置（玩家飞行控制，需要玩家在线）
flight:
  enabled: true # 是否启用飞行控制接口
  use-command: false # 是否使用控制台/fly命令操作（true=兼容Essentials/CMI等插件，false=直接用Bukkit API，无需任何插件）
  batch:
    enabled: false # 是否启用批量飞行控制接口 /api/flight/batch
    max-operations: 100 # 单次批量请求最大操作数量

# announce接口配置（发送全服公告）
announce:
  enabled: true # 是否启用全服公告接口
  prefix: "&6&l[公告] &r" # 公告前缀（可使用&颜色代码）

# worldinfo接口配置（世界信息查询）
worldinfo:
  enabled: true # 是否启用世界信息查询接口

# message接口配置（发送玩家私信，需要玩家在线）
message:
  enabled: true # 是否启用玩家私信发送接口

# 访问日志配置
access-log:
  enabled: true # 是否启用访问日志
  retention-days: 7 # 日志保留天数
  max-size-mb: 100 # 单个日志文件最大大小（MB）
  format: "[$time] $ip $method $uri $status $size $duration" # 日志格式
  log-post-body: false # 是否在日志中记录POST请求体（包含敏感数据，默认关闭）
  ws-enabled: true # 是否记录WebSocket事件日志
  ws-format: "[$time] WS $ip $event $payload" # WebSocket日志格式

# points接口配置 前置：PlayerPoints插件
points:
  enabled: true # 是否启用点券操作接口
  batch:
    enabled: false # 是否启用批量点券操作接口 /api/points/batch
    max-operations: 100 # 单次批量请求最大操作数量

# cmd接口配置（控制台命令执行，高风险功能，请谨慎启用）
cmd:
  enabled: false # 是否启用控制台命令执行接口（高风险功能，默认关闭）
  timeout-seconds: 10 # 命令执行超时时间（秒）
  max-output-lines: 50 # 返回的最大输出行数
  mode: "blacklist" # 过滤模式：blacklist（黑名单，禁止列表中的命令）、whitelist（白名单，只允许列表中的命令）
  batch:
    enabled: false # 是否启用批量命令执行接口 /api/cmd/batch
    max-operations: 50 # 单次批量请求最大命令数量
  blocked-commands:       # 黑名单模式：禁止执行的命令（支持前缀匹配，如 "plugman" 会拦截所有 plugman 开头命令）
    - "op"
    - "deop"
    - "stop"
    - "restart"
    - "reload"
    - "ban"
    - "pardon"
    - "ban-ip"
    - "pardon-ip"
    - "banlist"
    - "kick"
    - "whitelist"
    - "plugman"
    - "plugins"
    - "plugin"
    - "?"
    - "help"
    - "version"
    - "about"
    - "minecraft:"
    - "essentials:"
    - "pex"
    - "luckperms"
    - "lp"
  allowed-commands:       # 白名单模式：仅允许执行的命令（黑名单模式下此列表被忽略）
    - "say"
    - "broadcast"
    - "list"

# ==========================================
# Redis 配置（可选，用于分布式缓存、跨服数据共享、分布式限速）
# ==========================================
redis:
  enabled: false # 是否启用 Redis
  host: "127.0.0.1" # Redis 服务器地址
  port: 6379 # Redis 端口
  password: "" # Redis 密码（无密码请留空）
  database: 0 # Redis 数据库编号（0-15）
  timeout: 3000 # 连接超时（毫秒）
  pool:
    max-total: 8 # 连接池最大连接数
    max-idle: 4 # 连接池最大空闲连接数
    min-idle: 1 # 连接池最小空闲连接数
  # 缓存配置
  cache:
    enabled: false # 是否启用 Redis 缓存
    default-ttl-seconds: 300 # 默认缓存过期时间（秒）
  # 跨服 Pub/Sub（基于 Redis 实现跨服消息广播）
  pubsub:
    enabled: false # 是否启用跨服发布订阅
    channel-prefix: "webitem" # 频道前缀，实际频道名为 {prefix}/{server-id}
  # 分布式限速（替换内存级限速，所有子服共享限速计数）
  rate-limit:
    enabled: false # 是否启用 Redis 分布式限速（优先级高于 security.rate-limit）

# ==========================================
# 审计日志配置（操作记录溯源）
# ==========================================
audit-log:
  enabled: true          # 是否启用审计日志（记录所有API操作到数据库）
  retention-days: 30     # 日志保留天数（自动清理旧记录）
  batch-size: 100        # 批量写入数据库时的每批数量
  queue-size: 2000       # 内存队列大小（超出后新记录会被丢弃）

# 调试配置
debug: false # 是否启用调试日志（开启后输出详细的请求/握手/异常信息）

// 示例：其它插件注册自定义端点
WebItem webItem = (WebItem) Bukkit.getPluginManager().getPlugin("WebItem");
if (webItem != null) {
    webItem.getEndpointRegistry().registerEndpoint(
        yourPlugin, "/api/custom/xxx", yourHandler
    );
}

// 示例：其它插件注册自定义 WebSocket 事件
WebItem webItem = (WebItem) Bukkit.getPluginManager().getPlugin("WebItem");
if (webItem != null) {
    WsEndpointRegistry wsReg = webItem.getWsEndpointRegistry();
    if (wsReg != null) {
        wsReg.registerHandler(yourPlugin, "my_event", (session, json) -> {
            // 处理 WebSocket 事件...
            session.sendText("{\"status\":true,\"message\":\"ok\"}");
        });
    }
}