KATANA-Framework/Vigil

# Vigil — 基于 KATANA 的错误监控与事件响应 一个专为小团队打造的 **Sentry × PagerDuty**，作为真实的线上服务构建，以检验 **每一项** KATANA 能力（阶段 1–8）。应用程序将错误/事件上报给 Vigil；它将其分组 为 **issue**，驱动 **告警 / on-call**，并为工程师提供一个 **控制台** 来分类和解决 事件。 Vigil 是一个 git submodule，**仅**通过其公开的 CMake 接口 （`find_package(katana)` 或 `add_subdirectory`）使用 KATANA —— 没有 KATANA 内部依赖，也没有手动设置的后端宏。  ## 内容概览 - **两份 OpenAPI 契约，一个二进制文件** —— `ingest`（机器/SDK，API-key，CBOR/MessagePack）和 `console`（人类用户，JWT + RBAC），通过 `composite_router` 命名空间化并一同提供服务。所有的 DTO、 验证器、JSON serde、SQL repository、**Row↔DTO 桥接**（18 个转换器），以及 前端 **TypeScript client** 均由 KATANA 生成 —— 手动修补次数为 **零**。 - **PostgreSQL 数据层** —— 13 张 `vigil_*` 表；每一个查询都是一个生成的 repository 方法，使用 **命名参数**（`@name`）、**批量 `UNNEST`** 插入、**窗口函数 / 百分位数** （`row_number`、`percentile_cont`）以及 **事务**（状态变更 + 审计行原子操作）。 - **完整的 runtime** —— TLS/HTTPS（ALPN，SIGHUP 证书重载），JWT（HS256 + RS256/JWKS）和基于数据库的 API-key 认证，基于 Redis 的 `x-katana` **缓存 / 限流 / 幂等性**（带 L1 层），响应 压缩，边缘负载剔除，CORS，结合了 `*_FILE` 密钥 + SIGHUP 重载的分层配置， 结构化/访问/采样日志，W3C tracing（+ exporter 对接点），Prometheus `/metrics`， 健康/就绪检查，连接超时，最大连接数，优雅关闭。 - **真实的运维控制台** —— Next.js，深色主题为主（支持浅色），严重性语义化设计， 生成的 TS client 作为 *整个* API 层，无依赖的 SVG 图表，以及一个 **/status** 页面 内部试用 Vigil 自身的指标。 请参阅 [`docs/CAPABILITIES.md`](docs/CAPABILITIES.md) 获取完整的 §3 清单 → 其中展示了 37 项 能力各自被应用的位置（可通过 grep 验证）。 ## 快速开始 前置条件：C++23 工具链，CMake ≥ 3.20 + Ninja，`libpq`，OpenSSL，Node 20+，以及 Docker（用于 开发依赖）。Vigil 位于 KATANA 仓库内的 `submodules/Vigil`。 ### 一条命令 ``` ./tools/vigil dev ``` 拉起依赖（通过 `docker-compose.yml` 启动 Postgres 16 + Redis 7 + Prometheus，自动应用 schema + 种子数据），生成契约，构建后端，生成自签名的开发证书，通过 **HTTPS** 在 `:8443` 端口运行 后端，并在 `:3000` 端口启动 Next.js 控制台 —— 同时跟踪两者的输出，在 Ctrl-C 时关闭 一切。（如果你的用户不在 `docker` 组中，请设置 `DOCKER="sudo docker"`。） - 控制台 → http://localhost:3000 · API → https://localhost:8443 · Prometheus → http://localhost:9090 - 登录账号 `owner@acme.test` / `admin@acme.test` / `responder@acme.test` / `viewer@acme.test`， 密码 `demo1234`。 - Ingest 密钥（种子）：`vgl_live_alpha_5f3a9c1e`（项目 1），`vgl_live_beta_7b2d8e40`（项目 2）。 ### 手动运行 ``` # 依赖 docker compose up -d # backend (通过 add_subdirectory 使用 KATANA) cmake -S . -B build -G Ninja -DVIGIL_TESTS=ON && cmake --build build VIGIL_PG_DSN=postgresql://vigil:vigil@127.0.0.1:5433/vigil VIGIL_REDIS_PORT=6380 ./build/backend/Vigil # 控制台 cd web && npm install && NEXT_PUBLIC_VIGIL_URL=https://localhost:8443 npm run dev ``` ## 试用 API ``` KEY=vgl_live_alpha_5f3a9c1e # ingest 一批 (幂等、rate-limited、bulk-inserted、grouped 成一个 issue) curl -sk -X POST https://localhost:8443/ingest/events -H 'Content-Type: application/json' \ -H "X-Vigil-Key: $KEY" -H 'Idempotency-Key: demo-1' \ -d '{"events":[{"fingerprint":"fp-demo","level":"error","message":"boom","environment":"production"}]}' # 登录并查看 dashboard TOKEN=$(curl -sk -X POST https://localhost:8443/auth/login -H 'Content-Type: application/json' \ -d '{"email":"owner@acme.test","password":"demo1234"}' | python3 -c 'import sys,json;print(json.load(sys.stdin)["token"])') curl -sk https://localhost:8443/projects/1/overview -H "Authorization: Bearer $TOKEN" ``` Ingest 还支持 `application/cbor` 和 `application/x-msgpack` 格式的请求体（基于内容协商）。 ## 测试 ``` cmake -S . -B build -DVIGIL_TESTS=ON && cmake --build build cd build && VIGIL_PGPW=vigil ctest --output-on-failure # unit + integration bash tools/strict-codegen.sh # --strict codegen gate (CI) cd web && npm run build # type-checks the generated client + pages # e2e (需要运行中的 stack): npx playwright test ``` - **单元测试**（`test/unit_test.cpp`）：内置的 CBOR/MessagePack 解码器和加密辅助工具。 - **集成测试**（`test/integration.sh`）：HTTPS/ALPN，ingest 401/202/429/幂等性，console RBAC 401/403/200，缓存 HIT，gzip，`/readyz`，事务性解决并离开 feed。 - **端到端测试 (E2E)**（`web/e2e/console.spec.ts`）：登录 → 解决 issue → 它离开 feed；主题切换； 浅色/深色截图；内部试用状态。已在浏览器中实际验证。 ## 目录结构 ``` backend/ ingest.yaml console.yaml · sql/{ingest,console}/*.sql · db/{schema,seed}.sql src/{main.cpp, handlers/, auth/, util.hpp} generated/ (git-ignored; produced by katana_add_openapi/sql/typescript) web/ Next.js console · lib/{ingest,console}/generated_client.ts · lib/api.ts facade tools/ vigil (dev orchestrator) · dev-cert.sh · strict-codegen.sh docker-compose.yml · prometheus.yml · .github/workflows/ci.yml ``` ## 配置 分层加载：**默认值 < `vigil.conf` < `VIGIL_*` 环境变量 < `--flags` < `*_FILE` 密钥**，在 SIGHUP 时重新加载。配置键：`pg_dsn`、`redis_host`/`redis_port`、`jwt_secret`（或 `jwt_secret_file`）、`jwks_path`、 `tls_cert_path`/`tls_key_path`/`tls_enabled`、`ingest_stmt_timeout_ms`、`console_stmt_timeout_ms`、 `max_connections`、`load_shed_max_in_flight`、`access_log_sample`、`cors_origin`。（`*_file` 后缀专用于密钥间接寻址，例如 `jwt_secret` ← `jwt_secret_file`。） ## KATANA DX 构建 Vigil 同时作为 KATANA 最大的 DX 试点，它在框架上游修复了所暴露出的摩擦点：针对 `@named` SQL 参数的命名参数结构体，具备注释感知能力的 `@name` 重写器， 可空的 `@name?` 参数，`server.use()` 全局 middleware，位于 policy 链前方的基于数据库的 `api_key` 解析器，`STRICT` 代码生成，`reload_on_sighup`/`pool_readiness`/`transaction()` 辅助工具，在生成的 dispatch 中进行的 CBOR/MessagePack 请求转码，`text[]` 的 Row↔DTO 桥接， 以及具备认证感知的生成版 `createClient()`。Vigil 现在直接使用这些功能（本仓库不包含任何 框架变通方法）。生成的输出被手动修补了 **零** 次。 ## 阶段 9 对接点（按提示存根） Multipart source-map 上传、SSE/WebSocket 实时 issue feed 以及静态 source-map 提供服务正等待 KATANA 阶段 9；远程 `jwks_url` 获取和 OTLP wire exporter 是位于有效对接点之后的 `TODO` （目前基于文件加载的 JWKS 和日志 span exporter 可以正常工作）。它们均非检验阶段 1–8 所必需。

标签：Bash脚本, C++, PostgreSQL, 告警系统, 安全测试工具, 搜索引擎查询, 数据擦除, 测试用例, 自定义请求头, 请求拦截, 运维平台, 错误监控