.env.example

@@ -23,6 +23,11 @@ POSTGRES_PASSWORD=
 # 图数据库密码（Neo4j，知识图谱）。
 NEO4J_PASSWORD=
 
+# 全文(bleve)索引落盘目录。留空则用相对路径 .data/bleve —— 相对的是 mcp-go 的**启动目录**，
+# 从仓库根起和从 sundynix-mcp-go/ 起会写出两份互不相干的索引（本地排查全文召回时最容易被这个坑到）。
+# 本地开发建议显式写成绝对路径；容器部署已在 compose 里固定为 /data/bleve + 持久卷。
+BLEVE_PATH=
+
 # ── 必填：管理员 ─────────────────────────────────────────────
 # 管理员用户 ID 白名单（逗号分隔）。生产模式下只有这些用户能进 /admin 控制台。
 # 首次部署：先留空起服务 → 注册第一个账号 → 从返回的 user id 填进来 → 重启 gateway。

deploy/132-app/docker-compose.yml

@@ -72,6 +72,11 @@ services:
       MINIO_BUCKET: ${MINIO_BUCKET:-sundynix-docs}
       SUNDYNIX_SECRET_KEY: ${SUNDYNIX_SECRET_KEY:?}
       OTEL_EXPORTER_OTLP_ENDPOINT: http://192.168.100.128:4318
+      # 全文(bleve)索引落盘位置。不设则相对 CWD，写进容器可写层 → 每次发版重建容器就清零，
+      # 而混合检索只是静默少一路召回、不报错，很难发现。必须配合下面的持久卷。
+      BLEVE_PATH: /data/bleve
+    volumes:
+      - mcp-go-data:/data
 
   mcp-py:
     build: { context: ../../sundynix-mcp-py, dockerfile: Dockerfile }
@@ -83,3 +88,8 @@ services:
     # Docker 暴露给该服务(可逃逸)；不需要代码执行工具可注释掉这两行。mcp-py 无对外端口。
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock
+
+# 全文索引持久化：随容器重建保留（向量在 Milvus、图谱在 Neo4j，都在 128；
+# 只有 bleve 是跟着 mcp-go 走的本地索引，唯独它需要这个卷）。
+volumes:
+  mcp-go-data:

docker-compose.prod.yml

@@ -71,9 +71,14 @@ services:
       MINIO_BUCKET: sundynix-docs
       SUNDYNIX_SECRET_KEY: *secret-key
       OTEL_EXPORTER_OTLP_ENDPOINT: http://jaeger:4318
+      # 全文(bleve)索引落盘位置。不设则相对 CWD，写进容器可写层 → 每次重建容器就清零，
+      # 而混合检索只是静默少一路召回、不报错，很难发现。必须配合下面的持久卷。
+      BLEVE_PATH: /data/bleve
     depends_on:
       nats: { condition: service_started }
       milvus: { condition: service_healthy }   # mcp-go 须在 Milvus 后起，否则工具 no responders
+    volumes:
+      - mcp_go_data:/data
 
   mcp-py:
     build: { context: sundynix-mcp-py, dockerfile: Dockerfile }
@@ -181,3 +186,4 @@ volumes:
   minio_data:
   milvus_data:
   neo4j_data:
+  mcp_go_data:

sundynix-mcp-go/Dockerfile

@@ -16,7 +16,12 @@ RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/mcp-go ./cmd/serve
 # alpine 运行（内网 runner 连不上 gcr.io；二进制 CGO_ENABLED=0 全静态，ca-certs 供 TLS）。
 FROM alpine:3.20
 RUN sed -i 's#dl-cdn.alpinelinux.org#mirrors.aliyun.com#g' /etc/apk/repositories \
-    && apk add --no-cache ca-certificates tzdata && adduser -D -u 10001 app
+    && apk add --no-cache ca-certificates tzdata && adduser -D -u 10001 app \
+    # /data 存 bleve 全文索引：必须由 app 拥有（进程非 root），且 compose 要挂持久卷。
+    # 没有它的话 BLEVE_PATH 默认相对 CWD(=/)，uid 10001 在 / 下建不了目录 → 静默退回
+    # 内存索引，全文路每次重启清零，而混合检索只会少一路召回、不报错。
+    && mkdir -p /data && chown app:app /data
 USER app
+WORKDIR /data
 COPY --from=build /out/mcp-go /mcp-go
 ENTRYPOINT ["/mcp-go"]