Skip to content

Commit 35d6445

Browse files
committed
docs: 整合配置文档并简化项目结构
- 将配置示例和模板直接整合到 README.md 中,提供完整的 KIRO_AUTH_TOKEN 配置指南 - 增强 CLAUDE.md 中的环境变量配置示例,添加详细的使用说明和故障排除指导 - 删除独立的配置示例文件,减少文档维护负担,遵循 KISS 原则 - 清理 auth/token.go 中未使用的 refreshTokenAndReturn 函数,遵循 YAGNI 原则 - 统一配置文档结构,提高用户体验和维护效率
1 parent d14876c commit 35d6445

File tree

5 files changed

+141
-469
lines changed

5 files changed

+141
-469
lines changed

CLAUDE.md

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -63,8 +63,19 @@ docker-compose up -d # 启动服务
6363
cp .env.example .env
6464

6565
# === Token管理配置(推荐使用JSON格式) ===
66-
# 新的JSON格式配置方式,支持多认证方式和多token
67-
KIRO_AUTH_TOKEN='[{"auth":"Social","refreshToken":"xxx"},{"auth":"IdC","refreshToken":"xxx","clientId":"xxx","clientSecret":"xxx"}]'
66+
# 新的JSON格式配置方式,支持多认证方式和多token。
67+
#
68+
# 示例 1: 单个 Social 认证
69+
# KIRO_AUTH_TOKEN='[{"auth":"Social","refreshToken":"your_social_refresh_token"}]'
70+
#
71+
# 示例 2: 混合认证 (Social + IdC)
72+
# KIRO_AUTH_TOKEN='[{"auth":"Social","refreshToken":"social_token"},{"auth":"IdC","refreshToken":"idc_token","clientId":"idc_client","clientSecret":"idc_secret"}]'
73+
#
74+
# 示例 3: 多个 Social 认证 (用于负载均衡)
75+
# KIRO_AUTH_TOKEN='[{"auth":"Social","refreshToken":"token1"},{"auth":"Social","refreshToken":"token2"}]'
76+
#
77+
# 默认配置结构:
78+
KIRO_AUTH_TOKEN='[{"auth":"Social","refreshToken":"xxx"},{"auth":"IdC","refreshToken":"xxx","clientId":"xxx","clientSecret":"xxx"}]''''
6879
6980
# === 兼容传统环境变量(向后兼容) ===
7081
# AWS_REFRESHTOKEN=token1,token2,token3 # 支持逗号分隔多token

README.md

Lines changed: 128 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -138,8 +138,134 @@ curl -N -X POST http://localhost:8080/v1/messages \
138138

139139
#### 方式一:JSON配置(推荐)
140140

141-
> 📖 **详细配置说明**: 更多配置示例和说明请参考 [`config-examples/kiro_auth_token_examples.md`](./config-examples/kiro_auth_token_examples.md)
142-
> 🚀 **快速开始**: 可复制的配置模板请参考 [`config-examples/quick-start-templates.md`](./config-examples/quick-start-templates.md)
141+
<details>
142+
<summary>点击展开/折叠详细的 JSON 配置示例、模板和迁移指南</summary>
143+
144+
### KIRO_AUTH_TOKEN 快速配置模板
145+
146+
#### 基础配置(复制使用)
147+
148+
**1. 单个 Social 认证**
149+
```bash
150+
KIRO_AUTH_TOKEN='[
151+
{
152+
"auth": "Social",
153+
"refreshToken": "YOUR_SOCIAL_REFRESH_TOKEN"
154+
}
155+
]'
156+
KIRO_CLIENT_TOKEN=123456
157+
PORT=8080
158+
```
159+
160+
**2. 单个 IdC 认证**
161+
```bash
162+
KIRO_AUTH_TOKEN='[
163+
{
164+
"auth": "IdC",
165+
"refreshToken": "YOUR_IDC_REFRESH_TOKEN",
166+
"clientId": "YOUR_IDC_CLIENT_ID",
167+
"clientSecret": "YOUR_IDC_CLIENT_SECRET"
168+
}
169+
]'
170+
KIRO_CLIENT_TOKEN=123456
171+
PORT=8080
172+
```
173+
174+
**3. 多个 Social 认证(负载均衡)**
175+
```bash
176+
KIRO_AUTH_TOKEN='[
177+
{
178+
"auth": "Social",
179+
"refreshToken": "SOCIAL_TOKEN_1"
180+
},
181+
{
182+
"auth": "Social",
183+
"refreshToken": "SOCIAL_TOKEN_2"
184+
},
185+
{
186+
"auth": "Social",
187+
"refreshToken": "SOCIAL_TOKEN_3"
188+
}
189+
]'
190+
KIRO_CLIENT_TOKEN=123456
191+
PORT=8080
192+
TOKEN_SELECTION_STRATEGY=balanced
193+
```
194+
195+
**4. 混合认证(生产环境推荐)**
196+
```bash
197+
KIRO_AUTH_TOKEN='[
198+
{
199+
"auth": "Social",
200+
"refreshToken": "SOCIAL_TOKEN_PRIMARY"
201+
},
202+
{
203+
"auth": "Social",
204+
"refreshToken": "SOCIAL_TOKEN_BACKUP"
205+
},
206+
{
207+
"auth": "IdC",
208+
"refreshToken": "IDC_TOKEN_ENTERPRISE",
209+
"clientId": "IDC_CLIENT_ID",
210+
"clientSecret": "IDC_CLIENT_SECRET"
211+
}
212+
]'
213+
KIRO_CLIENT_TOKEN=your-secure-api-key
214+
PORT=8080
215+
TOKEN_SELECTION_STRATEGY=balanced
216+
TOKEN_USAGE_THRESHOLD=5
217+
LOG_LEVEL=info
218+
```
219+
220+
### KIRO_AUTH_TOKEN 配置详解
221+
222+
#### 基本结构
223+
224+
```json
225+
[
226+
{
227+
"auth": "认证方式",
228+
"refreshToken": "刷新令牌",
229+
"clientId": "客户端ID(IdC方式必需)",
230+
"clientSecret": "客户端密钥(IdC方式必需)"
231+
}
232+
]
233+
```
234+
235+
#### 字段说明
236+
237+
| 字段 | 类型 | 必需 | 说明 |
238+
|------|------|------|------|
239+
| `Auth` | string || 认证方式,支持 "Social" 或 "IdC" |
240+
| `RefreshToken` | string || AWS 刷新令牌 |
241+
| `ClientId` | string | IdC时必需 | IdC 认证的客户端 ID |
242+
| `ClientSecret` | string | IdC时必需 | IdC 认证的客户端密钥 |
243+
244+
#### 认证方式说明
245+
246+
- **Social 认证**: 适用于个人开发者和小型项目, 只需要 `RefreshToken`
247+
- **IdC 认证**: 适用于企业环境, 需要 `RefreshToken``ClientId``ClientSecret`
248+
249+
### 从传统环境变量迁移
250+
251+
如果您当前使用传统的环境变量配置 (`AWS_REFRESHTOKEN=token1,token2`), 可以迁移到新的 JSON 格式:
252+
253+
```bash
254+
# 新配置
255+
KIRO_AUTH_TOKEN='[
256+
{"auth": "Social", "refreshToken": "token1"},
257+
{"auth": "Social", "refreshToken": "token2"}
258+
]'
259+
```
260+
> **注意**: 系统保持向后兼容,旧的环境变量配置仍然可以使用。
261+
262+
### 验证与故障排除
263+
264+
启动服务后,检查日志中是否有 `Token配置加载成功` 的信息。
265+
如果遇到 `解析KIRO_AUTH_TOKEN失败` 的错误, 请使用在线 JSON 验证器检查格式。
266+
如果遇到 `IdC认证缺少必需参数` 的错误, 请为 IdC 认证添加 `ClientId``ClientSecret`
267+
268+
</details>
143269

144270
```bash
145271
# 新的JSON格式配置,支持多认证方式和多token

auth/token.go

Lines changed: 0 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -223,38 +223,6 @@ func getRefreshManager() *utils.TokenRefreshManager {
223223
return refreshManager
224224
}
225225

226-
// refreshTokenAndReturn 刷新token并返回TokenInfo,使用token池进行轮换
227-
func refreshTokenAndReturn() (types.TokenInfo, error) {
228-
pool := getTokenPool()
229-
if pool == nil {
230-
return types.TokenInfo{}, fmt.Errorf("token池未初始化")
231-
}
232-
233-
// 使用token池进行轮换
234-
for {
235-
refreshToken, tokenIdx, hasToken := pool.GetNextToken()
236-
if !hasToken {
237-
logger.Error("所有refresh token都已达到最大重试次数")
238-
return types.TokenInfo{}, fmt.Errorf("所有refresh token都已达到最大重试次数")
239-
}
240-
241-
logger.Debug("尝试使用refresh token", logger.Int("token_index", tokenIdx+1))
242-
243-
// 根据认证方式尝试刷新token
244-
tokenInfo, err := tryRefreshTokenByAuthMethod(refreshToken)
245-
if err != nil {
246-
logger.Error("Token刷新失败", logger.Err(err), logger.Int("token_index", tokenIdx+1))
247-
pool.MarkTokenFailed(tokenIdx)
248-
continue
249-
}
250-
251-
// 刷新成功,重置失败计数
252-
pool.MarkTokenSuccess(tokenIdx)
253-
logger.Info("Token刷新成功", logger.Int("token_index", tokenIdx+1))
254-
return tokenInfo, nil
255-
}
256-
}
257-
258226
// tryRefreshTokenByAuthMethod 根据认证方式刷新token
259227
func tryRefreshTokenByAuthMethod(refreshToken string) (types.TokenInfo, error) {
260228
// 从配置中找到对应的refresh token配置

0 commit comments

Comments
 (0)