# kadmin

**Repository Path**: topextend/kadmin

## Basic Information

- **Project Name**: kadmin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-11
- **Last Updated**: 2026-07-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Kadmin

ThinkPHP 8 + Vue 3 通用管理后台（前后端同仓）。后端基于 [topextend/think-library](https://packagist.org/packages/topextend/think-library)，提供 JWT、RBAC、操作日志、系统配置等能力；前端为 Element Plus + Pinia SPA，构建产物输出到 `www/admin/`。

许可证：[MIT](./LICENSE)

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | PHP >= 8.1、ThinkPHP 8、think-orm（`api/`） |
| 前端 | Vue 3、TypeScript、Vite、Element Plus、Pinia、vue-i18n（`web/`） |
| 数据库 | MySQL / PostgreSQL |
| 依赖 | Composer（后端）、npm（前端） |

## 功能概览

- **安装向导**：Web 化首次部署（环境检测 → 数据库 → 管理员 → 站点/存储/安全 → 完成）
- **RBAC**：菜单 + 按钮级权限，角色可配置控制台模块
- **系统管理**：用户、角色、部门、菜单、字典、表格列、计划任务、消息、素材、操作日志
- **账户中心**：个人资料、改密、消息中心、异步任务
- **多语言**：后端 `api/lang/` + 前端 `web/src/locales/`
- **插件中心**：插件市场与安装链路（需配置 `MARKET_BASE_URL`）
- **存储**：本地存储（默认），云存储配置项预留

## 目录结构

```
kadmin/
├── api/                        # 后端（ThinkPHP）
│   ├── app/                    # 多应用：admin / install / index
│   ├── config/                 # 全局配置
│   ├── database/               # MySQL / PostgreSQL 安装脚本
│   ├── lang/                   # 后端语言包
│   ├── public/                 # API Web 根目录（站点运行目录可指向此处）
│   ├── storage/                # 密钥等本地存储
│   ├── composer.json
│   └── think
├── web/                        # 前端源码（Vue 3 + Vite）
├── www/
│   └── admin/                  # 前端构建产物（npm run build 输出，Git 忽略）
├── package.json                # 根目录 npm → 转发到 web/（及 api 启动）
├── LICENSE
└── README.md
```

更细的后端分层与 API 说明见 [api/README.md](./api/README.md)；前端说明见 [web/README.md](./web/README.md)。

## 快速开始

部署后默认**没有** `api/.env` 和 `api/public/install.lock`。访问管理端会自动进入安装向导：数据库初始化时生成 `.env`，完成安装时写入 `install.lock`。

```bash
# 后端依赖
cd api && composer install && cd ..

# 前端：配置 API 地址后构建
# web/.env.production 示例：VITE_API_URL=https://api.example.com/admin
npm install
npm run build
```

然后配置好站点（API → `api/public/`，前端静态 → `www/`），浏览器打开管理端即可安装。

### 本地开发

```bash
# 终端 1：后端（默认 8787），无需事先复制 .env
cd api
php think run -p 8787
# 或在根目录：npm run api

# 终端 2：前端（默认 5174，代理 /admin、/install → 8787）
npm run dev
```

- 前端：`http://127.0.0.1:5174`（无 lock 时自动跳转 `/install`）
- 后端 API：`http://127.0.0.1:8787/admin/...`
- 安装 API：`http://127.0.0.1:8787/install/...`（仅根据 `public/install.lock` 判断是否已安装）

### Web 安装向导

1. API 运行目录指向 `api/public/`；静态管理端使用 `www/admin/`
2. `composer install` 与 `npm install && npm run build`
3. 访问管理端 → 自动进入安装：环境检测 → 数据库 → 管理员 → 站点/存储/安全 → 完成
4. 数据库步骤会写入 `api/.env`；点「完成安装」后生成 `api/public/install.lock`
5. **重装**：删除 `api/public/install.lock`（必要时清空库）后重新打开管理端；仅删库不删 lock 无法进入向导
6. **安全**：安装完成前勿将 `/install` 长期暴露公网；装完后 lock 会拒绝再次安装写入

## 常用命令

| 命令（仓库根目录） | 实际效果 |
|--------------------|----------|
| `cd api && composer install` | 安装后端依赖 |
| `npm install` | 安装 `web/` 依赖 |
| `npm run dev` | 启动前端开发服务 |
| `npm run build` | 前端类型检查 + 构建到 `www/admin/` |
| `npm run api` | 启动后端 `php think run` |

也可分别进入 `api/`、`web/` 使用原有命令。

## 配置要点

### 后端 `api/.env`

| 变量 | 说明 |
|------|------|
| `APP_DEBUG` | 调试模式（生产务必 `false`） |
| `DB_DRIVER` | `mysql` 或 `pgsql` |
| `DB_*` | 数据库连接与表前缀 |
| `CORS_ORIGINS` | 允许跨域的前端 Origin |
| `CLOUD_JWT_SECRET` / `JWT_SECRET` | JWT 密钥（≥32 位） |
| `MARKET_BASE_URL` | 插件中心站点根 URL |

### 前端 `web/.env.production`

```env
# 分域（前端站点 /admin，API 子域）
VITE_API_URL=https://api.example.com/admin
```

前端构建 `base` 固定为 `/admin/`，产物在 `www/admin/`。宝塔示例：

| 站点 | 网站目录 | 运行目录 |
|------|----------|----------|
| `ytween.com` | `.../ytween.com/www` | `/` |
| `api.ytween.com` | `.../ytween.com` | `/api/public` |

`api/.env` 的 `CORS_ORIGINS` 需包含前端 Origin（如 `https://ytween.com`）。

Nginx 需为 `/admin` 做 SPA 回退（宝塔 → 网站 → 配置文件），例如：

```nginx
location /admin/ {
    try_files $uri $uri/ /admin/index.html;
}
```

## 生产部署概要

1. 克隆仓库；配置 `web/.env.production`（`VITE_API_URL` 指向 API，如 `https://api.example.com/admin`）
2. 根目录：`cd api && composer install --no-dev`
3. 根目录：`npm install && npm run build`（输出 `www/admin/`）
4. Web 服务器：API 指向 `api/public/`；管理端静态资源指向 `www/admin/`（网站目录可用 `www/`）
5. **不要**事先复制 `api/.env`；打开管理端走安装向导（migrate 写 `.env`，finish 写 `install.lock`）
6. 如使用插件自动编译前端，配置 Redis 队列 Worker：
   ```bash
   cd api && php think queue:work --queue addon-build --sleep 3 --tries 2 --timeout 900
   ```

**注意**：`api/.env`、`web/.env.production`、`api/public/install.lock`、`www/admin/` 不提交 Git。

## 计划任务

```bash
cd api && php think admin:queue:run
```

```cron
* * * * * cd /path/to/kadmin/api && php think admin:queue:run >> /dev/null 2>&1
```

## 仓库

- Gitee：[topextend/kadmin](https://gitee.com/topextend/kadmin)
- think-library：[Packagist](https://packagist.org/packages/topextend/think-library)