feat(m8): P2 pgvector + Ollama 向量化与语义检索

- PostgreSQL 切换 pgvector/pgvector:pg17 镜像;迁移 000024 建 vector 扩展、
  knowledge_chunks.embedding vector(1024) + HNSW 余弦索引,retrieval_mode 放宽三态
- OllamaEmbedder 本地 bge-m3 批量嵌入,404 惰性 pull 重试,维度/超时校验,可整体关闭
- SemanticRetriever/HybridRetriever + NewRetriever 按 retrieval_mode 分发,缺 embedder 回退 FTS
- 文档入库同步批量向量化;Ollama 故障降级入库 + embedding_failed 事件
- 修复 pgx CopyFrom 对 vector 列二进制编码误读:COPY 基础列后同事务 unnest 批量回填
- 修复降级路径 embeddings=nil 索引越界 panic(Add 与 Reprocess)
- 知识库列表 vectorized_chunk_count + 前端三态检索模式选择与向量化覆盖率
- 单测 embedder/retrievers + 集成 TestKnowledgeVectorLifecycle 全绿

Co-Authored-By: Claude <noreply@anthropic.com>

docs/adr/0001-baseline-storage.md

@@ -1,7 +1,7 @@
 # ADR-0001：基线存储只使用 PostgreSQL 与 Redis
 
-状态：已接受  
-日期：2026-08-10
+状态：已被 [ADR-0002](./0002-vector-storage-and-object-store.md) 取代  
+日期：2026-08-10（2026-08-12 修订：对象存储与向量化基础设施入基线，见 ADR-0002）
 
 ## 决策
 

docs/adr/0002-vector-storage-and-object-store.md

@@ -0,0 +1,27 @@
+# ADR-0002：对象存储与向量化基础设施入基线
+
+状态：已接受  
+日期：2026-08-12  
+取代/修订：[ADR-0001](./0001-baseline-storage.md)
+
+## 决策
+
+M8 起把 MinIO（对象存储）与 pgvector + 本地 Ollama（向量化）纳入基线，但它们都**不作为启动依赖**。
+
+- **MinIO 自托管**：上传/下载全部经 `gateway-api` 代理，MinIO 不暴露主机端口；`gateway.file_objects` 元数据行以 PostgreSQL 为权威，对象未就绪时上传得到明确报错，服务不崩溃。
+- **pgvector + Ollama**：PostgreSQL 镜像切换为 `pgvector/pgvector:pg17`（数据卷兼容），`knowledge_chunks.embedding vector(1024)` 由本地 Ollama 容器（默认 `bge-m3`）产生；Ollama 未就绪时知识库入库降级（embedding 置 NULL + `knowledge_document.embedding_failed` 事件），检索自动回退纯 FTS。
+- **不引入 pgvector-go / S3 客户端到领域层**：向量以 `$1::vector` 字面量直传；对象存储经 `internal/platform/storage` 适配层隔离，领域层只依赖接口。
+- **ClickHouse 仍不属于基线**：审计与统计继续存放 PostgreSQL。
+
+## 动机
+
+- 知识库需要向量化语义召回（旗舰版"外部文档导入、自动切分、向量化、语义匹配召回"），并作为 M10 记忆管理、M12 语义输出的依赖基座。
+- 门户个人文件仓库与管理端文件管理需要对象存储；自托管 MinIO 保证完全内网离线。
+- 本地 Ollama 生成嵌入避免外发文本到公网 embedding API，多语言模型 bge-m3 与中文检索目标匹配。
+
+## 影响
+
+- 部署编排新增 `minio`、`ollama` 两个 stateful 服务与 `minio-data`、`ollama-models` 卷；nginx `client_max_body_size` 提到 256 MiB 盖过 128 MiB 上传上限。
+- 运维需备份 `minio-data`、`ollama-models` 卷；Ollama 首次拉取 bge-m3 约 1.2 GiB，`EMBEDDINGS_ENABLED=false` 可关闭。
+- `EMBEDDING_DIM` 必须与 `vector(1024)` 一致，配置校验拦截不符。
+- ADR-0001 第 4 条（MinIO/S3 不在基线）与"知识库只保存纯文本"不再成立，本 ADR 取代。

