From f47634e104f0eb1d7b6a1bf51ccc8c9d134e1d7e Mon Sep 17 00:00:00 2001 From: d-robotics Date: Wed, 2 Sep 2026 19:41:13 +0800 Subject: [PATCH] docs: plan public knowledge cluster delivery --- docs/api/API_CONTRACT.md | 9 ++ docs/api/MCP_CONTRACT.md | 7 ++ docs/architecture/ADR.md | 11 ++ docs/architecture/ARCHITECTURE.md | 24 ++++ docs/demo/DEMO_SCOPE.md | 69 +++++++---- docs/development/DEFINITION_OF_DONE.md | 7 ++ docs/plans/ASYNC_INGESTION_MCP_PLAN.md | 32 ++++-- docs/plans/PROGRESS.md | 26 ++++- docs/plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md | 120 ++++++++++++++++++++ docs/plans/TASKS.md | 17 ++- docs/plans/V1_EXECUTION_PLAN.md | 25 ++-- docs/product/PRD.md | 15 +++ 12 files changed, 316 insertions(+), 46 deletions(-) create mode 100644 docs/plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md diff --git a/docs/api/API_CONTRACT.md b/docs/api/API_CONTRACT.md index 743d756..47bf703 100644 --- a/docs/api/API_CONTRACT.md +++ b/docs/api/API_CONTRACT.md @@ -63,6 +63,15 @@ DEMO-010 提供 `/admin/upload`、`/admin/documents` 和 `/admin/search` 三个 `/admin` 默认展示上传页。它们是同源静态页面,不是新增业务 API,也不改变上述公开 REST 契约;所有业务操作仍调用 `/api/v1`。 +## 当前公共知识库部署边界(PLAN-002) + +当前阶段所有 Document 属于同一个公共知识可见域,不新增用户、知识库或 ACL 字段,也不把 +这些完整未实现能力伪装为默认放行。Admin 写接口只允许部署在企业受控网络或统一接入网关后; +Ingress 是否进一步认证属于部署配置,但前端隐藏按钮或隐藏路由不构成安全控制。 + +集群重启、扩缩容和滚动部署不得改变本契约或要求浏览器重新注入 Provider 配置。数据库、BOS、 +模型与队列凭据由服务端 Secret 提供,任何 API 响应都不得返回这些值。 + ## Planned async ingestion contract(DEMO-015/016,尚未实现) | Method | Path | 行为 | diff --git a/docs/api/MCP_CONTRACT.md b/docs/api/MCP_CONTRACT.md index 6cc0185..7734e7e 100644 --- a/docs/api/MCP_CONTRACT.md +++ b/docs/api/MCP_CONTRACT.md @@ -42,3 +42,10 @@ ACL 或用户委托授权。 公开错误边界:缺失/无效 Token 为 HTTP `401`,scope 不足为 `403`;Tool 参数不合法返回 MCP 参数错误;检索运行失败只返回 `knowledge search failed`。Host/Origin allowlist 默认只允许 本机,远程部署必须显式注入公开域名。 + +## 当前公共知识库部署边界(PLAN-002) + +集群阶段仍只暴露只读 `search_knowledge`,并为 WorkBuddy 配置稳定的 HTTPS MCP 地址。 +Credential 由 Kubernetes Secret 在服务端运行时注入,客户端只保存管理员分发的最小 +`knowledge:search` Token;Pod 重启或滚动升级不得要求重新生成配置。公共知识域不等于匿名 +访问或超级管理员身份,未来引入非公共知识前必须升级为用户委托身份与 ACL-aware Search。 diff --git a/docs/architecture/ADR.md b/docs/architecture/ADR.md index 8abd9bb..80b6c99 100644 --- a/docs/architecture/ADR.md +++ b/docs/architecture/ADR.md @@ -25,6 +25,17 @@ canonical Chunk 重建的检索行。共用数据库实例不改变两类数据 `VECTOR_INDEX(... pre_filter)` 产生 `VECTOR INDEX ADAPTIVE SCAN (PRE-FILTER)`;版本下限与 运行检查据此调整为 4.3.5.4。生产升级和重新验收仍由运维流程控制。 +## Public knowledge delivery boundary + +PLAN-002 将当前交付阶段限定为企业受控网络内的单一公共知识可见域,并加入 Kubernetes/Helm +集群交付任务。这是部署范围和实施顺序调整,不是新的架构选型:继续采用 ADR-002 的模块化 +单体 API、独立 Worker 和 MCP Gateway,以及架构既定的 Celery/RabbitMQ;OceanBase/BOS +边界继续遵循 ADR-012。 + +ADR-007 仍为 Accepted。当前阶段只是延后用户/组/角色和 Document ACL;开始接收任何非公共 +知识前,必须先实现 Permission Resolver 和检索前/检索中 ACL 下推。公共知识库也不等于匿名 +公网开放,Admin 写操作只允许经受控网络或统一接入网关访问,MCP 使用最小只读服务身份。 + The migration retains the Demo's Dense Top20 → Reranker Top5 behavior and current lightweight Parser scope. Top50 retrieval, distance thresholds, dual-query RRF, Marker/Pandoc and LLM-derived index content require separate product and evaluation decisions. diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md index 48bb3eb..db41147 100644 --- a/docs/architecture/ARCHITECTURE.md +++ b/docs/architecture/ARCHITECTURE.md @@ -202,6 +202,11 @@ Vector/Sparse rows 历史。清理失败时 Job 终止,不能在未知状态继续执行。Job 通过数据库状态、唯一有效 Attempt 和幂等键避免重复投递产生并发执行;具体队列实现保持可替换,不进入业务服务接口。 +公共知识库集群交付阶段由 Celery/RabbitMQ 作为首个生产执行器。API 只调用队列执行器抽象, +Celery task 只负责恢复应用上下文并调用 Ingestion Application Service;重试分类、Attempt 状态、 +清理顺序和业务幂等仍由应用层持有。Broker 消息不是 Job 的 source of truth,Worker 重启或消息 +重复投递必须以 OceanBase 中的持久化 Job/Attempt 状态收敛。 + --- ### 4.3 文档结构与 Chunk @@ -732,6 +737,25 @@ Observability 未来根据负载再拆服务。 +### 16.1 当前公共知识库集群交付基线 + +PLAN-002 将当前交付范围收敛为企业受控网络内的单一公共知识可见域。该范围不重开 ADR-007: +所有现有文档共享同一可见性,因而当前检索不执行事后 ACL 过滤;接收任何非公共知识前,必须 +先实现 Permission Resolver 和数据库/向量检索前置过滤。Admin 写接口不得直接暴露到匿名公网, +MCP 使用运行时 Secret 注入的最小 `knowledge:search` 服务身份。 + +集群中 API/Admin、MCP Gateway 和 Async Worker 分别部署并独立扩缩容,业务核心继续保持模块化 +单体。当前 Parser 及云端 Embedding/Reranker 不需要 GPU Worker,因此它不进入最小交付,但角色 +边界保留。OceanBase、BOS 和 AI Provider 使用外部服务;RabbitMQ 默认使用外部地址,可为开发/ +演示显式启用 Chart 依赖。 + +Kubernetes/Helm 必须提供:生产镜像、`existingSecret`、串行 Migration Job、Ingress/TLS、 +readiness/liveness、资源限制、非 root 与只读根文件系统、多副本和滚动更新。仓库的一键入口只 +编排已有集群和外部服务,不创建云账号或把凭据写入 Values、镜像、命令行及日志。现有 +`docker-compose.dev.yml` 包含已被 ADR-012 取代的 PostgreSQL/MinIO 假设,只能视为待清理的 +本地开发资产,不能作为集群模板。详细依赖和验收见 +[`PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md`](../plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md)。 + --- ## 17. V1 验收重点 diff --git a/docs/demo/DEMO_SCOPE.md b/docs/demo/DEMO_SCOPE.md index 3e07b43..9f77da5 100644 --- a/docs/demo/DEMO_SCOPE.md +++ b/docs/demo/DEMO_SCOPE.md @@ -92,7 +92,7 @@ Demo 阶段优先简单实现,不引入不必要的基础设施。 | Vector DB | OceanBase Vector | 当前默认,通过 `VectorStore` 隔离 SDK,不做多数据库运行时切换 | | Reranker | `bce-reranker-base` | 延续当前可调用的千帆 Reranker,Demo 中保留 | | Frontend | 简单 React/Vue 或 FastAPI HTML | 以最小可用为目标 | -| Deployment | 本地 / 单机 Docker | 暂不考虑 K8s | +| Deployment | Kubernetes/Helm | PLAN-002 起面向企业受控网络交付;本地模式仅用于开发测试 | --- @@ -335,7 +335,8 @@ Search Service 或 `/api/v1/search`,用于验证标准 MCP、identity 边界 将现有同步入库流水线放入持久化 Ingestion Job。可重试失败自动执行有界重试;每次重试前 删除旧解析产物、Chunk、索引状态和向量数据,但保留不可变原始文件、Document 和 Attempt -历史。清理失败时终止,不在未知脏状态继续执行。 +历史。清理失败时终止,不在未知脏状态继续执行。通过执行器抽象接入 Celery/RabbitMQ,使 +API 与 Worker 可独立部署,并以持久化状态处理 Worker 重启和重复消息。 ### DEMO-016 批量异步上传 @@ -361,12 +362,13 @@ Admin Console 状态展示。批次内文件相互隔离,不包含目录上传 - 多 Embedding Benchmark Platform; - 多 Vector DB; - 动态 Provider; -- RabbitMQ / Celery; -- Kubernetes; -- 高可用; - 灾备; - 完整 Observability。 +用户/权限隔离属于完整 V1 后置能力,不因“公共知识库”而取消;本阶段所有已接收知识共享一个 +可见域,且仅部署在企业受控网络或统一接入网关后。RabbitMQ/Celery 与最小 Kubernetes 可用性 +已由 PLAN-002 纳入当前交付,跨区域容灾和完整平台级高可用仍不在范围内。 + --- ## 10. Demo Task 清单 @@ -387,12 +389,17 @@ DEMO-014 地瓜机器人品牌化前端优化(用户新增) DEMO-015 异步入库 Job + 自动重试前清理(用户新增) DEMO-016 批量异步上传 + 状态展示(用户新增) ARCH-001~006 Provider 架构迁移与真实验收 +PLAN-002 公共知识库集群交付规划(已完成) +DEPLOY-001 API/Admin、MCP Gateway、Async Worker 生产镜像 +DEPLOY-002 Kubernetes/Helm 一键部署 +DEPLOY-003 可用性、滚动升级和远程 WorkBuddy 验收 ``` 实施状态(2026-09-02):`DEMO-001~DEMO-010`、用户新增的 `DEMO-014` 与 `ARCH-001~ARCH-006` 均已完成并通过当前 Scope 的闭环验收。`PLAN-001` 已完成现状审计和 -任务拆分;`DEMO-012` 已完成,`DEMO-015`、`DEMO-016` 已批准并按顺序实施。`DEMO-011` 和 -`DEMO-013` 仍为可选项,不因本状态记录自动进入范围。 +任务拆分;`DEMO-012` 已完成。`PLAN-002` 已将公共知识库集群交付纳入范围,后续严格按 +`DEMO-015`、`DEMO-016`、`DEPLOY-001~003` 顺序实施。`DEMO-011` 和 `DEMO-013` 仍为 +可选项,不因本状态记录自动进入范围。 可选: @@ -404,13 +411,17 @@ DEMO-013 OCR / MinerU 已批准顺序: ```text -DEMO-012 MCP search_knowledge - → DEMO-015 Async Job + Retry Cleanup +PLAN-002 Public Knowledge Cluster Plan + → DEMO-015 Celery/RabbitMQ Async Job + Retry Cleanup → DEMO-016 Batch Async Upload + UI + → DEPLOY-001 Production Images + → DEPLOY-002 Kubernetes/Helm One-click Deploy + → DEPLOY-003 Availability + Remote Acceptance ``` 详细 Task 映射、依赖与验收边界见 -[`docs/plans/ASYNC_INGESTION_MCP_PLAN.md`](../plans/ASYNC_INGESTION_MCP_PLAN.md)。 +[`docs/plans/ASYNC_INGESTION_MCP_PLAN.md`](../plans/ASYNC_INGESTION_MCP_PLAN.md) 和 +[`docs/plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md`](../plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md)。 --- @@ -500,11 +511,13 @@ Demo 阶段不设严格生产指标。 ## 14. Codex 开发约束 -Codex 当前只能实现 `DEMO-001 ~ DEMO-010`、`DEMO-012`、`DEMO-014 ~ DEMO-016` 和已批准的 -`ARCH-001 ~ ARCH-006`。 -ARCH 迁移任务不授权实现下列被排除的完整 V1 能力。 +Codex 当前只能实现 `DEMO-001 ~ DEMO-010`、`DEMO-012`、`DEMO-014 ~ DEMO-016`、 +`ARCH-001 ~ ARCH-006`、`PLAN-001 ~ PLAN-002` 和 `DEPLOY-001 ~ DEPLOY-003`。 +PLAN-002 只授权实现 Celery/RabbitMQ 异步执行器与最小 Kubernetes/Helm 集群交付,不授权 +拆分额外微服务或扩大业务能力。 -除非明确要求,否则禁止提前实现权限、审计、Knowledge Compilation、多数据库、多模型平台、微服务、Kubernetes 和企业级 Job Queue。 +除非明确要求,否则禁止提前实现权限、审计、Knowledge Compilation、多数据库、多模型平台、 +额外微服务、跨区域容灾和完整 Observability 平台。 当本文件与完整 PRD 的实现优先级冲突时: @@ -533,10 +546,10 @@ docs/demo/DEMO_SCOPE.md > 完整 V1 PRD -只允许实现 DEMO-001 ~ DEMO-010 以及本文件明确列出的 ARCH-001 ~ ARCH-006。 -Provider 架构迁移任务按顺序完成后,再继续 DEMO-010。 +只允许实现本文件明确列出的 Demo、Architecture、Plan 与 Deploy Task,并且一次只执行一个 +Task。当前严格顺序为 DEMO-015 → DEMO-016 → DEPLOY-001 → DEPLOY-002 → DEPLOY-003。 -当前 Demo 的目标只有: +当前公共知识库阶段的业务目标保持为: Upload → Parse/Clean @@ -548,6 +561,14 @@ Upload → Source Result → Search UI +并补齐以下交付能力: + +Async Job / Retry Cleanup +→ Batch Async Upload +→ Production Images +→ Kubernetes/Helm One-click Deploy +→ Availability + Remote WorkBuddy Acceptance + 不要提前实现: - ACL @@ -557,9 +578,9 @@ Upload - Knowledge Compilation - Multi Vector Store - Embedding Benchmark Platform -- Celery/RabbitMQ -- Kubernetes -- 企业级高可用 +- 额外微服务 +- 跨区域容灾 +- 完整 Observability 平台 先不要修改代码。 @@ -568,7 +589,7 @@ Upload 1. 当前仓库状态; 2. 为完成 Demo 需要保留哪些现有结构; 3. 哪些完整 V1 设计可以暂时不实现; -4. DEMO-001 ~ DEMO-010 与 ARCH-001 ~ ARCH-006 的建议执行顺序; +4. 当前已批准 Task 的执行顺序; 5. 下一步应该实施的第一个 Task。 ``` @@ -585,6 +606,12 @@ Async Job + Retry Cleanup ↓ Batch Async Upload ↓ +Production Images + ↓ +Kubernetes/Helm One-click Deploy + ↓ +Availability + Remote WorkBuddy Acceptance + ↓ Hybrid Search ↓ OCR / Complex Parsing diff --git a/docs/development/DEFINITION_OF_DONE.md b/docs/development/DEFINITION_OF_DONE.md index cecf152..bcf9195 100644 --- a/docs/development/DEFINITION_OF_DONE.md +++ b/docs/development/DEFINITION_OF_DONE.md @@ -10,3 +10,10 @@ failure and configured limits. For MCP tasks, contract tests must cover tool discovery, identity propagation, authorization/error boundaries, REST/application-service parity, infrastructure redaction, and the explicitly targeted MCP client compatibility check. + +For cluster delivery tasks, completion also requires reproducible production images, Secret-only +sensitive configuration, serialized migration, readiness/liveness probes, resource and pod-security +defaults, idempotent Helm install/upgrade, rolling-restart verification, durable worker recovery, stable +HTTPS Admin/MCP endpoints, and remote WorkBuddy acceptance. Manifests, rendered output, logs and images +must be checked for credential leakage. Public-knowledge delivery does not complete or waive V1 +user/ACL tasks. diff --git a/docs/plans/ASYNC_INGESTION_MCP_PLAN.md b/docs/plans/ASYNC_INGESTION_MCP_PLAN.md index 1923515..175f43a 100644 --- a/docs/plans/ASYNC_INGESTION_MCP_PLAN.md +++ b/docs/plans/ASYNC_INGESTION_MCP_PLAN.md @@ -43,8 +43,13 @@ - 每次重新执行前,按顺序清理该 Document 的向量行、`ChunkIndexState`、Chunk 和解析产物,再从不可变原始文件重新处理; - 原始文件、Document 标识和审计所需的 Job/Attempt 历史不得被重试清理删除; - 任一清理步骤失败时禁止启动下一次尝试,并记录为终止失败,避免在未知脏状态上重复执行。 +- 通过执行器抽象接入 Celery/RabbitMQ,使 API 和 Worker 可独立部署;业务应用服务不得直接 + 依赖 Celery API,确保执行器仍可替换; +- Worker 重启、消息重复投递和确认超时必须保持持久化 Job 状态一致,不能产生双重有效 + Attempt 或重复派生数据。 -该 Task 只完成 Demo 入库所需的 Job/Retry 基线,不扩展到完整审计系统、Compilation、OCR、分布式高可用或通用企业级 Job 平台。 +该 Task 只完成公共知识库入库所需的 Job/Retry 与队列基线,不扩展到完整审计系统、 +Compilation、OCR、跨区域高可用或通用企业级 Job 平台。 ### DEMO-016:批量异步上传与状态展示(新增) @@ -62,19 +67,23 @@ ## 3. 实施顺序与依赖 ```text -DEMO-009 + ARCH-006 - └──→ DEMO-012 MCP search_knowledge +DEMO-009 + ARCH-006 → DEMO-012(已完成) -DEMO-003 → DEMO-004 → DEMO-005 → DEMO-006 - └──→ DEMO-015 Async Job + Retry Cleanup - └──→ DEMO-016 Batch Async Upload + UI +PLAN-002(已完成) + └──→ DEMO-003 → DEMO-004 → DEMO-005 → DEMO-006 + └──→ DEMO-015 Async Job + Celery/RabbitMQ + Retry Cleanup + └──→ DEMO-016 Batch Async Upload + UI + └──→ DEPLOY-001 → DEPLOY-002 → DEPLOY-003 ``` 推荐严格按以下顺序执行并逐项闭环: -1. `DEMO-012` +1. `PLAN-002`(已完成) 2. `DEMO-015` 3. `DEMO-016` +4. `DEPLOY-001` +5. `DEPLOY-002` +6. `DEPLOY-003` MCP 与异步入库没有代码级前置依赖,因此提高 MCP 优先级不会阻塞后续批量上传。`DEMO-016` 必须等待 `DEMO-015`,否则会把同步流水线简单并发放大,缺少可靠的状态、隔离和恢复边界。 @@ -94,6 +103,7 @@ MCP 与异步入库没有代码级前置依赖,因此提高 MCP 优先级不 - 第二次尝试开始前,旧解析产物、Chunk、索引状态和向量均已清理,原始源文件仍存在; - 永久错误不重试,达到次数上限后稳定进入 `failed`; - 并发或重复投递不会产生双重有效执行和重复派生数据。 +- RabbitMQ 消息确认超时或 Worker 重启后,Job 可恢复到终态且不会重复生成派生数据。 ### DEMO-016 @@ -104,6 +114,10 @@ MCP 与异步入库没有代码级前置依赖,因此提高 MCP 优先级不 ## 5. 非目标与 ADR 影响 -- 不把 RabbitMQ/Celery、Kubernetes、高可用或完整 Observability 纳入上述 Demo Task;具体执行器继续通过接口隔离,后续 V1 可替换。 +- PLAN-002 已把 Celery/RabbitMQ 纳入 `DEMO-015`,并以独立 `DEPLOY-*` Task 纳入最小 + Kubernetes、多副本和滚动升级能力;跨区域容灾、自动云资源编排和完整 Observability + 仍为非目标。 - 不改变 OceanBase/BOS canonical、向量索引可重建、原始文档不可变、Provider 抽象和 MCP 隐藏基础设施等 Accepted ADR。 -- 本次只是任务拆分、优先级和契约澄清,不需要新增或重开 Accepted ADR。 +- 公共知识库只是阶段性单一可见域;ADR-007 保持 Accepted,用户/ACL 实现后置且不得用全局 + Top-K 后过滤替代。 +- 本次任务拆分和交付边界不需要新增或重开 Accepted ADR。 diff --git a/docs/plans/PROGRESS.md b/docs/plans/PROGRESS.md index 4aad046..a2ad61c 100644 --- a/docs/plans/PROGRESS.md +++ b/docs/plans/PROGRESS.md @@ -1,13 +1,12 @@ # 项目进度 -当前阶段:Retrieval Demo 与品牌界面闭环完成 +当前阶段:公共知识库集群交付规划完成,准备实施异步入库 -已完成:DEMO-001~DEMO-010、DEMO-014、ARCH-001~ARCH-006 +已完成:DEMO-001~DEMO-010、DEMO-012、DEMO-014、ARCH-001~ARCH-006、PLAN-001~PLAN-002 进行中:无 阻塞:无 -下一任务:无。`docs/demo/DEMO_SCOPE.md` 当前批准的必做任务和 DEMO-014 已经完成;可选 -DEMO-011~013 或 V1 backlog 需在明确选定新 Task 后再开始。 +下一任务:`DEMO-015`。随后严格执行 `DEMO-016 → DEPLOY-001 → DEPLOY-002 → DEPLOY-003`。 Provider 架构迁移按 `ARCH-001 → ARCH-002 → ARCH-003 → ARCH-004 → ARCH-005 → ARCH-006` 执行并已完成。DEMO-010 在迁移闭环验收后实施,未扩大为完整 V1 Admin Console。 @@ -314,3 +313,22 @@ Provider 架构迁移按 `ARCH-001 → ARCH-002 → ARCH-003 → ARCH-004 → AR `DEMO-012` 约定的 WorkBuddy 客户端验收项闭环;公网 HTTPS 部署验证属于部署环境验收, 不阻塞本地 Demo Task 完成。 - 下一任务:`DEMO-015`。 + +### PLAN-002(已完成) + +- 将当前交付目标明确为企业受控网络内的单一公共知识库:本阶段所有知识共享一个可见域, + 暂缓用户、角色、知识库空间和 Document ACL,但不废弃 ADR-007,也不把未实现项标记完成。 +- 保持 Accepted ADR 的模块化单体边界,确定 API/Admin、MCP Gateway 和 Async Worker 独立 + 部署;OceanBase/BOS/AI Provider 使用外部服务,当前云端模型链路不启用 GPU Worker。 +- 将 Celery/RabbitMQ 正式并入 `DEMO-015`,并新增 `DEPLOY-001~003`,严格顺序为 + `DEMO-015 → DEMO-016 → DEPLOY-001 → DEPLOY-002 → DEPLOY-003`。 +- 定义 `make deploy VALUES=...` 的一键部署边界:操作者预先提供集群访问与 Secret,仓库负责 + 生产镜像、串行 Migration、Helm 安装/升级、Ingress/TLS、探针、资源与 Pod 安全配置;不得 + 将凭据写入 Git、镜像、命令行或日志。 +- 明确现有 `docker-compose.dev.yml` 的 PostgreSQL/MinIO 假设已被 ADR-012 取代,不作为集群 + 交付模板;新增 `docs/plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md` 作为任务范围和验收基线。 +- 本任务仅修改规划、产品、架构、API/MCP 契约、Demo Scope 和 DoD 文档,没有修改业务代码、 + 数据库 Migration 或 Accepted ADR 状态。 +- 验证结果:Markdown 相对链接、敏感值模式和 Git diff 检查通过;Ruff Format/Lint、Mypy、 + Alembic Head/离线升级通过;Unit + Integration `165 passed`,RAG Evaluation `5 passed`。 +- 下一任务:`DEMO-015`。 diff --git a/docs/plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md b/docs/plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md new file mode 100644 index 0000000..e76ddfc --- /dev/null +++ b/docs/plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md @@ -0,0 +1,120 @@ +# 公共知识库集群交付计划 + +**Task:** PLAN-002 +**Status:** Accepted planning baseline +**Date:** 2026-09-02 + +## 1. 阶段目标与边界 + +当前阶段只交付一个面向企业内部受控网络的公共知识库,先保证服务持续可用、可重复部署, +并让使用者打开 Admin Console 或连接 WorkBuddy 后即可使用,无需感知后端进程启停。 + +“公共”表示本阶段所有已接收知识处于同一个可见域,不代表面向公网匿名开放,也不代表 +ADR-007 被废弃。用户、用户组、角色、知识库多空间、Document ACL、SSO、OAuth 用户委托等 +完整 V1 能力继续后置;一旦需要接收非公共知识,必须先实现 Permission Resolver 和检索前/ +检索中 ACL 下推,禁止先做全局 Top-K 再过滤。 + +Admin 写操作只部署在企业受控网络或统一接入网关后。MCP 继续使用运行时注入、只具备 +`knowledge:search` scope 的服务凭据;静态 Demo credential 不得演变为共享超级管理员 Token。 + +## 2. 目标部署拓扑 + +```text + Ingress / TLS + │ + ┌──────────────┴──────────────┐ + │ │ + Admin Console + Knowledge API MCP Gateway + replicas replicas + │ │ + └──────── Application Services ────────┐ + │ + ┌─────────────────────────────┼─────────────┐ + │ │ │ + OceanBase MySQL BOS RabbitMQ + canonical + vector │ + ▼ + Async Worker(s) +``` + +沿用 ADR-002:业务核心仍为模块化单体,不拆分额外微服务;API、MCP Gateway 和异步 Worker +分别作为可独立扩缩容的进程/容器交付。当前 Parser 与云端 Embedding/Reranker 不需要本地 GPU, +因此 GPU Worker 不进入本轮最小部署,未来引入本地 OCR/模型时再按既有架构角色启用。 + +OceanBase、BOS 和模型服务使用集群外已有服务。RabbitMQ 默认使用外部地址;Helm Chart 可以 +提供显式开关安装开发/演示依赖,但生产值不得把队列数据生命周期绑定到应用 Pod。 + +## 3. “一键部署”的定义 + +在操作者已具备 Kubernetes 访问权限、目标 Namespace 和 Secret 的前提下,仓库提供单一入口: + +```text +make deploy VALUES= +``` + +该入口负责: + +- 校验非敏感配置和 `existingSecret` 引用,不把凭据写入 Git、镜像、命令行或日志; +- 运行一次性、可追踪且串行的数据库 Migration Job; +- 安装或升级 API/Admin、MCP Gateway、Async Worker、Service 和可选 RabbitMQ 依赖; +- 配置 Ingress/TLS、资源 requests/limits、非 root、只读根文件系统和最小 ServiceAccount; +- 配置 readiness/liveness probe、副本数和滚动升级策略; +- 支持重复执行和幂等升级,并提供对应卸载/回滚说明。 + +本定义不承诺自动创建 OceanBase、BOS、域名证书或云厂商账号,也不允许在仓库内保存这些 +资源的敏感凭据。 + +## 4. Task 顺序与依赖 + +```text +PLAN-002 + └──→ DEMO-015 Celery/RabbitMQ Async Job + Retry Cleanup + └──→ DEMO-016 Batch Async Upload + Status UI + └──→ DEPLOY-001 Production Images + └──→ DEPLOY-002 Kubernetes/Helm One-click Deploy + └──→ DEPLOY-003 Availability + Remote Acceptance +``` + +### DEMO-015 + +实现持久化 Job/Attempt、重试前清理、幂等消费和有界自动重试,并把执行器正式接入 +Celery/RabbitMQ。队列调用保持在抽象边界后,不允许业务服务直接依赖 Celery API。 + +### DEMO-016 + +基于 DEMO-015 提供逐文件隔离的批量异步提交、批次/Job 查询和 Admin Console 状态展示。 + +### DEPLOY-001 + +交付 API/Admin、MCP Gateway、Async Worker 的生产容器镜像与启动约定;镜像使用固定依赖、 +非 root 用户、健康检查和多架构可构建基线,不内置凭据。 + +### DEPLOY-002 + +交付 Kubernetes/Helm Chart、环境 Values Schema、`existingSecret`、Migration Job、Ingress/TLS、 +Pod 安全、资源限制、探针和 `make deploy` 入口。现有 `docker-compose.dev.yml` 仍仅作为旧的 +本地开发文件,因其 PostgreSQL/MinIO 假设与 ADR-012 不一致,不得作为集群交付模板。 + +### DEPLOY-003 + +在目标集群完成安装、幂等升级、滚动重启、Worker 故障恢复和远程 WorkBuddy 验收;形成运行 +手册、备份/恢复责任边界和最小日志/指标检查。灾备演练与完整 Observability 平台仍属后置项。 + +## 5. 最小验收标准 + +- 新 Namespace 可由单一命令完成安装,重复执行不会破坏已有数据; +- Migration 在应用升级前串行成功,失败时新版本不继续接管流量; +- Admin/API 与 MCP 使用稳定 HTTPS 地址,重启或滚动升级不要求最终用户重新注入配置; +- API/MCP 支持至少两个副本,readiness 未通过的 Pod 不接收流量; +- Worker 重启后持久化 Job 可继续恢复,重复消息不产生双重有效执行或重复派生数据; +- 远程 WorkBuddy 仅发现批准的 `search_knowledge` Tool,并完成一次真实检索; +- 清单、镜像、日志和验收产物不包含凭据,敏感值均来自 Secret; +- 关键请求、Job 和外部依赖失败具备可定位的结构化日志和最小指标。 + +## 6. 明确后置能力 + +- 用户、用户组、角色、多租户、知识库空间隔离和 Document ACL; +- LDAP/SSO、OAuth 用户委托、公共互联网匿名访问; +- GPU Worker、本地模型、OCR/MinerU; +- 跨区域容灾、自动云资源编排和完整 Observability 平台; +- 未被既有 Demo/V1 明确批准的业务能力。 diff --git a/docs/plans/TASKS.md b/docs/plans/TASKS.md index 195c0d8..592e6ac 100644 --- a/docs/plans/TASKS.md +++ b/docs/plans/TASKS.md @@ -27,17 +27,24 @@ validation. Provider credentials and internal endpoints are runtime inputs and n - [x] PLAN-001 MCP 与异步批量入库现状审计、任务拆分和契约基线 - [x] DEMO-012 MCP `search_knowledge` Gateway + identity + WorkBuddy verification -- [ ] DEMO-015 Async ingestion Job + bounded automatic retry + pre-retry cleanup +- [x] PLAN-002 公共知识库集群交付范围、任务拆分和一键部署基线 +- [ ] DEMO-015 Async ingestion Job + Celery/RabbitMQ + bounded retry + pre-retry cleanup - [ ] DEMO-016 Batch async upload API + per-file Job status + Admin Console +- [ ] DEPLOY-001 Production images for API/Admin, MCP Gateway and Async Worker +- [ ] DEPLOY-002 Kubernetes/Helm one-click deployment + Secret/Migration/Ingress baseline +- [ ] DEPLOY-003 Availability, rolling upgrade and remote WorkBuddy acceptance Dependencies and acceptance boundaries are defined in -[`ASYNC_INGESTION_MCP_PLAN.md`](ASYNC_INGESTION_MCP_PLAN.md). These Demo tasks are vertical slices of -the V1 backlog below; completing a slice does not automatically complete its corresponding `EKP-*` -task. +[`ASYNC_INGESTION_MCP_PLAN.md`](ASYNC_INGESTION_MCP_PLAN.md) and +[`PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md`](PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md). These Demo/Deploy tasks are +vertical slices of the V1 backlog below; completing a slice does not automatically complete its +corresponding `EKP-*` task. The current public-knowledge phase defers, but does not complete or +supersede, the unchecked user/ACL tasks. ```text DEMO-009 + ARCH-006 → DEMO-012 -DEMO-003~006 → DEMO-015 → DEMO-016 +PLAN-002 + └→ DEMO-003~006 → DEMO-015 → DEMO-016 → DEPLOY-001 → DEPLOY-002 → DEPLOY-003 ``` ## Phase 0 diff --git a/docs/plans/V1_EXECUTION_PLAN.md b/docs/plans/V1_EXECUTION_PLAN.md index 87f1bda..203879e 100644 --- a/docs/plans/V1_EXECUTION_PLAN.md +++ b/docs/plans/V1_EXECUTION_PLAN.md @@ -12,12 +12,23 @@ ## 当前增量实施顺序(2026-09-02) -在不扩大 V1 范围的前提下,当前先按 Demo 垂直切片补齐已确认的高优先级能力: +`DEMO-012` 已完成 MCP `search_knowledge` 与本地 WorkBuddy 验收。根据 PLAN-002,当前阶段按 +“单一公共知识可见域、企业受控网络、持续可用和一键集群部署”推进,不提前实现用户/权限隔离: -1. `DEMO-012`:MCP `search_knowledge`、identity 边界和 WorkBuddy 验证; -2. `DEMO-015`:异步入库 Job、自动重试和重试前派生数据清理; -3. `DEMO-016`:批量异步上传、批次/Job 查询和 Admin Console 状态展示。 +1. `PLAN-002`:确定公共知识库交付边界、目标拓扑、Task 拆分与验收门槛; +2. `DEMO-015`:持久化异步 Job、Celery/RabbitMQ 执行器、自动重试和重试前清理; +3. `DEMO-016`:批量异步上传、批次/Job 查询和 Admin Console 状态展示; +4. `DEPLOY-001`:API/Admin、MCP Gateway、Async Worker 生产镜像; +5. `DEPLOY-002`:Kubernetes/Helm、Secret、Migration、Ingress/TLS 和一键部署入口; +6. `DEPLOY-003`:多副本可用性、滚动升级、Worker 恢复和远程 WorkBuddy 验收。 -`DEMO-012` 复用已经完成的 Search Service,可独立先行。`DEMO-016` 依赖 `DEMO-015`,不得在 -缺少持久化状态、幂等执行和恢复边界时直接并发调用当前同步流水线。详细范围和验收标准见 -[`ASYNC_INGESTION_MCP_PLAN.md`](ASYNC_INGESTION_MCP_PLAN.md)。 +严格依赖为: + +```text +PLAN-002 → DEMO-015 → DEMO-016 → DEPLOY-001 → DEPLOY-002 → DEPLOY-003 +``` + +`DEMO-016` 不得在缺少持久化状态、幂等消费和恢复边界时直接并发调用同步流水线;集群交付也 +不得继续使用 `docker-compose.dev.yml` 中已被 ADR-012 取代的 PostgreSQL/MinIO 假设。详细 +范围和验收标准见 [`ASYNC_INGESTION_MCP_PLAN.md`](ASYNC_INGESTION_MCP_PLAN.md) 与 +[`PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md`](PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md)。 diff --git a/docs/product/PRD.md b/docs/product/PRD.md index 25c3436..ef561be 100644 --- a/docs/product/PRD.md +++ b/docs/product/PRD.md @@ -10,6 +10,21 @@ --- +## 当前阶段交付覆盖(PLAN-002) + +为优先达成服务可用和一键集群部署,当前阶段只交付企业受控网络内的单一公共知识库:所有 +已接收知识处于同一个可见域,用户打开 Admin Console 或连接 WorkBuddy 即可使用,无需感知 +后端进程启停。用户、用户组、角色、知识库多空间、Document ACL、LDAP/SSO 和 OAuth 用户 +委托仍是本 PRD 的后续 V1 要求,本阶段不实现,也不得标记为完成。 + +该阶段覆盖不会取代安全原则:公共知识库不等于匿名公网开放;Admin 写操作必须位于受控网络 +或统一接入网关后,MCP 使用运行时注入的最小 `knowledge:search` 服务凭据。一旦平台需要接收 +非公共知识,必须先完成 Permission Resolver 与检索前/检索中 ACL 下推,禁止全局 Top-K 后置 +过滤。实施顺序和集群验收边界见 +[`PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md`](../plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md)。 + +--- + # 1. 项目背景 企业内部存在大量分散于 PDF、Word、PPT、Excel、Markdown、图片、扫描件及其他文件中的知识资产。