# 部署说明

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 表结构 |