wiki/quant/freqtrade-deploy-guide.md

# Freqtrade 实盘部署全流程

从零部署 Freqtrade 交易机器人到 Vultr 服务器，运行 OKX USDT-M 永续合约实盘交易。

---

## 1. 服务器信息

| 项目 | 详情 |
|------|------|
| 服务商 | Vultr |
| IP | `104.156.239.5` |
| 系统 | Ubuntu 22.04 |
| 配置 | 2 vCPU / 2GB RAM / 61GB SSD |
| 部署路径 | `/opt/freqtrade/` |
| SSH 用户 | `root` |
| SSH 密钥 | 本机 `~/.ssh/id_rsa` |
| 跳板 | 通过阿里云 ecs 跳板（ProxyJump） |

### SSH 配置

在本机 `~/.ssh/config` 中添加：

```
Host vultr
  HostName 104.156.239.5
  User root
  IdentityFile ~/.ssh/id_rsa
  IdentitiesOnly yes
  ProxyJump ecs
```

连接命令：`ssh vultr`

### 端口

| 端口 | 用途 |
|------|------|
| 22 | SSH |
| 8080 | Freqtrade API Server / freqUI |

---

## 2. 前置依赖安装

```bash
# 更新系统
ssh vultr "apt update && apt install -y software-properties-common"

# 安装 Python 3.12（Ubuntu 22.04 默认 3.10 不满足 freqtrade >=3.11）
ssh vultr "add-apt-repository -y ppa:deadsnakes/ppa && apt install -y python3.12 python3.12-venv python3.12-dev"

# 安装构建依赖
ssh vultr "apt install -y build-essential git curl"

# 配置防火墙
ssh vultr "ufw allow 22/tcp && ufw allow 8080/tcp"
```

---

## 3. 部署 Freqtrade

### 3.1 克隆仓库

```bash
# 方式一：从 Gitea 克隆（推荐）
ssh vultr "git clone https://git.looq.fun/liam/freqtrade-deploy.git /opt/freqtrade"

# 方式二：从本机 scp 推送
scp -o ProxyJump=ecs -r /root/agents/freqtrade vultr:/opt/freqtrade
```

### 3.2 创建虚拟环境并安装

```bash
ssh vultr "cd /opt/freqtrade && python3.12 -m venv .venv && .venv/bin/pip install -e ."
```

### 3.3 安装 freqUI

```bash
ssh vultr "cd /opt/freqtrade && .venv/bin/freqtrade install-ui"
```

---

## 4. 配置

### 4.1 部署策略文件

将策略文件推送到服务器：

```bash
scp -o ProxyJump=ecs user_data/strategies/multi_asset_channel_breakout_v5.py \
    vultr:/opt/freqtrade/user_data/strategies/
```

### 4.2 配置 config.json

在 `/opt/freqtrade/user_data/config.json` 中配置以下关键项：

```json
{
    "max_open_trades": 2,
    "stake_currency": "USDT",
    "stake_amount": "unlimited",
    "tradable_balance_ratio": 0.99,
    "dry_run": false,
    "timeframe": "15m",
    "stoploss": -0.80,
    "trading_mode": "futures",
    "margin_mode": "isolated",
    "exchange": {
        "name": "okx",
        "key": "e756108d-f14c-4777-8351-cd989f389dd2",
        "secret": "BC4579AEE9816ED4A38218910B6EC278",
        "password": "30l9L666.",
        "ccxt_config": {"hostname": "www.okx.cab"},
        "ccxt_async_config": {"hostname": "www.okx.cab"},
        "pair_whitelist": ["BTC/USDT:USDT", "ETH/USDT:USDT"]
    },
    "pairlists": [{"method": "StaticPairList"}],
    "api_server": {
        "enabled": true,
        "listen_ip_address": "0.0.0.0",
        "listen_port": 8080,
        "username": "liam",
        "password": "30l9L666"
    },
    "webhook": {
        "enabled": true,
        "url": "https://open.feishu.cn/open-apis/bot/v2/hook/2b1bc9a6-b470-447f-b783-1b253dcf522c"
    },
    "strategy": "MultiAssetChannelBreakoutV5",
    "strategy_path": "user_data/strategies/",
    "initial_state": "running"
}
```

**OKX API Key 说明：**
- key: `e756108d-f14c-4777-8351-cd989f389dd2`
- secret: `BC4579AEE9816ED4A38218910B6EC278`
- password: `30l9L666.`
- hostname: `www.okx.cab`（OKX 国内加速域名，非 `www.okx.com`）
- 该 key 无 IP 限制（`ip: "0"`），任何服务器都能用

**freqUI 登录：**
- 地址：`http://104.156.239.5:8080/`
- 用户名：`liam`
- 密码：`30l9L666`

---

## 5. Systemd 服务

### 5.1 创建服务文件

```bash
ssh vultr "cat > /etc/systemd/system/freqtrade.service << 'EOF'
[Unit]
Description=Freqtrade Trading Bot
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/freqtrade
ExecStart=/opt/freqtrade/.venv/bin/freqtrade trade -c user_data/config.json
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF"
```

### 5.2 启用并启动

```bash
ssh vultr "systemctl daemon-reload && systemctl enable freqtrade && systemctl start freqtrade"
```

---

## 6. 验证部署

