管理面板（Admin Panel）¶

网关内置了基于 Web 的管理面板，用于管理配置、监控流量和查看请求日志——无需编辑配置文件或重启服务器。

访问地址：http://localhost:8765/admin/

配置管理¶

Configuration 标签页可通过可视化界面管理提供商、模型和服务器设置。

服务器设置¶

设置全局代理 URL，适用于所有提供商（除非在提供商级别单独覆盖）。

提供商管理¶

每个提供商卡片显示名称、API 标准类型、Base URL、脱敏后的 API Key、可选代理，以及提供商 Logo（如果在提供商 shim 中声明）。当提供商配置的 shim 包含 to_transforms 或 from_transforms 时，活跃的转换规则会显示在卡片上。支持以下操作：

• 添加新提供商（"+ Add Provider" 按钮）
• 编辑现有提供商（名称、类型/shim、Base URL、API Key、代理）
• 重命名提供商——所有关联模型引用自动更新
• 克隆提供商——打开添加提供商弹窗，预填源提供商的设置作为模板
• 删除提供商

编辑时，API Key 显示为密码字段，支持可见性切换和复制按钮。卡片上显示的脱敏 Key 不会被写回配置文件。

模型路由¶

提供商区域下方是模型路由表，列出所有已配置的模型及其目标提供商和能力标记。支持以下操作：

• 搜索模型名称或通过下拉框过滤提供商
• 排序：点击列标题按模型名或提供商排序
• 添加新模型并指定提供商
• 从提供商获取 —— 查询上游 /v1/models 端点，浏览可用模型并通过复选框批量添加，支持可选前缀。错误响应会显示可操作的诊断信息：
  • 连接被拒绝 — 上游服务未运行或防火墙阻止了连接
  • 超时 — 从网关容器无法访问上游主机
  • DNS 解析失败 — 无法解析 Base URL 中的主机名
• 编辑模型能力（内联编辑）
• 删除模型路由条目
• 测试：直接在管理面板中测试模型

模型能力¶

每个模型可声明能力，决定可用的测试类型并在 /v1/models 响应中返回：

模型测试¶

点击模型行中的 Test 按钮可运行快速测试。可用的测试类型取决于模型声明的能力：

Embedding 模型显示单一的 Test 按钮（无下拉菜单），因为只有一种适用的测试类型。

测试等待期间会显示 Cancel 按钮，可随时中止请求。状态旁会显示实时计时器（例如"Sending request... 5s"），便于观察长时间运行的请求。测试负载使用 max_tokens=256 以加快完成速度。

测试结果在主输出区域显示提取的模型回复，可折叠区域包含原始请求负载、原始响应体，以及（视觉测试时）测试图片预览。

删除确认¶

破坏性操作根据严重程度使用两种确认方式：

• 删除提供商 — 弹出输入确认弹窗，提示级联影响（所有关联模型将被移除）。
• 删除模型、删除 API Key 和 Clear Log — 使用内联两步确认：按钮变为"Sure? Yes"，3 秒内未确认则自动恢复。

仪表盘¶

Dashboard 标签页提供网关流量的实时指标。

摘要卡片¶

• Total Requests — 自启动以来的累计请求数（或自上次持久化加载）
• Error Rate — 非 2xx 响应的百分比
• Active Streams — 当前活跃的流式连接数
• Uptime — 网关启动以来的运行时间

时间序列图表¶

两个滚动 60 秒窗口的图表：

• Throughput (req/s) — 每秒请求率
• Latency (ms) — 每秒平均响应时间

尚无流量时，图表会显示"No data yet"提示文字，而不是渲染一条平坦的直线。

按提供商分类¶

按目标提供商分组的请求计数表，便于了解流量分布。

网络诊断¶

仪表盘包含网络诊断部分，用于检测网关进程的网络连通性。显示三个检测项：

请求日志¶

Request Log 标签页显示通过网关的每个请求。

每条记录包含：

过滤¶

使用顶部的下拉筛选器可按以下条件过滤：

• Model — 按特定模型筛选
• Provider — 按目标提供商筛选
• Status — 仅显示成功（2xx/3xx）或错误（4xx/5xx）响应

