AlphaFuturesPro/docs/cache-deployment-guide.md

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

一、部署步骤

1. 后端部署

编译 TypeScript

cd backend
npm run build

预期输出:

> alpha-futures-backend@1.0.0 build
> tsc

验证编译结果

检查以下文件是否生成：

• backend/dist/api/market.js - 包含新增的三个 API 路由
• backend/dist/services/cacheService.js - 包含新增的两个方法

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

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

重启后端服务

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

# 或者手动启动
npm start

2. 前端部署

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

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

---

二、功能验证

1. API 接口测试

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

测试批量缓存接口

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

预期响应:

{
  "success": true,
  "message": "批量缓存完成，成功: 25/30",
  "data": {
    "total": 30,
    "success": 25,
    "failed": 5,
    "klineCached": 50
  }
}

测试单合约缓存接口

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

预期响应:

{
  "success": true,
  "message": "合约 AU 缓存成功",
  "data": {
    "symbol": "AU",
    "detail": true,
    "klines": [
      { "period": "1H", "success": true },
      { "period": "1D", "success": true }
    ]
  }
}

测试缓存统计接口

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

预期响应:

{
  "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 数据验证

-- 查看缓存的数据
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 数据验证

# 连接到 Redis
redis-cli

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

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

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

---

四、常见问题排查

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

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

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

解决方案:

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

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

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

排查步骤:

1. 检查 MySQL 连接是否正常

# 查看后端日志
tail -f backend/logs/app.log | grep -i "mysql\|save"

2. 检查 market_data 表是否存在

SHOW TABLES LIKE 'market_data';

3. 检查表结构

DESCRIBE market_data;

问题3: 前端页面报错

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

排查步骤:

1. 清除 Vite 缓存

rm -rf node_modules/.vite

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

3. 检查是否存在语法错误

# 在 backend 目录编译时检查
npm run build

问题4: Redis 缓存未命中

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

排查步骤:

1. 检查 Redis 连接

redis-cli ping
# 应返回 PONG

2. 查看后端日志

tail -f backend/logs/app.log | grep -i "redis\|cache"

3. 检查 Redis 配置

# 查看 backend/src/config/database/redis.ts
cat backend/src/config/database/redis.ts

---

五、性能优化建议

1. 批量缓存优化

当前实现：串行处理合约

for (const contract of contracts) {
  await fetchMarketDetail(contract.code);
}

优化方案：并行处理（限制并发数）

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. 缓存预热定时任务

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

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

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

cacheWarmupJob.start();

3. 缓存监控

添加缓存命中率监控：

// 在 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. 后端回滚

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

2. 前端回滚

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

3. 数据库清理（可选）

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

# 清除 Redis 缓存
redis-cli FLUSHDB

---

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