# Madong Admin Backend Framework
A high-performance admin backend platform built on PHP Webman, using a **front-end / back-end separation + dual front-end** architecture
[](https://www.php.net)
[](https://www.workerman.net/doc/webman)
[](https://www.mysql.com)
[](https://redis.io)
[](./LICENSE)
[](https://madong.tech)
[](http://v5.madong.tech/admin)
[中文](./README.md) | **English**
## Introduction
Madong is a blazing-fast development platform built on the PHP **Webman** framework, providing a stable, high-performance API service layer for front-end applications. The backend uses a clear domain-layered architecture and a first-class plugin system; the front end supports **dual front-end UIs** — two selectable Admin UIs (Single / Aura) for the backend panel, plus an independent Web site front-end shared with the multi-tenant edition.
> The front end and back end are deployed separately. The front-end directory must be downloaded or created separately.
## Dual Front-End UI Repository Addresses
Madong supports **dual front-end UIs**: the admin panel offers two selectable UIs (Single / Aura), and the site front-end is shared with the multi-tenant edition. **Pull from GitHub by default**; switch to the Gitee / GitCode mirrors if the network is restricted.
| Module | GitHub | Gitee Mirror | GitCode Mirror |
| :--- | :--- | :--- | :--- |
| Server | https://github.com/madong-code/madong-admin | https://gitee.com/motion-code/madong-admin | https://gitcode.com/motion-code/madong-admin |
| Admin(single) | https://github.com/madong-code/madong-single | https://gitee.com/motion-code/madong-single | https://gitcode.com/motion-code/madong-single |
| Admin(aura) | https://github.com/madong-code/madong-aura | https://gitee.com/motion-code/madong-aura | https://gitcode.com/motion-code/madong-aura |
| Web | https://github.com/madong-code/web-nuxt | https://gitee.com/motion-code/web-nuxt | https://gitcode.com/motion-code/web-nuxt |
| Skills | https://github.com/madong-code/madong-admin-skills | https://gitee.com/motion-code/madong-admin-skills | https://gitcode.com/motion-code/madong-admin-skills |
> The Gitee / GitCode mirrors live under the `motion-code/…` org, same repo names as GitHub; adjust if the actual address differs.
> Pick either Admin UI for `template/admin`; the site uses `web-nuxt`, shared with the multi-tenant edition.
> Install / download commands pull from GitHub by default, e.g. `php webman madong-download:frontend --admin`; for mirrors, configure `dependencies.npm.registry` etc., or specify a mirror repository address directly.
## Tech Stack
| Technology | Description |
|------------|-------------|
| PHP | 8.2 ~ 8.4, core development language |
| Webman | 2.2, high-performance PHP framework |
| MySQL | 8.0+, database |
| Redis | 7.0+, cache service |
| Composer | 2.x, dependency manager |
| Nginx / Apache | Web server |
## Project Structure
```
madong/
├── backend/ # Backend (CLI installer included; one-click install configures automatically)
└── template/ # Front-end templates (admin / web / install; download separately, see table above)
```
> For more modules, directories and developer docs, see the official documentation: [madong.tech](https://madong.tech)
## Core Features
- **Authentication**: JWT-based authentication mechanism
- **Authorization**: Fine-grained permission control system
- **Caching**: Integrated Redis cache
- **Communication**: Mail / SMS / notification infrastructure
- **File Upload**: Multiple storage backends supported
- **Internationalization**: Multi-language configuration support
- **Plugin System**: Third-party extensions (codegen, demo, etc.)
- **SSE Push**: Real-time Server-Sent Events progress feedback
- **Layered Architecture**: Clear DAO / Service layering
- **Code Generator**: Auto-generates controllers, models and service-layer code
- **Database Migration**: Versioned database management
- **Dual Front-End UI**: Two selectable Admin UIs plus an independent site front-end (shared with the multi-tenant edition)
## Requirements
- PHP 8.2 ~ 8.4
- MySQL 8.0+
- Redis 7.0+
- Nginx / Apache
- Composer 2.x+
- Node.js (with pnpm, for front-end builds)
## Installation & Deployment
### 1. Prepare the environment
Install: PHP 8.2 ~ 8.4, MySQL 8.0+, Redis 7.0+, Composer 2.x+, Node.js (with pnpm), Git.
### 2. Install backend dependencies
```bash
cd backend
composer install
```
### 3. Download front-end assets
**Option A: Command download (recommended)** — pulls from the GitHub repos in the table above by default:
```bash
cd backend
php webman madong-download:frontend # admin + web
php webman madong-download:frontend --admin # admin only
php webman madong-download:frontend --web # web only
php webman madong-download:frontend -b develop # specific branch
php webman madong-download:frontend -f # force overwrite
```
**Option B: Manual download** — clone from the GitHub URLs in the "Dual Front-End UI Repository Addresses" table; pick either Admin UI into `template/admin`, and the site into `template/web`.
### 4. Launch the installer
```
http://127.0.0.1:8500/install
```
### 5. Start the service
```bash
cd backend
php start.php start # development
php start.php start -d # production (daemonized)
```
The service runs at `http://127.0.0.1:8500` by default.
## Configuration
Database, Redis and other connection settings are written automatically by the one-click installer — no manual editing required.
> For more configuration options and advanced usage, see the official documentation: [madong.tech](https://madong.tech)
## Plugin Dependency Management
Plugins declare dependencies in `config/info.php` via `require.composer` (backend) and `npm_require.admin|web|common` (frontend). Install / uninstall is handled by the dependency pipeline in `core/business/plugin`:
- **Declaration merge**: merged into `composer.json` and `template/{admin,web}/package.json`; conflicts follow `dependencies.conflict.strategy` (`skip`/`override`/`fail`, default `skip`)
- **Real installation**: `dependencies.auto_install` defaults to `false` (merge only, print pending commands); set `true` to run `composer update` and `pnpm install` automatically
- **Network resilience**: `dependencies.network.retry` controls retries; `dependencies.composer.mirror` / `dependencies.npm.registry` configure mirrors
- **Reference counting**: a shared dependency is only removed when the last plugin using it is uninstalled
- **State persistence**: dependency state is stored in the plugin's `config/installed.php` (no database); a failed install does not abort the plugin install by default
- **Transaction rollback**: failed install / uninstall restores dependency declarations and template directories
If the network is unavailable during install, retry later:
```bash
php webman madong-plugin:install-deps