期货行情分析系统 — 使用说明

基于 Docker + Python(tushare) + PostgreSQL 的中国期货行情分析系统。当前阶段已实现数据采集、三层加权打分模型与 Web 报表浏览端。运行方式支持两种模式:① 宿主机定时器触发 docker-compose run 执行 CLI;② 通过 FastAPI HTTP API 服务触发。

环境准备

• Docker >= 20.10
• Docker Compose >= 2.0
• (可选) psql 或任意 PostgreSQL 客户端用于本地查库

快速开始

1. 启动全栈服务

docker-compose up -d

这会同时启动 PostgreSQL、tushare API 服务(端口 8000)与 Web 浏览端(端口 8080)。

3. 通过 CLI 跑当月主力

docker-compose run --rm tushare python -m src.main

不传参时,按 tushare/src/contracts.py 的 ROLLOVER_RULES 自动选 FG 玻璃当月主力(例如 2026-05 -> FG2609.ZCE),启动后会先打印 [AUTO] FG 当月主力 -> ...,然后:

1. 从 tushare 拉取合约日线数据
2. 写入 PostgreSQL futures 数据库
3. 运行三层打分模型
4. 保存打分结果并输出到 stdout

4. 通过 API 触发流水线

# 触发 FG 打分
curl -X POST http://localhost:8000/api/v1/run -H "Content-Type: application/json" \
  -d '{"symbol":"FG"}'

# 查询最新打分
curl "http://localhost:8000/api/v1/scores?limit=5"

# 查询合约列表
curl "http://localhost:8000/api/v1/contracts"

# 查询 K 线数据
curl "http://localhost:8000/api/v1/candles?ts_code=FG2609.ZCE"

5. 跑其他合约或品种

# 显式指定合约
docker-compose run --rm tushare python -m src.main RB2510.SHF
docker-compose run --rm tushare python -m src.main I2601.DCE

# 按品种代号自动选当月主力(目前只配置了 FG)
docker-compose run --rm tushare python -m src.main --symbol FG

6. 玻璃 FG 主力轮换规则

当前自然月	主力合约
1、2、3 月	当年 05
4、5、6、7 月	当年 09
8、9、10、11 月	次年 01
12 月	次年 05

三层打分模型

综合分数公式

综合分数 = (短期动力 × 0.4) + (中期趋势 × 0.35) + (长期结构 × 0.25)

1. 短期动力（7 日窗口，权重 0.4）

逐日打分后取均值：

持仓变化	价格方向	得分
增仓	上涨	100（多头主动进攻）
增仓	下跌	0（空头主动进攻）
减仓	上涨	70（空头撤退）
减仓	下跌	30（多头撤退）
持平（|变化|<1%）	上涨	60
持平（|变化|<1%）	下跌	40

2. 中期趋势（15 日窗口，权重 0.35）

价格信号 = (今收 - 15日前收) / 15日前收
价格信号得分 = clamp(50 + 收益率×500, 0, 100)

资金意愿:
  增仓上涨天数 > 增仓下跌天数 → 80
  两者相当 → 50
  增仓下跌天数 > 增仓上涨天数 → 20

模块得分 = 价格信号 × 0.6 + 资金意愿 × 0.4

3. 长期结构（30 日窗口，权重 0.25）

持仓变化幅度 = (30日日均持仓 - 30日前持仓) / 30日前持仓

> 10%  → 90（显著增仓）
5%~10% → 70（温和增仓）
-5%~5% → 50（基本持平）
-10%~-5% → 30（温和减仓）
< -10% → 10（显著减仓）

信号解读

综合分数	信号
80-100	强烈看多 — 价格与资金共振
50-80	偏多/震荡偏强
40-50	偏空/震荡偏弱
0-40	强烈看空 — 资金主动打压

数据查询

业务数据存储在 PostgreSQL 中，可通过以下方式查询：

