feat: add admin console and GHCR Docker deployment

Author: nextroad-dev

.dockerignore

@@ -0,0 +1,21 @@
+.git
+.github
+.runtime-v8
+bin
+data
+internal/api/dashboard/static/web
+webui/node_modules
+webui/test-results
+webui/playwright-report
+webui/coverage
+.env
+.env.*
+!.env.example
+*.db
+*.db-*
+*.sqlite
+*.sqlite-*
+*.exe
+*.test
+*.iso
+*.iso.sha256

.env.example

@@ -0,0 +1,7 @@
+# Published release tag, or latest.
+AUTO_ROUTER_VERSION=latest
+
+# Keep the admin UI local by default. Put a TLS reverse proxy in front before
+# binding to 0.0.0.0 or exposing this port to an untrusted network.
+AUTO_ROUTER_BIND=127.0.0.1
+AUTO_ROUTER_PORT=8080

.github/workflows/ci.yml

@@ -26,6 +26,28 @@ jobs:
       - run: go test -count=1 ./...
       - run: go build ./cmd/auto-router
 
+  frontend:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22.12.0"
+          cache: npm
+          cache-dependency-path: webui/package-lock.json
+      - run: npm ci
+        working-directory: webui
+      - run: npm run typecheck
+        working-directory: webui
+      - run: npm run build
+        working-directory: webui
+      - run: git diff --exit-code -- ../internal/api/dashboard/static/web
+        working-directory: webui
+
   race:
     runs-on: ubuntu-latest
     steps:

.github/workflows/docker-publish.yml

@@ -0,0 +1,65 @@
+name: Docker image
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Check out source
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Generate image metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/nextroad-dev/auto-router
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=ref,event=tag
+            type=ref,event=branch
+            type=ref,event=pr
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+            type=raw,value=edge,enable=${{ github.ref == 'refs/heads/main' }}
+
+      - name: Log in to GHCR
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build and publish multi-architecture image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            VERSION=${{ github.ref_name }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          sbom: true
+          provenance: true

Dockerfile

@@ -0,0 +1,34 @@
+# syntax=docker/dockerfile:1.7
+
+FROM node:22-alpine AS webui-build
+WORKDIR /src/webui
+COPY webui/package.json webui/package-lock.json ./
+RUN npm ci
+WORKDIR /src
+COPY docs/openapi.yaml ./docs/openapi.yaml
+COPY webui ./webui
+RUN cd webui && npm run api:types && npm run typecheck && npm run build
+
+FROM --platform=$BUILDPLATFORM golang:1.25-alpine AS go-build
+ARG TARGETOS
+ARG TARGETARCH
+ARG VERSION=dev
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+COPY --from=webui-build /src/internal/api/dashboard/static/web ./internal/api/dashboard/static/web
+RUN mkdir -p /out/data \
+    && CGO_ENABLED=0 GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH:-amd64} \
+       go build -trimpath -ldflags="-s -w -X main.buildVersion=${VERSION}" \
+       -o /out/auto-router ./cmd/auto-router \
+    && chown -R 65532:65532 /out/data
+
+FROM gcr.io/distroless/static-debian12:nonroot
+WORKDIR /app
+COPY --from=go-build --chown=65532:65532 /out/auto-router /app/auto-router
+COPY --from=go-build --chown=65532:65532 /out/data /app/data
+USER 65532:65532
+EXPOSE 8080
+STOPSIGNAL SIGTERM
+ENTRYPOINT ["/app/auto-router", "-listen", "0.0.0.0:8080"]

README.md

@@ -1,140 +1,96 @@
 # Auto Router
 
-按请求特征、模型能力与策略自动选择模型与 Provider 的独立 LLM Router。
+单用户 LLM 网关：管理上游提供商与模型，把推理请求转发到已选择的模型，并为每个推理密钥提供鉴权。
 
-**当前状态：阶段 1（基础架构）与阶段 2（Model Registry）已完成。** 模型 API（`/v1/chat/completions`、`/v1/responses`）和后台路径当前返回 `404`，不提供会误导客户端的假成功响应；Bifrost 代理、Jev、Policy 与管理后台尚未实现。
+## 启动
 
