qihuo/docs/DEPLOY.md

部署文档

国内期货交易监控复盘系统 — 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 登录服务器后执行：

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. 安装系统依赖

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

2. 克隆代码

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

3. Python 虚拟环境与依赖

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

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

source venv/bin/activate
pip install akshare

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

5. 环境变量

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（机构用户）

示例：

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 启动

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

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

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

---

更新部署

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

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

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

pip install akshare
pm2 restart qihuo

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

---

PM2 常用命令

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

---

本地开发

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	默认手续费表（可重载）

备份示例：

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

手工补列（极少需要）

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

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

---

Nginx 反向代理（可选）

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

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，开放端口：

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

查看应用是否在监听：

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

---

相关文档

• 功能说明文档
• README