# kadmin

**Repository Path**: topextend/kadmin

## Basic Information

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

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Kadmin

ThinkPHP 8 + Vue 3 通用管理后台，前后端同仓。后端 API 基于 [topextend/think-library](https://packagist.org/packages/topextend/think-library) ^1.0，提供 JWT 鉴权、RBAC、操作日志、系统配置等基础设施；前端为 Element Plus + Pinia 单页应用，构建产物输出到 `public/dist/`。

## 技术栈

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

## 功能概览

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

---

## 目录结构

```
kadmin/
├── app/                        # 后端应用（ThinkPHP 多应用）
│   ├── admin/                  # 管理后台 API（URL 前缀 /admin）
│   │   ├── application/        # 业务用例层（Manage 类，编排业务逻辑）
│   │   ├── controller/         # HTTP 入口（薄控制器，转发到 Manage）
│   │   ├── persistence/        # 数据访问层（Repository，封装表操作）
│   │   ├── infrastructure/     # 基础设施适配（如操作日志写入）
│   │   ├── support/            # 控制器基类等支撑代码
│   │   ├── command/            # CLI 命令（计划任务调度等）
│   │   └── route/app.php       # admin 路由定义
│   ├── install/                # 安装向导 API（URL 前缀 /install）
│   │   ├── application/        # InstallService 等安装逻辑
│   │   ├── controller/
│   │   └── route/app.php
│   └── index/                  # 默认应用，健康检查等
│       └── controller/
│
├── config/                     # ThinkPHP 全局配置
│   ├── app.php                 # 多应用映射、CORS 开关与来源
│   ├── library.php             # think-library 绑定（JWT/RBAC/Oplog/sysconf）
│   ├── database.php            # 数据库连接
│   ├── jwt.php                 # JWT 算法与 TTL
│   └── …                       # cache、log、filesystem 等
│
├── database/                   # 数据库安装脚本（MySQL / PostgreSQL 各一套）
│   ├── mysql/
│   │   ├── install.sql         # 建表 + 基础种子（部门、角色、菜单页、配置、字典）
│   │   ├── menu-buttons.sql    # 菜单按钮节点与 api_list（RBAC）
│   │   └── table-columns.sql   # 各列表页默认列配置（platform_table）
│   └── pgsql/                  # 同上，PostgreSQL 语法
│
├── deploy/                     # 生产部署
│   ├── DEPLOY.md               # 宝塔 / Gitee Webhook 部署说明
│   └── deploy.sh               # WebHook 部署：git 同步 + composer + npm build
│
├── lang/                       # 后端语言包（API 错误信息等）
│   ├── zh-cn/
│   └── en-us/
│
├── public/                     # Web 根目录（站点运行目录指向此处）
│   ├── index.php               # 入口
│   ├── dist/                   # 前端构建产物（npm run build 输出）
│   ├── img/                    # 静态图片
│   └── install.lock            # 安装完成标记（Git 忽略，仅服务器本地存在）
│
├── runtime/                    # 运行时缓存与日志（Git 忽略）
│
├── web/                        # 前端源码（Vue 3）
│   ├── src/
│   │   ├── api/                # 接口封装与类型
│   │   ├── components/         # 通用组件（ScTable、ScUpload、MediaPicker 等）
│   │   ├── composables/        # 组合式函数
│   │   ├── config/             # 前端常量配置
│   │   ├── directives/         # 自定义指令（如 v-auth）
│   │   ├── layout/             # 布局壳（侧栏、顶栏、TagsView）
│   │   ├── locales/            # i18n 语言包
│   │   ├── router/             # 路由（静态 + 动态菜单路由）
│   │   ├── stores/             # Pinia 状态（user、site、tags 等）
│   │   ├── utils/              # 工具函数
│   │   └── views/              # 页面
│   │       ├── install/        # 安装向导
│   │       ├── login/          # 登录
│   │       ├── dashboard/      # 控制台
│   │       ├── setting/        # 系统管理各模块
│   │       └── user/           # 个人中心
│   ├── scripts/                # 构建辅助脚本（类型生成等）
│   ├── .env.example            # 开发环境变量模板
│   └── .env.production.example # 生产 VITE_API_URL 模板
│
├── .env.example                # 后端环境变量模板
├── composer.json
└── README.md
```

### 后端分层说明

```
HTTP 请求
  → Controller（参数校验、响应封装）
    → Manage / Application（业务用例）
      → Repository（表级 CRUD）
        → platform_* 数据表
```

- **Controller**：不含复杂业务，继承 `AdminController`，统一 success/error 响应。
- **Manage**（`application/`）：如 `UserManage`、`RoleManage`，处理权限、校验、事务编排。
- **Repository**（`persistence/`）：单表或关联查询封装。
- **think-library**：通过 `config/library.php` 注入 JWT 密钥解析、RBAC 守卫、操作日志 scope 等。

### 前端路由说明

| 类型 | 来源 | 说明 |
|------|------|------|
| 静态路由 | `router/index.ts`、`router/systemRoutes.ts` | 登录、安装、404、个人中心等 |
| 动态路由 | `/admin/bootstrap` 返回的菜单树 | 按 RBAC 权限动态注册 `views/setting/*` |

---

## 数据库与默认种子

表前缀默认为 **`platform_`**（可在安装时通过 `DB_PREFIX` 自定义，SQL 文件中的 `platform_` 会被替换）。

| 表 | 用途 |
|----|------|
| `platform_user` | 管理员账号 |
| `platform_role` / `platform_user_role` / `platform_role_menu` | 角色与权限 |
| `platform_dept` | 部门 |
| `platform_menu` | 菜单树（含按钮节点与 `api_list`） |
| `platform_config` | 系统配置（站点名、存储、JWT 等） |
| `platform_dict` / `platform_dict_item` | 数据字典 |
| `platform_table` | 各列表页表格列 JSON 配置 |
| `platform_message` / `platform_message_read` | 消息中心 |
| `platform_queue` | 计划任务 |
| `platform_media` | 素材库 |
| `platform_oplog` | 操作日志 |
| `platform_async_task` | 异步任务（导出等） |

**默认种子内容**（不含敏感数据）：

- 站点名：`Kadmin后台管理系统` / `Kadmin Management System`
- 内置角色：超级管理员（`super`）
- 默认部门：后台管理部
- 完整菜单树 + RBAC 按钮（含 `setting-queue.commands` 等隐藏节点）
- 8 张业务表的列布局（用户/角色/部门/字典项/消息/计划任务/日志/表格列管理）
- 全体欢迎消息
- 本地存储默认配置（域名留空，安装时可填）

**不写入种子**：管理员账号、JWT 密钥、`install_completed` 标记——均由安装向导在运行时生成。

`TableColumnSeeds.php` 与 `database/*/table-columns.sql` 保持同步，供安装 SQL 与运行时 `PlatformSchema::seedTablesIfEmpty()` 共用。

---

## 安装

### 方式一：Web 安装向导（推荐）

1. 配置 Web 服务器，**运行目录指向 `public/`**
2. 复制环境文件并安装依赖：

```bash
composer install
cp .env.example .env
cd web && npm install && npm run build && cd ..
```

3. 浏览器访问 **`https://your-domain/install`**
4. 按向导完成：环境检测 → 数据库连接与迁移 → 创建管理员 → 站点信息 → 存储 → 安全（JWT）→ 完成
5. 完成后生成 **`public/install.lock`**，此后 `/install` 将拒绝再次安装

安装向导会自动：

- 依次执行 `install.sql` → `menu-buttons.sql` → `table-columns.sql`
- 写入 `.env`（数据库、表前缀等）
- 将当前访问域名写入 `CORS_ORIGINS`
- 生成 JWT 密钥并保存到 `platform_config`

### 方式二：手动导入 SQL

```bash
composer install
cp .env.example .env
# 编辑 .env 填写数据库

# MySQL
mysql -u root -p your_database < database/mysql/install.sql
mysql -u root -p your_database < database/mysql/menu-buttons.sql
mysql -u root -p your_database < database/mysql/table-columns.sql

# PostgreSQL
psql -U postgres -d your_database -f database/pgsql/install.sql
psql -U postgres -d your_database -f database/pgsql/menu-buttons.sql
psql -U postgres -d your_database -f database/pgsql/table-columns.sql
```

手动导入后仍需通过 `/install` 或自行配置 `.env`、创建管理员；**推荐始终走安装向导**。

### 安装状态判定

| 条件 | 前端行为 |
|------|----------|
| 存在 `public/install.lock` | 已安装，正常进入登录页 |
| 无 lock，安装 API 可用 | 跳转 `/install` |
| 无 lock，安装 API 不可用 | 显示服务不可用页（多为数据库未配置） |

---

## 本地开发

```bash
# 终端 1：后端（默认 8787）
composer install
cp .env.example .env
php think run -p 8787

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

- 前端开发地址：`http://127.0.0.1:5174`
- 后端 API：`http://127.0.0.1:8787/admin/...`
- 安装 API：`http://127.0.0.1:8787/install/...`
- `web/.env.example` 中 `VITE_API_URL` 留空即可走 Vite 代理

类型检查与生产构建：

```bash
cd web && npm run build    # 含 vue-tsc，输出到 public/dist/
```

---

## 配置说明

### 后端 `.env`

| 变量 | 说明 |
|------|------|
| `APP_DEBUG` | 调试模式（生产务必 `false`） |
| `DB_DRIVER` | `mysql` 或 `pgsql` |
| `DB_HOST` / `DB_NAME` / `DB_USER` / `DB_PASS` / `DB_PORT` | 数据库连接 |
| `DB_PREFIX` | 表前缀（默认空，即 `platform_`） |
| `DEFAULT_LANG` | 默认语言 `zh-cn` / `en-us` |
| `CORS_ORIGINS` | 允许跨域的前端 Origin，逗号分隔；安装时自动写入 |
| `CLOUD_JWT_SECRET` / `JWT_SECRET` | JWT 密钥（≥32 位；安装向导也会写入 `platform_config`） |
| `DOMAIN_BIND_ADMIN` | 可选，将指定域名直接绑定 admin 应用 |

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

```env
# 前后端同域（Nginx 反代 /admin）
VITE_API_URL=/admin

# 前后端分域
VITE_API_URL=https://api.example.com/admin
```

### `config/library.php`

绑定 think-library 与 kadmin 业务：

- `sysconf` → `platform_config`（`AdminScope::confGet/confSet`）
- `sysdata` → `platform_data`
- `sysoplog` → 操作日志 scope `admin`
- `jwt.scopes.admin` → JWT 校验、用户解析、忽略路由
- `rbac` → 菜单节点与 API 权限匹配

中间件（CORS、JWT、RBAC、Oplog 等）由 think-library 自动注册，**无需在项目中重复编写**。

---

## API 概览

多应用 URL 映射见 `config/app.php`：`/admin/*` → `app/admin`，`/install/*` → `app/install`。

### 管理后台 `/admin`

| 分组 | 示例路径 | 说明 |
|------|----------|------|
| 认证 | `POST /admin/auth/login` | 登录 |
| 引导 | `GET /admin/bootstrap` | 初始化（菜单、权限、站点信息） |
| 用户 | `GET /admin/admin/list` | 用户 CRUD、分配角色、重置密码 |
| 系统 | `GET /admin/system/role/list` | 角色、部门、菜单、字典、队列表等 |
| 配置 | `PUT /admin/config/sys` | 站点 / 安全设置 |
| 存储 | `PUT /admin/config/storage` | 存储配置 |
| 素材 | `POST /admin/media/upload` | 素材库 |
| 账户 | `GET /admin/account/messages` | 个人消息、任务 |

完整路由见 `app/admin/route/app.php`。

### 安装 `/install`

| 路径 | 说明 |
|------|------|
| `GET /install/status` | 安装状态 |
| `GET /install/check` | 环境检测 |
| `POST /install/db-test` | 数据库连接测试 |
| `POST /install/db-migrate` | 执行 SQL 迁移 |
| `POST /install/admin` | 创建管理员 |
| `PUT /install/site` | 保存站点信息 |
| `PUT /install/storage` | 保存存储配置 |
| `PUT /install/security` | 保存 JWT 等安全项 |
| `POST /install/finish` | 完成安装，写入 install.lock |

---

## 计划任务（CLI）

```bash
# 执行到期的 platform_queue 任务
php think admin:queue:run
```

建议 crontab 每分钟执行一次：

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

内置命令列表通过 RBAC 节点 `setting-queue.commands` 暴露给前端。

---

## 生产部署

详见 **[deploy/DEPLOY.md](deploy/DEPLOY.md)**，概要：

1. 克隆代码，`cp .env.example .env`，配置数据库与 JWT
2. `composer install --no-dev`
3. `cd web && npm ci && npm run build`（输出到 `public/dist/`）
4. 站点运行目录设为 `public/`
5. 访问 `/install` 完成首次配置
6. 可选：Gitee Webhook + 宝塔 Git → `deploy/deploy.sh` 自动更新

**注意**：`.env`、`web/.env.production`、`public/install.lock` 不提交 Git；生产构建使用 `composer install`，避免随意 `composer update` 导致依赖漂移。

---

## 仓库

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