diff --git a/deploy/infra/observability/README.md b/deploy/infra/observability/README.md
index 0ff99612..afe28b48 100644
--- a/deploy/infra/observability/README.md
+++ b/deploy/infra/observability/README.md
@@ -29,12 +29,12 @@ HOST=100.64.0.8 bash health-check.sh
 
 ## 端口账
 
-对外端口都逐个核对过没和 mini-infra 现有占用撞(new-api=3000、gitea=3001、ragflow=9380-9381、postgres=5433、minio=9000-9001、mysql=3306、redis=6379、nacos=8848、rocketmq=9876/10911、nginx=80/443、infinity=23817/23820)。
+对外端口都逐个核对过没和 mini-infra 现有占用撞(new-api=3000、gitea=3001、ragflow=9380-9381、postgres=5433、minio=9000-9001、mysql=3306、redis=6379、nacos=8848、rocketmq=9876/10911、nginx=80/443、infinity=23817/23820、mihomo=9090)。注:`docker ps` 只列 bridge 网端口,host 网容器与宿主进程(如 mihomo/clash 占的 9090)要 `ss -tlnp` 才看得全 —— Prometheus 因此从 9090 让到 9091。
 
 | 组件 | 对外端口 | 用途 |
 |---|---|---|
 | Grafana | 3002 | Web 看板(默认 3000/3001 已被占,改 3002) |
-| Prometheus | 9090 | Web UI / 查询 API |
+| Prometheus | 9091 | Web UI / 查询 API(9090 被 mini-infra 的 mihomo/clash API 占,对外改 9091;容器内仍 9090) |
 | Loki | 3100 | HTTP API + OTLP 日志摄入(`/otlp`) |
 | Tempo | 3200 | 查询 API |
 | Collector | 4317 / 4318 | OTLP gRPC / HTTP 入口(跨机信号源推这里) |
diff --git a/deploy/infra/observability/docker-compose.yml b/deploy/infra/observability/docker-compose.yml
index 720e9558..f915f441 100644
--- a/deploy/infra/observability/docker-compose.yml
+++ b/deploy/infra/observability/docker-compose.yml
@@ -21,7 +21,7 @@
 #    ragflow=9380-9381 / postgres=5433 / minio=9000-9001 / mysql=3306 / redis=6379 /
 #    nacos=8848 / rocketmq=9876,10911 / nginx=80,443 / infinity=23817,23820):
 #      Grafana    → 3002   (3000/3001 已占,绝不用默认 3000)
-#      Prometheus → 9090
+#      Prometheus → 9091   (宿主;9090 被 mini-infra 的 mihomo/clash API 占,容器内仍 9090)
 #      Loki       → 3100
 #      Tempo      → 3200   (query API)
 #      Collector  → 4317(gRPC OTLP)/ 4318(HTTP OTLP)/ 13133(健康探针)
@@ -70,7 +70,7 @@ services:
   # 收 OTLP(跨机经 Tailscale 推来)→ 脱敏 + 尾部采样 + 批量 → 分发三库。
   # 脱敏是进库前最后一道安全红线(手机号/token 打码)。健康探针在 13133。
   otel-collector:
-    image: otel/opentelemetry-collector-contrib:0.116.0
+    image: otel/opentelemetry-collector-contrib:0.155.0   # 版本几经周折:0.116.0 在 daocloud mirror 的镜像缺 binary(exec no such file、force 重下同 digest 仍坏);降 0.114.0 binary 好但 redaction 不认 blocked_key_patterns/redact_all_types(脱敏红线要键名屏蔽);0.155.0 binary 完好且 redaction 字段最全、向后兼容本配置
     container_name: infra-otelcol
     restart: unless-stopped
     networks: [infra-shared]
@@ -108,7 +108,7 @@ services:
       - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
       - prometheus-data:/prometheus
     ports:
-      - "9090:9090"
+      - "9091:9090"     # 宿主 9091(9090 被 mini-infra 的 mihomo/clash API 占,对外改 9091;容器内仍 9090,Grafana 走 prometheus:9090 不受影响)
     mem_limit: 1g
     cpus: 0.75
     cpu_shares: 512
