配置同步队列

This page is not available in English yet. Showing Simplified Chinese.

读者：需要确认下发结果或排查同步问题的运维人员。

当你在控制台修改逻辑节点、模板、用户或 Host 绑定时，Master 会把期望状态写入 配置同步队列，由各 Host 上的 Client 对本机 3x-ui 执行增删改。这就是核心概念中的实时配置下发。

1. 适用场景

新建逻辑节点后，确认 inbound 是否已在各 Host 落地
节点曾离线，恢复后检查是否自动补推
排查 drift（本机配置与期望态不一致）或 failed 任务

2. 工作流程

控制台保存变更
    → Master 计算期望 inbound / client 状态
    → 任务入队（按 Host 拆分）
    → Client 经 WebSocket 收到指令
    → 对比本机 3x-ui → add / update / delete
    → 回报结果 → 更新 sync_status

用户维度变更（新增订阅用户、禁用账号）走同类同步通道，与 inbound 物料化并行。

3. 查看队列

控制台 → 配置同步（或逻辑节点 / 主机详情中的同步子页）：

字段	含义
任务类型	inbound 物料化、client 同步、WireGuard peer 注入等
目标 Host	哪台 VPS
状态	`pending` / `running` / `success` / `failed`
时间	入队、开始、完成时间
错误信息	Client 或 XUI API 返回的失败原因

逻辑节点详情中每台绑定 Host 也有简化的 sync_status 徽章。

4. 离线补推

Client 断线时：

新任务保持 pending，不会丢失
Client 重连后 Master 推送积压任务
长时间离线可能导致订阅用户状态与面板短暂不一致，恢复后以对账为准

无需手工「点同步」；若持续失败，先检查 Client 服务与网络。

5. 漂移（drift）处理

drift 表示本机 inbound 与 Master 渲染结果 hash 不一致，常见原因：

人工登录 3x-ui 改了 inbound
节点磁盘满导致写入失败
版本升级后字段差异

处理建议：

在控制台对该逻辑节点触发 重新同步（若有按钮）或保存一次无改动的配置以强制入队
仍失败则 SSH 查看 journalctl -u xctl-client，对照 XUI API 错误
确认无人工改面板后，可删除本机对应 inbound 让 Client 重建（需评估业务影响）

6. 注意事项

大批量变更（如批量改模板）会产生多 Host 并行任务，注意 XUI API 限流
WireGuard 除 inbound 骨架外，peer 列表由 Master 动态注入，队列中可能有独立 peer 任务
删除逻辑节点或解绑 Host 会下发删除 inbound 操作，请确认无其他逻辑节点共享同一 inbound

7. 常见问题

Q：显示 synced 但用户连不上？
A：同步只保证面板配置；检查防火墙、域名解析、用户是否在准入组内。

Q：队列一直 pending？
A：Host 离线或 Client 未启动；systemctl status xctl-client。

Q：和用户同步有什么区别？
A：inbound 是「线路骨架」；用户同步是往 inbound 里挂 client / peer。二者都在同一套对账体系下。