Goravel Admin

SaaS ops + admin starter — Goravel · DB-per-tenant platform · Vue 3 / React · RBAC · Docker in 3 minutes

English | 中文  ·  Docs · Tenant demo · Platform ops
Demo login: demo / demo123

• SaaS ops path — database-per-tenant, platform console, provision → migrate → ready gate, /health /ready (TENANCY_DRIVER=database)
• Dual frontend — Vue 3 + Element Plus or React + Ant Design 6, same /api/admin
• Batteries included — JWT / RBAC, menus, logs, export, WebSocket notices, code generator, AI Lab

Good fit: mid-size multi-tenant SaaS ops, internal admin panels, Goravel secondary development.
Not a drop-in: financial trading cores or large commercial SaaS without extra ops. Module tiers: Open-source scope.

git clone https://github.com/wangxuancheng-dev/goravel-admin.git
cd goravel-admin
cp .env.docker.example .env
docker compose up -d --build
# http://localhost:3000  —  admin / admin123 (change ASAP)

Multi-tenant demo (optional): Platform ops → provision tenant → Tenant login.

UI dev (optional): Vite Vue html/ → :3007, React html-react/ → :3008, API at http://127.0.0.1:3000.

Platform Console (Tenant Management)

Login Page

React Admin Dashboard

Code Generator

System Monitoring

AI code generation

AI Lab (text, vision, image, audio; demo-ready with per-admin rate limits)

Cloudflare deploy

• Authentication & Authorization

  • JWT-based authentication
  • Role-based access control (RBAC)
  • Permission management
  • Multi-token management
  • Online admin monitoring and kick-out

• Admin Management

  • Admin user management
  • Department management
  • Role management
  • Permission assignment
  • Password reset

• System Configuration

  • Menu management (dynamic menu)
  • Dictionary management
  • System configuration
  • Blacklist management

• Logging & Monitoring

  • Operation logs (with automatic recording)
  • Login logs
  • System logs (with trace ID)
  • Service monitoring

• Additional Features

  • Dashboard with statistics
  • Notification center (WebSocket real-time notifications)
  • Data export management
  • AI Lab (top-level menu; Goravel AI SDK demos: text chat, vision, image gen, TTS, STT; enabled when AI_API_KEY is set, per-admin rate limits)
  • Multi-language support (Chinese/English)
  • Responsive UI design

Enable only when needed (see opensource):

• Monthly order/payment sharding and balance-log hash sharding
• Elasticsearch order sync / search
• Redis async queues and long-running export jobs (QUEUE_CONNECTION=redis)
• OpenTelemetry export to Jaeger / Grafana
• Payment admin sample (not a full acquiring stack: no production notify/refund — see opensource)

Backend:

• Goravel Framework (Go)
• RBAC Permission System
• WebSocket Support
• Database Migrations & Seeders

Frontend (pick one):

Both frontends talk to /api/admin and must ship new admin features together. React covers the main modules (including code generator and AI Lab). Details: html-react/README.md.

1. Backend Setup:

   # Install dependencies
   go mod tidy
   
   # Configure database in .env
   # Run migrations and seeders
   go run . artisan migrate
   go run . artisan db:seed
   
   # Start server
   go run .
   # or: go run . --no-ansi
   # or use air for live reload
   air

2. Frontend Setup (Vue):

   cd html
   
   # Install dependencies
   npm install
   
   # Configure API address in .env
   # VITE_API_BASE_URL=http://127.0.0.1:3000
   # VITE_API_PREFIX=/api/admin
   
   # Start development server (default http://localhost:3007)
   npm run dev

3. Frontend Setup (React, optional):

   cd html-react
   cp .env.example .env
   npm install
   npm run dev

   Dev server defaults to http://localhost:3008. Allow that origin in root .env CORS (and Accept-Language), then restart the Go backend. See html-react/README.md.

4. Default Login:

   • Username: admin
   • Password: admin123
   • (Please change the default password after first login)

For detailed build and deployment instructions, including cross-platform compilation, Docker deployment, and systemd service setup, please refer to build guide.

The admin API endpoints are prefixed with /api/admin. All endpoints require JWT authentication except login and captcha.

Routes are defined in routes/admin.go (tenant admin, /api/admin), routes/platform.go (platform console, /api/platform), and routes/api.go (end-user API, /api).

The project includes Swagger API documentation for interactive API exploration.

Error code overview for frontend integration: error codes

Access Swagger Documentation:

Swagger is off by default. Set SWAGGER_ENABLED=true in .env (keep it off or protected in production), then open:

• Local development: http://localhost:3000/swagger/index.html
• Production: https://your-domain.com/swagger/index.html

Regenerate Swagger Documentation:

After modifying API routes or adding new endpoints, regenerate the Swagger documentation:

# Generate Swagger documentation
swag init

This will regenerate the docs/docs.go, docs/swagger.json, and docs/swagger.yaml files based on the Swagger annotations in your code (see main.go for example annotations).

