# tradehk 部署运维指南

> 返回：[tradehk 文档中心](./README.md)
> 源文件：`docker-compose.yml`、`deploy/deploy.sh`、`deploy/nginx.conf`

## 概述

tradehk 采用 Docker Compose 部署，包含三个容器：Node.js 应用服务、MySQL 数据库、Nginx 反向代理。支持一键部署脚本。

---

## 环境要求

| 组件 | 版本要求 |
|------|---------|
| Docker | 20.10+ |
| Docker Compose | 2.0+ |
| 服务器内存 | 最低 2GB |
| 服务器磁盘 | 最低 20GB |
| 操作系统 | Ubuntu 20.04+ / CentOS 7+ |

---

## 快速部署

### 第一步：克隆仓库

```bash
git clone ssh://git@git.hk.hao.work:2222/hao/tradehk.git
cd tradehk
```

### 第二步：配置环境变量

复制并编辑环境变量文件：

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

关键环境变量说明：

| 变量 | 必填 | 说明 | 示例 |
|------|------|------|------|
| `DATABASE_URL` | ✅ | MySQL 连接字符串 | `mysql://user:pass@mysql:3306/tradehk` |
| `JWT_SECRET` | ✅ | JWT 签名密钥（随机字符串） | `your-secret-key-here` |
| `LARK_WEBHOOK_URL` | ⭕ | 飞书 Webhook URL | `https://open.feishu.cn/...` |
| `MARKET_ENGINE_POLL_MS` | ⭕ | 引擎轮询间隔（毫秒） | `30000` |
| `MARKET_SUMMARY_INTERVAL_HOURS` | ⭕ | 汇总通知间隔（小时） | `4` |
| `BINANCE_API_KEY` | ⭕ | Binance API Key（自动交易需要） | `your-api-key` |
| `BINANCE_API_SECRET` | ⭕ | Binance API Secret | `your-api-secret` |

### 第三步：一键部署

```bash
chmod +x deploy/deploy.sh
./deploy/deploy.sh
```

部署脚本会自动完成：
1. 构建 Docker 镜像
2. 启动 MySQL 容器并等待就绪
3. 运行数据库迁移（Drizzle migrate）
4. 启动 Node.js 应用容器
5. 启动 Nginx 反向代理

---

## Docker Compose 结构

```yaml
services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL
      - JWT_SECRET
      - LARK_WEBHOOK_URL
    depends_on:
      mysql:
        condition: service_healthy

  mysql:
    image: mysql:8.0
    volumes:
      - mysql_data:/var/lib/mysql
      - ./deploy/mysql/my.cnf:/etc/mysql/conf.d/my.cnf
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
      interval: 10s
      timeout: 5s
      retries: 5

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./deploy/nginx.conf:/etc/nginx/conf.d/default.conf
    depends_on:
      - app

volumes:
  mysql_data:
```

---

## Nginx 配置说明

tradehk 的 Nginx 配置实现了：

1. **前端静态文件服务**：React 构建产物（`/dist`）
2. **API 反向代理**：`/api/*` 转发到 Node.js 应用（`localhost:3000`）
3. **WebSocket 代理**：支持 tRPC WebSocket 连接
4. **HTTPS 支持**：可配置 SSL 证书

关键配置片段：

```nginx
server {
    listen 80;
    server_name your-domain.com;

    # 前端静态文件
    location / {
        root /app/dist;
        try_files $uri $uri/ /index.html;
    }

    # API 代理
    location /api/ {
        proxy_pass http://app:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
    }
}
```

---

## 数据库管理

### 运行迁移

```bash
docker compose exec app pnpm drizzle-kit migrate
```

### 查看数据库

```bash
docker compose exec mysql mysql -u root -p tradehk
```

### 常用 SQL 查询

查看最近信号：
```sql
SELECT symbol, interval, direction, strength, price, 
       FROM_UNIXTIME(signalAt/1000) as signal_time
FROM signals
ORDER BY signalAt DESC
LIMIT 20;
```

查看 EWO 转换统计：
```sql
SELECT symbol, interval, direction, COUNT(*) as count
FROM signals
WHERE direction IN ('long', 'short')
GROUP BY symbol, interval, direction
ORDER BY count DESC;
```

---

## 日常运维

### 查看日志

```bash
# 应用日志
docker compose logs -f app

# 最近100行
docker compose logs --tail=100 app

# 只看错误
docker compose logs app 2>&1 | grep -i error
```

### 重启服务

```bash
# 重启应用（不重启数据库）
docker compose restart app

# 完整重启
docker compose down && docker compose up -d
```

### 更新部署

```bash
git pull
docker compose build app
docker compose up -d app
```

### 备份数据库

```bash
docker compose exec mysql mysqldump -u root -p tradehk > backup_$(date +%Y%m%d).sql
```

---

## 飞书 Webhook 配置

### 获取 Webhook URL

1. 在飞书群中添加自定义机器人
2. 复制 Webhook URL（格式：`https://open.feishu.cn/open-apis/bot/v2/hook/xxx`）
3. 设置到环境变量 `LARK_WEBHOOK_URL`

### 测试通知

```bash
curl -X POST "https://open.feishu.cn/open-apis/bot/v2/hook/xxx" \
  -H "Content-Type: application/json" \
  -d '{"msg_type":"text","content":{"text":"tradehk 通知测试"}}'
```

---

## 性能调优

### MySQL 配置（deploy/mysql/my.cnf）

| 参数 | 推荐值 | 说明 |
|------|--------|------|
| `innodb_buffer_pool_size` | 服务器内存的50% | InnoDB 缓冲池 |
| `max_connections` | 200 | 最大连接数 |
| `query_cache_size` | 64M | 查询缓存 |

### 引擎轮询间隔

- **默认**：30秒（`MARKET_ENGINE_POLL_MS=30000`）
- **激进**：10秒（更快响应，更高 API 消耗）
- **保守**：60秒（减少 API 调用，适合多币对监控）

**注意**：Binance API 有速率限制，监控超过20个币对时建议将轮询间隔设为60秒以上。

---

## 常见问题

**Q：EWO 转换通知没有收到？**

检查顺序：
1. `LARK_WEBHOOK_URL` 是否正确配置
2. 用户设置中 `larkWebhookEnabled` 是否为 true
3. `ewoTurnRules` 中是否有对应币对的规则且 `enabled=true`
4. 查看应用日志是否有推送错误

**Q：信号通知太频繁？**

调整 `signalLarkThrottleMinutes` 参数（在用户设置中），默认10分钟，可以增加到30-60分钟。

**Q：数据库磁盘占用增长过快？**

signals 表会持续增长。建议设置定期清理任务：
```sql
DELETE FROM signals WHERE signalAt < UNIX_TIMESTAMP(DATE_SUB(NOW(), INTERVAL 30 DAY)) * 1000;
```

## 相关文档

- [系统架构总览](./系统架构总览.md) — 整体架构理解
- [飞书通知格式规范](./飞书通知格式规范.md) — 通知配置说明
- [开发历史与TODO](./开发历史与TODO.md) — 功能路线图