JoyLive-Control-Plane

中文文档

Introduction

A microservice governance control plane for joylive-agent, providing centralized management of traffic routing, rate limiting, circuit breaking, fault injection, load balancing, and lane-based traffic isolation policies.

Project Structure

This project follows a clean architecture pattern with dependency injection via Google Wire:

• Language: Go 1.23
• HTTP Framework: Gin
• gRPC: gRPC
• ORM: GORM (MySQL, PostgreSQL, SQLite, OpenGauss)
• DI: Google Wire
• Configuration: Viper
• Logging: Zap

joylive-control-plane/
├── cmd/               # Application entry points
│   └── server/        # Server entry + Wire DI
├── internal/          # Core business logic
│   ├── handler/       # HTTP request handlers
│   ├── service/       # Business logic layer
│   ├── repository/    # Data access layer (GORM)
│   ├── model/         # Domain models and DTOs
│   ├── middleware/     # CORS, JWT, logging, signature
│   └── server/        # HTTP/gRPC server, jobs, tasks
├── pkg/               # Shared utility packages
├── api/               # API response types and error definitions
├── config/            # YAML configuration files
├── deploy/            # Docker, docker-compose, K8s deployment
├── docs/              # Swagger documentation
├── test/              # Unit tests and mocks
├── web/               # Frontend placeholder
├── Makefile           # Build scripts
└── Dockerfile         # Docker build configuration

Quick Start

Local Development

1. Prerequisites

Make sure you have the following installed:

• Go 1.23+
• MySQL 5.7+ (or PostgreSQL / SQLite / OpenGauss)
• Redis 6.0+

2. Start Dependencies

# Start MySQL and Redis via Docker Compose
cd deploy/docker-compose
docker-compose up -d

3. Configure

Configuration files are located in the config/ directory. The default local.yml connects to:

• MySQL: 127.0.0.1:3380 (database: joylive)
• Redis: 127.0.0.1:6350
• HTTP: 0.0.0.0:8000
• gRPC: 0.0.0.0:20325

Override via environment variables:

export APP_CONF=config/local.yml  # Config file path
export DB_TYPE=mysql              # Database driver
export DB_DSN="user:pass@tcp(host:port)/dbname?charset=utf8mb4&parseTime=True"

4. Build and Run

# Install dev tools (wire, mockgen, swag)
make init

# Generate Wire dependency injection
make wire

# Build server binary
make build

# Run the server
./bin/server

5. Access

• HTTP API: http://localhost:8000
• Swagger UI: http://localhost:8000/swagger/index.html

Docker Deployment

1. Build Image

# Cross-compile for linux/amd64 and build Docker image
make image

2. Run Container

# Option 1: Using Docker Compose (recommended)
cd deploy/docker-compose
docker-compose up -d

# Option 2: Manual run
docker run -d -p 8000:8000 -p 20325:20325 --name joylive-control-plane joylive-control-plane:latest

3. Kubernetes Deployment

kubectl apply -f deploy/deployment.yaml

Build Commands

# Install dev tools
make init

# Build server binary
make build

# Generate Wire DI code
make wire

# Generate Swagger docs
make swagger

# Generate mocks
make mock

# Run tests
make test

# Build Docker image
make docker

# Cross-compile and build Docker image
make image

# Push Docker image
make push

Configuration

Configuration Files

• config/local.yml - Development environment
• config/prod.yml - Production environment

Key Configuration Items

Section	Description
server.http	HTTP server address and port
server.grpc	gRPC server address and port
database	Database driver and DSN
redis	Redis connection
jwt	JWT signing key
log	Log level, format, and output
agent	Agent download URL and auto-push settings

Architecture

┌─────────────────────────────────────────────────────┐
│                   joylive-agent                      │
│              (Policy Pull via HTTP)                  │
└───────────────────────┬─────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────┐
│              joylive-control-plane                   │
│  ┌──────────────────────────────────────────────┐   │
│  │  HTTP Server (Gin)     gRPC Server           │   │
│  │       │                      │               │   │
│  │  Middleware (CORS/JWT/Log/Sign)              │   │
│  │       │                                      │   │
│  │  Handlers (21 modules)                       │   │
│  │       │                                      │   │
│  │  Services (Business Logic)                   │   │
│  │       │                                      │   │
│  │  Repositories (GORM)                         │   │
│  └──────────────────────────────────────────────┘   │
│       │                │                │            │
│    MySQL            Redis           Registry         │
│  (Policy Store)    (Cache)      (Nacos/K8s/Istio)   │
└─────────────────────────────────────────────────────┘

Related Projects

1. joylive-agent - A Java microservice governance data-plane agent based on bytecode enhancement.

2. joylive-dashboard - A microservice governance console for managing policies and monitoring services.

3. joylive-injector - A component to automatically inject joylive-agent in cloud-native environments.

License

This project is licensed under the Apache License. See the LICENSE file for details.