```bash
# 1. 检查服务状态
ssh vultr "systemctl status freqtrade --no-pager"

# 2. 检查 API 响应
curl -s http://104.156.239.5:8080/api/v1/ping
# 应返回: {"status":"pong"}

# 3. 检查策略加载
ssh vultr "journalctl -u freqtrade --no-pager -n 30 | grep -E 'strategy|timeframe|RUNNING'"

# 4. 检查交易对白名单
ssh vultr "journalctl -u freqtrade --no-pager | grep 'Whitelist with'"

# 5. 访问 Web UI
open http://104.156.239.5:8080/
```

---

## 7. 运维命令

```bash
# 查看服务状态
ssh vultr "systemctl status freqtrade --no-pager"

# 查看实时日志
ssh vultr "journalctl -u freqtrade.service -f"

# 查看最近 50 行日志
ssh vultr "journalctl -u freqtrade.service --no-pager -n 50"

# 重启服务（部署新策略或修改配置后）
ssh vultr "systemctl restart freqtrade"

# 停止服务
ssh vultr "systemctl stop freqtrade"

# 查看交易记录（SQLite）
ssh vultr "cd /opt/freqtrade && python3 -c \"
import sqlite3
conn = sqlite3.connect('tradesv3.sqlite')
conn.row_factory = sqlite3.Row
rows = conn.execute('SELECT id,pair,open_rate,close_rate,close_profit_abs,exit_reason FROM trades ORDER BY id').fetchall()
for r in rows:
    print(dict(r))
conn.close()
\""
```

---

## 8. 当前线上配置摘要

| 配置项 | 值 |
|--------|------|
| 策略 | MultiAssetChannelBreakoutV5 |
| 交易所 | OKX |
| 交易模式 | USDT-M 永续合约 / 逐仓 |
| 币对 | BTC/USDT, ETH/USDT |
| 时间周期 | 15m |
| 杠杆 | 10x（策略内固定） |
| 最大持仓 | 2 |
| 硬止损 | -80%（config 与策略 `stoploss=-0.80` 一致；10x 杠杆下=价格 -8%） |
| 资金量 | unlimited（全仓比例 99%） |
| API Server | 0.0.0.0:8080 |
| 飞书 Webhook | 已启用 |
| UI | FreqUI |

---

## 9. 策略说明（MultiAssetChannelBreakoutV5）

### 9.1 核心逻辑

| 模块 | 说明 |
|------|------|
| 指标 | ATR(10) 波动率 + SMA 长均线 + 通道上下轨 + ADX(14) 动量 |
| 入场 | 收盘价突破动态上轨 **且** 在长均线上方 **且** ADX > 28 |
| 入场确认 | 实时下单防追高（偏离信号 K 线收盘价 >1% 取消）+ 防假突破（价格不低于信号 K 线均线和上轨） |
| 出场 | 收盘价跌破动态退出线（下轨 + ATR × 0.19） |
| 止损 | 分段：盈利 >5% 保本、>15% 允许 10% 回撤、>30% 允许 10% 回撤，其余靠 -8% 硬止损 |
| 杠杆 | 固定 10x |

### 9.2 关键参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `up_line_span` | 340 | 上轨窗口（15m K 线数，约 3.5 天） |
| `up_line_offset` | -0.18 | 上轨 ATR 偏移（负值=上轨低于最高点，降低入场门槛） |
| `buy_stop_profit_span` | 141 | 下轨窗口 |
| `buy_stop_profit_offset` | 0.19 | 下轨 ATR 偏移 |
| `ma_span_long_days` | 2 | 长均线天数（2×96=192 根 15m K 线） |
| `adx_threshold` | 28 | 动量过滤阈值 |
| `startup_candle_count` | 600 | 预热 K 线数 |

### 9.3 策略文件位置

| 位置 | 文件 |
|------|------|
| 本地 | `user_data/strategies/multi_asset_channel_breakout_v5.py` |
| 服务器 | `/opt/freqtrade/user_data/strategies/multi_asset_channel_breakout_v5.py` |
| 备份 | `skills/core/` |

---

## 10. 更换策略流程

```bash
# 1. 修改策略文件
# 本地编辑 user_data/strategies/xxx.py

# 2. 推送到服务器
scp -o ProxyJump=ecs user_data/strategies/xxx.py vultr:/opt/freqtrade/user_data/strategies/

# 3. 修改 config.json 中的 strategy 名称和 timeframe
ssh vultr "sed -i 's/\"strategy\": \"旧策略\"/\"strategy\": \"新策略\"/' /opt/freqtrade/user_data/config.json"

# 4. 重启服务
ssh vultr "systemctl restart freqtrade"

# 5. 验证
ssh vultr "journalctl -u freqtrade --no-pager -n 20 | grep -E 'strategy|RUNNING|Error'"
```

---

## 11. 注意事项

- **SSH 跳板**：必须通过 `ProxyJump ecs` 走阿里云跳板，直连 Vultr 会超时
- **Python 版本**：Ubuntu 22.04 默认 3.10，必须装 3.12
- **OKX hostname**：用 `www.okx.cab` 而非 `www.okx.com`，国内访问 okx.com 受限
- **时区**：服务器保持 UTC，所有交易所时间戳和 freqtrade 内部均用 UTC
- **Warmup**：策略启动时通过 REST 拉取历史 K 线（startup_candle_count=600），约 3 次 API 调用，完成后图表立即可用
- **仅做多**：`can_short = False`
- **ROI 禁用**：`minimal_roi = {"0": 100}`，全部由信号出场和 custom_stoploss 处理
- **服务自恢复**：`Restart=on-failure` + `RestartSec=10`，进程崩溃 10 秒后自动重启