docs/rewrite-progress.md

@@ -122,3 +122,14 @@
 - Compose（dev + production）新增 `minio` 服务与 `minio-data` 卷；nginx `client_max_body_size` 32m→256m 盖过 128 MiB 上传上限；`.env.example` / `production.env.example` 补 `S3_*`。
 - 端到端验证：上传→列表→下载往返一致→删除后桶无孤儿；admin 读 portal 文件 404；`TestFileObjectLifecycle` 集成测试连真实 MinIO+PostgreSQL 通过；`go build ./...`、`go vet ./...`、全量单测通过。
 - 管理端"文件管理"与门户端"文件仓库"菜单由服务端动态菜单下发。
+
+## 已完成：M8 基础设施层（P2 向量化与语义检索）
+
+- PostgreSQL 换 `pgvector/pgvector:pg17` 镜像（数据卷兼容，先备份再切换）；迁移 `000024` `CREATE EXTENSION vector`、`knowledge_chunks.embedding vector(1024)` 列 + HNSW 余弦索引，并把 `retrieval_mode` CHECK 放宽为 `('postgres_fts','vector','hybrid')` 三态。
+- 本地 Ollama（`bge-m3`，1024 维）生成嵌入，Compose 新增 `ollama` 服务与 `ollama-models` 卷；`OllamaEmbedder` 批量调 `/api/embed`，首见 404 惰性 `/api/pull` 重试一次，按批校验维度，超时 `EMBEDDING_TIMEOUT`；`EMBEDDINGS_ENABLED=false` 可整体关闭。
+- `SemanticRetriever`（`embedding <=> $1::vector` 余弦距离 + `embedding IS NOT NULL` 过滤）与 `HybridRetriever`（FTS + 语义按 chunk 去重融合）实现；`NewRetriever(service, embedder)` 按知识库 `retrieval_mode` 分发，embedder 为 nil 时自动回退纯 FTS（不因缺少 Ollama 而报错）。
+- 文档入库/重新分块时在 vector/hybrid 模式下同步批量计算向量（每文档一次 `/api/embed` 收数组）；Ollama 故障时优雅降级：文档照常入库、embedding 置 NULL，并在事务内发 `knowledge_document.embedding_failed` 事件。
+- 踩坑并修复：pgx v5 `CopyFrom` 对未知 OID（vector）列走二进制编码，字面量随 COPY 上传会被 `vector_recv` 误读为维度数而报 `vector cannot have more than 16000 dimensions`；改为 COPY 仅基础列，随后在同一事务内用 `UPDATE ... FROM unnest($1::uuid[], $2::text[])` 批量回填向量，避免 2 MiB 文档上千条逐条 INSERT。
+- 知识库列表新增 `vectorized_chunk_count`（`count(c.embedding)`），管理端展示"已向量化切片/总切片"覆盖率；创建/编辑知识库可三态选择检索模式，未向量化分块需重新处理才被语义召回。
+- `EMBEDDINGS_*` 配置（`OLLAMA_BASE_URL` 默认 `http://ollama:11434`、`EMBEDDING_MODEL` bge-m3、`EMBEDDING_DIM` 须与 `vector(1024)` 一致、批大小、超时）写入两个 `.env.example` 与 compose anchor。
+- 单测 `embedder_test.go`/`retrievers_test.go`（httptest 假 Ollama：批量切分、维度不符、404→pull→重试、降级分发）与集成 `TestKnowledgeVectorLifecycle`（真 pgvector+Ollama：导入即向量化、语义命中、embedder 失败时入库 + `embedding_failed` 事件）全部通过；`go build ./...`、`go vet ./...` 通过。

