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

> 返回：[Go 迭代系统主文档](./Go量化知识迭代系统完整架构.md) | [数据源接入指南](./数据源接入完整指南.md)

---

## 一、环境要求

| 组件 | 最低版本 | 推荐版本 | 说明 |
|------|---------|---------|------|
| 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 克隆项目

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

### 2.2 配置环境变量

```bash
cp .env.example .env
vim .env
```

`.env` 文件内容示例：

```bash
# 服务配置
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 热重载）

```bash
# 安装依赖
go mod tidy

# 启动 Air 热重载
air

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

### 2.4 数据库初始化

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

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

---

## 三、生产环境部署

### 3.1 编译二进制

```bash
# 编译 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 服务配置

```ini
# /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
```

```bash
# 启用并启动服务
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 部署

```yaml
# 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
```

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

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

# 停止服务
docker-compose down
```

---

## 四、Makefile 命令参考

```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 健康检查端点

```bash
# 基础健康检查
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 格式输出，便于日志聚合分析：

```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 手动触发知识库更新

```bash
# 更新所有模块
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 手动触发信号检测

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

### 6.3 清除缓存

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

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

### 6.4 回滚到上一版本

```bash
# 停止服务
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/