From 82b46b4b3827dd00c22013dc04b5b1899c682a39 Mon Sep 17 00:00:00 2001 From: "ochan.kwon" Date: Fri, 10 Apr 2026 09:32:48 +0900 Subject: [PATCH] feat: add VectorStore CRUD API endpoints and documentation Wire VectorStoreService to HTTP with 8 endpoints: types metadata, CRUD (create/list/get/update/delete), and connection testing (raw + by ID). Register routes, DI container bindings, and add API documentation. --- docs/api/README.md | 1 + docs/api/vector-store.md | 361 +++++++++++++++++++++++++ internal/container/container.go | 3 + internal/handler/vectorstore.go | 455 ++++++++++++++++++++++++++++++++ internal/router/router.go | 23 +- 5 files changed, 842 insertions(+), 1 deletion(-) create mode 100644 docs/api/vector-store.md create mode 100644 internal/handler/vectorstore.go diff --git a/docs/api/README.md b/docs/api/README.md index 63f46a93..e276b973 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -79,3 +79,4 @@ WeKnora API 按功能分为以下几类: | 组织管理 | 组织、成员、知识库/智能体共享 | [organization.md](./organization.md) | | Skills | 预装智能体技能 | [skill.md](./skill.md) | | 网络搜索 | 网络搜索服务商 | [web-search.md](./web-search.md) | +| 向量存储 | 向量数据库连接管理 | [vector-store.md](./vector-store.md) | diff --git a/docs/api/vector-store.md b/docs/api/vector-store.md new file mode 100644 index 00000000..2b58dbac --- /dev/null +++ b/docs/api/vector-store.md @@ -0,0 +1,361 @@ +# Vector Store API + +[返回目录](./README.md) + +向量存储(VectorStore)API 用于管理向量数据库连接配置。支持 Elasticsearch、PostgreSQL、Qdrant、Milvus、Weaviate、SQLite 六种引擎类型。 + +| 方法 | 路径 | 描述 | +| ------ | ---------------------------- | ------------------------------ | +| GET | `/vector-stores/types` | 获取支持的引擎类型及配置字段 | +| POST | `/vector-stores/test` | 使用原始凭据测试连接(不保存) | +| POST | `/vector-stores` | 创建向量存储 | +| GET | `/vector-stores` | 获取向量存储列表 | +| GET | `/vector-stores/:id` | 获取向量存储详情 | +| PUT | `/vector-stores/:id` | 更新向量存储(仅名称可修改) | +| DELETE | `/vector-stores/:id` | 删除向量存储(软删除) | +| POST | `/vector-stores/:id/test` | 测试已保存的向量存储连接 | + +--- + +## GET `/vector-stores/types` - 获取支持的引擎类型 + +返回所有支持的引擎类型,包含连接配置和索引配置的字段定义,可用于前端表单生成。 + +**请求**: + +```curl +curl --location 'http://localhost:8080/api/v1/vector-stores/types' \ +--header 'X-API-Key: sk-xxxxx' +``` + +**响应**: + +```json +{ + "success": true, + "data": [ + { + "type": "elasticsearch", + "display_name": "Elasticsearch (Keywords + Vector)", + "connection_fields": [ + {"name": "addr", "type": "string", "required": true, "description": "Elasticsearch URL (e.g., http://localhost:9200)"}, + {"name": "username", "type": "string", "required": false}, + {"name": "password", "type": "string", "required": false, "sensitive": true} + ], + "index_fields": [ + {"name": "index_name", "type": "string", "required": false, "default": "xwrag_default"}, + {"name": "number_of_shards", "type": "number", "required": false}, + {"name": "number_of_replicas", "type": "number", "required": false} + ] + }, + { + "type": "postgres", + "display_name": "PostgreSQL (Keywords + Vector)", + "connection_fields": [ + {"name": "use_default_connection", "type": "boolean", "required": false, "default": true, "description": "Use the application's default database connection"}, + {"name": "addr", "type": "string", "required": false, "description": "PostgreSQL connection string (required if use_default_connection is false)"}, + {"name": "username", "type": "string", "required": false}, + {"name": "password", "type": "string", "required": false, "sensitive": true} + ] + } + ] +} +``` + +--- + +## POST `/vector-stores/test` - 测试原始凭据连接 + +使用提供的凭据执行连接测试,不保存任何数据。成功时返回自动检测到的服务器版本。 + +**请求**: + +```curl +curl --location 'http://localhost:8080/api/v1/vector-stores/test' \ +--header 'X-API-Key: sk-xxxxx' \ +--header 'Content-Type: application/json' \ +--data '{ + "engine_type": "elasticsearch", + "connection_config": { + "addr": "http://es:9200", + "username": "elastic", + "password": "changeme" + } +}' +``` + +**响应(成功)**: + +```json +{ + "success": true, + "version": "7.10.1" +} +``` + +> `version` 字段包含自动检测到的服务器版本。如果无法检测(如 Milvus、SQLite),则为空字符串。 + +**响应(失败)**: + +```json +{ + "success": false, + "error": "failed to connect to elasticsearch: connection refused or authentication failed" +} +``` + +--- + +## POST `/vector-stores` - 创建向量存储 + +创建一个新的向量存储配置。同一 endpoint + index 组合不允许重复注册(包括环境变量配置的存储)。 + +**请求**: + +```curl +curl --location 'http://localhost:8080/api/v1/vector-stores' \ +--header 'X-API-Key: sk-xxxxx' \ +--header 'Content-Type: application/json' \ +--data '{ + "name": "elasticsearch-hot", + "engine_type": "elasticsearch", + "connection_config": { + "addr": "http://es-hot:9200", + "username": "elastic", + "password": "changeme" + }, + "index_config": { + "index_name": "my_index" + } +}' +``` + +**响应** (201): + +```json +{ + "success": true, + "data": { + "id": "550e8400-e29b-41d4-a716-446655440000", + "name": "elasticsearch-hot", + "engine_type": "elasticsearch", + "connection_config": { + "addr": "http://es-hot:9200", + "username": "elastic", + "password": "***" + }, + "index_config": { + "index_name": "my_index" + }, + "source": "user", + "readonly": false, + "created_at": "2026-04-07T10:00:00Z", + "updated_at": "2026-04-07T10:00:00Z" + } +} +``` + +> **注意**: 响应中的敏感字段(`password`、`api_key`)会被掩码为 `"***"`。 +> `connection_config.version` 字段在连接测试成功后自动填充(如 `"7.10.1"`),创建时为空。 + +--- + +## GET `/vector-stores` - 获取向量存储列表 + +返回当前租户的所有向量存储,包含环境变量配置的存储(`source: "env"`)和用户创建的存储(`source: "user"`)。环境变量存储排列在前。 + +**请求**: + +```curl +curl --location 'http://localhost:8080/api/v1/vector-stores' \ +--header 'X-API-Key: sk-xxxxx' +``` + +**响应**: + +```json +{ + "success": true, + "data": [ + { + "id": "__env_postgres__", + "name": "postgres (env)", + "engine_type": "postgres", + "connection_config": { + "use_default_connection": true + }, + "source": "env", + "readonly": true + }, + { + "id": "550e8400-e29b-41d4-a716-446655440000", + "name": "elasticsearch-hot", + "engine_type": "elasticsearch", + "connection_config": { + "addr": "http://es-hot:9200", + "username": "elastic", + "password": "***" + }, + "source": "user", + "readonly": false + } + ] +} +``` + +--- + +## GET `/vector-stores/:id` - 获取向量存储详情 + +根据 ID 获取单个向量存储详情。支持 `__env_*` 格式的环境变量存储 ID。 + +**请求**: + +```curl +curl --location 'http://localhost:8080/api/v1/vector-stores/550e8400-e29b-41d4-a716-446655440000' \ +--header 'X-API-Key: sk-xxxxx' +``` + +**响应**: + +```json +{ + "success": true, + "data": { + "id": "550e8400-e29b-41d4-a716-446655440000", + "name": "elasticsearch-hot", + "engine_type": "elasticsearch", + "connection_config": { + "addr": "http://es-hot:9200", + "username": "elastic", + "password": "***", + "version": "7.10.1" + }, + "index_config": { + "index_name": "my_index" + }, + "source": "user", + "readonly": false, + "created_at": "2026-04-07T10:00:00Z", + "updated_at": "2026-04-07T10:00:00Z" + } +} +``` + +--- + +## PUT `/vector-stores/:id` - 更新向量存储 + +更新向量存储的名称。`engine_type`、`connection_config`、`index_config` 创建后不可变更。环境变量存储不可修改(返回 400)。 + +**请求**: + +```curl +curl --location --request PUT 'http://localhost:8080/api/v1/vector-stores/550e8400-e29b-41d4-a716-446655440000' \ +--header 'X-API-Key: sk-xxxxx' \ +--header 'Content-Type: application/json' \ +--data '{ + "name": "elasticsearch-hot-renamed" +}' +``` + +**响应**: + +```json +{ + "success": true, + "data": { + "id": "550e8400-e29b-41d4-a716-446655440000", + "name": "elasticsearch-hot-renamed", + "engine_type": "elasticsearch", + "connection_config": { + "addr": "http://es-hot:9200", + "username": "elastic", + "password": "***" + }, + "index_config": { + "index_name": "my_index" + }, + "source": "user", + "readonly": false, + "created_at": "2026-04-07T10:00:00Z", + "updated_at": "2026-04-07T10:05:00Z" + } +} +``` + +--- + +## DELETE `/vector-stores/:id` - 删除向量存储 + +软删除向量存储。环境变量存储不可删除(返回 400)。 + +**请求**: + +```curl +curl --location --request DELETE 'http://localhost:8080/api/v1/vector-stores/550e8400-e29b-41d4-a716-446655440000' \ +--header 'X-API-Key: sk-xxxxx' +``` + +**响应**: + +```json +{ + "success": true +} +``` + +--- + +## POST `/vector-stores/:id/test` - 测试已保存的向量存储连接 + +对已保存的向量存储或环境变量存储执行连接测试。成功时返回检测到的服务器版本,并自动更新存储记录中的 `connection_config.version` 字段。 + +**请求**: + +```curl +curl --location --request POST 'http://localhost:8080/api/v1/vector-stores/550e8400-e29b-41d4-a716-446655440000/test' \ +--header 'X-API-Key: sk-xxxxx' +``` + +**响应(成功)**: + +```json +{ + "success": true, + "version": "7.10.1" +} +``` + +> 对于已保存的存储(非环境变量存储),检测到的版本会自动保存到 `connection_config.version` 中。 + +**响应(失败)**: + +```json +{ + "success": false, + "error": "failed to connect to elasticsearch: connection refused or authentication failed" +} +``` + +--- + +## 环境变量存储 + +通过 `RETRIEVE_DRIVER` 环境变量配置的向量存储以虚拟条目形式出现在列表中。这些条目的特征: + +- **ID 格式**: `__env_{driver}__`(如 `__env_postgres__`、`__env_elasticsearch_v8__`) +- **source**: `"env"` +- **readonly**: `true` +- **不可修改/删除**: PUT 和 DELETE 返回 400 +- **可测试连接**: POST `/:id/test` 正常工作 + +## 错误码 + +| HTTP 状态码 | 含义 | +|-------------|------| +| 400 | 请求参数错误、验证失败、尝试修改环境变量存储 | +| 401 | 未认证 | +| 404 | 向量存储不存在 | +| 409 | 同一 endpoint + index 组合已存在 | +| 500 | 内部服务器错误 | diff --git a/internal/container/container.go b/internal/container/container.go index a6729a2a..0bc5a218 100644 --- a/internal/container/container.go +++ b/internal/container/container.go @@ -187,8 +187,10 @@ func BuildContainer(container *dig.Container) *dig.Container { must(container.Provide(infra_web_search.NewRegistry)) must(container.Invoke(registerWebSearchProviders)) must(container.Provide(repository.NewWebSearchProviderRepository)) + must(container.Provide(repository.NewVectorStoreRepository)) must(container.Provide(service.NewWebSearchService)) must(container.Provide(service.NewWebSearchProviderService)) + must(container.Provide(service.NewVectorStoreService)) // Agent service layer (requires event bus, web search service) // SessionService is passed as parameter to CreateAgentEngine method when creating AgentService @@ -258,6 +260,7 @@ func BuildContainer(container *dig.Container) *dig.Container { must(container.Provide(handler.NewMCPServiceHandler)) must(container.Provide(handler.NewWebSearchHandler)) must(container.Provide(handler.NewWebSearchProviderHandler)) + must(container.Provide(handler.NewVectorStoreHandler)) must(container.Provide(handler.NewCustomAgentHandler)) must(container.Provide(service.NewSkillService)) must(container.Provide(handler.NewSkillHandler)) diff --git a/internal/handler/vectorstore.go b/internal/handler/vectorstore.go new file mode 100644 index 00000000..46421b3c --- /dev/null +++ b/internal/handler/vectorstore.go @@ -0,0 +1,455 @@ +package handler + +import ( + "context" + "net/http" + "os" + + "github.com/Tencent/WeKnora/internal/errors" + "github.com/Tencent/WeKnora/internal/logger" + "github.com/Tencent/WeKnora/internal/types" + "github.com/Tencent/WeKnora/internal/types/interfaces" + "github.com/gin-gonic/gin" +) + +// VectorStoreHandler handles HTTP requests for vector store CRUD +type VectorStoreHandler struct { + repo interfaces.VectorStoreRepository + service interfaces.VectorStoreService +} + +// NewVectorStoreHandler creates a new handler +func NewVectorStoreHandler( + repo interfaces.VectorStoreRepository, + service interfaces.VectorStoreService, +) *VectorStoreHandler { + return &VectorStoreHandler{repo: repo, service: service} +} + +// --- request DTOs --- + +// CreateStoreRequest defines the request body for creating a vector store +type CreateStoreRequest struct { + Name string `json:"name" binding:"required"` + EngineType types.RetrieverEngineType `json:"engine_type" binding:"required"` + ConnectionConfig types.ConnectionConfig `json:"connection_config" binding:"required"` + IndexConfig types.IndexConfig `json:"index_config"` +} + +// UpdateStoreRequest defines the request body for updating a vector store. +// Only name is mutable — engine_type, connection_config, index_config are immutable. +type UpdateStoreRequest struct { + Name string `json:"name" binding:"required"` +} + +// TestStoreRequest defines the body for testing raw credentials +type TestStoreRequest struct { + EngineType types.RetrieverEngineType `json:"engine_type" binding:"required"` + ConnectionConfig types.ConnectionConfig `json:"connection_config" binding:"required"` +} + +// --- helpers --- + +// getTenantID extracts tenant ID from gin context (set by auth middleware). +func (h *VectorStoreHandler) getTenantID(c *gin.Context) uint64 { + return c.GetUint64(types.TenantIDContextKey.String()) +} + +// getOwnedStore loads a store and verifies it belongs to the given tenant. +// Returns (nil, status, msg) on failure so callers can respond immediately. +func (h *VectorStoreHandler) getOwnedStore( + ctx context.Context, tenantID uint64, id string, +) (*types.VectorStore, int, string) { + store, err := h.repo.GetByID(ctx, tenantID, id) + if err != nil { + return nil, http.StatusInternalServerError, "failed to query vector store" + } + if store == nil { + return nil, http.StatusNotFound, "vector store not found" + } + return store, http.StatusOK, "" +} + +// envStoreReadonlyError returns a 400 error for attempting to modify env stores. +func envStoreReadonlyError() gin.H { + return gin.H{"success": false, "error": "environment-configured vector stores cannot be modified via API"} +} + +// --- endpoints --- + +// CreateStore godoc +// @Summary Create vector store +// @Description Create a new vector store configuration for the current tenant +// @Tags VectorStore +// @Accept json +// @Produce json +// @Param request body CreateStoreRequest true "Vector store configuration" +// @Success 201 {object} map[string]interface{} "Created vector store" +// @Failure 400 {object} errors.AppError "Invalid request or validation error" +// @Failure 401 {object} map[string]interface{} "Unauthorized" +// @Failure 409 {object} errors.AppError "Duplicate endpoint and index" +// @Security Bearer +// @Security ApiKeyAuth +// @Router /vector-stores [post] +func (h *VectorStoreHandler) CreateStore(c *gin.Context) { + ctx := c.Request.Context() + + tenantID := h.getTenantID(c) + if tenantID == 0 { + c.JSON(http.StatusUnauthorized, gin.H{"success": false, "error": "unauthorized: tenant context missing"}) + return + } + + var req CreateStoreRequest + if err := c.ShouldBindJSON(&req); err != nil { + logger.Warnf(ctx, "Invalid create vector store request: %v", err) + c.Error(errors.NewBadRequestError(err.Error())) + return + } + + store := &types.VectorStore{ + TenantID: tenantID, + Name: req.Name, + EngineType: req.EngineType, + ConnectionConfig: req.ConnectionConfig, + IndexConfig: req.IndexConfig, + } + + if err := h.service.CreateStore(ctx, store); err != nil { + logger.Warnf(ctx, "Failed to create vector store: %v", err) + c.Error(err) + return + } + + c.JSON(http.StatusCreated, gin.H{ + "success": true, + "data": types.NewVectorStoreResponse(store, "user", false), + }) +} + +// ListStores godoc +// @Summary List vector stores +// @Description List all vector stores for the current tenant, including environment-configured and user-created stores +// @Tags VectorStore +// @Produce json +// @Success 200 {object} map[string]interface{} "List of vector stores (env + DB)" +// @Failure 401 {object} map[string]interface{} "Unauthorized" +// @Security Bearer +// @Security ApiKeyAuth +// @Router /vector-stores [get] +func (h *VectorStoreHandler) ListStores(c *gin.Context) { + ctx := c.Request.Context() + + tenantID := h.getTenantID(c) + if tenantID == 0 { + c.JSON(http.StatusUnauthorized, gin.H{"success": false, "error": "unauthorized: tenant context missing"}) + return + } + + dbStores, err := h.repo.List(ctx, tenantID) + if err != nil { + logger.Warnf(ctx, "Failed to list vector stores: %v", err) + c.Error(errors.NewInternalServerError(err.Error())) + return + } + + // DB stores → VectorStoreResponse (masked) + maskedDBStores := make([]types.VectorStoreResponse, len(dbStores)) + for i, s := range dbStores { + maskedDBStores[i] = types.NewVectorStoreResponse(s, "user", false) + } + + // env stores → VectorStore → VectorStoreResponse (masked) + envStores := types.BuildEnvVectorStores(os.Getenv("RETRIEVE_DRIVER"), os.Getenv) + maskedEnvStores := make([]types.VectorStoreResponse, len(envStores)) + for i := range envStores { + maskedEnvStores[i] = types.NewVectorStoreResponse(&envStores[i], "env", true) + } + + // Merge: env stores first, then DB stores + allStores := append(maskedEnvStores, maskedDBStores...) + + c.JSON(http.StatusOK, gin.H{"success": true, "data": allStores}) +} + +// GetStore godoc +// @Summary Get vector store +// @Description Retrieve a single vector store by ID. Supports both DB stores and env stores (__env_* IDs) +// @Tags VectorStore +// @Produce json +// @Param id path string true "Vector store ID" +// @Success 200 {object} map[string]interface{} "Vector store details" +// @Failure 401 {object} map[string]interface{} "Unauthorized" +// @Failure 404 {object} map[string]interface{} "Vector store not found" +// @Security Bearer +// @Security ApiKeyAuth +// @Router /vector-stores/{id} [get] +func (h *VectorStoreHandler) GetStore(c *gin.Context) { + ctx := c.Request.Context() + + tenantID := h.getTenantID(c) + if tenantID == 0 { + c.JSON(http.StatusUnauthorized, gin.H{"success": false, "error": "unauthorized: tenant context missing"}) + return + } + + id := c.Param("id") + + // Handle env store + if types.IsEnvStoreID(id) { + envStore := types.FindEnvVectorStore(os.Getenv("RETRIEVE_DRIVER"), os.Getenv, id) + if envStore == nil { + c.JSON(http.StatusNotFound, gin.H{"success": false, "error": "vector store not found"}) + return + } + c.JSON(http.StatusOK, gin.H{ + "success": true, + "data": types.NewVectorStoreResponse(envStore, "env", true), + }) + return + } + + // DB store + store, status, msg := h.getOwnedStore(ctx, tenantID, id) + if status != http.StatusOK { + c.JSON(status, gin.H{"success": false, "error": msg}) + return + } + + c.JSON(http.StatusOK, gin.H{ + "success": true, + "data": types.NewVectorStoreResponse(store, "user", false), + }) +} + +// UpdateStore godoc +// @Summary Update vector store +// @Description Update a vector store (name only). Engine type, connection config, and index config are immutable. Env stores cannot be modified. +// @Tags VectorStore +// @Accept json +// @Produce json +// @Param id path string true "Vector store ID" +// @Param request body UpdateStoreRequest true "Updated fields" +// @Success 200 {object} map[string]interface{} "Updated vector store" +// @Failure 400 {object} map[string]interface{} "Env store or validation error" +// @Failure 401 {object} map[string]interface{} "Unauthorized" +// @Failure 404 {object} map[string]interface{} "Vector store not found" +// @Security Bearer +// @Security ApiKeyAuth +// @Router /vector-stores/{id} [put] +func (h *VectorStoreHandler) UpdateStore(c *gin.Context) { + ctx := c.Request.Context() + + tenantID := h.getTenantID(c) + if tenantID == 0 { + c.JSON(http.StatusUnauthorized, gin.H{"success": false, "error": "unauthorized: tenant context missing"}) + return + } + + id := c.Param("id") + + // env stores are read-only + if types.IsEnvStoreID(id) { + c.JSON(http.StatusBadRequest, envStoreReadonlyError()) + return + } + + // Ownership check + if _, status, msg := h.getOwnedStore(ctx, tenantID, id); status != http.StatusOK { + c.JSON(status, gin.H{"success": false, "error": msg}) + return + } + + var req UpdateStoreRequest + if err := c.ShouldBindJSON(&req); err != nil { + c.Error(errors.NewBadRequestError(err.Error())) + return + } + + updated := &types.VectorStore{ + ID: id, + TenantID: tenantID, + Name: req.Name, + } + + if err := h.service.UpdateStore(ctx, updated); err != nil { + logger.Warnf(ctx, "Failed to update vector store %s: %v", id, err) + c.Error(err) + return + } + + // Re-fetch to return full state + result, err := h.repo.GetByID(ctx, tenantID, id) + if err != nil { + logger.Warnf(ctx, "Failed to re-fetch vector store %s after update: %v", id, err) + } + if result != nil { + c.JSON(http.StatusOK, gin.H{ + "success": true, + "data": types.NewVectorStoreResponse(result, "user", false), + }) + } else { + c.JSON(http.StatusOK, gin.H{"success": true, "data": nil}) + } +} + +// DeleteStore godoc +// @Summary Delete vector store +// @Description Soft-delete a vector store. Env stores cannot be deleted. +// @Tags VectorStore +// @Produce json +// @Param id path string true "Vector store ID" +// @Success 200 {object} map[string]interface{} "Deletion success" +// @Failure 400 {object} map[string]interface{} "Env store cannot be deleted" +// @Failure 401 {object} map[string]interface{} "Unauthorized" +// @Failure 404 {object} map[string]interface{} "Vector store not found" +// @Security Bearer +// @Security ApiKeyAuth +// @Router /vector-stores/{id} [delete] +func (h *VectorStoreHandler) DeleteStore(c *gin.Context) { + ctx := c.Request.Context() + + tenantID := h.getTenantID(c) + if tenantID == 0 { + c.JSON(http.StatusUnauthorized, gin.H{"success": false, "error": "unauthorized: tenant context missing"}) + return + } + + id := c.Param("id") + + // env stores are read-only + if types.IsEnvStoreID(id) { + c.JSON(http.StatusBadRequest, envStoreReadonlyError()) + return + } + + // Ownership check + if _, status, msg := h.getOwnedStore(ctx, tenantID, id); status != http.StatusOK { + c.JSON(status, gin.H{"success": false, "error": msg}) + return + } + + if err := h.service.DeleteStore(ctx, tenantID, id); err != nil { + logger.Warnf(ctx, "Failed to delete vector store %s: %v", id, err) + c.Error(err) + return + } + + c.JSON(http.StatusOK, gin.H{"success": true}) +} + +// ListStoreTypes godoc +// @Summary List vector store types +// @Description Return supported engine types with connection and index field schemas for UI form generation +// @Tags VectorStore +// @Produce json +// @Success 200 {object} map[string]interface{} "List of engine types with config schemas" +// @Router /vector-stores/types [get] +func (h *VectorStoreHandler) ListStoreTypes(c *gin.Context) { + c.JSON(http.StatusOK, gin.H{ + "success": true, + "data": types.GetVectorStoreTypes(), + }) +} + +// TestStoreByID godoc +// @Summary Test vector store connection by ID +// @Description Test connectivity of an existing saved or env store. Returns detected server version. For DB stores, the version is automatically saved to connection_config. +// @Tags VectorStore +// @Produce json +// @Param id path string true "Vector store ID" +// @Success 200 {object} map[string]interface{} "Connection test result (success, version)" +// @Failure 401 {object} map[string]interface{} "Unauthorized" +// @Failure 404 {object} map[string]interface{} "Vector store not found" +// @Security Bearer +// @Security ApiKeyAuth +// @Router /vector-stores/{id}/test [post] +func (h *VectorStoreHandler) TestStoreByID(c *gin.Context) { + ctx := c.Request.Context() + + tenantID := h.getTenantID(c) + if tenantID == 0 { + c.JSON(http.StatusUnauthorized, gin.H{"success": false, "error": "unauthorized: tenant context missing"}) + return + } + + id := c.Param("id") + + // env store — test with unmasked config + if types.IsEnvStoreID(id) { + envStore := types.FindEnvVectorStore(os.Getenv("RETRIEVE_DRIVER"), os.Getenv, id) + if envStore == nil { + c.JSON(http.StatusNotFound, gin.H{"success": false, "error": "vector store not found"}) + return + } + version, err := h.service.TestConnection(ctx, envStore.EngineType, envStore.ConnectionConfig) + if err != nil { + logger.Warnf(ctx, "Vector store connection test failed: %v", err) + c.JSON(http.StatusOK, gin.H{"success": false, "error": err.Error()}) + return + } + c.JSON(http.StatusOK, gin.H{"success": true, "version": version}) + return + } + + // DB store + store, status, msg := h.getOwnedStore(ctx, tenantID, id) + if status != http.StatusOK { + c.JSON(status, gin.H{"success": false, "error": msg}) + return + } + + version, err := h.service.TestConnection(ctx, store.EngineType, store.ConnectionConfig) + if err != nil { + logger.Warnf(ctx, "Vector store connection test failed: %v", err) + c.JSON(http.StatusOK, gin.H{"success": false, "error": err.Error()}) + return + } + + // Update stored version if detected + if version != "" && version != store.ConnectionConfig.Version { + if updateErr := h.service.SaveDetectedVersion(ctx, store, version); updateErr != nil { + logger.Warnf(ctx, "Failed to update detected version for store %s: %v", store.ID, updateErr) + } + } + + c.JSON(http.StatusOK, gin.H{"success": true, "version": version}) +} + +// TestStoreRaw godoc +// @Summary Test vector store connection with raw credentials +// @Description Test connectivity using provided credentials without persisting. Returns detected server version. +// @Tags VectorStore +// @Accept json +// @Produce json +// @Param request body TestStoreRequest true "Engine type and connection config" +// @Success 200 {object} map[string]interface{} "Connection test result (success, version)" +// @Failure 400 {object} errors.AppError "Invalid request" +// @Failure 401 {object} map[string]interface{} "Unauthorized" +// @Security Bearer +// @Security ApiKeyAuth +// @Router /vector-stores/test [post] +func (h *VectorStoreHandler) TestStoreRaw(c *gin.Context) { + ctx := c.Request.Context() + + tenantID := h.getTenantID(c) + if tenantID == 0 { + c.JSON(http.StatusUnauthorized, gin.H{"success": false, "error": "unauthorized: tenant context missing"}) + return + } + + var req TestStoreRequest + if err := c.ShouldBindJSON(&req); err != nil { + c.Error(errors.NewBadRequestError(err.Error())) + return + } + + version, err := h.service.TestConnection(ctx, req.EngineType, req.ConnectionConfig) + if err != nil { + logger.Warnf(ctx, "Vector store connection test failed: %v", err) + c.JSON(http.StatusOK, gin.H{"success": false, "error": err.Error()}) + return + } + + c.JSON(http.StatusOK, gin.H{"success": true, "version": version}) +} diff --git a/internal/router/router.go b/internal/router/router.go index 9da4a23e..422ea281 100644 --- a/internal/router/router.go +++ b/internal/router/router.go @@ -55,6 +55,7 @@ type RouterParams struct { MCPServiceHandler *handler.MCPServiceHandler WebSearchHandler *handler.WebSearchHandler WebSearchProviderHandler *handler.WebSearchProviderHandler + VectorStoreHandler *handler.VectorStoreHandler FAQHandler *handler.FAQHandler TagHandler *handler.TagHandler CustomAgentHandler *handler.CustomAgentHandler @@ -62,7 +63,7 @@ type RouterParams struct { OrganizationHandler *handler.OrganizationHandler IMHandler *handler.IMHandler DataSourceHandler *handler.DataSourceHandler - WeKnoraCloudHandler *handler.WeKnoraCloudHandler + WeKnoraCloudHandler *handler.WeKnoraCloudHandler } // NewRouter 创建新的路由 @@ -140,6 +141,7 @@ func NewRouter(params RouterParams) *gin.Engine { RegisterMCPServiceRoutes(v1, params.MCPServiceHandler) RegisterWebSearchRoutes(v1, params.WebSearchHandler) RegisterWebSearchProviderRoutes(v1, params.WebSearchProviderHandler) + RegisterVectorStoreRoutes(v1, params.VectorStoreHandler) RegisterCustomAgentRoutes(v1, params.CustomAgentHandler) RegisterSkillRoutes(v1, params.SkillHandler) RegisterOrganizationRoutes(v1, params.OrganizationHandler) @@ -502,6 +504,25 @@ func RegisterWebSearchProviderRoutes(r *gin.RouterGroup, h *handler.WebSearchPro } } +// RegisterVectorStoreRoutes registers CRUD routes for vector store configurations +func RegisterVectorStoreRoutes(r *gin.RouterGroup, h *handler.VectorStoreHandler) { + stores := r.Group("/vector-stores") + { + // List available engine types (metadata for UI forms) + stores.GET("/types", h.ListStoreTypes) + // Test with raw credentials (no persistence) + stores.POST("/test", h.TestStoreRaw) + // CRUD + stores.POST("", h.CreateStore) + stores.GET("", h.ListStores) + stores.GET("/:id", h.GetStore) + stores.PUT("/:id", h.UpdateStore) + stores.DELETE("/:id", h.DeleteStore) + // Test existing saved or env store + stores.POST("/:id/test", h.TestStoreByID) + } +} + // RegisterCustomAgentRoutes registers custom agent routes func RegisterCustomAgentRoutes(r *gin.RouterGroup, agentHandler *handler.CustomAgentHandler) { agents := r.Group("/agents")