# wos-admin

**Repository Path**: dushu/wos-admin

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-10
- **Last Updated**: 2026-11-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Wos Admin

> 开箱即用的通用后台管理脚手架 · Koa2 + Vue 3 + MySQL 8 · 功能对标若依（RuoYi）· 自带零依赖皮肤 wos-ui

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
[![Vue](https://img.shields.io/badge/vue-3.5-42b883.svg)](https://vuejs.org/)
[![Koa](https://img.shields.io/badge/koa-2.x-33333d.svg)](https://koajs.com/)
[![MySQL](https://img.shields.io/badge/mysql-8.0-4479a1.svg)](https://www.mysql.com/)

一套可直接投产的后台管理底座：**9 个系统管理模块 + 5 个系统监控模块 + JWT 权限体系 + 按钮级权限码 + 部门数据范围**，
前后端全中文注释，约定优于配置。无需 Element Plus / Ant Design，皮肤为 60KB 的零依赖 CSS 设计系统，改一个 `--hue` 变量即可全站换肤。

**English**: A production-ready admin scaffold built with Koa2 + Vue 3 + MySQL 8 — RBAC with button-level permissions,
department-based data scope, operation/login logs, cron jobs, server monitor, and a zero-dependency CSS design system.

---

## 目录

- [功能特性](#功能特性)
- [技术栈](#技术栈)
- [快速开始](#快速开始)
- [默认账号](#默认账号)
- [项目结构](#项目结构)
- [数据库](#数据库)
- [配置项](#配置项)
- [生产部署](#生产部署)
- [权限模型](#权限模型)
- [文档索引](#文档索引)
- [常见问题](#常见问题)
- [参与贡献](#参与贡献)
- [许可证](#许可证)

---

## 功能特性

| 分类 | 能力 |
| --- | --- |
| 系统管理 | 用户、角色、菜单、部门、岗位、字典、参数设置、通知公告、外观设置 |
| 系统监控 | 操作日志、登录日志、在线用户（强退）、定时任务（Cron）、服务监控（CPU/内存/磁盘） |
| 权限体系 | JWT Token、角色菜单授权树、按钮级权限码（`system:user:add`）、部门数据范围（5 档） |
| 登录安全 | 图形验证码（可开关）、密码 bcrypt 加密、登录失败锁定、登录日志留痕 |
| 数据能力 | 统一分页/响应包装、Excel 导入导出、软删除、审计字段自动填充 |
| 外观个性化 | 主题色（色相滑杆 + 6 套预设，全站含登录页生效）、侧边栏折叠记忆、登录页背景图 |
| 站点信息 | 系统名称 / 副标题 / 版权 / ICP 备案 / 公网安备，后台可配，登录页与页脚同步展示 |
| 插件市场 | `plugin.json` 契约 + 运行时热插拔（内置腾讯云短信、阿里云短信两个示例插件） |
| 工程质量 | 严格 TypeScript 类型检查、60+ 项冒烟断言、可重复执行的数据库初始化 |

## 技术栈

| 端 | 技术 |
| --- | --- |
| 后端 | Node.js ≥ 18 · Koa 2 · @koa/router · Sequelize 6 · MySQL 8 · JWT · node-cron · ExcelJS |
| 前端 | Vue 3.5 · TypeScript · Vite 6 · Vue Router 4 · Pinia · Axios |
| 皮肤 | wos-ui：零依赖 CSS 设计系统（`--hue` 单变量换肤，48 个内联线性图标） |
| 部署 | 单进程 Node 服务，静态资源零依赖托管，无 Redis / 无消息队列 |

## 快速开始

**环境要求**：Node.js ≥ 18、MySQL ≥ 8.0、npm ≥ 9

```bash
git clone https://gitee.com/dushu/wos-admin.git
cd wos-admin
```

### 1. 初始化数据库（二选一）

**方式 A：脚本初始化（推荐，会同时建库 + 建表 + 灌种子数据）**

```bash
cd server
cp .env.example .env        # 修改 DB_USER / DB_PASSWORD / JWT_SECRET
npm install
npm run init:db
```

**方式 B：直接导入现成 SQL**

```bash
mysql -uroot -p --default-character-set=utf8mb4 < server/sql/wos-admin.sql
```

> `server/sql/wos-admin.sql` 是完整快照（建库 + 17 张表 + 种子数据 + 真实 bcrypt 密码），导入即可用。
> 分版本文件：`V1__init_schema.sql`（结构）、`V2__seed_data.sql`（数据，密码为占位符，由 init-db.js 运行时替换）。

### 2. 启动后端（:8080）

```bash
cd server
npm run dev      # 开发模式（--watch 热重载）
# npm start      # 生产模式
```

### 3. 启动前端（:5173）

```bash
cd admin
npm install
npm run dev      # /api、/profile/ 已配置代理到 8080
# npm run build  # 类型检查 + 生产构建
```

打开 <http://localhost:5173> 即可登录。

## 默认账号

| 账号 | 密码 | 角色 | 用途 |
| --- | --- | --- | --- |
| `admin` | `admin123` | 超级管理员（`*:*:*`） | 全部功能 |
| `test` | `admin123` | 普通角色 | 验证数据范围与 403 拦截 |

> 首次部署后请立即在「个人中心」修改密码，并更换 `.env` 中的 `JWT_SECRET`。

## 项目结构

```
wos-admin/
├── server/                        # Koa2 后端
│   ├── sql/
│   │   ├── wos-admin.sql          # 一键导入（建库 + 建表 + 种子）
│   │   ├── V1__init_schema.sql    # 17 张表结构（sys_* 体系）
│   │   └── V2__seed_data.sql      # 种子数据（78 个菜单/权限、字典、参数、示例用户）
│   ├── scripts/
│   │   ├── init-db.js             # 建库建表灌种子
│   │   └── smoke.js               # 冒烟测试（60+ 断言，可重复执行）
│   ├── market/                    # 插件市场（示例插件 + 索引）
│   └── src/
│       ├── main.js                # 入口：装配中间件 → 挂模块 → 启动调度器
│       ├── app.js                 # Koa 应用（CORS / bodyparser / 静态 / 错误兜底）
│       ├── config/                # 环境配置（env-file 驱动）
│       ├── models/index.js        # Sequelize 模型注册 + 审计钩子
│       ├── common/                # 中间件 / 工具 / 统一响应 / 业务码
│       ├── framework/             # 数据范围、定时任务、Token 与权限服务
│       └── modules/
│           ├── system/            # auth user role menu dept post dict config appearance notice online market
│           └── monitor/           # operLog loginLog server job
├── admin/                         # Vue3 管理后台
│   ├── public/wos-ui/             # 皮肤资产（css + js，零依赖）
│   └── src/
│       ├── api/                   # 按模块封装（响应解包 + 请求门面）
│       ├── components/            # 契约组件（全局注册，页面免 import）
│       ├── composables/           # 下载、主题色初始化
│       ├── layouts/               # 应用外壳
│       ├── router/                # 静态路由 + 动态菜单路由 + 守卫
│       ├── stores/                # user / app
│       └── views/                 # 17 个页面
└── docs/                          # 开发文档
```

## 数据库

库名 `wos_admin`，字符集 `utf8mb4`，共 17 张表：

| 分类 | 表 |
| --- | --- |
| 组织权限 | `sys_user` `sys_role` `sys_menu` `sys_dept` `sys_post` |
| 关联表 | `sys_user_role` `sys_role_menu` `sys_role_dept` `sys_user_post` |
| 配置内容 | `sys_dict_type` `sys_dict_data` `sys_config` `sys_notice` |
| 监控日志 | `sys_oper_log` `sys_login_log` `sys_job` `sys_job_log` |

字段说明、ER 关系与索引设计见 [docs/database.md](./docs/database.md)。

## 配置项

后端通过 `server/.env` 读取配置（模板见 `server/.env.example`）：

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `PORT` | `8080` | 服务端口 |
| `DB_HOST` / `DB_PORT` | `127.0.0.1` / `3306` | MySQL 地址 |
| `DB_NAME` | `wos_admin` | 数据库名 |
| `DB_USER` / `DB_PASSWORD` | `root` / 空 | 数据库账号 |
| `JWT_SECRET` | 必填 | 至少 32 字节随机串，生产必须更换 |
| `JWT_EXPIRE_HOURS` | `24` | Token 有效期（小时） |
| `LOGIN_RETRY_COUNT` | `5` | 登录失败次数上限 |
| `LOGIN_LOCK_MINUTES` | `10` | 锁定时长（分钟） |
| `CONFIG_CACHE_TTL_MS` | `60000` | 参数缓存 TTL，开发可调小便于即时生效 |

## 生产部署

```bash
# 1. 构建前端
cd admin && npm ci && npm run build      # 产物 admin/dist

# 2. 后端以生产模式常驻（推荐 PM2 / systemd）
cd ../server && npm ci --omit=dev
NODE_ENV=production npm start
```

- 前端 `dist` 交给 Nginx 托管，`/api` 与 `/profile/` 反向代理到 `127.0.0.1:8080`。
- 生产务必设置 `NODE_ENV=production`、强随机 `JWT_SECRET`、独立数据库账号。
- Token 目前为内存态存储（单实例），多实例部署需改为 Redis 或粘性会话。
- 也可不分离部署：后端 `src/app.js` 已内置静态资源托管，可把 `dist` 内容交由后端直出。

## 权限模型

```
用户 ──< 用户角色 >── 角色 ──< 角色菜单 >── 菜单（M 目录 / C 菜单 / F 按钮）
  └── 部门 ──────────── 角色数据范围（1 全部 / 2 自定义 / 3 本部门 / 4 本部门及以下 / 5 仅本人）
```

- 登录返回权限码集合，前端用 `v-permission` / `<PermissionButton>` 控制按钮显隐；后端中间件二次校验，双保险。
- 列表查询经数据范围过滤器自动拼接部门条件，越权返回 403。
- 按钮权限码在「菜单管理」维护（类型 `F`），保存后无需重启，前端重新拉取即生效。

## 文档索引

| 文档 | 内容 |
| --- | --- |
| [AGENTS.md](./AGENTS.md) | AI 协作规范：工程约定、代码规范、禁止事项、标准工作流 |
| [PROJECT_MAP.md](./PROJECT_MAP.md) | 项目地图：模块 / API / 页面 / 数据表全量清单 |
| [DESIGN.md](./DESIGN.md) | 设计规范：wos-ui 皮肤、组件契约、布局与配色 |
| [docs/backend.md](./docs/backend.md) | 后端开发指南：模块结构、中间件、路由约定、响应格式 |
| [docs/frontend.md](./docs/frontend.md) | 前端开发指南：组件库、路由、API 层、页面规范 |
| [docs/database.md](./docs/database.md) | 数据库设计：表结构与关系 |
| [docs/market.md](./docs/market.md) | 插件市场：`plugin.json` 契约、开发与发布流程 |
| [docs/changelog.md](./docs/changelog.md) | 变更日志 |

## 常见问题

**Q：`npm run init:db` 报 `ER_ACCESS_DENIED_ERROR`？**
A：检查 `server/.env` 中的 `DB_USER` / `DB_PASSWORD`，并确认 MySQL 账号有建库权限。

**Q：登录提示验证码错误？**
A：验证码开关是参数 `sys.account.captchaEnabled`，在「参数设置」里关闭后登录免验证码（前端会自动隐藏输入框）。

**Q：接口 401 / 403 怎么排查？**
A：401 是 Token 失效（重启后端会清空内存态 Token，需重新登录）；403 是权限码缺失或超出数据范围，看「菜单管理」中对应按钮的权限字符。

**Q：改了菜单但前端路由没变？**
A：菜单在登录时拉取，退出重登或刷新页面即可；已登录会话不会自动热更新路由。

**Q：能换掉 wos-ui 用 Element Plus 吗？**
A：可以。契约组件（`ListPage` / `FormDialog` / `Wos*`）集中封装在 `admin/src/components/`，替换实现即可，页面层不用大改。

## 参与贡献

欢迎 Issue 与 PR。提交前请阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)，并确保：

```bash
cd admin && npm run build      # 类型检查必须通过
cd server && npm run smoke     # 冒烟测试必须全绿
```

## 许可证

[MIT](./LICENSE) © 2026 Wos

功能设计参考 [RuoYi-Vue](https://github.com/yangzongzhuan/RuoYi-Vue)（MIT），本项目为独立实现，未复用其源码。