部署文档

本平台是私有化部署方案：A 股策略回测、定时行情扫描、买卖信号推送， 附带 RBAC 权限、审计日志与安全防护。以下是完整的部署流程。

相关文档

除本页的部署流程外，平台还有两份完整文档：

Markdown 源文件： api.md · features.md

一、方案概览

前端已彻底拆分为三个独立应用，同域不同路径部署；后端为 FastAPI 单进程， 数据落 SQLite（WAL 模式）。

二、环境要求

• Python 3.9+（推荐 3.11，Pydantic v2 与类型语法要求）
• Node.js 18+（仅构建期需要，服务器可不装）
• Nginx 1.20+
• 内存 ≥ 1GB（低于 1GB 时 vite build 可能 OOM，建议加 swap 或本地构建后上传 dist）
• 可选：tushare token（留空则使用本地合成数据，回测结果不具备投资参考价值）

三、目录结构

quant-platform/
├── backend/            FastAPI 后端
│   ├── app/            业务代码
│   ├── tests/          冒烟 / 幂等测试
│   ├── .venv/          Python 虚拟环境
│   ├── .env            环境变量（含 SECRET_KEY，勿外泄）
│   └── data/           SQLite 数据库
├── frontend/           用户端源码 → dist → /app
├── frontend-admin/     管理后台源码 → dist → /admin
├── frontend-shared/    两端共享源码（API 封装 / store / 样式 / 路径常量）
├── website/            产品官网静态文件 → /
├── deploy/             Nginx 配置、systemd、验证脚本
└── start.sh            启动脚本

四、本地构建

服务器无 Node 时在本地构建后上传产物：

cd frontend       && npm install && npm run build
cd frontend-admin && npm install && npm run build
# website/ 是纯静态，无需构建

构建产物中资源路径带前缀（/app/assets/…、/admin/assets/…）， 这是三端同域部署的关键，不要手工改写。

五、启动后端

cd /www/wwwroot/quant-platform/backend
python3.11 -m venv .venv
./.venv/bin/pip install -r requirements.txt

# 生成 .env（SECRET_KEY 必须固定，否则重启后全部 JWT 失效）
./.venv/bin/python -c "from app.config import settings; print(settings.SECRET_KEY)"

六、Nginx 配置

两个 Vue 应用都是 history 模式，刷新 /app/strategies、/admin/users 这类深层路径时必须回落到各自的 index.html，否则 404。

location = /app   { return 301 /app/; }
location ^~ /app/ {
    root /www/wwwroot/quant-platform/frontend/dist;
    rewrite ^/app/(.*)$ /$1 break;
    try_files $uri $uri/ /index.html;
}

location = /admin { return 301 /admin/; }
location ^~ /admin/ {
    root /www/wwwroot/quant-platform/frontend-admin/dist;
    rewrite ^/admin/(.*)$ /$1 break;
    try_files $uri $uri/ /index.html;
}

location ^~ /api/ {
    proxy_pass http://quant_backend;
    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    # 必须覆盖而非追加，否则客户端可伪造该头绕过限流
    proxy_set_header X-Forwarded-For   $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
}

location = / {
    root /www/wwwroot/quant-platform/website;
    try_files /index.html =404;
}

七、首次上线

1. 启动后端：systemctl restart quant（或 ./start.sh --daemon）
2. 访问 /app/login，用初始管理员账号登录
3. 在后台「系统设置」填入 tushare token（没有则保持合成数据，界面会显著警示）
4. 修改管理员密码，改掉初始密码
5. 按需创建策略模板与监控任务

八、上线验证

# 业务链路（直连后端）
backend/.venv/bin/python deploy/verify_deployment.py

# 真实域名（证书 / 跳转 / SPA / API / 安全）
backend/.venv/bin/python deploy/verify_domain.py

# 幂等去重边界
backend/.venv/bin/python backend/tests/idempotency_test.py

# 冒烟测试
backend/.venv/bin/python backend/tests/smoke_test.py

跑验证脚本要用服务自己的 venv（backend/.venv/bin/python）， 系统 python3.11 没装 httpx。

九、常见问题

刷新 /app/strategies 报 404

Nginx 缺 try_files … /index.html 回落，或 root 指错了目录。 注意 root 指向的是 dist 本身，不是它的父目录。

登录后刷新又跳回登录页

SECRET_KEY 每次重启都在变，导致已签发的 JWT 全部失效。 把 .env 里的 SECRET_KEY 固定下来。

提示「请求过于频繁」

触发了接口限流。登录 10 次/分钟、注册 5 次/分钟、验证码 30 次/分钟是硬上限。 等一分钟窗口滑过即可；阈值可在后台「系统设置」调整。

跨应用跳转跳到 /admin/app/login

Vue Router 的 history base 不同，前缀会被重复拼接。 后台（base /admin/）跳用户端必须用整页导航 window.location.href， 不能用 router.push。

行情数据全是合成数据

未配置 tushare token。填入后需清一次行情缓存。 合成数据在界面上有显著警示，不会与真实数据混淆。

调度任务没自动执行

检查 SCHEDULER_ENABLED=true 且 uvicorn 是单进程。 多 worker 会让调度器状态混乱。

十、版本升级

1. 备份数据库与当前产物：tar -czf backup.tar.gz backend/data frontend/dist frontend-admin/dist website
2. 上传新的 dist / website / 后端代码
3. nginx -t 通过后 systemctl reload nginx
4. systemctl restart quant
5. 跑第八节的验证脚本