.
├── app/
│   ├── http/
│   │   ├── controllers/
│   │   │   ├── admin/            # Tenant admin controllers
│   │   │   ├── platform/         # Platform console controllers
│   │   │   └── api/              # End-user API controllers
│   │   ├── middleware/           # Middleware (tenant, JWT, permission, operation log)
│   │   └── helpers/              # Helper functions
│   ├── models/                   # Database models
│   ├── services/                 # Business logic services
│   └── jobs/                     # Queue jobs (export, import, tenant ops)
├── routes/
│   ├── admin.go                  # Tenant admin routes (/api/admin)
│   ├── platform.go               # Platform console routes (/api/platform)
│   └── api.go                    # End-user API routes (/api)
├── database/
│   ├── migrations/               # Database migrations
│   └── seeders/                  # Database seeders
├── html/                         # Frontend Vue application
│   └── src/
│       ├── views/                # Page components
│       ├── components/           # Reusable components
│       ├── api/                 # API client
│       └── store/               # Pinia stores
├── html-react/                   # Frontend React application (Vue parity)
│   └── src/
│       ├── pages/                # Page components
│       ├── components/           # Reusable components
│       ├── api/                  # API client
│       └── stores/               # Zustand stores
├── config/                       # Configuration files
├── docs/                         # Generated Swagger files only (docs.go, swagger.json, swagger.yaml)
├── website/docs/                 # Project documentation (VitePress site)
├── tests/feature/                # Feature tests (need MySQL + Redis)
├── scripts/                      # CI guards and deploy scripts
├── CONTRIBUTING.md               # Contribution guidelines
├── CHANGELOG.md                  # Version history
└── images/                       # Screenshots

Monthly sharding (orders, etc.) is supported. New users can skip this until data volume requires it.
See sharding migration and opensource.

• Minimal production (admin-focused, no sharding / ES): opensource · template .env.production.example
• Full advanced stack (queues, sharding, ES, OTEL): opensource

• JWT token-based authentication
• Permission middleware for route protection
• Automatic operation logging
• Sensitive data filtering in logs
• Rate limiting on login endpoints
• Blacklist management for IP/Admin blocking
• Token revocation support

go run . or go run . --no-ansi or air

Deploy the frontend to Cloudflare Workers (Vue: html/, React: html-react/, same setup):

# Build the frontend (React example; use cd html for Vue)
cd html-react
# Note: Cloudflare Workers build environment automatically runs npm ci
# If you encounter Rollup optional dependency issues, use the following build command:
npm install --include=optional @rollup/rollup-linux-x64-gnu && npm run build

# Or use the project's CI build script:
npm run build:ci

# Deploy to Cloudflare Workers (requires wrangler.toml + worker.js in this directory;
# otherwise refreshing nested routes returns 404)
npx wrangler deploy

Configuration:

• Root directory: html-react (Vue: html)
• Environment variables (Variables & Secrets):
  • VITE_API_BASE_URL: https://api.xuancheng888.top
  • VITE_API_PREFIX: /api/admin
  • VITE_TENANT_DEMO_LOGIN_URL (optional): https://acme.xuancheng888.top/login?tenant_code=acme
• Custom domain: admin.xuancheng888.top

Note: worker.js handles SPA routing by falling back to index.html for non-asset paths. Uploading only dist without the Worker will 404 on refresh of routes like /admins.

Vanity / custom domains (different apex from API): the SPA opens wss://<page-host>/ws/... (same-origin). Set API_ORIGIN in wrangler.toml [vars] (e.g. https://api.xuancheng888.top) so the Worker proxies /ws to the API. Without that proxy, WebSocket never reaches Go.

Docs live under website/ and should be a separate Worker / domain from the admin SPA:

cd website
npm install
npm run build
npx wrangler deploy
# or: npm run deploy

• Root directory: website/ (wrangler.toml + worker.js)
• Output: docs/.vitepress/dist
• Suggested custom domain: docs.xuancheng888.top (do not share the admin Worker)
• Details: website/README.md

pprof is served at http://localhost:3000/debug/pprof/ when APP_DEBUG=true (or PPROF_ENABLED=true) and at least one of PPROF_TOKEN / PPROF_ALLOWED_IPS is set; without either control the routes are not registered.

Debug dashboard (requests / SQL / logs / jobs, development only): http://localhost:3000/goralens. See the Goralens docs.

To reduce the binary size, you can use UPX (Ultimate Packer for eXecutables) to compress the compiled executable:

Windows:

1. Download UPX (Windows 64-bit version):

   • Official download: https://github.com/upx/upx/releases/latest
   • Select upx-5.0.2-win64.zip (or the latest version)
   • Extract the zip to a path without non-ASCII characters or spaces (e.g., C:\tools\upx)
   • Ensure upx.exe is accessible

2. Compress the binary (PowerShell):

   # Option 1: Temporarily add UPX to PATH (recommended)
   $env:PATH += ";C:\tools\upx"
   
   # Run from the project root (where the compiled binary is)
   cd path\to\goravel-admin
   
   # Maximum compression level (-9)
   upx -9 main

Linux/macOS:

# Install UPX (if not already installed)
# Ubuntu/Debian: sudo apt-get install upx
# macOS: brew install upx

# Compress the binary
upx -9 main

Preferred: VitePress docs site — only maintain website/docs/ (+ website/docs/en/)

cd website && npm install && npm run dev

Root docs/ now only holds Swagger artifacts (docs.go / swagger.json / swagger.yaml), not project guides.

Built on Goravel — a Laravel-style Go web framework. See https://www.goravel.dev for framework docs.

Online documentation https://www.goravel.dev

To optimize the documentation, please submit a PR to the documentation repository https://github.com/goravel/docs

Welcome more discussion in Discord.

https://discord.gg/cFc5csczzS

The Goravel framework is open-sourced software licensed under the MIT license.