Gozargah-Node-Go

Attention ⚠️

This project is in the testing and development stage. The code may undergo major changes during this phase, so use it at your own risk.

Table of Contents

• Overview
  • Why Use Gozargah Node?
  • Supported Cores
• Documentation
  • Configuration
  • API
    • Data Structure
    • Methods
• Official library
  • Go
  • Python
• Donation
• Contributors

Overview

Gozargah Node is developed by the Gozargah team to replace Marzban-node. It aims to be more stable, scalable, and efficient.

Why Use Gozargah Node?

We designed this project to be usable in any project, even without Marzban. You can run nodes with a simple script and the help of official libraries.
We plan to expand supported cores after the testing stage, allowing you to use any core you want.

Supported Cores

Core	Support
xray-core	✅
sing-box	❌
v2ray-core	❌

Documentation

Configuration

You can set the settings below using environment variables or by placing them in a .env file.

Variable	Description
SERVICE_PORT	Bind application to this port (default: 62050).
NODE_HOST	Bind application to this host (default: 127.0.0.1).
XRAY_EXECUTABLE_PATH	Path of Xray binary (default: /usr/local/bin/xray).
XRAY_ASSETS_PATH	Path of Xray assets (default: /usr/local/share/xray).
SSL_CERT_FILE	SSL certificate file to secure the application between master and node (it will generate a self-signed SSL if it doesn't exist; better to use a real SSL with a domain).
SSL_KEY_FILE	SSL key file to secure the application between master and node (it will generate a self-signed SSL if it doesn't exist; better to use a real SSL with a domain).
SSL_CLIENT_CERT_FILE	SSL certificate file to ensure only allowed clients can connect.
SERVICE_PROTOCOL	Protocol to use: grpc or rest (recommended: grpc).
MAX_LOG_PER_REQUEST	Maximum number of logs per request (only for long polling in REST connections).
DEBUG	Debug mode for development; prints core logs in the node server (default: False).
GENERATED_CONFIG_PATH	Path to the generated config by the node (default: /var/lib/gozargah-node/generated).

API

Gozargah Node supports two types of connection protocols: gRPC and REST API.
We recommend using gRPC, with REST always available as a fallback option (in case there is a problem with gRPC).

Data Structure

The node uses the common/service.proto file messages for both protocols.

Message	Description
Empty	Used when no input is required. Can replace null with Empty.
BaseInfoResponse	Contains: - started (bool): Indicates if the service is started. - core_version (string): Version of the core. - node_version (string): Version of the node. - session_id (string): Session ID. - extra (string): Additional information.
Vmess	Contains: - id (string): UUID for Vmess configuration.
Vless	Contains: - id (string): UUID for Vless configuration. - flow (string): Currently only supports xtls-rprx-vision.
Trojan	Contains: - password (string): Password for Trojan configuration.
Shadowsocks	Contains: - password (string): Password for Shadowsocks. - method (string): Encryption method. Supported methods: aes-128-gcm, aes-256-gcm, chacha20-poly1305, xchacha20-poly1305.
Proxy	Contains: - vmess (Vmess): Vmess configuration. - vless (Vless): Vless configuration. - trojan (Trojan): Trojan configuration. - shadowsocks (Shadowsocks): Shadowsocks configuration.
User	Contains: - email (string): User's email. - proxies (Proxy): Proxy configurations. - inbounds ([]string): List of inbounds.
BackendType	Enum: - XRAY = 0: Represents the Xray backend type.
Backend	Contains: - type (BackendType): Type of backend. - config (string): Configuration for the backend. - users ([]User): List of users. - keepAlive (uint64): hold backend alive for x second after last connection
Log	Contains: - detail (string): Log details.
Stat	Contains: - name (string): Stat name. - type (string): Stat type. - link (string): Link associated with the stat. - value (int64): Stat value.
StatResponse	Contains: - stats ([]Stat): List of stats.
StatRequest	Contains: - name (string): Name of the stat to request, user email or inbound \ outbound tag. - reset (bool) Whether to reset traffic stats.
OnlineStatResponse	Contains: - name (string): User's email. - value (int64): Online connection number.
OnlineStatResponse	Contains: - name (string): User's email. - value (map<string, int64>): Online stat value.
BackendStatsResponse	Contains: - num_goroutine (uint32): Number of goroutines. - num_gc (uint32): Number of garbage collections. - alloc (uint64): Allocated memory. - total_alloc (uint64): Total allocated memory. - sys (uint64): System memory. - mallocs (uint64): Number of mallocs. - frees (uint64): Number of frees. - live_objects (uint64): Number of live objects. - pause_total_ns (uint64): Total pause time in nanoseconds. - uptime (uint32): Uptime in seconds.
SystemStatsResponse	Contains: - mem_total (uint64): Total memory. - mem_used (uint64): Used memory. - cpu_cores (uint64): Number of CPU cores. - cpu_usage (double): CPU usage percentage. - incoming_bandwidth_speed (uint64): Incoming bandwidth speed. - outgoing_bandwidth_speed (uint64): Outgoing bandwidth speed.
Users	Contains: - users ([]User): List of users.

Note: The node receives data with x-protobuf as the content type in the REST API.

Methods

• Add address:port at the beginning of the REST API URL.
• Use Authorization Bearer <session_id> in the header for authentication with the REST API.
• Use authorization Bearer <session_id> in metadata for authentication with gRPC.

gRPC	REST	Input	Output	Description
Start()	POST,/start	Backend	BaseInfoResponse	This is the only method called before creating a connection.
Stop()	PUT,/stop	Empty	Empty	Stops the backend and deactivates the connection with the client.
GetBaseInfo()	GET,/info	Empty	BaseInfoResponse	Returns base info; can be used to check the connection between the node and client.
GetLogs()	GET,/logs	Empty	gRPC: (stream Log) REST API: (SSE)	This method is a SSE connection in the REST protocol, but in gRPC, it provides a stream connection.
GetSystemStats()	GET,/stats/system	Empty	SystemStatsResponse	Retrieves system statistics.
GetBackendStats()	GET,/stats/backend	Empty	BackendStatsResponse	Retrieves backend statistics.
GetOutboundsStats()	GET, /stats/outbounds	StatRequest	StatResponse	Retrieves outbound statistics. The name field in the request will be ignored.
GetOutboundStats()	GET,/stats/outbound	StatRequest	StatResponse	Retrieves statistics for a specific outbound.
GetInboundsStats()	GET,/stats/inbounds	StatRequest	StatResponse	Retrieves inbound statistics. The name field in the request will be ignored.
GetInboundStats()	GET,/stats/inbound	StatRequest	StatResponse	Retrieves statistics for a specific inbound.
GetUsersStats()	GET,/stats/users	StatRequest	StatResponse	Retrieves user statistics and resets traffic stats. The name field in the request will be ignored.
GetUserStats()	GET,/stats/user	StatRequest	StatResponse	Retrieves statistics for a specific user.
GetUserOnlineStats()	GET,/stats/user/online	StatRequest	OnlineStatResponse	Retrieves online statistics for a specific user. The reset field in the request will be ignored
GetUserOnlineIpListStats()	GET,/stats/user/online_ip	StatRequest	StatsOnlineIpListResponse	Retrieves ip list statistics for a specific user. The reset field in the request will be ignored
SyncUser()	PUT,/user/sync	User	Empty	Adds/updates/removes a user in the core. To remove a user, ensure you send empty inbounds. Provides a stream in gRPC but must be called for each user in the REST API.
SyncUsers()	PUT,/users/sync	Users	Empty	Removes all old users and replaces them with the provided users.

Official library

We create some library's for you so make your job easier

Go

gozargah-node-bridge

To add bridge to your project use:

go get github.com/m03ed/gozargah_node_bridge

Python

gozargah-node-bridge-py

pip install gozargah-node-bridge

Donation

You can help gozargah team with your donations, Click Here

Contributors

We ❤️‍🔥 contributors! If you'd like to contribute, please check out our Contributing Guidelines and feel free to submit a pull request or open an issue. We also welcome you to join our Telegram group for either support or contributing guidance.

Check open issues to help the progress of this project.

Thanks to the all contributors who have helped improve Gozargah Node:

Made with contrib.rocks