diff --git a/docs/observability-implementation-plan.md b/docs/observability-implementation-plan.md
new file mode 100644
index 0000000..d151b5d
--- /dev/null
+++ b/docs/observability-implementation-plan.md
@@ -0,0 +1,718 @@
+# 局域网服务日志与可观测性实施计划
+
+- 状态：待实施
+- 编写日期：2026-07-22
+- 代码基线：`v0.2.0` / `04e80b1`
+- 目标部署机：`192.168.193.237`（实施时必须重新确认）
+- 当前 API：`http://192.168.193.237:39180`
+
+## 新会话启动方式
+
+新开 Codex 会话后，先发送下面的提示词：
+
+```text
+请完整阅读 docs/observability-implementation-plan.md、DEPLOY_5700U.md、
+compose.deploy.yml、server/src/main.rs、server/src/transcription_worker.rs、
+asr-service/app.py 和 utils/api.ts。
+
+把 observability-implementation-plan.md 作为本次任务的执行约束。
+先检查 git、目标部署机、Docker 日志驱动、磁盘和现有容器状态，再从文档中
+第一个未完成的阶段开始实施。每完成一个阶段就运行该阶段验收，不要跳过日志
+脱敏、请求 ID、持久化、回滚验证或文档更新。除非我明确要求，不要自行提交、
+推送或修改目标机防火墙。
+```
+
+新会话开始后应先更新本文档顶部的代码基线、目标机 IP 和实际组件版本。本文中的
+镜像版本、端口和资源阈值是实施起点，不得替代实施时的现场检查。
+
+## 1. 目标
+
+本计划要建立一条可从小程序故障追溯到具体代码版本的日志链路：
+
+```text
+小程序请求
+  -> Rust API 结构化请求日志
+     -> 转录队列事件
+        -> FunASR 结构化推理日志
+           -> Docker 本地日志与轮转
+              -> Grafana Alloy 采集
+                 -> Loki 持久化与检索
+                    -> Grafana 查询、面板和告警
+```
+
+完成后应支持：
+
+1. 任意可信局域网电脑通过浏览器访问 Grafana。
+2. 按环境、Compose 项目、服务、容器、日志级别、时间和代码版本筛选日志。
+3. 用 `request_id`、`feedback_session_id`、`lesson_id` 或 `segment_id` 关联 API 与 FunASR。
+4. 判断故障发生在哪个镜像版本和 Git 提交，避免按错误版本修改代码。
+5. 保存至少 14 天日志，并限制 Docker 原始容器日志占用。
+6. 在 Loki/Grafana 不可用时，API 与 FunASR 仍可正常提供业务服务。
+7. 后续可在同一 Grafana 中逐步加入日志告警和 Prometheus 指标。
+
+## 2. 非目标
+
+第一轮不做以下工作：
+
+- 不部署 Kubernetes，也不把现有单机 Compose 改成集群。
+- 不部署 Promtail；它已从当前 Loki 版本线移除，新部署使用 Alloy。
+- 不在应用代码中直接调用 Loki API，应用只写标准输出和标准错误。
+- 不在第一轮部署 Tempo、全链路追踪、Mimir 或 Elasticsearch。
+- 不采集请求体、反馈正文、转录文本、音频内容、Bearer Token 或数据库连接串。
+- 不把 Grafana、Loki、Alloy 或 Docker API 直接暴露到公网。
+- 不用日志替代业务数据库、审计表或音频持久化卷。
+
+## 3. 当前状态与缺口
+
+### 3.1 已确认状态
+
+- `compose.deploy.yml` 只包含 `funasr`、`migrate` 和 `api`。
+- API 暴露宿主机 `39180`，FunASR 只在 Compose 内部网络提供 `10095`。
+- 规划时 `GET /health` 返回健康，数据库、语音和微信鉴权均已配置。
+- Rust API 已使用 `tracing` 和 `tracing-subscriber`，转录 worker 已记录部分
+  `worker_id`、`segment_id` 和错误事件。
+- Rust 使用 `TraceLayer::new_for_http()`，但默认请求/响应事件为 `DEBUG`；镜像当前
+  `RUST_LOG=info`，不能依赖它提供完整访问日志。
+- Rust 日志当前是文本格式，没有稳定 JSON 字段、请求 ID 或代码版本字段。
+- FunASR 使用 Python `logging`，但 Uvicorn 通过 `--no-access-log` 关闭访问日志；当前主要
+  记录模型启动和推理异常，没有成功请求耗时。
+- Compose 没有服务级 `logging` 配置。若目标机未修改 Docker daemon，通常会使用默认
+  `json-file` 且没有自动轮转，存在磁盘耗尽风险。
+- `compose.deploy.yml` 中 API 镜像仍标记为 `teaching-feedback-api:0.1.0`，与当前
+  `v0.2.0` 不一致。
+- 仓库没有 Loki、Alloy、Grafana、日志持久化卷、数据源自动配置或日志运行手册。
+
+### 3.2 必须解决的问题
+
+| 问题 | 影响 | 解决阶段 |
+| --- | --- | --- |
+| Docker 日志无显式轮转 | 宿主机磁盘可能被占满 | 阶段 1 |
+| API 请求日志不完整 | 无法定位具体失败请求 | 阶段 2 |
+| API 与 ASR 缺少统一关联 ID | 跨服务排障依赖时间猜测 | 阶段 2 |
+| 日志没有版本元数据 | 无法映射到正确代码 | 阶段 1、2 |
+| 日志仅保存在单机 Docker 中 | 其他电脑无法方便检索历史 | 阶段 3 |
+| 没有保留期和持久化验证 | 重启或磁盘增长不可控 | 阶段 3 |
+| 没有基于实际基线的告警 | 故障只能人工发现 | 阶段 4 |
+| 没有时序指标 | 无法可靠发现“没有日志”的故障 | 阶段 5 |
+
+## 4. 目标架构
+
+应用栈和可观测性栈使用两份 Compose 文件独立管理：
+
+```text
+compose.deploy.yml                    compose.observability.yml
+
+api -------- stdout/stderr ----+      alloy ----> loki ----> grafana:3000
+funasr ----- stdout/stderr -----+        |          |             |
+migrate ---- stdout/stderr -----+--------+       loki-data     grafana-data
+                                         |
+                                 Docker Engine API
+                                 /var/run/docker.sock
+```
+
+约束：
+
+- `api`、`funasr`、`migrate` 不依赖 Loki、Alloy 或 Grafana 启动。
+- Alloy 通过 Docker Engine API 发现带指定标签的容器并读取日志。
+- Loki 与 Alloy 不发布宿主机端口。
+- 只有 Grafana 发布到可信局域网，建议默认使用 `${GRAFANA_PORT:-39300}:3000`。
+- 局域网外访问使用 WireGuard、Tailscale 或 SSH 隧道，不做公网裸端口。
+- Grafana 必须启用登录；禁止匿名访问。
+- Loki 初始使用单体模式、TSDB 索引和本地文件系统卷，接受单机无高可用的现实。
+- Loki 默认保留 14 天；稳定运行并确认磁盘余量后再考虑 30 天。
+
+## 5. 日志字段规范
+
+### 5.1 公共字段
+
+Rust API 和 FunASR 每条应用日志尽量使用一致字段：
+
+| 字段 | 示例 | 说明 |
+| --- | --- | --- |
+| `timestamp` | `2026-07-22T02:00:00.123Z` | RFC 3339 UTC 时间 |
+| `level` | `INFO` | `TRACE/DEBUG/INFO/WARN/ERROR` |
+| `service` | `api` | `api`、`funasr` 或 `migrate` |
+| `environment` | `lan` | 固定低基数字段 |
+| `app_version` | `0.2.0` | 发行版本 |
+| `git_sha` | `04e80b1` | 构建或部署提交 |
+| `event` | `http_request_finished` | 稳定、可查询的事件名 |
+| `request_id` | UUID | 单次 HTTP 请求关联 ID，不作为 Loki 标签 |
+| `message` | 简短英文或中文 | 人类可读说明 |
+
+容器、Compose 项目、Compose 服务、镜像等字段由 Alloy 从 Docker 元数据补充。
+
+### 5.2 API 请求字段
+
+- `method`
+- `route`：优先路由模板，例如 `/api/v1/profiles/{profile_id}`
+- `path`：必要时保留原始路径，但不得包含敏感 query 参数
+- `status`
+- `latency_ms`
+- `request_id`
+- `error_class`：只在失败时记录稳定分类
+
+不要记录完整请求头。尤其禁止记录 `Authorization`、Cookie、微信 code、AppSecret 和
+上传内容。
+
+### 5.3 语音链路字段
+
+- `feedback_session_id`
+- `lesson_id`
+- `segment_id`
+- `asr_request_id`
+- `worker_id`
+- `audio_format`
+- `audio_size_bytes`
+- `audio_duration_ms`
+- `queue_wait_ms`
+- `inference_latency_ms`
+- `provider`
+- `attempt`
+- `status`
+
+禁止记录本地音频绝对路径、热词原文、转录文字或反馈正文。
+
+### 5.4 Loki 标签规范
+
+仅将低基数字段设为 Loki 标签：
+
+- `environment`
+- `compose_project`
+- `compose_service`
+- `container`
+- `service`
+- `level`
+- `app_version`
+
+以下字段只能保留在 JSON 日志正文中，通过 `| json` 查询，不能成为标签：
+
+- `request_id`
+- 用户 ID、学生 ID、会话 ID、课节 ID、片段 ID
+- URL 原始路径
+- 错误消息
+
+## 6. 计划新增或修改的文件
+
+| 文件 | 动作 | 目的 |
+| --- | --- | --- |
+| `compose.deploy.yml` | 修改 | 日志轮转、容器筛选标签、版本环境变量、镜像版本 |
+| `server/Cargo.toml` | 修改 | 开启 `tracing-subscriber/json` 和 `tower-http/request-id` |
+| `server/src/main.rs` | 修改 | JSON 日志、请求 ID、INFO 请求完成日志、启动版本日志 |
+| `server/src/config.rs` | 修改 | 读取 `LOG_FORMAT`、`APP_VERSION`、`GIT_SHA`、`APP_ENV` |
+| `server/src/transcription_worker.rs` | 修改 | 增加队列等待、尝试次数、ASR 耗时和关联字段 |
+| `server/src/speech.rs` | 修改 | 将 `segment_id`/请求 ID 传给 FunASR |
+| `server/.env.example` | 修改 | 记录非敏感日志配置项 |
+| `utils/api.ts` | 修改 | 保存响应 `X-Request-ID` 到 `ApiRequestError` |
+| 相关小程序错误状态 | 修改 | 在可复制位置显示请求编号，不塞入短 Toast |
+| `asr-service/app.py` | 修改 | 请求 ID 中间件、成功/失败耗时和结构化字段 |
+| `asr-service/logging_config.py` | 新增 | 标准库 JSON formatter 与日志初始化 |
+| `asr-service/Dockerfile` | 修改 | 传入版本环境，继续避免重复 Uvicorn access log |
+| `compose.observability.yml` | 新增 | Alloy、Loki、Grafana 三个服务 |
+| `observability/alloy/config.alloy` | 新增 | Docker 发现、筛选、标签、转发配置 |
+| `observability/loki/loki.yml` | 新增 | 单体 TSDB、文件系统、保留期配置 |
+| `observability/grafana/provisioning/datasources/loki.yml` | 新增 | 自动创建 Loki 数据源 |
+| `observability/grafana/provisioning/dashboards/` | 后续新增 | 阶段 4 面板和告警 |
+| `observability/.env.example` | 新增 | 端口、版本、管理员账号变量说明，不含密码 |
+| `.gitignore` | 修改 | 忽略 `observability/.env`、本地数据和导出文件 |
+| `docs/observability-runbook.md` | 新增 | 启停、查询、备份、升级、故障处理 |
+| `DEPLOY_5700U.md` | 修改 | 把日志栈加入部署和验收流程 |
+
+## 7. 分阶段实施
+
+### 阶段 0：现场基线与风险检查
+
+目标：在修改配置前记录目标机真实状态。
+
+在目标部署机执行：
+
+```bash
+cd /path/to/teaching-feedback-assistant
+git status --short --branch
+git rev-parse HEAD
+git tag --points-at HEAD
+
+docker version
+docker compose version
+docker info --format '{{.LoggingDriver}}'
+docker compose -f compose.deploy.yml ps
+docker compose -f compose.deploy.yml images
+docker compose -f compose.deploy.yml logs --since 1h api funasr
+docker inspect teaching-feedback-api-1 --format '{{json .HostConfig.LogConfig}}' || true
+
+df -h
+docker system df
+timedatectl status
+ss -lntp | grep -E ':(39180|39300|3100|12345)\b' || true
+```
+
+实施要求：
+
+1. 不输出 `server/.env` 内容。
+2. 记录 Docker 当前日志驱动、容器名、镜像 ID、重启次数和日志占用。
+3. 确认 `39300` 是否可用；冲突时选择其他端口并更新本文档。
+4. 确认至少有 10 GB 可用空间给日志卷；不足时先清理或降低保留期。
+5. 确认目标机时钟同步。日志统一为 UTC，Grafana 按浏览器时区显示。
+6. 确认 API、FunASR 和真实转录链路在改造前正常。
+
+验收：把基线命令和非敏感结果写入实施记录，任何失败先解释，不进入阶段 1。
+
+### 阶段 1：Docker 日志轮转与版本元数据
+
+目标：即使集中日志尚未部署，容器日志也不能无限增长。
+
+在 `compose.deploy.yml` 增加可复用配置：
+
+```yaml
+x-default-logging: &default-logging
+  driver: local
+  options:
+    max-size: "20m"
+    max-file: "5"
+```
+
+对 `funasr`、`migrate` 和 `api` 使用该配置。优先使用服务级配置，不修改 Docker daemon
+全局默认，避免影响目标机的其他项目。
+
+同时增加：
+
+```yaml
+labels:
+  observability.logs: "true"
+  observability.environment: "lan"
+environment:
+  APP_ENV: lan
+  APP_VERSION: ${APP_VERSION:-0.2.0}
+  GIT_SHA: ${GIT_SHA:-unknown}
+  LOG_FORMAT: ${LOG_FORMAT:-json}
+```
+
+要求：
+
+1. API 镜像标签不得继续硬编码为 `0.1.0`。
+2. 实施时从 Git tag/commit 注入 `APP_VERSION` 和 `GIT_SHA`。
+3. 镜像版本必须固定，不使用 `latest`。
+4. `local` 日志驱动的配置值必须是字符串。
+5. 修改日志驱动后必须重建容器；仅 restart 不会更新已有容器的日志驱动。
+
+验证：
+
+```bash
+docker compose -f compose.deploy.yml config
+docker compose -f compose.deploy.yml up -d --build --force-recreate
+docker compose -f compose.deploy.yml ps
+docker compose -f compose.deploy.yml logs --since 10m api funasr
+docker inspect <api-container> --format '{{json .HostConfig.LogConfig}}'
+docker inspect <funasr-container> --format '{{json .Config.Labels}}'
+curl -fsS http://127.0.0.1:39180/health
+```
+
+阶段 1 完成标准：三个服务使用受控日志驱动，API 健康且真实转录仍成功。
+
+### 阶段 2：结构化请求日志与跨服务关联
+
+#### 2.1 Rust API
+
+依赖调整：
+
+```toml
+tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
+tower-http = { version = "0.6", features = ["cors", "trace", "request-id"] }
+```
+
+实现要求：
+
+1. `LOG_FORMAT=json` 时使用 `tracing_subscriber::fmt().json()`，关闭 ANSI，并保留当前 span。
+2. 本地开发允许 `LOG_FORMAT=pretty`，但生产 Compose 固定 `json`。
+3. 使用 `tower_http::request_id`：
+   - 接受合法的客户端 `X-Request-ID`。
+   - 缺失时用 `MakeRequestUuid` 生成。
+   - 在响应头中传播同一个 `X-Request-ID`。
+4. 中间件顺序按 tower-http 要求设置：先 Set Request ID，再 Trace，最后 Propagate。
+5. `TraceLayer` 的请求开始、请求结束和失败级别显式设置为 `INFO/ERROR`，不依赖默认
+   `DEBUG`。
+6. `make_span_with` 不记录 headers；记录 `method`、`route/path` 和 `request_id`。
+7. `on_response` 记录 `status` 和 `latency_ms`。
+8. 5xx/超时记录 `ERROR`，可预期 4xx 不得全部当成系统错误。
+9. 启动时记录 `service`、`environment`、`app_version`、`git_sha`、监听地址和语音提供方。
+10. 不在日志中输出 `DATABASE_URL`、微信密钥、Summary API Key 或任何 Token。
+
+补充单元/集成测试：
+
+- 无请求 ID 时响应包含合法 UUID。
+- 带合法请求 ID 时响应原样传播。
+- 日志中不包含 Authorization 值。
+- 200、400、401、500 都产生一次完成事件。
+- JSON 日志每行可被 `jq` 解析。
+
+#### 2.2 转录 worker 与 Rust -> FunASR
+
+1. 在 claim job 时取得 `processing_started_at`、`transcription_attempts` 等必要字段。
+2. 以 `segment_id` 作为跨 API/ASR 的稳定业务关联字段。
+3. Rust 请求 FunASR 时设置 `X-Request-ID`；可直接使用 `segment_id`，或生成新的
+   `asr_request_id` 并同时记录两者。
+4. 记录排队等待、音频读取、HTTP 调用、推理完成和数据库更新的分段耗时。
+5. 成功日志不得包含 transcript；失败日志只记录经过清理的错误分类和消息。
+
+#### 2.3 FunASR
+
+1. 新增标准 JSON formatter，不因日志系统引入另一套应用框架。
+2. 中间件读取/生成 `X-Request-ID`，并写回响应头。
+3. 记录 `asr_request_started`、`asr_request_finished` 和 `asr_request_failed`。
+4. 成功和失败均记录 `status`、`latency_ms`、`audio_size_bytes`、`audio_duration_ms`、
+   `audio_format` 和 `request_id`。
+5. 保留 `--no-access-log`，避免 Uvicorn 默认访问日志和自定义日志重复。
+6. 不记录临时路径、文件名、hotword、模型输出文本或上传内容。
+
+#### 2.4 小程序错误编号
+
+1. `ApiRequestError` 增加可选 `requestId`。
+2. `wx.request` 与 `wx.uploadFile` 都从响应头读取 `X-Request-ID`，兼容响应头大小写。
+3. 短 Toast 不塞入长 UUID；需要持久显示错误的状态区增加“请求编号”与复制入口。
+4. 开发者控制台可以记录请求编号，但不得打印 Token、上传路径或请求正文。
+
+阶段 2 验收：
+
+```bash
+cd server
+cargo fmt --check
+cargo test
+cargo clippy --all-targets --all-features -- -D warnings
+
+cd ..
+npm run typecheck
+docker compose -f compose.deploy.yml config
+```
+
+再用一个固定 `X-Request-ID` 调用 `/health` 和一个授权业务接口，确认 API 日志可按该 ID
+检索。使用真实音频验证 `segment_id` 能关联 Rust 与 FunASR，且日志中没有转录正文。
+
+### 阶段 3：部署 Alloy、Loki、Grafana
+
+#### 3.1 版本选择
+
+实施时查阅官方 release notes，选择互相兼容的稳定版本并固定完整版本号：
+
+- `grafana/alloy:<version>`
+- `grafana/loki:<version>`
+- `grafana/grafana:<version>`
+
+禁止使用 `latest`。将选定版本写入 `observability/.env.example` 和实施记录。
+
+#### 3.2 Compose 约束
+
+新增 `compose.observability.yml`，项目名建议为 `teaching-feedback-observability`。
+
+`loki`：
+
+- 单体模式。
+- 配置文件只读挂载。
+- `/var/loki` 使用 `loki-data` 持久化卷。
+- 不发布 `3100` 到宿主机。
+- 提供 readiness 健康检查。
+- `restart: unless-stopped`。
+
+`alloy`：
+
+- 配置文件只读挂载。
+- `/var/lib/alloy/data` 使用 `alloy-data`，保存 Docker 读取位置。
+- 初始部署读取 `/var/run/docker.sock`。
+- Docker Socket 挂载即使标记只读，也不是完整的 API 权限隔离；容器必须使用固定镜像、
+  最小权限且不对外开放 Alloy UI。安全要求提高时改为受限 Docker Socket Proxy。
+- 不发布 Alloy `12345` 到宿主机。
+- `restart: unless-stopped`。
+
+`grafana`：
+
+- `/var/lib/grafana` 使用 `grafana-data`。
+- 默认发布 `${GRAFANA_PORT:-39300}:3000`。
+- `GF_AUTH_ANONYMOUS_ENABLED=false`。
+- 管理员密码仅放在未提交的 `observability/.env` 或 Docker Secret。
+- 自动挂载 Loki 数据源 provisioning。
+- `restart: unless-stopped`。
+
+#### 3.3 Loki 配置
+
+`observability/loki/loki.yml` 至少满足：
+
+- `auth_enabled: false`，但 Loki 只存在于内部 Docker 网络。
+- 单体 `target=all`。
+- TSDB schema，不使用已弃用 BoltDB index。
+- chunks、rules、WAL 和 compactor 目录全部落在 `/var/loki`。
+- compactor retention 开启。
+- 初始 `retention_period: 336h`（14 天）。
+- 禁用匿名 usage analytics（若当前版本支持对应配置）。
+- 设定合理 ingestion/query 限制，防止一次错误查询拖垮单机。
+
+文件系统存储没有副本，也不会按磁盘剩余空间自动删除；保留期之外仍要监控磁盘。
+
+#### 3.4 Alloy 配置
+
+`observability/alloy/config.alloy` 应包含：
+
+1. `discovery.docker` 连接 `unix:///var/run/docker.sock`。
+2. `discovery.relabel` 只保留 `observability.logs=true` 的容器。
+3. 从 Docker 元数据映射 `compose_project`、`compose_service`、`container`、`image`。
+4. `loki.source.docker` 读取容器日志并保存 positions。
+5. `loki.process` 添加 `environment=lan`，解析 JSON 日志级别；解析失败时保留原始行。
+6. 不把 `request_id`、用户或业务 ID 提升为标签。
+7. `loki.write` 发送到 `http://loki:3100/loki/api/v1/push`。
+
+#### 3.5 Grafana 自动配置
+
+Loki 数据源通过 provisioning 创建：
+
+```yaml
+apiVersion: 1
+datasources:
+  - name: Loki
+    type: loki
+    access: proxy
+    url: http://loki:3100
+    isDefault: true
+    editable: false
+```
+
+首次只创建数据源和一个最小“日志浏览”面板，不提前加入未经验证的告警阈值。
+
+#### 3.6 启动与验证
+
+```bash
+docker compose -f compose.observability.yml config
+docker compose -f compose.observability.yml up -d
+docker compose -f compose.observability.yml ps
+docker compose -f compose.observability.yml logs --since 10m alloy loki grafana
+curl -fsS http://127.0.0.1:39300/api/health
+```
+
+验收：
+
+1. 浏览器可从另一台局域网电脑打开 `http://192.168.193.237:39300`。
+2. 未登录不能查看日志。
+3. Grafana Explore 能看到 `api` 和 `funasr`。
+4. 以下查询可用，实际标签名以 Alloy 配置为准：
+
+```logql
+{compose_service="api"} | json
+{compose_service="api"} | json | request_id="<request-id>"
+{compose_service="funasr"} | json | segment_id="<segment-id>"
+{compose_service="api"} | json | status >= 500
+```
+
+5. 重启 Alloy 后不大量重复采集旧日志。
+6. 重启整套可观测性 Compose 后，Grafana 数据源、账号配置和 Loki 历史仍存在。
+7. 停止 Loki/Alloy/Grafana 后，API 和 FunASR 继续正常工作。
+8. Loki、Alloy 的宿主机端口不可访问。
+
+### 阶段 4：基于实际日志建立面板与告警
+
+先运行至少 3–7 天，观察正常流量、错误数量和转录耗时，再设置阈值。
+
+首批面板：
+
+- API 请求总量、4xx、5xx。
+- API `latency_ms` 的 p50/p95/p99。
+- 各路由错误日志列表。
+- 转录成功、失败和重试数量。
+- ASR 推理耗时和音频时长比值。
+- `ASR service is unavailable` 与恢复事件。
+- 按 `app_version` 对比错误率。
+
+首批日志告警候选：
+
+- 5 分钟内 API 5xx 达到 3 次。
+- 10 分钟内出现转录失败。
+- 5 分钟内持续出现数据库查询失败。
+- ASR 不可用持续超过 5 分钟。
+- Loki ingestion 或 Alloy target unhealthy。
+
+告警要求：
+
+1. 每条告警必须提供可直接打开的 Grafana 查询。
+2. 配置 `for` 持续时间，避免瞬时启动日志触发。
+3. 通知内容包含服务、环境、版本和时间范围，不包含用户数据。
+4. 先发送到低风险通知渠道进行一周观察，再升级为正式告警。
+5. 告警规则和 dashboard JSON 纳入 Git，禁止只在网页里手工保存。
+
+Grafana 可直接基于 Loki 日志创建告警，但“服务完全无日志”“CPU/内存异常”“磁盘即将
+耗尽”更适合指标，留到阶段 5。
+
+### 阶段 5：按实际故障增加指标采集
+
+日志稳定后再引入 Prometheus 指标。Alloy 可以抓取指标，但它不是长期指标存储；自托管
+方案需要增加 Prometheus，或把指标 remote write 到已有兼容后端。
+
+建议指标：
+
+Rust API：
+
+- `http_requests_total{route,method,status_class}`
+- `http_request_duration_seconds{route,method}`
+- `transcription_queue_jobs{status}`
+- `transcription_job_duration_seconds`
+- `transcription_job_retries_total`
+- `database_pool_connections{state}`
+- `asr_available`
+
+FunASR：
+
+- `asr_requests_total{status}`
+- `asr_inference_duration_seconds`
+- `asr_audio_duration_seconds`
+- `asr_inflight_requests`
+- `asr_failures_total{reason}`
+
+宿主机与容器：
+
+- node-exporter：CPU、内存、磁盘、负载。
+- cAdvisor 或 Alloy Docker integration：容器 CPU、内存、重启和网络。
+- `up`：API、FunASR、Loki、Alloy、Grafana 抓取状态。
+
+指标标签禁止包含请求 ID、学生 ID、会话 ID 或原始 URL。路由必须使用模板路径，避免
+高基数。
+
+阶段 5 告警优先级：
+
+1. 磁盘剩余小于 15%。
+2. API/FunASR `up == 0` 持续 2 分钟。
+3. 转录队列持续增长或最老任务等待超阈值。
+4. API p95 延迟持续异常。
+5. 容器反复重启或内存逼近限制。
+
+只有在日志和指标仍无法解释跨服务延迟时，才评估 OpenTelemetry + Tempo tracing。
+
+## 8. 安全与隐私要求
+
+### 禁止进入日志
+
+- `Authorization`、Cookie、微信登录 code、session key。
+- `WECHAT_APP_SECRET`、数据库密码、完整 `DATABASE_URL`。
+- Summary/LLM API Key。
+- 学生姓名、家长称呼、反馈正文、转录全文、hotword。
+- 音频内容、完整本地路径、上传临时文件名。
+- 完整请求/响应 body。
+
+### 允许但不作为标签
+
+- 内部 UUID：profile/session/lesson/segment。
+- request ID。
+- 清理后的错误消息。
+
+### 网络与权限
+
+- Grafana 只允许可信局域网 CIDR 或 VPN 访问。
+- Loki、Alloy 和 Docker API 不发布到宿主机。
+- Alloy 的 Docker Socket 权限视为高权限，固定镜像版本并限制可访问人员。
+- Grafana 管理员密码不得提交；首次登录后更换默认密码。
+- Scalar 和 Grafana 都属于运维入口，未来若局域网信任边界扩大，应统一加反向代理、
+  HTTPS 和认证。
+
+## 9. 容量、保留与备份
+
+初始值：
+
+- Docker 原始日志：每容器 `20 MB x 5`。
+- Loki：14 天保留。
+- 每日检查：`df -h`、`docker system df`、Loki 卷大小。
+- 预警：磁盘剩余 20% 开始观察，15% 告警，10% 紧急处理。
+
+备份：
+
+- `grafana-data`：保存数据源、用户和本地状态；虽然 provisioning 在 Git 中，仍需备份。
+- `loki-data`：若历史日志不是关键资产，可不做强一致备份，但必须明确接受丢失风险。
+- 配置文件和 dashboard/alert provisioning 必须进入 Git。
+- 不备份 Alloy positions 时会导致重采或漏采风险，因此 `alloy-data` 应持久化。
+
+备份和恢复命令在实施时写入 `docs/observability-runbook.md`，并实际演练一次 Grafana 配置
+恢复和 Loki 重启持久性。
+
+## 10. 回滚方案
+
+可观测性栈必须可独立回滚：
+
+```bash
+docker compose -f compose.observability.yml down
+```
+
+该操作不能停止 `compose.deploy.yml` 的业务服务。默认不加 `-v`，避免误删日志和 Grafana
+数据。
+
+应用日志回滚：
+
+1. 将 `LOG_FORMAT=pretty` 可暂时恢复文本输出，不需要改业务代码。
+2. 若请求中间件引发问题，回退对应提交并重建 API 镜像。
+3. 若 `local` 日志驱动与采集不兼容，回退 Compose 日志块后 `--force-recreate` 容器；
+   restart 不足以恢复日志驱动。
+4. 每阶段使用独立提交，禁止把业务功能改动混进日志基础设施提交。
+
+删除数据前必须先确认：
+
+```bash
+docker volume ls | grep teaching-feedback
+docker compose -f compose.observability.yml down
+# 只有用户明确确认后才允许删除 loki-data/grafana-data/alloy-data
+```
+
+## 11. 建议提交拆分
+
+1. `ops(logging): configure container log rotation and version labels`
+2. `feat(logging): add structured request and transcription logs`
+3. `ops(observability): add alloy loki and grafana stack`
+4. `docs(observability): add operations and troubleshooting runbook`
+5. `feat(observability): add validated dashboards and alerts`
+6. `feat(metrics): expose service and transcription metrics`（阶段 5，单独实施）
+
+每个提交前运行与其影响范围相匹配的测试。部署修改未经目标机验收不得直接打 release tag。
+
+## 12. 最终验收清单
+
+- [ ] 目标机 Docker 日志驱动和轮转参数已记录。
+- [ ] API、FunASR、migrate 均使用受控日志轮转。
+- [ ] Rust 与 FunASR 每行输出有效 JSON。
+- [ ] API 响应返回 `X-Request-ID`。
+- [ ] 小程序能保留并展示失败请求编号。
+- [ ] 真实录音可通过 `segment_id/request_id` 关联 Rust 与 FunASR。
+- [ ] 日志中未发现 Token、密钥、学生信息、反馈正文或转录全文。
+- [ ] Alloy 只采集明确标记的容器。
+- [ ] Loki 与 Alloy 没有宿主机端口。
+- [ ] Grafana 需要登录且只在可信网络可达。
+- [ ] Loki 数据源由 provisioning 自动创建。
+- [ ] 14 天 retention 生效，磁盘增长已观察。
+- [ ] 重启可观测性栈后历史和配置仍存在。
+- [ ] 停止可观测性栈不影响 API 和 FunASR。
+- [ ] `cargo fmt --check`、`cargo test`、严格 Clippy 和 `npm run typecheck` 通过。
+- [ ] `docs/observability-runbook.md` 包含启停、查询、备份、升级和回滚命令。
+- [ ] 至少 3–7 天基线后再启用正式告警。
+- [ ] 指标阶段明确使用 Prometheus 或兼容存储，不误把 Alloy 当成指标数据库。
+
+## 13. 官方参考资料
+
+实施时重新核对最新稳定版本和配置语法：
+
+- Docker logging drivers：<https://docs.docker.com/engine/logging/configure/>
+- Grafana Alloy 工作方式：<https://grafana.com/docs/alloy/latest/introduction/how-alloy-works/>
+- Alloy Docker 日志采集：<https://grafana.com/docs/alloy/latest/reference/components/loki/loki.source.docker/>
+- Alloy Docker 容器安装：<https://grafana.com/docs/alloy/latest/set-up/install/docker/>
+- Loki Docker/Compose 安装：<https://grafana.com/docs/loki/latest/setup/install/docker/>
+- Loki 存储和 retention：<https://grafana.com/docs/loki/latest/configure/storage/>
+- Loki 配置参考：<https://grafana.com/docs/loki/latest/reference/loki-config-ref/>
+- Grafana Docker 安装：<https://grafana.com/docs/grafana/latest/setup-grafana/installation/docker/>
+- Grafana Alerting：<https://grafana.com/docs/grafana/latest/alerting/>
+- Alloy Prometheus scrape：<https://grafana.com/docs/alloy/latest/reference/components/prometheus/prometheus.scrape/>
+- tower-http request ID：<https://docs.rs/tower-http/0.6.11/tower_http/request_id/>
+- tower-http trace：<https://docs.rs/tower-http/0.6.11/tower_http/trace/>
+
+## 14. 实施完成后的交付报告
+
+新会话完成每个阶段后应报告：
+
+- 实际提交和部署版本。
+- 新增/修改文件与 `git diff --stat`。
+- 目标机日志驱动、容器、端口、网络和卷状态。
+- API、FunASR、Alloy、Loki、Grafana 健康检查结果。
+- 一条真实请求和一条真实转录的关联查询结果。
+- 日志脱敏检查结果。
+- 数据保留、磁盘使用和备份/恢复验证。
+- 已配置告警及其基线依据。
+- 未完成项、已知风险和明确回滚命令。
+
+报告不得输出密码、Token、完整数据库地址、学生信息、反馈正文或转录内容。