sanguo_vnpy 项目目录整理提案（修订版）

提案人: 姜维（平台总督）日期: 2026-04-29 状态: 待确认

一、项目定位理解

sanguo_vnpy = 基于vnpy框架构建的三国量化全流程平台

核心目标

基于vnpy开源框架进行适配，构建投研→策略开发→模拟→实盘的全流程量化交易平台。

已完成的适配成果

vnpy 4.x 回测服务：基于BacktestingEngine封装的API化回测服务（scripts/backtest-service/）
本地数据适配器：vnpy_local_data_adapter.py，本地数据集成方案
Docker容器化部署：Dockerfile + entrypoint.sh，NAS群晖Docker运行
NAS多用户架构：config/（nginx+systemd），7个用户隔离配置
edict任务管理集成：浅集成方案，看板可视化
自动化部署流程：jiangwei-platform/deploy/nas/ 部署全流程脚本

远期目标

聚宽/QMT多风格兼容适配
策略开发标准化流程
模拟交易验证
实盘交易接入

二、现状分析

目录与文件统计

目录	文件数	大小	成果物？	说明
`scripts/backtest-service/`	9	核心	✅	回测服务核心代码，vnpy 4.x适配
`scripts/start_*.py`	3	核心	✅	启动脚本（RPC/Web/回测）
`scripts/utils/`	30	辅助	⚠️	数据适配器+调试工具混杂
`scripts/deployment/`	37	辅助	⚠️	部署脚本（部分仍在用，部分过时）
`scripts/verify/`	2	辅助	⚠️	验证脚本
`docker/`	5	核心	✅	Dockerfile+entrypoint+requirements
`config/`	21	核心	✅	NAS多用户nginx+systemd配置
`jiangwei-platform/deploy/`	11	核心	✅	NAS部署全流程（脚本+模板+文档）
`research/`	39	参考	⚠️	调研报告+过程文件混杂
`test/`	88	调试	❌	大量v2/v3/v4重复测试脚本
`archives/`	4	废弃	❌	旧Docker镜像tar(90M)+pid文件
`logs/`	8	废弃	❌	历史调试日志
`backup/`	0	空目录	❌	空目录
根目录*.log	3	废弃	❌	auto-sync日志(4.6M)
`data/`	1	数据	✅	quant_trading.db

三、整理提案

设计原则

面向vnpy适配开发：目录结构要体现"基于vnpy构建"的定位
保留所有有价值成果物：核心代码、配置、调研报告
只移动不删除：清理的文件进archive/，保持原结构可追溯
不涉及NAS端：只整理本地仓库

目标目录结构

sanguo_vnpy/
├── README.md                          # 项目总说明（新建，描述项目定位和架构）
│
├── docker/                            # Docker镜像构建
│   ├── Dockerfile                     #   镜像定义
│   ├── entrypoint.sh                  #   容器启动脚本（含pip自动安装）
│   └── requirements/                  #   Python依赖
│
├── src/                               # 🔥 平台核心代码（新增顶层目录）
│   ├── backtest-service/              #   vnpy 4.x回测服务（从scripts/提升）
│   │   ├── main.py                    #     FastAPI入口
│   │   ├── api.py                     #     API路由
│   │   ├── executor.py                #     vnpy回测执行器
│   │   ├── models.py                  #     数据模型
│   │   ├── config.py                  #     配置
│   │   ├── task_queue.py              #     任务队列
│   │   └── result_storage.py          #     结果存储
│   ├── adapters/                      #   vnpy适配层（从scripts/utils/提取）
│   │   └── vnpy_local_data_adapter.py #     本地数据适配器
│   └── scripts/                       #   启动脚本
│       ├── start_backtest_service.py
│       ├── start_rpc_server.py
│       └── start_web_trader.py
│
├── config/                            # NAS部署配置（原位保留）
│   ├── nginx/                         #   7个用户nginx配置
│   └── systemd/                       #   14个systemd服务文件
│
├── deploy/                            # 部署相关（从jiangwei-platform/提升）
│   └── nas/                           #   NAS部署全流程
│       ├── create-user.sh
│       ├── create-all-users.sh
│       ├── generate-all-configs.sh
│       ├── deploy-plan.md
│       ├── deploy-log.md
│       ├── port-allocation.md
│       └── templates/
│
├── research/                          # 调研文档（清理后保留）
│   ├── vnpy/                          #   vnpy框架调研
│   │   ├── vnpy本地数据集成方案.md
│   │   ├── edict集成完成总结.md
│   │   ├── 服务使用说明文档.md
│   │   ├── edict-adapter-scheme.md    # （从research/根目录移入）
│   │   ├── 三国edict浅集成执行流程.md
│   │   ├── 安装vnpy解决方案.md
│   │   ├── 回测API_bug修复报告.md
│   │   ├── final_fix_summary.md
│   │   ├── 修复完成通知.md
│   │   ├── 赵云数据转换指南.md
│   │   └── final/                     # （从vnpy/删除空目录，保留现有文件）
│   ├── nas/                           #   NAS部署调研
│   ├── docker/                        #   Docker相关调研
│   ├── jq_essence_articles/           #   聚宽精华文章
│   └── webtrader/                     #   （从task-20260331重命名）
│       ├── vnpy-webtrader-research-report.md
│       └── nas-deployment-architecture-analysis.md
│
├── data/                              # 数据（原位保留）
│
├── archive/                           # 归档（新增，存放清理出的历史文件）
│   └── 2026-04-29-cleanup/            #   按日期归档，保持原目录结构
│       ├── test/                      #     88个测试脚本
│       ├── scripts/deployment/        #     37个部署脚本
│       ├── scripts/utils/             #     30个工具脚本（非核心的）
│       ├── scripts/verify/            #     2个验证脚本
│       ├── logs/                      #     历史日志
│       └── research/                  #     过程文件
│
└── .gitignore                         # （更新，忽略*.log等）