docs/旗舰版需求规划与完成情况.md

@@ -3,7 +3,7 @@
 - **报告日期**: 2026-08-12
 - **工程**: AI Gateway 全量 Go 重构(替代原 Python/FastAPI 网关)
 - **活跃工作树**: `/home/ben/ai-gateway-src/ai-gateway-go-deploy-0.10.0`
-- **当前版本**: 0.10.0(Go 1.26,PostgreSQL 17 + 双 Redis,22 个迁移)
+- **当前版本**: 0.10.0(Go 1.26,PostgreSQL 17+pgvector + 双 Redis + MinIO + Ollama,24 个迁移)
 
 ---
 
@@ -12,11 +12,11 @@
 | 项 | 状态 |
 |---|---|
 | 部署形态 | Docker Compose(项目名 `deploy`),gateway-api `:8080` / admin-web `:8081` / portal-web `:8082` |
-| 数据层 | PostgreSQL 17(权威配置 + 审计分区)+ critical/cache 双 Redis;22 个迁移已应用 |
-| 迁移 | `000001`…`000022`(含旗舰版资源市场 `000022_resource_marketplace.sql`) |
-| 验证 | `go build ./...`、`go vet`、全套单测、资源市场集成测试连真实库 **全部通过** |
+| 数据层 | PostgreSQL 17 + pgvector(权威配置 + 审计分区 + 向量列)+ critical/cache 双 Redis + MinIO + Ollama;24 个迁移已应用 |
+| 迁移 | `000001`…`000024`(含资源市场 `000022`、MinIO `000023`、pgvector `000024`) |
+| 验证 | `go build ./...`、`go vet`、全套单测、资源市场/文件管理集成测试连真实库 **全部通过** |
 | 前端 | Art Design Pro 管理端 + 门户端,已构建进镜像并运行 |
-| 版本控制 | 无 git(目录无 `.git`),靠目录快照;建议尽快接入版本控制 |
+| 版本控制 | git(remote `origin`=Gitea `superidou/ai-gateway-go`),每次改动 commit + push |
 
 ---
 
