docs: 文档重构 — 清理 AI agent 残留，整合 docs/ 目录结构
- 删除 11 个残留文件: continuation.md, init_plan.md, reasonix.toml, djapi/continuation.md, djapi/.serena/, djapi/.claude/, djapi/.mcp.json, .claude/skills/, docs/usage.html, docs/db_schema.md, docs/report_db_design.md - 7 个 CLAUDE-*.md 移入 docs/ 并重命名去 CLAUDE- 前缀 - 新增 4 个文档: architecture.md, development.md, api.md, deployment.md - 重写 usage.md, README.md - 修复所有过时引用和交叉链接
This commit is contained in:
Simon
@@ -0,0 +1,274 @@
|
||||
# 部署说明
|
||||
|
||||
cc-cursor 包含两个运行组件：**finance 量化引擎**（Mac Mini 本地）和 **djapi API 后端**（Linux 服务器）。部署架构如下：
|
||||
|
||||
```
|
||||
┌─ Mac Mini (本地) ─────────────────────────────────────────────┐
|
||||
│ │
|
||||
│ finance/ 量化引擎 │
|
||||
│ ├── 数据获取 (AkShare/Tushare) │
|
||||
│ ├── 因子计算 / 回测 / ML │
|
||||
│ └── Agent 日报生成 │
|
||||
│ │
|
||||
│ shared/script/autossh.sh │
|
||||
│ └── SSH 隧道 :13306 ──────────────────────┐ │
|
||||
│ │ │
|
||||
└─────────────────────────────────────────────┼──────────────────┘
|
||||
│
|
||||
MariaDB 10.11 │
|
||||
doorcome.cn:3306│
|
||||
│
|
||||
┌─ Linux 服务器 (doorcome.cn) ────────────────┼──────────────────┐
|
||||
│ │ │
|
||||
│ djapi/ Django API │ │
|
||||
│ ├── uWSGI :5004 │ │
|
||||
│ ├── nginx 反向代理 │ │
|
||||
│ └── 域名: api.doorcome.cn │ │
|
||||
│ │ │
|
||||
│ MariaDB myquant 库 │ │
|
||||
│ ├── mac_* 表 (量化引擎数据) │ │
|
||||
│ ├── xwlb_* 表 (新闻联播) │ │
|
||||
│ └── news_* 表 (日报) │ │
|
||||
│ │ │
|
||||
└─────────────────────────────────────────────┘ │
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. 本地环境（Mac Mini）
|
||||
|
||||
### 1.1 Python 环境
|
||||
|
||||
```bash
|
||||
conda activate quant # Python 3.11.13
|
||||
```
|
||||
|
||||
### 1.2 环境变量
|
||||
|
||||
复制并编辑 `finance/.env`（参考 `finance/.env.example`）：
|
||||
|
||||
```bash
|
||||
TUSHARE_TOKEN=your_token_here
|
||||
QWEN_API_KEY=sk-your-key-here
|
||||
MAC_DB_HOST=127.0.0.1
|
||||
MAC_DB_PORT=13306
|
||||
MAC_DB_USER=myquant
|
||||
MAC_DB_PASSWORD=your_password_here
|
||||
MAC_DB_NAME=myquant
|
||||
```
|
||||
|
||||
### 1.3 数据库 SSH 隧道
|
||||
|
||||
```bash
|
||||
bash shared/script/autossh.sh
|
||||
```
|
||||
|
||||
脚本内容：
|
||||
|
||||
```bash
|
||||
autossh -M 0 -fN -L 13306:localhost:3306 tunnel@doorcome.cn
|
||||
```
|
||||
|
||||
验证隧道：
|
||||
|
||||
```bash
|
||||
lsof -i :13306 | grep LISTEN
|
||||
```
|
||||
|
||||
连接信息：
|
||||
|
||||
```
|
||||
Host: 127.0.0.1
|
||||
Port: 13306
|
||||
User: myquant
|
||||
Database: myquant
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 服务器环境（doorcome.cn）
|
||||
|
||||
### 2.1 基本信息
|
||||
|
||||
| 项目 | 值 |
|
||||
|------|-----|
|
||||
| 服务器 | `simon@doorcome.cn` |
|
||||
| 项目路径 | `/home/simon/myquant/djapi/` |
|
||||
| Python 环境 | `/opt/miniconda/envs/django` (Python 3.10) |
|
||||
| uWSGI 端口 | `127.0.0.1:5004` |
|
||||
| nginx 反向代理 | 域名 → `127.0.0.1:5004` |
|
||||
| 生产域名 | `api.doorcome.cn`、`echart.doorcome.cn` |
|
||||
|
||||
### 2.2 服务器环境变量
|
||||
|
||||
服务器端 `djapi/.env`（**不随代码同步**，需在服务器上手动维护）：
|
||||
|
||||
```bash
|
||||
DJANGO_SECRET_KEY=...
|
||||
TUSHARE_TS_TOKEN=...
|
||||
MYSQL_HOST=localhost
|
||||
MYSQL_PORT=3306
|
||||
MYSQL_USER=myquant
|
||||
MYSQL_PASSWORD=...
|
||||
MYSQL_DATABASE=myquant
|
||||
NEWS_DB_HOST=127.0.0.1
|
||||
NEWS_DB_PORT=3306
|
||||
NEWS_DB_USER=myquant
|
||||
NEWS_DB_PASSWORD=...
|
||||
NEWS_DB_NAME=myquant
|
||||
DEEPSEEK_API_KEY=...
|
||||
DASHSCOPE_API_KEY=...
|
||||
```
|
||||
|
||||
### 2.3 uWSGI 配置
|
||||
|
||||
配置文件：`djapi/uwsgi.ini`
|
||||
|
||||
```ini
|
||||
[uwsgi]
|
||||
http = 127.0.0.1:5004
|
||||
chdir = /home/simon/myquant/djapi
|
||||
module = djapi.wsgi:application
|
||||
uid = simon
|
||||
gid = simon
|
||||
master = true
|
||||
workers = 5
|
||||
pidfile = /home/simon/myquant/djapi/uwsgi.pid
|
||||
vacuum = true
|
||||
thunder-lock = true
|
||||
enable-threads = true
|
||||
harakiri = 30
|
||||
post-buffering = 4096
|
||||
daemonize = /home/simon/myquant/djapi/uwsgi.log
|
||||
log-maxsize = 10240000
|
||||
py-autoreload = 1
|
||||
virtualenv = /opt/miniconda/envs/django
|
||||
env = DJANGO_SETTINGS_MODULE=djapi.settings
|
||||
```
|
||||
|
||||
### 2.4 uWSGI 管理命令
|
||||
|
||||
```bash
|
||||
# 启动
|
||||
uwsgi --ini uwsgi.ini
|
||||
|
||||
# 热重载
|
||||
uwsgi --reload uwsgi.pid
|
||||
|
||||
# 停止
|
||||
uwsgi --stop uwsgi.pid
|
||||
|
||||
# 强制停止
|
||||
kill $(lsof -ti:5004)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 代码部署
|
||||
|
||||
### 3.1 全量同步
|
||||
|
||||
```bash
|
||||
rsync -avz --delete \
|
||||
--exclude='.env' --exclude='db.sqlite3' \
|
||||
--exclude='*.log' --exclude='uwsgi.pid' \
|
||||
--exclude='__pycache__/' --exclude='*.pyc' \
|
||||
--exclude='xwlb_video/' --exclude='audio_processing/' \
|
||||
/path/to/cc-cursor/djapi/ \
|
||||
simon@doorcome.cn:/home/simon/myquant/djapi/
|
||||
```
|
||||
|
||||
### 3.2 单文件同步
|
||||
|
||||
```bash
|
||||
# 必须写完整目标路径，否则会展平到根目录
|
||||
rsync -avz api/views.py simon@doorcome.cn:/home/simon/myquant/djapi/api/views.py
|
||||
```
|
||||
|
||||
### 3.3 重启服务
|
||||
|
||||
```bash
|
||||
ssh simon@doorcome.cn "kill \$(lsof -ti:5004); sleep 2; /opt/miniconda/envs/django/bin/uwsgi --ini /home/simon/myquant/djapi/uwsgi.ini"
|
||||
```
|
||||
|
||||
### 3.4 部署后验证
|
||||
|
||||
```bash
|
||||
# Swagger 文档
|
||||
curl -s https://api.doorcome.cn/api/docs/ | head -5
|
||||
|
||||
# 日报查询
|
||||
curl -s 'https://api.doorcome.cn/api/news/reports/' | python -m json.tool | head -20
|
||||
|
||||
# 健康检查（冒烟）
|
||||
curl -s -o /dev/null -w "%{http_code}" 'https://api.doorcome.cn/api/news/reports/'
|
||||
# → 200
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 数据库
|
||||
|
||||
### 4.1 表前缀
|
||||
|
||||
| 前缀 | 用途 | 位置 |
|
||||
|------|------|------|
|
||||
| `mac_` | 量化引擎数据（股票列表、日线、财务、报告） | finance 引擎写入 |
|
||||
| `xwlb_` | 新闻联播数据 | djapi video 模块写入 |
|
||||
| `news_` | 日报数据 | 外部 pipeline 写入，djapi 只读 |
|
||||
|
||||
### 4.2 量化引擎表
|
||||
|
||||
| 表 | 内容 | 主键 |
|
||||
|----|------|------|
|
||||
| `mac_stock_basic` | A 股列表 (5,524 只) | ts_code |
|
||||
| `mac_stock_daily` | 日线 OHLCV | (ts_code, trade_date) |
|
||||
| `mac_stock_financial` | 财务指标 | (ts_code, end_date) |
|
||||
| `mac_report` | 报告持久化 | id |
|
||||
|
||||
### 4.3 日报表
|
||||
|
||||
| 表 | 内容 |
|
||||
|----|------|
|
||||
| `news_report` | 日报主表（一行 = 一份日报） |
|
||||
| `news_event` | 日报事件明细（一行 = 一条事件） |
|
||||
|
||||
详见 [db_schema_v1.1.md](db_schema_v1.1.md)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 开发环境
|
||||
|
||||
### 5.1 本地运行 djapi
|
||||
|
||||
```bash
|
||||
cd djapi
|
||||
python manage.py runserver 0.0.0.0:8000
|
||||
```
|
||||
|
||||
### 5.2 API 文档
|
||||
|
||||
- Swagger UI：`/api/docs/`
|
||||
- ReDoc：`/api/redoc/`
|
||||
- OpenAPI Schema：`/api/schema/`
|
||||
|
||||
### 5.3 数据库初始化
|
||||
|
||||
```bash
|
||||
python manage.py makemigrations
|
||||
python manage.py migrate
|
||||
python manage.py createsuperuser
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 文档索引
|
||||
|
||||
| 文档 | 内容 |
|
||||
|------|------|
|
||||
| [使用指南](usage.md) | 各模块使用方法和代码示例 |
|
||||
| [架构说明](architecture.md) | 项目架构、数据流、设计原则 |
|
||||
| [开发指南](development.md) | 环境搭建、开发约定 |
|
||||
| [DJAPI 接口](api.md) | Django API 端点参考 |
|
||||
| [日报查询 API](news_report_api.md) | news/reports + news/events 接口 |
|
||||
| [日报数据库](db_schema_v1.1.md) | news_report / news_event 表结构 |
|
||||
Reference in New Issue
Block a user