Rust web service

Rust web service 表示 Rust binary 承担长期运行的服务职责：提供 HTTP API、proxy、SSE、docs/data service、admin backend 或 ops daemon，并对外暴露稳定的网络、存储和部署边界。这里的关键词不是“Rust”，而是“服务进程”。

这个 Topic 不只是“语言是 Rust”。它要求维护者把监听端口、bind 策略、auth、upstream proxy、SQLite/配置读写、静态资产服务、事件流、容器部署和故障恢复都当作产品 contract 来维护。它与 embedded admin UI 常一起出现，但前者解释的是服务端 runtime，后者只解释前端资产如何随服务交付（projects/proxy-broker.md、projects/codex-vibe-monitor.md、projects/tavily-hikari.md）。

服务的观测面也属于 runtime contract：metrics exporter、健康/新鲜度状态、dashboard/alert provisioning、可选 tracing、hotpath report 和按需 CPU 诊断必须有自己的权限、网络、限额与降级语义，但不能取代业务持久化或改变服务成功条件（projects/codex-vibe-monitor.md、skills/style-playbook/references/topics/monitoring-dashboard/TOPIC.md）。

当 Cargo.toml 依赖 Axum/Tower/Tokio/SQLx/Reqwest 等服务栈，且 README 或 Dockerfile 证明它是运行中的服务时使用。纯 embedded crate 或 CLI crate 不应使用。

如果用户请求会影响 HTTP route、SSE、proxy behavior、SQLite persistence、static asset serving、Docker runtime、port binding、service auth、reverse proxy 集成或 graceful shutdown，就应使用本 Topic。若 Rust crate 只提供 embedded driver、firmware、CLI helper 或 build-time tool，应使用更具体的 embedded/CLI Topic（projects/gc9d01-rs.md）。

当服务同时带前端控制台或 docs/data API 时，也应使用本 Topic；前端 Topic 只能解释 UI surface，不能替代对 Rust 进程生命周期、监听地址、持久层和部署安全边界的记录（projects/style-playbook-skills.md）。

• Rust service + embedded React UI 需要双重 build gate；projects/proxy-broker.md 和 projects/codex-vibe-monitor.md 都把 web assets 打入服务。
• 服务默认 bind/port/auth 是项目记忆；projects/proxy-broker.md 保留 loopback + Forward Auth，projects/xp.md 保留 Xray/gRPC/cluster。
• SQLite/SQLx 常作为低运维持久层，但 schema/migration 要单独记录。
• Dockerfile 中固定 runtime base 可以避免 glibc 或 system dependency 漂移。
• 服务默认监听地址和端口是安全边界，不是 UI 细节。loopback、reverse proxy、Forward Auth、admin token、CORS/SSE 等行为需要在项目快照中保留（projects/proxy-broker.md）。
• 当 Rust 服务承载嵌入式前端时，release 验证要覆盖 Cargo tests、web build、asset embedding、Docker image 和版本显示；缺一项都可能导致运行时页面不可用（projects/codex-vibe-monitor.md）。
• 默认把 runtime config、DB path、log/metrics、health endpoint 和 shutdown/restart 行为写进项目记忆；这些信息直接决定本地预览、部署迁移和故障排查方式（projects/xp.md）。
• 把 metrics、trace、profile 和业务事实分开描述：metrics 用于有界聚合历史，trace 用于受限单请求关联，profile 用于按需 CPU 归因，业务库保存调用/任务/审计事实；观测停机只能让诊断降级，不能阻塞请求、ACK、任务或事务（projects/codex-vibe-monitor.md）。
• 对 exporter 和诊断接口分别记录 bind、auth、network、token source、响应/查询上限和故障语义；Prometheus/Tempo 不应被当作普通公网 API，scrape/read/Viewer/OTLP 身份也不应复用（projects/codex-vibe-monitor.md）。
• 服务验证不能只跑 Cargo tests 或只探活 HTTP route；带观测面的服务还要验证 target freshness、样本质量、Histogram 查询类型、dashboard provisioning 和外部 backend 故障隔离，具体工具由项目合同决定（projects/codex-vibe-monitor.md）。
• 先判断服务的主职责是 control plane、proxy、dashboard backend、daemon 还是 data service。projects/proxy-broker.md 的风险在 bind/auth，projects/tavily-hikari.md 的风险在 upstream anonymization 和 key pool，projects/xp.md 的风险在 cluster state 与 reconcile；它们不能共用一段空泛的“Rust 服务默认值”。
• 对代理类服务，upstream 约束本身就是主题边界。只写“有 reqwest/axum”不够，必须记录请求能否转发、哪些 header 必须剥离、哪些历史路径只读兼容、哪些上游行为不能重新引入（projects/tavily-hikari.md、projects/codex-vibe-monitor.md）。
• 对带 UI 的 Rust 服务，前端只是暴露面，不是服务定义本身。回答此 Topic 时默认先讲 bind/auth/data/runtime，再讲 React/shadcn/Storybook；否则容易把核心风险讲反。

