feat(api-key): add IP whitelist/blacklist restriction and usage log IP tracking

- Add IP restriction feature for API keys (whitelist/blacklist with CIDR support)
- Add IP address logging to usage logs (admin-only visibility)
- Remove billing_type column from usage logs UI (redundant)
- Use generic "Access denied" error message for security

Backend:
- New ip package with IP/CIDR validation and matching utilities
- Database migrations for ip_whitelist, ip_blacklist (api_keys) and ip_address (usage_logs)
- Middleware IP restriction check after API key validation
- Input validation for IP/CIDR patterns on create/update

Frontend:
- API key form with enable toggle for IP restriction
- Shield icon indicator in table for keys with IP restriction
- Removed billing_type filter and column from usage views

backend/internal/handler/openai_gateway_handler.go

@@ -11,6 +11,7 @@ import (
 	"time"
 
 	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/ip"
 	"github.com/Wei-Shaw/sub2api/internal/pkg/openai"
 	middleware2 "github.com/Wei-Shaw/sub2api/internal/server/middleware"
 	"github.com/Wei-Shaw/sub2api/internal/service"
@@ -94,6 +95,10 @@ func (h *OpenAIGatewayHandler) Responses(c *gin.Context) {
 
 	// For non-Codex CLI requests, set default instructions
 	userAgent := c.GetHeader("User-Agent")
+
+	// 获取客户端 IP
+	clientIP := ip.GetClientIP(c)
+
 	if !openai.IsCodexCLIRequest(userAgent) {
 		reqBody["instructions"] = openai.DefaultInstructions
 		// Re-serialize body
@@ -242,7 +247,7 @@ func (h *OpenAIGatewayHandler) Responses(c *gin.Context) {
 		}
 
 		// Async record usage
-		go func(result *service.OpenAIForwardResult, usedAccount *service.Account, ua string) {
+		go func(result *service.OpenAIForwardResult, usedAccount *service.Account, ua string, cip string) {
 			ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
 			defer cancel()
 			if err := h.gatewayService.RecordUsage(ctx, &service.OpenAIRecordUsageInput{
@@ -252,10 +257,11 @@ func (h *OpenAIGatewayHandler) Responses(c *gin.Context) {
 				Account:      usedAccount,
 				Subscription: subscription,
 				UserAgent:    ua,
+				IPAddress:    cip,
 			}); err != nil {
 				log.Printf("Record usage failed: %v", err)
 			}
-		}(result, account, userAgent)
+		}(result, account, userAgent, clientIP)
 		return
 	}
 }

backend/internal/pkg/ip/ip.go

+// Package ip 提供客户端 IP 地址提取工具。
+package ip
+
+import (
+	"net"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+)
+
+// GetClientIP 从 Gin Context 中提取客户端真实 IP 地址。
+// 按以下优先级检查 Header：
+// 1. CF-Connecting-IP (Cloudflare)
+// 2. X-Real-IP (Nginx)
+// 3. X-Forwarded-For (取第一个非私有 IP)
+// 4. c.ClientIP() (Gin 内置方法)
+func GetClientIP(c *gin.Context) string {
+	// 1. Cloudflare
+	if ip := c.GetHeader("CF-Connecting-IP"); ip != "" {
+		return normalizeIP(ip)
+	}
+
+	// 2. Nginx X-Real-IP
+	if ip := c.GetHeader("X-Real-IP"); ip != "" {
+		return normalizeIP(ip)
+	}
+
+	// 3. X-Forwarded-For (多个 IP 时取第一个公网 IP)
+	if xff := c.GetHeader("X-Forwarded-For"); xff != "" {
+		ips := strings.Split(xff, ",")
+		for _, ip := range ips {
+			ip = strings.TrimSpace(ip)
+			if ip != "" && !isPrivateIP(ip) {
+				return normalizeIP(ip)
+			}
+		}
+		// 如果都是私有 IP，返回第一个
+		if len(ips) > 0 {
+			return normalizeIP(strings.TrimSpace(ips[0]))
+		}
+	}
+
+	// 4. Gin 内置方法
+	return normalizeIP(c.ClientIP())
+}
+
+// normalizeIP 规范化 IP 地址，去除端口号和空格。
+func normalizeIP(ip string) string {
+	ip = strings.TrimSpace(ip)
+	// 移除端口号（如 "192.168.1.1:8080" -> "192.168.1.1"）
+	if host, _, err := net.SplitHostPort(ip); err == nil {
+		return host
+	}
+	return ip
+}
+
+// isPrivateIP 检查 IP 是否为私有地址。
+func isPrivateIP(ipStr string) bool {
+	ip := net.ParseIP(ipStr)
+	if ip == nil {
+		return false
+	}
+
+	// 私有 IP 范围
+	privateBlocks := []string{
+		"10.0.0.0/8",
+		"172.16.0.0/12",
+		"192.168.0.0/16",
+		"127.0.0.0/8",
+		"::1/128",
+		"fc00::/7",
+	}
+
+	for _, block := range privateBlocks {
+		_, cidr, err := net.ParseCIDR(block)
+		if err != nil {
+			continue
+		}
+		if cidr.Contains(ip) {
+			return true
+		}
+	}
+	return false
+}
+
+// MatchesPattern 检查 IP 是否匹配指定的模式（支持单个 IP 或 CIDR）。
+// pattern 可以是：
+// - 单个 IP: "192.168.1.100"
+// - CIDR 范围: "192.168.1.0/24"
+func MatchesPattern(clientIP, pattern string) bool {
+	ip := net.ParseIP(clientIP)
+	if ip == nil {
+		return false
+	}
+
+	// 尝试解析为 CIDR
+	if strings.Contains(pattern, "/") {
+		_, cidr, err := net.ParseCIDR(pattern)
+		if err != nil {
+			return false
+		}
+		return cidr.Contains(ip)
+	}
+
+	// 作为单个 IP 处理
+	patternIP := net.ParseIP(pattern)
+	if patternIP == nil {
+		return false
+	}
+	return ip.Equal(patternIP)
+}
+
+// MatchesAnyPattern 检查 IP 是否匹配任意一个模式。
+func MatchesAnyPattern(clientIP string, patterns []string) bool {
+	for _, pattern := range patterns {
+		if MatchesPattern(clientIP, pattern) {
+			return true
+		}
+	}
+	return false
+}
+
+// CheckIPRestriction 检查 IP 是否被 API Key 的 IP 限制允许。
+// 返回值：(是否允许, 拒绝原因)
+// 逻辑：
+// 1. 先检查黑名单，如果在黑名单中则直接拒绝
+// 2. 如果白名单不为空，IP 必须在白名单中
+// 3. 如果白名单为空，允许访问（除非被黑名单拒绝）
+func CheckIPRestriction(clientIP string, whitelist, blacklist []string) (bool, string) {
+	// 规范化 IP
+	clientIP = normalizeIP(clientIP)
+	if clientIP == "" {
+		return false, "access denied"
+	}
+
+	// 1. 检查黑名单
+	if len(blacklist) > 0 && MatchesAnyPattern(clientIP, blacklist) {
+		return false, "access denied"
+	}
+
+	// 2. 检查白名单（如果设置了白名单，IP 必须在其中）
+	if len(whitelist) > 0 && !MatchesAnyPattern(clientIP, whitelist) {
+		return false, "access denied"
+	}
+
+	return true, ""
+}
+
+// ValidateIPPattern 验证 IP 或 CIDR 格式是否有效。
+func ValidateIPPattern(pattern string) bool {
+	if strings.Contains(pattern, "/") {
+		_, _, err := net.ParseCIDR(pattern)
+		return err == nil
+	}
+	return net.ParseIP(pattern) != nil
+}
+
+// ValidateIPPatterns 验证多个 IP 或 CIDR 格式。
+// 返回无效的模式列表。
+func ValidateIPPatterns(patterns []string) []string {
+	var invalid []string
+	for _, p := range patterns {
+		if !ValidateIPPattern(p) {
+			invalid = append(invalid, p)
+		}
+	}
+	return invalid
+}

backend/internal/repository/api_key_repo.go

@@ -26,13 +26,21 @@ func (r *apiKeyRepository) activeQuery() *dbent.APIKeyQuery {
 }
 
 func (r *apiKeyRepository) Create(ctx context.Context, key *service.APIKey) error {
-	created, err := r.client.APIKey.Create().
+	builder := r.client.APIKey.Create().
 		SetUserID(key.UserID).
 		SetKey(key.Key).
 		SetName(key.Name).
 		SetStatus(key.Status).
-		SetNillableGroupID(key.GroupID).
-		Save(ctx)
+		SetNillableGroupID(key.GroupID)
+
+	if len(key.IPWhitelist) > 0 {
+		builder.SetIPWhitelist(key.IPWhitelist)
+	}
+	if len(key.IPBlacklist) > 0 {
+		builder.SetIPBlacklist(key.IPBlacklist)
+	}
+
+	created, err := builder.Save(ctx)
 	if err == nil {
 		key.ID = created.ID
 		key.CreatedAt = created.CreatedAt
@@ -108,6 +116,18 @@ func (r *apiKeyRepository) Update(ctx context.Context, key *service.APIKey) erro
 		builder.ClearGroupID()
 	}
 
+	// IP 限制字段
+	if len(key.IPWhitelist) > 0 {
+		builder.SetIPWhitelist(key.IPWhitelist)
+	} else {
+		builder.ClearIPWhitelist()
+	}
+	if len(key.IPBlacklist) > 0 {
+		builder.SetIPBlacklist(key.IPBlacklist)
+	} else {
+		builder.ClearIPBlacklist()
+	}
+
 	affected, err := builder.Save(ctx)
 	if err != nil {
 		return err
@@ -268,14 +288,16 @@ func apiKeyEntityToService(m *dbent.APIKey) *service.APIKey {
 		return nil
 	}
 	out := &service.APIKey{
-		ID:        m.ID,
-		UserID:    m.UserID,
-		Key:       m.Key,
-		Name:      m.Name,
-		Status:    m.Status,
-		CreatedAt: m.CreatedAt,
-		UpdatedAt: m.UpdatedAt,
-		GroupID:   m.GroupID,
+		ID:          m.ID,
+		UserID:      m.UserID,
+		Key:         m.Key,
+		Name:        m.Name,
+		Status:      m.Status,
+		IPWhitelist: m.IPWhitelist,
+		IPBlacklist: m.IPBlacklist,
+		CreatedAt:   m.CreatedAt,
+		UpdatedAt:   m.UpdatedAt,
+		GroupID:     m.GroupID,
 	}
 	if m.Edges.User != nil {
 		out.User = userEntityToService(m.Edges.User)

backend/internal/repository/usage_log_repo.go

@@ -22,7 +22,7 @@ import (
 	"github.com/lib/pq"
 )
 
-const usageLogSelectColumns = "id, user_id, api_key_id, account_id, request_id, model, group_id, subscription_id, input_tokens, output_tokens, cache_creation_tokens, cache_read_tokens, cache_creation_5m_tokens, cache_creation_1h_tokens, input_cost, output_cost, cache_creation_cost, cache_read_cost, total_cost, actual_cost, rate_multiplier, billing_type, stream, duration_ms, first_token_ms, user_agent, image_count, image_size, created_at"
+const usageLogSelectColumns = "id, user_id, api_key_id, account_id, request_id, model, group_id, subscription_id, input_tokens, output_tokens, cache_creation_tokens, cache_read_tokens, cache_creation_5m_tokens, cache_creation_1h_tokens, input_cost, output_cost, cache_creation_cost, cache_read_cost, total_cost, actual_cost, rate_multiplier, billing_type, stream, duration_ms, first_token_ms, user_agent, ip_address, image_count, image_size, created_at"
 
 type usageLogRepository struct {
 	client *dbent.Client
@@ -110,6 +110,7 @@ func (r *usageLogRepository) Create(ctx context.Context, log *service.UsageLog)
 			duration_ms,
 			first_token_ms,
 			user_agent,
+			ip_address,
 			image_count,
 			image_size,
 			created_at
@@ -119,7 +120,7 @@ func (r *usageLogRepository) Create(ctx context.Context, log *service.UsageLog)
 			$8, $9, $10, $11,
 			$12, $13,
 			$14, $15, $16, $17, $18, $19,
-		$20, $21, $22, $23, $24, $25, $26, $27, $28
+			$20, $21, $22, $23, $24, $25, $26, $27, $28, $29
 		)
 		ON CONFLICT (request_id, api_key_id) DO NOTHING
 		RETURNING id, created_at
@@ -130,6 +131,7 @@ func (r *usageLogRepository) Create(ctx context.Context, log *service.UsageLog)
 	duration := nullInt(log.DurationMs)
 	firstToken := nullInt(log.FirstTokenMs)
 	userAgent := nullString(log.UserAgent)
+	ipAddress := nullString(log.IPAddress)
 	imageSize := nullString(log.ImageSize)
 
 	var requestIDArg any
@@ -163,6 +165,7 @@ func (r *usageLogRepository) Create(ctx context.Context, log *service.UsageLog)
 		duration,
 		firstToken,
 		userAgent,
+		ipAddress,
 		log.ImageCount,
 		imageSize,
 		createdAt,
@@ -1873,6 +1876,7 @@ func scanUsageLog(scanner interface{ Scan(...any) error }) (*service.UsageLog, e
 		durationMs          sql.NullInt64
 		firstTokenMs        sql.NullInt64
 		userAgent           sql.NullString
+		ipAddress           sql.NullString
 		imageCount          int
 		imageSize           sql.NullString
 		createdAt           time.Time
@@ -1905,6 +1909,7 @@ func scanUsageLog(scanner interface{ Scan(...any) error }) (*service.UsageLog, e
 		&durationMs,
 		&firstTokenMs,
 		&userAgent,
+		&ipAddress,
 		&imageCount,
 		&imageSize,
 		&createdAt,
@@ -1959,6 +1964,9 @@ func scanUsageLog(scanner interface{ Scan(...any) error }) (*service.UsageLog, e
 	if userAgent.Valid {
 		log.UserAgent = &userAgent.String
 	}
+	if ipAddress.Valid {
+		log.IPAddress = &ipAddress.String
+	}
 	if imageSize.Valid {
 		log.ImageSize = &imageSize.String
 	}

backend/internal/server/middleware/api_key_auth.go

@@ -6,6 +6,7 @@ import (
 	"strings"
 
 	"github.com/Wei-Shaw/sub2api/internal/config"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/ip"
 	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	"github.com/gin-gonic/gin"
@@ -71,6 +72,17 @@ func apiKeyAuthWithSubscription(apiKeyService *service.APIKeyService, subscripti
 			return
 		}
 
+		// 检查 IP 限制（白名单/黑名单）
+		// 注意：错误信息故意模糊，避免暴露具体的 IP 限制机制
+		if len(apiKey.IPWhitelist) > 0 || len(apiKey.IPBlacklist) > 0 {
+			clientIP := ip.GetClientIP(c)
+			allowed, _ := ip.CheckIPRestriction(clientIP, apiKey.IPWhitelist, apiKey.IPBlacklist)
+			if !allowed {
+				AbortWithError(c, 403, "ACCESS_DENIED", "Access denied")
+				return
+			}
+		}
+
 		// 检查关联的用户
 		if apiKey.User == nil {
 			AbortWithError(c, 401, "USER_NOT_FOUND", "User associated with API key not found")

backend/internal/service/api_key.go

@@ -3,16 +3,18 @@ package service
 import "time"
 
 type APIKey struct {
-	ID        int64
-	UserID    int64
-	Key       string
-	Name      string
-	GroupID   *int64
-	Status    string
-	CreatedAt time.Time
-	UpdatedAt time.Time
-	User      *User
-	Group     *Group
+	ID          int64
+	UserID      int64
+	Key         string
+	Name        string
+	GroupID     *int64
+	Status      string
+	IPWhitelist []string
+	IPBlacklist []string
+	CreatedAt   time.Time
+	UpdatedAt   time.Time
+	User        *User
+	Group       *Group
 }
 
 func (k *APIKey) IsActive() bool {

backend/internal/service/api_key_service.go

@@ -9,6 +9,7 @@ import (
 
 	"github.com/Wei-Shaw/sub2api/internal/config"
 	infraerrors "github.com/Wei-Shaw/sub2api/internal/pkg/errors"
+	"github.com/Wei-Shaw/sub2api/internal/pkg/ip"
 	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
 	"github.com/Wei-Shaw/sub2api/internal/pkg/timezone"
 )
@@ -20,6 +21,7 @@ var (
 	ErrAPIKeyTooShort     = infraerrors.BadRequest("API_KEY_TOO_SHORT", "api key must be at least 16 characters")
 	ErrAPIKeyInvalidChars = infraerrors.BadRequest("API_KEY_INVALID_CHARS", "api key can only contain letters, numbers, underscores, and hyphens")
 	ErrAPIKeyRateLimited  = infraerrors.TooManyRequests("API_KEY_RATE_LIMITED", "too many failed attempts, please try again later")
+	ErrInvalidIPPattern   = infraerrors.BadRequest("INVALID_IP_PATTERN", "invalid IP or CIDR pattern")
 )
 
 const (
@@ -57,16 +59,20 @@ type APIKeyCache interface {
 
 // CreateAPIKeyRequest 创建API Key请求
 type CreateAPIKeyRequest struct {
-	Name      string  `json:"name"`
-	GroupID   *int64  `json:"group_id"`
-	CustomKey *string `json:"custom_key"` // 可选的自定义key
+	Name        string   `json:"name"`
+	GroupID     *int64   `json:"group_id"`
+	CustomKey   *string  `json:"custom_key"`   // 可选的自定义key
+	IPWhitelist []string `json:"ip_whitelist"` // IP 白名单
+	IPBlacklist []string `json:"ip_blacklist"` // IP 黑名单
 }
 
 // UpdateAPIKeyRequest 更新API Key请求
 type UpdateAPIKeyRequest struct {
-	Name    *string `json:"name"`
-	GroupID *int64  `json:"group_id"`
-	Status  *string `json:"status"`
+	Name        *string  `json:"name"`
+	GroupID     *int64   `json:"group_id"`
+	Status      *string  `json:"status"`
+	IPWhitelist []string `json:"ip_whitelist"` // IP 白名单（空数组清空）
+	IPBlacklist []string `json:"ip_blacklist"` // IP 黑名单（空数组清空）
 }
 
 // APIKeyService API Key服务
@@ -186,6 +192,20 @@ func (s *APIKeyService) Create(ctx context.Context, userID int64, req CreateAPIK
 		return nil, fmt.Errorf("get user: %w", err)
 	}
 
+	// 验证 IP 白名单格式
+	if len(req.IPWhitelist) > 0 {
+		if invalid := ip.ValidateIPPatterns(req.IPWhitelist); len(invalid) > 0 {
+			return nil, fmt.Errorf("%w: %v", ErrInvalidIPPattern, invalid)
+		}
+	}
+
+	// 验证 IP 黑名单格式
+	if len(req.IPBlacklist) > 0 {
+		if invalid := ip.ValidateIPPatterns(req.IPBlacklist); len(invalid) > 0 {
+			return nil, fmt.Errorf("%w: %v", ErrInvalidIPPattern, invalid)
+		}
+	}
+
 	// 验证分组权限（如果指定了分组）
 	if req.GroupID != nil {
 		group, err := s.groupRepo.GetByID(ctx, *req.GroupID)
@@ -236,11 +256,13 @@ func (s *APIKeyService) Create(ctx context.Context, userID int64, req CreateAPIK
 
 	// 创建API Key记录
 	apiKey := &APIKey{
-		UserID:  userID,
-		Key:     key,
-		Name:    req.Name,
-		GroupID: req.GroupID,
-		Status:  StatusActive,
+		UserID:      userID,
+		Key:         key,
+		Name:        req.Name,
+		GroupID:     req.GroupID,
+		Status:      StatusActive,
+		IPWhitelist: req.IPWhitelist,
+		IPBlacklist: req.IPBlacklist,
 	}
 
 	if err := s.apiKeyRepo.Create(ctx, apiKey); err != nil {
@@ -312,6 +334,20 @@ func (s *APIKeyService) Update(ctx context.Context, id int64, userID int64, req
 		return nil, ErrInsufficientPerms
 	}
 
+	// 验证 IP 白名单格式
+	if len(req.IPWhitelist) > 0 {
+		if invalid := ip.ValidateIPPatterns(req.IPWhitelist); len(invalid) > 0 {
+			return nil, fmt.Errorf("%w: %v", ErrInvalidIPPattern, invalid)
+		}
+	}
+
+	// 验证 IP 黑名单格式
+	if len(req.IPBlacklist) > 0 {
+		if invalid := ip.ValidateIPPatterns(req.IPBlacklist); len(invalid) > 0 {
+			return nil, fmt.Errorf("%w: %v", ErrInvalidIPPattern, invalid)
+		}
+	}
+
 	// 更新字段
 	if req.Name != nil {
 		apiKey.Name = *req.Name
@@ -344,6 +380,10 @@ func (s *APIKeyService) Update(ctx context.Context, id int64, userID int64, req
 		}
 	}
 
+	// 更新 IP 限制（空数组会清空设置）
+	apiKey.IPWhitelist = req.IPWhitelist
+	apiKey.IPBlacklist = req.IPBlacklist
+
 	if err := s.apiKeyRepo.Update(ctx, apiKey); err != nil {
 		return nil, fmt.Errorf("update api key: %w", err)
 	}

backend/internal/service/gateway_service.go

@@ -2247,6 +2247,7 @@ type RecordUsageInput struct {
 	Account      *Account
 	Subscription *UserSubscription // 可选：订阅信息
 	UserAgent    string            // 请求的 User-Agent
+	IPAddress    string            // 请求的客户端 IP 地址
 }
 
 // RecordUsage 记录使用量并扣费（或更新订阅用量）
@@ -2337,6 +2338,11 @@ func (s *GatewayService) RecordUsage(ctx context.Context, input *RecordUsageInpu
 		usageLog.UserAgent = &input.UserAgent
 	}
 
+	// 添加 IPAddress
+	if input.IPAddress != "" {
+		usageLog.IPAddress = &input.IPAddress
+	}
+
 	// 添加分组和订阅关联
 	if apiKey.GroupID != nil {
 		usageLog.GroupID = apiKey.GroupID

backend/internal/service/openai_gateway_service.go

@@ -1093,6 +1093,7 @@ type OpenAIRecordUsageInput struct {
 	Account      *Account
 	Subscription *UserSubscription
 	UserAgent    string // 请求的 User-Agent
+	IPAddress    string // 请求的客户端 IP 地址
 }
 
 // RecordUsage records usage and deducts balance
@@ -1167,6 +1168,11 @@ func (s *OpenAIGatewayService) RecordUsage(ctx context.Context, input *OpenAIRec
 		usageLog.UserAgent = &input.UserAgent
 	}
 
+	// 添加 IPAddress
+	if input.IPAddress != "" {
+		usageLog.IPAddress = &input.IPAddress
+	}
+
 	if apiKey.GroupID != nil {
 		usageLog.GroupID = apiKey.GroupID
 	}

backend/internal/service/usage_log.go

@@ -39,6 +39,7 @@ type UsageLog struct {
 	DurationMs   *int
 	FirstTokenMs *int
 	UserAgent    *string
+	IPAddress    *string
 
 	// 图片生成字段
 	ImageCount int

backend/migrations/031_add_ip_address.sql

+-- Add IP address field to usage_logs table for request tracking (admin-only visibility)
+ALTER TABLE usage_logs ADD COLUMN IF NOT EXISTS ip_address VARCHAR(45);
+
+-- Create index for IP address queries
+CREATE INDEX IF NOT EXISTS idx_usage_logs_ip_address ON usage_logs(ip_address);

backend/migrations/032_add_api_key_ip_restriction.sql

+-- Add IP restriction fields to api_keys table
+-- ip_whitelist: JSON array of allowed IPs/CIDRs (if set, only these IPs can use the key)
+-- ip_blacklist: JSON array of blocked IPs/CIDRs (these IPs are always blocked)
+
+ALTER TABLE api_keys ADD COLUMN IF NOT EXISTS ip_whitelist JSONB DEFAULT NULL;
+ALTER TABLE api_keys ADD COLUMN IF NOT EXISTS ip_blacklist JSONB DEFAULT NULL;
+
+COMMENT ON COLUMN api_keys.ip_whitelist IS 'JSON array of allowed IPs/CIDRs, e.g. ["192.168.1.100", "10.0.0.0/8"]';
+COMMENT ON COLUMN api_keys.ip_blacklist IS 'JSON array of blocked IPs/CIDRs, e.g. ["1.2.3.4", "5.6.0.0/16"]';

frontend/src/api/admin/usage.ts

@@ -64,7 +64,6 @@ export async function getStats(params: {
   group_id?: number
   model?: string
   stream?: boolean
-  billing_type?: number
   period?: string
   start_date?: string
   end_date?: string

frontend/src/api/keys.ts

@@ -42,12 +42,16 @@ export async function getById(id: number): Promise<ApiKey> {
  * @param name - Key name
  * @param groupId - Optional group ID
  * @param customKey - Optional custom key value
+ * @param ipWhitelist - Optional IP whitelist
+ * @param ipBlacklist - Optional IP blacklist
  * @returns Created API key
  */
 export async function create(
   name: string,
   groupId?: number | null,
-  customKey?: string
+  customKey?: string,
+  ipWhitelist?: string[],
+  ipBlacklist?: string[]
 ): Promise<ApiKey> {
   const payload: CreateApiKeyRequest = { name }
   if (groupId !== undefined) {
@@ -56,6 +60,12 @@ export async function create(
   if (customKey) {
     payload.custom_key = customKey
   }
+  if (ipWhitelist && ipWhitelist.length > 0) {
+    payload.ip_whitelist = ipWhitelist
+  }
+  if (ipBlacklist && ipBlacklist.length > 0) {
+    payload.ip_blacklist = ipBlacklist
+  }
 
   const { data } = await apiClient.post<ApiKey>('/keys', payload)
   return data

frontend/src/components/admin/usage/UsageFilters.vue

@@ -127,12 +127,6 @@
           <Select v-model="filters.stream" :options="streamTypeOptions" @change="emitChange" />
         </div>
 
-        <!-- Billing Type Filter -->
-        <div class="w-full sm:w-auto sm:min-w-[180px]">
-          <label class="input-label">{{ t('usage.billingType') }}</label>
-          <Select v-model="filters.billing_type" :options="billingTypeOptions" @change="emitChange" />
-        </div>
-
         <!-- Group Filter -->
         <div class="w-full sm:w-auto sm:min-w-[200px]">
           <label class="input-label">{{ t('admin.usage.group') }}</label>
@@ -227,12 +221,6 @@ const streamTypeOptions = ref<SelectOption[]>([
   { value: false, label: t('usage.sync') }
 ])
 
-const billingTypeOptions = ref<SelectOption[]>([
-  { value: null, label: t('admin.usage.allBillingTypes') },
-  { value: 1, label: t('usage.subscription') },
-  { value: 0, label: t('usage.balance') }
-])
-
 const emitChange = () => emit('change')
 
 const updateStartDate = (value: string) => {

frontend/src/components/admin/usage/UsageTable.vue

@@ -96,12 +96,6 @@
           </div>
         </template>
 
-        <template #cell-billing_type="{ row }">
-          <span class="inline-flex items-center rounded px-2 py-0.5 text-xs font-medium" :class="row.billing_type === 1 ? 'bg-purple-100 text-purple-800 dark:bg-purple-900 dark:text-purple-200' : 'bg-emerald-100 text-emerald-800 dark:bg-emerald-900 dark:text-emerald-200'">
-            {{ row.billing_type === 1 ? t('usage.subscription') : t('usage.balance') }}
-          </span>
-        </template>
-
         <template #cell-first_token="{ row }">
           <span v-if="row.first_token_ms != null" class="text-sm text-gray-600 dark:text-gray-400">{{ formatDuration(row.first_token_ms) }}</span>
           <span v-else class="text-sm text-gray-400 dark:text-gray-500">-</span>
@@ -120,6 +114,11 @@
           <span v-else class="text-sm text-gray-400 dark:text-gray-500">-</span>
         </template>
 
+        <template #cell-ip_address="{ row }">
+          <span v-if="row.ip_address" class="text-sm font-mono text-gray-600 dark:text-gray-400">{{ row.ip_address }}</span>
+          <span v-else class="text-sm text-gray-400 dark:text-gray-500">-</span>
+        </template>
+
         <template #empty><EmptyState :message="t('usage.noRecords')" /></template>
       </DataTable>
     </div>
@@ -249,11 +248,11 @@ const cols = computed(() => [
   { key: 'stream', label: t('usage.type'), sortable: false },
   { key: 'tokens', label: t('usage.tokens'), sortable: false },
   { key: 'cost', label: t('usage.cost'), sortable: false },
-  { key: 'billing_type', label: t('usage.billingType'), sortable: false },
   { key: 'first_token', label: t('usage.firstToken'), sortable: false },
   { key: 'duration', label: t('usage.duration'), sortable: false },
   { key: 'created_at', label: t('usage.time'), sortable: true },
-  { key: 'user_agent', label: t('usage.userAgent'), sortable: false }
+  { key: 'user_agent', label: t('usage.userAgent'), sortable: false },
+  { key: 'ip_address', label: t('admin.usage.ipAddress'), sortable: false }
 ])
 
 const formatCacheTokens = (tokens: number): string => {

frontend/src/i18n/locales/en.ts

@@ -361,6 +361,14 @@ export default {
     customKeyTooShort: 'Custom key must be at least 16 characters',
     customKeyInvalidChars: 'Custom key can only contain letters, numbers, underscores, and hyphens',
     customKeyRequired: 'Please enter a custom key',
+    ipRestriction: 'IP Restriction',
+    ipWhitelist: 'IP Whitelist',
+    ipWhitelistPlaceholder: '192.168.1.100\n10.0.0.0/8',
+    ipWhitelistHint: 'One IP or CIDR per line. Only these IPs can use this key when set.',
+    ipBlacklist: 'IP Blacklist',
+    ipBlacklistPlaceholder: '1.2.3.4\n5.6.0.0/16',
+    ipBlacklistHint: 'One IP or CIDR per line. These IPs will be blocked from using this key.',
+    ipRestrictionEnabled: 'IP restriction enabled',
     ccSwitchNotInstalled: 'CC-Switch is not installed or the protocol handler is not registered. Please install CC-Switch first or manually copy the API key.',
     ccsClientSelect: {
       title: 'Select Client',
@@ -421,9 +429,6 @@ export default {
     exportFailed: 'Failed to export usage data',
     exportExcelSuccess: 'Usage data exported successfully (Excel format)',
     exportExcelFailed: 'Failed to export usage data',
-    billingType: 'Billing',
-    balance: 'Balance',
-    subscription: 'Subscription',
     imageUnit: ' images',
     userAgent: 'User-Agent'
   },
@@ -1721,7 +1726,6 @@ export default {
       allAccounts: 'All Accounts',
       allGroups: 'All Groups',
       allTypes: 'All Types',
-      allBillingTypes: 'All Billing',
       inputCost: 'Input Cost',
       outputCost: 'Output Cost',
       cacheCreationCost: 'Cache Creation Cost',
@@ -1730,7 +1734,8 @@ export default {
       outputTokens: 'Output Tokens',
       cacheCreationTokens: 'Cache Creation Tokens',
       cacheReadTokens: 'Cache Read Tokens',
-      failedToLoad: 'Failed to load usage records'
+      failedToLoad: 'Failed to load usage records',
+      ipAddress: 'IP'
     },
 
     // Settings

frontend/src/i18n/locales/zh.ts

@@ -358,6 +358,14 @@ export default {
     customKeyTooShort: '自定义密钥至少需要16个字符',
     customKeyInvalidChars: '自定义密钥只能包含字母、数字、下划线和连字符',
     customKeyRequired: '请输入自定义密钥',
+    ipRestriction: 'IP 限制',
+    ipWhitelist: 'IP 白名单',
+    ipWhitelistPlaceholder: '192.168.1.100\n10.0.0.0/8',
+    ipWhitelistHint: '每行一个 IP 或 CIDR，设置后仅允许这些 IP 使用此密钥',
+    ipBlacklist: 'IP 黑名单',
+    ipBlacklistPlaceholder: '1.2.3.4\n5.6.0.0/16',
+    ipBlacklistHint: '每行一个 IP 或 CIDR，这些 IP 将被禁止使用此密钥',
+    ipRestrictionEnabled: '已配置 IP 限制',
     ccSwitchNotInstalled: 'CC-Switch 未安装或协议处理程序未注册。请先安装 CC-Switch 或手动复制 API 密钥。',
     ccsClientSelect: {
       title: '选择客户端',
@@ -418,9 +426,6 @@ export default {
     exportFailed: '使用数据导出失败',
     exportExcelSuccess: '使用数据导出成功（Excel格式）',
     exportExcelFailed: '使用数据导出失败',
-    billingType: '消费类型',
-    balance: '余额',
-    subscription: '订阅',
     imageUnit: '张',
     userAgent: 'User-Agent'
   },
@@ -1866,7 +1871,6 @@ export default {
       allAccounts: '全部账户',
       allGroups: '全部分组',
       allTypes: '全部类型',
-      allBillingTypes: '全部计费',
       inputCost: '输入成本',
       outputCost: '输出成本',
       cacheCreationCost: '缓存创建成本',
@@ -1875,7 +1879,8 @@ export default {
       outputTokens: '输出 Token',
       cacheCreationTokens: '缓存创建 Token',
       cacheReadTokens: '缓存读取 Token',
-      failedToLoad: '加载使用记录失败'
+      failedToLoad: '加载使用记录失败',
+      ipAddress: 'IP'
     },
 
     // Settings

frontend/src/types/index.ts

@@ -278,6 +278,8 @@ export interface ApiKey {
   name: string
   group_id: number | null
   status: 'active' | 'inactive'
+  ip_whitelist: string[]
+  ip_blacklist: string[]
   created_at: string
   updated_at: string
   group?: Group
@@ -287,12 +289,16 @@ export interface CreateApiKeyRequest {
   name: string
   group_id?: number | null
   custom_key?: string // Optional custom API Key
+  ip_whitelist?: string[]
+  ip_blacklist?: string[]
 }
 
 export interface UpdateApiKeyRequest {
   name?: string
   group_id?: number | null
   status?: 'active' | 'inactive'
+  ip_whitelist?: string[]
+  ip_blacklist?: string[]
 }
 
 export interface CreateGroupRequest {
@@ -559,9 +565,6 @@ export interface UpdateProxyRequest {
 
 export type RedeemCodeType = 'balance' | 'concurrency' | 'subscription'
 
-// 消费类型: 0=钱包余额, 1=订阅套餐
-export type BillingType = 0 | 1
-
 export interface UsageLog {
   id: number
   user_id: number
@@ -588,7 +591,6 @@ export interface UsageLog {
   actual_cost: number
   rate_multiplier: number
 
-  billing_type: BillingType
   stream: boolean
   duration_ms: number
   first_token_ms: number | null
@@ -600,6 +602,9 @@ export interface UsageLog {
   // User-Agent
   user_agent: string | null
 
+  // IP 地址（仅管理员可见）
+  ip_address: string | null
+
   created_at: string
 
   user?: User
@@ -829,7 +834,6 @@ export interface UsageQueryParams {
   group_id?: number
   model?: string
   stream?: boolean
-  billing_type?: number
   start_date?: string
   end_date?: string
 }

frontend/src/views/admin/UsageView.vue

@@ -95,8 +95,8 @@ const exportToExcel = async () => {
         t('admin.usage.inputCost'), t('admin.usage.outputCost'),
         t('admin.usage.cacheReadCost'), t('admin.usage.cacheCreationCost'),
         t('usage.rate'), t('usage.original'), t('usage.billed'),
-        t('usage.billingType'), t('usage.firstToken'), t('usage.duration'),
-        t('admin.usage.requestId'), t('usage.userAgent')
+        t('usage.firstToken'), t('usage.duration'),
+        t('admin.usage.requestId'), t('usage.userAgent'), t('admin.usage.ipAddress')
       ]
       const rows = all.map(log => [
         log.created_at,
@@ -117,11 +117,11 @@ const exportToExcel = async () => {
         log.rate_multiplier?.toFixed(2) || '1.00',
         log.total_cost?.toFixed(6) || '0.000000',
         log.actual_cost?.toFixed(6) || '0.000000',
-        log.billing_type === 1 ? t('usage.subscription') : t('usage.balance'),
         log.first_token_ms ?? '',
         log.duration_ms,
         log.request_id || '',
-        log.user_agent || ''
+        log.user_agent || '',
+        log.ip_address || ''
       ])
       const ws = XLSX.utils.aoa_to_sheet([headers, ...rows])
       const wb = XLSX.utils.book_new()