跳到主要内容

数据模型

实体关系与建表 DDL。SQLite 为基准,MySQL / Postgres 由 GORM AutoMigrate 翻译,方言差异收口在 internal/store/dialect.go。

3. 数据模型​

3.1 实体关系​

Provider(提供商) 1──N ApiKey(密钥)
Provider 1──N Model(真实模型)
Model M──N ApiKey ← model_key 关联表(带权重,须同提供商)
Model M──N ApiKey ← model_key_ban 组合禁用记录(细粒度熔断)
Route(逻辑modelId) 1──N RouteTarget ──N──1 Model(带 weight)

熔断粒度是「模型 × 密钥」组合(model_key_ban):某个上游密钥对某个模型失效不等于整个 模型对所有密钥失效。模型的可用性是派生结论(绑定密钥是否全部被禁用,store.ModelHealth), 因此没有单一写入点,也不与路由(RouteTarget)绑定。

3.2 建表 DDL(SQLite 为基准,MySQL / Postgres 由 GORM AutoMigrate 翻译)​

多后端口径:schema 仍以 SQLite DDL 为基准文档。切换 database.driver 到 mysql / postgres 时,实体表由 GORM AutoMigrate 按方言翻译(TEXT 列的 DEFAULT '' 与 TEXT 索引在 MySQL 非法,模型层已去除 text 列默认值、virtual_key.key_value 定长 varchar(191) 承载唯一索引);content_log 因体积大不走 AutoMigrate,由 Dialect.contentLogDDL() 按方言手写建表(MySQL 把 idx_cl_time 内联进建表语句)。 上面的 DDL 摘要仅供理解实体关系,实际列类型以运行时迁移为准。

-- 提供商
CREATE TABLE provider (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL UNIQUE,
base_url TEXT NOT NULL, -- 如 https://open.bigmodel.cn/api/paas/v4
proxy_url TEXT NOT NULL DEFAULT '',
timeout_ms INTEGER NOT NULL DEFAULT 120000, -- 单次尝试的"首字节超时"
remark TEXT NOT NULL DEFAULT '',
header_profile TEXT NOT NULL DEFAULT '', -- 客户端模拟请求头 JSON 对象
created_at INTEGER NOT NULL,
updated_at INTEGER NOT NULL
);

-- 密钥
CREATE TABLE api_key (
id INTEGER PRIMARY KEY AUTOINCREMENT,
provider_id INTEGER NOT NULL REFERENCES provider(id) ON DELETE CASCADE,
key_value TEXT NOT NULL, -- 明文存储(本地工具),UI 脱敏展示 + 显式明文查看按钮
name TEXT NOT NULL DEFAULT '', -- 名称(新增必填、同提供商内唯一):日志/统计/模型绑定处的回显标识
created_at INTEGER NOT NULL,
updated_at INTEGER NOT NULL
);

-- 真实模型(type 决定端点家族,protocol 决定上游调用格式;禁用粒度在 model_key_ban)
CREATE TABLE model (
id INTEGER PRIMARY KEY AUTOINCREMENT,
provider_id INTEGER NOT NULL REFERENCES provider(id) ON DELETE CASCADE,
name TEXT NOT NULL, -- 真实模型名,如 glm-4.6
type TEXT NOT NULL DEFAULT 'chat', -- chat | embedding | rerank | image | tts | stt | video;非 chat 仅支持 completions 协议
protocol TEXT NOT NULL DEFAULT 'completions', -- completions(/chat/completions) | responses(/responses) | messages(/v1/messages) | gemini(generateContent)
input_price REAL NOT NULL DEFAULT 0, -- 每 1M prompt token 价格(billing_mode=token)
cached_price REAL NOT NULL DEFAULT 0, -- 每 1M 命中缓存输入 token 价格;<=0 回退输入价
output_price REAL NOT NULL DEFAULT 0, -- 每 1M completion token 价格(billing_mode=token)
per_call_price REAL NOT NULL DEFAULT 0, -- 每次调用价格(billing_mode=per_call)
billing_mode TEXT NOT NULL DEFAULT 'token', -- token | per_call
price_currency TEXT NOT NULL DEFAULT 'USD', -- 价格币种:仅 USD
api_path TEXT NOT NULL DEFAULT '', -- 自定义 API 路径覆盖(空=按协议默认路径拼接)
body_override TEXT NOT NULL, -- 请求体覆盖 JSON(合并进出站请求体)
notified_status TEXT NOT NULL DEFAULT '', -- 通知去重:'' 或 'disabled'
created_at INTEGER NOT NULL,
updated_at INTEGER NOT NULL,
UNIQUE(provider_id, name)
);

