feat(ops): usage dashboard with SQLite (PRD-usage-dashboard-minimal)

- Shared USAGE_DATABASE_PATH volume for search, mcp-server, bot (WAL)
- Record events: search (query/rate_limit/error), mcp HTTP paths, bot commands, tunnel connect, landing pixel
- /ops/usage HTML + JSON summary (Basic Auth OPS_USAGE_USER/PASSWORD)
- /ops/pixel/landing.gif for optional embed; hash actors with USAGE_ACTOR_SALT

Made-with: Cursor

Author: ilyar

.env.example

@@ -26,6 +26,13 @@ SEARCH_RANKER=minisearch
 SEARCH_RESPONSE_CACHE_MAX=64
 # Bust cache after deploy without filesystem mtime change (optional string).
 KNOWLEDGE_CACHE_REVISION=
+
+# Usage dashboard (SQLite shared by search, mcp-server, bot). Set strong USAGE_ACTOR_SALT in production.
+USAGE_DATABASE_PATH=/data/usage/events.sqlite
+USAGE_ACTOR_SALT=replace-with-random-salt
+# HTTP Basic for https://<host>/ops/usage/ (panel is proxied to mcp-server:3000).
+OPS_USAGE_USER=
+OPS_USAGE_PASSWORD=
 # Public URL clients use (scheme + host, no trailing slash). With Caddy on 80/443 use http://your-host or https://your-host
 PUBLIC_ORIGIN=https://spawn-dock.w3voice.net
 # docker-compose.prod.yml mounts ./data/state → /app/.spawndock

README.md

@@ -263,7 +263,7 @@ npm-пакет `mcp-tma-client` в `packages/mcp-tma-client/`. Работает
 ## Спецификации (PRD)
 
 - `docs/PRD-public-knowledge-search-service.md` — публичный `/knowledge` API
-- `docs/PRD-usage-dashboard-minimal.md` — минимальная панель использования (search, mcp, bot, tunnel, landing)
+- `docs/PRD-usage-dashboard-minimal.md` — панель использования (SQLite); UI: **`/ops/usage`** (Basic Auth `OPS_USAGE_*`), пиксель лендинга: **`/ops/pixel/landing.gif`**
 
 ## Структура проекта
 

data/usage/.gitkeep

@@ -20,8 +20,11 @@ services:
       QWEN_HTTP_PORT: "8790"
       QWEN_OAUTH: "true"
       KNOWLEDGE_ROOT: /corpus
+      USAGE_DATABASE_PATH: /data/usage/events.sqlite
+      USAGE_ACTOR_SALT: ${USAGE_ACTOR_SALT:-change-me-usage-salt}
     volumes:
       - ./knowledge:/corpus:ro
+      - ./data/usage:/data/usage
     restart: unless-stopped
     healthcheck:
       test:
@@ -46,9 +49,14 @@ services:
       QWEN_API_URL: http://search:8790
       QWEN_CONTAINER_IMAGE: spawndock/search:prod
       QWEN_KNOWLEDGE_HOST_PATH: ${QWEN_KNOWLEDGE_HOST_PATH:-}
+      USAGE_DATABASE_PATH: /data/usage/events.sqlite
+      USAGE_ACTOR_SALT: ${USAGE_ACTOR_SALT:-change-me-usage-salt}
+      OPS_USAGE_USER: ${OPS_USAGE_USER:-}
+      OPS_USAGE_PASSWORD: ${OPS_USAGE_PASSWORD:-}
     volumes:
       - ./data/state:/app/.spawndock
       - ./knowledge:/app/knowledge:ro
+      - ./data/usage:/data/usage
     depends_on:
       search:
         condition: service_healthy
@@ -69,6 +77,10 @@ services:
       - .env
     environment:
       CONTROL_PLANE_URL: http://mcp-server:3000
+      USAGE_DATABASE_PATH: /data/usage/events.sqlite
+      USAGE_ACTOR_SALT: ${USAGE_ACTOR_SALT:-change-me-usage-salt}
+    volumes:
+      - ./data/usage:/data/usage
     depends_on:
       mcp-server:
         condition: service_healthy

docker-compose.prod.yml

@@ -44,8 +44,13 @@ services:
       TELEGRAM_BOT_USERNAME: ${TELEGRAM_BOT_USERNAME:-}
       TELEGRAM_MINI_APP_SHORT_NAME: ${TELEGRAM_MINI_APP_SHORT_NAME:-}
       HF_TOKEN: ${HF_TOKEN:-}
