feat(observe): OpenObserve 本地 compose + README(查询/仪表盘) + .env.example

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.env.example

@@ -137,3 +137,19 @@ PANGLE_REPORT_SECURITY_KEY=
 # GroMore AppId(报表 site_id 维度)→ 应用环境;默认取现网两个应用,按需覆盖。
 PANGLE_REPORT_SITE_ID_PROD=5830519
 PANGLE_REPORT_SITE_ID_TEST=5832303
+
+# ===== 可观测(OpenObserve 接口指标)=====
+# 采集每个接口 QPS + 耗时 + 错误率,批量直采到 OpenObserve(本地 Docker,见 deploy/openobserve/)。
+# 默认关;开启需 ENABLED=true 且填 USER/PASSWORD(与 docker-compose 里 root 账号一致)。
+# 未开/缺凭证 → 中间件透传、worker 不启动,整套 no-op,不影响业务。
+OBSERVE_ENABLED=false
+OBSERVE_ENDPOINT=http://localhost:5080
+OBSERVE_ORG=default
+OBSERVE_STREAM=app_requests
+OBSERVE_USER=admin@shaguabijia.local
+OBSERVE_PASSWORD=Complexpass#123
+# 进阶(一般不用改):攒批间隔秒 / 单批最大条数 / 有界队列上限(满则丢) / 上报超时秒
+OBSERVE_FLUSH_INTERVAL_SEC=5
+OBSERVE_BATCH_MAX=200
+OBSERVE_QUEUE_MAX=10000
+OBSERVE_TIMEOUT_SEC=5

deploy/openobserve/.gitignore

@@ -0,0 +1,2 @@
+# OpenObserve 落盘数据(parquet/索引/元数据),运行时产生,不入库。
+data/

deploy/openobserve/README.md

@@ -0,0 +1,67 @@
+# OpenObserve 本地部署（接口 QPS / 耗时可观测）
+
+app-server 通过中间件采集每个接口的 QPS + 耗时 + 错误率，批量上报到这里。
+设计见 [../../docs/superpowers/specs/2026-07-06-openobserve-api-metrics-design.md](../../docs/superpowers/specs/2026-07-06-openobserve-api-metrics-design.md)。
+
+## 启动
+
+```bash
+cd deploy/openobserve
+docker compose up -d
+```
+
+- Web UI：http://localhost:5080
+- 登录：`admin@shaguabijia.local` / `Complexpass#123`（见 `docker-compose.yml`）
+- 数据落 `deploy/openobserve/data/`（已挂卷持久化；该目录已 gitignore）
+
+## 让 app-server 上报
+
+在项目根的 `.env` 打开观测（`OBSERVE_*`，账号密码与 compose 里 root 一致）：
+
+```dotenv
+OBSERVE_ENABLED=true
+OBSERVE_ENDPOINT=http://localhost:5080
+OBSERVE_ORG=default
+OBSERVE_STREAM=app_requests
+OBSERVE_USER=admin@shaguabijia.local
+OBSERVE_PASSWORD=Complexpass#123
+```
+
+重启 app-server，随便打几个接口。stream `app_requests` **首次上报自动创建**，
+在 UI 的 Logs → 选 `app_requests` 就能看到逐条请求事件（字段：`method` / `route` /
+`status` / `duration_ms` / `service` / `env`）。
+
+> 未开 `OBSERVE_ENABLED` 或缺账号密码时，中间件透传、worker 不启动，整套 no-op，不影响业务。
+
+## 查询（Logs 页 SQL，或建 Dashboard 面板）
+
+各接口 QPS（1 分钟分桶，面板里再除 60 得每秒）：
+
+```sql
+SELECT route, histogram(_timestamp, '1 minute') AS ts, count(*) AS cnt
+FROM app_requests GROUP BY route, ts ORDER BY ts
+```
+
+各接口 P95 耗时（毫秒）：
+
+```sql
+SELECT route, approx_percentile_cont(duration_ms, 0.95) AS p95_ms
+FROM app_requests GROUP BY route ORDER BY p95_ms DESC
+```
+
+各接口错误率（5xx 占比）：
+
+```sql
+SELECT route,
+       count(*) FILTER (WHERE status >= 500) * 100.0 / count(*) AS err_pct
+FROM app_requests GROUP BY route ORDER BY err_pct DESC
+```
+
+## 停止 / 清数据
+
+```bash
+docker compose down            # 停止(保留数据)
+docker compose down -v && rm -rf data   # 停止并清空数据
+```
+
+> 生产部署（持久化规格、独立 ingest 账号、鉴权收紧）见 spec 第 9 节，本期不做。

deploy/openobserve/docker-compose.yml

@@ -0,0 +1,16 @@
+# 本地开发用 OpenObserve(单容器 = local 模式)。用于接收 app-server 的接口指标(QPS/耗时/错误率)。
+# 启动: cd deploy/openobserve && docker compose up -d
+# Web UI: http://localhost:5080  (账号见下方 env)
+services:
+  openobserve:
+    image: public.ecr.aws/zinclabs/openobserve:latest
+    container_name: openobserve
+    ports:
+      - "5080:5080"
+    environment:
+      ZO_ROOT_USER_EMAIL: "admin@shaguabijia.local"
+      ZO_ROOT_USER_PASSWORD: "Complexpass#123"
+      ZO_DATA_DIR: "/data"
+    volumes:
+      - ./data:/data
+    restart: unless-stopped