# 查看最新打分
docker-compose exec postgres psql -U trade -d futures -c \
  "SELECT ts_code, trade_date, composite, signal FROM scores ORDER BY trade_date DESC LIMIT 5;"

# 查看合约日线
docker-compose exec postgres psql -U trade -d futures -c \
  "SELECT trade_date, open, high, low, close, vol, oi FROM candles WHERE ts_code='FG2609.ZCE' ORDER BY trade_date DESC LIMIT 10;"

# 或通过 API 查询
curl "http://localhost:8000/api/v1/scores?ts_code=FG2609.ZCE&limit=10"
curl "http://localhost:8000/api/v1/candles?ts_code=FG2609.ZCE"

项目结构

trade/
├── docker-compose.yml          # Docker Compose 编排(postgres + tushare + web)
├── 使用说明.md                  # 本文件
├── CLAUDE.md                    # Claude Code 项目指引
├── data/                        # auth.db 目录(gitignored)
│   └── auth.db                  # web 自己维护的用户表(SQLite)
├── .gitignore                   # Git 忽略配置
├── tushare/                     # Python 数据服务
│   ├── Dockerfile
│   ├── requirements.txt
│   └── src/                     # 数据采集 + 打分 + FastAPI
│       ├── api.py               # FastAPI 服务入口
│       ├── models.py
│       ├── fetcher.py
│       ├── scorer.py
│       ├── storage.py           # PostgreSQL 读写
│       ├── contracts.py
│       └── main.py              # CLI 入口
└── web/                         # Web 浏览端
    ├── .dockerignore
    ├── backend/                 # Go 1.25 后端 (chi + lib/pq + JWT)
    │   ├── Dockerfile           # 多阶段:node 构 UI → go 构二进制 → alpine 运行
    │   ├── go.mod
    │   ├── main.go
    │   ├── embed.go             # //go:embed all:dist
    │   ├── .env.example         # ADMIN_USER/ADMIN_PASS/JWT_SECRET 示例
    │   ├── dist/                # 占位,Docker 构建期被 vite 输出覆盖
    │   └── internal/
    │       ├── config/          # 环境变量加载
    │       ├── store/           # PostgreSQL 业务查询 + SQLite auth.db
    │       ├── auth/            # JWT + bcrypt + 首启 admin 引导
    │       ├── middleware/      # RequireUser / RequireAdmin / 日志
    │       ├── handlers/        # 登录 / 打分 / K线 / 用户管理
    │       └── router/          # chi 路由装配
    └── frontend/                # Vue 3 + Vite + Element Plus + ECharts
        ├── package.json
        ├── vite.config.ts
        ├── tsconfig.json
        ├── index.html
        └── src/
            ├── main.ts / App.vue
            ├── router/          # 守卫(未登录/管理员路由)
            ├── stores/          # Pinia: auth.ts(持久化 token) + theme.ts(暗/浅色模式)
            ├── api/             # axios 封装 + 各端点
            ├── views/           # 登录 / 打分列表 / 图表 / 用户管理
            └── components/      # 抽屉 + ECharts K 线

技术栈

• Python 3.13 (alpine) + tushare + pandas + FastAPI + psycopg3 — 数据采集、打分与 API 服务
• Go 1.25.8 (alpine 3.23) + chi + lib/pq + JWT — Web 后端
• Vue 3 + Vite + Element Plus + ECharts — Web 前端
• PostgreSQL 18.3 (alpine 3.23) — 业务数据存储
• SQLite — 鉴权数据存储(auth.db)
• Docker / Docker Compose — 容器化部署

常见问题

Q: 为什么某些日期返回空数据？

A: tushare 数据更新有延迟，且不同接口对 token 积分等级有要求。若 fut_daily 返回空但 trade_cal 正常，通常是该日期实际行情数据尚未入库。

Q: 合约代码格式？

A: 郑商所用 .ZCE 后缀（如 FG2609.ZCE），上期所用 .SHF，大商所用 .DCE。注意不是 .CZC。

Q: 如何定时自动跑？

