239 lines
6.1 KiB
Markdown
239 lines
6.1 KiB
Markdown
# 系统性优化方案 - 2026-04-03
|
||
|
||
## 待处理问题
|
||
|
||
| # | 类别 | 问题 | 严重度 | 优先级 |
|
||
|---|------|------|--------|--------|
|
||
| 1 | 前端 | OAuth auth_url 缺少 origin 验证 | MEDIUM | P1 |
|
||
| 2 | 前端 | API 响应缺少运行时类型验证 | MEDIUM | P2 |
|
||
| 3 | 后端 | 缓存击穿 (cache stampede) 风险 | MEDIUM | P2 |
|
||
| 4 | 后端 | Webhook 服务 Goroutine 生命周期管理 | MEDIUM | P2 |
|
||
|
||
---
|
||
|
||
## 1. OAuth auth_url 缺少 origin 验证
|
||
|
||
### 问题描述
|
||
`window.location.assign(result.auth_url)` 直接使用后端返回的 `auth_url`，未验证其 origin 是否属于可信域。
|
||
|
||
**风险**: 后端被攻击或配置错误时可能返回恶意 URL 导致用户被重定向到钓鱼站点。
|
||
|
||
**受影响文件**:
|
||
- `frontend/admin/src/pages/auth/LoginPage/LoginPage.tsx:137-141`
|
||
- `frontend/admin/src/pages/admin/ProfileSecurityPage/ProfileSecurityPage.tsx:195-205`
|
||
|
||
### 修复方案
|
||
|
||
在 `oauth.ts` 添加 origin 验证函数：
|
||
|
||
```typescript
|
||
export function validateOAuthUrl(authUrl: string): boolean {
|
||
try {
|
||
const url = new URL(authUrl)
|
||
// 仅允许同源或已知可信 OAuth 提供商
|
||
const trustedOrigins = [
|
||
'https://github.com',
|
||
'https://google.com',
|
||
'https://facebook.com',
|
||
// ... 其他可信提供商
|
||
]
|
||
return url.origin === window.location.origin ||
|
||
trustedOrigins.includes(url.origin)
|
||
} catch {
|
||
return false
|
||
}
|
||
}
|
||
```
|
||
|
||
然后在调用前验证：
|
||
|
||
```typescript
|
||
const result = await getOAuthAuthorizationUrl(provider, ...)
|
||
if (!validateOAuthUrl(result.auth_url)) {
|
||
throw new Error('Invalid OAuth authorization URL')
|
||
}
|
||
window.location.assign(result.auth_url)
|
||
```
|
||
|
||
### 验证方式
|
||
- 单元测试覆盖恶意 URL 场景
|
||
- E2E 测试验证重定向行为
|
||
|
||
---
|
||
|
||
## 2. API 响应缺少运行时类型验证
|
||
|
||
### 问题描述
|
||
`parseJsonResponse` 使用 TypeScript 类型断言 (`as ApiResponse<T>`)，不验证运行时响应结构。`result.data` 可能是 `undefined`。
|
||
|
||
**受影响文件**:
|
||
- `frontend/admin/src/lib/http/client.ts:87-89, 240-245`
|
||
|
||
### 修复方案
|
||
|
||
添加运行时验证：
|
||
|
||
```typescript
|
||
interface ApiResponse<T> {
|
||
code: number
|
||
message: string
|
||
data?: T
|
||
}
|
||
|
||
function isApiResponse(obj: unknown): obj is ApiResponse<unknown> {
|
||
if (typeof obj !== 'object' || obj === null) return false
|
||
const r = obj as Record<string, unknown>
|
||
return typeof r.code === 'number' && typeof r.message === 'string'
|
||
}
|
||
|
||
async function parseJsonResponse<T>(response: Response): Promise<T> {
|
||
const raw = await response.json()
|
||
|
||
if (!isApiResponse(raw)) {
|
||
throw new Error('Invalid API response structure')
|
||
}
|
||
|
||
if (raw.code !== 0) {
|
||
throw AppError.fromResponse(raw, response.status)
|
||
}
|
||
|
||
if (raw.data === undefined) {
|
||
throw new Error('API response missing data field')
|
||
}
|
||
|
||
return raw.data as T
|
||
}
|
||
```
|
||
|
||
### 验证方式
|
||
- 用 mock 测试验证无效响应被正确拒绝
|
||
- 用有效响应验证数据正确解析
|
||
|
||
---
|
||
|
||
## 3. 缓存击穿 (Cache Stampede) 风险
|
||
|
||
### 问题描述
|
||
`AuthMiddleware.isJTIBlacklisted` 在 L1 cache miss 时，所有并发请求同时打 L2 (Redis)，无 singleflight 保护。
|
||
|
||
**受影响文件**:
|
||
- `internal/api/middleware/auth.go:113-130`
|
||
|
||
### 修复方案
|
||
|
||
使用 `golang.org/x/sync/singleflight`：
|
||
|
||
```go
|
||
import "golang.org/x/sync/singleflight"
|
||
|
||
var sfGroup singleflight.Group
|
||
|
||
func (m *AuthMiddleware) isJTIBlacklisted(jti string) bool {
|
||
if jti == "" {
|
||
return false
|
||
}
|
||
|
||
key := "jwt_blacklist:" + jti
|
||
if _, ok := m.l1Cache.Get(key); ok {
|
||
return true
|
||
}
|
||
|
||
if m.cacheManager != nil {
|
||
// 使用 singleflight 防止缓存击穿
|
||
val, err := sfGroup.Do(key, func() (interface{}, error) {
|
||
return m.cacheManager.Get(context.Background(), key)
|
||
})
|
||
if err == nil && val != nil {
|
||
return true
|
||
}
|
||
}
|
||
|
||
return false
|
||
}
|
||
```
|
||
|
||
### 验证方式
|
||
- 并发测试验证 singleflight 正确聚合请求
|
||
- 单元测试验证缓存未命中时行为正确
|
||
|
||
---
|
||
|
||
## 4. Webhook 服务 Goroutine 生命周期管理
|
||
|
||
### 问题描述
|
||
`WebhookService` 启动 worker pool 和 `time.AfterFunc` 重试，无 `Shutdown()` 方法。服务器关闭时 goroutine 被强制终止，可能丢失 delivery 记录。
|
||
|
||
**受影响文件**:
|
||
- `internal/service/webhook.go:110-123, 235-254`
|
||
|
||
### 修复方案
|
||
|
||
添加 `Shutdown` 方法：
|
||
|
||
```go
|
||
// Shutdown 优雅关闭 Webhook 服务
|
||
// 等待所有处理中的 delivery 完成，最多等待 timeout
|
||
func (s *WebhookService) Shutdown(ctx context.Context) error {
|
||
// 1. 停止接收新任务
|
||
close(s.queue)
|
||
|
||
// 2. 等待现有 worker 完成
|
||
done := make(chan struct{})
|
||
go func() {
|
||
s.wg.Wait()
|
||
close(done)
|
||
}()
|
||
|
||
select {
|
||
case <-done:
|
||
// 正常完成
|
||
case <-ctx.Done():
|
||
return ctx.Err()
|
||
}
|
||
|
||
// 3. 清理 AfterFunc 重试（可选：等待或取消）
|
||
// time.AfterFunc 无法直接取消，但 goroutine 会在下一次执行时检查 shutdown 状态
|
||
|
||
return nil
|
||
}
|
||
```
|
||
|
||
在 `main.go` 的服务器关闭逻辑中调用：
|
||
|
||
```go
|
||
// 创建带超时的 context
|
||
shutdownCtx, shutdownCancel := context.WithTimeout(context.Background(), 30*time.Second)
|
||
defer shutdownCancel()
|
||
|
||
// 关闭 Webhook 服务
|
||
if err := webhookSvc.Shutdown(shutdownCtx); err != nil {
|
||
log.Printf("Webhook service shutdown error: %v", err)
|
||
}
|
||
```
|
||
|
||
### 验证方式
|
||
- 单元测试验证 Shutdown 等待 worker 完成
|
||
- 集成测试验证关闭时 delivery 记录不丢失
|
||
|
||
---
|
||
|
||
## 优先级排序
|
||
|
||
| 优先级 | 问题 | 理由 |
|
||
|--------|------|------|
|
||
| P1 | OAuth origin 验证 | 直接影响用户安全，有实际攻击面 |
|
||
| P2 | 缓存击穿 | 高并发场景下影响性能，不是立即安全问题 |
|
||
| P2 | API 响应验证 | 数据一致性，但现有代码已有基础校验 |
|
||
| P2 | Webhook 生命周期 | 关闭时可能丢数据，但不是高频场景 |
|
||
|
||
---
|
||
|
||
## 验证矩阵
|
||
|
||
| 问题 | go build | go test | npm run build | 手动验证 |
|
||
|------|----------|---------|---------------|----------|
|
||
| OAuth origin | - | 需要补充测试 | - | E2E |
|
||
| API 响应验证 | - | 需要补充测试 | - | 单元测试 |
|
||
| 缓存击穿 | ✅ | 需要补充测试 | - | 并发测试 |
|
||
| Webhook shutdown | ✅ | 需要补充测试 | - | 集成测试 |
|