• projects/proxy-broker.md：代理池/session listener/operator console。
• projects/codex-vibe-monitor.md：代理服务、SQLite、嵌入式 UI 与 Prometheus/Grafana/可选 Tempo 观测面的组合，适合检查“服务 runtime”与“观测 runtime”是否仍然分层。
• projects/octo-rill.md：GitHub feed ingestion + SQLite + React workspace。
• projects/xp.md：OpenRaft desired-state + Xray reconcile。
• projects/style-playbook-skills.md：本地知识库站点与生成任务 DB。
• projects/tavily-hikari.md：MCP proxy/key pool/audit log 形态，适合检查代理服务与 SQLite 持久层的边界。

这些样本覆盖了代理、控制台、分布式协调、知识库数据服务与审计服务等不同职责。维护时应先按实际服务责任选择参考实现，再把端口、认证、持久层和嵌入式前端的验证范围组合起来，不能把任一项目的默认值机械复制到另一种运行形态。

• 把 Rust service 当 CLI，会漏掉端口、auth、SSE、static assets 和 DB path。
• 只跑 Cargo tests 不跑 web build，会破坏 embedded UI。
• 默认 bind 从 loopback 改成 public 是安全风险。
• 把 SQLite path、data dir 或 env var 留在 README 之外，会让部署迁移时丢状态；项目快照应把 DB、volume 和 runtime env 写进 Evidence-backed sections（projects/tavily-hikari.md）。
• 只验证 Docker build 不访问服务端点，会漏掉 route、static asset、SSE 和 auth 行为；对 owner-facing 预览必须用当前端口租约和浏览器验证链路（projects/style-playbook-skills.md）。
• 把服务抽象成“后端 API”也很容易漏事。很多仓库的真正 contract 在 proxy、reconcile、audit log、队列或 state migration 上，而不是 REST 路由列表；只审 route handler 会遗漏最贵的故障点（projects/xp.md、projects/codex-vibe-monitor.md）。
• 把前端问题和服务问题混在一起会让修复顺序错误。正确做法通常是先确认服务 bind/auth/storage/runtime 是否成立，再决定是否继续查嵌入式 UI、Storybook 或 React 组件层。
• 把 /metrics、hotpath report 或 trace query 当作普通无鉴权 route，会把诊断数据和内部拓扑暴露出去；应采用私网抓取、固定白名单、独立 token 和明确的 degraded/unknown 状态（projects/codex-vibe-monitor.md）。
• 只验证业务 route 成功，不验证 metrics freshness、dashboard query 和观测 backend 停机，会让服务在“业务可用但不可诊断”时缺少明确状态；把运行时和观测 runtime 分别验收，再检查两者的故障隔离。
• 把 tracing、hotpath 或 profiler 的项目数字写成 Rust service 通用默认值，会掩盖部署容量和安全差异；项目快照应保留事实，Topic 只保留边界和审查问题（skills/style-playbook/references/topics/monitoring-dashboard/TOPIC.md）。

• projects/proxy-broker.md
• projects/octo-rill.md
• projects/xp.md
• projects/style-playbook-skills.md
• projects/codex-vibe-monitor.md
• ops/observability/compose.yml
• src/observability/
• scripts/cvm-observe