# taiji-AI-PAD 环境变量配置说明

**版本**: v1.2.1  
**最后更新**: 2025年12月22日

## 📋 概述

为了简化配置管理，所有 API Key 和敏感信息现在统一在 `.env` 文件中管理。您只需要在一个地方填写所有密钥，无需在多个配置文件中重复填写。

## 🚀 快速开始

### 1. 创建环境变量文件

如果项目中没有 `.env` 文件，请复制模板：

```bash
cp .env.example .env
```

### 2. 编辑 `.env` 文件

打开 `.env` 文件，填写您的实际 API Key：

```bash
nano .env
# 或使用您喜欢的编辑器
```

### 3. 配置项说明

#### 必需配置项

| 配置项 | 说明 | 示例 |
|--------|------|------|
| `OPENROUTER_API_KEY` | OpenRouter API 密钥 | `sk-or-v1-...` |
| `RAPIDAPI_KEY` | RapidAPI 密钥 | `33902cc39dmsh...` |
| `LITELLM_MASTER_KEY` | LiteLLM 主密钥 | `sk-taiji-master-key` |

#### 可选配置项

| 配置项 | 说明 | 何时需要 |
|--------|------|----------|
| `OPENAI_API_KEY` | OpenAI API 密钥 | 使用 OpenAI 模型时 |
| `ANTHROPIC_API_KEY` | Anthropic API 密钥 | 使用 Claude 模型时 |
| `LANGFUSE_*` | Langfuse 监控配置 | 启用监控功能时 |

## 📝 当前配置的密钥位置

### ✅ 已统一管理的密钥

以下密钥现在都在 `.env` 文件中：

1. **OpenRouter API Key** - 用于模型网关
2. **RapidAPI Key** - 用于数据接入服务
3. **LiteLLM Master Key** - 用于模型网关认证

### 📍 配置文件位置

- **`.env`** - 实际环境变量文件（包含真实密钥，已加入 .gitignore）
- **`.env.example`** - 配置模板文件（可提交到 Git）
- **`docker-compose.yml`** - 使用 `${VAR}` 语法引用环境变量

## 🔧 如何添加新的 API Key

### 步骤 1: 在 `.env` 文件中添加

```bash
# 在 .env 文件中添加
NEW_API_KEY=your-new-api-key-here
```

### 步骤 2: 在 `docker-compose.yml` 中引用

```yaml
services:
  your-service:
    environment:
      - NEW_API_KEY=${NEW_API_KEY}
```

### 步骤 3: 在代码中读取

```python
import os
api_key = os.getenv("NEW_API_KEY", "")
```

## 🔒 安全注意事项

1. **⚠️ 永远不要提交 `.env` 文件到 Git**
   - `.env` 文件已在 `.gitignore` 中
   - 只提交 `.env.example` 作为模板

2. **生产环境建议**
   - 使用密钥管理服务（如 AWS Secrets Manager）
   - 使用环境变量注入（如 Kubernetes Secrets）
   - 定期轮换 API Key

3. **权限控制**
   - 确保 `.env` 文件权限为 `600`（仅所有者可读写）
   ```bash
   chmod 600 .env
   ```

## 📊 配置项清单

### 当前已配置的密钥

- ✅ OpenRouter API Key
- ✅ RapidAPI Key
- ✅ LiteLLM Master Key

### 可选配置的密钥

- ⚪ OpenAI API Key（如需要直接使用 OpenAI）
- ⚪ Anthropic API Key（如需要直接使用 Anthropic）
- ⚪ Langfuse 监控密钥（如需要启用监控）

## 🧪 验证配置

配置完成后，验证环境变量是否正确加载：

```bash
# 检查环境变量
docker-compose config | grep -E "OPENROUTER|RAPIDAPI|LITELLM"

# 重启服务以应用新配置
docker-compose restart litellm-gateway data-ingestion

# 检查服务健康状态
curl http://localhost:4000/health  # LiteLLM Gateway
curl http://localhost:8001/health  # Data Ingestion
```

## 📚 相关文档

- [Docker Compose 环境变量文档](https://docs.docker.com/compose/environment-variables/)
- [项目 README](../README.md)
- [测试准备说明](./测试准备说明.md)

## ❓ 常见问题

### Q: 为什么需要 `.env` 文件？

A: `.env` 文件可以：
- 集中管理所有密钥
- 避免在代码中硬编码敏感信息
- 方便不同环境使用不同配置
- 提高安全性（不提交到 Git）

### Q: 如何在不同环境使用不同配置？

A: 可以创建多个环境文件：
- `.env.development` - 开发环境
- `.env.production` - 生产环境
- `.env.testing` - 测试环境

然后使用：
```bash
docker-compose --env-file .env.production up
```

### Q: 忘记填写某个 Key 会怎样？

A: 如果某个环境变量未设置，Docker Compose 会使用空字符串或默认值。服务可能会启动失败或功能受限。请检查服务日志：
```bash
docker-compose logs service-name
```