-架构边界见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)，分阶段交付与验收门槛见 [docs/ROADMAP.md](docs/ROADMAP.md)。
-
-## 快速开始
-
-```bash
-go build -o bin/auto-router ./cmd/auto-router
-./bin/auto-router -config configs/example.json
-```
-
-不带 `-config` 时使用内置默认值。默认监听 `127.0.0.1:8080`，数据库位于 `data/auto-router.db`。
-
-检查服务：
-
-```bash
-curl -i http://127.0.0.1:8080/healthz   # 进程存活
-curl -i http://127.0.0.1:8080/readyz    # 配置与数据库可用
+```sh
+go run ./cmd/auto-router
 ```
 
-## 模型注册表
+默认监听 `127.0.0.1:8080`，数据库为当前工作目录下的 `data/auto-router.db`。新建数据库使用 schema v8。
 
-注册表由三部分组成：
+如需在本机并行运行另一实例，可用 `-listen 127.0.0.1:8081` 指定监听地址。
 
-1. **models.dev 同步**（可选、显式触发）：把白名单里的 `provider/model` 元数据与能力写入 SQLite；
-2. **本地覆盖**（配置文件）：提供 `base_url`、`api_key`、启停、优先级与上游模型标识；
-3. **SQLite**：运行时唯一真相，路由只读不可变快照。
+### Docker Compose（GHCR）
 
-第一次使用：
-
-```bash
-cp configs/registry.example.json config.local.json   # 可用 ${VAR} 引用环境变量
-export OPENAI_API_KEY=sk-...
-./bin/auto-router -config config.local.json -sync-models   # 同步后退出，不启动 HTTP
-./bin/auto-router -config config.local.json                # 正常启动
+```sh
+cp .env.example .env
+docker compose pull
+docker compose up -d
+docker compose logs -f auto-router
 ```
 
-关键语义：
-
-- 同步只写元数据（`display_name`、能力、`upstream_model_id`、上下文/输出容量），**永不改写** `base_url`、`api_key`、`enabled`、`priority` 与本地条目；新建的同步 Provider 默认 `enabled=false` 且没有凭据，因此配置之前不可能被转发。
-- 白名单条目在源数据中找不到会让**整次同步失败并回滚**；“新增模型只改配置”指加一条白名单后重跑 `-sync-models`，零代码改动。
-- 从白名单或配置中移除的条目只置 `enabled=0`，永不删除，避免残留凭据被继续使用。
-- `registry.sync.include` 为空时 `-sync-models` 直接失败，不会把空目录当作成功。
-- 启动与请求路径不做任何网络访问，也没有后台同步；目录为空时只记录 `WARN`，服务照常提供（`/readyz` 只取决于数据库可达）。
-- 阶段 2 **不存价格**：models.dev 的 `cost` 等字段同步时丢弃，表结构中没有价格/成本列，Dashboard 成本与 Policy 成本输入已从 V1 移除（见 [ROADMAP 需求偏差](docs/ROADMAP.md)）。
+打开 <http://127.0.0.1:8080/admin/> 完成首次管理员密码设置。Compose 默认只将端口绑定到本机 loopback；需要从其他机器访问时，应先配置 TLS 反向代理，再调整 `.env` 中的 `AUTO_ROUTER_BIND`。数据保存在 `auto-router-data` 命名卷中；升级时运行 `docker compose pull && docker compose up -d`。不要用 `docker compose down -v`，否则会删除数据库卷。
 
-## 配置
+镜像为 `ghcr.io/nextroad-dev/auto-router`，支持 `linux/amd64` 与 `linux/arm64`。`.env` 中的 `AUTO_ROUTER_VERSION` 可设为 `latest` 或具体版本（例如 `1.2.3`）。首次发布后，仓库维护者需在 GitHub Packages 将该镜像包可见性设为 **Public**，用户才能免登录拉取。
 
-加载顺序为：内置默认值 → JSON 文件 → 环境变量（环境变量优先）。未知 JSON 字段、非法值、空值环境变量都会让进程在监听前失败，而不是静默使用默认值。`configs/example.json` 与内置默认值保持一致；`configs/registry.example.json` 给出注册表段的完整示例（可直接作为 `-config` 使用）。
+GitHub Actions 会在 PR 上构建验证、在 `main` 发布 `edge`，并在推送 `v*` 标签时发布版本标签和 `latest`：
 