-- 模型 × 密钥 多对多(密钥须与模型同提供商)
CREATE TABLE model_key (
model_id INTEGER NOT NULL REFERENCES model(id) ON DELETE CASCADE,
key_id INTEGER NOT NULL REFERENCES api_key(id) ON DELETE CASCADE,
weight INTEGER NOT NULL DEFAULT 1,
PRIMARY KEY (model_id, key_id)
);

-- 逻辑路由
CREATE TABLE route (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL UNIQUE, -- 逻辑 modelId,如 glm
remark TEXT NOT NULL DEFAULT '',
created_at INTEGER NOT NULL,
updated_at INTEGER NOT NULL
);

-- 路由目标
CREATE TABLE route_target (
id INTEGER PRIMARY KEY AUTOINCREMENT,
route_id INTEGER NOT NULL REFERENCES route(id) ON DELETE CASCADE,
model_id INTEGER NOT NULL REFERENCES model(id) ON DELETE CASCADE,
weight INTEGER NOT NULL DEFAULT 1,
UNIQUE(route_id, model_id)
);

-- 运行配置(key-value,全热生效;见 §9 配置清单)
CREATE TABLE app_config (
key TEXT PRIMARY KEY,
value TEXT NOT NULL -- JSON 编码
);

-- 请求日志(统计事实表,只增不改;无任何请求内容字段)
CREATE TABLE request_log (
id INTEGER PRIMARY KEY AUTOINCREMENT,
request_id TEXT NOT NULL,
route TEXT NOT NULL, -- 逻辑 modelId
model TEXT NOT NULL, -- 真实模型名
provider TEXT NOT NULL,
key_id INTEGER NOT NULL DEFAULT 0, -- 命中的密钥 id(脱敏,不存 key 值)
status TEXT NOT NULL, -- success | error | client_error
error_code TEXT NOT NULL DEFAULT '', -- http 状态码 / timeout / connection_failed / all_backends_unavailable / ...
error_body TEXT NOT NULL DEFAULT '', -- 上游错误体截断(≤2KB),诊断用;不含请求正文
is_stream INTEGER NOT NULL DEFAULT 0,
prompt_tokens INTEGER NOT NULL DEFAULT 0,
completion_tokens INTEGER NOT NULL DEFAULT 0,
tokens_estimated INTEGER NOT NULL DEFAULT 0, -- 1=上游未返回 usage,为估算值
audio_seconds REAL NOT NULL DEFAULT 0, -- STT 输入音频时长(秒)
input_chars INTEGER NOT NULL DEFAULT 0, -- TTS 输入字符数
ttft_ms INTEGER NOT NULL DEFAULT 0, -- 首 token 延迟(非流式=总耗时)
total_ms INTEGER NOT NULL DEFAULT 0,
tps REAL NOT NULL DEFAULT 0, -- 流式输出速度 tok/s = completion/(total-ttft);仅流式成功、非估算且生成窗口≥500ms 时记录,否则 0
cost REAL NOT NULL DEFAULT 0, -- 按 model 价格计算
retries INTEGER NOT NULL DEFAULT 0, -- 本次请求发生的目标/key 转移次数
created_at INTEGER NOT NULL
);
CREATE INDEX idx_rl_time ON request_log(created_at);
CREATE INDEX idx_rl_route ON request_log(route, created_at);
CREATE INDEX idx_rl_model ON request_log(model, created_at);
CREATE INDEX idx_rl_provider ON request_log(provider, created_at);
CREATE INDEX idx_rl_key ON request_log(key_id, created_at);

