CONFIGURATION_SYSTEM.md

统一配置系统说明

JetBrains AI Proxy现在采用了全新的统一配置系统，实现了自动配置发现、多种配置方式支持和配置热重载等功能。

🏗️ 系统架构

核心组件

1. ConfigManager (internal/config/config.go)

   • 统一的配置管理器
   • 支持多种配置源的合并
   • 线程安全的配置访问
   • 配置验证和默认值处理

2. ConfigDiscovery (internal/config/discovery.go)

   • 自动配置文件发现
   • 配置文件格式验证
   • 配置文件监控和热重载
   • 示例配置生成

3. JWTBalancer (internal/balancer/jwt_balancer.go)

   • JWT负载均衡器
   • 支持轮询和随机策略
   • 并发安全的token管理
   • 动态token更新

4. HealthChecker (internal/balancer/health_checker.go)

   • JWT健康检查器
   • 自动故障检测和恢复
   • 可配置的检查间隔
   • 并发健康检查

📁 文件结构

jetbrains-ai-proxy/
├── main.go                          # 主程序，支持新配置系统
├── start.sh                         # 智能启动脚本
├── CONFIGURATION_SYSTEM.md          # 配置系统说明（本文件）
├── MULTI_JWT_README.md              # 多JWT功能说明
├── internal/
│   ├── config/
│   │   ├── config.go                # 配置管理器
│   │   └── discovery.go             # 配置发现器
│   ├── balancer/
│   │   ├── jwt_balancer.go          # JWT负载均衡器
│   │   ├── health_checker.go        # 健康检查器
│   │   └── jwt_balancer_test.go     # 测试用例
│   └── jetbrains/
│       └── client.go                # 集成配置系统的客户端
└── examples/
    ├── complete_example.md          # 完整使用示例
    ├── start_with_multiple_jwt.sh   # 多JWT启动脚本
    └── .env.example                 # 环境变量示例

⚙️ 配置优先级

系统按以下优先级加载和合并配置：

1. 命令行参数 (最高优先级)
2. 环境变量
3. 配置文件
4. 默认值 (最低优先级)

🔍 配置发现机制

系统会按以下顺序搜索配置文件：

1. CONFIG_FILE 环境变量指定的路径
2. 当前目录：config.json, jetbrains-ai-proxy.json
3. config目录：config/config.json, configs/config.json
4. 隐藏目录：.config/config.json
5. 用户主目录：$HOME/.config/jetbrains-ai-proxy/config.json
6. 系统目录：/etc/jetbrains-ai-proxy/config.json

如果没有找到配置文件，系统会自动生成示例配置。

🚀 使用方式

1. 自动配置（推荐）

# 生成示例配置
./jetbrains-ai-proxy --generate-config

# 编辑配置文件
vim config/config.json

# 启动服务（自动发现配置）
./jetbrains-ai-proxy

2. 使用启动脚本

# 智能启动（自动检查配置）
./start.sh

# 生成配置
./start.sh --generate

# 查看配置
./start.sh --config

3. 指定配置文件

# 使用特定配置文件
./jetbrains-ai-proxy --config /path/to/config.json

# 或设置环境变量
export CONFIG_FILE=/path/to/config.json
./jetbrains-ai-proxy

📋 配置文件格式

JSON配置文件示例

{
  "jetbrains_tokens": [
    {
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
      "name": "Primary_JWT",
      "description": "Primary JWT token for JetBrains AI",
      "priority": 1,
      "metadata": {
        "environment": "production",
        "region": "us-east-1"
      }
    }
  ],
  "bearer_token": "your_bearer_token_here",
  "load_balance_strategy": "round_robin",
  "health_check_interval": "30s",
  "server_port": 8080,
  "server_host": "0.0.0.0"
}

环境变量配置

# JWT Tokens（逗号分隔）
JWT_TOKENS=token1,token2,token3

# Bearer Token
BEARER_TOKEN=your_bearer_token

# 负载均衡策略
LOAD_BALANCE_STRATEGY=round_robin

# 服务器配置
SERVER_HOST=0.0.0.0
SERVER_PORT=8080

# 配置文件路径（可选）
CONFIG_FILE=config/config.json

🔄 配置热重载

系统支持运行时配置重载，无需重启服务：

自动重载

配置文件监控器会自动检测配置文件变化并重新加载。

手动重载

# 通过API端点重载
curl -X POST http://localhost:8080/reload

# 响应
{
  "message": "Configuration reloaded successfully"
}

🛠️ 管理端点

系统提供了丰富的管理端点：

端点	方法	描述
/health	GET	健康检查和负载均衡状态
/config	GET	当前配置信息（隐藏敏感数据）
/stats	GET	详细统计信息
/reload	POST	重新加载配置

🔧 高级功能

1. JWT Token元数据

支持为每个JWT token配置元数据：

{
  "token": "jwt_token_here",
  "name": "Production_Primary",
  "description": "Primary production JWT token",
  "priority": 1,
  "metadata": {
    "environment": "production",
    "region": "us-east-1",
    "tier": "primary",
    "max_requests_per_minute": "1000"
  }
}

2. 配置验证

系统会自动验证配置的有效性：

• JWT token格式检查
• 必需字段验证
• 数值范围检查
• 策略有效性验证

3. 配置合并策略

多个配置源的合并规则：

• 数组类型：高优先级完全覆盖低优先级
• 对象类型：递归合并，高优先级字段覆盖低优先级
• 基本类型：高优先级直接覆盖低优先级

🚨 故障排除

配置问题诊断

# 查看当前配置
./jetbrains-ai-proxy --print-config

# 验证配置文件
./jetbrains-ai-proxy --config config.json --print-config

# 生成新的示例配置
./jetbrains-ai-proxy --generate-config

常见问题

1. 配置文件未找到

   • 检查文件路径和权限
   • 使用 --generate-config 生成示例配置

2. JWT tokens无效

   • 检查token格式和有效性
   • 查看健康检查日志

3. 配置合并问题

   • 使用 --print-config 查看最终配置
   • 检查配置优先级

📈 性能考虑

1. 配置缓存: 配置在内存中缓存，避免重复读取
2. 并发安全: 使用读写锁保护配置访问
3. 懒加载: 配置发现器按需加载配置文件
4. 监控优化: 配置文件监控使用高效的文件系统事件

🔮 未来扩展

系统设计支持以下扩展：

• 远程配置中心集成（如Consul、etcd）
• 配置加密和安全存储
• 配置版本管理和回滚
• 更多负载均衡策略
• 动态配置更新API