diff --git a/backend/crates/gateway-admin/src/model/client_keys.rs b/backend/crates/gateway-admin/src/model/client_keys.rs index 67c0a6872..2683f24df 100644 --- a/backend/crates/gateway-admin/src/model/client_keys.rs +++ b/backend/crates/gateway-admin/src/model/client_keys.rs @@ -317,9 +317,69 @@ impl ClientKeyBudgetWindowPeriod { } } +/// 手动对齐只需要账号身份,列表不读取凭据、额度或用量 +#[derive(serde::Serialize, Debug)] +pub struct BudgetReferenceAccount { + pub id: String, + pub name: String, + pub email: Option, + pub provider: String, +} + +#[derive(serde::Serialize, Debug)] +#[serde(rename_all = "camelCase")] +pub struct BudgetReferenceAccountPage { + pub items: Vec, + pub next_cursor: Option, +} + +/// 管理员可预览的账号窗口保留 Provider 的稳定标识 +pub struct ClientKeyBudgetReference { + pub key: String, + pub label: String, + pub period: ClientKeyBudgetWindowPeriod, + pub bounds: ExplicitClientKeyBudgetWindow, +} + +impl ClientKeyBudgetReference { + /// 只取整账号当前的日/周窗口,对齐结束后恢复密钥自身周期 + pub fn from_current_window( + window: super::provider_credentials::ProviderQuotaWindow, + now: DateTime, + ) -> Option { + use super::provider_credentials::QuotaLocalUsageAttribution; + if window.local_usage_attribution != QuotaLocalUsageAttribution::AccountWide + || window + .upstream + .as_ref() + .is_some_and(|upstream| upstream.stale) + { + return None; + } + let period = match window.window_seconds? { + 86_400 => ClientKeyBudgetWindowPeriod::Daily, + 604_800 => ClientKeyBudgetWindowPeriod::Weekly, + _ => return None, + }; + let (starts_at, ends_at) = window.observed_bounds()?; + (starts_at..ends_at).contains(&now).then_some(Self { + key: window.key, + label: window.label, + period, + bounds: ExplicitClientKeyBudgetWindow { + starts_at, + ends_at, + resume_calendar: true, + }, + }) + } +} + /// 按请求完成时间归属的左闭右开预算窗口 #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub struct ExplicitClientKeyBudgetWindow { + /// 一次性对齐的窗口到期后恢复原生滚动 + pub resume_calendar: bool, pub starts_at: DateTime, pub ends_at: DateTime, } diff --git a/backend/crates/gateway-admin/src/model/observability.rs b/backend/crates/gateway-admin/src/model/observability.rs index 4816c696a..bfac2b4d1 100644 --- a/backend/crates/gateway-admin/src/model/observability.rs +++ b/backend/crates/gateway-admin/src/model/observability.rs @@ -648,6 +648,56 @@ pub struct AttemptMetrics { pub costs: Vec, } +/// 管理员按当前指标排列模型与趋势,值只来自固定的聚合列 +#[derive(Debug, Clone, Copy, Default, serde::Deserialize)] +#[serde(rename_all = "camelCase")] +pub enum KeyUsageMetric { + #[default] + CostUsd, + Tokens, + Requests, +} + +#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct KeyUsageTotals { + pub requests: u64, + pub tokens: Option, + pub cost_usd: Option, + pub has_missing_cost: bool, + pub has_estimated_cost: bool, +} + +#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct KeyModelRow { + pub model: String, + pub totals: KeyUsageTotals, + pub peak_requests: u64, + pub active_days: u32, +} + +#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)] +pub struct KeyTrendPoint { + pub date: chrono::NaiveDate, + pub value: Option, +} + +#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)] +pub struct KeyTrendSeries { + /// 空字符串表示未记录模型,None 表示合并的其他模型 + pub model: Option, + pub points: Vec, +} + +#[derive(Debug, Clone, Default, serde::Serialize, serde::Deserialize)] +pub struct KeyStatisticsOverview { + pub totals: KeyUsageTotals, + pub series: Vec, + #[serde(rename = "modelCount")] + pub model_count: u64, +} + /// 时间序列粒度 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] pub enum Granularity { diff --git a/backend/crates/gateway-admin/src/model/provider_credentials.rs b/backend/crates/gateway-admin/src/model/provider_credentials.rs index f2522de28..61046cc9c 100644 --- a/backend/crates/gateway-admin/src/model/provider_credentials.rs +++ b/backend/crates/gateway-admin/src/model/provider_credentials.rs @@ -820,6 +820,14 @@ pub struct ProviderQuotaWindow { pub provider_data: Option, } +impl ProviderQuotaWindow { + pub(crate) fn observed_bounds(&self) -> Option<(DateTime, DateTime)> { + let ends_at = self.reset_at?; + let duration = chrono::Duration::try_seconds(i64::try_from(self.window_seconds?).ok()?)?; + Some((ends_at.checked_sub_signed(duration)?, ends_at)) + } +} + /// 账号用量统计周期,完整周/月额度优先,随后使用 Provider 提供的本地滚动日统计 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)] pub enum AccountUsagePeriod { diff --git a/backend/crates/gateway-admin/src/ports/store.rs b/backend/crates/gateway-admin/src/ports/store.rs index dfc43227d..c85018730 100644 --- a/backend/crates/gateway-admin/src/ports/store.rs +++ b/backend/crates/gateway-admin/src/ports/store.rs @@ -22,9 +22,9 @@ use crate::model::{ }, auth::{AdminAuditEvent, AuthSession}, client_keys::{ - BatchUpdateClientKeys, ClientKeyBudgetMutationOrigin, ClientKeyBudgetWindow, - ClientKeyBudgetWindowPeriod, ClientKeyListQuery, ClientKeyPage, ClientKeyRecord, - ClientKeySecret, DeleteClientKey, NewClientKey, ResetClientKeyBudget, + BatchUpdateClientKeys, BudgetReferenceAccountPage, ClientKeyBudgetMutationOrigin, + ClientKeyBudgetWindow, ClientKeyBudgetWindowPeriod, ClientKeyListQuery, ClientKeyPage, + ClientKeyRecord, ClientKeySecret, DeleteClientKey, NewClientKey, ResetClientKeyBudget, SetClientKeyBudgetWindow, SetClientKeyEnabled, UpdateClientKey, UpdateClientKeyBudgetLimits, }, @@ -385,6 +385,18 @@ pub trait AuthStore: Send + Sync { /// Client API Key 资料读取与管理写入 #[async_trait] pub trait ClientKeyStore: Send + Sync { + async fn client_key_budget( + &self, + id: &gateway_core::policy::ClientApiKeyId, + ) -> AdminStoreResult>; + + async fn budget_reference_accounts( + &self, + id: &gateway_core::policy::ClientApiKeyId, + search: &str, + after: &str, + ) -> AdminStoreResult; + async fn client_key_budget_window( &self, id: &gateway_core::policy::ClientApiKeyId, @@ -533,6 +545,19 @@ pub trait ObservabilityStore: Send + Sync { granularity: Granularity, ) -> AdminStoreResult>; + async fn client_key_statistics( + &self, + range: TimeRange, + id: &gateway_core::policy::ClientApiKeyId, + query: crate::model::observability::KeyUsageMetric, + ) -> AdminStoreResult; + + async fn client_key_models( + &self, + range: TimeRange, + id: &gateway_core::policy::ClientApiKeyId, + ) -> AdminStoreResult>; + async fn usage_trend( &self, range: TimeRange, diff --git a/backend/crates/gateway-admin/src/use_case/accounts/mod.rs b/backend/crates/gateway-admin/src/use_case/accounts/mod.rs index cec6cc2d1..e68a2e3aa 100644 --- a/backend/crates/gateway-admin/src/use_case/accounts/mod.rs +++ b/backend/crates/gateway-admin/src/use_case/accounts/mod.rs @@ -20,11 +20,13 @@ use gateway_core::{ use crate::{ model::{ AdminError, MutationContext, + account_groups::AccountGroupRef, accounts::{ AccountConnectionTestEvent, AccountConnectionTestEventStream, AccountListQuery, AccountPageItem, AccountUpdateResult, AccountUsage, AccountUsageWindowQuery, AccountsUpdateResult, BatchUpdateAccounts, UpdateAccount, }, + client_keys::ClientKeyBudgetReference, observability::TimeRange, provider_credentials::{ AccountDirectoryItem, AccountDirectoryPage, AccountExportBundle, AccountPersonalInfo, @@ -107,6 +109,12 @@ pub trait AccountsService: Send + Sync { refresh: bool, ) -> Result; + async fn key_budget_references( + &self, + account_id: &ProviderAccountId, + key_groups: &[AccountGroupRef], + ) -> Result, AdminError>; + async fn quota_forecast( &self, account_id: &ProviderAccountId, @@ -972,6 +980,48 @@ impl AccountsService for DefaultAccountsService { self.load_directory_item(account_id, refresh).await } + async fn key_budget_references( + &self, + account_id: &ProviderAccountId, + key_groups: &[AccountGroupRef], + ) -> Result, AdminError> { + let (stored, provider) = self.provider_for_account(account_id).await?; + if !key_groups.is_empty() + && !stored.account.groups.iter().any(|account_group| { + account_group.enabled && key_groups.iter().any(|group| group.id == account_group.id) + }) + { + return Err(AdminError::bad_request("参考账号不在此密钥的账号范围内")); + } + // 只取已观测的额度边界,预览与确认都不触发上游刷新或账号用量聚合 + let quota = match super::peer_link::upstream::read_quota( + self.upstream_info.as_deref(), + provider.as_ref(), + &stored.account, + ProviderQuotaRequest { + account_id: account_id.clone(), + refresh: false, + rolling_usage: None, + }, + ) + .await + { + Ok(quota) => quota, + Err(error) + if error.kind() == crate::ports::provider::ProviderAdminErrorKind::Unsupported => + { + return Ok(Vec::new()); + } + Err(error) => return Err(map_provider_error(error, "provider quota")), + }; + let now = Utc::now(); + Ok(quota + .windows + .into_iter() + .filter_map(|window| ClientKeyBudgetReference::from_current_window(window, now)) + .collect()) + } + async fn quota_forecast( &self, account_id: &ProviderAccountId, @@ -1304,9 +1354,7 @@ fn quota_usage_window( if window.local_usage_attribution != QuotaLocalUsageAttribution::AccountWide { return None; } - let reset_at = window.reset_at?; - let seconds = i64::try_from(window.window_seconds?).ok()?; - let start = reset_at.checked_sub_signed(Duration::try_seconds(seconds)?)?; + let (start, reset_at) = window.observed_bounds()?; let range = TimeRange::new(start, reset_at).ok()?; // 上游百分比以该 reset 边界定义;以当前时间回推会让本地 Token 属于另一窗口 Some(AccountUsageWindowQuery { diff --git a/backend/crates/gateway-admin/src/use_case/client_keys.rs b/backend/crates/gateway-admin/src/use_case/client_keys.rs index 10773e405..539ab5a8f 100644 --- a/backend/crates/gateway-admin/src/use_case/client_keys.rs +++ b/backend/crates/gateway-admin/src/use_case/client_keys.rs @@ -15,11 +15,11 @@ use crate::{ model::{ AdminError, MutationContext, client_keys::{ - BatchUpdateClientKeys, ClientKeyBudgetMutationOrigin, ClientKeyBudgetWindow, - ClientKeyBudgetWindowPeriod, ClientKeyCursorValue, ClientKeyListQuery, - ClientKeyMutation, ClientKeyPage, ClientKeyRecord, ClientKeySecret, ClientKeySortField, - CreateClientKey, CreatedClientKey, DeleteClientKey, NewClientKey, ResetClientKeyBudget, - SetClientKeyBudgetWindow, SetClientKeyEnabled, UpdateClientKey, + BatchUpdateClientKeys, BudgetReferenceAccountPage, ClientKeyBudgetMutationOrigin, + ClientKeyBudgetWindow, ClientKeyBudgetWindowPeriod, ClientKeyCursorValue, + ClientKeyListQuery, ClientKeyMutation, ClientKeyPage, ClientKeyRecord, ClientKeySecret, + ClientKeySortField, CreateClientKey, CreatedClientKey, DeleteClientKey, NewClientKey, + ResetClientKeyBudget, SetClientKeyBudgetWindow, SetClientKeyEnabled, UpdateClientKey, UpdateClientKeyBudgetLimits, }, }, @@ -33,6 +33,13 @@ use super::{map_store_error, publish_committed}; /// API 消费的 Client Key 管理服务 #[async_trait] pub trait ClientKeyService: Send + Sync { + async fn budget_reference_accounts( + &self, + id: &gateway_core::policy::ClientApiKeyId, + search: &str, + after: &str, + ) -> Result; + async fn budget_window( &self, id: &ClientApiKeyId, @@ -212,6 +219,18 @@ impl ClientKeyService for DefaultClientKeyService { Ok(revision) } + async fn budget_reference_accounts( + &self, + id: &gateway_core::policy::ClientApiKeyId, + search: &str, + after: &str, + ) -> Result { + self.store + .budget_reference_accounts(id, search.trim(), after) + .await + .map_err(|error| map_store_error(error, "client API key")) + } + async fn budget_window( &self, id: &ClientApiKeyId, @@ -250,7 +269,11 @@ impl ClientKeyService for DefaultClientKeyService { } async fn budget(&self, id: &ClientApiKeyId) -> Result { - self.get(id).await.map(|key| key.budget) + self.store + .client_key_budget(id) + .await + .map_err(|error| map_store_error(error, "client API key"))? + .ok_or_else(|| AdminError::not_found("API Key 不存在")) } async fn update_budget_limits( diff --git a/backend/crates/gateway-admin/src/use_case/observability/mod.rs b/backend/crates/gateway-admin/src/use_case/observability/mod.rs index 36f11396d..26719871a 100644 --- a/backend/crates/gateway-admin/src/use_case/observability/mod.rs +++ b/backend/crates/gateway-admin/src/use_case/observability/mod.rs @@ -60,6 +60,19 @@ pub trait ObservabilityService: Send + Sync { -> Result; async fn usage_records(&self, query: UsageQuery) -> Result; async fn usage_record_detail(&self, request_id: &str) -> Result; + async fn client_key_statistics( + &self, + range: TimeRange, + id: &gateway_core::policy::ClientApiKeyId, + query: crate::model::observability::KeyUsageMetric, + ) -> Result; + + async fn client_key_models( + &self, + range: TimeRange, + id: &gateway_core::policy::ClientApiKeyId, + ) -> Result, AdminError>; + async fn usage_summary( &self, range: TimeRange, @@ -287,6 +300,29 @@ impl ObservabilityService for DefaultObservabilityService { Ok(detail) } + async fn client_key_statistics( + &self, + range: TimeRange, + id: &gateway_core::policy::ClientApiKeyId, + query: crate::model::observability::KeyUsageMetric, + ) -> Result { + self.store + .client_key_statistics(range, id, query) + .await + .map_err(|error| map_store_error(error, "client key statistics")) + } + + async fn client_key_models( + &self, + range: TimeRange, + id: &gateway_core::policy::ClientApiKeyId, + ) -> Result, AdminError> { + self.store + .client_key_models(range, id) + .await + .map_err(|error| map_store_error(error, "client key statistics")) + } + async fn usage_summary( &self, range: TimeRange, diff --git a/backend/crates/gateway-admin/src/use_case/observability/store_cache.rs b/backend/crates/gateway-admin/src/use_case/observability/store_cache.rs index 1b0b18477..e51c1675e 100644 --- a/backend/crates/gateway-admin/src/use_case/observability/store_cache.rs +++ b/backend/crates/gateway-admin/src/use_case/observability/store_cache.rs @@ -226,6 +226,23 @@ impl ObservabilityStore for CachedObservabilityStore { ) -> AdminStoreResult> { self.inner.dashboard_trend(range, granularity).await } + async fn client_key_statistics( + &self, + range: TimeRange, + id: &gateway_core::policy::ClientApiKeyId, + query: crate::model::observability::KeyUsageMetric, + ) -> AdminStoreResult { + self.inner.client_key_statistics(range, id, query).await + } + + async fn client_key_models( + &self, + range: TimeRange, + id: &gateway_core::policy::ClientApiKeyId, + ) -> AdminStoreResult> { + self.inner.client_key_models(range, id).await + } + async fn usage_trend( &self, range: TimeRange, diff --git a/backend/crates/gateway-admin/tests/model/provider_credentials.rs b/backend/crates/gateway-admin/tests/model/provider_credentials.rs index 9edb5fd43..c4801ff3c 100644 --- a/backend/crates/gateway-admin/tests/model/provider_credentials.rs +++ b/backend/crates/gateway-admin/tests/model/provider_credentials.rs @@ -335,3 +335,42 @@ fn pending_mutation_v1_should_keep_existing_storage_fields_and_reject_invalid_do document["schema_version"] = json!(2); assert!(PendingAuthorizationMutation::from_storage_v1(document).is_err()); } + +#[test] +fn manual_key_alignment_only_accepts_the_current_account_wide_day_or_week() { + use chrono::{Duration, Utc}; + use gateway_admin::model::{ + client_keys::{ClientKeyBudgetReference, ClientKeyBudgetWindowPeriod}, + upstream_info::UpstreamQuotaWindow, + }; + let now = Utc::now(); + for (seconds, period) in [ + (86_400, ClientKeyBudgetWindowPeriod::Daily), + (604_800, ClientKeyBudgetWindowPeriod::Weekly), + ] { + let mut window = usage_window("account", "quota", seconds); + let end = now + Duration::hours(2); + window.reset_at = Some(end); + let reference = ClientKeyBudgetReference::from_current_window(window.clone(), now).unwrap(); + let selected = reference.period; + let bounds = reference.bounds; + assert_eq!(selected, period); + assert_eq!(bounds.starts_at, end - Duration::seconds(seconds as i64)); + assert_eq!(bounds.ends_at, end); + assert!(bounds.resume_calendar); + assert!(ClientKeyBudgetReference::from_current_window(window.clone(), end).is_none()); + window.upstream = Some(UpstreamQuotaWindow { + account_id: None, + observed_at: Some(now), + stale: true, + amount: None, + }); + assert!(ClientKeyBudgetReference::from_current_window(window.clone(), now).is_none()); + window.upstream = None; + window.local_usage_attribution = QuotaLocalUsageAttribution::Unavailable; + assert!(ClientKeyBudgetReference::from_current_window(window.clone(), now).is_none()); + } + let mut short = usage_window("primary", "short", 18_000); + short.reset_at = Some(now + Duration::hours(1)); + assert!(ClientKeyBudgetReference::from_current_window(short, now).is_none()); +} diff --git a/backend/crates/gateway-admin/tests/use_case/client_keys.rs b/backend/crates/gateway-admin/tests/use_case/client_keys.rs index ed56aac8f..f1b119141 100644 --- a/backend/crates/gateway-admin/tests/use_case/client_keys.rs +++ b/backend/crates/gateway-admin/tests/use_case/client_keys.rs @@ -35,6 +35,17 @@ struct TestClientKeyStore { #[async_trait] impl ClientKeyStore for TestClientKeyStore { + async fn budget_reference_accounts( + &self, + _: &gateway_core::policy::ClientApiKeyId, + _: &str, + _: &str, + ) -> gateway_admin::ports::store::AdminStoreResult< + gateway_admin::model::client_keys::BudgetReferenceAccountPage, + > { + Err(unused()) + } + async fn batch_update_client_keys( &self, _: gateway_admin::model::client_keys::BatchUpdateClientKeys, @@ -89,6 +100,15 @@ impl ClientKeyStore for TestClientKeyStore { Ok(()) } + async fn client_key_budget( + &self, + id: &gateway_core::policy::ClientApiKeyId, + ) -> AdminStoreResult> { + self.get_client_key(id) + .await + .map(|key| key.map(|row| row.budget)) + } + async fn get_client_key( &self, _: &ClientApiKeyId, diff --git a/backend/crates/gateway-admin/tests/use_case/mod.rs b/backend/crates/gateway-admin/tests/use_case/mod.rs index 2d3a93d4b..fc3d4c7d5 100644 --- a/backend/crates/gateway-admin/tests/use_case/mod.rs +++ b/backend/crates/gateway-admin/tests/use_case/mod.rs @@ -719,6 +719,17 @@ impl AccountRuntimeStore for UnavailableStore { #[async_trait] impl ClientKeyStore for UnavailableStore { + async fn budget_reference_accounts( + &self, + _: &gateway_core::policy::ClientApiKeyId, + _: &str, + _: &str, + ) -> gateway_admin::ports::store::AdminStoreResult< + gateway_admin::model::client_keys::BudgetReferenceAccountPage, + > { + Err(unavailable("reference accounts")) + } + async fn batch_update_client_keys( &self, _: gateway_admin::model::client_keys::BatchUpdateClientKeys, @@ -772,6 +783,15 @@ impl ClientKeyStore for UnavailableStore { Err(unavailable("client key budget reset")) } + async fn client_key_budget( + &self, + id: &gateway_core::policy::ClientApiKeyId, + ) -> AdminStoreResult> { + self.get_client_key(id) + .await + .map(|key| key.map(|row| row.budget)) + } + async fn get_client_key( &self, _: &ClientApiKeyId, @@ -853,6 +873,23 @@ impl ObservabilityStore for UnavailableStore { Err(unavailable("dashboard trend")) } + async fn client_key_statistics( + &self, + _: TimeRange, + _: &gateway_core::policy::ClientApiKeyId, + _: gateway_admin::model::observability::KeyUsageMetric, + ) -> AdminStoreResult { + Ok(Default::default()) + } + + async fn client_key_models( + &self, + _: TimeRange, + _: &gateway_core::policy::ClientApiKeyId, + ) -> AdminStoreResult> { + Ok(Default::default()) + } + async fn usage_trend( &self, _: TimeRange, diff --git a/backend/crates/gateway-admin/tests/use_case/observability/mod.rs b/backend/crates/gateway-admin/tests/use_case/observability/mod.rs index fd30f44b9..3d30e234a 100644 --- a/backend/crates/gateway-admin/tests/use_case/observability/mod.rs +++ b/backend/crates/gateway-admin/tests/use_case/observability/mod.rs @@ -1266,6 +1266,23 @@ impl ObservabilityStore for FixtureObservabilityStore { Ok(self.trend.lock().expect("trend").clone()) } + async fn client_key_statistics( + &self, + _: TimeRange, + _: &gateway_core::policy::ClientApiKeyId, + _: gateway_admin::model::observability::KeyUsageMetric, + ) -> AdminStoreResult { + Ok(Default::default()) + } + + async fn client_key_models( + &self, + _: TimeRange, + _: &gateway_core::policy::ClientApiKeyId, + ) -> AdminStoreResult> { + Ok(Default::default()) + } + async fn usage_trend( &self, _: TimeRange, diff --git a/backend/crates/gateway-api/src/admin/client_key_usage.rs b/backend/crates/gateway-api/src/admin/client_key_usage.rs new file mode 100644 index 000000000..f94005292 --- /dev/null +++ b/backend/crates/gateway-api/src/admin/client_key_usage.rs @@ -0,0 +1,291 @@ +//! 管理员查看单个密钥的模型统计与手动对齐本期额度的接口 + +use axum::{Router, extract::State, http::StatusCode, response::IntoResponse, routing::get}; +use chrono::{DateTime, Utc}; +use gateway_admin::model::observability::{KeyStatisticsOverview, KeyUsageMetric, TimeRange}; +use gateway_admin::{ + AdminServices, + model::client_keys::{ + ClientKeyBudgetMutationOrigin, ClientKeyBudgetReference, ClientKeyBudgetWindowPeriod, + SetClientKeyBudgetWindow, + }, +}; +use gateway_core::{account::ProviderAccountId, policy::ClientApiKeyId}; +use serde::{Deserialize, Serialize}; + +use super::{ + AdminAuth, AdminEnvelope, AdminError, AdminJson, AdminQuery, AdminResponse, + client_keys::ClientBudgetView, wire::map_admin_service_error, +}; +use crate::{auth::SessionState, time::TimePresenter}; + +pub(super) fn router() -> Router { + Router::new() + .route( + "/api/admin/client-keys/budget-reference-accounts", + get(accounts::), + ) + .route("/api/admin/client-keys/statistics", get(statistics::)) + .route("/api/admin/client-keys/statistics/models", get(models::)) + .route( + "/api/admin/client-keys/budget-alignment", + get(preview::).post(align::), + ) +} + +#[derive(Deserialize)] +#[serde(rename_all = "camelCase", deny_unknown_fields)] +struct StatisticsQuery { + id: String, + period: Option, + #[serde(default)] + metric: KeyUsageMetric, + as_of: Option, +} + +fn key_id(value: String) -> Result { + ClientApiKeyId::new(value).map_err(|_| AdminError::bad_request("API Key ID 无效")) +} + +#[derive(Serialize)] +struct Statistics { + budget: ClientBudgetView, + dates: Vec, + #[serde(rename = "asOf")] + as_of: i64, + #[serde(flatten)] + overview: KeyStatisticsOverview, +} + +async fn statistics( + _auth: AdminAuth, + State(state): State, + AdminQuery(query): AdminQuery, +) -> Result { + let services = state.admin_services(); + let id = key_id(query.id.clone())?; + let tz = services.timezone(); + let range = statistics_range(&query, tz)?; + let budget = services + .client_keys() + .budget(&id) + .await + .map_err(map_admin_service_error)?; + let overview = services + .observability() + .client_key_statistics(range, &id, query.metric) + .await + .map_err(map_admin_service_error)?; + let end = tz.local(range.end).date_naive(); + let dates = tz + .local(range.start) + .date_naive() + .iter_days() + .take_while(|date| *date <= end) + .collect(); + Ok(AdminResponse::new( + StatusCode::OK, + AdminEnvelope::ok(Statistics { + budget: ClientBudgetView::from((budget, TimePresenter::new(tz))), + dates, + as_of: range.end.timestamp_millis(), + overview, + }), + )) +} + +fn statistics_range( + query: &StatisticsQuery, + tz: gateway_core::time::DeploymentTimeZone, +) -> Result { + let period = query.period.as_deref().unwrap_or("7d"); + if !matches!(period, "7d" | "30d") { + return Err(AdminError::bad_request("统计周期须为 7 天或 30 天")); + } + crate::time::query_range( + None, + None, + Some(period), + Some(query.as_of.unwrap_or_else(|| Utc::now().timestamp_millis())), + tz, + "7d", + ) + .map_err(|_| AdminError::bad_request("统计时间范围无效")) +} + +async fn models( + _auth: AdminAuth, + State(state): State, + AdminQuery(query): AdminQuery, +) -> Result { + let services = state.admin_services(); + let range = statistics_range(&query, services.timezone())?; + let id = key_id(query.id)?; + services + .client_keys() + .budget(&id) + .await + .map_err(map_admin_service_error)?; + let items = services + .observability() + .client_key_models(range, &id) + .await + .map_err(map_admin_service_error)?; + Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(items))) +} + +#[derive(Deserialize)] +#[serde(deny_unknown_fields)] +struct AccountSearch { + id: String, + #[serde(default)] + search: String, + #[serde(default)] + cursor: String, +} + +async fn accounts( + _auth: AdminAuth, + State(state): State, + AdminQuery(query): AdminQuery, +) -> Result { + let page = state + .admin_services() + .client_keys() + .budget_reference_accounts(&key_id(query.id)?, &query.search, &query.cursor) + .await + .map_err(map_admin_service_error)?; + Ok(AdminResponse::new(StatusCode::OK, AdminEnvelope::ok(page))) +} + +#[derive(Deserialize)] +#[serde(rename_all = "camelCase", deny_unknown_fields)] +struct ReferenceQuery { + id: String, + account_id: String, +} + +#[derive(Serialize)] +#[serde(rename_all = "camelCase")] +struct ReferenceWindow { + key: String, + label: String, + period: &'static str, + starts_at: DateTime, + ends_at: DateTime, + starts_at_display: String, + ends_at_display: String, +} + +#[derive(Serialize)] +struct Preview { + revision: u64, + windows: Vec, +} + +async fn reference_windows( + services: &AdminServices, + id: &ClientApiKeyId, + account: String, +) -> Result, AdminError> { + let account_id = + ProviderAccountId::new(account).map_err(|_| AdminError::bad_request("参考账号 ID 无效"))?; + let key = services + .client_keys() + .get(id) + .await + .map_err(map_admin_service_error)?; + services + .accounts() + .key_budget_references(&account_id, &key.groups) + .await + .map_err(map_admin_service_error) +} + +async fn preview( + _auth: AdminAuth, + State(state): State, + AdminQuery(query): AdminQuery, +) -> Result { + let services = state.admin_services(); + let id = key_id(query.id)?; + let time = TimePresenter::new(services.timezone()); + let windows = reference_windows(services, &id, query.account_id) + .await? + .into_iter() + .map( + |ClientKeyBudgetReference { + key, + label, + period, + bounds, + }| ReferenceWindow { + key, + label, + period: period.as_str(), + starts_at: bounds.starts_at, + ends_at: bounds.ends_at, + starts_at_display: time.datetime(&bounds.starts_at), + ends_at_display: time.datetime(&bounds.ends_at), + }, + ) + .collect(); + // 日周窗口共享配置版本,普通请求的消费累计不会让预览失效 + let revision = services + .client_keys() + .budget_window(&id, ClientKeyBudgetWindowPeriod::Weekly) + .await + .map_err(map_admin_service_error)? + .revision; + Ok(AdminResponse::new( + StatusCode::OK, + AdminEnvelope::ok(Preview { revision, windows }), + )) +} + +#[derive(Deserialize)] +#[serde(rename_all = "camelCase", deny_unknown_fields)] +struct AlignRequest { + id: String, + account_id: String, + window_key: String, + starts_at: DateTime, + ends_at: DateTime, + revision: u64, +} + +async fn align( + auth: AdminAuth, + State(state): State, + AdminJson(input): AdminJson, +) -> Result { + let services = state.admin_services(); + let id = key_id(input.id)?; + let reference = reference_windows(services, &id, input.account_id) + .await? + .into_iter() + .find(|reference| { + reference.key == input.window_key + && reference.bounds.starts_at == input.starts_at + && reference.bounds.ends_at == input.ends_at + }) + .ok_or_else(|| AdminError::conflict("参考窗口已变化,请重新预览"))?; + let revision = services + .client_keys() + .set_budget_window( + &auth.context().mutation_context(), + SetClientKeyBudgetWindow { + id, + period: reference.period, + expected_revision: input.revision, + window: Some(reference.bounds), + }, + ClientKeyBudgetMutationOrigin::Admin, + ) + .await + .map_err(map_admin_service_error)?; + Ok(AdminResponse::new( + StatusCode::OK, + AdminEnvelope::ok(revision), + )) +} diff --git a/backend/crates/gateway-api/src/admin/client_keys.rs b/backend/crates/gateway-api/src/admin/client_keys.rs index 22f0fd3c6..90d3142d9 100644 --- a/backend/crates/gateway-api/src/admin/client_keys.rs +++ b/backend/crates/gateway-api/src/admin/client_keys.rs @@ -336,6 +336,48 @@ impl ClientKeyMutationRequest { } } +#[derive(Debug, Clone, PartialEq, Serialize)] +#[serde(rename_all = "camelCase")] +pub(super) struct ClientBudgetView { + daily_limit_usd: String, + weekly_limit_usd: String, + daily_used_usd: String, + weekly_used_usd: String, + daily_resets_at: Option>, + daily_resets_at_display: Option, + weekly_resets_at: Option>, + weekly_resets_at_display: Option, +} + +impl + From<( + gateway_core::engine::budget::ClientBudgetStatus, + crate::time::TimePresenter, + )> for ClientBudgetView +{ + fn from( + (budget, time): ( + gateway_core::engine::budget::ClientBudgetStatus, + crate::time::TimePresenter, + ), + ) -> Self { + Self { + daily_limit_usd: budget.limits.daily_usd.canonical(), + weekly_limit_usd: budget.limits.weekly_usd.canonical(), + daily_used_usd: budget.daily_used_usd.canonical(), + weekly_used_usd: budget.weekly_used_usd.canonical(), + daily_resets_at_display: budget + .daily_resets_at() + .map(|value| time.datetime(&value.into())), + daily_resets_at: budget.daily_resets_at().map(DateTime::from), + weekly_resets_at_display: budget + .weekly_resets_at() + .map(|value| time.datetime(&value.into())), + weekly_resets_at: budget.weekly_resets_at().map(DateTime::from), + } + } +} + /// 不含完整 Key 的管理端安全视图 #[derive(Debug, Clone, PartialEq, Serialize)] #[serde(rename_all = "camelCase")] @@ -356,14 +398,8 @@ pub struct ClientKeyView { enabled: bool, max_concurrency: u64, requests_per_minute: u64, - daily_limit_usd: String, - weekly_limit_usd: String, - daily_used_usd: String, - weekly_used_usd: String, - daily_resets_at: Option>, - daily_resets_at_display: Option, - weekly_resets_at: Option>, - weekly_resets_at_display: Option, + #[serde(flatten)] + budget: ClientBudgetView, created_at: DateTime, created_at_display: String, updated_at: DateTime, @@ -410,20 +446,7 @@ impl From<(ClientKeyRecord, crate::time::TimePresenter)> for ClientKeyView { enabled: record.enabled, max_concurrency: record.limits.max_concurrency, requests_per_minute: record.limits.requests_per_minute, - daily_limit_usd: record.budget.limits.daily_usd.canonical(), - weekly_limit_usd: record.budget.limits.weekly_usd.canonical(), - daily_used_usd: record.budget.daily_used_usd.canonical(), - weekly_used_usd: record.budget.weekly_used_usd.canonical(), - daily_resets_at_display: record - .budget - .daily_resets_at() - .map(|value| time.datetime(&value.into())), - daily_resets_at: record.budget.daily_resets_at().map(DateTime::from), - weekly_resets_at_display: record - .budget - .weekly_resets_at() - .map(|value| time.datetime(&value.into())), - weekly_resets_at: record.budget.weekly_resets_at().map(DateTime::from), + budget: ClientBudgetView::from((record.budget, time)), created_at_display: time.datetime(&record.created_at), created_at: record.created_at, updated_at_display: time.datetime(&record.updated_at), @@ -867,6 +890,7 @@ where S: SessionState + Clone + Send + Sync + 'static, { Router::new() + .merge(super::client_key_usage::router::()) .route("/api/admin/client-keys", get(list_client_keys::)) .route( "/api/admin/client-keys/batch-update", diff --git a/backend/crates/gateway-api/src/admin/mod.rs b/backend/crates/gateway-api/src/admin/mod.rs index 273af23b1..fd13637e0 100644 --- a/backend/crates/gateway-api/src/admin/mod.rs +++ b/backend/crates/gateway-api/src/admin/mod.rs @@ -15,6 +15,7 @@ pub mod account_groups; pub mod accounts; pub mod auth; pub mod backups; +mod client_key_usage; pub mod client_keys; mod compression; pub(crate) mod diagnostics; diff --git a/backend/crates/gateway-api/tests/admin/client_keys.rs b/backend/crates/gateway-api/tests/admin/client_keys.rs index 7c964889d..714a2a042 100644 --- a/backend/crates/gateway-api/tests/admin/client_keys.rs +++ b/backend/crates/gateway-api/tests/admin/client_keys.rs @@ -749,3 +749,81 @@ fn clearing_an_xai_profile_override_conflicts_with_an_explicit_xai_value() { "providerRequestProfileOverrides" ); } + +#[tokio::test] +async fn key_statistics_route_returns_calendar_days_and_current_budget_only_to_admin() { + use crate::support::{cookie_request, key_fixture, response_json}; + use axum::http::{Method, StatusCode}; + use gateway_core::policy::ClientApiKeyId; + use tower::ServiceExt as _; + + let fixture = key_fixture().await; + fixture.auth.insert_session("stats-admin"); + let record = fixture + .services + .client_keys() + .reveal(&ClientApiKeyId::new("key-42").unwrap()) + .await + .unwrap() + .record; + *fixture.client_key.lock().unwrap() = Some(record); + let app = client_keys::router::().with_state(fixture.state()); + for (query, cookie, status, days) in [ + ("id=key-42", "", StatusCode::UNAUTHORIZED, 0), + ( + "id=missing", + "cpr_session=stats-admin", + StatusCode::NOT_FOUND, + 0, + ), + ( + "id=key-42&period=today", + "cpr_session=stats-admin", + StatusCode::BAD_REQUEST, + 0, + ), + ("id=key-42", "cpr_session=stats-admin", StatusCode::OK, 7), + ( + "id=key-42&period=30d", + "cpr_session=stats-admin", + StatusCode::OK, + 30, + ), + ] { + let mut request = cookie_request( + Method::GET, + &format!("/api/admin/client-keys/statistics?{query}"), + cookie, + ); + request + .headers_mut() + .insert("x-request-id", "req_stats".parse().unwrap()); + let response = app.clone().oneshot(request).await.unwrap(); + assert_eq!(response.status(), status); + if days > 0 { + let body = response_json(response).await; + assert_eq!(body["data"]["dates"].as_array().unwrap().len(), days); + assert!(body["data"]["budget"]["dailyUsedUsd"].is_string()); + assert!(body["data"]["series"].as_array().unwrap().is_empty()); + assert_eq!(body["data"]["modelCount"], 0); + } + } + for (cookie, status) in [ + ("", StatusCode::UNAUTHORIZED), + ("cpr_session=stats-admin", StatusCode::OK), + ] { + let mut request = cookie_request( + Method::GET, + "/api/admin/client-keys/statistics/models?id=key-42", + cookie, + ); + request + .headers_mut() + .insert("x-request-id", "req_models".parse().unwrap()); + let response = app.clone().oneshot(request).await.unwrap(); + assert_eq!(response.status(), status); + if status == StatusCode::OK { + assert_eq!(response_json(response).await["data"], serde_json::json!([])); + } + } +} diff --git a/backend/crates/gateway-api/tests/admin/mod.rs b/backend/crates/gateway-api/tests/admin/mod.rs index 2b9f6a526..368b61b1b 100644 --- a/backend/crates/gateway-api/tests/admin/mod.rs +++ b/backend/crates/gateway-api/tests/admin/mod.rs @@ -1032,6 +1032,17 @@ fn mutation( #[async_trait] impl ClientKeyStore for MemoryClientKeyStore { + async fn budget_reference_accounts( + &self, + _: &gateway_core::policy::ClientApiKeyId, + _: &str, + _: &str, + ) -> gateway_admin::ports::store::AdminStoreResult< + gateway_admin::model::client_keys::BudgetReferenceAccountPage, + > { + Err(unavailable("reference accounts")) + } + async fn batch_update_client_keys( &self, _: gateway_admin::model::client_keys::BatchUpdateClientKeys, @@ -1113,6 +1124,15 @@ impl ClientKeyStore for MemoryClientKeyStore { Ok(()) } + async fn client_key_budget( + &self, + id: &gateway_core::policy::ClientApiKeyId, + ) -> AdminStoreResult> { + self.get_client_key(id) + .await + .map(|key| key.map(|row| row.budget)) + } + async fn get_client_key( &self, id: &ClientApiKeyId, @@ -1568,6 +1588,23 @@ impl ObservabilityStore for UnusedStore { Err(unavailable("dashboard trend")) } + async fn client_key_statistics( + &self, + _: TimeRange, + _: &gateway_core::policy::ClientApiKeyId, + _: gateway_admin::model::observability::KeyUsageMetric, + ) -> AdminStoreResult { + Ok(Default::default()) + } + + async fn client_key_models( + &self, + _: TimeRange, + _: &gateway_core::policy::ClientApiKeyId, + ) -> AdminStoreResult> { + Ok(Default::default()) + } + async fn usage_trend( &self, range: TimeRange, diff --git a/backend/crates/gateway-plugin/runtime/src/callback/keys.rs b/backend/crates/gateway-plugin/runtime/src/callback/keys.rs index 8634e0f04..b81c30c04 100644 --- a/backend/crates/gateway-plugin/runtime/src/callback/keys.rs +++ b/backend/crates/gateway-plugin/runtime/src/callback/keys.rs @@ -86,6 +86,7 @@ impl PluginClientKeys { .window .map(|window| { Ok(ExplicitClientKeyBudgetWindow { + resume_calendar: false, starts_at: chrono::DateTime::from_timestamp_micros(window.starts_at_us) .ok_or_else(invalid)?, ends_at: chrono::DateTime::from_timestamp_micros(window.ends_at_us) diff --git a/backend/crates/gateway-store/src/postgres/client_budget_windows.rs b/backend/crates/gateway-store/src/postgres/client_budget_windows.rs index 87fa8f46b..8a2a7f736 100644 --- a/backend/crates/gateway-store/src/postgres/client_budget_windows.rs +++ b/backend/crates/gateway-store/src/postgres/client_budget_windows.rs @@ -88,6 +88,7 @@ pub(super) async fn set( "period": command.period.as_str(), "starts_at": command.window.map(|window| window.starts_at), "ends_at": command.window.map(|window| window.ends_at), "owner": owner, + "resume_calendar": command.window.is_some_and(|window| window.resume_calendar), }); // 只创建未开启的账本,不因窗口管理顺带开启另一个原生周期 sqlx::query( @@ -128,16 +129,25 @@ pub(super) async fn set( let column = command.period.as_str(); let next: i64 = match command.window { Some(window) => { + if window.resume_calendar + && !(window.starts_at..window.ends_at).contains(&chrono::Utc::now()) + { + return Err(AdminStoreError::new( + AdminStoreErrorKind::Conflict, + "client API key", + "参考窗口已失效,请重新选择", + )); + } // 首次接管和迟到的周期同步都从同一费用账本计入窗口内已完成请求 sqlx::query_scalar(sqlx::AssertSqlSafe(format!("update client_api_key_budget_windows set - {column}_explicit=true, {column}_start=$2, {column}_end=$3, + {column}_explicit=$5, {column}_start=$2, {column}_end=$3, {column}_used_usd=case when charge_history_since > $2 then {column}_used_usd else (select coalesce(sum(amount_usd),0) from client_api_key_charge_events where client_api_key_id=$1 and completed_at >= $2 and completed_at < $3) end, revision=revision+1,last_operation_request=$4 where client_api_key_id=$1 and (charge_history_since is null or charge_history_since <= $2 or ({column}_start=$2 and {column}_end=$3)) returning revision"))) - .bind(command.id.as_str()).bind(window.starts_at).bind(window.ends_at).bind(request) + .bind(command.id.as_str()).bind(window.starts_at).bind(window.ends_at).bind(request).bind(!window.resume_calendar) .fetch_optional(&mut *tx).await.map_err(unavailable)? .ok_or_else(|| AdminStoreError::new(AdminStoreErrorKind::Conflict, "client API key", "费用历史不完整,无法重算该预算窗口"))? diff --git a/backend/crates/gateway-store/src/postgres/client_budgets.rs b/backend/crates/gateway-store/src/postgres/client_budgets.rs index 5fb24bf75..924d61323 100644 --- a/backend/crates/gateway-store/src/postgres/client_budgets.rs +++ b/backend/crates/gateway-store/src/postgres/client_budgets.rs @@ -458,6 +458,24 @@ pub(super) async fn load_client_key_budgets( .iter() .map(|record| record.id.as_str()) .collect::>(); + let mut budgets = read_client_key_budgets(pool, &ids).await?; + for record in records { + record.budget = + budgets + .remove(&record.id) + .ok_or_else(|| crate::StoreError::Unavailable { + backend: crate::StoreBackend::PostgreSql, + message: "load client budget policy".to_owned(), + source: None, + })?; + } + Ok(()) +} + +pub(super) async fn read_client_key_budgets( + pool: &PgPool, + ids: &[&str], +) -> StoreResult> { // 起止相等是重置后的未开启窗口,不能因应用时钟领先数据库而投影为活跃预算 let rows = sqlx::query( "select k.id, k.daily_limit_usd::text, k.weekly_limit_usd::text, @@ -504,17 +522,7 @@ pub(super) async fn load_client_key_budgets( }, ); } - for record in records { - record.budget = - budgets - .remove(&record.id) - .ok_or_else(|| crate::StoreError::Unavailable { - backend: crate::StoreBackend::PostgreSql, - message: "load client budget policy".to_owned(), - source: None, - })?; - } - Ok(()) + Ok(budgets) } pub(super) fn stored_window( diff --git a/backend/crates/gateway-store/src/postgres/client_keys.rs b/backend/crates/gateway-store/src/postgres/client_keys.rs index a00ea1cd8..8ccf21efc 100644 --- a/backend/crates/gateway-store/src/postgres/client_keys.rs +++ b/backend/crates/gateway-store/src/postgres/client_keys.rs @@ -16,7 +16,8 @@ use gateway_admin::{ MutationContext, account_groups::AccountGroupRef as AdminAccountGroupRef, client_keys::{ - BatchUpdateClientKeys, ClientKeyCursor as AdminClientKeyCursor, + BatchUpdateClientKeys, BudgetReferenceAccountPage, + ClientKeyCursor as AdminClientKeyCursor, ClientKeyCursorValue as AdminClientKeyCursorValue, ClientKeyListQuery as AdminClientKeyListQuery, ClientKeyPage as AdminClientKeyPage, ClientKeyRecord as AdminClientKeyRecord, ClientKeySecret as AdminClientKeySecret, @@ -731,6 +732,70 @@ impl PgAdminClientKeyStore { #[async_trait] impl ClientKeyStore for PgAdminClientKeyStore { + async fn client_key_budget( + &self, + id: &ClientApiKeyId, + ) -> AdminStoreResult> { + super::client_budgets::read_client_key_budgets(&self.keys.pool, &[id.as_str()]) + .await + .map(|mut budgets| budgets.remove(id.as_str())) + .map_err(|error| admin_store_error(ENTITY, error)) + } + + async fn budget_reference_accounts( + &self, + id: &gateway_core::policy::ClientApiKeyId, + search: &str, + after: &str, + ) -> AdminStoreResult { + use gateway_admin::model::client_keys::BudgetReferenceAccount; + const PAGE_SIZE: u8 = 20; + let store_error = + |operation, source| admin_store_error(ENTITY, postgres_unavailable(operation, source)); + // 空分组表示全部账号,只有启用分组内的成员可作为受限密钥的参考账号 + let groups: Vec = sqlx::query_scalar( + "select array(select account_group_id from client_api_key_groups where client_api_key_id = k.id) + from client_api_keys k where k.id = $1", + ) + .bind(id.as_str()) + .fetch_optional(&self.keys.pool) + .await + .map_err(|error| store_error("read key groups", error))? + .ok_or_else(|| admin_store_error(ENTITY, StoreError::NotFound { + source: None, entity: ENTITY, id: id.as_str().to_owned() + }))?; + let rows: Vec<(String, String, Option, String)> = sqlx::query_as( + "select a.id, a.name, a.email, a.provider_kind from provider_accounts a + where a.id > $1 + and ($2 = '' or strpos(lower(a.name), lower($2)) > 0 + or strpos(lower(coalesce(a.email, '')), lower($2)) > 0) + and (cardinality($3::text[]) = 0 or exists ( + select 1 from account_group_accounts m join account_groups g on g.id = m.account_group_id + where m.provider_account_id = a.id and m.account_group_id = any($3) and g.enabled)) + order by a.id limit $4", + ) + .bind(after) + .bind(search) + .bind(&groups) + .bind(i64::from(PAGE_SIZE) + 1) + .fetch_all(&self.keys.pool) + .await + .map_err(|error| store_error("select reference accounts", error))?; + let has_more = rows.len() > usize::from(PAGE_SIZE); + let items: Vec<_> = rows + .into_iter() + .take(usize::from(PAGE_SIZE)) + .map(|(id, name, email, provider)| BudgetReferenceAccount { + id, + name, + email, + provider, + }) + .collect(); + let next_cursor = items.last().filter(|_| has_more).map(|row| row.id.clone()); + Ok(BudgetReferenceAccountPage { items, next_cursor }) + } + async fn client_key_budget_window( &self, id: &ClientApiKeyId, diff --git a/backend/crates/gateway-store/src/postgres/observability/admin_adapter.rs b/backend/crates/gateway-store/src/postgres/observability/admin_adapter.rs index 8181c7e18..e3fc9159d 100644 --- a/backend/crates/gateway-store/src/postgres/observability/admin_adapter.rs +++ b/backend/crates/gateway-store/src/postgres/observability/admin_adapter.rs @@ -511,6 +511,57 @@ impl AdminObservabilityStore for PgAdminObservabilityStore { .collect()) } + async fn client_key_statistics( + &self, + range: admin_observability::TimeRange, + id: &gateway_core::policy::ClientApiKeyId, + query: admin_observability::KeyUsageMetric, + ) -> AdminStoreResult { + let range = store_range(range).map_err(observability_error)?; + let timezone = self.repository.timezone; + self.repository + .query_budget + .run( + &self.repository.pool, + "load key usage statistics", + |mut connection| async move { + let mut snapshot = AnalyticsSnapshot::new(&mut connection).await?; + let result = snapshot + .client_key_statistics(range, id.as_str(), timezone, query) + .await?; + snapshot.finish().await?; + Ok(result) + }, + ) + .await + .map_err(observability_error) + } + + async fn client_key_models( + &self, + range: admin_observability::TimeRange, + id: &gateway_core::policy::ClientApiKeyId, + ) -> AdminStoreResult> { + let range = store_range(range).map_err(observability_error)?; + let timezone = self.repository.timezone; + self.repository + .query_budget + .run( + &self.repository.pool, + "load key usage statistics", + |mut connection| async move { + let mut snapshot = AnalyticsSnapshot::new(&mut connection).await?; + let result = snapshot + .client_key_models(range, id.as_str(), timezone) + .await?; + snapshot.finish().await?; + Ok(result) + }, + ) + .await + .map_err(observability_error) + } + async fn usage_trend( &self, range: admin_observability::TimeRange, diff --git a/backend/crates/gateway-store/src/postgres/observability/analytics/key_usage.rs b/backend/crates/gateway-store/src/postgres/observability/analytics/key_usage.rs new file mode 100644 index 000000000..6dceb3f9a --- /dev/null +++ b/backend/crates/gateway-store/src/postgres/observability/analytics/key_usage.rs @@ -0,0 +1,206 @@ +//! 单密钥趋势与模型汇总在数据库内归并,输出规模分别随日期数和模型数增长 +use super::*; +use admin_observability::{KeyModelRow, KeyStatisticsOverview, KeyUsageMetric}; +use gateway_core::time::DeploymentTimeZone; +use sqlx::types::Json; + +const TOTALS: &str = "jsonb_build_object('requests',requests,'tokens',tokens,'costUsd',cost::text, + 'hasEstimatedCost',estimated,'hasMissingCost',missing)"; + +impl AnalyticsSnapshot<'_> { + async fn key_usage_query( + &mut self, + range: ObservabilityRange, + key: &str, + timezone: DeploymentTimeZone, + ) -> StoreResult> { + self.require_visible(Some(range))?; + let boundaries = calendar_buckets(range, timezone)?; + let mut sql = QueryBuilder::new( + "with parts(bucket,model,counts,costs,contribution) as ( + select bucket_start,dimensions[2],counts,costs,true from request_analytics_1h + where collection='usage_contribution' and dimensions[4]=", + ); + sql.push_bind(key.to_owned()) + .push(" and bucket_start >= ") + .push_bind(range.start) + .push(" and bucket_start < ") + .push_bind(range.end); + + let spans = if boundaries + .iter() + .all(|t| t.timestamp().rem_euclid(900) == 0) + { + let hourly = boundaries + .iter() + .all(|t| t.timestamp().rem_euclid(3600) == 0); + let (hours, quarters) = self.summary_buckets(range, hourly).await?; + let model = + aggregate::summary_dimension_sql("key_model", Some(DiagnosticDimension::Model)); + for (table, seconds, buckets) in [ + ("request_analytics_1h", 3600, hours), + ("request_analytics_15m", 900, quarters), + ] { + if buckets.is_empty() { + continue; + } + sql.push(format!( + " union all select bucket_start,{model},counts,costs,false from {table} + where collection='key_model' and schema_version=" + )) + .push_bind(SCHEMA_VERSION) + .push(" and histogram_version=") + .push_bind(HISTOGRAM_VERSION) + .push(" and dimensions[1]=") + .push_bind(key.to_owned()); + push_summary_buckets(&mut sql, &buckets, seconds); + } + self.uncovered_spans(range).await? + } else { + vec![(range.start, range.end)] + }; + + if !spans.is_empty() { + let (starts, ends): (Vec<_>, Vec<_>) = spans.into_iter().unzip(); + sql.push( + " union all select bucket_start,name,counts,costs,false from (with matching as ( + select mr.*,", + ) + .push(completed_usage_fact_predicate("mr")) + .push(" as is_completed_usage,"); + aggregate::push_output_bucket( + &mut sql, + "mr.started_at", + range, + Some(ObservationGranularity::Day), + Some(&boundaries), + ); + sql.push(" as output_bucket,") + .push(aggregate::fact_dimension_sql(Some( + DiagnosticDimension::Model, + ))) + .push(" as name from unnest(") + .push_bind(starts) + .push("::timestamptz[],") + .push_bind(ends) + .push( + "::timestamptz[]) span(start_at,end_at) cross join lateral ( + select * from request_analytics_facts f where f.client_api_key_ref=", + ) + .push_bind(key.to_owned()) + .push(" and f.started_at >= span.start_at and f.started_at < span.end_at"); + push_unrecovered_request_filter(&mut sql, "f"); + sql.push(" offset 0) mr)"); + aggregate::push_fact_aggregation_selected( + &mut sql, + false, + true, + DistributionRead::None, + Some(&[ + "request_count", + "total_tokens", + "total_tokens_known_count", + "calculated_count", + "unavailable_count", + ]), + None, + ); + sql.push(") fact_parts"); + } + sql.push("), daily as ( + select (bucket at time zone ").push_bind(timezone.name()).push(")::date as day, model, + coalesce(sum((counts->>'request_count')::numeric),0) as requests, + sum(case when contribution and not counts ? 'total_tokens' and counts ?| array['input_tokens','output_tokens'] + then coalesce((counts->>'input_tokens')::numeric,0) + coalesce((counts->>'output_tokens')::numeric,0) + else (counts->>'total_tokens')::numeric end) + filter(where contribution or (counts->>'total_tokens_known_count')::numeric > 0) as tokens, + sum((costs->>'USD')::numeric) as cost, + coalesce(sum((counts->>'calculated_count')::numeric),0)>0 as estimated, + bool_or(coalesce((counts->>'unavailable_count')::numeric,0)>0 + or (costs - array['USD','standard_usd','no_cache_usd']) <> '{}'::jsonb + or (coalesce((counts->>'request_count')::numeric,0)>0 and not costs ? 'USD')) as missing + from parts group by 1,2 + ), models as ( + select model,sum(requests) as requests,sum(tokens) as tokens,sum(cost) as cost, + bool_or(estimated) as estimated,bool_or(missing or cost is null) as missing, + max(requests) as peak, count(*) filter(where requests>0) as active, + bool_or(requests<0 or coalesce(tokens<0,false) or coalesce(cost<0,false)) + or coalesce(greatest(max(cost),sum(cost)) > ").push_bind(gateway_core::metering::Decimal::MAX.canonical()) + .push("::numeric,false) as invalid_amount + from daily group by model + ) "); + Ok(sql) + } + + pub(crate) async fn client_key_statistics( + &mut self, + range: ObservabilityRange, + key: &str, + timezone: DeploymentTimeZone, + metric: KeyUsageMetric, + ) -> StoreResult { + let field = match metric { + KeyUsageMetric::CostUsd => "cost", + KeyUsageMetric::Tokens => "tokens", + KeyUsageMetric::Requests => "requests", + }; + let mut sql = self.key_usage_query(range, key, timezone).await?; + // 先按整个周期选出模型,再合并其余模型,防止同一颜色在不同日期代表不同模型 + sql.push(format!(", ranked as ( + select model,row_number() over(order by {field} desc nulls last,model collate \"C\") as pos from models + ), series_days as ( + select day,case when pos<=5 then daily.model end as model,least(pos,6) as pos,sum({field})::text as value + from daily join ranked using(model) group by 1,2,3 + ), series as ( + select model,pos,jsonb_agg(jsonb_build_object('date',day,'value',value) order by day) as points + from series_days group by model,pos + ), totals as ( + select coalesce(sum(requests),0) as requests,sum(tokens) as tokens,sum(cost) as cost, + coalesce(bool_or(estimated),false) as estimated,coalesce(bool_or(missing),false) as missing,count(*) as model_count,coalesce(bool_or(invalid_amount),false) as invalid_amount from models + ) select jsonb_build_object('totals',{TOTALS},'modelCount',model_count,'series', + coalesce((select jsonb_agg(jsonb_build_object('model',model,'points',points) order by pos) from series),'[]'::jsonb)), invalid_amount + from totals")); + let (Json(result), invalid_amount): (Json, bool) = sql + .build_query_as() + .fetch_one(&mut *self.tx) + .await + .map_err(|error| postgres_unavailable("read bounded key usage trend", error))?; + if invalid_amount + || result + .totals + .cost_usd + .as_deref() + .is_some_and(|amount| amount.parse::().is_err()) + { + return Err(invalid("key usage aggregate exceeds native range")); + } + Ok(result) + } + + pub(crate) async fn client_key_models( + &mut self, + range: ObservabilityRange, + key: &str, + timezone: DeploymentTimeZone, + ) -> StoreResult> { + let mut sql = self.key_usage_query(range, key, timezone).await?; + sql.push(format!( + "select jsonb_build_object('model',model,'totals',{TOTALS}, + 'peakRequests',peak,'activeDays',active),invalid_amount from models order by model collate \"C\"" + )); + let rows: Vec<(Json, bool)> = sql + .build_query_as() + .fetch_all(&mut *self.tx) + .await + .map_err(|error| postgres_unavailable("read key model totals", error))?; + rows.into_iter() + .map(|(Json(row), invalid_amount)| { + if invalid_amount { + Err(invalid("key usage aggregate exceeds native range")) + } else { + Ok(row) + } + }) + .collect() + } +} diff --git a/backend/crates/gateway-store/src/postgres/observability/analytics/mod.rs b/backend/crates/gateway-store/src/postgres/observability/analytics/mod.rs index a392b8b2b..7abc39887 100644 --- a/backend/crates/gateway-store/src/postgres/observability/analytics/mod.rs +++ b/backend/crates/gateway-store/src/postgres/observability/analytics/mod.rs @@ -8,6 +8,7 @@ mod counts; mod forecast; mod histogram; mod incremental; +mod key_usage; mod metrics; mod query; mod reset; diff --git a/backend/crates/gateway-store/tests/postgres/backup_export.rs b/backend/crates/gateway-store/tests/postgres/backup_export.rs index 8f21651b9..fe2c53c12 100644 --- a/backend/crates/gateway-store/tests/postgres/backup_export.rs +++ b/backend/crates/gateway-store/tests/postgres/backup_export.rs @@ -154,6 +154,7 @@ async fn business_backup_restores_core_state_and_usage_without_request_history() period: ClientKeyBudgetWindowPeriod::Weekly, expected_revision: saved.revision, window: Some(ExplicitClientKeyBudgetWindow { + resume_calendar: false, starts_at: saved.starts_at.unwrap(), ends_at: saved.ends_at.unwrap(), }), @@ -184,6 +185,7 @@ async fn business_backup_restores_core_state_and_usage_without_request_history() .await .unwrap(); change.window = Some(ExplicitClientKeyBudgetWindow { + resume_calendar: false, starts_at: start, ends_at: start + TimeDelta::hours(1), }); diff --git a/backend/crates/gateway-store/tests/postgres/client_budget_windows.rs b/backend/crates/gateway-store/tests/postgres/client_budget_windows.rs index 2c0c94f19..6dbd16ea1 100644 --- a/backend/crates/gateway-store/tests/postgres/client_budget_windows.rs +++ b/backend/crates/gateway-store/tests/postgres/client_budget_windows.rs @@ -25,6 +25,7 @@ fn window( period: ClientKeyBudgetWindowPeriod::Weekly, expected_revision: revision, window: Some(ExplicitClientKeyBudgetWindow { + resume_calendar: false, starts_at: start, ends_at: end, }), @@ -367,3 +368,129 @@ async fn explicit_window_admission_counts_pending_cost_once() { ); database.close().await; } + +#[tokio::test] +async fn manual_alignment_counts_only_current_charges_and_returns_to_calendar_at_expiry() { + let Some(db) = TestDatabase::create("manual_alignment").await else { + return; + }; + seed(&db, "key", "10", "20").await; + let admin = PgAdminClientKeyStore::new(db.pool.clone()); + let budgets = PgClientBudgetStore::new(db.pool.clone()); + let now = chrono::DateTime::from_timestamp_millis(Utc::now().timestamp_millis()).unwrap(); + let mut outside = charge("key", "outside", "4"); + outside.completed_at = (now - Duration::days(8)).into(); + budgets.settle(outside).await.unwrap(); + budgets.settle(charge("key", "inside", "3")).await.unwrap(); + let before = status(&db, "key").await; + let end = now + Duration::days(1); + let mut command = window(0, end - Duration::days(7), end); + command.window.as_mut().unwrap().resume_calendar = true; + let mut expired = command.clone(); + expired.window.as_mut().unwrap().ends_at = now; + let origin = || ClientKeyBudgetMutationOrigin::Admin; + assert_eq!( + admin + .set_client_key_budget_window(expired, origin(), &context()) + .await + .unwrap_err() + .kind(), + AdminStoreErrorKind::Conflict + ); + admin + .set_client_key_budget_window(command.clone(), origin(), &context()) + .await + .unwrap(); + let after = status(&db, "key").await; + assert_eq!(after.daily_used_usd, before.daily_used_usd); + assert_eq!(after.limits, before.limits); + assert_eq!(after.weekly_used_usd.canonical(), "3"); + let aligned = admin + .client_key_budget_window(&key_id("key"), ClientKeyBudgetWindowPeriod::Weekly) + .await + .unwrap(); + assert_eq!(aligned.ends_at, Some(end)); + assert!(!aligned.explicit); + budgets.settle(charge("key", "after", "2")).await.unwrap(); + assert_eq!( + admin + .set_client_key_budget_window(command, origin(), &context()) + .await + .unwrap(), + 1 + ); + assert_eq!(status(&db, "key").await.weekly_used_usd.canonical(), "5"); + // 将同一账本推进至到期状态,验证下一次准入会续开原生窗口 + sqlx::query("update client_api_key_budget_windows set weekly_start = weekly_start - interval '2 days', weekly_end = weekly_end - interval '2 days' where client_api_key_id = 'key'").execute(&db.pool).await.unwrap(); + budgets.admit(key_id("key")).await.unwrap(); + let next = admin + .client_key_budget_window(&key_id("key"), ClientKeyBudgetWindowPeriod::Weekly) + .await + .unwrap(); + assert!(next.ends_at.unwrap() > end); + assert_eq!(next.used_usd.canonical(), "0"); + db.close().await; +} + +#[tokio::test] +async fn reference_accounts_page_through_large_pools_and_search_only_key_groups() { + let Some(database) = TestDatabase::create("budget_reference_accounts").await else { + return; + }; + seed(&database, "key", "0", "0").await; + let key = key_id("key"); + let store = PgAdminClientKeyStore::new(database.pool.clone()); + sqlx::query( + "insert into provider_accounts (id, name, email, provider_kind, authentication_kind, + provider_credentials_json, has_refresh_token, credential_observed_at, created_at, updated_at) + select 'ref-' || n, 'Account ' || n, 'person' || n || '@example.test', 'openai', 'oauth', + '{}'::jsonb, false, now(), now(), now() + from generate_series(1000, 2199) n", + ).execute(&database.pool).await.unwrap(); + let first = store.budget_reference_accounts(&key, "", "").await.unwrap(); + assert_eq!(first.items.len(), 20); + let next = store + .budget_reference_accounts(&key, "", first.next_cursor.as_deref().unwrap()) + .await + .unwrap(); + assert_eq!(next.items[0].id, "ref-1020"); + let id_only = store + .budget_reference_accounts(&key, "ref-2199", "") + .await + .unwrap(); + assert!(id_only.items.is_empty()); + for term in ["PERSON2199@", "account 2199"] { + let page = store + .budget_reference_accounts(&key, term, "") + .await + .unwrap(); + assert_eq!(page.items.len(), 1); + assert_eq!(page.items[0].id, "ref-2199"); + assert!(page.next_cursor.is_none()); + } + let group = "grp_00000000000000000000000000000001"; + sqlx::query("insert into account_groups(id, name, color, created_at, updated_at) values ($1, 'Test', '#2563EBFF', now(), now())") + .bind(group).execute(&database.pool).await.unwrap(); + sqlx::query("insert into client_api_key_groups(client_api_key_id, account_group_id, created_at) values ('key', $1, now())").bind(group).execute(&database.pool).await.unwrap(); + sqlx::query("insert into account_group_accounts(account_group_id, provider_account_id, created_at) values ($1, 'ref-2198', now())").bind(group).execute(&database.pool).await.unwrap(); + let scoped = store + .budget_reference_accounts(&key, "219", "") + .await + .unwrap(); + assert_eq!(scoped.items.len(), 1); + assert_eq!(scoped.items[0].id, "ref-2198"); + sqlx::query("update account_groups set enabled = false where id = $1") + .bind(group) + .execute(&database.pool) + .await + .unwrap(); + assert!( + store + .budget_reference_accounts(&key, "", "") + .await + .unwrap() + .items + .is_empty() + ); + database.close().await; +} diff --git a/backend/crates/gateway-store/tests/postgres/usage_data/read.rs b/backend/crates/gateway-store/tests/postgres/usage_data/read.rs index ab974c4c8..19ebb780c 100644 --- a/backend/crates/gateway-store/tests/postgres/usage_data/read.rs +++ b/backend/crates/gateway-store/tests/postgres/usage_data/read.rs @@ -478,3 +478,163 @@ async fn byte_boundaries_timeout_and_cancellation_release_readers() { after.close().await; db.close().await; } + +#[tokio::test] +async fn admin_key_model_statistics_keep_local_days_and_missing_model_through_rollup() { + use gateway_admin::{model::observability::TimeRange, ports::store::ObservabilityStore as _}; + use gateway_core::policy::ClientApiKeyId; + use gateway_store::postgres::PgAdminObservabilityStore; + + let Some(db) = TestDatabase::create("key_model_days").await else { + return; + }; + let writer = PgUsageDataStore::new(db.pool.clone(), observability_query_budget()); + let reader = + PgAdminObservabilityStore::new(db.pool.clone(), None, None, observability_query_budget()) + .with_timezone("America/New_York".parse().unwrap()); + let mut unassigned = data(6); + unassigned.model = None; + unassigned.requested_model = None; + unassigned.started_at_ms += 5 * 3_600_000; + unassigned.completed_at_ms = Some(unassigned.started_at_ms + 1_000); + let mut priced = data(10); + priced.cost = UsageCost::Known { + source: UsageCostSource::Calculated, + amount: "1.25".into(), + currency: "USD".into(), + }; + let mut other = priced.clone(); + other.client_key_ref = "another_key".into(); + writer + .write_records(records(vec![ + UsageRecordChange::Put { + id: "known".into(), + data: Box::new(priced), + }, + UsageRecordChange::Put { + id: "unassigned".into(), + data: Box::new(unassigned), + }, + UsageRecordChange::Put { + id: "other".into(), + data: Box::new(other), + }, + ])) + .await + .unwrap(); + drain_analytics(&db.pool).await; + let range = TimeRange::new( + start() - TimeDelta::hours(20), + start() + TimeDelta::hours(28), + ) + .unwrap(); + let id = ClientApiKeyId::new("key_usage").unwrap(); + // 非整桶的边缘强制读窄事实,再对照整日汇总 + for range in [ + TimeRange::new( + start() - TimeDelta::milliseconds(1), + start() + TimeDelta::hours(5) + TimeDelta::milliseconds(1), + ) + .unwrap(), + range, + ] { + use gateway_admin::model::observability::KeyUsageMetric; + let overview = reader + .client_key_statistics(range, &id, KeyUsageMetric::CostUsd) + .await + .unwrap(); + assert_eq!(overview.model_count, 2); + assert_eq!(overview.totals.requests, 2); + assert_eq!(overview.totals.tokens, Some(16)); + assert!(overview.totals.has_missing_cost); + assert_eq!(overview.series[0].model.as_deref(), Some("model_a")); + assert_eq!(overview.series[0].points[0].date.to_string(), "2026-09-30"); + assert_eq!(overview.series[1].points[0].date.to_string(), "2026-10-01"); + assert!(overview.series[1].points[0].value.is_none()); + let rows = reader.client_key_models(range, &id).await.unwrap(); + assert_eq!(rows.len(), 2); + assert_eq!(rows[0].model, ""); + assert!(rows[0].totals.cost_usd.is_none()); + assert!(rows[1].totals.has_estimated_cost); + assert!(!rows[1].totals.has_missing_cost); + assert_eq!((rows[1].active_days, rows[1].peak_requests), (1, 1)); + assert_eq!( + rows[1] + .totals + .cost_usd + .as_deref() + .unwrap() + .parse::() + .unwrap() + .canonical(), + "1.25" + ); + } + use gateway_admin::model::observability::KeyUsageMetric; + let mut imported = Vec::new(); + for index in 0..6 { + let UsageAggregateChange::Put { mut aggregate } = + contribution(&format!("rank-{index}"), 3 + index, 42, "0.2") + else { + unreachable!() + }; + aggregate.identity.dimensions.model = Some(format!("extra-{index}")); + imported.push(UsageAggregateChange::Put { aggregate }); + } + let UsageAggregateChange::Put { mut aggregate } = contribution("euro", 1, 8, "1") else { + unreachable!() + }; + aggregate.costs = BTreeMap::from([("EUR".into(), "1".into())]); + aggregate.counts.remove(&UsageMetric::TotalTokens); + aggregate + .counts + .insert(UsageMetric::InputTokens, UsageDelta(3)); + aggregate + .counts + .insert(UsageMetric::OutputTokens, UsageDelta(5)); + imported.push(UsageAggregateChange::Put { aggregate }); + writer.write_aggregates(aggregates(imported)).await.unwrap(); + let result = reader + .client_key_statistics(range, &id, KeyUsageMetric::Requests) + .await + .unwrap(); + assert_eq!(result.model_count, 8); + assert_eq!(result.series.len(), 6); + assert_eq!(result.series[0].model.as_deref(), Some("extra-5")); + assert!(result.series[5].model.is_none()); + assert_eq!( + result + .series + .iter() + .flat_map(|s| &s.points) + .map(|p| p.value.as_ref().unwrap().parse::().unwrap()) + .sum::(), + result.totals.requests + ); + let rows = reader.client_key_models(range, &id).await.unwrap(); + let priced = rows.iter().find(|row| row.model == "model_a").unwrap(); + assert!(priced.totals.has_missing_cost); + assert_eq!(priced.totals.tokens, Some(18)); + assert_eq!( + priced + .totals + .cost_usd + .as_deref() + .unwrap() + .parse::() + .unwrap(), + 1.25 + ); + writer + .write_aggregates(aggregates(vec![contribution("correction", 0, 0, "-2")])) + .await + .unwrap(); + assert!(reader.client_key_models(range, &id).await.is_err()); + assert!( + reader + .client_key_statistics(range, &id, KeyUsageMetric::CostUsd) + .await + .is_err() + ); + db.close().await; +} diff --git a/docs/api.md b/docs/api.md index 1858fa146..2c16bd553 100644 --- a/docs/api.md +++ b/docs/api.md @@ -2036,10 +2036,21 @@ HTTP 返回 `403` 和 `image_generation_disabled`,WebSocket 每个 `response.c | `POST` | `/api/admin/client-keys/update` | 更新字段 | 原子更新名称、分组范围和限额 | | `POST` | `/api/admin/client-keys/batch-update` | `ids` 和至少一个更新字段 | 原子更新 1 至 1000 个不同密钥,返回 `{ updated, configRevision }` | | `POST` | `/api/admin/client-keys/reset-budget` | `{ id, period }` | 管理员清零日/周已用金额;`period` 为 `daily`、`weekly` 或 `all` | +| `GET` | `/api/admin/client-keys/statistics` | `id`、`period`、`metric`、`asOf` | 返回当前额度、周期合计、模型数和所选指标的每日趋势 | +| `GET` | `/api/admin/client-keys/statistics/models` | `id`、`period`、`asOf` | 返回每个模型的周期汇总、活跃天数和单日最高请求数 | +| `GET` | `/api/admin/client-keys/budget-reference-accounts` | `id`、可选 `search`、`cursor` | 按密钥账号范围搜索名称或邮箱,每批最多 20 条,仅返回账号标识和展示字段;`nextCursor` 为空表示已到末尾 | +| `GET` | `/api/admin/client-keys/budget-alignment` | `id`、`accountId` | 预览当前可对齐的账号日/周窗口及密钥窗口版本 | +| `POST` | `/api/admin/client-keys/budget-alignment` | `id`、`accountId`、`windowKey`、`startsAt`、`endsAt`、`revision` | 按预览对齐本期并返回新版本 | | `POST` | `/api/admin/client-keys/enable` | `{ id }` | 启用 | | `POST` | `/api/admin/client-keys/disable` | `{ id }` | 禁用 | | `POST` | `/api/admin/client-keys/delete` | `{ id }` | 删除 | +两个统计接口按部署时区和请求开始时间统计近 7 天(`7d`,默认)或 30 天(`30d`)。概览返回截止时间 `asOf`(Unix 毫秒),切换指标与读取明细时可用其固定统计区间。趋势按 `metric`(`costUsd`、`tokens`、`requests`)返回周期排名前五的模型,其余合为一条曲线(`model: null`)。模型优先取上游实际模型,缺失时回退到请求模型,两者都缺失时为空字符串 + +模型和周期合计包含请求数、已知 Token、已知 USD 费用,以及费用是否含本地估算或存在缺失。无已知数值时对应金额或 Token 为 `null`,费用占比以该 Key 周期内的已知 USD 总额为分母 + +手动对齐使用密钥可访问分组内账号的当前整账号 24 小时或七天窗口。确认时复核预览边界和密钥窗口版本,按完成时间重算本期消费。窗口到期后密钥恢复原生日历规则。已失效的预览或不足以重算的费用历史返回冲突 + 批量更新只提交要修改的字段,各密钥保留其余配置。任一密钥或分组不存在、任一密钥的最终配置无效时,整批回滚 - `enabled` 设置启用状态。`groupIds` 替换全部分组,显式传空数组授权全部当前及未来账号 diff --git a/docs/architecture.md b/docs/architecture.md index 57baf5928..ae280f3e2 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -799,6 +799,7 @@ Core 负责准入与结算时序,Store 持久化费用账本,Admin 负责限 Admin 的手动重置复用同一账本与 Key 行锁,在一个事务中清零所选周期金额、推进计费起点并写入审计, 关闭所选窗口并保留费用事件,不推进配置 revision,下次使用时重新开启窗口。 结算仍按完成时间判断归属,重置前完成的费用不会重新扣入已重置周期或开启窗口。 +管理员手动对齐账号窗口时,同一事务更新所选周期的边界、从费用事件重算已用金额并记录审计。一次性对齐的窗口到期后恢复原生滚动。 插件预算回调通过 `PluginClientKeyAccess` 进入同一 `ClientKeyService` 和 `ClientKeyStore`,存储事务先复核插件实例版本, 再执行原生预算操作;不建立另一份预算状态。查询复用账本投影,不触发准入。局部更新金额上限不改用量或窗口, 仅在值变化时提交配置 revision、审计并发布;重置仍不推进配置版本。重复调用及结果未知的合同见 diff --git a/frontend/package.json b/frontend/package.json index 320eabe26..fa0c8986e 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -17,7 +17,7 @@ }, "dependencies": { "@boxicons/vue": "1.0.1", - "@codex-proxy/ui": "github:zyycn/codex-proxy-ui#v0.12.0", + "@codex-proxy/ui": "github:zyycn/codex-proxy-ui#v0.13.0", "@fontsource-variable/inter": "^5.3.0", "@fontsource-variable/jetbrains-mono": "^5.3.0", "@lucide/vue": "^1.73.0", diff --git a/frontend/pnpm-lock.yaml b/frontend/pnpm-lock.yaml index bdbdc8edb..e042f1d94 100644 --- a/frontend/pnpm-lock.yaml +++ b/frontend/pnpm-lock.yaml @@ -195,8 +195,8 @@ importers: specifier: 1.0.1 version: 1.0.1(vue@3.5.45(typescript@6.0.3)) '@codex-proxy/ui': - specifier: github:zyycn/codex-proxy-ui#v0.12.0 - version: https://codeload.github.com/zyycn/codex-proxy-ui/tar.gz/8ffe8a2386603961f48e7fb12ba03be7a81539ec(axios@1.21.1(debug@4.4.3))(change-case@5.4.4)(jiti@2.7.0)(postcss@8.5.30)(vite@8.3.8(@types/node@26.6.6)(jiti@2.7.0)(yaml@2.9.0))(vue@3.5.45(typescript@6.0.3))(yaml@2.9.0) + specifier: github:zyycn/codex-proxy-ui#v0.13.0 + version: https://codeload.github.com/zyycn/codex-proxy-ui/tar.gz/498a491ea97dbb8c5cedbffd97064edab6969341(axios@1.21.1(debug@4.4.3))(change-case@5.4.4)(jiti@2.7.0)(postcss@8.5.30)(vite@8.3.8(@types/node@26.6.6)(jiti@2.7.0)(yaml@2.9.0))(vue@3.5.45(typescript@6.0.3))(yaml@2.9.0) '@fontsource-variable/inter': specifier: ^5.3.0 version: 5.3.0 @@ -456,9 +456,9 @@ packages: resolution: {integrity: sha512-dlT1m5e/0yUL0kRNcQn7yGLVThkgbB0Ga/1AmfDDC/8ik6AIiSf2QLQO2zPYvefsHP0aFgxO93cVLCCfDp7kzQ==} engines: {node: '>= 20.12.0'} - '@codex-proxy/ui@https://codeload.github.com/zyycn/codex-proxy-ui/tar.gz/8ffe8a2386603961f48e7fb12ba03be7a81539ec': - resolution: {gitHosted: true, integrity: sha512-7QCwJyfOkLDKjmCGh2zwsvbFV2c1fcUlJSpDXsGg9vrZBdsbx9CQtgYwlnsuUm0Oj6wUgrZ4l3YUCBheIzQJkQ==, tarball: https://codeload.github.com/zyycn/codex-proxy-ui/tar.gz/8ffe8a2386603961f48e7fb12ba03be7a81539ec} - version: 0.12.0 + '@codex-proxy/ui@https://codeload.github.com/zyycn/codex-proxy-ui/tar.gz/498a491ea97dbb8c5cedbffd97064edab6969341': + resolution: {gitHosted: true, integrity: sha512-/3G0XsMSCcijhwvwHL7HNLLaI9sEL03m0DDX/aVVGvqu13qsqn6rrsoBvSMgxjYgsvfd5ZnzvbI+ZCva8n/rhQ==, tarball: https://codeload.github.com/zyycn/codex-proxy-ui/tar.gz/498a491ea97dbb8c5cedbffd97064edab6969341} + version: 0.13.0 engines: {node: '>=24'} peerDependencies: vite: ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0 @@ -3571,7 +3571,7 @@ snapshots: fast-wrap-ansi: 0.2.2 sisteransi: 1.0.5 - '@codex-proxy/ui@https://codeload.github.com/zyycn/codex-proxy-ui/tar.gz/8ffe8a2386603961f48e7fb12ba03be7a81539ec(axios@1.21.1(debug@4.4.3))(change-case@5.4.4)(jiti@2.7.0)(postcss@8.5.30)(vite@8.3.8(@types/node@26.6.6)(jiti@2.7.0)(yaml@2.9.0))(vue@3.5.45(typescript@6.0.3))(yaml@2.9.0)': + '@codex-proxy/ui@https://codeload.github.com/zyycn/codex-proxy-ui/tar.gz/498a491ea97dbb8c5cedbffd97064edab6969341(axios@1.21.1(debug@4.4.3))(change-case@5.4.4)(jiti@2.7.0)(postcss@8.5.30)(vite@8.3.8(@types/node@26.6.6)(jiti@2.7.0)(yaml@2.9.0))(vue@3.5.45(typescript@6.0.3))(yaml@2.9.0)': dependencies: '@ant-design/colors': 8.0.1 '@ant-design/fast-color': 3.0.1 diff --git a/frontend/src/api/modules/keys.ts b/frontend/src/api/modules/keys.ts index 3b0eb5a17..e7b5a6f4d 100644 --- a/frontend/src/api/modules/keys.ts +++ b/frontend/src/api/modules/keys.ts @@ -185,3 +185,87 @@ export function enableApiKey(data: ApiKeyIdParam) { data, }) } + +export type KeyUsageMetric = 'costUsd' | 'tokens' | 'requests' +export type KeyStatisticsPeriod = '7d' | '30d' +export interface KeyUsageTotals { + requests: number + tokens: number | null + costUsd: string | null + hasMissingCost: boolean + hasEstimatedCost: boolean +} +export interface KeyModelRow { + model: string + totals: KeyUsageTotals + activeDays: number + peakRequests: number +} +export interface KeyStatistics { + budget: Pick + dates: string[] + asOf: number + totals: KeyUsageTotals + modelCount: number + series: { model: string | null, points: { date: string, value: string | null }[] }[] +} +export function getKeyStatistics(id: string, period: KeyStatisticsPeriod, metric: KeyUsageMetric, asOf: number | undefined, options: RequestOptions) { + return request({ + url: '/api/admin/client-keys/statistics', + method: 'GET', + params: { id, period, metric, asOf }, + ...options, + }) +} +export function getKeyModelTotals(id: string, period: KeyStatisticsPeriod, asOf: number, options: RequestOptions) { + return request({ + url: '/api/admin/client-keys/statistics/models', + method: 'GET', + params: { id, period, asOf }, + ...options, + }) +} + +export interface BudgetReferenceAccount { + id: string + name: string + email: string | null + provider: string +} + +export function getBudgetReferenceAccounts(id: string, search: string, cursor: string | undefined, options: RequestOptions) { + return request<{ items: BudgetReferenceAccount[], nextCursor: string | null }>({ + url: '/api/admin/client-keys/budget-reference-accounts', + method: 'GET', + params: { id, search: search || undefined, cursor }, + ...options, + }) +} + +export interface KeyReferenceWindow { + key: string + label: string + period: 'daily' | 'weekly' + startsAt: string + startsAtDisplay: string + endsAt: string + endsAtDisplay: string +} + +export interface KeyAlignmentPreview { + revision: number + windows: KeyReferenceWindow[] +} + +export function previewKeyAlignment(id: string, accountId: string, options: RequestOptions) { + return request({ + url: '/api/admin/client-keys/budget-alignment', + method: 'GET', + params: { id, accountId }, + ...options, + }) +} + +export function alignKeyBudget(data: { id: string, accountId: string, revision: number, windowKey: string, startsAt: string, endsAt: string }) { + return request({ url: '/api/admin/client-keys/budget-alignment', method: 'POST', data }) +} diff --git a/frontend/src/i18n/locales/en/keys.json b/frontend/src/i18n/locales/en/keys.json index a84672261..f97c0f3ab 100644 --- a/frontend/src/i18n/locales/en/keys.json +++ b/frontend/src/i18n/locales/en/keys.json @@ -29,7 +29,43 @@ "viewUsageAndCostsFor": "View usage and costs for {name}", "costDetailsTitle": "Cost details (USD)", "confirmNextTime": "Confirm next time", + "statistics": { + "title": "Usage statistics", + "heading": "Usage statistics · {name}", + "metric": "Metric", + "period": "Period", + "days": "Last {days} days", + "showingPrevious": "Showing the last {days} days of data.", + "costUsd": "Cost", + "tokens": "Usage", + "requests": "Requests", + "trend": "Daily usage", + "model": "Model", + "other": "Other models ({count})", + "unknownModel": "Unspecified model", + "knownCost": "Known USD costs only", + "costShare": "Cost share", + "peakRequests": "Peak daily requests", + "activeDays": "Active days", + "includesEstimate": "Includes estimated costs", + "empty": "No usage in this period", + "missing": "No known values for this metric" + }, + "alignment": { + "title": "Align to account", + "description": "Recalculate this period’s spending, then resume the original cycle.", + "account": "Reference account", + "noAccounts": "No matching accounts", + "select": "Search by name or email", + "window": "Account window", + "empty": "This account has no active daily or weekly window to align to", + "start": "Window starts", + "end": "Window resets", + "confirm": "Align this window", + "saved": "Budget window aligned" + }, "budgetReset": { + "title": "Reset budget", "dailyQuota": "Daily quota", "weeklyQuota": "Weekly quota", "keyQuotaReset": "Key quota reset", diff --git a/frontend/src/i18n/locales/zh-Hans/keys.json b/frontend/src/i18n/locales/zh-Hans/keys.json index a36ba8956..fcefea71d 100644 --- a/frontend/src/i18n/locales/zh-Hans/keys.json +++ b/frontend/src/i18n/locales/zh-Hans/keys.json @@ -29,7 +29,43 @@ "viewUsageAndCostsFor": "查看 {name} 的费用用量", "costDetailsTitle": "费用详情(USD)", "confirmNextTime": "下次使用时确定", + "statistics": { + "title": "用量统计", + "heading": "用量统计 · {name}", + "metric": "统计指标", + "period": "统计周期", + "days": "近 {days} 天", + "showingPrevious": "当前显示近 {days} 天的数据", + "costUsd": "费用", + "tokens": "用量", + "requests": "请求数", + "trend": "每日用量趋势", + "model": "模型", + "other": "其他 {count} 个模型", + "unknownModel": "未记录模型", + "knownCost": "仅含已知美元费用", + "costShare": "费用占比", + "peakRequests": "单日最高请求数", + "activeDays": "活跃天数", + "includesEstimate": "含本地估算", + "empty": "此期间没有用量记录", + "missing": "此指标暂无已知数值" + }, + "alignment": { + "title": "对齐账号窗口", + "description": "重算本期费用,到期恢复原周期", + "account": "参考账号", + "noAccounts": "没有匹配的账号", + "select": "按名称或邮箱搜索", + "window": "参考窗口", + "empty": "该账号没有可对齐的有效日或周窗口", + "start": "本期开始", + "end": "本期重置", + "confirm": "确认对齐本期", + "saved": "本期额度窗口已对齐" + }, "budgetReset": { + "title": "重置额度", "dailyQuota": "日额度", "weeklyQuota": "周额度", "keyQuotaReset": "已重置密钥额度", diff --git a/frontend/src/i18n/locales/zh-Hant/keys.json b/frontend/src/i18n/locales/zh-Hant/keys.json index 8907269bc..1a21a9182 100644 --- a/frontend/src/i18n/locales/zh-Hant/keys.json +++ b/frontend/src/i18n/locales/zh-Hant/keys.json @@ -29,7 +29,43 @@ "viewUsageAndCostsFor": "查看 {name} 的費用用量", "costDetailsTitle": "費用詳情(USD)", "confirmNextTime": "下次使用時確定", + "statistics": { + "title": "用量統計", + "heading": "用量統計 · {name}", + "metric": "統計指標", + "period": "統計期間", + "days": "近 {days} 天", + "showingPrevious": "目前顯示近 {days} 天的資料", + "costUsd": "費用", + "tokens": "用量", + "requests": "請求數", + "trend": "每日用量趨勢", + "model": "模型", + "other": "其他 {count} 個模型", + "unknownModel": "未記錄模型", + "knownCost": "僅含已知美元費用", + "costShare": "費用佔比", + "peakRequests": "單日最高請求數", + "activeDays": "活躍天數", + "includesEstimate": "含本機估算", + "empty": "此期間沒有用量記錄", + "missing": "此指標暫無已知數值" + }, + "alignment": { + "title": "對齊帳號窗口", + "description": "重算本期費用,到期恢復原週期", + "account": "參考帳號", + "noAccounts": "沒有符合的帳號", + "select": "依名稱或電子郵件搜尋", + "window": "參考窗口", + "empty": "此帳號沒有可對齊的有效日或週窗口", + "start": "本期開始", + "end": "本期重設", + "confirm": "確認對齊本期", + "saved": "本期額度窗口已對齊" + }, "budgetReset": { + "title": "重置額度", "dailyQuota": "日額度", "weeklyQuota": "周額度", "keyQuotaReset": "已重置密鑰額度", diff --git a/frontend/src/views/key-usage/components/KeyUsageBudget.vue b/frontend/src/views/key-usage/components/KeyUsageBudget.vue index 11bb9e4e7..f9424a13e 100644 --- a/frontend/src/views/key-usage/components/KeyUsageBudget.vue +++ b/frontend/src/views/key-usage/components/KeyUsageBudget.vue @@ -1,13 +1,12 @@ diff --git a/frontend/src/views/key-usage/index.vue b/frontend/src/views/key-usage/index.vue index 6c1b041c3..89504ec9b 100644 --- a/frontend/src/views/key-usage/index.vue +++ b/frontend/src/views/key-usage/index.vue @@ -1,5 +1,5 @@ + + diff --git a/frontend/src/views/keys/components/ApiKeyBudgetResetModal.vue b/frontend/src/views/keys/components/ApiKeyBudgetResetModal.vue index e4656c355..53a2b79cc 100644 --- a/frontend/src/views/keys/components/ApiKeyBudgetResetModal.vue +++ b/frontend/src/views/keys/components/ApiKeyBudgetResetModal.vue @@ -3,12 +3,14 @@ import type { ApiKey } from '@/api' import { ZButton, ZDialog, ZSegmented } from '@codex-proxy/ui' import { ArrowRight } from '@lucide/vue' -import { computed, shallowRef, watch } from 'vue' +import { computed, shallowRef, useTemplateRef, watch } from 'vue' import { useI18n } from 'vue-i18n' import { resetApiKeyBudget } from '@/api' import { useAsyncAction } from '@/composables/useAsyncAction' import { notification as ZNotification } from '@/utils/notification' +import ApiKeyBudgetAlignment from './ApiKeyBudgetAlignment.vue' + const props = defineProps<{ apiKey: ApiKey | null }>() const emit = defineEmits<{ reset: [] }>() @@ -17,7 +19,25 @@ const { t } = useI18n({ useScope: 'global' }) const open = defineModel({ default: false }) const period = shallowRef('all') -const { loading, run } = useAsyncAction() +const mode = shallowRef('reset') +const alignment = useTemplateRef>('alignment') +const aligning = shallowRef(false) +const { loading: resetting, run } = useAsyncAction() +const loading = computed(() => resetting.value || aligning.value) +const modes = computed(() => [ + { + value: 'reset', + label: t('keys.actions.resetUsedCredit'), + }, + { + value: 'align', + label: t('keys.alignment.title'), + }, +]) +function finishAlignment() { + open.value = false + emit('reset') +} const periods = computed(() => ([ { label: t('common.values.all'), @@ -48,8 +68,11 @@ const windows = computed(() => props.apiKey : []) watch(open, (value) => { - if (value) + if (value) { + mode.value = 'reset' period.value = 'all' + aligning.value = false + } }) async function resetBudget() { @@ -71,8 +94,8 @@ async function resetBudget() { diff --git a/frontend/src/views/keys/components/ApiKeyModelUsageTable.vue b/frontend/src/views/keys/components/ApiKeyModelUsageTable.vue new file mode 100644 index 000000000..62ef6fe5c --- /dev/null +++ b/frontend/src/views/keys/components/ApiKeyModelUsageTable.vue @@ -0,0 +1,135 @@ + + + diff --git a/frontend/src/views/keys/components/ApiKeyStatisticsModal.vue b/frontend/src/views/keys/components/ApiKeyStatisticsModal.vue new file mode 100644 index 000000000..6ac90bc66 --- /dev/null +++ b/frontend/src/views/keys/components/ApiKeyStatisticsModal.vue @@ -0,0 +1,220 @@ + + + diff --git a/frontend/src/views/keys/components/KeyReferenceAccountPicker.vue b/frontend/src/views/keys/components/KeyReferenceAccountPicker.vue new file mode 100644 index 000000000..017124481 --- /dev/null +++ b/frontend/src/views/keys/components/KeyReferenceAccountPicker.vue @@ -0,0 +1,111 @@ + + + diff --git a/frontend/src/views/keys/index.vue b/frontend/src/views/keys/index.vue index 5811b744a..7d35f4a63 100644 --- a/frontend/src/views/keys/index.vue +++ b/frontend/src/views/keys/index.vue @@ -20,6 +20,7 @@ import ApiKeyFormModal from './components/ApiKeyFormModal.vue' import ApiKeyIdentityCell from './components/ApiKeyIdentityCell.vue' import ApiKeyPrefixCell from './components/ApiKeyPrefixCell.vue' import ApiKeyScopeCell from './components/ApiKeyScopeCell.vue' +import ApiKeyStatisticsModal from './components/ApiKeyStatisticsModal.vue' import ApiKeyStatusBadge from './components/ApiKeyStatusBadge.vue' import { useApiKeyEditor } from './composables/useApiKeyEditor' import { useApiKeyMutations } from './composables/useApiKeyMutations' @@ -33,6 +34,7 @@ const selectedIds = ref>(new Set()) const showBatchEdit = shallowRef(false) const batchKeys = shallowRef([]) const showBudgetResetModal = shallowRef(false) +const statisticsKey = shallowRef(null) const resettingKey = shallowRef(null) function openBudgetReset(key: ApiKey) { @@ -244,6 +246,7 @@ watch([showFormModal, showBatchEdit], ([editor, batch]) => { :configuring="revealingKeys.get(row.id) === 'use'" :updating-status="updatingStatusKeyIds.has(row.id)" @edit="openEdit" + @statistics="statisticsKey = $event" @reset-budget="openBudgetReset" @delete="requestDeleteKey" @import-client="openImportKeyModal" @@ -284,6 +287,8 @@ watch([showFormModal, showBatchEdit], ([editor, batch]) => { @after-leave="clearCreatedKey" /> + +