项目实践

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
shadcn/ui

技术栈

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

{
  "cargo": {
    "deps_build": [
      "protoc-bin-vendored",
      "tonic-build",
      "tonic-prost-build"
    ],
    "deps_dev": [
      "assert_cmd",
      "bytes",
      "http-body-util",
      "predicates",
      "pretty_assertions",
      "shadowsocks",
      "tempfile",
      "tokio-stream",
      "tower",
      "wiremock",
      "x509-parser"
    ],
    "deps_main": [
      "anyhow",
      "argon2",
      "axum",
      "base64",
      "chrono",
      "clap",
      "crossterm",
      "dialoguer",
      "flate2",
      "futures-util",
      "hex",
      "hmac",
      "libc",
      "maxminddb",
      "nanoid",
      "openraft",
      "prost",
      "rand",
      "ratatui",
      "rcgen"
    ]
  },
  "ci_workflows": [
    "ci.yml",
    "label-gate.yml",
    "notify-release-failure.yml",
    "release.yml",
    "xray-e2e.yml"
  ],
  "configs_root": [
    ".bun-version",
    ".dockerignore",
    ".gitignore",
    "Cargo.toml",
    "dprint.json",
    "lefthook.yml",
    "package.json",
    "rust-toolchain.toml",
    "rustfmt.toml"
  ],
  "markers_present": [
    "bun_lock",
    "cargo_toml",
    "dockerfile",
    "github_actions",
    "package_json"
  ],
  "package_json": {
    "deps_dev": [
      "@commitlint/cli",
      "@commitlint/config-conventional",
      "commitlint-plugin-function-rules",
      "dprint"
    ]
  }
}

技术栈完整数据（无需 JavaScript）

{
  "cargo": {
    "deps_build": [
      "protoc-bin-vendored",
      "tonic-build",
      "tonic-prost-build"
    ],
    "deps_dev": [
      "assert_cmd",
      "bytes",
      "http-body-util",
      "predicates",
      "pretty_assertions",
      "shadowsocks",
      "tempfile",
      "tokio-stream",
      "tower",
      "wiremock",
      "x509-parser"
    ],
    "deps_main": [
      "anyhow",
      "argon2",
      "axum",
      "base64",
      "chrono",
      "clap",
      "crossterm",
      "dialoguer",
      "flate2",
      "futures-util",
      "hex",
      "hmac",
      "libc",
      "maxminddb",
      "nanoid",
      "openraft",
      "prost",
      "rand",
      "ratatui",
      "rcgen"
    ]
  },
  "ci_workflows": [
    "ci.yml",
    "label-gate.yml",
    "notify-release-failure.yml",
    "release.yml",
    "xray-e2e.yml"
  ],
  "configs_root": [
    ".bun-version",
    ".dockerignore",
    ".gitignore",
    "Cargo.toml",
    "dprint.json",
    "lefthook.yml",
    "package.json",
    "rust-toolchain.toml",
    "rustfmt.toml"
  ],
  "markers_present": [
    "bun_lock",
    "cargo_toml",
    "dockerfile",
    "github_actions",
    "package_json"
  ],
  "package_json": {
    "deps_dev": [
      "@commitlint/cli",
      "@commitlint/config-conventional",
      "commitlint-plugin-function-rules",
      "dprint"
    ]
  }
}

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, shadcn/ui

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

XP Cluster Manager

目录

目录

技术栈

Purpose

Taxonomy

Repository map

Runtime and delivery

Architecture notes

Workflow and quality gates

Reusable decisions

Risks and open questions

Evidence index

Distributed system

shadcn/ui

目录

技术栈

运行与交付

依赖与工具

配置与质量

其他信息

Purpose

Taxonomy

Repository map

Runtime and delivery

Architecture notes

Workflow and quality gates

Reusable decisions

Risks and open questions

Evidence index

相关内容

Distributed system

shadcn/ui