Ivan's Blog
项目实践

Codex Vibe Monitor

Codex Vibe Monitor 是面向自部署的 OpenAI 兼容代理观测工作台：它接入 /v1/* HTTP / WebSocket 流量，将调用留证、实时 SSE、历史统计、请求排障、上游账号池、forward proxy、价格目录和 SQLite 持久化收在同一套运营界面中。

  • Rust web service
  • Embedded admin UI
  • React app
  • Progressive web app
  • SQLite
  • Dockerized dev
  • Monitoring dashboard
  • Storybook accessibility
  • Storybook component QA
  • UI version display
  • PR label release
  • Release failure notification
  • Quality gates
  • GitHub Actions scheduling
  • Worktree bootstrap

目录

技术栈

运行与交付

CI 工作流
  • ci-main.yml
  • ci-pr.yml
  • docs-pages.yml
  • label-gate.yml
  • notify-release-failure.yml
  • release-snapshot-pr.yml
  • release.yml
  • review-policy.yml
能力标记
  • bun_lock
  • cargo_toml
  • dockerfile
  • github_actions
  • package_json
JSON

Purpose

Codex Vibe Monitor 是面向自部署的 OpenAI 兼容代理观测工作台：它接入 /v1/* HTTP / WebSocket 流量，将调用留证、实时 SSE、历史统计、请求排障、上游账号池、forward proxy、价格目录和 SQLite 持久化收在同一套运营界面中。CRS runtime polling 已退役；历史 xy 记录和 quota snapshot 仅保留只读查询，服务不再从 XYAI 上游抓取新数据，这是重要的兼容边界。

Taxonomy

  • Tags: Rust web service, Embedded admin UI, React app, Progressive web app, SQLite, Dockerized dev, Monitoring dashboard, Storybook accessibility, Storybook component QA, UI version display, PR label release, Release failure notification, Quality gates, GitHub Actions scheduling, Worktree bootstrap
  • Why / evidence: 这些 tags 来自 checked-out repo 和 catalog record。主要证据包括 README.md、Cargo.toml、Dockerfile、web/package.json、web/index.html、web/public/site.webmanifest、web/.storybook/main.ts、ops/observability/README.md、ops/observability/compose.yml、ops/observability/prometheus.yml、ops/observability/grafana/、src/observability/、scripts/cvm-observe、scripts/cvm-hotpath-cpu、.github/quality-gates.json、.github/workflows/ci-pr.yml、.github/workflows/ci-main.yml、.github/workflows/notify-release-failure.yml，以及 worktree 相关的 docs/specs/v7se4-worktree-bootstrap/SPEC.md、lefthook.yml、scripts/install-lefthook-hooks.sh、scripts/run-lefthook-hook.sh、scripts/worktree-bootstrap.sh、scripts/worktree-setup.sh、scripts/sync-worktree-resources.sh 与 scripts/test-worktree-bootstrap.sh。Topic token 的大小写以对应技术/工作流的官方写法为准；slug 只作为稳定 ID，不直接充当项目标题。

Repository map

  • Cargo.toml 是 Axum/SQLx/Tokio 服务 manifest，包含 SQLite、SSE、proxy、OpenAI-compatible forwarding 和 CLI 依赖。
  • web/ 是 React/Vite 管理台；web/.storybook/main.ts 启用 @storybook/addon-a11y 与 docs，属于 Storybook accessibility。
  • web/public/site.webmanifest 与 web/index.html 定义了 standalone install metadata、theme color 和 icon/manifest linkage。
  • Dockerfile 先构建 web assets，再构建 Rust binary，并固定 Bun/Rust/Debian 版本以控制 glibc 漂移。
  • ops/observability/ 保存 Prometheus、Grafana、可选 Tempo、Compose network/volume、dashboard provisioning、recording rules 与 alert provisioning；src/observability/ 保存应用侧 bounded metrics、HTTP/body/browser 采集、资源采样、报告适配和可选 tracing 边界。
  • .github/quality-gates.json、ci-pr.yml、ci-main.yml、release.yml 和 review-policy.yml 定义 PR/main/release gate。

Runtime and delivery

Web build 会写入版本信息：web/package.json 的 build 链接 scripts/write-version.mjs，Dockerfile 通过 APP_EFFECTIVE_VERSION 注入 VITE_APP_VERSION。后端运行时是单 Rust service，SQLite 为低运维持久层；Docker artifact 是主要部署形态。与此同时，web/index.html 与 web/public/site.webmanifest 已经把这个控制台声明成 display: standalone 的 install surface，说明 install metadata 不是附属美术资源，而是产品 runtime identity 的一部分。

性能观测是独立于业务持久化的运行时交付面：应用从真实事件更新有界 metrics，Prometheus 负责历史，Grafana 通过仓库 provisioning 管理六个 dashboard、查询和告警；hotpath-rs 负责函数、规范化 SQL、路由和选定锁的归因。请求 tracing 当前是默认关闭的可选能力，Tempo 只保存受限的请求链路；受限 samply CPU attach 是按需诊断工具，不是常驻 profiler。相关 Compose、网络隔离、凭据边界和验证顺序见 ops/observability/README.md 与 docs/solutions/performance/prometheus-grafana-compose-integration.md。

这个仓库也是 Lefthook 型 Worktree bootstrap 的 canonical 实现。维护者先确保 repo 外的全局 lefthook 可执行，再以 bun run hooks:install 生成 shared Git hooks；lefthook.yml 的 post-checkout command 调用当前 checkout 的 scripts/run-lefthook-hook.sh。linked worktree 会自动以 copy-missing-only 语义同步本地资源，并通过 scripts/worktree-setup.sh 依次恢复 repo root、web/、docs-site/ 的 Bun 依赖和 Rust crate 缓存；主 worktree 普通 checkout 跳过依赖恢复。自动路径汇总告警但不阻断 checkout，手动 bun run worktree:bootstrap 则保留聚合失败码（README.md、docs/specs/v7se4-worktree-bootstrap/SPEC.md、lefthook.yml、scripts/worktree-bootstrap.sh、scripts/worktree-setup.sh）。

Architecture notes

系统边界是代理层、统计采集层、SQLite persistence 和 dashboard SSE。代理不能只当 reverse proxy；它还承担审计记录和 quota snapshot 暴露。历史 XYAI 数据是 compatibility/read-only surface，后续改动不能重新引入上游抓取假设。

观测链路另有清晰的职责边界：应用 exporter 和 hotpath exporter 向 Prometheus 提供聚合指标，Grafana 只查询已 provision 的 Prometheus/Tempo 数据，业务数据库继续保存调用、费用、token、终态、任务与审计事实。metrics、trace 和 CPU profile 不能互相冒充；观测组件、exporter、sampler 或报告 API 的故障只能使观测降级，不能改变代理请求、ACK、任务执行或业务写入的成功语义。固定 label 白名单、凭据分离、私网抓取、报告限额和 tracing 的异步有界队列是当前实现的安全边界，而不是所有项目的固定数值。

证据锚点：README.md。

Workflow and quality gates

这个 repo 是 PR label release 的强参考：PR gate、main gate、release snapshot、review policy 拆得很细。.github/quality-gates.json 记录 required checks，release.yml 与 label gate 决定版本发布，.github/workflows/notify-release-failure.yml 把失败通知作为独立的可复用 release surface。Storybook a11y 和 web tests 属于 UI gate，Rust tests 属于服务 gate。

观测集成的质量证明覆盖配置、运行时和查询语义：六个 dashboard JSON、Prometheus recording rules、Grafana datasources/alerts、Compose 服务边界、metrics freshness/样本量检查、hotpath 报告白名单，以及监控停机不影响业务的验收。scripts/cvm-observe 提供固定查询和 HTTPS 机器访问面，scripts/test-observability-tools.py、scripts/test-observability-acceptance.py 与 scripts/test-observability-diagnostics.py 证明工具输入、隔离验收和诊断边界；这些证据不等于生产部署或性能预算已在所有环境通过。

.github/workflows/ci-pr.yml 的 edited metadata 重验与普通 candidate 共用可取消的 per-PR concurrency group；是否隔离重验运行属于 GitHub Actions scheduling，而不是修改 gate 名称或 release contract。

Worktree 侧的质量证明不是 shell 静态检查，而是 scripts/test-worktree-bootstrap.sh 建立真实 linked worktree 并通过真实 Lefthook hook 触发 bootstrap；fake Bun/Cargo 锁定依赖执行顺序和 locked 参数，Vitest sentinel 证明恢复后的 web tool 可执行。测试还覆盖缺少全局 Lefthook、repo-local binary shadow、unmanaged hook 保留、自定义 core.hooksPath、历史 revision no-op、现有 .env.local 不覆盖，以及自动/手动失败语义（scripts/test-worktree-bootstrap.sh、scripts/install-lefthook-hooks.sh）。

Reusable decisions

  • 在 Dockerfile 中固定 builder/runtime 发行版，避免 glibc 版本漂移导致容器运行失败。
  • 把版本显示作为 UI contract；release 和 web build 都要传递 effective version。
  • 将代理审计数据放入 SQLite，适合个人/小团队单节点服务。
  • 把 manifest、theme-color、apple-touch-icon 和 app icons 都内置在仓库里，有助于保持 install surface 与本地图标资产一致，不再依赖运行时第三方拉取。
  • 已采用 Lefthook 的仓库可把 standard shared hook generation、当前 revision runner、copy-missing local resources、best-effort dependency recovery 和真实 linked-worktree smoke 收敛成一条 canonical bootstrap chain；不要再并列维护 custom wrapper 或 dual entrypoint（lefthook.yml、scripts/install-lefthook-hooks.sh、scripts/run-lefthook-hook.sh）。
  • 自动 post-checkout 与手动 worktree:bootstrap 应复用同一 setup implementation，但保留不同失败语义：自动路径告警后成功返回，手动路径暴露聚合非零状态（scripts/worktree-bootstrap.sh、scripts/worktree-setup.sh）。
  • 用有界、低基数的 runtime metrics 记录真实 source event，把 Prometheus/Grafana 当作历史与查询面，把业务 SQLite 当作业务事实面；不要用业务表回填 metrics，也不要让 dashboard 成为业务成功条件（docs/design/performance-observability.md、docs/specs/performance-telemetry/METRICS.md）。
  • 将应用 classic Histogram 与 hotpath native Histogram 分开抓取、查询和容量审查；dashboard provisioning、recording rules 和 alert rules 进入仓库，Grafana UI 不作为配置真相（ops/observability/prometheus.yml、ops/observability/grafana/provisioning/）。
  • 将 metrics scrape、Grafana Viewer、hotpath report 和 tracing 摄入/查询凭据分开，并把 Prometheus/Tempo 保持在受限网络；项目具体的端口、留存、采样率、容量与性能预算只由当前项目合同决定，不能复制成通用默认值（ops/observability/compose.yml、docs/design/request-lifecycle-observability.md）。
  • 让 tracing 默认可关闭、异步且有界；让 CPU profiler 通过受限命令按需 attach，禁止把任意 PID、shell 或 profiler daemon 暴露成通用运维入口（src/observability/traces.rs、scripts/cvm-hotpath-cpu）。

Risks and open questions

  • 代理处理敏感请求，日志和 SQLite retention 需要清晰策略。
  • CRS/XYAI 历史兼容边界容易被误解。
  • Release snapshot 机制复杂，不能用简单 tag push 替换。
  • 当前 install metadata 已经明确，但没有 service worker/offline/update lifecycle 的同等级证据；后续若要把它提升为“真正的可离线 PWA”，必须先补齐这条链路。
  • linked worktree 在本地依赖出现前就需要启动 shared hook，因此全局 Lefthook 是明确前置条件；repo-local node_modules/.bin/lefthook 不能替代它。自定义 core.hooksPath 或 unmanaged hook 必须被保留，不能由安装入口暗中覆盖（docs/specs/v7se4-worktree-bootstrap/SPEC.md、scripts/install-lefthook-hooks.sh）。
  • 观测的六个 dashboard、Tempo 兼容边界和旧性能 SQLite/自研性能图表退役是当前实现事实；新增项目不能据此推导固定 dashboard 数量、tracing 必选、留存期限或性能预算。任何容量/开销结论都需要项目自己的验证卡和环境证据（docs/specs/performance-telemetry/SPEC.md、docs/specs/performance-telemetry/empirical-candidate-card.md）。
  • Grafana、Tempo、hotpath 或 profiler 的可达性不能通过复制生产入口、凭据或内部部署路径来证明；公共 playbook 只保留相对配置路径和抽象网络/身份边界。

Evidence index

  • README.md
  • Cargo.toml
  • Dockerfile
  • web/package.json
  • web/index.html
  • web/public/site.webmanifest
  • web/.storybook/main.ts
  • ops/observability/README.md
  • ops/observability/compose.yml
  • ops/observability/prometheus.yml
  • ops/observability/recording-rules.yml
  • ops/observability/grafana/dashboards/
  • ops/observability/grafana/provisioning/
  • src/observability/
  • scripts/cvm-observe
  • scripts/cvm-hotpath-cpu
  • scripts/test-observability-acceptance.py
  • scripts/test-observability-diagnostics.py
  • scripts/test-observability-tools.py
  • docs/design/performance-observability.md
  • docs/design/request-lifecycle-observability.md
  • docs/specs/performance-telemetry/SPEC.md
  • docs/specs/performance-telemetry/METRICS.md
  • docs/solutions/performance/prometheus-grafana-compose-integration.md
  • docs/specs/k7kpk-bundle-icons-locally/SPEC.md
  • docs/specs/v7se4-worktree-bootstrap/SPEC.md
  • docs/specs/v7se4-worktree-bootstrap/IMPLEMENTATION.md
  • lefthook.yml
  • scripts/install-lefthook-hooks.sh
  • scripts/run-lefthook-hook.sh
  • scripts/worktree-bootstrap.sh
  • scripts/worktree-setup.sh
  • scripts/sync-worktree-resources.sh
  • scripts/test-worktree-bootstrap.sh
  • .github/quality-gates.json
  • .github/workflows/ci-pr.yml
  • .github/workflows/ci-main.yml
  • .github/workflows/label-gate.yml
  • .github/workflows/notify-release-failure.yml
  • .github/workflows/release.yml

相关内容