diff --git a/deploy/infra/observability/health-check.sh b/deploy/infra/observability/health-check.sh
index be534b3c..0e286d1e 100755
--- a/deploy/infra/observability/health-check.sh
+++ b/deploy/infra/observability/health-check.sh
@@ -13,7 +13,7 @@
 #
 # 各件探的就绪端点:
 #   Collector  :13133 /            health_check extension(就绪返 200)
-#   Prometheus :9090  /-/healthy   自身健康
+#   Prometheus :9091  /-/healthy   自身健康(宿主 9091→容器 9090;9090 被 mihomo/clash 占)
 #   Tempo      :3200  /ready       就绪(未就绪期返 503,就绪后 200)
 #   Loki       :3100  /ready       就绪(未就绪期返 503,就绪后 200)
 #   Grafana    :3002  /api/health  自身健康(DB/插件就绪返 200)
@@ -28,7 +28,7 @@ MAX_TIME="${MAX_TIME:-8}"
 # 探针清单:名称|URL。逐个探,记录结果。
 CHECKS=(
   "Collector|http://${HOST}:13133/"
-  "Prometheus|http://${HOST}:9090/-/healthy"
+  "Prometheus|http://${HOST}:9091/-/healthy"
   "Tempo|http://${HOST}:3200/ready"
   "Loki|http://${HOST}:3100/ready"
   "Grafana|http://${HOST}:3002/api/health"
diff --git a/deploy/infra/observability/loki-config.yaml b/deploy/infra/observability/loki-config.yaml
index 23530ebe..3d10d26f 100644
--- a/deploy/infra/observability/loki-config.yaml
+++ b/deploy/infra/observability/loki-config.yaml
@@ -2,7 +2,9 @@
 # Loki 配置 —— 日志存储 · 单进程 monolithic · 后端 = MinIO(obs-loki 桶)
 # 设计 §4/§6:只收 WARN/ERROR(在源头控级别),chunks 落 MinIO、index 落本地卷。
 # Collector 用 otlphttp 发到 :3100/otlp(Loki 3.x 原生 OTLP 摄入端点)。
-# ${MINIO_*} 由启动参数 -config.expand-env=true 从容器环境变量展开(compose 注入)。
+# MINIO_ACCESS_KEY / MINIO_SECRET_KEY 由启动参数 -config.expand-env=true 从容器环境变量展开(compose 注入)。
+# 坑:Loki 的 expand-env 会连注释一起扫描、且严格校验美元花括号变量引用;变量名里出现通配符星号
+#     会报 "missing closing brace" 起不来(Tempo 同款 expand-env、同坑),故本注释一律不写该符号形式。
 # =============================================================================
 
 # 内网单机、不启多租户鉴权(鉴权由所在网络与 nginx 边界兜)。
diff --git a/deploy/infra/observability/tempo.yaml b/deploy/infra/observability/tempo.yaml
index 434f7eb9..c5d0daed 100644
--- a/deploy/infra/observability/tempo.yaml
+++ b/deploy/infra/observability/tempo.yaml
@@ -2,7 +2,9 @@
 # Tempo 配置 —— 追踪存储 · 单进程 monolithic · 后端 = MinIO(obs-tempo 桶)
 # 设计 §7:选 Tempo(同 Grafana 体系、三联下钻、对象存储内存友好)。
 # 收 Collector 转发的 OTLP;blocks 落 MinIO、WAL 落本地卷 /var/tempo。
-# ${MINIO_*} 由启动参数 -config.expand-env=true 从容器环境变量展开(compose 注入)。
+# MINIO_ACCESS_KEY / MINIO_SECRET_KEY 由 -config.expand-env=true 从容器环境变量展开(compose 注入)。
+# 坑:注释里勿写带星号的美元花括号形式 —— Tempo/Loki 的 expand-env 会连注释一起严格校验,
+#     变量名含通配符星号会报 missing closing brace 起不来。
 # =============================================================================
 
 # 允许 Grafana 经 HTTP 流式拉取查询结果(TraceQL 搜索用)。