feat: 初始化考培练系统项目
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
This commit is contained in:
111
256
docs/规划/全链路联调/Ai工作流/dify/Dify_API_Keys_配置管理经验.md
Normal file
256
docs/规划/全链路联调/Ai工作流/dify/Dify_API_Keys_配置管理经验.md
Normal file
@@ -0,0 +1,256 @@
|
||||
# Dify API Keys 配置管理经验
|
||||
|
||||
## 📅 更新时间
|
||||
2025-10-16
|
||||
|
||||
## 🎯 经验背景
|
||||
|
||||
在全链路联调阶段，发现代码中存在多处硬编码的 Dify API Keys，不利于维护和安全管理。本文档总结了统一配置管理的实施经验。
|
||||
|
||||
## ✅ 问题发现
|
||||
|
||||
### 硬编码问题
|
||||
|
||||
**发现位置**：`app/api/v1/exam.py`
|
||||
|
||||
```python
|
||||
# ❌ 硬编码的 API Key
|
||||
headers = {
|
||||
"Authorization": "Bearer app-tDlrmXyS9NtWCShsOx5FH49L",
|
||||
"Content-Type": "application/json",
|
||||
}
|
||||
```
|
||||
|
||||
**问题影响**：
|
||||
1. 更换 API Key 需要搜索全部代码
|
||||
2. 敏感信息暴露在代码中
|
||||
3. 不同环境无法灵活配置
|
||||
4. 版本控制中包含敏感信息
|
||||
|
||||
## 🔧 解决方案
|
||||
|
||||
### 1. 配置文件集中管理
|
||||
|
||||
**文件**：`app/core/config.py`
|
||||
|
||||
```python
|
||||
class Settings(BaseSettings):
|
||||
# Dify API 基础配置
|
||||
DIFY_API_BASE: Optional[str] = Field(default="http://dify.ireborn.com.cn/v1")
|
||||
|
||||
# 各工作流 API Keys
|
||||
DIFY_API_KEY: Optional[str] = Field(default="app-LZhZcMO6CiriLMOLB2PwUGHx") # 上传知识库
|
||||
DIFY_EXAM_GENERATOR_API_KEY: str = Field(default="app-tDlrmXyS9NtWCShsOx5FH49L") # 试题生成器
|
||||
DIFY_ANSWER_JUDGE_API_KEY: str = Field(default="app-FvMdrvbRBz547DVZEorgO1WT") # 答案判断器
|
||||
DIFY_PRACTICE_API_KEY: Optional[str] = Field(default="app-rYP6LNM4iPmNjIHns12zFeJp") # 陪练场景提取
|
||||
DIFY_PRACTICE_ANALYSIS_API_KEY: str = Field(default="app-9MWaCEiRegpYGQLov4S9oQjh") # 陪练分析报告
|
||||
DIFY_COURSE_CHAT_API_KEY: str = Field(default="app-lJzD6COkL8z7Eez8t6ZrYoJS") # 与课程对话
|
||||
DIFY_YANJI_ANALYSIS_API_KEY: str = Field(default="app-g0I5UT8lBB0fvuxGDOqrG8Zj") # 智能工牌分析
|
||||
```
|
||||
|
||||
### 2. 代码重构
|
||||
|
||||
**重构前**：
|
||||
```python
|
||||
headers = {
|
||||
"Authorization": "Bearer app-tDlrmXyS9NtWCShsOx5FH49L",
|
||||
"Content-Type": "application/json",
|
||||
}
|
||||
```
|
||||
|
||||
**重构后**：
|
||||
```python
|
||||
from app.core.config import settings
|
||||
|
||||
headers = {
|
||||
"Authorization": f"Bearer {settings.DIFY_EXAM_GENERATOR_API_KEY}",
|
||||
"Content-Type": "application/json",
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 配置验证脚本
|
||||
|
||||
创建验证脚本 `verify_dify_config.py`：
|
||||
|
||||
```python
|
||||
from app.core.config import settings
|
||||
|
||||
def verify_dify_config():
|
||||
"""验证所有 Dify 配置"""
|
||||
configs = [
|
||||
("API Base URL", "DIFY_API_BASE", settings.DIFY_API_BASE),
|
||||
("上传知识库", "DIFY_API_KEY", settings.DIFY_API_KEY),
|
||||
("试题生成器", "DIFY_EXAM_GENERATOR_API_KEY", settings.DIFY_EXAM_GENERATOR_API_KEY),
|
||||
# ... 其他配置项
|
||||
]
|
||||
|
||||
all_valid = True
|
||||
for name, var_name, value in configs:
|
||||
if not value:
|
||||
print(f"❌ {name}: 配置缺失")
|
||||
all_valid = False
|
||||
else:
|
||||
print(f"✅ {name}: 已配置")
|
||||
|
||||
return all_valid
|
||||
```
|
||||
|
||||
## 📋 完整工作流清单
|
||||
|
||||
| 工作流名称 | 配置变量 | API Key |
|
||||
|-----------|---------|---------|
|
||||
| 上传知识库 | `DIFY_API_KEY` | `app-LZhZcMO6CiriLMOLB2PwUGHx` |
|
||||
| 试题生成器 | `DIFY_EXAM_GENERATOR_API_KEY` | `app-tDlrmXyS9NtWCShsOx5FH49L` |
|
||||
| 答案判断器 | `DIFY_ANSWER_JUDGE_API_KEY` | `app-FvMdrvbRBz547DVZEorgO1WT` |
|
||||
| 陪练场景提取 | `DIFY_PRACTICE_API_KEY` | `app-rYP6LNM4iPmNjIHns12zFeJp` |
|
||||
| 陪练分析报告 | `DIFY_PRACTICE_ANALYSIS_API_KEY` | `app-9MWaCEiRegpYGQLov4S9oQjh` |
|
||||
| 与课程对话 | `DIFY_COURSE_CHAT_API_KEY` | `app-lJzD6COkL8z7Eez8t6ZrYoJS` |
|
||||
| 智能工牌分析 | `DIFY_YANJI_ANALYSIS_API_KEY` | `app-g0I5UT8lBB0fvuxGDOqrG8Zj` |
|
||||
|
||||
## 💡 最佳实践
|
||||
|
||||
### 1. 命名规范
|
||||
- 统一前缀：`DIFY_`
|
||||
- 功能描述：`EXAM_GENERATOR`、`ANSWER_JUDGE`
|
||||
- 后缀：`_API_KEY`
|
||||
- 示例：`DIFY_EXAM_GENERATOR_API_KEY`
|
||||
|
||||
### 2. 类型注解
|
||||
```python
|
||||
# ✅ 推荐：使用明确的类型注解
|
||||
DIFY_EXAM_GENERATOR_API_KEY: str = Field(default="app-xxx")
|
||||
|
||||
# ⚠️ 可选配置使用 Optional
|
||||
DIFY_API_KEY: Optional[str] = Field(default="app-xxx")
|
||||
```
|
||||
|
||||
### 3. 环境变量覆盖
|
||||
```bash
|
||||
# .env 文件
|
||||
DIFY_EXAM_GENERATOR_API_KEY=app-new-key-for-dev
|
||||
DIFY_ANSWER_JUDGE_API_KEY=app-new-key-for-dev
|
||||
```
|
||||
|
||||
### 4. 安全管理
|
||||
```gitignore
|
||||
# .gitignore 必须包含
|
||||
.env
|
||||
.env.local
|
||||
.env.*.local
|
||||
```
|
||||
|
||||
## 🔍 排查经验
|
||||
|
||||
### 1. 查找硬编码 API Keys
|
||||
|
||||
```bash
|
||||
# 搜索所有 app- 开头的字符串
|
||||
grep -r "app-[A-Za-z0-9]" --include="*.py" app/
|
||||
|
||||
# 搜索 Bearer 后跟 app-
|
||||
grep -r "Bearer app-" --include="*.py" app/
|
||||
```
|
||||
|
||||
### 2. 验证配置生效
|
||||
|
||||
```bash
|
||||
# 运行验证脚本
|
||||
python verify_dify_config.py
|
||||
|
||||
# 预期输出
|
||||
✅ 所有 Dify 配置验证通过！
|
||||
```
|
||||
|
||||
### 3. 调试配置加载
|
||||
|
||||
```python
|
||||
# 临时添加调试日志
|
||||
import logging
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
logger.debug(f"DIFY_EXAM_GENERATOR_API_KEY: {settings.DIFY_EXAM_GENERATOR_API_KEY[:20]}...")
|
||||
```
|
||||
|
||||
## ⚠️ 注意事项
|
||||
|
||||
### 1. 不要提交敏感信息
|
||||
```bash
|
||||
# 检查暂存区
|
||||
git diff --cached | grep -i "app-"
|
||||
|
||||
# 如果误提交，使用 git filter-branch 清理历史
|
||||
```
|
||||
|
||||
### 2. 环境隔离
|
||||
- 开发环境：使用测试 API Keys
|
||||
- 生产环境：使用正式 API Keys
|
||||
- 通过环境变量区分
|
||||
|
||||
### 3. API Key 轮换
|
||||
定期轮换 API Keys，步骤：
|
||||
1. 在 Dify 平台生成新 Key
|
||||
2. 更新配置文件
|
||||
3. 重启服务验证
|
||||
4. 废弃旧 Key
|
||||
|
||||
### 4. 权限最小化
|
||||
- 每个工作流使用独立 API Key
|
||||
- 便于权限管理和问题追踪
|
||||
- 避免一个 Key 的泄露影响所有功能
|
||||
|
||||
## 📊 实施效果
|
||||
|
||||
### 改进前
|
||||
- ❌ 3 处硬编码 API Keys
|
||||
- ❌ 修改需要搜索全部代码
|
||||
- ❌ 无法按环境区分配置
|
||||
- ❌ 安全风险高
|
||||
|
||||
### 改进后
|
||||
- ✅ 统一在配置文件管理
|
||||
- ✅ 一处修改全局生效
|
||||
- ✅ 支持环境变量覆盖
|
||||
- ✅ 提供验证脚本
|
||||
- ✅ 完善的文档说明
|
||||
|
||||
## 🔗 相关文档
|
||||
|
||||
- [Dify API Keys 配置说明](/root/aiedu/kaopeilian-backend/docs/dify_api_keys.md)
|
||||
- [Dify 系统对接分析报告](/root/aiedu/Dify系统对接分析报告.md)
|
||||
- [配置更新总结](/root/aiedu/DIFY_API_KEYS_UPDATE_SUMMARY.md)
|
||||
|
||||
## 📝 更新日志
|
||||
|
||||
| 日期 | 变更内容 | 影响范围 |
|
||||
|------|---------|---------|
|
||||
| 2025-10-16 | 添加试题生成器和答案判断器 API Keys | `app/api/v1/exam.py` |
|
||||
| 2025-10-16 | 移除硬编码，统一使用配置变量 | `app/api/v1/exam.py` |
|
||||
| 2025-10-16 | 创建配置验证脚本 | 新增 `verify_dify_config.py` |
|
||||
| 2025-10-16 | 创建配置文档 | 新增 `docs/dify_api_keys.md` |
|
||||
|
||||
## 🎓 经验总结
|
||||
|
||||
1. **早期规划很重要**：在项目初期就应该统一配置管理规范
|
||||
2. **代码审查必不可少**：定期检查是否有新的硬编码出现
|
||||
3. **自动化验证**：使用脚本自动验证配置完整性
|
||||
4. **文档同步更新**：配置变更时必须同步更新文档
|
||||
5. **安全意识**：敏感信息绝不提交到版本控制
|
||||
|
||||
## 🚀 后续优化建议
|
||||
|
||||
1. **CI/CD 集成**：
|
||||
- 在部署流程中添加配置验证步骤
|
||||
- 配置缺失时阻止部署
|
||||
|
||||
2. **密钥管理服务**：
|
||||
- 考虑使用 AWS Secrets Manager 或 HashiCorp Vault
|
||||
- 实现动态密钥轮换
|
||||
|
||||
3. **监控告警**：
|
||||
- API Key 即将过期时发送告警
|
||||
- API 调用失败时检查 Key 是否有效
|
||||
|
||||
4. **权限审计**：
|
||||
- 定期审计 API Key 使用情况
|
||||
- 发现异常调用及时处理
|
||||
|
||||
Reference in New Issue
Block a user