操作清单

#	操作	文件数	风险	说明
1	新建 src/ 核心目录	-	无	体现vnpy适配开发结构
2	scripts/backtest-service/ → src/backtest-service/	9	低	回测服务核心代码提升到src/
3	scripts/utils/vnpy_local_data_adapter.py → src/adapters/	1	低	数据适配器归入适配层
4	*scripts/start_.py → src/scripts/**	3	低	启动脚本提升
5	jiangwei-platform/deploy/ → deploy/	11	低	部署相关提升到顶层
6	research/edict-adapter-scheme.md → research/vnpy/	1	无	归类到vnpy目录
7	research/task-20260331-vnpy-webtrader-research/ → research/webtrader/	2	无	重命名为更清晰的名称
8	test/ 全部 → archive/2026-04-29-cleanup/test/	88	低	重复测试脚本归档
9	scripts/deployment/ → archive/	37	低	过时部署脚本归档
10	scripts/utils/（非核心）→ archive/	29	低	保留vnpy_local_data_adapter.py后归档
11	scripts/verify/ → archive/	2	低	验证脚本归档
12	删除 archives/（旧镜像tar）	4	无	90M旧文件，已无用
13	删除根目录 .log + logs/*	11	无	垃圾日志
14	删除 backup/ 空目录	0	无	空目录
15	删除 models.py.bak	1	无	备份文件
16	新建 README.md	1	无	项目总说明
17	更新 .gitignore	1	无	忽略*.log等

关键说明

NAS端兼容：NAS上挂载的是 /volume1/stock/sanguo_vnpy/bt-service/ 和 entrypoint.sh，与本地 scripts/backtest-service/ 是独立的两份。本地目录调整不影响NAS运行。但后续需要同步更新entrypoint.sh中的路径引用。
scripts/deployment/ 中的有用脚本：nas_manager.sh、copy_and_start.sh 等可能仍在使用，整理时会检查并保留活跃脚本到 deploy/ 目录。
研究文档保留策略：research/下的文档按主题归入子目录（vnpy/nas/docker/webtrader/jq），删除散落在根目录的过程文件（如scrape脚本移到archive）。

四、预计效果

指标	整理前	整理后
总文件数	279	~80
根目录内容	4个log + 1个md + 9个目录	1个README + 7个目录
核心代码位置	scripts/backtest-service/	src/backtest-service/
目录语义	混乱，大量调试噪音	清晰，体现vnpy适配开发定位
磁盘占用	~95M	~5M

五、需要注意的点

git历史保留：所有操作通过 git mv 执行，保留完整历史
NAS同步检查：整理后确认auto-sync不会破坏NAS上的文件
README.md内容：需要描述项目定位（基于vnpy的全流程量化平台）、已完成适配、架构设计、使用方法

请确认是否同意此方案，或需要调整的地方。确认后立即执行。

9.6 KiB Raw Permalink Blame History Unescape Escape

sanguo_vnpy 项目目录整理提案（修订版）

一、项目定位理解

核心目标

已完成的适配成果

远期目标

二、现状分析

目录与文件统计

三、整理提案

设计原则

目标目录结构

操作清单

关键说明

四、预计效果

五、需要注意的点

9.6 KiB

Raw Permalink Blame History