daily_stock_analysis/DEPLOYMENT_GUIDE.md

# 📘 股票智能分析系统 - 部署运行指南

> 本文档涵盖项目的启动方式、部署方式及注意事项

---

## 📋 目录

1. [快速启动](#一快速启动)
2. [启动方式](#二启动方式)
3. [部署方式](#三部署方式)
4. [注意事项](#四注意事项)
5. [常见问题](#五常见问题)

---

## 一、快速启动

### 1.1 环境要求

| 组件 | 最低要求 | 推荐版本 |
|------|----------|----------|
| Python | 3.10+ | 3.11.x |
| Node.js | 18+ | 20.x |
| Docker | 20.10+ | 最新版 |
| 内存 | 512MB | 1GB+ |
| 磁盘 | 1GB | 5GB+ |

### 1.2 最小配置

复制配置文件并填写必要信息：

```bash
# Windows
copy .env.example .env

# Linux/Mac
cp .env.example .env
```

编辑 `.env` 文件，至少配置以下项：

```env
# 1. 自选股列表（必填）
STOCK_LIST=600519,300750,002594

# 2. AI 模型（二选一）
# 方案 A: Gemini（免费）
GEMINI_API_KEY=your_gemini_key

# 方案 B: OpenAI 兼容 API（如 DeepSeek）
OPENAI_API_KEY=your_key
OPENAI_BASE_URL=https://api.deepseek.com/v1
OPENAI_MODEL=deepseek-chat

# 3. 通知渠道（至少一个）
WECHAT_WEBHOOK_URL=https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx
# 或
EMAIL_SENDER=your_email@qq.com
EMAIL_PASSWORD=your_auth_code
```

---

## 二、启动方式

### 2.1 命令行模式

#### 基本命令

```bash
# 安装依赖
pip install -r requirements.txt

# 仅获取数据（测试模式，不消耗 AI 额度）
python main.py --dry-run

# 完整运行（执行 AI 分析）
python main.py

# 调试模式（输出详细日志）
python main.py --debug

# 指定分析特定股票
python main.py --stocks 600519,000001

# 不发送推送通知
python main.py --no-notify

# 单股推送模式（每分析完一只立即推送）
python main.py --single-notify

# 仅运行大盘复盘
python main.py --market-review
```

#### 启动 WebUI

```bash
# 编译前端（首次需要）
cd apps/dsa-web
npm install
npm run build
cd ../..

# 启动 WebUI + 定时分析
python main.py --webui

# 仅启动 WebUI（不执行分析）
python main.py --webui-only

# 或使用等效命令
python main.py --serve
python main.py --serve-only
```

访问地址：http://127.0.0.1:8000

#### 定时任务模式

```bash
# 启用定时任务（每日自动执行）
python main.py --schedule

# 自定义执行时间（默认 18:00）
SCHEDULE_TIME=09:30 python main.py --schedule
```

### 2.2 参数说明

| 参数 | 说明 |
|------|------|
| `--dry-run` | 仅获取数据，不进行 AI 分析 |
| `--debug` | 启用调试模式，输出详细日志 |
| `--stocks` | 指定股票代码，逗号分隔 |
| `--no-notify` | 不发送推送通知 |
| `--single-notify` | 单股推送模式 |
| `--schedule` | 启用定时任务 |
| `--market-review` | 仅运行大盘复盘 |
| `--webui` | 启动 WebUI + 定时分析 |
| `--webui-only` | 仅启动 WebUI |
| `--serve` | 启动 API 服务 |
| `--serve-only` | 仅启动 API 服务 |
| `--host` | 绑定地址（默认 127.0.0.1） |
| `--port` | 端口（默认 8000） |

---

## 三、部署方式

### 3.1 GitHub Actions 部署（推荐）

**优点**：零成本、免服务器、自动定时运行

#### 部署步骤

1. **Fork 仓库**
   - 点击右上角 `Fork` 按钮

2. **配置 Secrets**
   ```
   Settings → Secrets and variables → Actions → New repository secret
   ```

3. **添加必要 Secrets**

   | Secret 名称 | 说明 | 必填 |
   |------------|------|:----:|
   | `STOCK_LIST` | 自选股代码 | ✅ |
   | `GEMINI_API_KEY` 或 `OPENAI_API_KEY` | AI 模型 API Key | ✅ |
   | `WECHAT_WEBHOOK_URL` / `EMAIL_SENDER` | 通知渠道 | ✅ |

4. **启用 Actions**
   ```
   Actions 标签 → I understand my workflows, go ahead and enable them
   ```

5. **手动测试**
   ```
   Actions → 每日股票分析 → Run workflow → Run workflow
   ```

**默认定时**：工作日 18:00（北京时间）自动执行

### 3.2 Docker 部署

#### 快速启动

```bash
# 1. 克隆仓库
git clone https://github.com/ZhuLinsen/daily_stock_analysis.git
cd daily_stock_analysis

# 2. 配置环境变量
cp .env.example .env
# 编辑 .env 填入配置

# 3. 启动容器
# Web 服务模式（推荐，提供 API 与 WebUI）
docker-compose -f ./docker/docker-compose.yml up -d server

# 定时任务模式
docker-compose -f ./docker/docker-compose.yml up -d analyzer

# 同时启动两种模式
docker-compose -f ./docker/docker-compose.yml up -d
```

#### 访问服务

| 服务 | 地址 |
|------|------|
| WebUI | http://localhost:8000 |
| API | http://localhost:8000/api |

#### 常用命令

```bash
# 查看日志
docker-compose -f ./docker/docker-compose.yml logs -f server
docker-compose -f ./docker/docker-compose.yml logs -f analyzer

# 停止服务
docker-compose -f ./docker/docker-compose.yml down

# 重启服务
docker-compose -f ./docker/docker-compose.yml restart server

# 更新镜像（拉取代码后）
docker-compose -f ./docker/docker-compose.yml up -d --build

# 进入容器
docker exec -it stock-server /bin/bash
```

#### Docker 运行模式

| 模式 | 命令 | 说明 |
|------|------|------|
| Web 服务 | `up -d server` | 提供 WebUI 和 API |
| 定时分析 | `up -d analyzer` | 每日自动执行分析 |
| 双模式 | `up -d` | 同时启动两种模式 |

### 3.3 本地服务器部署

#### Linux/Mac 系统

```bash
# 1. 克隆项目
git clone https://github.com/ZhuLinsen/daily_stock_analysis.git
cd daily_stock_analysis

# 2. 创建虚拟环境
python -m venv venv
source venv/bin/activate

# 3. 安装依赖
pip install -r requirements.txt

# 4. 编译前端
cd apps/dsa-web
npm install
npm run build
cd ../..

# 5. 配置环境
cp .env.example .env
vim .env

# 6. 启动服务
# 方式 A: 直接运行
python main.py --webui

# 方式 B: 使用 systemd（推荐生产环境）
sudo nano /etc/systemd/system/stock-analysis.service
```

**systemd 服务配置示例**：

```ini
[Unit]
Description=Stock Analysis Service
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/daily_stock_analysis
Environment=PYTHONUNBUFFERED=1
ExecStart=/home/ubuntu/daily_stock_analysis/venv/bin/python main.py --webui
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

启动服务：
```bash
sudo systemctl daemon-reload
sudo systemctl enable stock-analysis
sudo systemctl start stock-analysis
sudo systemctl status stock-analysis
```

#### Windows 系统

```powershell
# 1. 克隆项目
git clone https://github.com/ZhuLinsen/daily_stock_analysis.git
cd daily_stock_analysis

# 2. 安装依赖
pip install -r requirements.txt

# 3. 编译前端
cd apps\dsa-web
npm install
npm run build
cd ..\..

# 4. 配置环境
copy .env.example .env
# 编辑 .env

# 5. 启动
python main.py --webui
```

**使用 NSSM 注册 Windows 服务**（生产环境）：

```powershell
# 下载 NSSM: https://nssm.cc/download
nssm install stock-analysis
# 设置 Path: python
# 设置 Arguments: main.py --webui
# 设置 Working directory: D:\daily_stock_analysis

nssm start stock-analysis
```

### 3.4 部署方式对比

| 部署方式 | 复杂度 | 成本 | 适用场景 | 稳定性 |
|----------|--------|------|----------|--------|
| GitHub Actions | ⭐ 低 | 免费 | 个人用户、轻度使用 | ⭐⭐⭐ |
| Docker | ⭐⭐ 中 | 低 | 有服务器的用户 | ⭐⭐⭐⭐ |
| 本地服务器 | ⭐⭐⭐ 高 | 中 | 企业用户、高频使用 | ⭐⭐⭐⭐⭐ |
| 云服务器 | ⭐⭐ 中 | 中 | 需要 24h 在线服务 | ⭐⭐⭐⭐⭐ |

---

## 四、注意事项

### 4.1 安全配置

#### API Key 保护

```bash
# ❌ 不要这样做
# 在代码中硬编码 API Key
# 提交 .env 到 Git 仓库

# ✅ 正确做法
# 使用环境变量
# 将 .env 加入 .gitignore
# GitHub Actions 使用 Secrets
```

#### 最小权限原则

| 服务 | 建议权限 |
|------|----------|
| AI API Key | 仅文本生成权限 |
| 邮件授权码 | 仅 SMTP 发送权限 |
| Tushare Token | 仅行情数据权限 |

### 4.2 性能优化

#### 并发控制

```env
# .env 中配置
MAX_WORKERS=3  # 根据机器性能调整，建议 2-5
```

#### API 限流处理

```env
# 个股分析和大盘分析之间的延迟（秒）
ANALYSIS_DELAY=10

# Gemini 请求延迟
GEMINI_REQUEST_DELAY=30
```

#### 内存优化（Docker）

```yaml
# docker-compose.yml
deploy:
  resources:
    limits:
      memory: 512M
    reservations:
      memory: 256M
```

### 4.3 数据备份

```bash
# 数据库备份（SQLite）
cp data/stock_analysis.db backup/stock_analysis_$(date +%Y%m%d).db

# 日志归档
tar -czf logs_backup_$(date +%Y%m%d).tar.gz logs/

# Docker 数据卷备份
docker run --rm -v daily_stock_analysis_data:/data -v $(pwd):/backup alpine tar czf /backup/data_backup.tar.gz -C /data .
```

### 4.4 监控与日志

#### 日志位置

| 部署方式 | 日志路径 |
|----------|----------|
| 本地运行 | `./logs/` |
| Docker | `/app/logs/` 或挂载的宿主机目录 |
| GitHub Actions | Actions 运行日志 |

#### 关键日志文件

```
logs/
├── stock_analysis_YYYYMMDD.log      # 常规日志
├── stock_analysis_debug_YYYYMMDD.log # 调试日志
└── notifications_YYYYMMDD.log        # 推送日志
```

#### 健康检查

```bash
# API 健康检查
curl http://localhost:8000/api/health

# Docker 健康检查（自动）
docker ps  # 查看 STATUS 列
```

### 4.5 网络与代理

```env
# 国内用户可能需要代理访问 Gemini/OpenAI
USE_PROXY=true
PROXY_HOST=127.0.0.1
PROXY_PORT=10809

# Docker 代理配置
# docker-compose.yml 中 environment 部分
- http_proxy=http://host.docker.internal:10809
- https_proxy=http://host.docker.internal:10809
```

### 4.6 时区设置

```env
# .env 中设置
TZ=Asia/Shanghai

# Docker 中已默认设置上海时区
```

---

## 五、常见问题

### Q1: Windows 下中文显示乱码？

```powershell
# 设置 UTF-8 编码
chcp 65001

# 或在运行前设置环境变量
$env:PYTHONIOENCODING="utf-8"
python main.py
```

### Q2: 前端页面 404？

```bash
# 需要编译前端
cd apps/dsa-web
npm install
npm run build
```

### Q3: Docker 启动失败？

```bash
# 检查端口占用
netstat -tlnp | grep 8000

# 检查环境变量
cat .env | grep -E "^(STOCK_LIST|OPENAI|GEMINI)"

# 查看详细日志
docker-compose logs
```

### Q4: API 额度不足？

- **Gemini**: 免费版有额度限制，建议申请多个 Key 轮换使用
- **DeepSeek**: 充值或降低分析频率
- **本地模型**: 使用 Ollama 部署本地大模型

### Q5: 推送收不到？

1. 检查 Webhook URL 是否正确
2. 检查网络连通性：`curl -v WEBHOOK_URL`
3. 查看通知日志：`logs/notifications_*.log`
4. 确认消息长度未超限（企业微信 4096 字节）

### Q6: 数据获取失败？

```bash
# 检查数据源状态
python -c "from data_provider.base import DataFetcherManager; m = DataFetcherManager(); print(m.list_fetchers())"

# 单个数据源测试
python -c "from data_provider.tushare_fetcher import TushareFetcher; f = TushareFetcher(); print(f.test_connection())"
```

---

## 六、参考链接

- [完整配置指南](docs/full-guide.md)
- [常见问题](docs/FAQ.md)
- [更新日志](docs/CHANGELOG.md)
- [项目主页](https://github.com/ZhuLinsen/daily_stock_analysis)

---

**免责声明**: 本项目仅供学习和研究使用，不构成任何投资建议。股市有风险，投资需谨慎。