# codex_shms **Repository Path**: zhihuicode/codex_shms ## Basic Information - **Project Name**: codex_shms - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-07-22 - **Last Updated**: 2026-08-14 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 工业物联网平台 · 通用全栈基建框架 一个可复用的前后端一体化脚手架,采用**工业物联网科技风(深色)**界面。提供认证授权、系统管理、 监控看板/大屏、统一响应与异常、异步任务,以及 PostgreSQL / TDengine / Valkey / Kafka / MinIO 五类中间件的客户端封装与健康检查。**不含具体业务领域模型**,可作为多个项目的通用底座。 --- ## 目录 - [技术栈](#技术栈) - [系统架构](#系统架构) - [目录结构](#目录结构) - [端口约定](#端口约定) - [快速开始](#快速开始) - [默认账号与访问入口](#默认账号与访问入口) - [核心能力](#核心能力) - [功能模块与交互](#功能模块与交互) - [接口一览](#接口一览) - [接口调用示例](#接口调用示例) - [开发流程](#开发流程) - [数据库迁移](#数据库迁移) - [安全提示](#安全提示) --- ## 技术栈 | 层 | 技术 | | --- | --- | | 前端 | Vue 3 + TypeScript + Vite + Element Plus(暗色定制)+ Pinia + Vue Router + ECharts | | 后端 | Python 3.12 + FastAPI + SQLAlchemy 2.0 (async) + Alembic,uv 管理依赖 | | 异步任务 | arq(基于 Valkey/Redis) | | 业务库 | PostgreSQL 16 | | 时序库 | TDengine 3.x(taospy WebSocket 连接) | | 缓存 | Valkey 8(Redis 协议兼容,redis-py 连接) | | 消息队列 | Kafka 3.x(KRaft 模式,aiokafka) | | 物联网消息 | MQTT / Mosquitto 2.x(paho-mqtt,后台线程订阅) | | 对象存储 | MinIO(S3 兼容) | | 系统监控 | psutil(CPU/内存采集) | ## 系统架构 ``` 浏览器(Vue3 + Element Plus 科技风) 登录/RBAC 菜单 · 看板 · 大屏 · 中间件示例 · 系统管理 │ HTTP /api(vite 代理 → 18000) ▼ ┌──────────────────────────────────────────────────────┐ │ FastAPI 后端(18000) │ │ 中间件: CORS → 审计/请求计数 → 全局异常 │ │ 路由 api/v1: auth·user·role·menu·dict·audit │ │ system(健康探针)·monitor(指标)·demo │ │ 依赖: JWT 鉴权 · require_permission(RBAC) │ │ 服务/客户端(lifespan 统一 init/close/ping) │ └───┬──────┬───────┬───────┬───────┬───────┬────────────┘ │ │ │ │ │ │ ▼ ▼ ▼ ▼ ▼ ▼ PostgreSQL Valkey Kafka TDengine MinIO MQTT 业务/RBAC 缓存/ 消息 时序数据 对象 Mosquitto 审计日志 限流/ (看板) 存储 (后台线程订阅) 请求计数 ▲ │ arq worker(定时任务:清理过期审计日志) └── Valkey 队列 ``` 数据流要点: - **鉴权**:前端 axios 拦截器带 JWT;access 过期用 refresh 自动换新并重放。 - **RBAC**:路由 `require_permission` 校验;菜单/按钮按权限动态渲染。 - **监控**:审计中间件把请求数写 Valkey,`/monitor/metrics` 聚合 CPU/内存/中间件状态。 - **MQTT**:paho 后台线程订阅 `demo/#`,消息进环形缓冲,前端轮询 `/demo/mqtt/messages`。 ## 目录结构 ``` . ├── backend/ # FastAPI 后端 │ ├── app/ │ │ ├── core/ # 配置/日志/安全(JWT+bcrypt)/统一响应/异常/分页 │ │ ├── db/ # SQLAlchemy async engine 与 session │ │ ├── clients/ # tdengine/valkey/kafka/minio/mqtt 客户端封装(init/close/ping) │ │ ├── models/ # ORM: user/role/menu/dict/audit │ │ ├── schemas/ # Pydantic 请求/响应模型 │ │ ├── services/ # 业务逻辑(auth/rbac) │ │ ├── api/v1/ # 路由: auth/user/role/menu/dict/audit/system/monitor/demo(含 MQTT) │ │ ├── middleware/ # 审计中间件 + 请求计数(供监控大屏) │ │ ├── worker.py # arq 异步任务(cron 示例:清理过期审计日志) │ │ ├── seed.py # 初始化管理员/角色/菜单权限树 │ │ └── main.py # 应用入口(lifespan 统一管理中间件连接) │ └── alembic/ # 数据库迁移 ├── frontend/ # Vue3 前端 │ └── src/ │ ├── api/ # axios 封装 + 拦截器(token 自动刷新)+ 各模块接口 │ ├── stores/ # Pinia: user(登录态/权限)、permission(动态菜单) │ ├── router/ # 路由 + 全局权限守卫 │ ├── layout/ # 主框架布局(侧边栏/顶栏) │ ├── styles/ # theme.css 工业物联网科技风全局主题 │ ├── components/ # BaseChart(ECharts 按需封装:折线/饼/仪表盘) │ ├── utils/ # tree.ts 扁平列表转树 │ └── views/ # login / dashboard / bigscreen / middleware / system(user/role/menu/dict/audit) └── deploy/ ├── docker-compose.yml # 一键拉起全部(含前后端镜像) ├── middleware-only.yml # 仅中间件(本地跑源码用) ├── test-middleware.yml # 联调测试用(缓存镜像 + 避冲突端口) └── mosquitto.conf # MQTT broker 配置(允许匿名,仅开发用) ``` ## 端口约定 > 默认端口刻意避开常见占用(8000/5173),便于与其他项目共存。 | 服务 | 本地开发端口 | 容器编排端口 | 说明 | | --- | --- | --- | --- | | 后端 API | 18000 | 18000→8000 | `uvicorn ... --port 18000` | | 前端 | 5180 | 8080(nginx) | vite dev 代理 `/api` → 后端 | | PostgreSQL | 5432 | 5432 | 业务库 | | TDengine | 6041 | 6041 | WebSocket 连接 | | Valkey | 6379 | 6379 | Redis 协议 | | Kafka | 9092 | 9092 | KRaft 单节点 | | MQTT | 1883 | 1883 | Mosquitto(匿名) | | MinIO | 9000 / 9001 | 9000 / 9001 | API / 控制台 | ## 快速开始 ### 方式一:全部容器化(一键) ```bash cd deploy docker compose up -d --build # 初始化数据库表与默认数据(管理员/角色/菜单) docker compose exec backend uv run python -m app.seed ``` ### 方式二:本地开发(中间件用容器,前后端跑源码) ```bash # 1. 起中间件 cd deploy && docker compose -f middleware-only.yml up -d # 2. 后端 cd ../backend cp .env.example .env uv sync # 安装依赖 uv run python -m app.seed # 建表 + 初始化数据 uv run uvicorn app.main:app --reload --port 18000 # 启动 API(默认避开 8000) # 3. 异步任务 worker(另开终端,可选) uv run arq app.worker.WorkerSettings # 4. 前端 cd ../frontend npm install npm run dev # http://localhost:5180 ``` > 前端 dev 代理目标固定在 `vite.config.ts`(`/api` → `http://127.0.0.1:18000`)。 > 如需改后端地址,直接改该文件的 `proxy.target`。 ## 默认账号与访问入口 | 项 | 地址 / 值 | | --- | --- | | 前端(本地) | http://localhost:5180 | | 前端(容器) | http://localhost:8080 | | 后端 Swagger 文档 | http://localhost:18000/docs | | MinIO 控制台 | http://localhost:9001 | | 默认管理员 | **admin / admin123** | 登录后建议先逛这几处快速验证环境: 1. **中间件示例**(`/middleware`):顶部看 6 个中间件连通状态灯;逐个测试 TDengine 写查、 Valkey 读写、Kafka 发送、MinIO 上传、**MQTT 发布 → 下方 2 秒内实时回显**。 2. **监控看板**(`/dashboard`):点「生成示例数据」灌入时序数据,查看降采样折线图与设备分布饼图。 3. **监控大屏**(`/bigscreen`):全屏查看 CPU/内存仪表盘与中间件状态,每 3 秒自刷。 ## 核心能力 ### 认证与授权 - JWT 双令牌(access + refresh);access 过期时前端拦截器自动用 refresh 换新并重放请求 - RBAC:用户-角色-菜单/权限点,后端路由级 `require_permission("system:user:list")` 校验 - 登录失败限流:Valkey 计数,超阈值临时锁定账号 - 密码 bcrypt 加密;支持管理员重置他人密码、用户改自己密码 ### 统一约定 - 响应体统一 `{code, message, data}`,后端用 `Resp.ok()` / `Resp.fail()` - 全局异常处理 + 错误码枚举(`app/core/exceptions.py`) - 统一分页 `PageParams`(page / page_size / order_by / desc) ### 中间件封装(`app/clients/`) 每个中间件提供 `init_x` / `close_x`(由 `main.py` lifespan 统一管理生命周期)与 `ping_x` 健康探活: - `GET /health/live` 存活探针 - `GET /health/ready` 就绪探针(逐个探活 PG/Valkey/Kafka/MinIO/TDengine/MQTT) - `GET /demo/*` 每个中间件的读写示例接口 - **MQTT** 采用 paho-mqtt 自带后台网络线程(`loop_start`)订阅 `demo/#`,收到的消息进 程内环形缓冲供前端轮询。> 说明:aiomqtt 在 Windows 默认 ProactorEventLoop 上会因 `add_reader` 不支持而失败,故改用 paho 独立线程,跨平台稳定。 ### 系统监控 - `GET /monitor/metrics`:CPU 使用率/核数、内存使用率/进程占用、6 中间件实时状态、 请求总数/异常数/异常率、运行时长 - 请求计数由审计中间件写入 Valkey(健康检查与监控接口自身不计,避免噪音) ### 异步任务(arq) - `app/worker.py` 定义任务与 cron;示例:每日 3:00 清理过期审计日志 - API 侧可通过 arq 连接池入队后台任务 ## 功能模块与交互 登录后左侧菜单按当前用户权限**动态渲染**,主要模块: | 模块 | 路由 | 交互说明 | | --- | --- | --- | | 监控看板 | `/dashboard` | 折线图(TDengine 按小时降采样趋势)+ 饼图(设备分布);"生成示例数据"一键灌入演示时序数据 | | 监控大屏 | `/bigscreen` | 全屏深色大屏,CPU/内存仪表盘、6 中间件状态灯、请求/异常统计,**每 3 秒自动刷新** | | 中间件示例 | `/middleware` | 连通状态总览 + 各中间件读写测试:TDengine 写查、Valkey 读写、Kafka 发送、MinIO 上传、**MQTT 发布与实时接收(2 秒轮询)** | | 用户管理 | `/system/user` | 分页 + 关键字搜索;新增/编辑(含多选分配角色)/删除/重置密码 | | 角色管理 | `/system/role` | 增删改;编辑时用**菜单权限树**勾选分配权限 | | 菜单管理 | `/system/menu` | 树形表格;支持目录(M)/菜单(C)/按钮(F)三级,增删改 | | 字典管理 | `/system/dict` | 字典类型列表 + 右侧抽屉管理该类型下的字典数据 | | 审计日志 | `/system/audit` | 分页查看写操作留痕(操作人/方法/路径/IP/状态码/耗时) | > 界面为**工业物联网科技风**(深色):青色荧光主色、网格背景、仪表盘/状态灯,全局主题见 > `frontend/src/styles/theme.css`。 > 页面按钮也受权限控制:前端 `useUserStore().hasPerm('system:user:add')` 决定是否显示。 ## 接口一览 所有接口挂在 `/api/v1` 前缀下。除登录/刷新/健康检查外,均需 `Authorization: Bearer `。 | 模块 | 方法 & 路径 | 说明 | | --- | --- | --- | | 认证 | `POST /auth/login` | 登录,返回双 token | | | `POST /auth/refresh` | 刷新 access token | | | `GET /auth/me` | 当前用户信息(角色/权限) | | | `POST /auth/logout` | 登出 | | | `PUT /auth/password` | 改自己密码(校验原密码) | | 用户 | `GET /users` | 分页列表(支持 keyword) | | | `GET /users/{id}` | 详情(含已分配角色) | | | `POST /users` / `PUT /users/{id}` / `POST /users/delete` | 增 / 改 / 删 | | | `PUT /users/{id}/password` | 重置指定用户密码 | | 角色 | `GET /roles` / `GET /roles/{id}` | 列表 / 详情(含已分配菜单) | | | `POST /roles` / `PUT /roles/{id}` / `POST /roles/delete` | 增 / 改 / 删 | | 菜单 | `GET /menus` / `GET /menus/routes` | 全部菜单 / 当前用户可见菜单 | | | `POST /menus` / `PUT /menus/{id}` / `POST /menus/delete` | 增 / 改 / 删 | | 字典 | `GET/POST /dicts/types`,`PUT /dicts/types/{id}`,`POST /dicts/types/delete` | 字典类型 CRUD | | | `GET /dicts/data/{type}`,`POST /dicts/data`,`PUT /dicts/data/{id}`,`POST /dicts/data/delete` | 字典数据 CRUD | | 审计 | `GET /audit-logs` | 分页查询审计日志 | | 监控 | `GET /monitor/metrics` | CPU/内存/中间件/请求统计 | | 健康 | `GET /health/live` / `GET /health/ready` | 存活 / 就绪探针 | | 示例 | `POST /demo/tdengine/seed`,`GET /demo/tdengine/dashboard` | 看板示例数据 / 聚合 | | | `POST /demo/tdengine/write`,`GET /demo/tdengine/query` | TDengine 读写 | | | `POST /demo/valkey/set`,`GET /demo/valkey/get` | Valkey 读写 | | | `POST /demo/kafka/send` | Kafka 发送 | | | `POST /demo/minio/upload` | MinIO 上传(返回预签名 URL) | | | `POST /demo/mqtt/publish`,`GET /demo/mqtt/messages` | MQTT 发布 / 读取最近接收消息 | ## 接口调用示例 以本地后端(18000)为例,演示登录取 token → 带 token 调接口 → MQTT 收发。 ```bash BASE=http://localhost:18000/api/v1 # 1) 登录,取出 access_token TOKEN=$(curl -s -X POST $BASE/auth/login \ -H 'Content-Type: application/json' \ -d '{"username":"admin","password":"admin123"}' \ | python -c "import sys,json;print(json.load(sys.stdin)['data']['access_token'])") # 2) 带 token 获取当前用户信息 curl -s $BASE/auth/me -H "Authorization: Bearer $TOKEN" # 3) 用户分页列表(带查询参数) curl -s "$BASE/users?page=1&page_size=10&keyword=adm" -H "Authorization: Bearer $TOKEN" # 4) 就绪探针:6 个中间件连通状态 curl -s $BASE/health/ready -H "Authorization: Bearer $TOKEN" # 5) MQTT:发布一条消息,再读回后台订阅收到的最近消息 curl -s -X POST "$BASE/demo/mqtt/publish?topic=demo/sensor&msg=temp:25.6" \ -H "Authorization: Bearer $TOKEN" curl -s "$BASE/demo/mqtt/messages?limit=5" -H "Authorization: Bearer $TOKEN" # 6) 看板:生成示例时序数据,再取聚合(趋势+分布) curl -s -X POST "$BASE/demo/tdengine/seed?hours=24&devices=4" -H "Authorization: Bearer $TOKEN" curl -s $BASE/demo/tdengine/dashboard -H "Authorization: Bearer $TOKEN" ``` > 统一响应体 `{"code":0,"message":"ok","data":...}`;`code` 非 0 即为业务错误。 > 注意:含中文的请求体经 shell 传递可能乱码,建议用 `--data-binary @文件` 或前端调用。 ## 开发流程 **新增一个后端管理模块(以「设备」为例)的典型流程:** 1. **建模型** `app/models/device.py`,并在 `app/models/__init__.py` 导出 2. **写 Schema** `app/schemas/device.py`(Create/Update/Out) 3. **写路由** `app/api/v1/device.py`,用 `DbDep` 注入 session、 `Depends(require_permission("system:device:list"))` 控权,返回 `Resp.ok(...)` 4. **注册路由** 在 `app/api/v1/router.py` `include_router(device.router)` 5. **加权限菜单** 在 `app/seed.py` 补菜单/按钮权限点,重新 seed 6. **前端接口** `frontend/src/api/device.ts`;**类型** 补到 `types.ts` 7. **前端页面** `frontend/src/views/system/device/index.vue`;**注册路由** `router/index.ts` 8. **验证**:后端 `python -m compileall app`,前端 `npm run build`;起服务联调 **约定:** - 后端每个方法写简明 docstring;前端每个方法上方加中文注释 - 列表接口统一用 `PageParams` 分页;写操作会被审计中间件自动留痕 - 新中间件客户端放 `app/clients/`,实现 `init/close/ping` 并接入 `main.py` lifespan - 前端页面统一用 Element Plus + `theme.css` 的科技风变量,不写零散内联色值 **代码检查:** ```bash cd backend && uv run ruff check . # 后端 lint cd frontend && npm run build # 前端类型检查 + 打包(vue-tsc) ``` ## 数据库迁移 ```bash cd backend uv run alembic revision --autogenerate -m "message" uv run alembic upgrade head ``` > 首次可直接用 `python -m app.seed`(内部 `create_all`)快速建表;正式环境走 Alembic。 > 开发期若模型大改,可 drop 全表后重新 seed(仅限本地测试数据)。 ## 安全提示 - 生产环境务必修改 `JWT_SECRET` 及各中间件默认密码 - MinIO / Kafka / TDengine 默认凭据仅供本地开发,勿用于生产 - 后端 API 默认全部需要认证(除登录/刷新/健康检查),`demo` 接口也要求登录 - `vite.config.ts` 的代理与写死端口仅用于开发;生产由 nginx(见 `frontend/nginx.conf`)转发 ## 最近更新 - **接入 MQTT 中间件**:Mosquitto broker + paho-mqtt 后台线程订阅;中间件示例页支持发布 与实时接收(2 秒轮询),健康探针/监控大屏纳入 MQTT(共 6 个中间件)。 - **新增「中间件示例」页** `/middleware`:连通状态总览 + 各中间件读写测试。 - **工业物联网科技风主题**:全局深色 + 青色荧光,登录页/侧边栏/看板/大屏统一改造 (`frontend/src/styles/theme.css`)。 - **监控看板折线图修复**:TDengine 时间戳(`"... +08:00"` 带空格)转 ISO 后再渲染, 解决曲线不显示问题。 - **全量中文注释**:前后端所有方法均补充中文注释/docstring。 - **默认端口避让**:后端 18000、前端 5180,避免与常见 8000/5173 冲突。