文件上传

概述

FastapiAdmin 采用统一上传架构，所有文件上传都通过单一接口实现，支持不同类型文件的分类存储。

上传类型

类型	路径参数	存储目录	用途
`file`	`upload_type=file`	`upload/file/YYYY/MM/DD/`	通用文件上传（默认）
`avatar`	`upload_type=avatar`	`upload/avatar/YYYY/MM/DD/`	用户头像上传
`param`	`upload_type=param`	`upload/param/YYYY/MM/DD/`	参数配置文件上传
`resource`	`upload_type=resource`	`upload/resource/[target_path]/YYYY/MM/DD/`	监控资源文件，支持指定目录

统一上传接口

接口地址: /api/v1/common/file/upload

请求方式: POST

Content-Type: multipart/form-data

权限要求: module_common:file:upload

请求参数:

参数	类型	位置	必填	说明
`file`	`UploadFile`	Body	是	上传的文件
`upload_type`	`string`	Query	否	上传类型，默认 `file`
`target_path`	`string`	Form	否	目标目录路径，仅 `resource` 类型支持

响应示例:

json

{
  "code": 0,
  "msg": "上传文件成功",
  "data": {
    "file_path": "/app/uploads/resource/images/2024/01/15/abc123.png",
    "file_name": "abc123.png",
    "origin_name": "original-file.png",
    "file_url": "http://localhost:8000/app/uploads/resource/images/2024/01/15/abc123.png"
  }
}

资源上传接口

接口地址: /api/v1/monitor/resource/upload

请求方式: POST

Content-Type: multipart/form-data

权限要求: module_monitor:resource:upload

请求参数:

参数	类型	位置	必填	说明
`file`	`UploadFile`	Body	是	上传的文件
`target_path`	`string`	Form	否	目标目录路径

说明: 此接口是统一上传接口的快捷方式，内部调用统一上传接口，使用 resource 类型。

前端调用示例

通用文件上传

typescript

import { request } from "@utils";

async function uploadFile(file: File) {
  const formData = new FormData();
  formData.append("file", file);

  const response = await request<ApiResponse<UploadFilePath>>({
    url: "/common/file/upload",
    method: "post",
    data: formData,
    headers: { "Content-Type": "multipart/form-data" },
  });

  return response.data.data;
}

头像上传

typescript

import { UserAPI } from "@api/module_system/user";

async function uploadAvatar(file: File) {
  const formData = new FormData();
  formData.append("file", file);

  const response = await UserAPI.uploadCurrentUserAvatar(formData);
  return response.data.data;
}

参数配置上传

typescript

import { uploadFile } from "@api/module_system/params";

async function uploadParamConfig(file: File) {
  const formData = new FormData();
  formData.append("file", file);

  const response = await uploadFile(formData);
  return response.data.data;
}

资源文件上传（指定目录）

typescript

import { ResourceAPI } from "@api/module_monitor/resource";

async function uploadResource(file: File, targetPath: string) {
  const formData = new FormData();
  formData.append("file", file);
  formData.append("target_path", targetPath);

  const response = await ResourceAPI.uploadFile(formData);
  return response.data.data;
}

// 使用示例：上传到 images 目录
await uploadResource(file, "images");

// 使用示例：上传到 nested/path 目录
await uploadResource(file, "nested/path");

安全特性

文件名清理: 自动清理文件名中的危险字符
路径穿越防护: 检测并阻止 ../ 等路径穿越攻击
文件类型验证: 基于 MIME 类型和扩展名的双重验证
文件大小限制: 可配置的单个文件大小限制
内容检测: 通过文件头字节验证文件真实性

目录结构

upload/
├── file/           # 通用文件
│   └── YYYY/MM/DD/
├── avatar/         # 头像
│   └── YYYY/MM/DD/
├── param/          # 参数配置
│   └── YYYY/MM/DD/
└── resource/       # 监控资源
    ├── images/
    ├── documents/
    └── YYYY/MM/DD/

资源管理

概述

资源管理模块提供对 upload/resource 目录的完整管理能力，包括文件浏览、上传、下载、删除、移动、复制、重命名和目录创建等功能。

功能列表

功能	方法	接口	说明
目录浏览	`listResource`	`GET /api/v1/monitor/resource/list`	浏览指定目录
文件上传	`uploadFile`	`POST /api/v1/monitor/resource/upload`	上传到指定目录
文件下载	`downloadFile`	`GET /api/v1/monitor/resource/download`	下载文件
删除资源	`deleteResource`	`DELETE /api/v1/monitor/resource/delete`	删除文件或目录
移动资源	`moveResource`	`POST /api/v1/monitor/resource/move`	移动文件或目录
复制资源	`copyResource`	`POST /api/v1/monitor/resource/copy`	复制文件或目录
重命名资源	`renameResource`	`POST /api/v1/monitor/resource/rename`	重命名文件或目录
创建目录	`createDirectory`	`POST /api/v1/monitor/resource/create-dir`	创建新目录
导出列表	`exportResource`	`POST /api/v1/monitor/resource/export`	导出资源列表

目录浏览

接口: GET /api/v1/monitor/resource/list

权限: module_monitor:resource:list

查询参数:

参数	类型	必填	说明
`path`	`string`	否	目录路径，默认根目录
`include_hidden`	`boolean`	否	是否包含隐藏文件，默认 `false`
`page_no`	`integer`	否	页码，默认 1
`page_size`	`integer`	否	每页数量，默认 20

响应示例:

json

