PPanel Server

PPanel is a pure, professional, and perfect open-source proxy panel tool, designed for learning and practical use.

English | 中文 | Report Bug | Request Feature

Article 1.
All human beings are born free and equal in dignity and rights.
They are endowed with reason and conscience and should act towards one another in a spirit of brotherhood.

Article 12.
No one shall be subjected to arbitrary interference with his privacy, family, home or correspondence, nor to attacks upon his honour and reputation.
Everyone has the right to the protection of the law against such interference or attacks.

Article 19.
Everyone has the right to freedom of opinion and expression; this right includes freedom to hold opinions without interference and to seek, receive and impart information and ideas through any media and regardless of frontiers.

Source: United Nations – Universal Declaration of Human Rights (UN.org)

📋 Overview

PPanel Server is the backend component of the PPanel project, providing robust APIs and core functionality for managing proxy services. Built with Go, it emphasizes performance, security, and scalability.

Key Features

• Multi-Protocol Support: Supports Shadowsocks, V2Ray, Trojan, and more.
• Privacy First: No user logs are collected, ensuring privacy and security.
• Minimalist Design: Simple yet powerful, with complete business logic.
• User Management: Full authentication and authorization system.
• Subscription System: Manage user subscriptions and service provisioning.
• Payment Integration: Supports multiple payment gateways.
• Order Management: Track and process user orders.
• Ticket System: Built-in customer support and issue tracking.
• Node Management: Monitor and control server nodes.
• API Framework: Comprehensive RESTful APIs for frontend integration.

Subscription Mode Behavior

The subscription behavior can be switched by the backend config Subscribe.SingleModel:

• false (multi-subscription mode): each successful purchase creates a new user_subscribe record.
• true (single-subscription mode): purchase is auto-routed to renewal semantics when the user already has a paid subscription:
  • a new order is still created,
  • but the existing subscription is extended (instead of creating another user_subscribe).

🚀 Quick Start

Prerequisites

• Go: 1.21 or higher
• Docker: Optional, for containerized deployment
• Git: For cloning the repository

Installation from Source

1. Clone the repository:

   git clone https://github.com/perfect-panel/ppanel-server.git
   cd ppanel-server
   

2. Install dependencies:

   go mod download
   

3. Generate code:

   chmod +x script/generate.sh
   ./script/generate.sh
   

4. Build the project:

   make linux-amd64
   

5. Run the server:

   ./ppanel-server-linux-amd64 run --config etc/ppanel.yaml
   

🐳 Docker Deployment

1. Build the Docker image:

   docker buildx build --platform linux/amd64 -t ppanel-server:latest .
   

2. Run the container:

   docker run --rm -p 8080:8080 -v $(pwd)/etc:/app/etc ppanel-server:latest
   

3. Use Docker Compose (create docker-compose.yml):

   version: '3.8'
   services:
     ppanel-server:
       image: ppanel-server:latest
       ports:
         - "8080:8080"
       volumes:
         - ./etc:/app/etc
       environment:
         - TZ=Asia/Shanghai
   

   Run:

   docker-compose up -d
   

4. Pull from Docker Hub (after CI/CD publishes):

   docker pull ppanel/ppanel-server:latest
   docker run --rm -p 8080:8080 ppanel/ppanel-server:latest
   

📖 API Documentation

Explore the full API documentation:

• Swagger: https://ppanel.dev/en-US/swagger/ppanel

The documentation covers all endpoints, request/response formats, and authentication details.

🔗 Related Projects

Project	Description	Link
PPanel Web	Frontend for PPanel	GitHub
PPanel User Web	User interface for PPanel	Preview
PPanel Admin Web	Admin interface for PPanel	Preview

🌐 Official Website

Visit ppanel.dev for more details.

🏛 Architecture

📁 Directory Structure

.
├── apis/             # API definition files
├── cmd/              # Application entry point
├── doc/              # Documentation
├── etc/              # Configuration files (e.g., ppanel.yaml)
├── generate/         # Code generation tools
├── initialize/       # System initialization
├── internal/         # Internal modules
│   ├── config/       # Configuration parsing
│   ├── handler/      # HTTP handlers
│   ├── middleware/   # HTTP middleware
│   ├── logic/        # Business logic
│   ├── model/        # Data models
│   ├── svc/          # Service layer
│   └── types/        # Type definitions
├── pkg/              # Utility code
├── queue/            # Queue services
├── scheduler/        # Scheduled tasks
├── script/           # Build scripts
├── go.mod            # Go module definition
├── Makefile          # Build automation
└── Dockerfile        # Docker configuration

💻 Development

Format API Files

goctl api format --dir apis/user.api

Add a New API

1. Create a new API file in apis/.
2. Import it in apis/ppanel.api.
3. Regenerate code:

   ./script/generate.sh
   

Build for Multiple Platforms

Use the Makefile to build for various platforms (e.g., Linux, Windows, macOS):

make all  # Builds linux-amd64, darwin-amd64, windows-amd64
make linux-arm64  # Build for specific platform

Supported platforms include:

• Linux: 386, amd64, arm64, armv5-v7, mips, riscv64, loong64, etc.
• Windows: 386, amd64, arm64, armv7
• macOS: amd64, arm64
• FreeBSD: amd64, arm64

🤝 Contributing

Contributions are welcome! Please follow the Contribution Guidelines for bug fixes, features, or documentation improvements.

✨ Special Thanks

A huge thank you to the following outstanding open-source projects that have provided invaluable support for this project's development! 🚀

Project	Description	Project	Description
Gin	High-performance Go Web framework	Gorm	Powerful Go ORM framework
Asynq	Asynchronous task queue for Go	Go-Swagger	Comprehensive Go Swagger toolkit
Go-Zero	Go microservices framework (this project's API generator is built on Go-Zero)

---

🎉 Salute to Open Source: Thank you to the open-source community for making development simpler and more efficient! Please give these projects a ⭐ to support the open-source movement!

📄 License

This project is licensed under the GPL-3.0 License.