-- 单次尝试日志(一次客户端请求可含多跳重试,每跳一行;最终落客户端的结果在 request_log)
CREATE TABLE request_attempt (
id INTEGER PRIMARY KEY AUTOINCREMENT,
request_id TEXT NOT NULL,
attempt INTEGER NOT NULL, -- 从 1 起
route TEXT NOT NULL,
model TEXT NOT NULL,
provider TEXT NOT NULL,
key_id INTEGER NOT NULL DEFAULT 0,
status TEXT NOT NULL, -- success | error | client_error
http_status INTEGER NOT NULL DEFAULT 0,
error_code TEXT NOT NULL DEFAULT '',
error_body TEXT NOT NULL DEFAULT '', -- 上游错误体截断(≤2KB)
latency_ms INTEGER NOT NULL DEFAULT 0,
ttft_ms INTEGER NOT NULL DEFAULT 0,
tps REAL NOT NULL DEFAULT 0, -- 该次尝试的流式输出速度(口径同 request_log.tps)
prompt_tokens INTEGER NOT NULL DEFAULT 0,
completion_tokens INTEGER NOT NULL DEFAULT 0,
created_at INTEGER NOT NULL
);
CREATE INDEX idx_ra_request ON request_attempt(request_id, attempt);

-- 每日统计预聚合(写入路径同步 UPSERT;查询优先走此表,当日/特殊维度回退 request_log 现算)
CREATE TABLE request_log_daily (
day INTEGER NOT NULL, -- YYYYMMDD
route TEXT NOT NULL DEFAULT '',
model TEXT NOT NULL DEFAULT '',
provider TEXT NOT NULL DEFAULT '',
status TEXT NOT NULL DEFAULT '',
total INTEGER NOT NULL DEFAULT 0,
success INTEGER NOT NULL DEFAULT 0,
errors INTEGER NOT NULL DEFAULT 0,
prompt_tokens INTEGER NOT NULL DEFAULT 0,
completion_tokens INTEGER NOT NULL DEFAULT 0,
cached_tokens INTEGER NOT NULL DEFAULT 0,
audio_seconds REAL NOT NULL DEFAULT 0,
input_chars INTEGER NOT NULL DEFAULT 0,
cost REAL NOT NULL DEFAULT 0,
retries_sum INTEGER NOT NULL DEFAULT 0,
ttftb0..ttftb9 INTEGER NOT NULL DEFAULT 0, -- TTFT 10 桶直方图(桶边界见 store.TTFTBucketBounds)
totalb0..totalb9 INTEGER NOT NULL DEFAULT 0, -- 总耗时 10 桶直方图(桶边界见 store.TotalBucketBounds)
tpsb0..tpsb9 INTEGER NOT NULL DEFAULT 0, -- 流式生成速度 10 桶直方图(tok/s,边界见 store.TPSBucketBounds;无有效样本的请求不入桶)
updated_at INTEGER NOT NULL DEFAULT 0,
PRIMARY KEY (day, route, model, provider, status)
);

-- 内容日志(可选;成功捕获需全局开关;关闭时仅记转发失败;独立短保留期)
CREATE TABLE content_log (
request_id TEXT PRIMARY KEY,
route TEXT NOT NULL,
client_request_headers TEXT NOT NULL DEFAULT '',
client_request_body TEXT NOT NULL DEFAULT '',
request_url TEXT NOT NULL DEFAULT '', -- 出站请求完整 URL(含 path/query;query 密钥参数值脱敏)
request_headers TEXT NOT NULL DEFAULT '',
request_body TEXT NOT NULL,
response_headers TEXT NOT NULL DEFAULT '',
response_body TEXT NOT NULL, -- 非流式=完整body;流式=拼接的文本增量
created_at INTEGER NOT NULL
);
CREATE INDEX idx_cl_time ON content_log(created_at);

-- 视频生成任务映射(POST /v1/videos 提交成功后登记;轮询/下载按 video_id 回查上游)
CREATE TABLE video_task (
id INTEGER PRIMARY KEY AUTOINCREMENT,
video_id TEXT NOT NULL UNIQUE, -- 上游返回的任务 id
route TEXT NOT NULL, -- 提交时的逻辑路由名(诊断用)
model_id INTEGER NOT NULL,
provider_id INTEGER NOT NULL,
key_id INTEGER NOT NULL DEFAULT 0, -- 提交时命中的密钥
created_at INTEGER NOT NULL
);