feat(knowledge-base): validate vector store bindings on create, copy, and delete
Wires KnowledgeBase.VectorStoreID and the ownership-aware retrieve factory into the user-facing knowledge-base lifecycle: - POST /knowledge-bases validates the requested vector_store_id against the caller's tenant scope and the engine registry. New error codes ErrVectorStoreBindingInvalid (2200) and ErrVectorStoreUnavailable (2201) distinguish the typed branches without echoing UUIDs to the client. - GET / POST / PUT / PUT-pin responses embed the bound store's display metadata (name, source, engine_type, status) without exposing any connection credentials. Cross-tenant shared KBs receive a suppressed payload (vector_store_id stripped, source="shared") so operator-chosen store names cannot be enumerated across tenants. - POST /knowledge-bases/copy synchronously rejects clones whose target has a different embedding model or vector store, before the async clone task is enqueued. The async clone worker re-applies the same checks for defense in depth. - DELETE /vector-stores/:id refuses to remove a store with bound KBs, inside a transaction that row-locks the store on PostgreSQL and serializes via WAL on SQLite. unregister-from-registry is wrapped in defer/recover so a panic surfaces as a structured warning instead of silently leaking a stale engine. - vector_store_id is immutable after creation. The GORM <-:create tag blocks every ORM update path; the service-layer DTO omits the field entirely; a reflection-based regression test catches any future maintainer who adds it back to either layer. - Empty-string vector_store_id is normalized to nil at both the create path and inside SharesStoreWith, so rows persisted by callers that did not run Normalize first cannot trip false same-store comparisons. Part of #993. Depends on #994 and #1310.
This commit is contained in:
@@ -332,6 +332,10 @@ curl --location --request PUT 'http://localhost:8080/api/v1/vector-stores/550e84
|
||||
|
||||
对 DB 中的存储执行软删除。环境变量存储不可删除(返回 `400`)。
|
||||
|
||||
**Phase 2 — 绑定保护**:
|
||||
|
||||
删除请求在事务中执行,并按 `(tenant_id, vector_store_id)` 复合索引统计当前租户中仍绑定到该存储的活跃知识库数量。**只要存在任意绑定的知识库(已软删除的 KB 不计入),删除即被拒绝**,调用者必须先解绑或删除这些知识库才能继续。在 PostgreSQL 上,事务期间会对 `vector_stores` 行加 `SELECT … FOR UPDATE` 行锁,阻止并发的知识库创建请求悄悄落到正在被删除的存储上(SQLite 上则依赖 WAL + 单写入序列化达成同样语义)。
|
||||
|
||||
**路径参数**:
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
@@ -345,7 +349,7 @@ curl --location --request DELETE 'http://localhost:8080/api/v1/vector-stores/550
|
||||
--header 'X-API-Key: sk-xxxxx'
|
||||
```
|
||||
|
||||
**响应**:
|
||||
**响应(成功)**:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -353,6 +357,20 @@ curl --location --request DELETE 'http://localhost:8080/api/v1/vector-stores/550
|
||||
}
|
||||
```
|
||||
|
||||
**响应(绑定保护触发)**:
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": {
|
||||
"code": 1000,
|
||||
"message": "vector store still has 3 knowledge base(s) bound to it; unbind or delete them before removing the store"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
HTTP `400`。错误消息中包含具体的知识库数量(便于运营定位),但不包含任何 KB 的 ID/名称,以避免跨租户信息泄漏。删除被拒绝时,DB 中的存储行保持原状,进程内引擎注册表也不会被清除。
|
||||
|
||||
## POST `/vector-stores/:id/test` - 测试已保存或环境变量存储的连接
|
||||
|
||||
对已保存的 DB 存储或环境变量虚拟存储执行一次连接测试。成功时返回检测到的服务器版本;对 DB 存储,检测到的版本会被自动写回 `connection_config.version`,环境变量存储不会更新。
|
||||
@@ -399,13 +417,18 @@ curl --location --request POST 'http://localhost:8080/api/v1/vector-stores/550e8
|
||||
- **readonly**:`true`
|
||||
- **不可修改/删除**:`PUT` 和 `DELETE` 返回 `400`
|
||||
- **可测试连通性**:`POST /vector-stores/:id/test` 正常工作
|
||||
- **被知识库绑定时**:未指定 `vector_store_id` 创建的知识库默认使用环境变量存储;这种知识库在响应中显示为 `vector_store_name="System default"` + `vector_store_source="env"`。
|
||||
|
||||
## 错误码
|
||||
|
||||
| HTTP 状态码 | 含义 |
|
||||
| ----------- | --------------------------------------------------- |
|
||||
| 400 | 请求参数错误、校验失败、尝试修改环境变量存储 |
|
||||
| 401 | 未认证(缺少租户上下文或 API Key) |
|
||||
| 404 | 向量存储不存在 |
|
||||
| 409 | 同一 endpoint + index 组合已存在 |
|
||||
| 500 | 内部服务器错误 |
|
||||
| HTTP 状态码 | code | 含义 |
|
||||
| ----------- | ---- | --------------------------------------------------- |
|
||||
| 400 | 1000 | 请求参数错误、校验失败、尝试修改环境变量存储、删除时仍有知识库绑定 |
|
||||
| 400 | 2200 | 知识库创建时引用的 `vector_store_id` 无效(不存在或属于其他租户) |
|
||||
| 400 | 2201 | 知识库创建时引用的存储当前不可用(DB 中存在但未注册到引擎) |
|
||||
| 401 | 1001 | 未认证(缺少租户上下文或 API Key) |
|
||||
| 404 | 1003 | 向量存储不存在 |
|
||||
| 409 | 1005 | 同一 endpoint + index 组合已存在 |
|
||||
| 500 | 1007 | 内部服务器错误 |
|
||||
|
||||
> `2200` / `2201` 由 `POST /knowledge-bases` 等知识库创建路径返回(详见 [knowledge-base.md](./knowledge-base.md)),列于此处仅为完整覆盖与向量存储相关的所有错误码。
|
||||
|
||||
Reference in New Issue
Block a user