+      USAGE_DATABASE_PATH: /data/usage/events.sqlite
+      USAGE_ACTOR_SALT: ${USAGE_ACTOR_SALT:-dev-usage-salt}
+      OPS_USAGE_USER: ${OPS_USAGE_USER:-}
+      OPS_USAGE_PASSWORD: ${OPS_USAGE_PASSWORD:-}
     volumes:
       - ./data/state:/app/.spawndock
+      - ./data/usage:/data/usage
     depends_on:
       qwen:
         condition: service_healthy
@@ -87,6 +92,10 @@ services:
       TELEGRAM_BOT_USERNAME: ${TELEGRAM_BOT_USERNAME:-}
       TELEGRAM_MINI_APP_SHORT_NAME: ${TELEGRAM_MINI_APP_SHORT_NAME:-}
       HF_TOKEN: ${HF_TOKEN:-}
+      USAGE_DATABASE_PATH: /data/usage/events.sqlite
+      USAGE_ACTOR_SALT: ${USAGE_ACTOR_SALT:-dev-usage-salt}
+    volumes:
+      - ./data/usage:/data/usage
     depends_on:
       mcp-server:
         condition: service_healthy

docker-compose.yml

@@ -18,7 +18,7 @@ WORKDIR /opt/search
 COPY docker/search/package.json docker/search/package-lock.json ./
 RUN npm ci --omit=dev
 
-COPY docker/search/http-server.mjs docker/search/knowledge-rank.mjs ./
+COPY docker/search/http-server.mjs docker/search/knowledge-rank.mjs docker/search/usage-log.mjs ./
 COPY openapi/knowledge-v1.yaml ./openapi.yaml
 COPY knowledge ./knowledge
 

docker/search/Dockerfile

@@ -9,6 +9,7 @@ import { readFileSync, existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { corpusMaxMtime, rankKnowledgeForQuery } from "./knowledge-rank.mjs";
+import { hashActorValue, recordSearchUsage } from "./usage-log.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PORT = parseInt(process.env.SEARCH_HTTP_PORT || process.env.QWEN_HTTP_PORT || "8790", 10);
@@ -158,6 +159,21 @@ function resolveTier(req) {
   return "free";
 }
 
+function searchUsageActor(req) {
+  const auth = req.headers.authorization;
+  if (typeof auth === "string" && auth.startsWith("Bearer ")) {
+    const token = auth.slice(7).trim();
+    if (token) {
+      return { actorType: "api_token", actorKey: hashActorValue(token) };
+    }
+  }
+  if (isPublicFacingRequest(req)) {
+    return { actorType: "anonymous_ip", actorKey: hashActorValue(clientFacingIp(req)) };
+  }
+  const ra = req.socket.remoteAddress || "internal";
+  return { actorType: "internal", actorKey: hashActorValue(`dock:${ra}`) };
+}
+
 function checkRateLimit(tier, keyId) {
   const t = TIERS[tier];
   if (!t) return { ok: true };
@@ -405,11 +421,21 @@ async function handleRequest(req, res) {
       return;
     }
 
+    const rateTier = tier === "basic" ? "basic" : "free";
+    const usageActor = searchUsageActor(req);
+
     if (isPublicFacingRequest(req)) {
-      const rateTier = tier === "basic" ? "basic" : "free";
       const keyId = `${rateTier}:${tier === "basic" ? "token" : clientFacingIp(req)}`;
       const rl = checkRateLimit(rateTier, keyId);
       if (!rl.ok) {
+        recordSearchUsage({
+          eventType: "search_rate_limit",
+          actorType: usageActor.actorType,
+          actorKey: usageActor.actorKey,
+          tier: rateTier,
+          status: 429,
+          meta: { reason: rl.reason },
+        });
         sendError(res, 429, "rate_limit", `Rate limit exceeded (${rl.reason})`, {
           tier: rateTier,
           limit: rl.limit,
@@ -437,9 +463,25 @@ async function handleRequest(req, res) {
 
     try {
       const result = await runSearchQuery(query);
+      recordSearchUsage({
+        eventType: "search_query",
+        actorType: usageActor.actorType,
+        actorKey: usageActor.actorKey,
+        tier: rateTier,
+        status: 200,
+        meta: { cache_hit: result.meta?.cache_hit === true },
+      });
       sendJson(res, 200, result);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
+      recordSearchUsage({
+        eventType: "search_error",
+        actorType: usageActor.actorType,
+        actorKey: usageActor.actorKey,
+        tier: rateTier,
+        status: 502,
+        meta: { message: message.slice(0, 500) },
+      });
       sendError(res, 502, "search_failed", message);
     }
     return;