{
  "code": 0,
  "msg": "获取目录列表成功",
  "data": {
    "path": "/upload/resource",
    "name": "resource",
    "items": [
      {
        "name": "images",
        "is_file": false,
        "is_dir": true,
        "size": null,
        "created_time": "2024-01-15T10:30:00",
        "modified_time": "2024-01-15T10:30:00",
        "is_hidden": false
      },
      {
        "name": "logo.svg",
        "is_file": true,
        "is_dir": false,
        "size": 12345,
        "created_time": "2024-01-15T10:30:00",
        "modified_time": "2024-01-15T10:30:00",
        "is_hidden": false,
        "file_url": "http://localhost:8000/app/uploads/resource/logo.svg"
      }
    ],
    "total_files": 10,
    "total_dirs": 5,
    "total_size": 1024000
  }
}

删除资源

接口: DELETE /api/v1/monitor/resource/delete

权限: module_monitor:resource:delete

请求体: string[] - 文件路径数组

示例:

json

["upload/resource/images/logo.svg", "upload/resource/documents"]

移动资源

接口: POST /api/v1/monitor/resource/move

权限: module_monitor:resource:move

请求体:

json

{
  "source_path": "upload/resource/images/logo.svg",
  "target_path": "upload/resource/backup/logo.svg",
  "overwrite": false
}

复制资源

接口: POST /api/v1/monitor/resource/copy

权限: module_monitor:resource:copy

请求体:

json

{
  "source_path": "upload/resource/images/logo.svg",
  "target_path": "upload/resource/images/logo_copy.svg",
  "overwrite": false
}

重命名资源

接口: POST /api/v1/monitor/resource/rename

权限: module_monitor:resource:rename

请求体:

json

{
  "old_path": "upload/resource/images/logo.svg",
  "new_name": "logo_new.png"
}

创建目录

接口: POST /api/v1/monitor/resource/create-dir

权限: module_monitor:resource:create-dir

请求体:

json

{
  "parent_path": "upload/resource/images",
  "dir_name": "screenshots"
}

健康检查

概述

健康检查端点提供应用状态的实时监控，支持三级健康检查。

检查类型

类型	接口	用途	依赖
基础检查	`GET /health`	负载均衡器探活	无
就绪检查	`GET /health/ready`	K8s readinessProbe	数据库、Redis
存活检查	`GET /health/live`	K8s livenessProbe	无

基础健康检查

接口: GET /api/v1/common/health

权限: 无

响应示例:

json

{
  "code": 0,
  "msg": "健康",
  "data": {
    "status": "ok",
    "timestamp": "2024-01-15T10:30:00",
    "version": "1.0.0"
  }
}

就绪检查

接口: GET /api/v1/common/health/ready

权限: 无

说明: 检查所有依赖（数据库、Redis）是否就绪，用于判断应用是否可以接收流量。

响应示例:

json

{
  "code": 0,
  "msg": "依赖就绪",
  "data": {
    "status": "ready",
    "timestamp": "2024-01-15T10:30:00",
    "version": "1.0.0",
    "uptime_seconds": 3600.5,
    "dependencies": {
      "database": {
        "status": "up",
        "latency_ms": 5.23
      },
      "redis": {
        "status": "up",
        "latency_ms": 1.12
      }
    },
    "disk_usage": {
      "total": 500000000000,
      "used": 250000000000,
      "free": 250000000000,
      "percent": 50.0
    }
  }
}

失败响应 (HTTP 503):

json

{
  "code": 503,
  "msg": "依赖未就绪",
  "data": {
    "status": "not_ready",
    "timestamp": "2024-01-15T10:30:00",
    "version": "1.0.0",
    "uptime_seconds": 3600.5,
    "dependencies": {
      "database": {
        "status": "down",
        "latency_ms": null
      },
      "redis": {
        "status": "up",
        "latency_ms": 1.12
      }
    },
    "disk_usage": {
      "total": 500000000000,
      "used": 250000000000,
      "free": 250000000000,
      "percent": 50.0
    }
  }
}

存活检查

接口: GET /api/v1/common/health/live

权限: 无

响应示例:

json

{
  "code": 0,
  "msg": "存活",
  "data": {
    "status": "alive",
    "timestamp": "2024-01-15T10:30:00",
    "uptime_seconds": 3600.5
  }
}

监控指标

概述

FastapiAdmin 集成了 Prometheus 指标采集，通过 /metrics 端点暴露 HTTP 请求指标。

指标端点

接口: GET /api/v1/common/metrics

格式: Prometheus text format

可用指标

指标名称	类型	说明
`http_requests_total`	Counter	HTTP 请求总数
`http_request_duration_seconds`	Histogram	HTTP 请求延迟（秒）
`http_request_size_bytes`	Histogram	HTTP 请求大小（字节）
`http_response_size_bytes`	Histogram	HTTP 响应大小（字节）
`http_requests_in_progress`	Gauge	正在处理的 HTTP 请求数

配置说明

指标采集已在 app/scripts/init_app.py 中自动配置，无需手动启用。

默认排除的端点:

