lanrenbang/xray-api-bridge repository overview

⁠xray-api-bridge

English⁠ | 简体中文⁠

This project provides a complete RESTful HTTP API interface for the Xray-core instance's gRPC management API. It acts as a bridge, converting HTTP requests into gRPC calls, allowing services like Caddy to interact with Xray without needing a native gRPC client.

⁠Features

• Complete REST API: Includes all endpoints of the current Xray gRPC management API.
• Real-time Subscription: Generates complete subscription links based on the currently running Xray server and necessary subscription configurations.
• Complete Backend: You can use this project as a backend to develop your own frontend panel, dashboard, desktop widget, etc.
• Support for secrets in environment variables (e.g., Docker/Podman secrets).
• Automatically tracks upstream updates and rebuilds images.
• Includes Docker/Podman build/compose configurations.
• Provides pre-configured Caddy nesting for Compose.

⁠Project Structure

.
├── apiserver
├── bridge
├── tokenauth
├── xrayapi                           # Source code above
├── templates
│   └── subscription.jsonc.template   # Subscription configuration template
├── .env.warp.example                 # Template substitution definitions
├── compose.yaml                      # Container orchestration - Sub-service execution
├── compose.override.yaml             # Container override - Standalone execution
├── Dockerfile                        # Image generation config
├── API.md                            # REST API endpoint documentation
├── go.mod
├── go.sum
├── main.go
├── README-cn.md
└── README.md

⁠Usage

1. Install Docker or Podman (recommended), or choose to run natively.
2. caddy-services⁠ is recommended as the perfect companion for this project. You can also install other versions of Caddy or Nginx yourself, but you will need to implement the corresponding configurations manually.
3. xray-services⁠ is recommended as the perfect companion for this project. You can also use an existing Xray setup and modify it by referring to this project, mainly regarding the configuration templates. The Subscription Endpoint Configuration⁠ in this project depends on multiple variable definitions from xray-services. If you are not using that version, you will need to manually configure them in the current .env.warp.
4. Clone this repository:

git clone https://github.com/Lanrenbang/xray-api-bridge.git

1. Copy or rename .env.warp.example⁠ to .env.warp and modify the necessary content as needed.
2. Refer to the internal comments to modify compose.yaml⁠/compose.override.yaml⁠ as required.
3. Add the information configured as secrets in the previous step to the keystore:

echo -n "some secret" | docker secret create <secret_name> - 
echo -n "some secret" | podman secret create <secret_name> - 

1. Enter the root directory and start the container service:

docker compose up -d
podman compose up -d

⁠Others

• Full API Documentation Reference⁠.
• If you do not wish to use containers and prefer to run this project natively, please refer to the Native Execution Guide⁠.
• For container health checks, please refer to the HEALTHCHECK Guide⁠.

⁠Related Projects

• caddy-services⁠
• xray-services⁠

⁠Credits

• go-chi⁠, Web framework used for routing and middlewares.
• grpc⁠, gRPC client used to communicate with Xray-core.
• Xray-core⁠, Used for configuration structures and gRPC definitions.
• VMessAEAD/VLESS Sharing Standard Proposal⁠, Standard for subscription generation.
• 5-in-1 Configuration⁠, Subscription sharing configuration reference.

⁠Support Me

⁠License

This project is distributed under the terms of the LICENSE file.