server

PPanel Server

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.

🚀 Quick Start

Prerequisites

• Go: 1.27.1 or higher
• Database: MySQL 8.0+, MariaDB 11.8+ or PostgreSQL 16+, and Redis 6.0+
• Docker: Optional, for containerized deployment
• Git: For cloning the repository

Deploying a release binary instead of building? See the installation guide (script/install.sh, systemd unit, checksum verification) and the configuration guide.

Installation from Source

1. Clone the repository:

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

2. Install dependencies:

   go mod download
   

3. Build the project (the binaries land in bin/; pick the target of the machine that will run it):

   make linux-amd64
   

4. Run the server:

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

   With an empty configuration file the first start serves the setup wizard on 127.0.0.1 at the configured Port (http://127.0.0.1:8080/init by default), reachable from the same machine only. On a remote host open an SSH tunnel (ssh -L 8080:127.0.0.1:8080 user@host) or set PPANEL_DB and PPANEL_REDIS for a non-interactive installation; both are described in the installation guide.

🐳 Docker Deployment

The image runs as an unprivileged user (uid 65532), listens on port 8080, reads /app/etc/ppanel.yaml and reports its health through ppanel healthcheck (HEALTHCHECK). The first-run setup wizard listens on 127.0.0.1 inside the container and cannot be reached through a published port, so a container deployment provides the connections in one of two ways:

• set PPANEL_DB and PPANEL_REDIS: on the first start the server completes the empty configuration file with them and a generated JWT secret, applies the migrations and creates the first administrator, whose password is printed once in docker logs; or
• mount a pre-filled etc/ppanel.yaml (configuration guide).

1. Build the Docker image:

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

2. Run the container. The mounted configuration file must exist and be writable by uid 65532 on the first start, when the server completes it (replace the database and Redis addresses with yours):

   mkdir -p etc && touch etc/ppanel.yaml && sudo chown 65532:65532 etc/ppanel.yaml
   docker run -d --name ppanel-server -p 8080:8080 \
     -e PPANEL_DB='ppanel:secret@tcp(db.internal:3306)/ppanel' \
     -e PPANEL_REDIS='redis://:secret@redis.internal:6379/0' \
     -v "$(pwd)/etc/ppanel.yaml:/app/etc/ppanel.yaml" \
     ppanel-server:latest
   docker logs -f ppanel-server   # prints the first administrator's password once
   

3. Use Docker Compose. The repository's docker-compose.yml builds the image, publishes port 8080, mounts ./etc/ppanel.yaml and checks the container's health:

   services:
     ppanel:
       container_name: ppanel-server
       build:
         context: .
         dockerfile: Dockerfile
       ports:
         - "8080:8080"
       volumes:
         - ./etc/ppanel.yaml:/app/etc/ppanel.yaml
       # environment:
       #   PPANEL_DB: "ppanel:password@tcp(db:3306)/ppanel"
       #   PPANEL_REDIS: "redis://:password@redis:6379/0"
       healthcheck:
         test: ["CMD", "/app/ppanel", "healthcheck"]
         interval: 30s
         timeout: 5s
         retries: 3
         start_period: 30s
       stop_grace_period: 20s
       restart: always
   

   ./etc/ppanel.yaml must exist as a file before the first docker compose up (Docker creates a directory of that name otherwise) and be writable by uid 65532; uncomment environment or pre-fill the file, then:

   mkdir -p etc && touch etc/ppanel.yaml && sudo chown 65532:65532 etc/ppanel.yaml
   docker compose up -d
   

   stop_grace_period gives the graceful shutdown (HTTP first, then the scheduler, the task worker and the trace exporter, up to about 18 s) the time it needs; with plain docker run, stop with docker stop --time 20.

4. Pull a published image: ppanel/ppanel-server:lts follows the LTS line (master), :latest the feature line, :beta the prereleases, and ghcr.io/perfect-panel/ppanel-server:nightly is the nightly build of dev:

   docker pull ppanel/ppanel-server:lts
   

The server answers GET /healthz (liveness) and GET /readyz (readiness: database and Redis reachable) for monitoring and load balancers; see the configuration guide.

📖 API Documentation

API documentation is generated from Swaggo annotations on the handlers and checked against the routes actually registered by Hertz. The root ppanel.json is the complete Swagger 2.0 document:

ppanel.json

After changing a route, request DTO, or response DTO, run:

./script/generate-swagger.sh
go test ./internal/transport/http/routes -run '^TestSwagger' -count=1

GitHub Actions on master generates the full document plus the admin.json, user.json, common.json, and node.json scopes, then syncs them to docs/public/swagger in perfect-panel/frontend. The GH_TOKEN secret needs Contents write access to that repository.

🔗 Related Projects

🌐 Official Website

Visit ppanel.dev for more details.

🏛 Architecture

📁 Directory Structure

.
├── cmd/              # Application entry point
├── docs/             # Documentation
├── etc/              # Configuration files (e.g., ppanel.yaml)
├── internal/         # Internal modules
│   ├── app/          # Assembly, bootstrap, migrations and scheduling
│   ├── arch/         # Architecture boundary checks
│   ├── auth/         # Shared authentication capabilities
│   ├── config/       # Configuration parsing
│   ├── infra/        # Mail, SMS, shared task messages and infrastructure
│   ├── module/       # Business facades, contracts, entities and adapters
│   ├── repository/   # Repository contracts and transaction assembly
│   └── transport/    # HTTP, WebSocket and task consumers
├── pkg/              # Utility code
├── script/           # Installation and CI helper scripts
├── scripts/          # Performance and maintenance scripts
├── go.mod            # Go module definition
├── Makefile          # Build automation
└── Dockerfile        # Docker configuration

💻 Development

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

Every binary is static (CGO_ENABLED=0 -trimpath), built with the metadata from script/ldflags.sh. The release publishes ppanel-server-<os>-<arch>.tar.gz (.zip for Windows) with a SHA256SUMS file for:

• Linux: 386, amd64, arm64 (plus the linux/amd64 and linux/arm64 container images)
• Windows: 386, amd64, arm64
• macOS: amd64, arm64

make additionally builds linux-amd64-v3, linux-armv5, linux-armv6, linux-armv7, windows-amd64-v3, windows-armv7 and darwin-amd64-v3.

🔒 Security

Report vulnerabilities privately through GitHub Security Advisories, not in public issues. SECURITY.md lists the supported versions and what to expect.

🤝 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
Hertz	High-performance Go HTTP framework	Gorm	Powerful Go ORM framework
Asynq	Asynchronous task queue for Go	Go-Swagger	Comprehensive Go Swagger toolkit

🎉 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.