点击 Clear Log 清除当前视图中的所有条目。

主题¶

管理面板提供 8 种主题，可通过右上角的下拉菜单切换：

主题选择存储在 localStorage 中，浏览器关闭后依然保留。

认证¶

管理面板不需要网关 API Key。

可在配置文件中设置 server.admin_password 启用内置密码保护：

{ "server": { "admin_password": "${ADMIN_PASSWORD}" } }

详见配置 — 管理面板安全。

启用密码保护后：

• 登录令牌存储在 localStorage 中，会话在浏览器重启后依然保留，而非仅限于当前标签页。
• 右上角显示登出按钮，可手动结束会话。
• 会话在 30 分钟无操作后自动过期。鼠标移动、键盘输入、滚动和点击均视为活跃操作。
• 登录表单使用标准 HTML 表单语义，浏览器密码管理器可保存和自动填充凭据。

也可以通过反向代理保护管理面板：

• Caddy：使用 basicauth 指令
• Nginx：使用 auth_basic 指令
• Traefik：使用 BasicAuth 中间件

网关 API Key（通过 server.api_key 配置）仅保护 AI 请求端点（/v1/*）。详见配置 — 网关 API Key。

国际化¶

管理面板支持 English 和中文。通过右上角的语言下拉菜单切换。选择同样保存在 localStorage 中。

数据持久化¶

指标和请求日志数据持久化到配置文件旁的单个 SQLite 数据库中：

~/.config/llm-rosetta-gateway/
    config.jsonc
    data/
        gateway.db    # SQLite 数据库 — 请求日志 + 指标（WAL 模式）

工作原理¶

• 请求日志条目在每次请求时直接写入 gateway.db
• 指标计数器在每次更新后保存到 gateway.db
• 启动时加载持久化数据——指标和日志在重启后恢复
• WAL 模式确保写入崩溃安全，同时不阻塞读取

数据保留¶

最多保留 5,000 条请求日志。超出上限时，最旧的条目会自动删除。

历史数据迁移¶

首次启动时，如果数据目录中存在旧版的 request_log.jsonl 或 metrics.json 文件，会自动导入 gateway.db 并重命名为 *.migrated。

从 Docker 访问宿主机服务¶

当网关在 Docker 容器中运行，且需要访问宿主机上的服务（例如运行在 localhost:44501 的另一个 API 代理）时，不能使用 127.0.0.1 作为 Base URL——该地址在容器内指向的是容器自身。

应使用仪表盘网络诊断中显示的 Host IP。这是 Docker 桥接网络的网关地址（通常为 172.x.0.1），由容器的默认路由自动检测。管理面板中的提供商代理 URL 占位符会动态显示检测到的 Host IP，可直接复制使用。

防火墙配置（ufw）¶

如果宿主机运行了 ufw，即使容器和宿主机共享桥接网络，Docker 容器的流量默认也会被阻止。需要显式允许 Docker 子网。

推荐的做法是用一条规则放行整个 Docker 私有地址段（172.16.0.0/12）。这涵盖了所有 Docker 网络——默认 bridge、compose 创建的网络，以及未来新建的任何网络——无需逐个网络添加规则：

sudo ufw allow from 172.16.0.0/12 comment 'Docker all subnets'

这是安全的，因为 172.16.0.0/12 是 RFC 1918 私有地址段，不会在公网上路由。只有运行在同一宿主机上的容器才能使用这些地址。

如果防火墙阻止了流量，"从提供商获取"和模型测试会显示超时错误。检查网络诊断中的 Host IP 并添加相应的 ufw 规则即可解决。

缓存 / 反向代理¶

管理面板在所有 /admin/api/* 响应上设置 Cache-Control: no-cache, no-store, must-revalidate。这可以防止激进的反向代理缓存（例如 Caddy 搭配 Souin 插件）返回过期的仪表盘指标或请求日志数据。

模型测试轮询使用 POST 请求而非 GET，以避免被中间代理缓存。

移动端 / 响应式¶

管理面板支持响应式布局——页头、标签栏和内容区域会自动适配窄屏幕。数据表格在移动设备上可水平滚动，不会裁切列内容。