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

You can also download the Releases archive.

5. Copy or rename .env.warp.example to .env.warp and modify the necessary content as needed.
6. Refer to the internal comments to modify compose.yaml/compose.override.yaml as required.
7. 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> - 

Or run docker/podman secret create <secret_name> directly and enter the secret when prompted.

Note: <secret_name> must match the entries in .env.warp and compose.yaml.

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

docker compose up -d
podman compose up -d

Tip:

• If Caddy is used as a frontend, this service will start as a sub-service. No action is needed here; please refer to caddy-services for details.

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.