-标量字段：
-
-| JSON 字段 | 环境变量 | 默认值 |
-| --- | --- | --- |
-| `http.address` | `AUTO_ROUTER_HTTP_ADDRESS` | `127.0.0.1:8080` |
-| `http.read_header_timeout` | `AUTO_ROUTER_READ_HEADER_TIMEOUT` | `5s` |
-| `http.idle_timeout` | `AUTO_ROUTER_IDLE_TIMEOUT` | `60s` |
-| `http.readiness_timeout` | `AUTO_ROUTER_READINESS_TIMEOUT` | `2s` |
-| `http.shutdown_timeout` | `AUTO_ROUTER_SHUTDOWN_TIMEOUT` | `10s` |
-| `database.path` | `AUTO_ROUTER_DATABASE_PATH` | `data/auto-router.db` |
-| `database.busy_timeout` | `AUTO_ROUTER_DATABASE_BUSY_TIMEOUT` | `5s` |
-| `log.level` | `AUTO_ROUTER_LOG_LEVEL` | `info` |
+```sh
+git tag v1.2.3
+git push origin v1.2.3
+```
 
-注册表字段（**只能来自配置文件**，环境变量不覆盖列表）：
+首次启动时按管理页面提示设置一个 owner 密码。首次设置由 `GET /admin/v1/setup/status` 检查状态，并由 `POST /admin/v1/setup/password` 提交。密码至少 12 字节，可在系统设置中修改。
 
-| JSON 字段 | 默认值 | 说明 |
-| --- | --- | --- |
-| `registry.sync.url` | `https://models.dev/api.json` | 必须是 `https`；仅回环地址允许 `http`（测试用） |
-| `registry.sync.timeout` | `30s` | 单次抓取超时；响应体上限 32 MiB |
-| `registry.sync.include` | `[]` | 白名单，格式 `provider/model`，以第一个 `/` 分隔 |
-| `registry.providers[]` | `[]` | `key`、`display_name`、`base_url`、`api_key`、`enabled`、`priority` |
-| `registry.models[]` | `[]` | `provider`、`model`、`upstream_model_id`、`display_name`、`context_window`、`max_output`、`supports_tools`、`supports_vision`、`supports_reasoning`、`enabled`、`priority` |
+低于 v8 的旧数据库不会自动迁移至当前版本，也不会被自动删除。需要使用全新数据库时，请先停止服务，并自行备份或移走旧数据库文件，再启动服务。
 
-约定：
+忘记密码时，停止服务并通过环境变量提供新密码后运行离线恢复命令：
 
-- `api_key` 支持 `${VAR}` 展开；变量未设置会让进程启动失败并只报变量名，不打印值。`$${` 转义为字面量 `${`。
-- `registry.models[].provider` 必须在本文件的 `registry.providers[]` 中声明；写成未声明的 Provider 直接报错（几乎都是拼写错误，且这样的 pair 永远无法启用）。
-- `enabled` 省略即 `false`（fail-closed）；`priority` 数值越小越优先；`upstream_model_id` 省略时默认等于 `model`。
-- 标识约束：Provider key 为 `^[a-z0-9][a-z0-9._-]{0,63}$`；模型 ID 允许字母数字与 `._:/@~+-`（真实 models.dev 中存在 `meta-llama/Llama-3.3-70B`、`claude-sonnet-4@20250514` 这类 ID），最长 128 字符。
-- 容量约束：`context_window > 0`；`max_output` 省略或落在 `(0, context_window]`；违反约束的配置在启动前报错。
+```sh
+AUTO_ROUTER_RECOVERY_PASSWORD='your-new-password' go run ./cmd/auto-router -recover-admin
+```
 
-## 命令与端点
+PowerShell：
 
