Initial commit: 宁夏智慧养殖监管平台
This commit is contained in:
shenquanyi
176
docs/baidu-map-license.md
Normal file
176
docs/baidu-map-license.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# 百度地图商用授权解决方案
|
||||
|
||||
## 问题描述
|
||||
|
||||
当前项目使用百度地图API时出现"未获得百度地图商用授权"的提示，这是因为使用了示例或无效的API密钥导致的。
|
||||
|
||||
## 解决方案
|
||||
|
||||
### 1. 获取百度地图API密钥
|
||||
|
||||
#### 1.1 申请流程
|
||||
1. 访问百度地图开放平台：http://lbsyun.baidu.com/
|
||||
2. 注册并登录百度账号
|
||||
3. 进入控制台：http://lbsyun.baidu.com/apiconsole/key
|
||||
4. 点击「创建应用」按钮
|
||||
5. 填写应用信息并获取API Key (AK)
|
||||
|
||||
#### 1.2 应用配置要求
|
||||
- **应用名称**：填写您的应用名称（如：宁夏智慧养殖监管平台）
|
||||
- **应用类型**：选择「浏览器端」
|
||||
- **启用服务**：勾选「地图」、「定位」等需要的服务
|
||||
- **Referer白名单**：
|
||||
- 开发环境：设置为 `*`（允许所有域名）
|
||||
- 生产环境：设置为您的具体域名（如：`https://yourdomain.com/*`）
|
||||
|
||||
#### 1.3 常见错误解决
|
||||
如果遇到「APP不存在，AK有误」错误：
|
||||
1. 检查API密钥是否正确复制
|
||||
2. 确认应用类型选择为「浏览器端」
|
||||
3. 检查Referer白名单配置
|
||||
4. 确认API密钥状态为「启用」
|
||||
|
||||
### 2. 配置API密钥
|
||||
|
||||
#### 方法一：直接修改配置文件（开发环境）
|
||||
|
||||
编辑 `frontend/src/config/env.js` 文件：
|
||||
|
||||
```javascript
|
||||
export const BAIDU_MAP_CONFIG = {
|
||||
// 替换为您申请的真实API密钥
|
||||
apiKey: 'YOUR_REAL_API_KEY_HERE',
|
||||
// ... 其他配置
|
||||
};
|
||||
```
|
||||
|
||||
#### 方法二：使用环境变量（推荐）
|
||||
|
||||
1. 在项目根目录创建 `.env.local` 文件：
|
||||
```
|
||||
VITE_BAIDU_MAP_API_KEY=YOUR_REAL_API_KEY_HERE
|
||||
```
|
||||
|
||||
2. 修改 `frontend/src/config/env.js`：
|
||||
```javascript
|
||||
export const BAIDU_MAP_CONFIG = {
|
||||
apiKey: import.meta.env.VITE_BAIDU_MAP_API_KEY || 'fallback_key',
|
||||
// ... 其他配置
|
||||
};
|
||||
```
|
||||
|
||||
### 3. 商用授权说明
|
||||
|
||||
#### 免费配额
|
||||
- 每日调用量：10万次
|
||||
- 并发请求：无限制
|
||||
- 适用于：个人开发、测试、小型项目
|
||||
|
||||
#### 商用授权
|
||||
如果项目需要商用或超出免费配额，需要：
|
||||
|
||||
1. **联系百度销售**：
|
||||
- 电话：400-890-0065
|
||||
- 邮箱：lbsyun@baidu.com
|
||||
|
||||
2. **购买商用授权**：
|
||||
- 根据调用量选择合适的套餐
|
||||
- 签署商用授权协议
|
||||
- 获得商用版API密钥
|
||||
|
||||
3. **配置商用密钥**：
|
||||
- 将商用API密钥替换到配置文件中
|
||||
- 更新Referer白名单为生产域名
|
||||
|
||||
### 4. 安全建议
|
||||
|
||||
1. **密钥保护**：
|
||||
- 不要将API密钥提交到公开的代码仓库
|
||||
- 使用环境变量存储敏感信息
|
||||
- 定期更换API密钥
|
||||
|
||||
2. **域名限制**：
|
||||
- 在百度控制台设置准确的Referer白名单
|
||||
- 避免使用通配符 `*`（仅开发环境使用）
|
||||
|
||||
3. **使用监控**：
|
||||
- 定期检查API调用量
|
||||
- 设置调用量告警
|
||||
- 监控异常调用
|
||||
|
||||
### 5. 故障排除
|
||||
|
||||
#### 常见错误及解决方法
|
||||
|
||||
1. **"Invalid API key"**
|
||||
- 检查API密钥是否正确
|
||||
- 确认应用类型为"浏览器端"
|
||||
- 检查Referer白名单设置
|
||||
|
||||
2. **"Quota exceeded"**
|
||||
- 检查当日调用量是否超限
|
||||
- 考虑升级到商用版本
|
||||
- 优化代码减少不必要的API调用
|
||||
|
||||
3. **"Service not enabled"**
|
||||
- 在百度控制台启用"地图API"服务
|
||||
- 确认应用状态为"正常"
|
||||
|
||||
### 当前问题状态
|
||||
|
||||
✅ **API密钥已配置**：已成功配置有效的百度地图API密钥，地图服务正常工作
|
||||
|
||||
### 7. 立即解决步骤
|
||||
|
||||
#### 步骤1：申请有效的API密钥
|
||||
1. 访问：http://lbsyun.baidu.com/apiconsole/key
|
||||
2. 登录百度账号
|
||||
3. 点击「创建应用」
|
||||
4. 配置应用信息：
|
||||
- 应用名称：宁夏智慧养殖监管平台
|
||||
- 应用类型：**浏览器端**（重要！）
|
||||
- 启用服务：勾选「地图」
|
||||
- Referer白名单：设置为 `*`（开发环境）
|
||||
5. 创建成功后复制API密钥
|
||||
|
||||
#### 步骤2：配置API密钥
|
||||
有两种配置方式：
|
||||
|
||||
**方式一：修改环境变量文件（推荐）**
|
||||
```bash
|
||||
# 编辑 frontend/.env 文件
|
||||
VITE_BAIDU_MAP_API_KEY=您申请的真实API密钥
|
||||
```
|
||||
|
||||
**方式二：直接修改配置文件**
|
||||
```javascript
|
||||
// 编辑 frontend/src/config/env.js
|
||||
apiKey: '您申请的真实API密钥'
|
||||
```
|
||||
|
||||
#### 步骤3：重启开发服务器
|
||||
```bash
|
||||
cd frontend
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### 8. 项目状态
|
||||
|
||||
- ✅ 已配置有效的API密钥：`3AN3VahoqaXUs32U8luXD2Dwn86KK5B7`
|
||||
- ✅ 前端服务器正常运行：http://localhost:5301/
|
||||
- ✅ 后端API服务正常：http://localhost:5350/api/
|
||||
- ✅ 百度地图服务可正常使用
|
||||
- ✅ 已配置环境变量支持
|
||||
- ✅ 已添加详细的申请指导
|
||||
- ✅ 已配置安全的.gitignore规则
|
||||
|
||||
### 9. 重要提醒
|
||||
|
||||
1. **必须申请真实API密钥**：测试密钥无法正常使用
|
||||
2. **应用类型必须选择「浏览器端」**：这是最常见的错误原因
|
||||
3. **保护API密钥安全**：不要将真实密钥提交到代码仓库
|
||||
4. **商用需要授权**：如用于商业用途，需要联系百度申请商用授权
|
||||
|
||||
---
|
||||
|
||||
**注意**：当前使用的是临时测试密钥，仅供开发调试使用，请尽快申请正式的API密钥。
|
||||
305
docs/performance-monitoring.md
Normal file
305
docs/performance-monitoring.md
Normal file
@@ -0,0 +1,305 @@
|
||||
# 性能监控系统文档
|
||||
|
||||
## 概述
|
||||
|
||||
性能监控系统是一个全面的监控工具，用于实时跟踪和分析应用程序的性能指标。它包括以下主要功能：
|
||||
|
||||
- **系统资源监控**：CPU、内存和磁盘使用情况
|
||||
- **数据库性能监控**：连接池状态、慢查询识别和查询模式分析
|
||||
- **API性能监控**：请求响应时间、错误率和请求频率
|
||||
- **警报系统**：基于可配置阈值的性能警报
|
||||
- **历史数据**：性能指标的历史记录和趋势分析
|
||||
- **可视化界面**：直观的性能指标展示
|
||||
|
||||
## 系统架构
|
||||
|
||||
性能监控系统由以下组件组成：
|
||||
|
||||
1. **核心监控引擎**：`performance-monitor.js`
|
||||
2. **API中间件**：`performance-middleware.js`
|
||||
3. **配置模块**：`performance-config.js`
|
||||
4. **API路由**：`performance-routes.js`
|
||||
5. **前端组件**：`PerformanceMonitor.vue`
|
||||
|
||||
## 安装和配置
|
||||
|
||||
### 后端集成
|
||||
|
||||
1. 在Express应用中引入性能监控系统：
|
||||
|
||||
```javascript
|
||||
const { initPerformanceMonitoring, getPerformanceRoutes } = require('./backend/config/performance-config');
|
||||
|
||||
// 初始化性能监控系统
|
||||
const performanceMonitor = initPerformanceMonitoring(app, {
|
||||
autoStart: true,
|
||||
interval: 60000, // 监控间隔（毫秒）
|
||||
logToConsole: false,
|
||||
thresholds: {
|
||||
system: {
|
||||
cpuUsage: 80, // CPU使用率阈值（百分比）
|
||||
memoryUsage: 80, // 内存使用率阈值（百分比）
|
||||
diskUsage: 80 // 磁盘使用率阈值（百分比）
|
||||
},
|
||||
database: {
|
||||
connectionPoolUtilization: 80, // 连接池利用率阈值（百分比）
|
||||
slowQueryCount: 5, // 慢查询数量阈值
|
||||
errorRate: 5 // 错误率阈值（百分比）
|
||||
},
|
||||
api: {
|
||||
responseTime: 500, // API响应时间阈值（毫秒）
|
||||
errorRate: 5, // API错误率阈值（百分比）
|
||||
requestRate: 1000 // 每分钟请求数阈值
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
// 注册性能监控路由
|
||||
app.use('/api/performance', getPerformanceRoutes());
|
||||
```
|
||||
|
||||
### 前端集成
|
||||
|
||||
1. 在Vue应用中引入性能监控组件：
|
||||
|
||||
```javascript
|
||||
import PerformanceMonitor from './components/PerformanceMonitor.vue';
|
||||
|
||||
// 在Vue组件中使用
|
||||
export default {
|
||||
components: {
|
||||
PerformanceMonitor
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. 在模板中使用组件：
|
||||
|
||||
```html
|
||||
<template>
|
||||
<div>
|
||||
<performance-monitor />
|
||||
</div>
|
||||
</template>
|
||||
```
|
||||
|
||||
## API参考
|
||||
|
||||
### 后端API
|
||||
|
||||
#### 性能监控核心API
|
||||
|
||||
```javascript
|
||||
const { performanceMonitor } = require('./backend/utils/performance-monitor');
|
||||
|
||||
// 启动监控
|
||||
performanceMonitor.startMonitoring(60000); // 参数：监控间隔（毫秒）
|
||||
|
||||
// 停止监控
|
||||
performanceMonitor.stopMonitoring();
|
||||
|
||||
// 获取所有性能指标
|
||||
const metrics = await performanceMonitor.getAllMetrics();
|
||||
|
||||
// 获取系统资源指标
|
||||
const systemMetrics = performanceMonitor.getSystemMetrics();
|
||||
|
||||
// 获取数据库性能指标
|
||||
const dbMetrics = await performanceMonitor.getDatabaseMetrics();
|
||||
|
||||
// 获取API性能指标
|
||||
const apiStats = performanceMonitor.getApiStats();
|
||||
|
||||
// 设置警报阈值
|
||||
performanceMonitor.setAlertThresholds({
|
||||
system: { cpuUsage: 75 },
|
||||
api: { responseTime: 300 }
|
||||
});
|
||||
|
||||
// 获取警报阈值
|
||||
const thresholds = performanceMonitor.getAlertThresholds();
|
||||
|
||||
// 重置API统计
|
||||
performanceMonitor.resetApiStats();
|
||||
```
|
||||
|
||||
#### HTTP API端点
|
||||
|
||||
| 端点 | 方法 | 描述 |
|
||||
|------|------|------|
|
||||
| `/api/performance/metrics` | GET | 获取所有性能指标 |
|
||||
| `/api/performance/system` | GET | 获取系统资源指标 |
|
||||
| `/api/performance/database` | GET | 获取数据库性能指标 |
|
||||
| `/api/performance/api` | GET | 获取API性能指标 |
|
||||
| `/api/performance/start` | POST | 启动性能监控 |
|
||||
| `/api/performance/stop` | POST | 停止性能监控 |
|
||||
| `/api/performance/status` | GET | 获取监控状态 |
|
||||
| `/api/performance/thresholds` | GET | 获取警报阈值 |
|
||||
| `/api/performance/thresholds` | POST | 设置警报阈值 |
|
||||
| `/api/performance/api/reset` | POST | 重置API统计 |
|
||||
|
||||
### 事件系统
|
||||
|
||||
性能监控系统提供了一个事件系统，可以监听各种性能相关的事件：
|
||||
|
||||
```javascript
|
||||
const { perfEvents } = require('./backend/utils/performance-monitor');
|
||||
|
||||
// 监控启动事件
|
||||
perfEvents.on('monitoringStarted', (data) => {
|
||||
console.log(`性能监控已启动，间隔: ${data.interval}ms`);
|
||||
});
|
||||
|
||||
// 监控停止事件
|
||||
perfEvents.on('monitoringStopped', () => {
|
||||
console.log('性能监控已停止');
|
||||
});
|
||||
|
||||
// 数据库状态变化事件
|
||||
perfEvents.on('databaseStatus', (status) => {
|
||||
console.log('数据库状态更新:', status);
|
||||
});
|
||||
|
||||
// 数据库错误事件
|
||||
perfEvents.on('databaseError', (error) => {
|
||||
console.error('数据库错误:', error);
|
||||
});
|
||||
|
||||
// 慢查询事件
|
||||
perfEvents.on('slowQuery', (query) => {
|
||||
console.warn(`检测到慢查询: ${query.duration}ms - ${query.query}`);
|
||||
});
|
||||
|
||||
// API错误事件
|
||||
perfEvents.on('apiError', (data) => {
|
||||
console.error(`API错误: ${data.method} ${data.path} - ${data.error}`);
|
||||
});
|
||||
|
||||
// 慢API请求事件
|
||||
perfEvents.on('slowApiRequest', (data) => {
|
||||
console.warn(`慢API请求: ${data.endpoint} - ${data.duration}ms`);
|
||||
});
|
||||
|
||||
// 高CPU使用率事件
|
||||
perfEvents.on('highCpuUsage', (data) => {
|
||||
console.warn(`高CPU使用率: ${data.usage}% (阈值: ${data.threshold}%)`);
|
||||
});
|
||||
|
||||
// 高内存使用率事件
|
||||
perfEvents.on('highMemoryUsage', (data) => {
|
||||
console.warn(`高内存使用率: ${data.usage}% (阈值: ${data.threshold}%)`);
|
||||
});
|
||||
|
||||
// 高磁盘使用率事件
|
||||
perfEvents.on('highDiskUsage', (data) => {
|
||||
console.warn(`高磁盘使用率: ${data.usage}% (阈值: ${data.threshold}%)`);
|
||||
});
|
||||
```
|
||||
|
||||
## 前端组件
|
||||
|
||||
`PerformanceMonitor.vue` 组件提供了一个直观的界面，用于展示性能指标和配置警报阈值。它包括以下功能：
|
||||
|
||||
- 系统资源监控面板（CPU、内存、磁盘）
|
||||
- 数据库性能监控面板（连接池、慢查询、查询模式）
|
||||
- API性能监控面板（请求统计、响应时间、错误率）
|
||||
- 警报配置面板（设置各项指标的警报阈值）
|
||||
- 实时图表展示历史趋势
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 性能监控
|
||||
|
||||
1. **设置合适的监控间隔**：根据应用负载和服务器资源选择合适的监控间隔。高负载系统可能需要更长的间隔（如5分钟），而关键系统可能需要更短的间隔（如30秒）。
|
||||
|
||||
2. **配置合理的警报阈值**：根据系统特性和业务需求设置合理的警报阈值。过低的阈值可能导致过多的警报，过高的阈值可能导致问题被忽略。
|
||||
|
||||
3. **定期分析性能数据**：定期查看性能监控数据，识别潜在问题和优化机会。
|
||||
|
||||
### 数据库优化
|
||||
|
||||
1. **关注慢查询**：定期检查慢查询列表，优化频繁出现的慢查询。
|
||||
|
||||
2. **监控连接池**：保持合理的连接池大小，避免连接池耗尽或过度分配。
|
||||
|
||||
3. **分析查询模式**：利用查询模式统计，识别频繁执行的查询，考虑添加索引或优化查询结构。
|
||||
|
||||
### API优化
|
||||
|
||||
1. **关注慢响应API**：优化响应时间超过阈值的API端点。
|
||||
|
||||
2. **监控错误率**：保持低错误率，及时修复错误率高的API端点。
|
||||
|
||||
3. **平衡请求负载**：避免单个端点过度负载，考虑负载均衡或缓存策略。
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
1. **监控系统占用过多资源**：
|
||||
- 增加监控间隔
|
||||
- 减少收集的指标
|
||||
- 限制历史数据存储量
|
||||
|
||||
2. **警报过多**：
|
||||
- 调整警报阈值
|
||||
- 合并相似警报
|
||||
- 实现警报抑制机制
|
||||
|
||||
3. **数据不准确**：
|
||||
- 检查监控代码是否正确集成
|
||||
- 验证数据源是否可靠
|
||||
- 确保时间同步
|
||||
|
||||
### 日志文件
|
||||
|
||||
性能监控系统会在 `logs/performance` 目录下生成以下日志文件：
|
||||
|
||||
- `system-YYYY-MM-DD.log`：系统资源监控日志
|
||||
- `database-YYYY-MM-DD.log`：数据库性能监控日志
|
||||
- `system-error-YYYY-MM-DD.log`：系统监控错误日志
|
||||
- `database-error-YYYY-MM-DD.log`：数据库监控错误日志
|
||||
|
||||
## 扩展和定制
|
||||
|
||||
### 添加新的监控指标
|
||||
|
||||
要添加新的监控指标，需要修改以下文件：
|
||||
|
||||
1. `performance-monitor.js`：添加新的指标收集和处理逻辑
|
||||
2. `performance-routes.js`：添加新的API端点
|
||||
3. `PerformanceMonitor.vue`：添加新的UI组件展示指标
|
||||
|
||||
### 集成外部监控系统
|
||||
|
||||
性能监控系统可以与外部监控系统集成，如Prometheus、Grafana或ELK堆栈：
|
||||
|
||||
```javascript
|
||||
// 示例：将性能指标导出到Prometheus
|
||||
const client = require('prom-client');
|
||||
const register = new client.Registry();
|
||||
|
||||
// 创建指标
|
||||
const cpuGauge = new client.Gauge({
|
||||
name: 'cpu_usage_percent',
|
||||
help: 'CPU使用率百分比',
|
||||
registers: [register]
|
||||
});
|
||||
|
||||
// 更新指标
|
||||
perfEvents.on('systemMetrics', (metrics) => {
|
||||
cpuGauge.set(metrics.cpuUsage.usage);
|
||||
});
|
||||
|
||||
// 暴露指标端点
|
||||
app.get('/metrics', (req, res) => {
|
||||
res.set('Content-Type', register.contentType);
|
||||
res.end(register.metrics());
|
||||
});
|
||||
```
|
||||
|
||||
## 结论
|
||||
|
||||
性能监控系统提供了全面的工具，用于监控和优化应用程序的性能。通过实时跟踪系统资源、数据库性能和API响应时间，可以及早发现潜在问题，提高应用程序的可靠性和用户体验。
|
||||
|
||||
定期查看性能指标，设置合理的警报阈值，并根据性能数据进行优化，可以显著提高应用程序的性能和稳定性。
|
||||
Reference in New Issue
Block a user