@@ -77,7 +77,7 @@ Prompt 分类/模板/不可变版本/必填校验;知识库(2 MiB 有界正文
 | 模型管理 | 对接本地模型(Ollama/vLLM) | 不支持 | ✓ | ✓ | ✅ 走 OpenAI 兼容通用 provider |
 | 模型管理 | 不同大模型 Token 配额、使用量统计 | 不支持 | ✓ | ✓ | ✅ quota + usage 聚合 |
 | 模型管理 | 大模型使用权限分级管控(用户/角色) | ✓ | ✓ | ✓ | ✅ RBAC scope |
-| 知识库 | 外部文档导入、自动切分、向量化、语义匹配召回 | — | ✓ | ✓ | ⚠️ 导入/切分/检索 ✅;向量化+语义匹配 ❌(现为 FTS+中文分词) |
+| 知识库 | 外部文档导入、自动切分、向量化、语义匹配召回 | — | ✓ | ✓ | ✅ M8 P2:pgvector + 本地 Ollama bge-m3,vector/hybrid 三态,导入即同步向量化(失败自动降级 FTS) |
 | 记忆管理 | 记忆集合:个人/部门/全局多层记忆,提炼与语义匹配召回 | — | ✓ | ✓ | ❌ |
 | 记忆管理 | 根据调用自动裁剪衰减片段 | — | ✓ | ✓ | ❌ |
 | 记忆管理 | 记忆授权:提炼内容/沉淀经验授权给其他用户 | — | ✓ | ✓ | ❌ |
@@ -134,8 +134,8 @@ Prompt 分类/模板/不可变版本/必填校验;知识库(2 MiB 有界正文
 
 ## 四、差距汇总
 
-- **完全未实现(❌,约 18 项)**:AI 助手、收藏、数据报表/企业报表、配置管理(env 注入)、智能体管理三项(节点/LLMTrace/会话)、记忆管理三项、渠道管理全项、多租户、供应链安全扫描、站内消息、完整审批流、License、定时任务全项、个人渠道、个人安全策略、ARM64。(M8 已落地:文件管理/MinIO、个人文件仓库)
-- **部分覆盖需补齐(⚠️,约 10 项)**:平台概览看板、知识库向量化语义召回、资源/渠道审批、工具输出脱敏与大模型回答拦截替换、工具命令审批与工具限流、集群部署方案、站内消息/审批待办/任务结果、数字员工会话入口、资源权限等级三档、全类型权限申请。
+- **完全未实现(❌,约 16 项)**:AI 助手、收藏、数据报表/企业报表、配置管理(env 注入)、智能体管理三项(节点/LLMTrace/会话)、记忆管理三项、渠道管理全项、多租户、供应链安全扫描、完整审批流、License、定时任务全项、个人渠道、个人安全策略、ARM64。(M8 已落地:文件管理/MinIO、个人文件仓库、知识库向量化语义召回)
+- **部分覆盖需补齐(⚠️,约 9 项)**:平台概览看板、资源/渠道审批、工具输出脱敏与大模型回答拦截替换、工具命令审批与工具限流、集群部署方案、站内消息/审批待办/任务结果、数字员工会话入口、资源权限等级三档、全类型权限申请。
 
 ---
 
@@ -143,7 +143,7 @@ Prompt 分类/模板/不可变版本/必填校验;知识库(2 MiB 有界正文
 
 | 里程碑 | 内容 | 依赖 |
 |---|---|---|
-| **M8 基础设施层** | 对象存储(MinIO)、向量化(pgvector)、定时任务调度器、站内消息 | — |
+| **M8 基础设施层** | 对象存储(MinIO)、向量化(pgvector)、定时任务调度器、站内消息 | —(P1 MinIO/P2 pgvector+Ollama 已完成,待 P3 调度器 + P4 站内信) |
 | **M9 智能体与可观测** | LLMTrace、智能体会话、智能体节点(监控/节点池/路由)、AI 助手 | M8 |
 | **M10 记忆管理** | 多层记忆集合、语义召回、裁剪衰减、记忆授权 | M8(pgvector) |
 | **M11 渠道与审批** | 渠道管理(企业微信/个人微信/钉钉/飞书)、个人渠道、完整审批流、资源权限等级 | M8 |
@@ -156,10 +156,10 @@ Prompt 分类/模板/不可变版本/必填校验;知识库(2 MiB 有界正文
 
 ## 六、验证情况(当前基线)
 
-- `go build ./...` ✅、`go vet ./internal/workbench/` ✅
-- 全套单测(全部包)✅;资源市场单测(含 MCP 客户端)✅
-- 集成测试 `TestMarketplaceLifecycle`、`TestWorkbenchPostgreSQLLifecycle` 连真实 PostgreSQL ✅
-- 部署冒烟:healthz/readyz ✅、admin :8081 / portal :8082 302 ✅、22 迁移应用 ✅
+- `go build ./...` ✅、`go vet ./...` ✅
+- 全套单测(全部包)✅;资源市场/文件/向量化单测(embedder/retriever)✅
+- 集成测试 `TestMarketplaceLifecycle`、`TestWorkbenchPostgreSQLLifecycle`、`TestFileObjectLifecycle`、`TestKnowledgeVectorLifecycle`(pgvector+Ollama:导入即向量化、语义命中、embedder 失败降级)连真实 PostgreSQL/MinIO/Ollama ✅
+- 部署冒烟:healthz/readyz ✅、admin :8081 / portal :8082 302 ✅、24 迁移应用 ✅、vector 模式知识库导入即向量化 + 语义检索命中 ✅
 
 ## 七、部署与已知坑