/metrics - 指标端点本身
/health - 健康检查
/health/live - 存活检查
/health/ready - 就绪检查
/docs - API 文档
/redoc - 文档
/openapi.json - OpenAPI 规范
/static/* - 静态资源
/favicon.ico - 网站图标

Grafana 配置示例

yaml

# Prometheus 数据源配置
apiVersion: 1
datasources:
  - name: Prometheus
    type: prometheus
    url: http://prometheus:9090
    access: proxy

# HTTP 请求速率面板
- title: HTTP Request Rate
  type: graph
  targets:
    - expr: rate(http_requests_total[5m])
      legendFormat: "{{handler}} - {{method}}"

# 请求延迟面板
- title: HTTP Request Latency
  type: graph
  targets:
    - expr: histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))
      legendFormat: "p95 - {{handler}}"

最佳实践

1. 文件上传

✅ 使用统一上传接口处理所有文件上传
✅ 上传前在客户端验证文件类型和大小
✅ 使用 target_path 参数组织文件结构
✅ 文件名避免使用特殊字符和中文

2. 资源管理

✅ 定期清理不再使用的文件
✅ 使用目录结构组织不同类型的资源
✅ 删除前确认文件没有被其他资源引用

3. 监控运维

✅ 配置 K8s 探针使用 /health/ready 和 /health/live
✅ 使用 Prometheus 采集 /metrics 数据
✅ 设置合理的告警阈值

认证系统

概述

FastapiAdmin 提供完整的用户认证系统，包括用户登录、Token 管理、验证码、租户切换等功能。

登录流程

获取验证码 (可选): 调用 /captcha 获取验证码图片
用户登录: 调用 /login 提交用户名、密码和验证码
获取租户列表: 登录成功后返回用户关联的租户列表
选择租户: 调用 /select-tenant 选择工作租户
获取用户信息: 调用 /current/info 获取当前用户详情

核心接口

功能	方法	接口	说明
获取验证码	`getCaptcha`	`GET /api/v1/system/auth/captcha`	获取验证码图片
用户登录	`login`	`POST /api/v1/system/auth/login`	用户认证
退出登录	`logout`	`POST /api/v1/system/auth/logout`	清除Token
刷新Token	`refresh`	`POST /api/v1/system/auth/refresh`	刷新访问令牌
获取租户列表	`getTenants`	`GET /api/v1/system/auth/tenants`	获取用户关联的租户
选择租户	`selectTenant`	`POST /api/v1/system/auth/select-tenant`	切换租户上下文
获取用户信息	`getCurrentUserInfo`	`GET /api/v1/system/user/current/info`	获取当前用户详情

前端调用示例

typescript

import { AuthAPI } from "@api/module_system/auth";
import { UserAPI } from "@api/module_system/user";

// 1. 获取验证码
async function getCaptcha() {
  const response = await AuthAPI.getCaptcha();
  return response.data.data;
}

// 2. 用户登录
async function login(username: string, password: string, captchaKey: string, captcha: string) {
  const response = await AuthAPI.login({
    username,
    password,
    captcha_key: captchaKey,
    captcha: captcha,
    login_type: "password",
  });
  return response.data.data;
}

// 3. 选择租户
async function selectTenant(tenantId: number) {
  const response = await AuthAPI.selectTenant({ tenant_id: tenantId });
  return response.data.data;
}

// 4. 获取用户信息
async function getUserInfo() {
  const response = await UserAPI.getCurrentUserInfo();
  return response.data.data;
}

Token 管理

访问令牌: 有效期由 ACCESS_TOKEN_EXPIRE_MINUTES 配置，用于API认证
刷新令牌: 有效期更长，用于刷新访问令牌
会话ID: 唯一标识用户会话，存储在Redis中

插件市场

概述

FastapiAdmin 提供插件市场功能，支持插件的安装、卸载、启用/禁用等操作。

核心接口

功能	方法	接口	权限	说明
插件市场列表	`marketplace`	`GET /api/v1/system/plugin/marketplace`	租户用户	获取可用插件
我的插件	`myPlugins`	`GET /api/v1/system/plugin/my`	租户用户	获取已安装插件
安装插件	`install`	`POST /api/v1/system/plugin/install`	租户用户	安装插件
卸载插件	`uninstall`	`POST /api/v1/system/plugin/uninstall`	租户用户	卸载插件
切换状态	`toggle`	`POST /api/v1/system/plugin/toggle`	租户用户	启用/禁用插件

插件状态说明

状态码	插件市场含义	我的插件含义
`0`	插件可用	已启用
`1`	插件不可用	已禁用

前端调用示例

typescript

import PluginAPI, { type PluginTable } from "@api/module_application/plugin";

// 获取插件市场列表
async function getMarketplace(category?: string) {
  const response = await PluginAPI.marketplace(
    { page_no: 1, page_size: 10 },
    category
  );
  return response.data.data;
}

// 安装插件
async function installPlugin(pluginId: number) {
  await PluginAPI.install(pluginId);
}

// 切换插件状态
async function togglePlugin(pluginId: number) {
  await PluginAPI.toggle(pluginId);
}

定时任务

概述

FastapiAdmin 提供基于 APScheduler 的定时任务管理功能，支持任务的创建、修改、删除、暂停、恢复和立即执行。

核心接口

功能	方法	接口	说明
获取调度器状态	`getSchedulerStatus`	`GET /api/v1/task/cronjob/job/scheduler/status`	获取调度器运行状态
获取任务列表	`getSchedulerJobs`	`GET /api/v1/task/cronjob/job/scheduler/jobs`	获取所有任务
启动调度器	`startScheduler`	`POST /api/v1/task/cronjob/job/scheduler/start`	启动调度器
暂停调度器	`pauseScheduler`	`POST /api/v1/task/cronjob/job/scheduler/pause`	暂停调度器
恢复调度器	`resumeScheduler`	`POST /api/v1/task/cronjob/job/scheduler/resume`	恢复调度器
关闭调度器	`shutdownScheduler`	`POST /api/v1/task/cronjob/job/scheduler/shutdown`	关闭调度器
暂停任务	`pauseJob`	`POST /api/v1/task/cronjob/job/task/pause/{jobId}`	暂停指定任务
恢复任务	`resumeJob`	`POST /api/v1/task/cronjob/job/task/resume/{jobId}`	恢复指定任务
立即执行	`runJobNow`	`POST /api/v1/task/cronjob/job/task/run/{jobId}`	立即执行任务
删除任务	`removeJob`	`DELETE /api/v1/task/cronjob/job/task/remove/{jobId}`	删除任务
获取日志	`getJobLogList`	`GET /api/v1/task/cronjob/job/log/list`	获取任务执行日志
同步任务	`syncJobsToDb`	`POST /api/v1/task/cronjob/job/scheduler/sync`	同步任务到数据库

调度器状态

typescript

interface SchedulerStatus {
  status: string;        // running, paused, shutdown
  is_running: boolean;   // 是否运行中
  job_count: number;     // 任务数量
}

前端调用示例

typescript

import JobAPI from "@api/module_task/cronjob/job";

// 获取调度器状态
async function getStatus() {
  const response = await JobAPI.getSchedulerStatus();
  return response.data.data;
}

// 启动调度器
async function startScheduler() {
  await JobAPI.startScheduler();
}

// 暂停任务
async function pauseTask(jobId: string) {
  await JobAPI.pauseJob(jobId);
}

// 立即执行任务
async function runNow(jobId: string) {
  await JobAPI.runJobNow(jobId);
}

AI 对话

概述

FastapiAdmin 集成 AI 对话功能，支持创建会话、发送消息、获取历史记录等操作。

核心接口

功能	方法	接口	说明
会话列表	`getSessionList`	`GET /api/v1/ai/chat/list`	获取会话分页列表
创建会话	`createSession`	`POST /api/v1/ai/chat/create`	创建新会话
更新会话	`updateSession`	`PUT /api/v1/ai/chat/update/{id}`	更新会话标题
删除会话	`deleteSession`	`DELETE /api/v1/ai/chat/delete`	删除会话
AI对话	`chat`	`POST /api/v1/ai/chat/ai-chat`	发送消息获取AI回复
会话详情	`getSessionDetail`	`GET /api/v1/ai/chat/detail/{sessionId}`	获取会话详情和消息

数据结构

typescript

interface ChatSession {
  session_id: string;
  id: string;
  title: string | null;
  agent_id: string | null;
  team_id: string | null;
  workflow_id: string | null;
  created_time: string | null;
  updated_time: string | null;
  message_count: number;
  messages: ChatSessionMessage[];
}

interface ChatSessionMessage {
  id: string;
  role: string;        // user, assistant
  content: string;
  created_at: number | null;
}

interface AiChatResponse {
  response: string;    // AI回复内容
  session_id: string;  // 会话ID
  function_calls: Array<{
    name: string;
    arguments: Record<string, any>;
  }> | null;           // 函数调用（可选）
}

前端调用示例

typescript

import AiChatAPI from "@api/module_ai/chat";

// 创建会话
async function createChat(title: string) {
  const response = await AiChatAPI.createSession({ title });
  return response.data.data;
}

// 发送消息
async function sendMessage(message: string, sessionId?: string) {
  const response = await AiChatAPI.chat({
    message,
    session_id: sessionId ?? null,
  });
  return response.data.data;
}

// 获取会话详情
async function getChatDetail(sessionId: string) {
  const response = await AiChatAPI.getSessionDetail(sessionId);
  return response.data.data;
}

用户管理

概述

用户管理模块提供完整的用户生命周期管理功能，包括用户的创建、查询、更新、删除、密码管理、导入导出等操作。

核心接口

功能	方法	接口	权限
获取当前用户信息	`getCurrentUserInfo`	`GET /api/v1/system/user/current/info`	登录用户
更新当前用户信息	`updateCurrentUserInfo`	`PUT /api/v1/system/user/current/info/update`	登录用户
修改密码	`changeCurrentUserPassword`	`PUT /api/v1/system/user/current/password/change`	登录用户
重置密码	`resetUserPassword`	`PUT /api/v1/system/user/reset/password`	`module_system:user:update`
用户注册	`registerUser`	`POST /api/v1/system/user/register`	公开
忘记密码	`forgetPassword`	`POST /api/v1/system/user/forget/password`	公开
查询用户列表	`listUser`	`GET /api/v1/system/user/list`	`module_system:user:query`
查询用户详情	`detailUser`	`GET /api/v1/system/user/detail/{id}`	`module_system:user:detail`
创建用户	`createUser`	`POST /api/v1/system/user/create`	`module_system:user:create`
更新用户	`updateUser`	`PUT /api/v1/system/user/update/{id}`	`module_system:user:update`
删除用户	`deleteUser`	`DELETE /api/v1/system/user/delete`	`module_system:user:delete`
批量设置状态	`batchUser`	`PATCH /api/v1/system/user/available/setting`	`module_system:user:patch`
导出用户	`exportUser`	`POST /api/v1/system/user/export`	`module_system:user:export`
下载导入模板	`downloadTemplateUser`	`POST /api/v1/system/user/import/template`	`module_system:user:download`
导入用户	`importUser`	`POST /api/v1/system/user/import/data`	`module_system:user:import`

关键业务逻辑

用户创建流程

验证用户名不能为空
检查是否试图创建超级管理员（不允许）
检查用户名是否已存在
检查部门是否存在（如果指定了部门）
密码加密存储
关联角色和岗位

权限控制

超级管理员不能被创建、修改、删除
不能删除当前登录用户
启用状态的用户不能被删除

前端调用示例

typescript

// 获取用户列表
const users = await UserAPI.listUser({ page_no: 1, page_size: 10 });

// 创建用户
await UserAPI.createUser({
  username: 'user001',
  name: '张三',
  dept_id: 1,
  role_ids: [1, 2],
  position_ids: [1],
  password: 'password123',
  gender: 1,
  email: 'zhangsan@example.com',
  mobile: '13800138000'
});

// 修改密码
await UserAPI.changeCurrentUserPassword({
  old_password: 'oldpass',
  new_password: 'newpass',
  confirm_password: 'newpass'
});

角色管理

概述

角色管理模块提供角色的创建、查询、更新、删除以及权限分配功能，支持数据权限范围设置。

核心接口

功能	方法	接口	权限
查询角色列表	`listRole`	`GET /api/v1/system/role/list`	`module_system:role:query`
查询角色详情	`detailRole`	`GET /api/v1/system/role/detail/{id}`	`module_system:role:detail`
创建角色	`createRole`	`POST /api/v1/system/role/create`	`module_system:role:create`
更新角色	`updateRole`	`PUT /api/v1/system/role/update/{id}`	`module_system:role:update`
删除角色	`deleteRole`	`DELETE /api/v1/system/role/delete`	`module_system:role:delete`
批量设置状态	`batchRole`	`PATCH /api/v1/system/role/available/setting`	`module_system:role:patch`
角色授权	`setRolePermission`	`PATCH /api/v1/system/role/permission/setting`	`module_system:role:permission`
导出角色	`exportRole`	`POST /api/v1/system/role/export`	`module_system:role:export`

数据权限范围

范围值	说明
1	仅本人数据权限
2	本部门数据权限
3	本部门及以下数据权限
4	全部数据权限
5	自定义数据权限

前端调用示例

typescript

// 获取角色列表
const roles = await RoleAPI.listRole({ page_no: 1, page_size: 10 });

// 角色授权
await RoleAPI.setRolePermission({
  role_ids: [1],
  menu_ids: [1, 2, 3],
  data_scope: 4,
  dept_ids: []
});

部门管理

概述

部门管理模块提供部门的树形结构管理功能，支持部门的创建、查询、更新、删除和状态管理。

核心接口

功能	方法	接口	权限
查询部门树	`getDeptTree`	`GET /api/v1/system/dept/tree`	`module_system:dept:query`
查询部门详情	`detailDept`	`GET /api/v1/system/dept/detail/{id}`	`module_system:dept:detail`
创建部门	`createDept`	`POST /api/v1/system/dept/create`	`module_system:dept:create`
更新部门	`updateDept`	`PUT /api/v1/system/dept/update/{id}`	`module_system:dept:update`
删除部门	`deleteDept`	`DELETE /api/v1/system/dept/delete`	`module_system:dept:delete`
批量设置状态	`batchDept`	`PATCH /api/v1/system/dept/available/setting`	`module_system:dept:patch`

关键业务逻辑

部门删除

删除部门时会递归删除所有子部门
确保数据完整性

状态联动

启用部门时，会级联启用所有上级部门
停用部门时，会级联停用所有子部门

前端调用示例

typescript

// 获取部门树
const deptTree = await DeptAPI.getDeptTree({});

// 创建部门
await DeptAPI.createDept({
  name: '技术部',
  code: 'tech',
  parent_id: 0,
  order: 1,
  status: '0'
});

// 删除部门（会递归删除子部门）
await DeptAPI.deleteDept([1]);

菜单管理

概述

菜单管理模块提供系统菜单的树形结构管理功能，支持菜单的创建、查询、更新、删除和状态管理。

核心接口

功能	方法	接口	权限
查询菜单树	`getMenuTree`	`GET /api/v1/system/menu/tree`	`module_system:menu:query`
查询菜单详情	`detailMenu`	`GET /api/v1/system/menu/detail/{id}`	`module_system:menu:detail`
创建菜单	`createMenu`	`POST /api/v1/system/menu/create`	`module_system:menu:create`
更新菜单	`updateMenu`	`PUT /api/v1/system/menu/update/{id}`	`module_system:menu:update`
删除菜单	`deleteMenu`	`DELETE /api/v1/system/menu/delete`	`module_system:menu:delete`
批量设置状态	`batchMenu`	`PATCH /api/v1/system/menu/available/setting`	`module_system:menu:patch`

菜单类型

类型值	说明
1	目录
2	菜单
3	按钮
4	外链

前端调用示例

typescript

// 获取菜单树
const menuTree = await MenuAPI.getMenuTree({});

// 创建菜单
await MenuAPI.createMenu({
  name: '系统管理',
  path: '/system',
  component: 'Layout',
  type: 1,
  parent_id: 0,
  order: 1,
  status: '0',
  icon: 'system'
});

缓存管理

概述

缓存管理模块提供对 Redis 缓存的监控和管理功能，包括缓存信息查询、缓存键管理和缓存清除等操作。

核心接口

功能	方法	接口	权限
获取缓存监控信息	`getCacheInfo`	`GET /api/v1/monitor/cache/info`	`module_monitor:cache:query`
获取缓存名称列表	`getCacheNames`	`GET /api/v1/monitor/cache/get/names`	`module_monitor:cache:query`
获取缓存键名列表	`getCacheKeys`	`GET /api/v1/monitor/cache/get/keys/{cache_name}`	`module_monitor:cache:query`
获取缓存值	`getCacheValue`	`GET /api/v1/monitor/cache/get/value/{cache_name}/{cache_key}`	`module_monitor:cache:query`
清除指定缓存名称	`clearCacheByName`	`DELETE /api/v1/monitor/cache/delete/name/{cache_name}`	`module_monitor:cache:delete`
清除指定缓存键	`clearCacheByKey`	`DELETE /api/v1/monitor/cache/delete/key/{cache_key}`	`module_monitor:cache:delete`
清除所有缓存	`clearAllCache`	`DELETE /api/v1/monitor/cache/delete/all`	`module_monitor:cache:delete`

响应数据结构

typescript

interface CacheMonitorSchema {
  command_stats: Array<{
    name: string;    // 命令名称
    value: string;   // 调用次数
  }>;
  db_size: number;   // Redis数据库中的Key总数
  info: object;      // Redis服务器信息
}

interface CacheInfoSchema {
  cache_key: string;      // 缓存键名
  cache_name: string;     // 缓存名称
  cache_value: any;       // 缓存值
  remark: string | null;  // 备注说明
}

前端调用示例

typescript

// 获取缓存监控信息
const cacheInfo = await CacheAPI.getCacheInfo();

// 获取缓存名称列表
const cacheNames = await CacheAPI.getCacheNames();

// 获取指定缓存名称的键名列表
const keys = await CacheAPI.getCacheKeys('captcha');

// 清除所有缓存
await CacheAPI.clearAllCache();

在线用户管理

概述

在线用户管理模块提供对当前在线用户的监控和管理功能，支持查看在线用户列表、强制下线和清除所有在线用户等操作。

核心接口

功能	方法	接口	权限
获取在线用户列表	`getOnlineList`	`GET /api/v1/monitor/online/list`	`module_monitor:online:query`
强制下线	`forceOffline`	`DELETE /api/v1/monitor/online/delete`	`module_monitor:online:delete`
清除所有在线用户	`clearAllOnline`	`DELETE /api/v1/monitor/online/clear`	`module_monitor:online:delete`

前端调用示例

typescript

// 获取在线用户列表
const onlineUsers = await OnlineAPI.getOnlineList({ page_no: 1, page_size: 10 });

// 强制下线指定用户
await OnlineAPI.forceOffline('session-id-xxx');

// 清除所有在线用户（慎用）
await OnlineAPI.clearAllOnline();

服务器监控

概述

服务器监控模块提供服务器系统资源的实时监控信息，包括 CPU、内存、磁盘、网络等使用情况。

核心接口

功能	方法	接口	权限
获取服务器监控信息	`getServerInfo`	`GET /api/v1/monitor/server/info`	`module_monitor:server:query`

响应数据结构

typescript

interface ServerMonitorSchema {
  cpu: {
    percent: number;      // CPU使用率(%)
    cores: number;        // CPU核心数
  };
  memory: {
    total: number;        // 总内存(字节)
    used: number;         // 已使用内存(字节)
    free: number;         // 空闲内存(字节)
    percent: number;      // 内存使用率(%)
  };
  disk: {
    total: number;        // 磁盘总容量(字节)
    used: number;         // 已使用(字节)
    free: number;         // 空闲(字节)
    percent: number;      // 使用率(%)
  };
  network: {
    bytes_sent: number;   // 发送字节数
    bytes_recv: number;   // 接收字节数
  };
  uptime: number;         // 服务器运行时间(秒)
}

数据字典管理

概述

数据字典管理模块提供系统字典类型和字典数据的管理功能，支持字典的增删改查和缓存同步。

核心接口

字典类型

功能	方法	接口	权限
获取字典类型列表	`listDictType`	`GET /api/v1/system/dict/type/list`	`module_system:dict_type:query`
获取字典类型详情	`detailDictType`	`GET /api/v1/system/dict/type/detail/{id}`	`module_system:dict_type:detail`
创建字典类型	`createDictType`	`POST /api/v1/system/dict/type/create`	`module_system:dict_type:create`
更新字典类型	`updateDictType`	`PUT /api/v1/system/dict/type/update/{id}`	`module_system:dict_type:update`
删除字典类型	`deleteDictType`	`DELETE /api/v1/system/dict/type/delete`	`module_system:dict_type:delete`

字典数据

功能	方法	接口	权限
获取字典数据列表	`listDictData`	`GET /api/v1/system/dict/data/list`	`module_system:dict_data:query`
获取字典数据详情	`detailDictData`	`GET /api/v1/system/dict/data/detail/{id}`	`module_system:dict_data:detail`
创建字典数据	`createDictData`	`POST /api/v1/system/dict/data/create`	`module_system:dict_data:create`
更新字典数据	`updateDictData`	`PUT /api/v1/system/dict/data/update/{id}`	`module_system:dict_data:update`
删除字典数据	`deleteDictData`	`DELETE /api/v1/system/dict/data/delete`	`module_system:dict_data:delete`
根据类型获取字典数据	`getDictDataByType`	`GET /api/v1/system/dict/data/info/{dict_type}`	公开

前端调用示例

typescript

// 获取字典类型列表
const dictTypes = await DictAPI.listDictType({ page_no: 1, page_size: 10 });

// 根据字典类型获取数据（用于下拉选择等场景）
const statusOptions = await DictAPI.getDictDataByType('sys_user_status');

日志管理

概述

日志管理模块提供操作日志的查询、详情查看和导出功能。

核心接口

功能	方法	接口	权限
获取日志列表	`listLog`	`GET /api/v1/system/log/list`	`module_system:log:query`
获取日志详情	`detailLog`	`GET /api/v1/system/log/detail/{id}`	`module_system:log:detail`
删除日志	`deleteLog`	`DELETE /api/v1/system/log/delete`	`module_system:log:delete`
导出日志	`exportLog`	`POST /api/v1/system/log/export`	`module_system:log:export`

前端调用示例

typescript

// 查询日志
const logs = await LogAPI.listLog({
  page_no: 1,
  page_size: 20,
  start_time: '2024-01-01',
  end_time: '2024-01-31'
});

// 导出日志
const response = await LogAPI.exportLog({
  start_time: '2024-01-01',
  end_time: '2024-01-31'
});

通知管理

概述

通知管理模块提供公告通知的管理功能，支持公告的创建、查询、更新、删除和状态管理。

核心接口

功能	方法	接口	权限
获取公告列表	`listNotice`	`GET /api/v1/system/notice/list`	`module_system:notice:query`
获取公告详情	`detailNotice`	`GET /api/v1/system/notice/detail/{id}`	`module_system:notice:detail`
创建公告	`createNotice`	`POST /api/v1/system/notice/create`	`module_system:notice:create`
更新公告	`updateNotice`	`PUT /api/v1/system/notice/update/{id}`	`module_system:notice:update`
删除公告	`deleteNotice`	`DELETE /api/v1/system/notice/delete`	`module_system:notice:delete`
获取启用公告	`getAvailableNotice`	`GET /api/v1/system/notice/available`	登录用户
获取通知面板	`getNotificationPanel`	`GET /api/v1/system/notice/panel`	登录用户

前端调用示例

typescript

// 获取启用的公告（首页展示）
const notices = await NoticeAPI.getAvailableNotice();

// 获取通知面板数据（铃铛图标）
const panelData = await NoticeAPI.getNotificationPanel();

参数配置管理

概述

参数配置管理模块提供系统参数的管理功能，支持参数的增删改查和缓存同步。

核心接口

功能	方法	接口	权限
获取参数列表	`listParams`	`GET /api/v1/system/param/list`	`module_system:param:query`
获取参数详情	`detailParams`	`GET /api/v1/system/param/detail/{id}`	`module_system:param:detail`
根据键获取参数	`getParamsByKey`	`GET /api/v1/system/param/key/{config_key}`	`module_system:param:query`
根据键获取参数值	`getParamsValue`	`GET /api/v1/system/param/value/{config_key}`	`module_system:param:query`
创建参数	`createParams`	`POST /api/v1/system/param/create`	`module_system:param:create`
更新参数	`updateParams`	`PUT /api/v1/system/param/update/{id}`	`module_system:param:update`
删除参数	`deleteParams`	`DELETE /api/v1/system/param/delete`	`module_system:param:delete`
获取初始化参数	`getInitParams`	`GET /api/v1/system/param/info`	公开

前端调用示例

typescript

// 获取初始化参数（用于系统启动时加载配置）
const configParams = await ParamsAPI.getInitParams();

// 根据键获取参数值
const maxUploadSize = await ParamsAPI.getParamsValue('sys.max_upload_size');

岗位管理

概述

岗位管理模块提供岗位的管理功能，支持岗位的增删改查和状态管理。

核心接口

功能	方法	接口	权限
获取岗位列表	`listPosition`	`GET /api/v1/system/position/list`	`module_system:position:query`
获取岗位详情	`detailPosition`	`GET /api/v1/system/position/detail/{id}`	`module_system:position:detail`
创建岗位	`createPosition`	`POST /api/v1/system/position/create`	`module_system:position:create`
更新岗位	`updatePosition`	`PUT /api/v1/system/position/update/{id}`	`module_system:position:update`
删除岗位	`deletePosition`	`DELETE /api/v1/system/position/delete`	`module_system:position:delete`

前端调用示例

typescript

// 获取岗位列表
const positions = await PositionAPI.listPosition({ page_no: 1, page_size: 10 });

// 创建岗位
await PositionAPI.createPosition({
  name: '高级开发工程师',
  code: 'senior_dev',
  order: 1,
  status: '0'
});

租户管理

概述

租户管理模块提供多租户架构下的租户管理功能，支持租户的创建、查询、更新、删除以及用户管理、配额管理、配置管理和菜单权限管理。

核心接口

租户基本操作

功能	方法	接口	权限
获取租户列表	`listTenant`	`GET /api/v1/system/tenant/list`	`module_system:tenant:query`
获取租户详情	`detailTenant`	`GET /api/v1/system/tenant/detail/{id}`	`module_system:tenant:query`
创建租户	`createTenant`	`POST /api/v1/system/tenant/create`	`module_system:tenant:create`
更新租户	`updateTenant`	`PUT /api/v1/system/tenant/update/{id}`	`module_system:tenant:update`
删除租户	`deleteTenant`	`DELETE /api/v1/system/tenant/delete`	`module_system:tenant:delete`
切换租户状态	`toggleTenantStatus`	`PUT /api/v1/system/tenant/status/{id}`	`module_system:tenant:patch`

租户用户管理

功能	方法	接口	权限
获取租户用户	`getTenantUsers`	`GET /api/v1/system/tenant/{id}/users`	`module_system:tenant:query`
添加租户用户	`addTenantUser`	`POST /api/v1/system/tenant/{id}/users`	`module_system:tenant:create`
移除租户用户	`removeTenantUser`	`DELETE /api/v1/system/tenant/{id}/users/{uid}`	`module_system:tenant:delete`

租户配额管理

功能	方法	接口	权限
获取租户配额	`getTenantQuota`	`GET /api/v1/system/tenant/{id}/quota`	`module_system:tenant:query`
更新租户配额	`updateTenantQuota`	`PUT /api/v1/system/tenant/{id}/quota`	`module_system:tenant:update`

租户配置管理

功能	方法	接口	权限
获取租户配置	`getTenantConfig`	`GET /api/v1/system/tenant/{id}/config`	`module_system:tenant:query`
更新租户配置	`updateTenantConfig`	`PUT /api/v1/system/tenant/{id}/config`	`module_system:tenant:update`

租户菜单权限

功能	方法	接口	权限
获取租户菜单	`getTenantMenus`	`GET /api/v1/system/tenant/{id}/menus`	`module_system:tenant:query`
设置租户菜单	`setTenantMenus`	`PUT /api/v1/system/tenant/{id}/menus`	`module_system:tenant:update`

前端调用示例

typescript

// 创建租户
const tenant = await TenantAPI.createTenant({
  name: '示例租户',
  code: 'example_tenant',
  admin_name: '管理员',
  admin_account: 'admin',
  admin_password: 'password'
});

// 添加用户到租户
await TenantAPI.addTenantUser(tenant.id, { user_id: 123 });

// 设置租户配额
await TenantAPI.updateTenantQuota(tenant.id, {
  user_limit: 100,
  storage_limit: 1024 * 1024 * 1024 // 1GB
});

工单管理

概述

工单管理模块提供工单的创建、查询、更新和删除功能，支持工单流程管理。

核心接口

功能	方法	接口	权限
获取工单列表	`listTicket`	`GET /api/v1/system/ticket/list`	`module_ticket:ticket:query`
获取工单详情	`detailTicket`	`GET /api/v1/system/ticket/detail/{id}`	`module_ticket:ticket:query`
创建工单	`createTicket`	`POST /api/v1/system/ticket/create`	`module_ticket:ticket:create`
更新工单	`updateTicket`	`PUT /api/v1/system/ticket/update/{id}`	`module_ticket:ticket:update`
删除工单	`deleteTicket`	`DELETE /api/v1/system/ticket/delete`	`module_ticket:ticket:delete`

前端调用示例

typescript

// 创建工单
await TicketAPI.createTicket({
  title: '系统故障报告',
  content: '系统登录页面无法正常加载',
  priority: 'high',
  type: 'bug'
});

// 获取工单列表
const tickets = await TicketAPI.listTicket({ page_no: 1, page_size: 10 });

目录 ​

文件上传 ​

概述 ​

上传类型 ​

统一上传接口 ​

资源上传接口 ​

前端调用示例 ​

通用文件上传 ​

头像上传 ​

参数配置上传 ​

资源文件上传（指定目录） ​

安全特性 ​

目录结构 ​

资源管理 ​

概述 ​

功能列表 ​

目录浏览 ​

删除资源 ​

移动资源 ​

复制资源 ​

重命名资源 ​

创建目录 ​

健康检查 ​

概述 ​

检查类型 ​

基础健康检查 ​

就绪检查 ​

存活检查 ​

监控指标 ​

概述 ​

指标端点 ​

可用指标 ​

配置说明 ​

Grafana 配置示例 ​

最佳实践 ​

1. 文件上传 ​

2. 资源管理 ​

3. 监控运维 ​

认证系统 ​

概述 ​

登录流程 ​

核心接口 ​

前端调用示例 ​

Token 管理 ​

插件市场 ​

概述 ​

核心接口 ​

插件状态说明 ​

前端调用示例 ​

定时任务 ​

概述 ​

核心接口 ​

调度器状态 ​

前端调用示例 ​

AI 对话 ​

概述 ​

核心接口 ​

数据结构 ​

前端调用示例 ​

用户管理 ​

概述 ​

核心接口 ​

关键业务逻辑 ​

用户创建流程 ​

权限控制 ​

前端调用示例 ​

角色管理 ​

概述 ​

核心接口 ​

数据权限范围 ​

前端调用示例 ​

部门管理 ​

概述 ​

核心接口 ​

关键业务逻辑 ​

部门删除 ​

状态联动 ​

前端调用示例 ​

菜单管理 ​

概述 ​

目录

文件上传

概述

上传类型

统一上传接口

资源上传接口

前端调用示例

通用文件上传

头像上传

参数配置上传

资源文件上传（指定目录）

安全特性

目录结构

资源管理

概述

功能列表

目录浏览

删除资源

移动资源

复制资源

重命名资源

创建目录

健康检查

概述

检查类型

基础健康检查

就绪检查

存活检查

监控指标

概述

指标端点

可用指标

配置说明

Grafana 配置示例

最佳实践

1. 文件上传

2. 资源管理

3. 监控运维

认证系统

概述

登录流程

核心接口

前端调用示例

Token 管理

插件市场

概述

核心接口

插件状态说明

前端调用示例

定时任务

概述

核心接口

调度器状态

前端调用示例

AI 对话

概述

核心接口

数据结构

前端调用示例

用户管理

概述

核心接口

关键业务逻辑

用户创建流程

权限控制

前端调用示例

角色管理

概述

核心接口

数据权限范围

前端调用示例

部门管理

概述

核心接口

关键业务逻辑

部门删除

状态联动

前端调用示例

菜单管理

概述