Ivan's Blog
项目实践

XP Cluster Manager

XP Cluster Manager 是 self-hosted multi-host Xray cluster manager。README.md 明确每台 host 运行 xp 和 xray 两个进程，xp 用 OpenRaft 保存 cluster-wide desired state，并通过 Xray gRPC API reconcile 本地 runtime。

  • Distributed system
  • Rust web service
  • Embedded admin UI
  • React app
  • shadcn/ui
  • Ops tool
  • Dockerized dev
  • Storybook component QA
  • Service ports
  • PR label release
  • Release failure notification

目录

技术栈

运行与交付

CI 工作流
  • ci.yml
  • label-gate.yml
  • notify-release-failure.yml
  • release.yml
  • xray-e2e.yml
能力标记
  • bun_lock
  • cargo_toml
  • dockerfile
  • github_actions
  • package_json
JSON

Purpose

XP Cluster Manager 是 self-hosted multi-host Xray cluster manager。README.md 明确每台 host 运行 xp 和 xray 两个进程，xp 用 OpenRaft 保存 cluster-wide desired state，并通过 Xray gRPC API reconcile 本地 runtime。它还内置 Vite + React admin UI，构建产物嵌入 Rust binary。

Taxonomy

  • Tags: Distributed system, Rust web service, Embedded admin UI, React app, shadcn/ui, Ops tool, Dockerized dev, Storybook component QA, Service ports, PR label release, Release failure notification
  • Why / evidence: 这些 tags 来自 checked-out repo 和 catalog record。主要证据包括 README.md、Cargo.toml、Dockerfile、proto/、docs/desgin/subscription.md、docs/desgin/quota.md、web/package.json、web/components.json。Topic token 的大小写以对应技术/工作流的官方写法为准；slug 只作为稳定 ID，不直接充当项目标题。

Repository map

  • Cargo.toml 包含 Axum、OpenRaft、prost、rcgen、ratatui、reqwest 等依赖，说明它同时有 API、Raft、CLI/TUI 和 Xray integration。
  • proto/ 保存 gRPC/protobuf 边界；src/ 是服务和 runtime。
  • web/ 是 React/shadcn/ui admin UI，web/components.json 记录 radix-nova style 和 aliases，.storybook/main.ts 提供 component QA。
  • Dockerfile 构建 web assets、Rust binary，并以 Xray Docker tag 作为 build arg。

Runtime and delivery

Web dev 固定 60080，Storybook 固定 60081，这类默认端口在本地预览时必须用 port lease 管理。Dockerfile 的 XRAY_DOCKER_TAG、BUN_VERSION、XP_BUILD_VERSION 是 release/build contract。服务运行需要管理 Xray inbound/client、subscriptions、quota 和 cluster state。

Architecture notes

核心架构是 OpenRaft desired-state + 本机 Xray reconcile。admin UI 是控制面；subscription output、quota、auto-ban、REALITY/Shadowsocks 配置是用户可见功能。因为是 distributed system，任何单机 API 改动都要考虑 Raft log/state migration 和多 host 一致性。

证据锚点：README.md。

Workflow and quality gates

.github/workflows/ci.yml、xray-e2e.yml、label-gate.yml、release.yml、notify-release-failure.yml 说明 CI、Xray e2e、label release 和失败通知都是交付面。Web 有 Storybook/test/e2e，但没有 accessibility addon 证据，应命名为 component QA。

Reusable decisions

  • 把 desired state 放 Raft，把 local runtime 作为 reconcile 结果，是多主机 ops 工具的稳定边界。
  • 将 admin UI 嵌入 Rust binary，部署时减少前后端分离复杂度。
  • Xray e2e 单独成 workflow，避免普通 CI 掩盖集成风险。

Risks and open questions

  • 分布式状态迁移风险高，不能把它当普通 Rust web service。
  • 默认端口硬编码需要在 Agent 本地预览时遵守租约。
  • Xray 版本和协议配置变化会影响生成的订阅/REALITY。

Evidence index

  • README.md
  • Cargo.toml
  • Dockerfile
  • proto/
  • docs/desgin/subscription.md
  • docs/desgin/quota.md
  • web/package.json
  • web/components.json
  • web/.storybook/main.ts
  • .github/workflows/ci.yml
  • .github/workflows/xray-e2e.yml
  • .github/workflows/label-gate.yml
  • .github/workflows/release.yml
  • .github/workflows/notify-release-failure.yml

相关内容