# 部署文档

国内期货交易监控复盘系统 — Ubuntu 服务器部署、更新与运维说明。

---

## 部署概要

| 项目 | 默认值 |
|------|--------|
| 部署目录 | `/opt/qihuo` |
| 运行用户 | `root`（与 `deploy.sh` / PM2 配置一致） |
| 服务端口 | `6600` |
| 进程管理 | PM2，应用名 `qihuo` |
| 数据库 | SQLite `futures.db` |
| 仓库 | https://git.bz121.com/dekun/qihuo.git |

---

## 环境要求

- **系统**：Ubuntu 20.04+（推荐）
- **Python**：3.10+
- **Node.js + PM2**：进程守护与开机自启
- **网络**：
  - `hq.sinajs.cn`（新浪行情）
  - 企业微信 API（若启用推送）
  - `git.bz121.com`（拉取代码）
  - 可选：`pip` 安装 akshare 时需访问 PyPI

---

## 一键部署（推荐）

以 **root** 登录服务器后执行：

```bash
cd /opt/qihuo
# 若目录不存在，先克隆：
# git clone https://git.bz121.com/dekun/qihuo.git /opt/qihuo

bash deploy.sh
```

`deploy.sh` 会自动完成：

1. 安装 `python3`、`python3-venv`、`git`、`nodejs`、`npm`、`pm2`
2. `git pull` 或 `git clone` 到 `/opt/qihuo`
3. 创建虚拟环境 `venv` 并 `pip install -r requirements.txt`
4. 首次生成 `.env`（随机 `SECRET_KEY`）
5. `pm2 start ecosystem.config.cjs` 并 `pm2 save`

部署完成后访问：`http://<服务器IP>:6600`

---

## 手动部署

### 1. 安装系统依赖

```bash
apt update
apt install -y python3 python3-venv python3-pip git nodejs npm
npm install -g pm2
```

### 2. 克隆代码

```bash
git clone https://git.bz121.com/dekun/qihuo.git /opt/qihuo
cd /opt/qihuo
```

### 3. Python 虚拟环境与依赖

```bash
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
```

### 4. 可选：AKShare（手续费第三方同步）

```bash
source venv/bin/activate
pip install akshare
```

不安装也可使用系统内置 `data/fee_rates.json` 默认费率。

### 5. 环境变量

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

| 变量 | 说明 |
|------|------|
| `HOST` | 监听地址，默认 `0.0.0.0` |
| `PORT` | 端口，默认 `6600` |
| `SECRET_KEY` | Flask Session 密钥，务必随机 |
| `ADMIN_USERNAME` | 初始管理员用户名 |
| `ADMIN_PASSWORD` | 初始管理员密码（仅首次建库生效） |
| `ADMIN_SYNC_FROM_ENV` | `true` 时重启可从 `.env` 同步账号密码 |
| `WECHAT_WEBHOOK` | 企业微信机器人地址（可选） |
| `QUOTE_SOURCE` | `sina`（默认）/ `ths` / `auto` |
| `THS_REFRESH_TOKEN` | 同花顺 iFinD token（机构用户） |

示例：

```env
HOST=0.0.0.0
PORT=6600
SECRET_KEY=请替换为随机长字符串
ADMIN_USERNAME=admin
ADMIN_PASSWORD=你的强密码
ADMIN_SYNC_FROM_ENV=false
WECHAT_WEBHOOK=
QUOTE_SOURCE=sina
```

### 6. PM2 启动

```bash
cd /opt/qihuo
pm2 start ecosystem.config.cjs
pm2 save
pm2 startup   # 按提示执行命令，实现开机自启
```

### 7. 创建日志目录（若不存在）

```bash
mkdir -p /opt/qihuo/logs /opt/qihuo/uploads
```

---

## 更新部署

代码已推送后，在服务器执行：

```bash
cd /opt/qihuo
git pull
source venv/bin/activate
pip install -r requirements.txt
pm2 restart qihuo
```

若新增可选依赖（如 akshare）：

```bash
pip install akshare
pm2 restart qihuo
```

应用启动时会自动执行 SQLite 表结构迁移（`ALTER TABLE` 容错），一般无需手工改库。

