airi/apps/server/docs/ai-context/workers-and-runtime.md

Workers And Runtime

进程角色

入口：src/bin/run.ts。

• api
  • 启动 Hono HTTP + WebSocket 服务
  • 没有任何"常驻后台 loop"，也没有"POST 触发的 fire-and-forget"。所有写路径都在请求线程里同步完成

不再有独立的 worker / billing-consumer 进程。原先的 Redis Stream billing event 链路、advisory-lock poller、admin flux grant batch 异步处理全部移除。

API 角色

启动路径：

• src/bin/run.ts
• runApiServer()
• createApp()

启动时会做的事情：

• 解析 env
• 初始化日志
• 可选初始化 OTel
• 连接 Postgres / Redis
• 跑数据库迁移
• 装配服务
• 启动 HTTP server
• 注入 WebSocket

Admin flux grant：同步执行

详见 admin-flux-grants.md。简要：admin 调 POST /api/admin/flux-grants，路由 handler 在请求线程内顺序对每个 recipient 调 BillingService.creditFlux，HTTP 响应里直接返回每条的 outcome（granted / skipped / failed）。失败由 admin 看响应自行重发，可选 idempotencyKey 让重发安全。

失败 / 崩溃恢复

服务端没有需要恢复的"中间状态"。每次 creditFlux 自己是一个 DB 事务；要么写进 flux_transaction ledger 要么没写，没有第三态。(user_id, request_id) partial unique index 保证带 idempotencyKey 的重发不会双发。

环境变量分层

基础运行

• HOST
• PORT
• API_SERVER_URL
• DATABASE_URL
• REDIS_URL

Auth

• AUTH_GOOGLE_CLIENT_ID
• AUTH_GOOGLE_CLIENT_SECRET
• AUTH_GITHUB_CLIENT_ID
• AUTH_GITHUB_CLIENT_SECRET

Stripe

• STRIPE_SECRET_KEY
• STRIPE_WEBHOOK_SECRET

OTel

• OTEL_SERVICE_NAMESPACE
• OTEL_SERVICE_NAME
• OTEL_TRACES_SAMPLING_RATIO
• OTEL_EXPORTER_OTLP_ENDPOINT
• OTEL_EXPORTER_OTLP_HEADERS
• OTEL_DEBUG

NOTICE: BILLING_EVENTS_* 已全部移除。

聊天 WebSocket 运行时

src/routes/chat-ws/index.ts 是另一种独立运行时：

• 同实例连接保存在进程内 Map
• 跨实例 fan-out 通过 Redis Pub/Sub

这意味着：

• WS 广播不具备持久化和重放能力
• 真正补齐消息还是靠 pullMessages
• 广播只是为了降低拉取延迟，不代表存在旧式 sync 端点

如果要改 Redis key / channel 构造、Pub/Sub payload，先看 redis-boundaries-and-pubsub.md。

OpenTelemetry

初始化在 instrumentation.ts（NodeSDK lifecycle）+ src/otel/index.ts（metric handles）+ src/otel/gauges/*.ts（DB-backed ObservableGauge callbacks，例如 gauges/active-sessions.ts）。

启用条件：

• OTEL_EXPORTER_OTLP_ENDPOINT 存在

覆盖面：

• HTTP
• Auth
• Chat engagement
• Revenue
• LLM
• DB / Redis instrumentation

重要实现细节：

• sdk.start() 必须发生在 metrics.getMeter() 之前
• /livez 和 /readyz 会被 HTTP instrumentation 忽略

运行时修改建议

• 新增异步工作：先问三遍"为什么不能在请求线程里同步做完"。绝大多数 admin / webhook / 短 batch 都可以；实在不行也优先 fire-and-forget per-request，而不是引入常驻 loop。
• 真的需要 idle-driven 的活（清理过期 token、定时聚合等）：先评估是否值得。如果是，开 Postgres pg_cron 或外部 cron service 调专门的 internal API endpoint，比"进程内常驻 loop"更可观察、更易停。
• 改 Stripe / Flux 写路径：看 billing-architecture.md，所有 ledger 写入都在事务内同步完成
• 改聊天同步：先区分"持久化消息"与"广播通知"两层
• 改部署限流：注意当前 rate-limit.ts 仍是单实例内存模型