-| 命令 / 端点 | 作用 |
-| --- | --- |
-| `-config <file>` | 指定 JSON 配置文件 |
-| `-sync-models` | 从 models.dev 同步白名单后退出（不启动 HTTP） |
-| `GET` / `HEAD` `/healthz` | 存活检查，仅表示进程在运行 |
-| `GET` / `HEAD` `/readyz` | 就绪检查，会执行一次带超时的数据库探测 |
-
-就绪失败只返回 `{"status":"not_ready"}`，不暴露数据库路径、驱动错误或配置内容；响应带 `Cache-Control: no-store`。
-
-## 安全
-
-- 默认只监听回环地址。**当前没有身份认证**，不要直接暴露到公网或不受信任网络。
-- Provider 的 `api_key` **明文存储**在 SQLite 中。缓解措施：POSIX 下数据库与 `-wal`/`-shm` 为 `0600`、日志与错误信息一律掩码（`sk-…abcd`）、支持 `${VAR}` 避免明文入库版本、`.gitignore` 覆盖 `*.db*`。
-- **残余风险（未假装已解决）**：磁盘或备份可读、Windows ACL 未加固、无静态加密、无密钥轮换。静态加密与 Windows ACL 列为显式推迟项。
-- 普通运行日志不记录请求体、prompt 或凭据。
-
-## 目录结构
-
-```text
-cmd/auto-router/      进程入口、装配、生命周期、-sync-models
-internal/api/         HTTP 边界与探针
-internal/config/      启动配置、默认值、环境覆盖、registry 段与校验
-internal/models/      注册表领域类型、校验、排序契约、只读快照
-internal/modelsdev/   models.dev 抓取、白名单映射与真实 fixture
-internal/storage/     SQLite 连接、事务迁移、注册表持久化
-configs/              示例配置
-docs/                 架构边界与阶段计划
-docs/tasks/           各阶段的交付与验收记录
+```powershell
+$env:AUTO_ROUTER_RECOVERY_PASSWORD = "你的新密码"
+go run ./cmd/auto-router -recover-admin
+Remove-Item Env:AUTO_ROUTER_RECOVERY_PASSWORD
 ```
 
-## 开发
+恢复命令要求数据库已存在且为受支持版本，并取得服务监听端口；成功后新密码立即生效。该环境变量只用于本次恢复操作。
 
-```bash
-gofmt -l cmd internal          # 应无输出
-go vet ./...
-go test -count=1 ./...
-go build ./cmd/auto-router
-```
+## 配置与使用
+
+- **提供商**：在「提供商」中添加上游 URL、API 密钥与类型：`openai`、`openai_compatible`、`anthropic` 或 `gemini`。通过模型发现后选择要加入路由的模型。上游 API 密钥只写入，不会在读取响应中返回。
+- **模型组**：在「模型组」中配置简单、中等、复杂三组。每组由已启用的提供商/模型组合组成，顺序就是 fallback 顺序；每组最多 8 项。
+- **调用密钥**：在「调用密钥」创建具名 inference key。原始值只在创建或轮换时显示一次。客户端通过 `Authorization: Bearer <key>` 调用。
+- **仪表盘**：展示请求成功率、时间窗口内各模型与模型组的实际上游尝试次数和 Token，以及最近 60 秒已完成尝试的输出 Token TPS。
 
-`go test -race` 需要 cgo 与 C 工具链；本机没有 C 工具链时该命令无法运行，`-race` 由 Linux CI 覆盖。
+启用 Jev 后，请求内容会按默认的脱敏模式发送至 Jev 服务；选择 features-only 模式时不会发送对话文本。原始 Jev 请求与响应正文默认不捕获。
 
-测试不使用真实凭据或外网：使用临时 SQLite、`httptest` 与本地上游。`internal/modelsdev/testdata/api.json` 是从真实 `models.dev/api.json` 抓取并裁剪的固定 fixture（来源与裁剪方式见同目录 README），测试本身不访问网络。CI（`.github/workflows/ci.yml`）在 Linux 与 Windows 上运行 `go mod verify`、`go vet`、`go test` 与构建，并在 Linux 上额外运行 `-race`。
+## API
 
-已完成的验证：
+推理入口：
 
-- 阶段 1：配置默认值、文件与环境变量优先级、非法/未知/空值拒绝；SQLite 持久化重开、含 `#` 与 `%` 的路径按字面量处理、WAL/foreign_keys/busy_timeout 在连接重建后仍生效、内存库彼此隔离；迁移幂等、失败批次整体回滚、历史校验和/名称不匹配与更新版本库被拒绝；探针语义、405/404 边界、就绪超时与取消传播；优雅排空在途请求、超时强制关闭、真实进程启动/探针/数据库落盘的正向冒烟。
-- 阶段 2：迁移 v1 建表幂等、外键与 CHECK 约束、事务失败整体回滚；同步幂等、白名单移除与本地条目移除只禁用不删除、本地覆盖不被同步改写；models.dev 映射（含共享模型、含 `/` 的模型 ID、Provider 前缀模型键、`max_output` 截断告警、缺上下文跳过、缺失白名单整体失败、`cost` 被丢弃）；`httptest` 假源下的超时/4xx/5xx/畸形 JSON；真实进程 `-sync-models` → 启动 `/readyz` → 关闭 → 重开仍可加载；密钥不进日志与错误信息、POSIX 文件权限收紧。
+| 方法与路径 | 协议 |
+| --- | --- |
+| `GET /v1/models` | 可路由逻辑模型列表 |
+| `POST /v1/chat/completions` | OpenAI Chat Completions |
+| `POST /v1/responses` | OpenAI Responses |
+| `POST /v1/messages` | Anthropic Messages |
+| `POST /v1beta/models/{model}:generateContent` | Gemini generateContent |
+| `POST /v1beta/models/{model}:streamGenerateContent` | Gemini 流式生成 |
 
