MCXboxBroadcast（Broadcaster 项目）是一款把 Bedrock 版 Minecraft 服务器广播到 Xbox Live 的 Geyser 扩展，它的自动接受好友请求、初始邀请与过期清理三大机制，能让你完全不用手动维护好友列表：新玩家发好友请求自动通过、通过后立刻收到进服邀请、长期不活跃的玩家自动移除，全程无人值守。

🤝 为什么需要"自动好友管理"

在 Xbox Live 上，玩家只能从好友列表里看到可加入的游戏会话。也就是说：

• 玩家想加入你的服务器 → 必须先和"广播账号"成为好友；
• 一个 Xbox 账号的好友上限只有1000 人（见 Constants.java 中的MAX_FRIENDS）。

如果全靠人工通过好友请求、手动删除不活跃玩家，运营一个社区服务器会非常辛苦。MCXboxBroadcast 用一套自动化流程把这件事彻底托管掉了。

✅ 机制一：自动接受好友请求（auto-friend）

默认开启，核心逻辑在 FriendManager.java 的acceptPendingFriendRequests()：

1. 启动时补一次：工具每次启动都会立即执行一次扫描，把离线期间堆积的好友请求全部处理掉（FriendManager.init()）；
2. 定时扫描：开启后，后台线程按friend-sync.update-interval（默认60 秒，Xbox 限流要求最低 20 秒）周期性地拉取待处理的好友请求队列，逐个通过；
3. 过滤分屏子账号：联机会产生guest子账号，代码通过isGuestAccount()识别并跳过，避免误加这类临时账号；
4. 限流自动重试：添加好友的请求统一进入后台队列（toAdd/toRemove），遇到 HTTP429（限流）时会读取Retry-After头并自动延迟重试；如果返回错误码1028（好友列表已满），会清空待加队列避免无谓重试。

小提示：如果某个玩家屏蔽了广播账号或其隐私设置不允许加好友（错误码1011/1049），工具会自动拒绝该请求（避免反复重试），并可通过 Slack webhook 通知你，详见 NotificationConfig。

📩 机制二：初始邀请（initial-invite）

默认开启。好友关系一旦建立，FriendManager.sendInvite()（L471-L502）会立即为玩家创建一条 Xbox"游戏邀请"（invite handle）并推送给他。

效果是：新加入的好友马上就能在 Minecraft 的 Xbox 好友页看到你的服务器会话，而不是等到下次刷新。关闭该选项后，新好友只会出现"好友"关系，需要自己手动找会话入口。

🧹 机制三：过期清理（expiry）——自动移除不活跃玩家

Xbox 好友名额是稀缺资源，长期不玩的玩家白白占坑很浪费。过期清理机制（SessionManager.expireFriends()）会定期把"久未上线"的好友解除好友关系：

• 记录最后在线时间：玩家每次通过 NetherNet 中继真正进入服务器时（HttpRelaySignaling.recordJoin()）都会刷新其lastSeen时间戳；新添加好友时也会重置计时，让过期时间从加好友那一刻开始算。这些记录保存在本地 SQLite 数据库player_history.db中（FileStorageManager.java）；
• 定期检查：开启expiry.enabled后，工具每expiry.check秒（默认1800 秒，即 30 分钟）扫描一次所有账号的好友列表；
• 判定与移除：好友的最后在线时间早于expiry.days天（默认15 天）前，就会被从所有关联账号的好友列表中移除，并清空其历史记录——下次再想玩，重新发好友请求即可自动通过；
• 多账号保护：你自己管理的那些子账号（多账号模式）永远不会被当成"过期玩家"移除；且如果任一账号的好友列表查询失败，本轮会整体跳过，保证下次检查时所有账号一起移除，避免数据不一致。

⚙️ friend-sync 配置块速查

以下配置位于config.yml（定义见 CoreConfig.FriendSyncConfig），全部带有合理的默认值：

friend-sync: update-interval: 60 # 好友请求扫描间隔（秒），最低 20 auto-friend: true # 自动接受好友请求 initial-invite: true # 加好友成功后自动发送游戏邀请 expiry: enabled: true # 启用过期清理 days: 15 # 多少天未上线视为过期 check: 1800 # 多久检查一次过期（秒）

旧版配置项should-expire、expire-days、expire-check、auto-follow已升级迁移，详见 ConfigLoader.java 中的版本转换规则。

❓ 常见问题

好友列表满了怎么办？当达到 1000 人上限时，Xbox 会返回1028，工具会停止继续添加。请调小expiry.days或增大expiry.check频率，加快回收空位。

玩家为什么一直加不上好友？若对方账号设置了隐私限制或年龄限制（1011/1049），该玩家无法成为好友，工具会记录警告并发送通知（配置 Slack webhook 后推送到群聊）。

移除好友会丢失数据吗？移除时会清空该玩家的lastSeen记录，但只影响"下次重新计算过期时间"，服务器世界数据不受任何影响。

📁 相关模块路径一览

• 好友管理核心逻辑：core/src/main/java/com/rtm516/mcxboxbroadcast/core/FriendManager.java
• 过期清理调度：core/src/main/java/com/rtm516/mcxboxbroadcast/core/SessionManager.java
• 配置定义：core/src/main/java/com/rtm516/mcxboxbroadcast/core/configs/CoreConfig.java
• 玩家上线记录（SQLite）：core/src/main/java/com/rtm516/mcxboxbroadcast/core/storage/FileStorageManager.java
• 加入服务器时的时间戳刷新：core/src/main/java/com/rtm516/mcxboxbroadcast/core/nethernet/HttpRelaySignaling.java
• 独立版部署文件：bootstrap/standalone/Dockerfile、Pterodactyl 面板模板：egg-m-c-xbox-broadcast.json

整套机制开箱即用：默认配置下，你的 Xbox 广播账号会自动完成"接受请求 → 发送邀请 → 定期清退"的完整闭环，把好友列表变成一块自维护的"进服门票池"。🎮