---

## PM2 常用命令

```bash
pm2 status              # 查看状态
pm2 logs qihuo          # 查看日志
pm2 logs qihuo --lines 100
pm2 restart qihuo       # 重启
pm2 stop qihuo          # 停止
pm2 delete qihuo        # 删除进程
pm2 save                # 保存进程列表
```

日志文件：

- `/opt/qihuo/logs/pm2-out.log`
- `/opt/qihuo/logs/pm2-error.log`

---

## 本地开发

```bash
git clone https://git.bz121.com/dekun/qihuo.git
cd qihuo
python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
python app.py
```

浏览器访问：`http://127.0.0.1:6600`

---

## 账号与密码

| 场景 | 操作 |
|------|------|
| 首次部署 | `.env` 中设置 `ADMIN_USERNAME` / `ADMIN_PASSWORD` 后启动 |
| 已部署后改 `.env` 密码 | 设 `ADMIN_SYNC_FROM_ENV=true`，`pm2 restart qihuo` |
| 网页改密码 | 登录 → 系统设置 |
| 忘记密码 | `cd /opt/qihuo && source venv/bin/activate && python reset_admin.py` |

账号数据在 `futures.db` 的 `settings` 表，不会仅因改 `.env` 自动更新（除非开启 `ADMIN_SYNC_FROM_ENV`）。

---

## 数据库与数据文件

| 路径 | 说明 |
|------|------|
| `/opt/qihuo/futures.db` | 主数据库，建议定期备份 |
| `/opt/qihuo/uploads/` | 复盘截图、自动 K 线图 |
| `/opt/qihuo/data/fee_rates.json` | 默认手续费表（可重载） |

备份示例：

```bash
cp /opt/qihuo/futures.db /opt/qihuo/futures.db.bak.$(date +%Y%m%d)
```

### 手工补列（极少需要）

若极老版本库缺少字段，可对照报错执行（新版本启动会自动迁移）：

```bash
sqlite3 /opt/qihuo/futures.db "ALTER TABLE key_monitors ADD COLUMN sina_code TEXT;"
```

---

## Nginx 反向代理（可选）

将 6600 反代到 80/443，并配置 HTTPS：

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

    location / {
        proxy_pass http://127.0.0.1:6600;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

---

## 防火墙

若使用 `ufw`，开放端口：

```bash
ufw allow 6600/tcp
# 或使用 Nginx 时只开放 80/443
```

---

## 故障排查

| 现象 | 可能原因 | 处理 |
|------|----------|------|
| 无法访问 6600 | 服务未启动 / 防火墙 | `pm2 status`、`pm2 logs qihuo` |
| 登录失败 | 密码未同步 | 网页改密或 `reset_admin.py` |
| 现价一直 `--` | 新浪网络不可达 | 检查服务器能否访问 `hq.sinajs.cn` |
| 关键位 500 | 缺 `sina_code` 列 | `git pull` 重启；或手工 `ALTER TABLE` |
| K 线生成失败 | matplotlib 未装 | `pip install matplotlib==3.9.2` |
| 手续费同步失败 | 未装 akshare | `pip install akshare` 或用「重载 JSON」 |
| `git pull` 冲突 | 本地有修改 | 备份 `futures.db` 后处理冲突或 `git stash` |

查看应用是否在监听：

```bash
ss -tlnp | grep 6600
```

---

## 安全建议

1. 部署后立即修改默认密码
2. 勿将 `.env`、`futures.db` 提交到公开仓库
3. 生产环境使用 HTTPS + 限制访问 IP
4. 定期备份 `futures.db` 与 `uploads/`

---

## 目录结构（部署后）

```
/opt/qihuo/
├── app.py
├── venv/
├── futures.db
├── .env
├── logs/
│   ├── pm2-out.log
│   └── pm2-error.log
├── uploads/
├── data/fee_rates.json
├── ecosystem.config.cjs
├── deploy.sh
└── docs/
    ├── FEATURES.md
    └── DEPLOY.md
```

---

## 相关文档

- [功能说明文档](./FEATURES.md)
- [README](../README.md)