# xn-admin-react-ts **Repository Path**: jenning/xn-admin-react-ts ## Basic Information - **Project Name**: xn-admin-react-ts - **Description**: xn-admin-react-ts 是「心念后台」的 React 管理端，基于 React 19、TypeScript 与 Ant Design，由基准前端 xn-admin-vue3-ts 移植而来，对接同一套微服务后端 xn-admin-cloud。业务能力与 Vue 端对齐（登录鉴权、动态菜单、RBAC、CRUD、主题布局、监控与文件任务等），视觉使用 Ant Design 原生风格。采用 - **Primary Language**: TypeScript - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 5 - **Forks**: 0 - **Created**: 2026-08-06 - **Last Updated**: 2026-09-06 ## Categories & Tags **Categories**: Uncategorized **Tags**: React, React19, TypeScript, Ant-Design, vite ## README

登录到工作台

# xn-admin-react-ts [简体中文](README.md) | [English](README.en.md) 心念后台管理系统前端：React 19 + TypeScript + Vite + Ant Design。 xn-admin-react-ts 是「心念后台」的 React 管理端，基于 React 19、TypeScript 与 Ant Design，由基准前端 xn-admin-vue3-ts 移植而来，对接同一套微服务后端 xn-admin-cloud。业务能力与 Vue 端对齐（登录鉴权、动态菜单、RBAC、CRUD、主题布局、智能对话、监控与文件任务等），视觉使用 Ant Design 原生风格。采用 Apache License 2.0 开源，**可商用、可自用**。 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE) [![开源](https://img.shields.io/badge/开源-免费-success.svg)](./LICENSE) [![商用](https://img.shields.io/badge/商用-允许-brightgreen.svg)](./LICENSE) [![自用](https://img.shields.io/badge/自用-允许-brightgreen.svg)](./LICENSE) 本仓库**独立开源**（Apache-2.0，**可商用、可自用**）。对接微服务后端独立仓库 **xn-admin-cloud**（经网关 `8088`），提供 JWT 登录、RBAC、动态路由/菜单、page-ui 驱动 CRUD、主题、通知与系统监控等能力。 本工程是基准前端 **xn-admin-vue3-ts** 的 React 技术栈移植。同步进度见 [`SYNC.md`](./SYNC.md)。 **视觉刻意与 Element Plus 端区分**：使用 Ant Design 原生主色（`#1677ff`）、浅色侧栏与白顶栏（主题可切换），不做「壳层仿 Element」。业务能力以基准为准。 版本：`1.1.0` · 许可证：[Apache-2.0](./LICENSE) · **可商用 / 可自用** · Copyright 2026 心念 **在线演示：** https://react.xinniankeji.vip · 官网：https://xinniankeji.vip ## 相关仓库 开源范围仅后端 + 四套管理端： | 仓库 | 在线 | Gitee | GitHub | 说明 | | ------------------- | --------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------- | --------------------------------- | | `xn-admin-cloud` | [官网](https://xinniankeji.vip) | [Gitee](https://gitee.com/jenning/xn-admin-cloud) | [GitHub](https://github.com/xinnian0310/xn-admin-cloud) | 微服务后端（必需） | | `xn-admin-vue3-ts` | [演示](https://vue3-ts.xinniankeji.vip) | [Gitee](https://gitee.com/jenning/xn-admin-vue3-ts) | [GitHub](https://github.com/xinnian0310/xn-admin-vue3-ts) | 功能基准（Vue 3 + TypeScript） | | `xn-admin-vue3-js` | [演示](https://vue3-js.xinniankeji.vip) | [Gitee](https://gitee.com/jenning/xn-admin-vue3-js) | [GitHub](https://github.com/xinnian0310/xn-admin-vue3-js) | Vue 3 + JavaScript（Composition） | | `xn-admin-vue2-js` | [演示](https://vue2.xinniankeji.vip) | [Gitee](https://gitee.com/jenning/xn-admin-vue2-js) | [GitHub](https://github.com/xinnian0310/xn-admin-vue2-js) | Vue 3 + JavaScript（Options API） | | `xn-admin-react-ts` | [演示](https://react.xinniankeji.vip) | [Gitee](https://gitee.com/jenning/xn-admin-react-ts) | [GitHub](https://github.com/xinnian0310/xn-admin-react-ts) | 本仓库 | ## 前提 1. Node.js 20+（建议 20 LTS） 2. 后端 **xn-admin-cloud** 已启动，网关可访问：http://127.0.0.1:8088 （按其仓库 README 三步启动：`docker compose up -d` → `scripts/run-dev`） 3. 中间件可由后端仓库 Docker Compose 拉起（也可本机自备 MySQL / Redis / Nacos / MinIO） ## 默认账号 与后端种子账号一致（首次初始化，**仅用于本地开发**）： | 用户名 | 初始密码 | 说明 | | ------------ | --------- | ---------- | | `SuperAdmin` | `xinnian` | 超级管理员 | | `admin` | `admin` | 管理员 | 登录后请尽快修改密码。详见 [SECURITY.md](./SECURITY.md)。 ## 快速启动 ```bash npm install # 安装依赖 npm run dev # 启动开发服务 ``` 开发地址：http://localhost:1800（与 vue2-js `1801` / vue3-js `1802` / vue3-ts `1803` 错开，便于同时联调） Vite 已代理到网关： | 前缀 | 目标 | | -------------- | ------------------------------------ | | `/api` | `http://localhost:8088` | | `/uploads` | `http://localhost:8088` | | `/ws` | `http://localhost:8088`（WebSocket） | | `/swagger-ui` | `http://localhost:8088` | | `/v3/api-docs` | `http://localhost:8088` | ```bash npm run build # tsc -b + vite 生产构建 npm run preview # 本地预览构建产物 npm run typecheck # TypeScript：仅做类型检查 npm run lint # oxlint：代码检查 npm run lint:fix # oxlint：自动修复可修复项 npm run format # Prettier：格式化代码 npm run format:check # Prettier：仅检查格式，不改文件 ``` 生产静态资源需由 Nginx 等反向代理到同一网关（`/api`、`/uploads`、`/ws`），或自行调整构建时的代理/网关地址。 ## 质量检查 ```bash npm run typecheck # TypeScript 类型检查 npm run lint # oxlint npm run format:check # Prettier 格式检查 npm run ci # 全量检查：typecheck + lint + format:check + build ``` 提交前会经 Husky 跑 lint-staged（oxlint 修复 + Prettier 格式化）；提交信息需符合 [Conventional Commits](https://www.conventionalcommits.org/)（如 `feat: xxx`）。约定详见 [CONTRIBUTING.md](CONTRIBUTING.md)。 在 Cursor / VS Code 中打开本仓库并安装推荐扩展后：**保存文件会自动 Prettier 格式化，并执行 oxlint 可自动修复项**（见 `.vscode/settings.json`）。 ## 技术栈 | 类别 | 技术 | | ------------- | ------------------------------------------------ | | 框架 | React 19、TypeScript 6、Vite 8 | | UI | Ant Design 6、@ant-design/icons、Iconify | | 状态 / 路由 | Zustand 5、React Router 7 | | 请求 | Axios | | 图表 / 编辑器 | ECharts、wangEditor | | Excel | ExcelJS、xlsx | | 工程化 | oxlint、Prettier、Husky、lint-staged、commitlint | ## 与基准差异 | 项 | 基准 Vue（xn-admin-vue3-ts） | 本工程 React | | --------------- | ---------------------------- | --------------------------------------------- | | UI | Element Plus | **Ant Design 原生视觉** | | 默认主色 / 侧栏 | `#409eff` 同色顶栏侧栏 | `#1677ff` + 浅色侧栏 + 白顶栏（可切换） | | 菜单图标字段 | `icon`（Element） | 优先 `iconAntd`，回退 `icon` | | 状态 | Pinia | Zustand | | 路由 | vue-router `addRoute` | 动态 `RouteObject` 挂载 | | 视图目录 | `src/views` | `src/pages` | | 权限 | `v-permission` | `` / `usePermission` | | `APP_CLIENT_ID` | `xn-admin-vue3-ts` | `xn-admin-react-ts`（`src/config/client.ts`） | | 开发端口 | `1803` | `1800` | ## 目录结构 ``` src/ ├── api/ # 接口模块（auth、user、role、route、notice、logs…） ├── components/ # 通用组件（Xn* / Auth / ThemePicker…） ├── config/ # 应用 / 客户端 / 主题等配置 ├── hooks/ # usePageUi、usePermission 等 ├── layouts/ # AdminLayout 及 Side / Top / Mix / Columns ├── pages/ # 业务页面（由 view-loader 懒加载） ├── router/ # 静态路由 + 动态注册与守卫 ├── stores/ # Zustand：user、permission、menu、tagsView、theme、notice ├── styles/ # 全局样式 ├── types/ # 类型定义 └── utils/ # request、icons、excel、download、view-loader… ``` ## 通用组件 每个组件目录下有独立文档，入口见 [`src/components/README.md`](./src/components/README.md)。 典型列表页组合： ``` XnPageLayout ├── aside → XnTreePanel（可选） ├── search → XnSearch ├── toolbar → XnButton + XnExport └── table → XnTable ``` `XnDialog` 是业务弹窗（默认取消 / 确定）；`XnModal` 是底层 Ant Design Modal 封装（拖拽、限高）。业务页优先用 `XnDialog`。配置通常来自后端 page-ui 与 `` / `usePermission`。 | 组件 | 说明 | 文档 | | ----------------- | -------------------------------------- | ------------------------------------------------------ | | XnAppIcon | 统一图标（Ant Design / Iconify / SVG） | [README](./src/components/XnAppIcon/README.md) | | XnAppBrandLogo | 品牌 Logo | [README](./src/components/XnAppBrandLogo/README.md) | | XnAuth | 按钮级权限（对应 Vue `v-permission`） | [README](./src/components/XnAuth/README.md) | | XnAvatarCrop | 头像裁剪上传 | [README](./src/components/XnAvatarCrop/README.md) | | XnButton | 工具栏 / 行操作按钮 | [README](./src/components/XnButton/README.md) | | XnCaptcha | 图形 / 滑块验证码 | [README](./src/components/XnCaptcha/README.md) | | XnCode | JSON / 代码查看（行号、复制、着色） | [README](./src/components/XnCode/README.md) | | XnCopy | 一键复制按钮 | [README](./src/components/XnCopy/README.md) | | XnCron | Quartz Cron 编辑器 | [README](./src/components/XnCron/README.md) | | XnDesc | 详情描述列表 | [README](./src/components/XnDesc/README.md) | | XnDialog | 业务弹窗壳（内部用 `XnModal`） | [README](./src/components/XnDialog/README.md) | | XnDictSelect | 字典下拉 | [README](./src/components/XnDictSelect/README.md) | | XnEmpty | 无数据 / 无权限等空状态 | [README](./src/components/XnEmpty/README.md) | | XnErrorPage | 403 / 404 / 503 错误页 | [README](./src/components/XnErrorPage/README.md) | | XnExport | 导出按钮 | [README](./src/components/XnExport/README.md) | | XnFilePicker | 从已上传文件中选择 | [README](./src/components/XnFilePicker/README.md) | | XnIconPicker | 图标选择器 | [README](./src/components/XnIconPicker/README.md) | | XnImport | Excel 导入对话框 | [README](./src/components/XnImport/README.md) | | XnImageUpload | 图片上传（单张 / 多张 + 预览） | [README](./src/components/XnImageUpload/README.md) | | XnLongText | 长文本截断 + 弹窗查看 | [README](./src/components/XnLongText/README.md) | | XnModal | 可拖拽、限高的 Ant Design Modal | [README](./src/components/XnModal/README.md) | | XnNoticeInbox | 消息中心抽屉 | [README](./src/components/XnNoticeInbox/README.md) | | XnOrgSelect | 单位 / 用户 / 角色 / 岗位 | [README](./src/components/XnOrgSelect/README.md) | | XnPageLayout | 列表页骨架 | [README](./src/components/XnPageLayout/README.md) | | XnPopconfirm | 行内确认气泡 | [README](./src/components/XnPopconfirm/README.md) | | XnRegion | 省市区级联 | [README](./src/components/XnRegion/README.md) | | XnRichEditor | 富文本（wangEditor） | [README](./src/components/XnRichEditor/README.md) | | XnSearch | 配置化搜索表单 | [README](./src/components/XnSearch/README.md) | | XnSidebarMenu | 多级菜单 | [README](./src/components/XnSidebarMenu/README.md) | | XnSmsCode | 短信验证码倒计时 | [README](./src/components/XnSmsCode/README.md) | | XnTable | 配置化表格 | [README](./src/components/XnTable/README.md) | | XnTagsView | 页面标签栏 | [README](./src/components/XnTagsView/README.md) | | XnThemePicker | 主题设置 | [README](./src/components/XnThemePicker/README.md) | | XnTreePanel | 左侧树面板 | [README](./src/components/XnTreePanel/README.md) | | XnUiPreferenceFab | 个人界面偏好 FAB | [README](./src/components/XnUiPreferenceFab/README.md) | | XnUpload | 大文件分片上传 | [README](./src/components/XnUpload/README.md) | | XnWatermark | 页面水印 | [README](./src/components/XnWatermark/README.md) | ## 界面预览 截图目录 [`docs/images/`](./docs/images/)，命名与基准仓库 **xn-admin-vue3-ts** 对齐（如 `login.png`、`users.png`），均为本工程 Ant Design 界面实拍。 ### 登录与首页 | 模块 | 截图 | | ------ | ------------------------------------ | | 登录页 | ![登录页](./docs/images/login.png) | | 首页 | ![首页](./docs/images/dashboard.png) | ### 智能对话 | 模块 | 截图 | | -------- | ------------------------------------------- | | 智能对话 | ![智能对话](./docs/images/ai-chat.png) | | 厂商目录 | ![厂商目录](./docs/images/ai-providers.png) | | 我的模型 | ![我的模型](./docs/images/ai-models.png) | | 配额管理 | ![配额管理](./docs/images/ai-quota.png) | ### 个人中心 | 模块 | 截图 | | -------- | -------------------------------------------- | | 个人信息 | ![个人信息](./docs/images/profile.png) | | 我的消息 | ![我的消息](./docs/images/messages-mine.png) | ### 系统监控 | 模块 | 截图 | | -------- | --------------------------------------------- | | 在线用户 | ![在线用户](./docs/images/monitor-online.png) | | 服务监控 | ![服务监控](./docs/images/monitor-server.png) | | 缓存监控 | ![缓存监控](./docs/images/monitor-redis.png) | | SQL 监控 | ![SQL 监控](./docs/images/monitor-sql.png) | ### 日志管理 | 模块 | 截图 | | -------- | --------------------------------------------- | | 登录日志 | ![登录日志](./docs/images/logs-login.png) | | 操作日志 | ![操作日志](./docs/images/logs-oper.png) | | 异常日志 | ![异常日志](./docs/images/logs-exception.png) | | 任务日志 | ![任务日志](./docs/images/jobs-log.png) | ### 组织与账号 | 模块 | 截图 | | -------- | ------------------------------------ | | 用户管理 | ![用户管理](./docs/images/users.png) | | 单位管理 | ![单位管理](./docs/images/units.png) | | 岗位管理 | ![岗位管理](./docs/images/posts.png) | ### 权限与安全 | 模块 | 截图 | | -------- | -------------------------------------------------- | | 角色列表 | ![角色列表](./docs/images/roles.png) | | 角色权限 | ![角色权限](./docs/images/permissions.png) | | 权限内容 | ![权限内容](./docs/images/permissions-content.png) | | 路由管理 | ![路由管理](./docs/images/routes.png) | | 安全策略 | ![安全策略](./docs/images/security.png) | ### 内容运营 | 模块 | 截图 | | ---------- | --------------------------------------------- | | 公告管理 | ![公告管理](./docs/images/notices.png) | | 站内信 | ![站内信](./docs/images/messages.png) | | 联系与捐赠 | ![联系与捐赠](./docs/images/site-contact.png) | ### 基础数据与系统设置 | 模块 | 截图 | | ---------- | ----------------------------------------------- | | 字典管理 | ![字典管理](./docs/images/dicts.png) | | 登录页设置 | ![登录页设置](./docs/images/login-settings.png) | | 系统配置 | ![系统配置](./docs/images/config.png) | | 远程连接 | ![远程连接](./docs/images/remote-storage.png) | ### 系统工具 | 模块 | 截图 | | -------- | --------------------------------------- | | 文件管理 | ![文件管理](./docs/images/files.png) | | 定时任务 | ![定时任务](./docs/images/jobs.png) | | 接口文档 | ![接口文档](./docs/images/api-docs.png) | | 代码生成 | ![代码生成](./docs/images/codegen.png) | | 回收站 | ![回收站](./docs/images/recycle.png) | ## 功能概览 - JWT 登录与会话刷新；`` / `usePermission` 按钮级权限 - 动态菜单 / 路由注册（后端路由 + `pages` 懒加载） - 角色、权限、用户、单位、岗位、字典、公告、站内信、登录页配置、系统配置、安全策略、远程连接、联系与捐赠 - 页面标签栏、多布局模式、主题（含自定义色与背景） - 通用系统配置 + 登录用户个人布局/字号（右下角悬浮入口） - 表格列个性化、Excel 导入导出 - 通用组件：验证码、短信码、字典/组织/省市区、图片上传、文件选择、水印、Cron、`XnDialog` / `XnModal` 等（见 [`src/components/README.md`](./src/components/README.md)） - 系统监控：在线用户 / 服务 / Redis / SQL - 文件管理、定时任务、回收站、代码生成、接口文档页（Swagger UI / API 切换） - 智能对话：厂商目录、我的模型、流式会话、试用配额 - 公告 WebSocket 推送（`/ws`） - 日志管理：登录 / 操作 / 异常 / 任务日志（查询、详情、删除、清空、导出） ## 环境与约定 - 路径别名：`@` → `src/` - `APP_CLIENT_ID = xn-admin-react-ts`（`src/config/client.ts`），公开系统配置按 client 隔离品牌文案 - 鉴权 Token 由 `utils/request` 注入；未登录跳转登录页 - 列表页模式：`XnPageLayout` → `XnSearch` → `XnButton` → `XnTable`（+ 可选 `XnTreePanel`） - 动态菜单页面对应 `src/pages/**/index.tsx`（由 view-loader 懒加载） - 详细同步与缺口说明见 [`SYNC.md`](./SYNC.md) ## 生产部署（摘要） - `npm run build` 产出静态资源，由 Nginx 等托管 - 将 `/api`、`/uploads`、`/ws` 反向代理到后端网关（默认 `127.0.0.1:8088`） - 安全见 [SECURITY.md](./SECURITY.md)；贡献见 [CONTRIBUTING.md](./CONTRIBUTING.md) ## 支持捐赠 如果这个项目对你有帮助，欢迎请作者喝杯咖啡 ☕

支持捐赠（微信支付 / 支付宝）

## 开源与许可证 本项目采用 [Apache License 2.0](./LICENSE) **免费开源**，**允许个人自用与商业使用**，无需单独购买授权。 | 用途 | 是否允许 | | ---------------------- | ------------------------- | | 个人学习、自用部署 | 允许 | | 二次开发、修改源码 | 允许 | | 商业项目使用、对外交付 | 允许 | | 闭源商用 | 允许（须遵守 Apache-2.0） | | 再分发源码或编译产物 | 允许 | 使用、修改或分发时请：保留版权声明、本许可证文本及 NOTICE（如有）；对修改过的文件注明变更。软件按「现状」提供，不附带任何明示或默示担保。完整条款见 [LICENSE](./LICENSE)。 捐赠为自愿支持，不构成商业授权或付费售后。