AlphaFuturesPro/docs/cache-deployment-guide.md

# 数据缓存功能部署与操作指南

## 一、部署步骤

### 1. 后端部署

#### 编译 TypeScript

```bash
cd backend
npm run build
```

**预期输出**:
```
> alpha-futures-backend@1.0.0 build
> tsc
```

#### 验证编译结果

检查以下文件是否生成：
- `backend/dist/api/market.js` - 包含新增的三个 API 路由
- `backend/dist/services/cacheService.js` - 包含新增的两个方法

```bash
# 检查 API 路由
grep -n "cache-all\|cache/:symbol\|cache-stats" backend/dist/api/market.js

# 检查服务方法
grep -n "saveDirect\|getDBStats" backend/dist/services/cacheService.js
```

#### 重启后端服务

```bash
# 如果使用 pm2
pm2 restart alpha-futures-backend

# 或者手动启动
npm start
```

### 2. 前端部署

前端代码无需编译，直接生效。刷新浏览器页面即可。

```bash
# 如果是生产环境构建
npm run build
```

---

## 二、功能验证

### 1. API 接口测试

使用 curl 或 Postman 测试新增接口：

#### 测试批量缓存接口

```bash
curl -X POST http://localhost:3007/api/market/cache-all
```

**预期响应**:
```json
{
  "success": true,
  "message": "批量缓存完成，成功: 25/30",
  "data": {
    "total": 30,
    "success": 25,
    "failed": 5,
    "klineCached": 50
  }
}
```

#### 测试单合约缓存接口

```bash
curl -X POST http://localhost:3007/api/market/cache/AU \
  -H "Content-Type: application/json" \
  -d '{"periods": ["1H", "1D"]}'
```

**预期响应**:
```json
{
  "success": true,
  "message": "合约 AU 缓存成功",
  "data": {
    "symbol": "AU",
    "detail": true,
    "klines": [
      { "period": "1H", "success": true },
      { "period": "1D", "success": true }
    ]
  }
}
```

#### 测试缓存统计接口

```bash
curl http://localhost:3007/api/market/cache-stats
```

**预期响应**:
```json
{
  "success": true,
  "data": {
    "total": 150,
    "byType": {
      "detail": 50,
      "kline:1H": 30,
      "kline:1D": 30
    }
  }
}
```

### 2. 前端页面验证

1. 打开浏览器访问 `http://localhost:5173`（开发环境）
2. 进入 AdminConfig 页面
3. 切换到"数据缓存"页签
4. 验证以下元素是否存在：
   - [ ] 缓存统计卡片（4个统计项）
   - [ ] "一键获取数据"按钮
   - [ ] "缓存所有合约到数据库"按钮
   - [ ] 合约代码输入框和"缓存指定合约"按钮
   - [ ] 常用合约代码快捷按钮

---

## 三、数据库检查

### MySQL 数据验证

```sql
-- 查看缓存的数据
SELECT symbol, type, updated_at 
FROM market_data 
ORDER BY updated_at DESC 
LIMIT 20;

-- 按类型统计
SELECT type, COUNT(*) as count 
FROM market_data 
GROUP BY type;

-- 查看特定合约的缓存
SELECT * FROM market_data 
WHERE symbol = 'AU';
```

### Redis 数据验证

```bash
# 连接到 Redis
redis-cli

# 查看所有市场数据相关的 key
KEYS market:*

# 查看特定 key 的过期时间
TTL market:detail:AU

# 获取特定 key 的数据
GET market:detail:AU
```

---

## 四、常见问题排查

### 问题1: 批量缓存请求超时

**现象**: 点击"缓存所有合约到数据库"后长时间无响应

**原因**: 合约数量过多，请求处理时间过长

**解决方案**:
1. 检查后端日志查看进度
2. 分批处理（先缓存部分热门合约）
3. 增加超时时间配置

### 问题2: 数据库缓存未生效

**现象**: API 返回成功，但数据库中无数据

**排查步骤**:
1. 检查 MySQL 连接是否正常
```bash
# 查看后端日志
tail -f backend/logs/app.log | grep -i "mysql\|save"
```

2. 检查 market_data 表是否存在
```sql
SHOW TABLES LIKE 'market_data';
```

3. 检查表结构
```sql
DESCRIBE market_data;
```

### 问题3: 前端页面报错

**现象**: 打开 AdminConfig 页面显示空白或报错

**排查步骤**:
1. 清除 Vite 缓存
```bash
rm -rf node_modules/.vite
```

2. 检查浏览器控制台错误信息

3. 检查是否存在语法错误
```bash
# 在 backend 目录编译时检查
npm run build
```

### 问题4: Redis 缓存未命中

**现象**: 数据只存入 MySQL，Redis 中没有

**排查步骤**:
1. 检查 Redis 连接
```bash
redis-cli ping
# 应返回 PONG
```

2. 查看后端日志
```bash
tail -f backend/logs/app.log | grep -i "redis\|cache"
```

3. 检查 Redis 配置
```bash
# 查看 backend/src/config/database/redis.ts
cat backend/src/config/database/redis.ts
```

---

## 五、性能优化建议

### 1. 批量缓存优化

当前实现：串行处理合约
```typescript
for (const contract of contracts) {
  await fetchMarketDetail(contract.code);
}
```

优化方案：并行处理（限制并发数）
```typescript
const batchSize = 5;
for (let i = 0; i < contracts.length; i += batchSize) {
  const batch = contracts.slice(i, i + batchSize);
  await Promise.all(batch.map(c => fetchMarketDetail(c.code)));
  await delay(100);
}
```

### 2. 缓存预热定时任务

建议添加定时任务，在非交易时间自动预热缓存：

```typescript
// 每天早上 8:30 预热缓存
import { CronJob } from 'cron';

const cacheWarmupJob = new CronJob('30 8 * * *', async () => {
  console.log('开始缓存预热...');
  await warmupCache();
});

cacheWarmupJob.start();
```

### 3. 缓存监控

添加缓存命中率监控：

```typescript
// 在 cacheService 中添加统计
class CacheService {
  private stats = { hits: 0, misses: 0 };
  
  async get<T>(...) {
    // Redis 命中
    if (redisData) {
      this.stats.hits++;
      return JSON.parse(redisData);
    }
    
    // MySQL 命中
    if (mysqlData) {
      this.stats.hits++;
      return mysqlData;
    }
    
    // 未命中
    this.stats.misses++;
    return fetchFromSource();
  }
  
  getHitRate() {
    const total = this.stats.hits + this.stats.misses;
    return total === 0 ? 0 : (this.stats.hits / total * 100).toFixed(2);
  }
}
```

---

## 六、安全注意事项

1. **API 限流**: 批量缓存 API 可能会产生大量请求，建议添加限流
2. **权限控制**: 确保只有管理员可以访问缓存管理功能
3. **数据清理**: 定期清理过期的 Redis 缓存，避免内存溢出
4. **错误处理**: 批量操作时单个失败不应影响整体流程

---

## 七、回滚方案

如果需要回滚到之前的版本：

### 1. 后端回滚

```bash
cd backend
git checkout HEAD -- src/api/market.ts src/services/cacheService.ts
npm run build
pm2 restart alpha-futures-backend
```

### 2. 前端回滚

```bash
git checkout HEAD -- src/pages/admin/AdminConfig.jsx
```

### 3. 数据库清理（可选）

```sql
-- 清除所有缓存数据
TRUNCATE TABLE market_data;
```

```bash
# 清除 Redis 缓存
redis-cli FLUSHDB
```

---

**文档版本**: 1.0  
**最后更新**: 2026-03-02