# OpsMind

**Repository Path**: elfbobo_admin_admin/ops-mind

## Basic Information

- **Project Name**: OpsMind
- **Description**: 面向中小规模 IT 基础设施的综合运维管理平台，涵盖服务器/资产管理、监控告警、证书与凭据、CI/CD 服务构建与发版、项目中心、消息中心与拓扑可视化等能力，采用 FastAPI + Vue 3 前后端分离架构。
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 明鉴 · 综合运维平台

> 产品名：**明鉴**（API 标题：明鉴运维管理系统 API）｜ 当前版本：**v1.8.25** ｜ 架构：前后端分离

明鉴是一套面向中小规模 IT 基础设施的**综合运维管理平台**，涵盖服务器/资产管理、监控告警、证书与凭据、CI/CD 服务构建与发版、项目中心、消息中心与拓扑可视化等能力，采用 FastAPI + Vue 3 前后端分离架构。

> ⚠️ **本仓库为内部项目，README 中的默认账号、密钥、数据库连接均为示例/开发配置，生产部署前必须替换并做安全加固。**

---

## 目录

- [核心功能](#核心功能)
- [技术栈](#技术栈)
- [系统架构](#系统架构)
- [目录结构](#目录结构)
- [快速开始](#快速开始)
- [核心模块](#核心模块)
- [API 文档](#api-文档)
- [数据库 Schema 与迁移](#数据库-schema-与迁移)
- [部署与运维](#部署与运维)
- [安全最佳实践](#安全最佳实践)
- [开发规范](#开发规范)
- [常见问题](#常见问题)
- [版本历史](#版本历史)
- [许可证与贡献](#许可证与贡献)

---

## 核心功能

- **资产管理**：服务器列表、分组、远程命令执行；网络设备故障管理、拓扑可视化
- **监控告警**：CPU/内存/磁盘/网络实时监控；告警管理；Prometheus 告警规则；多数据源管理（Elasticsearch、Prometheus 等）；ES 告警引擎；Alertmanager 集成
- **自动化运维**：任务管理（创建/执行/定时任务）、执行历史
- **安全管理**：用户、角色、权限（RBAC）、操作日志、系统日志、系统参数
- **证书管理**：ACME 证书申请/监控、证书看板与到期预警
- **凭据管理**：凭据库（含 KubeConfig 类型）、CI/CD Agent 管理
- **项目中心**：全局一级实体「项目」，聚合证书/任务/CI-CD/拓扑等资源，提供项目资源总览
- **持续集成/部署**：CI/CD 项目、服务构建、构建集群、环境管理、制品库、发版与回滚、构建队列与历史（Jenkins 风格）
- **消息中心**：站内消息、推送群组（钉钉/飞书/邮箱）、消息模板（20+ Exporter 专用）、Alertmanager Webhook 路由
- **拓扑可视化**：网络拓扑与「涟漪视图」，支持节点绑定真实资源、告警指标联动、撤销/重做、导入导出
- **报表分析**：系统/性能/服务器/告警等前端聚合报表（基于监控指标与告警数据）
- **会话管理**：登录会话 1 小时有效期，超时无操作自动退出

> 说明：「漏洞扫描」「脚本管理」为早期规划/历史模块，当前代码库中已无对应实现，已从本文档移除。

---

## 技术栈

### 后端

| 组件 | 版本 / 说明 |
| --- | --- |
| Python | 3.9+（开发环境实测 3.12/3.13） |
| FastAPI | 0.104.1 |
| Uvicorn | 0.24.0 |
| SQLAlchemy | 2.0.23（ORM，`models/` 定义元数据） |
| Alembic | 1.13.0（**历史遗留，见[数据库章节](#alembic-的现状历史遗留)）** |
| PostgreSQL | 15.6（生产/容器默认） |
| Redis | 8.4（compose 内置，按配置预留） |
| RabbitMQ | 4.2.2-management（compose 内置，按配置预留） |
| 认证 / 权限 | JWT（`python-jose`，HS256）+ RBAC |
| 其他 | Pydantic 2、Prometheus Client、Elasticsearch 8、pycryptodome、pika |

### 前端

| 组件 | 版本 / 说明 |
| --- | --- |
| Vue | 3.3.11+ |
| Vite | 5.0.8（构建工具） |
| Element Plus | 2.4.4 |
| ECharts | 5.6.0 |
| Pinia | 2.1.7（状态管理） |
| Vue Router | 4.2.5 |
| Axios / Day.js / Lodash-es | HTTP / 时间 / 工具 |
| Tiptap | 3.x（富文本，用于消息模板等） |

> **Prometheus / Grafana / Alertmanager** 为**外部集成系统**，不随 `docker-compose` 启动；平台通过数据源配置、告警规则同步与 Webhook 与之对接。

---

## 系统架构

平台采用前后端分离 + 外部依赖的部署形态。下图为基础部署拓扑（更详细的架构说明见 [`.wiki/architecture.md`](.wiki/architecture.md)）：

```
┌────────────────┐      ┌──────────────────────────────┐      ┌─────────────────┐
│  浏览器 / Vue  │─────▶│  FastAPI 后端（明鉴 API）     │─────▶│  PostgreSQL 15  │
│  前端  :8082   │      │  :8000（uvicorn main:app）    │      │  db: example_db │
└────────────────┘      └──────────────────────────────┘      └─────────────────┘
                               │  │  │
             ┌─────────────────┘  │  └─────────────────┐
             ▼                    ▼                    ▼
       ┌─────────────┐    ┌──────────────┐     ┌─────────────────────┐
       │  Redis 8    │    │ RabbitMQ 4   │     │  外部系统集成        │
       │ 缓存/会话   │    │ 消息队列     │     │ Prometheus / ES /   │
       └─────────────┘    └──────────────┘     │ Grafana /          │
                                               │ Alertmanager        │
                                               └─────────────────────┘
```

**关键运行时行为**（来自 `backend/main.py` 的 lifespan）：应用启动时**仅校验数据库是否已初始化**（检查是否存在「超级管理员」角色），并拉起若干后台常驻任务——证书监控推送、证书到期检查（6h）、服务器探活、Prometheus 规则自动同步、ES 告警引擎、Node Exporter 采集。**应用启动不会自动执行任何 DDL/迁移脚本。**

---

## 目录结构

```
DevOps/
├── backend/                  # 后端（FastAPI）
│   ├── api/                  # 路由层（27 个模块：auth/servers/alerts/cicd/...）
│   ├── config/               # 配置（config.yaml 为权威配置来源）
│   ├── models/               # ORM 模型（SQLAlchemy）
│   ├── schemas/              # Pydantic 校验模型
│   ├── services/             # 业务逻辑层
│   ├── migrations/           # 数据库增量迁移 SQL 脚本（YYYYMMDD_简述.sql）
│   ├── alembic/              # Alembic 配置（历史遗留，勿用，见下）
│   ├── init.sql              # 完整数据库初始化脚本（Schema 权威来源）
│   ├── main.py               # 应用入口
│   ├── requirements.txt      # Python 依赖
│   └── Dockerfile            # 后端镜像构建
├── frontend/                 # 前端（Vue 3 + Vite）
│   ├── src/                  # 源代码（api/components/views/router/store/...）
│   ├── public/               # 静态资源
│   ├── .env.development      # 开发环境变量（API 地址）
│   ├── .env.production       # 生产环境变量
│   ├── index.html            # HTML 模板
│   ├── package.json          # 依赖与脚本
│   ├── vite.config.js        # Vite 配置
│   └── Dockerfile            # 前端镜像构建
├── .wiki/                    # 项目 Wiki（按 backend/ frontend/ 分层）
├── prototype/                # 原型/设计稿
├── docker-compose.yaml       # Docker 编排（postgres/redis/rabbitmq/backend/frontend）
├── LICENSE                   # MIT 许可证
└── README.md                 # 本文档
```

---

## 快速开始

### 环境要求

- Docker 与 Docker Compose **v2**（`docker compose` 子命令）
- 或本地：Python 3.9+、Node.js 18+

### Docker 部署（推荐）

```bash
docker compose up -d
```

容器服务与端口：

| 服务 | 容器内端口 | 宿主机端口 | 说明 |
| --- | --- | --- | --- |
| 前端（Nginx 静态 + 反代） | 8082 | **8082** | 访问入口 |
| 后端 API | 8000 | 8000 | Swagger：`/docs` |
| PostgreSQL | 5432 | 5432 | 库名 `example_db` |
| Redis | 6379 | 6379 | 带密码 |
| RabbitMQ | 5672 / 15672 | 5672 / 15672 | 15672 为管理界面 |

> 💡 **数据库自动初始化**：`docker-compose` 将 `backend/init.sql` 挂载到 Postgres 的 `docker-entrypoint-initdb.d`，**仅当数据库为空时**自动执行一次建表与种子数据。已有库不会重复执行。

**访问地址**

- 前端应用：<http://localhost:8082>
- 后端 API 文档：<http://localhost:8000/docs>
- RabbitMQ 管理界面：<http://localhost:15672>（compose 内置）

> 注：Prometheus / Grafana 不在 compose 内，需另行部署并通过数据源配置接入。

**默认账号（仅开发环境）**

- 用户名：`admin`　密码：`123456`
- ⚠️ 生产环境请务必通过 `init.sql` 种子或数据库改密，并禁用弱口令。

### 本地开发

#### 后端

```bash
cd backend
python -m venv venv && source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt
# 初始化数据库（首次）：见「数据库 Schema 与迁移」
python main.py        # 等价于 uvicorn main:app（reload 跟随 config.yaml 的 debug）
```

#### 前端

```bash
cd frontend
npm install
npm run dev           # 开发服务器，默认 http://localhost:5173（以 vite 配置为准）
```

本地联调时，前端通过 `.env.development` 中的 `VITE_API_BASE` 指向后端 `http://localhost:8000`。

---

## 核心模块

### 1. 资产管理

- **服务器**：列表、分组、远程命令执行、硬件/系统详情
- **网络设备**：设备信息管理、网络拓扑

### 2. 监控告警

- 实时监控指标（CPU/内存/磁盘/网络）
- 告警管理（查看、处理、状态流转）
- 多数据源管理（Elasticsearch、Prometheus、InfluxDB、MySQL、PostgreSQL，支持连接测试）
- Prometheus 告警规则管理与自动同步
- ES 告警引擎（基于 ES 查询的告警）

### 3. 自动化运维

- 任务管理（创建/编辑/执行/定时）、执行历史

### 4. 安全管理

- 用户、角色、权限（RBAC 细粒度）
- 操作日志、系统日志（审计）

### 5. 证书管理

- ACME 证书申请与监控、到期预警、证书看板

### 6. 凭据与 Agent

- 凭据库（类型含 **KubeConfig** 等多行文本凭据）
- CI/CD Agent 管理

### 7. 项目中心

- 全局一级实体「项目」，聚合证书、任务、CI-CD、拓扑等资源
- 项目资源总览聚合页；模块内联项目上下文过滤

### 8. 持续集成/部署

- CI/CD 项目、服务构建（多语言/凭据引用/执行后端）
- 构建集群（CRUD + 探测）、环境管理、制品库（列表/下载）
- 发版与回滚、构建队列、构建历史全局查询（Jenkins 风格）

### 9. 消息中心

- 站内消息（筛选/已读/批量）
- 推送群组（钉钉/飞书/邮箱，Token/Webhook/成员配置、字段过滤与翻译）
- 消息模板（Markdown/普通文本，20+ Exporter 专用）
- Alertmanager Webhook：`POST /message-center/alertmanager` 按 `group` 路由到对应群组

#### Prometheus 告警直推（跳过 Alertmanager）

平台在 `/message-center/alertmanager/` 下实现了 **Alertmanager 兼容的入站 API**（`POST /api/v1/alerts`、`POST /api/v2/alerts`），因此可让 Prometheus 把告警**直接推送到平台**，**无需独立部署 Alertmanager**，由平台按每条告警的 `labels.group` 字段路由到对应推送群组（钉钉/飞书/邮箱）。

在 Prometheus 的 `prometheus.yml` 中，将平台的 API 前端地址注册为 Alertmanager 即可：

```yaml
# prometheus.yml
alerting:
  alertmanagers:
    - static_configs:
        - targets:
            - "127.0.0.1:8000"     # 明鉴后端地址 主机:端口
      path_prefix: /message-center/alertmanager
```

> Prometheus 会自动向该地址追加 `api/v2/alerts` 并推送告警，最终请求命中平台的 `POST /message-center/alertmanager/api/v2/alerts`。

告警规则中必须给对应 `labels` 打上路由信息：

```yaml
groups:
  - name: example
    rules:
      - alert: CPUUsageHigh
        expr: 100 - avg(rate(node_cpu_seconds_total{mode="idle"}[5m])) by (instance) > 85
        for: 5m
        labels:
          severity: warning
          # 推送群组名，需提前在「消息中心-推送群组」中配置，告警按此路由
          group: "运维告警"
          # 可选：归属项目（平台侧按 project 聚合）
          project: "核心业务"
        annotations:
          description: "服务器 {{ $labels.instance }} CPU 使用率持续高于 85%"
```

关键说明：

- **`labels.group` 为必填**：对应推送群组名，未匹配到已配置群组的告警会被跳过，不会推送；
- `labels.severity`（`critical`/`error`→紧急、`warning`→警告、`info`→信息）映射为平台严重级别；`labels.instance` 用于关联服务器；
- `labels.project`（可选）：告警归属项目，供「项目中心」聚合展示；
- 已存在且未到重发间隔（`retry_interval`，默认 10 分钟）的相同告警会自动去重跳过，避免重复轰炸；
- 告警恢复（`endsAt` 已生效）会推送恢复通知。

**troubleshooting**：推送后未收到通知，依次检查——① `labels.group` 是否与「推送群组」名称完全一致；② 群组 Token/Webhook 是否有效；③ 查看后端日志关键字 `[Alertmanager v2]` 或 `[Alertmanager]` 确认是否命中群组、为何跳过。

### 10. 拓扑可视化

- 网络拓扑与「涟漪视图」：节点绑定真实资源（server/interface）、区域容器、告警联动、30s 轮询、撤销/重做、导入导出

### 11. 报表分析

- 系统/性能/服务器/告警前端聚合报表（基于监控指标与告警数据）

### 12. 会话管理

- 登录会话 1 小时有效期，超时无操作自动退出，超时前提醒

---

## API 文档

后端采用 RESTful 风格，启动后访问：

- Swagger UI：<http://localhost:8000/docs>
- ReDoc：<http://localhost:8000/redoc>
- 结构化接口说明另见 [`.wiki/api-reference.md`](.wiki/api-reference.md)

健康检查：`GET /health` → `{"status":"healthy"}`（compose 健康探针使用此端点）。

---

## 数据库 Schema 与迁移

### 核心原则

- **`backend/init.sql` 是数据库 Schema 的唯一权威来源**，必须与 `models/` 中的 SQLAlchemy 模型保持一致。
- **禁止在 Python 代码中硬编码 `ALTER TABLE` / `CREATE TABLE` 等 DDL**（应用启动不再触碰数据库结构）。
- 所有结构变更通过**独立、幂等、带注释与回滚说明的 SQL 迁移脚本**，由运维**人工通过 `psql` 执行**，再重启后端生效。

### 首次部署（初始化）

```bash
# 创建数据库 example_db 后执行（空库）
psql -h <host> -U <user> -d example_db -f backend/init.sql
```

> 使用 `docker compose` 时无需手动执行——`init.sql` 会在空库首次启动时自动挂载执行。

### 增量迁移（已有库升级）

将变更写入 `backend/migrations/`，命名约定 `YYYYMMDD_简述.sql`，要求：

- 含注释说明 + `IF NOT EXISTS` 保证幂等；
- 附回滚（如 `DROP ...`）注释，便于必要时人工回退；
- 不依赖程序自动执行。

```bash
# 人工执行单个迁移
psql -h <host> -U <user> -d example_db -f backend/migrations/20260723_cicd_build_release.sql
```

> ✅ 推荐实践：每次结构变更**同步更新 `init.sql`**，使新库可直接一次性初始化，避免迁移脚本无限堆叠。

### Alembic 的现状（历史遗留）

`backend/alembic/`（含 `env.py`、`script.py.mako` 与 `versions/` 下 3 个早期迁移：`001_initial_migration` → `002` → `003`）是项目早期的迁移方案**残留**：

- 其版本链停留在 2026-07-08，之后 Schema 演进完全由 `init.sql` + `backend/migrations/*.sql` 接管；
- `alembic upgrade head` 会尝试 `CREATE TABLE`，而 `init.sql` 已建好同名表，**对已初始化库执行会直接报错（relation already exists）**；
- 因此 **Alembic 当前不可用、也不应使用**。保留该目录仅作历史参考，后续如需恢复自动化迁移，应基于当前 `init.sql` 重新基线化（baseline）Alembic，而非在其旧版本链上追加。

> 设计决策见版本历史 **v1.4.3**：按需求禁止程序自动执行 SQL 迁移，移除 `main.py` 的 `run_startup_migrations()`，迁移改由人工 `psql` 执行。

---

## 部署与运维

### 配置来源

后端**以 `backend/config/config.yaml` 为权威配置**（应用名、版本、端口、数据库/Redis/JWT/CORS/日志/ACME 等）。部分项支持**环境变量覆盖**（优先级：环境变量 > config.yaml > 默认值）：

| 环境变量 | 覆盖的 config.yaml 路径 | 说明 |
| --- | --- | --- |
| `DATABASE_URL` | `database.url` | PostgreSQL 连接串 |
| `REDIS_URL` | `redis.url` | Redis 连接串（含密码） |
| `SECRET_KEY` | `jwt.secret_key` | JWT 签名密钥 |
| `ACME_EMAIL` | `acme.email` | ACME 注册邮箱 |
| `ACME_ACCOUNT_DIR` | `acme.account_dir` | ACME 账号密钥目录 |

> `docker-compose.yaml` 已通过 `DATABASE_URL` / `REDIS_URL` 将后端指向 compose 内服务名（`postgres` / `redis`）。其余配置（JWT 算法/过期、CORS、日志、RabbitMQ 连接）请直接在 `config.yaml` 中修改。

### 日志与备份

- **应用日志**：`logs/app.log`（滚动，见 config.yaml `logging`）
- **审计日志**：数据库 `operation_logs` 表
- **备份**：定期备份 PostgreSQL；配置文件与代码纳入 Git 版本控制

---

## 安全最佳实践

1. **密钥**：`config.yaml` 中 `jwt.secret_key` 默认占位符 `your-secret-key-here`，**生产必须替换为强随机值**并通过环境变量注入。
2. **密码**：使用 bcrypt 存储（`passlib`）；默认管理员口令 `123456` 仅限开发，上线即改。
3. **CORS**：默认 `cors.origins: ["*"]` 为开放策略，生产应限定可信前端域名。
4. **调试模式**：`app.debug: true` 会开启热重载与详细日志，**生产设为 `false`**。
5. **权限**：基于 RBAC 的细粒度控制，前端菜单/按钮与后端接口双重校验。
6. **输入校验**：Pydantic 严格校验；告警 Webhook 同时接受 JSON/YAML 并做解析兜底。
7. **网络安全**：生产环境应在前置网关/防火墙限制数据库、Redis、RabbitMQ 管理端口的暴露面。

---

## 开发规范

### 后端

1. 遵循 PEP 8；公共函数/类加文档字符串
2. 命名：类大驼峰、函数/变量小驼峰、常量全大写下划线
3. 数据访问统一走 `models/` + `services/`，**不在路由层写 DDL**
4. 结构变更按[数据库章节](#数据库-schema-与迁移)流程：改 `init.sql` + 写 `migrations/*.sql`

### 前端

1. 遵循 Vue 3 官方风格指南；组件单一职责、小而精
2. 命名：组件大驼峰、变量/方法小驼峰、常量全大写下划线
3. 状态管理用 Pinia，避免过度全局状态
4. 严重级别配色统一走 `utils/severity.js` 与 `.sev-*` 类，禁止散落硬编码

---

## 常见问题

### 1. 服务启动失败

- 端口被占用；数据库/Redis 未就绪；`config.yaml` 或环境变量错误。
- 检查：`docker compose ps`、后端日志 `logs/app.log`、DB 连通性。

### 2. 前端无法访问后端 API

- CORS 配置、后端未启动、`VITE_API_BASE` 路径错误。
- 检查前端 `.env.development` 的 API 地址与后端 `/docs` 可达性。

### 3. 监控数据不显示

- 数据源（Prometheus/ES）连接或采集异常；Grafana 数据源未配置。
- 检查「数据源管理」连接测试与对应服务健康状态。

### 4. 忘记管理员密码

无独立重置接口。可二选一：

- 重新执行 `init.sql` 中的管理员种子（会重置为默认口令，仅适用于可重建的库）；
- 或直连数据库更新 `users.password_hash`（bcrypt 哈希）后重新登录。

---

## 版本历史

完整版本变更记录请查阅 [VERSION.md](docs/VERSION.md)。

---

## 许可证与贡献

- **许可证**：MIT（见 `LICENSE`）。
- **仓库**：内部 Gitee 仓库（DevOps 项目）。提交规范遵循 Conventional Commits，版本号见 `backend/config/config.yaml` 的 `app.version`。
- **贡献流程**：从 `master` 切特性分支 → 提交（中文 Conventional Commits）→ 推送到内部仓库 → 发起合并评审。

---

**注意**：本项目为内部运维平台示例代码，在生产环境部署前请根据实际需求进行安全加固、密钥管理与性能优化。