quantKonwledge/20_Go迭代系统/部署运维指南.md

Go 量化知识迭代系统部署运维指南

返回：Go 迭代系统主文档 | 数据源接入指南

---

一、环境要求

组件	最低版本	推荐版本	说明
Go	1.21	1.23.5	已验证版本
Air	1.40	v1.64.5	已验证版本
Redis	6.0	7.x	缓存层
MySQL	8.0	8.0.x	历史数据存储
Docker	20.x	24.x	容器化部署（可选）
Linux	Ubuntu 20.04	Ubuntu 22.04	推荐操作系统

---

二、本地开发部署

2.1 克隆项目

git clone ssh://git@git.hk.hao.work:2222/hao/quant-system.git
cd quant-system

2.2 配置环境变量

cp .env.example .env
vim .env

.env 文件内容示例：

# 服务配置
PORT=9090
ENV=development
LOG_LEVEL=debug

# 数据库
MYSQL_DSN=root:password@tcp(localhost:3306)/quant_system?charset=utf8mb4&parseTime=True
REDIS_ADDR=localhost:6379
REDIS_PASSWORD=

# 数据源 API Keys
GLASSNODE_API_KEY=your_glassnode_api_key
COINGLASS_API_KEY=your_coinglass_api_key
CMC_API_KEY=your_cmc_api_key
FRED_API_KEY=your_fred_api_key

# 通知配置
FEISHU_WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/xxx
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
TELEGRAM_CHAT_ID=your_chat_id

# 知识库仓库路径
KNOWLEDGE_REPO_PATH=/home/ubuntu/quantKnowledge
KNOWLEDGE_REPO_REMOTE=ssh://git@git.hk.hao.work:2222/hao/quantKonwledge.git

# Binance（公开 API，无需 Key）
BINANCE_BASE_URL=https://api.binance.com
BINANCE_FUTURES_URL=https://fapi.binance.com

2.3 启动开发模式（Air 热重载）

# 安装依赖
go mod tidy

# 启动 Air 热重载
air

# 验证服务
curl http://localhost:9090/health

2.4 数据库初始化

# 创建数据库
mysql -u root -p -e "CREATE DATABASE quant_system CHARACTER SET utf8mb4;"

# 运行迁移
./scripts/init_db.sh

---

三、生产环境部署

3.1 编译二进制

# 编译 Linux amd64 二进制
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
  go build -ldflags="-w -s" -o quant-system ./cmd/server/main.go

# 查看文件大小（应约 7-10 MB）
ls -lh quant-system

3.2 Systemd 服务配置

# /etc/systemd/system/quant-system.service

[Unit]
Description=Quant Knowledge Iteration System
After=network.target mysql.service redis.service

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/opt/quant-system
EnvironmentFile=/opt/quant-system/.env
ExecStart=/opt/quant-system/quant-system
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

# 启用并启动服务
sudo systemctl enable quant-system
sudo systemctl start quant-system

# 查看状态
sudo systemctl status quant-system

# 查看日志
sudo journalctl -u quant-system -f

3.3 Docker Compose 部署

# docker-compose.yml

version: '3.8'

services:
  quant-system:
    build: .
    ports:
      - "9090:9090"
    environment:
      - ENV=production
      - PORT=9090
    env_file:
      - .env
    depends_on:
      - mysql
      - redis
    restart: always
    volumes:
      - /home/ubuntu/quantKnowledge:/knowledge:rw  # 挂载知识库目录
    networks:
      - quant-net

  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: quant_system
    volumes:
      - mysql_data:/var/lib/mysql
    networks:
      - quant-net

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    networks:
      - quant-net

volumes:
  mysql_data:
  redis_data:

networks:
  quant-net:
    driver: bridge

# 启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f quant-system

# 停止服务
docker-compose down

---

四、Makefile 命令参考

.PHONY: dev build test clean update-knowledge status migrate docker-up

# 开发模式（Air 热重载）
dev:
	air

# 编译
build:
	CGO_ENABLED=0 go build -o ./tmp/quant-system ./cmd/server/main.go

# 运行测试
test:
	go test ./... -v -cover

# 清理编译产物
clean:
	rm -rf tmp/

# 触发知识库更新
update-knowledge:
	curl -X POST http://localhost:9090/api/v1/knowledge/update

# 查看系统状态
status:
	curl http://localhost:9090/api/v1/status | jq .

# 查看数据源状态
datasources:
	curl http://localhost:9090/api/v1/datasources | jq .

# 数据库迁移
migrate:
	./scripts/init_db.sh

# Docker 部署
docker-up:
	docker-compose up -d

# Docker 停止
docker-down:
	docker-compose down

# 查看日志
logs:
	docker-compose logs -f quant-system

# 回填历史 K 线数据
backfill:
	./scripts/backfill_klines.sh

---

五、监控与告警

5.1 健康检查端点

# 基础健康检查
curl http://localhost:9090/health
# 返回：{"status":"ok","version":"0.1.1","uptime":"2h30m"}

# 详细状态
curl http://localhost:9090/api/v1/status
# 返回知识库状态、数据源状态、最后更新时间

# 数据源状态
curl http://localhost:9090/api/v1/datasources
# 返回所有数据源的在线状态和延迟

5.2 日志配置

系统使用 zap 结构化日志，支持 JSON 格式输出，便于日志聚合分析：

{
  "level": "info",
  "ts": "2026-03-06T10:10:00.000+0800",
  "caller": "signals/scorer.go:45",
  "msg": "信号检测完成",
  "symbol": "BTCUSDT",
  "timeframe": "10m",
  "score": 6,
  "signal_type": "strong_long",
  "ewo_value": 33.32,
  "ewo_direction": "green"
}

5.3 关键告警规则

告警条件	级别	通知方式
服务宕机	P0	飞书 + Telegram
数据源离线 > 5 分钟	P1	飞书
知识库更新失败	P1	飞书
强信号触发（评分 ≥ 5）	P2	飞书
API 响应延迟 > 5s	P2	日志记录

---

六、常见运维操作

6.1 手动触发知识库更新

# 更新所有模块
curl -X POST http://localhost:9090/api/v1/knowledge/update

# 更新指定模块
curl -X POST http://localhost:9090/api/v1/knowledge/update \
  -H "Content-Type: application/json" \
  -d '{"module": "12_信号系统优化", "symbol": "BTC"}'

6.2 手动触发信号检测

curl -X POST http://localhost:9090/api/v1/signals/detect \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTCUSDT",
    "timeframe": "10m",
    "notify": true
  }'

6.3 清除缓存

# 清除 Redis 缓存（谨慎操作）
redis-cli FLUSHDB

# 或通过 API 清除指定缓存
curl -X DELETE http://localhost:9090/api/v1/cache/BTCUSDT

6.4 回滚到上一版本

# 停止服务
sudo systemctl stop quant-system

# 回滚 Git
cd /opt/quant-system
git log --oneline -5  # 查看最近 5 次提交
git checkout <commit_hash>

# 重新编译
make build

# 重启服务
sudo systemctl start quant-system

---

参考资料

• [1] Go 官方文档：https://go.dev/doc/
• [2] Air 热重载配置：./Air热重载配置与迭代工作流程.md
• [3] 系统完整架构：./Go量化知识迭代系统完整架构.md
• [4] Docker Compose 文档：https://docs.docker.com/compose/
• [5] Systemd 服务管理：https://systemd.io/