跨服支持

Assiah 支持 BungeeCord/Velocity 群组服环境下的跨服邮件互通。

架构

跨服支持依赖两个组件：

• MySQL — 所有子服连接同一数据库，邮件数据共享
• Redis — 提供跨服实时通知、缓存同步和玩家路由（可选但推荐）

跨服架构包含三个核心模块：

模块	说明
MailNetworkBridge	基于 Redis Pub/Sub 的跨服通信桥接器
MailRouteManager	维护玩家 UUID → 服务器标识的路由映射
MailCacheProvider	Redis 缓存层（未读数量缓存 + 路由缓存）

配置步骤

1. 设置服务器标识

每个子服在 config.yml 中设置不同的 server-name：

server-name: lobby    # 大厅服
# server-name: survival  # 生存服
# server-name: rpg       # RPG 服

2. 所有子服使用同一 MySQL 数据库

database:
  mode: mysql
  mysql:
    enabled: true
    host: 你的MySQL地址
    port: 3306
    database: assiah
    username: root
    password: 你的密码
    parameters: "?useSSL=false&serverTimezone=UTC&characterEncoding=utf8"
    pool:
      maximum-pool-size: 8
      minimum-idle: 2
      connection-timeout-ms: 10000
  table-prefix: assiah_

确保所有子服的 table-prefix 一致。

3. 启用 Redis

redis:
  enabled: true
  connection:
    host: 你的Redis地址
    port: 6379
    password: ""
    database: 0
    timeout-ms: 3000
  channel:
    mail-notify: assiah:mail:notify
    route-sync: assiah:mail:route
    cache-evict: assiah:mail:evict
  cache:
    unread-ttl-seconds: 30
    mailbox-list-ttl-seconds: 15
    route-ttl-seconds: 60
  degrade:
    fail-open: true
    log-when-unavailable: true
    keep-core-flow-working: true

确保所有子服连接同一个 Redis 实例，且频道名称一致。

Redis 频道说明

频道	用途
assiah:mail:notify	新邮件通知广播，通知目标玩家所在的子服
assiah:mail:route	路由同步，追踪玩家当前所在的子服
assiah:mail:evict	缓存失效广播，确保各子服缓存一致性

缓存 TTL 配置

Redis 缓存的过期时间可以按需调整：

redis:
  cache:
    unread-ttl-seconds: 30       # 未读数量缓存（秒）
    mailbox-list-ttl-seconds: 15 # 邮箱列表缓存（秒）
    route-ttl-seconds: 60        # 玩家路由缓存（秒）

• 未读缓存：加速未读数量查询，避免每次都查数据库
• 列表缓存：加速邮箱列表加载
• 路由缓存：记录玩家当前所在服务器，用于跨服通知投递

玩家路由

玩家上下线时，插件会自动维护路由信息：

• 玩家登录 → 注册路由（本地 + Redis），广播 route_update
• 玩家退出 → 移除路由（本地 + Redis），广播 route_remove

查询玩家所在服务器时，优先查本地缓存，本地没有再查 Redis。

降级策略

Redis 是可选增强层，不是核心依赖。降级行为可以精细控制：

redis:
  degrade:
    fail-open: true              # Redis 不可用时允许核心功能继续运行
    log-when-unavailable: true   # Redis 不可用时输出警告日志
    keep-core-flow-working: true # 保持核心流程正常工作

降级后的影响：

• 邮箱核心功能（收发、领取、管理）仍然完整可用
• 跨服实时通知不可用，但玩家登录时仍会收到未读邮件通知
• 缓存加速不可用，所有查询直接走数据库