-平台限制：Windows 无法向当前进程投递 `os.Interrupt`，因此信号到优雅退出的真实链路测试在 Windows 上跳过，由 Linux CI 覆盖；优雅排空逻辑本身在两端都有测试。
+Anthropic 与 Gemini 原生入口按对应协议直通，要求所选上游支持相同协议。OpenAI Chat 文本请求可以转换后转发至 Anthropic 或 Gemini，但仅支持有限的安全子集；不支持的参数或功能会在发送上游前被拒绝。
 
-## 后续阶段
+管理端主要接口：
 
-按 [docs/ROADMAP.md](docs/ROADMAP.md) 依次进行：Bifrost Proxy → Jev Client → Analyzer → Policy Engine → Auto Routing → Logging → Admin API → Dashboard。每个阶段单独实现并测试后再进入下一阶段。
+| 方法与路径 | 用途 |
+| --- | --- |
+| `GET /admin/v1/setup/status` · `POST /admin/v1/setup/password` | 首次设置 owner 密码 |
+| `POST /admin/v1/session` · `GET/DELETE /admin/v1/session` | 密码登录、会话检查与退出 |
+| `PATCH /admin/v1/password` | 修改 owner 密码 |
+| `GET /admin/v1/providers` · `POST /admin/v1/providers` | 查看与新增提供商 |
+| `GET /admin/v1/providers/{key}/discover` | 从上游发现模型 |
+| `POST /admin/v1/providers/{key}/models` | 选择该提供商的模型 |
+| `GET/PUT /admin/v1/groups` | 读取或整体更新简单/中等/复杂模型组 |
+| `GET /admin/v1/dashboard?window=24h` | 仪表盘指标；窗口可选 `1h`、`24h`、`7d`、`30d` |
+| `GET /admin/v1/logs/stats?group_by=attempt_model` | 按实际模型汇总上游尝试；用 `attempt_group` 按模型组汇总 |
+| `GET/POST /admin/v1/keys` · `POST /admin/v1/keys/{name}/rotate` · `DELETE /admin/v1/keys/{name}` | 管理具名推理密钥 |
+
+管理 API 使用登录后签发的 `HttpOnly` 会话 Cookie；推理密钥只用于推理 API。完整请求、响应与错误结构见 [docs/openapi.yaml](docs/openapi.yaml)。
+
+服务状态探针为 `GET /healthz` 和 `GET /readyz`。管理静态页面由服务自身提供。由于服务默认使用 HTTP 并绑定 loopback，若经反向代理对外提供访问，应由代理终止 TLS。