# 环境配置快速指南

## 📋 配置步骤

### 1. 创建配置文件

如果您是首次使用，请复制模板文件：

```bash
# Windows PowerShell
Copy-Item .env.example .env

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

### 2. 配置必填项

#### ✅ DeepSeek API配置（必填）

1. 访问 [DeepSeek Platform](https://platform.deepseek.com/api_keys)
2. 注册/登录账号
3. 创建API密钥
4. 在`.env`文件中填写：

```env
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

### 3. 配置可选项

#### 📧 邮件通知配置（推荐）

**配置示例（163邮箱）：**

```env
EMAIL_ENABLED=true
SMTP_SERVER=smtp.163.com
SMTP_PORT=465
EMAIL_FROM=your_email@163.com
EMAIL_PASSWORD=your_authorization_code
EMAIL_TO=receiver@qq.com
```

**获取邮箱授权码：**

1. **163邮箱**
   - 登录163邮箱网页版
   - 设置 → POP3/SMTP/IMAP
   - 开启"POP3/SMTP服务"
   - 点击"生成授权码"
   - 复制授权码（16位字符）

2. **QQ邮箱**
   - 登录QQ邮箱网页版
   - 设置 → 账户
   - 找到"POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务"
   - 开启"POP3/SMTP服务"
   - 点击"生成授权码"
   - 按提示完成验证

**常用SMTP配置：**

| 邮箱类型 | SMTP服务器 | SSL端口 | TLS端口 |
|---------|-----------|---------|---------|
| 163邮箱 | smtp.163.com | 465 | 587 |
| QQ邮箱 | smtp.qq.com | 465 | 587 |
| Gmail | smtp.gmail.com | 465 | 587 |
| 126邮箱 | smtp.126.com | 465 | 587 |

#### 📱 Webhook通知配置（可选）

**钉钉机器人配置：**

1. 在钉钉群中添加自定义机器人
2. 安全设置选择"自定义关键词"
3. **关键词必须设置为：`aiagents通知`**
4. 复制Webhook地址
5. 在`.env`文件中填写：

```env
WEBHOOK_ENABLED=true
WEBHOOK_TYPE=dingtalk
WEBHOOK_URL=https://oapi.dingtalk.com/robot/send?access_token=xxxxxx
```

**飞书机器人配置：**

1. 在飞书群中添加自定义机器人
2. 复制Webhook地址
3. 在`.env`文件中填写：

```env
WEBHOOK_ENABLED=true
WEBHOOK_TYPE=feishu
WEBHOOK_URL=https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxx
```

#### 📊 Tushare数据接口（可选）

1. 访问 [Tushare官网](https://tushare.pro/register)
2. 注册账号
3. 获取Token
4. 在`.env`文件中填写：

```env
TUSHARE_TOKEN=your_tushare_token_here
```

#### 💹 MiniQMT量化交易（可选）

如果您使用MiniQMT进行量化交易：

```env
MINIQMT_ENABLED=true
MINIQMT_ACCOUNT_ID=your_account_id
MINIQMT_HOST=127.0.0.1
MINIQMT_PORT=58610
```

## 🧪 配置测试

配置完成后，运行测试工具验证配置：

```bash
# Windows
.\venv\Scripts\python.exe test_notification_config.py

# Linux/Mac
python test_notification_config.py
```

**测试结果示例：**

```
============================================================
通知配置测试工具
============================================================

[邮件] 测试邮件配置
  - 启用状态: [已启用]
  - SMTP服务器: smtp.163.com
  - 配置完整性: [完整]
[成功] 测试邮件发送成功！

[Webhook] 测试Webhook配置
  - 启用状态: [已启用]
  - Webhook类型: dingtalk
  - 配置完整性: [完整]
[成功] 钉钉Webhook测试成功！

============================================================
测试结果汇总
============================================================
邮件通知: [OK] 正常
Webhook通知: [OK] 正常
```

## ⚠️ 常见问题

### Q1: 邮件发送失败 - 认证错误

**问题**：`SMTPAuthenticationError`

**解决方案**：
- 确认使用的是**授权码**，不是登录密码
- 检查邮箱是否开启了POP3/SMTP服务
- 163邮箱授权码需要在邮箱设置中生成

### Q2: 钉钉消息发送失败 - 关键词不匹配

**问题**：`关键词不匹配`

**解决方案**：
- 确保钉钉机器人的自定义关键词设置为：**`aiagents通知`**
- 或者修改机器人安全设置为"加签"或"IP地址"

### Q3: 网络连接失败

**问题**：`getaddrinfo failed` 或 `Connection timeout`

**解决方案**：
- 检查网络连接
- 检查防火墙设置
- 确认SMTP服务器地址正确
- 尝试使用不同的端口（465或587）

### Q4: .env文件中文乱码

**问题**：编辑器显示中文乱码

**解决方案**：
- 使用UTF-8编码打开文件
- VS Code：右下角点击编码 → 选择"UTF-8"
- 记事本：另存为时选择"UTF-8"编码

## 📁 配置文件说明

```
.env.example    # 配置模板（提交到版本控制）
.env           # 实际配置（不提交到版本控制，包含敏感信息）
```

## 🔐 安全建议

1. **不要提交.env文件到版本控制系统**
   - `.env`文件已在`.gitignore`中
   - 只提交`.env.example`模板

2. **定期更换密钥**
   - 建议定期更换API密钥和授权码
   - 如发现泄露，立即更换

3. **权限控制**
   - 限制`.env`文件的访问权限
   - 不要在公开场合分享配置信息

## 📚 相关文档

- [邮件配置指南.md](邮件配置指南.md) - 详细的邮件配置说明
- [Webhook通知配置指南.md](Webhook通知配置指南.md) - Webhook配置详解
- [通知功能修复说明.md](通知功能修复说明.md) - 问题排查指南

## 🆘 需要帮助？

如遇到问题：
1. 运行测试工具查看详细错误信息
2. 查看相关文档
3. 检查系统日志
4. 参考常见问题解答

---

**更新时间**: 2025-10-14  
**版本**: v1.0