A: 通过宿主机 cron / launchd 等定时器调用 docker-compose run --rm tushare ...。也可直接调用 API: curl -X POST http://localhost:8000/api/v1/run ...。

Web 报表(浏览端)

./web/ 提供一个图形化的浏览端,展示 tushare 流水线写入 PostgreSQL 的打分与行情数据。后端 Go(golang:1.25.8-alpine3.23)读取数据库,前端 Vue 3 + Element Plus + ECharts,通过 docker-compose 一起部署。

1. 配置首启凭据

在 web/backend/.env 写入(.env 已 gitignored,可参考 web/backend/.env.example):

ADMIN_USER=admin
ADMIN_PASS=请改成强密码
JWT_SECRET=$(openssl rand -hex 32)

ADMIN_USER/ADMIN_PASS 仅在 auth.db 中没有任何 admin 时生效,首次启动会以这一对凭据建立管理员;之后即使改这两个变量也不会改密。JWT_SECRET 必须 ≥16 字符。

2. 启动

# 构建并启动 web 服务,不影响现有 tushare
docker-compose up -d --build web

# 查看启动日志:首启会出现 [bootstrap] admin 'xxx' created
docker-compose logs -f web

浏览器访问 http://localhost:8080,用上一步的管理员账号登录。

3. 页面说明

• 打分列表 /scores:按合约、日期、条数筛选,展示综合分/信号/三层得分;点击「明细」弹抽屉,显示短期 7 日逐日打分、中期(15d)价格收益与资金意愿、长期(30d)持仓变化。
• K 线 / 持仓 /chart:选合约 + 日期区间,主图蜡烛(开高低收),副图持仓量曲线;鼠标拖选缩放。
• 用户管理 /admin/users:仅管理员可见。可创建子账号(user 默认,亦可建 admin)、重置密码、禁用/启用、删除;不允许对自己执行禁用或删除。

普通用户登录后 /admin/* 路径会被前端守卫拦截并跳回 /scores,后端也会以 403 拒绝。

前端支持暗/浅色模式切换,点击顶部导航栏的「暗/亮」开关即可切换。侧边导航在暗色模式使用深色背景,浅色模式使用浅色背景。

4. 子账号维护流程

1. 用 admin 登录 → 进入 /admin/users → 「新建账号」,填写用户名 / 密码(≥6 位) / 角色。
2. 把账号发给同事即可登录;无注册入口。
3. 离职 / 风险事件:用「禁用」临时停用(token 立即失效,前端不能再请求),或「删除」彻底清除。

5. 数据流向与数据库分离

tushare(写) → PostgreSQL futures 数据库 ←(只读)── web 后端
web 后端 ←(读写)→ data/auth.db (SQLite)

业务数据(candles + scores)统一存储在 PostgreSQL 中,auth.db 表为:

users(id, username UNIQUE, password_hash, role IN ('admin','user'),
      disabled, created_at, updated_at)

auth.db 在 ./data/ 目录,被 .gitignore 覆盖。

6. 常见问题

Q: 忘记管理员密码怎么办?

docker-compose stop web
sqlite3 data/auth.db "DELETE FROM users WHERE role='admin';"
# 修改 web/backend/.env 里的 ADMIN_USER/ADMIN_PASS
docker-compose up -d web

启动时会重新触发 bootstrap 写入新的 admin。

Q: 改了 Go / Vue 代码但页面没变?

源码不挂载,镜像内是 COPY 进去的。重建:docker-compose build web && docker-compose up -d web。

Q: 登录提示 "JWT_SECRET 必须至少 16 个字符"?

web/backend/.env 没设或太短,用 openssl rand -hex 32 生成一个 64 字符的十六进制字符串即可。

Q: 为什么 tushare 容器启动后没有立即退出?

因为默认命令改为 uvicorn src.api:app 常驻 API 服务。如需执行单次 CLI,用 docker-compose run --rm tushare python -m src.main ...。