hao/quantKonwledge
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动

feat: 新增第20模块 Go+Air量化知识迭代系统完整文档

浏览代码 
- 新增 20_Go迭代系统/README.md：模块索引与实际试运行记录
- 新增 Go量化知识迭代系统完整架构.md：完整目录结构、核心模块详解、API设计、数据流架构图
- 新增 Air热重载配置与迭代工作流程.md：安装步骤、.air.toml配置、日常迭代流程
- 新增 数据源接入完整指南.md：12个数据源（Binance/OKX/Bybit/Deribit/Glassnode/CoinGlass/DeFiLlama/TheGraph/CMC/FRED等）
- 新增 部署运维指南.md：本地开发、生产部署、Docker Compose、监控告警

已验证：Go 1.23.5 + Air v1.64.5 热重载 < 1秒，API接口全部正常
这个提交包含在：
Manus Quant Agent
2026-03-06 00:47:51 -05:00
父节点 235c1f6635
当前提交 2a8b8413af
共修改 5 个文件，包含 1973 行新增和 0 行删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件

230
20_Go迭代系统/Air热重载配置与迭代工作流程.md 普通文件
查看文件

@@ -0,0 +1,230 @@
# Air 热重载配置与迭代工作流程
> 返回：[Go 迭代系统主文档](./Go量化知识迭代系统完整架构.md) | [Wiki 主索引](../wiki/README.md)
>
> **已验证**：2026-03-06 实际测试，Air v1.64.5 + Go 1.23.5，热重载响应时间 **< 1 秒**。
---
## 一、Air 简介
**Air** 是 Go 语言最流行的热重载工具（GitHub Stars 23.1k+），核心功能是监听文件变化，自动重新编译并重启服务，彻底解决 Go 开发中"改一行代码就要手动 `go build && ./server`"的痛点。
**与其他语言热重载对比**：
| 语言 | 热重载工具 | 重启速度 | 备注 |
|------|----------|---------|------|
| Go + Air | Air v1.64.5 | **< 1 秒** | 编译型，速度极快 |
| Node.js | nodemon | < 0.5 秒 | 解释型，无需编译 |
| Python | uvicorn --reload | < 0.5 秒 | 解释型，无需编译 |
| Java | Spring DevTools | 3-10 秒 | JVM 启动慢 |
---
## 二、安装步骤
### 2.1 安装 Go
```bash
# 下载 Go 1.23.5（Linux amd64）
wget https://go.dev/dl/go1.23.5.linux-amd64.tar.gz -O /tmp/go.tar.gz
# 解压到 /usr/local
sudo tar -C /usr/local -xzf /tmp/go.tar.gz
# 配置环境变量（写入 ~/.bashrc）
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
echo 'export GOPATH=$HOME/go' >> ~/.bashrc
echo 'export PATH=$PATH:$GOPATH/bin' >> ~/.bashrc
source ~/.bashrc
# 验证
go version
# 输出：go version go1.23.5 linux/amd64
```
### 2.2 安装 Air
```bash
# 方式一：go install（推荐）
go install github.com/air-verse/air@latest
# 方式二：curl 脚本
curl -sSfL https://raw.githubusercontent.com/air-verse/air/master/install.sh | sh -s -- -b $(go env GOPATH)/bin
# 验证
air -v
# 输出：v1.64.5, built with Go go1.25.8
```
---
## 三、.air.toml 完整配置说明
```toml
# Air v1.64.5 热重载配置
# 量化知识迭代系统 - QuantSystem
root = "."
tmp_dir = "tmp"
[build]
# 编译命令（每次文件变化后执行）
cmd = "go build -o ./tmp/quant-system ./cmd/server/main.go"
# 编译输出的二进制文件路径
bin = "tmp/quant-system"
# 启动命令（支持注入环境变量）
full_bin = "PORT=9090 ./tmp/quant-system"
# 监听的文件扩展名（包含 .md 以便知识库更新时触发）
include_ext = ["go", "tpl", "tmpl", "html", "toml", "yaml", "yml", "json", "md"]
# 排除的目录（不监听变化，避免无限循环）
exclude_dir = ["tmp", "vendor", "testdata", "node_modules", ".git"]
# 排除测试文件（测试文件变化不触发重启）
exclude_regex = ["_test\\.go"]
# 文件变化后等待 1 秒再重编译（防止连续保存触发多次）
delay = 1000
# 构建失败时不停止旧进程（保持服务可用）
stop_on_error = false
# 构建错误日志路径
log = "tmp/build-errors.log"
[log]
# 显示时间戳
time = true
# 显示所有日志（包括 watcher 日志）
main_only = false
[color]
# 各类日志颜色（ANSI 颜色）
main = "magenta"
watcher = "cyan"
build = "yellow"
runner = "green"
[misc]
# 退出时清理 tmp 目录
clean_on_exit = true
```
### 关键配置项说明
| 配置项 | 说明 | 量化系统推荐值 |
|--------|------|--------------|
| `delay` | 文件变化后等待时间（ms）| 1000（防止连续保存）|
| `exclude_dir` | 排除目录 | 必须排除 `tmp`，否则死循环 |
| `include_ext` | 监听扩展名 | 加入 `md` 以便文档更新触发 |
| `stop_on_error` | 编译失败时保留旧进程 | `false`（保持服务可用）|
| `full_bin` | 启动命令 | 注入 `PORT` 等环境变量 |
---
## 四、日常迭代工作流程
### 4.1 标准开发流程
```
1. 启动 Air
$ cd quant-system && air
2. 修改 .go 文件（例如新增指标计算逻辑）
→ Air 自动检测到文件变化
→ 自动执行 go build
→ 编译成功后自动重启服务
→ 整个过程 < 1 秒
3. 验证功能
$ curl http://localhost:9090/api/v1/indicators/calculate \
-d '{"symbol":"BTCUSDT","timeframe":"10m","indicators":["EWO"]}'
4. 功能正常 → 提交
$ git add -A && git commit -m "feat: 新增 EWO 相对阈值计算" && git push
```
### 4.2 知识库 MD 文档迭代流程
```
触发方式（三种）：
A. 定时触发（cron，每 10 分钟）
B. API 触发：POST /api/v1/knowledge/update
C. 手动脚本：./scripts/update_knowledge.sh
执行流程：
1. updater/knowledge_updater.go 调度
2. 从数据源拉取最新数据
3. 格式化为 Markdown 表格
4. 定位 quantKonwledge 仓库对应文档
5. 更新文档中 <!-- AUTO_UPDATE_START --> 到 <!-- AUTO_UPDATE_END --> 之间的内容
6. git add + commit + push 到 quantKonwledge 仓库
7. 飞书通知：「知识库已更新」
MD 文档中的自动更新标记示例：
<!-- AUTO_UPDATE_START: btc_ewo_status -->
| 更新时间 | EWO 值 | 方向 | 信号评分 |
|---------|-------|------|---------|
| 2026-03-06 10:10 | +33.32 | 绿(多头) | +6 |
<!-- AUTO_UPDATE_END: btc_ewo_status -->
```
### 4.3 新增数据源迭代流程
```
1. 在 internal/datasource/ 新建目录（如 internal/datasource/coinbase/）
2. 实现 DataSource 接口（interface.go 中定义）
3. 在 datasource/manager.go 注册新数据源
4. Air 自动检测到文件变化，重编译重启
5. 验证：GET /api/v1/datasources 查看新数据源状态
6. 编写对应 MD 文档：20_Go迭代系统/数据源接入完整指南.md
7. 提交到两个仓库：quant-system + quantKonwledge
```
---
## 五、常见问题与解决方案
| 问题 | 原因 | 解决方案 |
|------|------|---------|
| Air 启动后无输出 | PATH 未配置 | `export PATH=$PATH:$HOME/go/bin` |
| 端口被占用 | 旧进程未退出 | `pkill -f quant-system` |
| 编译后立即退出 | 代码有 panic | 查看 `tmp/build-errors.log` |
| 文件变化未触发重载 | 扩展名不在 `include_ext` | 检查 `.air.toml` 配置 |
| 无限循环重编译 | `tmp/` 未排除 | 确认 `exclude_dir` 包含 `"tmp"` |
| 热重载后 API 返回旧数据 | Redis 缓存未清除 | 重启时自动清除，或手动 `redis-cli FLUSHDB` |
---
## 六、与 tradehk 的协同关系
本系统与 `tradehk` 仓库的协同方式：
```
tradehk（TypeScript 前端）
↓ 参考指标逻辑
quant-system（Go 后端）
↓ 计算结果写入
quantKonwledge（MD 知识库）
↓ 文档反哺
tradehk 开发优化
```
**具体协同点**：
- `tradehk/client/src/lib/indicators.ts` → `quant-system/internal/indicators/` 的 Go 实现参考
- `tradehk/server/_core/marketEngine.ts` → `quant-system/internal/signals/ewo_detector.go` 的逻辑参考
- `tradehk` 发出的飞书通知格式 → `quant-system/internal/notifier/formatter.go` 保持一致
---
## 参考资料
- [1] Air 官方文档：https://github.com/air-verse/air
- [2] Go 官方下载：https://go.dev/dl/
- [3] Go 迭代系统完整架构：`./Go量化知识迭代系统完整架构.md`
- [4] tradehk 部署运维指南：`../wiki/tradehk/部署运维指南.md`