WeKnora/docs/api/tenant.md

租户管理 API

返回目录

包含两组接口：

• 租户 CRUD（/tenants、/tenants/:id、/tenants/:id/api-key）：当前认证用户对自己所属租户进行管理；跨租户访问需要管理员权限。
• 跨租户接口（/tenants/all、/tenants/search）：需要服务端启用 EnableCrossTenantAccess 且当前用户具备 CanAccessAllTenants 权限，否则返回 403。
• 租户 KV 配置（/tenants/kv/:key）：当前租户级别的通用配置项，tenant_id 从认证上下文中获取，不在 URL 中传入。

方法	路径	描述
GET	/tenants/all	获取所有租户列表（需跨租户权限）
GET	/tenants/search	分页搜索租户（需跨租户权限）
POST	/tenants	创建新租户
GET	/tenants/:id	获取指定租户信息
PUT	/tenants/:id	更新租户信息
DELETE	/tenants/:id	删除租户
POST	/tenants/:id/api-key	重置租户 API Key
GET	/tenants	获取当前用户可见的租户列表
GET	/tenants/kv/:key	获取当前租户的 KV 配置（tenant 由认证上下文确定）
PUT	/tenants/kv/:key	更新当前租户的 KV 配置（tenant 由认证上下文确定）

GET /tenants/all - 获取所有租户列表

获取系统中所有租户列表，需要跨租户权限。

请求:

curl --location 'http://localhost:8080/api/v1/tenants/all' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: sk-An7_t_izCKFIJ4iht9Xjcjnj_MC48ILvwezEDki9ScfIa7KA'

响应:

{
    "data": {
        "items": [
            {
                "id": 10001,
                "name": "weknora-1",
                "description": "weknora tenants 1",
                "status": "active",
                "business": "wechat",
                "created_at": "2025-08-11T20:37:28.39698+08:00",
                "updated_at": "2025-08-11T20:37:28.405693+08:00"
            },
            {
                "id": 10002,
                "name": "weknora-2",
                "description": "weknora tenants 2",
                "status": "active",
                "business": "wechat",
                "created_at": "2025-08-11T20:52:58.05679+08:00",
                "updated_at": "2025-08-11T20:52:58.060495+08:00"
            }
        ]
    },
    "success": true
}

GET /tenants/search - 搜索租户

按关键词搜索租户，需要跨租户权限。

查询参数:

• keyword: 搜索关键词（可选）
• tenant_id: 按租户ID筛选（可选）
• page: 页码（默认 1）
• page_size: 每页条数（默认 20）

请求:

curl --location 'http://localhost:8080/api/v1/tenants/search?keyword=weknora&page=1&page_size=10' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: sk-An7_t_izCKFIJ4iht9Xjcjnj_MC48ILvwezEDki9ScfIa7KA'

响应:

{
    "data": {
        "items": [
            {
                "id": 10002,
                "name": "weknora",
                "description": "weknora tenants",
                "status": "active",
                "business": "wechat",
                "created_at": "2025-08-11T20:52:58.05679+08:00",
                "updated_at": "2025-08-11T20:52:58.060495+08:00"
            }
        ],
        "total": 1,
        "page": 1,
        "page_size": 10
    },
    "success": true
}

POST /tenants - 创建新租户

创建一个新的租户，服务端会自动生成租户 ID 与 API Key。

参数说明（请求体）:

字段	类型	必填	说明
name	string	是	租户名称
description	string	否	租户描述
business	string	否	业务标识（如 wechat）
retriever_engines	object	否	检索引擎组合配置（engines 数组：每项含 retriever_type 与 retriever_engine_type）
storage_quota	int	否	存储配额（字节）

请求:

curl --location 'http://localhost:8080/api/v1/tenants' \
--header 'Content-Type: application/json' \
--data '{
    "name": "weknora",
    "description": "weknora tenants",
    "business": "wechat",
    "retriever_engines": {
        "engines": [
            {
                "retriever_type": "keywords",
                "retriever_engine_type": "postgres"
            },
            {
                "retriever_type": "vector",
                "retriever_engine_type": "postgres"
            }
        ]
    }
}'

响应:

{
    "data": {
        "id": 10000,
        "name": "weknora",
        "description": "weknora tenants",
        "api_key": "sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG",
        "status": "active",
        "retriever_engines": {
            "engines": [
                {
                    "retriever_engine_type": "postgres",
                    "retriever_type": "keywords"
                },
                {
                    "retriever_engine_type": "postgres",
                    "retriever_type": "vector"
                }
            ]
        },
        "business": "wechat",
        "storage_quota": 10737418240,
        "storage_used": 0,
        "created_at": "2025-08-11T20:37:28.396980093+08:00",
        "updated_at": "2025-08-11T20:37:28.396980301+08:00",
        "deleted_at": null
    },
    "success": true
}

GET /tenants/:id - 获取指定租户信息

获取指定 ID 的租户详情。只能访问自己所属租户；访问其他租户需要跨租户权限，否则返回 403。

路径参数:

字段	类型	说明
id	int	租户 ID

请求:

curl --location 'http://localhost:8080/api/v1/tenants/10000' \
--header 'X-API-Key: sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG' \
--header 'Content-Type: application/json'

响应:

{
    "data": {
        "id": 10000,
        "name": "weknora",
        "description": "weknora tenants",
        "api_key": "sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG",
        "status": "active",
        "retriever_engines": {
            "engines": [
                {
                    "retriever_engine_type": "postgres",
                    "retriever_type": "keywords"
                },
                {
                    "retriever_engine_type": "postgres",
                    "retriever_type": "vector"
                }
            ]
        },
        "business": "wechat",
        "storage_quota": 10737418240,
        "storage_used": 0,
        "created_at": "2025-08-11T20:37:28.39698+08:00",
        "updated_at": "2025-08-11T20:37:28.405693+08:00",
        "deleted_at": null
    },
    "success": true
}

PUT /tenants/:id - 更新租户信息

更新指定租户的基础信息。访问规则同 GET /tenants/:id。

路径参数:

字段	类型	说明
id	int	租户 ID

参数说明（请求体）: 与 POST /tenants 相同字段；未传字段保持原值。

请求:

curl --location --request PUT 'http://localhost:8080/api/v1/tenants/10000' \
--header 'X-API-Key: sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG' \
--header 'Content-Type: application/json' \
--data '{
    "name": "weknora new",
    "description": "weknora tenants new",
    "status": "active",
    "retriever_engines": {
        "engines": [
            {
                "retriever_engine_type": "postgres",
                "retriever_type": "keywords"
            },
            {
                "retriever_engine_type": "postgres",
                "retriever_type": "vector"
            }
        ]
    },
    "business": "wechat",
    "storage_quota": 10737418240
}'

响应:

{
    "data": {
        "id": 10000,
        "name": "weknora new",
        "description": "weknora tenants new",
        "api_key": "sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG",
        "status": "active",
        "retriever_engines": {
            "engines": [
                {
                    "retriever_engine_type": "postgres",
                    "retriever_type": "keywords"
                },
                {
                    "retriever_engine_type": "postgres",
                    "retriever_type": "vector"
                }
            ]
        },
        "business": "wechat",
        "storage_quota": 10737418240,
        "storage_used": 0,
        "created_at": "2025-08-11T20:37:28.39698+08:00",
        "updated_at": "2025-08-11T20:49:02.13421034+08:00",
        "deleted_at": null
    },
    "success": true
}

DELETE /tenants/:id - 删除租户

删除指定租户。访问规则同 GET /tenants/:id。

路径参数:

字段	类型	说明
id	int	租户 ID

请求:

curl --location --request DELETE 'http://localhost:8080/api/v1/tenants/10000' \
--header 'X-API-Key: sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG' \
--header 'Content-Type: application/json'

响应:

{
    "message": "Tenant deleted successfully",
    "success": true
}

POST /tenants/:id/api-key - 重置租户 API Key

为指定租户生成新的 API Key，旧 Key 立即失效。访问规则同 GET /tenants/:id。

路径参数:

字段	类型	说明
id	int	租户 ID

请求:

curl --location --request POST 'http://localhost:8080/api/v1/tenants/10000/api-key' \
--header 'X-API-Key: sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG' \
--header 'Content-Type: application/json'

响应:

{
    "data": {
        "api_key": "sk-IKtd9JGV4-aPGQ6RiL8YJu9Vzb3-ae4lgFkjFJZmhvUn2mLu"
    },
    "success": true
}

GET /tenants - 获取租户列表

返回当前认证上下文对应的租户（普通用户为单条；管理员仍只返回自身租户）。

请求:

curl --location 'http://localhost:8080/api/v1/tenants' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'

响应:

{
    "data": {
        "items": [
            {
                "id": 10002,
                "name": "weknora",
                "description": "weknora tenants",
                "api_key": "sk-An7_t_izCKFIJ4iht9Xjcjnj_MC48ILvwezEDki9ScfIa7KA",
                "status": "active",
                "retriever_engines": {
                    "engines": [
                        {
                            "retriever_engine_type": "postgres",
                            "retriever_type": "keywords"
                        },
                        {
                            "retriever_engine_type": "postgres",
                            "retriever_type": "vector"
                        }
                    ]
                },
                "business": "wechat",
                "storage_quota": 10737418240,
                "storage_used": 0,
                "created_at": "2025-08-11T20:52:58.05679+08:00",
                "updated_at": "2025-08-11T20:52:58.060495+08:00",
                "deleted_at": null
            }
        ]
    },
    "success": true
}

GET /tenants/kv/:key - 获取租户 KV 配置

获取当前租户的 KV 配置项。租户 ID 从认证上下文中获取（即由 X-API-Key / Bearer Token 对应的租户决定），URL 中不需要也不接受 tenant_id。

路径参数:

字段	类型	说明
key	string	配置键名（见下方支持的 key 列表，不支持的键返回 400）

支持的 key 值:

key	说明
agent-config	Agent 配置（最大迭代次数、温度、System Prompt、可用工具等）
web-search-config	网页搜索配置
conversation-config	普通模式会话/对话配置
prompt-templates	系统提示词模板（只读，按用户语言本地化）
parser-engine-config	解析引擎配置（如 MinerU）
storage-engine-config	存储引擎配置（Local/MinIO/COS）
chat-history-config	聊天历史索引配置
retrieval-config	全局检索配置

请求:

curl --location 'http://localhost:8080/api/v1/tenants/kv/agent-config' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json'

响应（以 agent-config 为例）:

{
    "data": {
        "max_iterations": 10,
        "allowed_tools": ["knowledge_search", "web_search"],
        "temperature": 0.3,
        "system_prompt": "...",
        "use_custom_system_prompt": false,
        "available_tools": [
            { "name": "knowledge_search", "label": "知识库检索", "description": "..." }
        ],
        "available_placeholders": [
            { "name": "web_search_status", "label": "联网搜索状态", "description": "..." }
        ]
    },
    "success": true
}

失败时（不支持的键）：

{ "success": false, "error": "unsupported key" }

PUT /tenants/kv/:key - 更新租户 KV 配置

更新当前租户的 KV 配置项。租户 ID 从认证上下文中获取，请求体结构按 key 不同而异。prompt-templates 为只读，不支持 PUT。

路径参数:

字段	类型	说明
key	string	配置键名（见 GET 接口的支持列表，prompt-templates 除外）

请求（以 agent-config 为例）:

curl --location --request PUT 'http://localhost:8080/api/v1/tenants/kv/agent-config' \
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "max_iterations": 20,
    "temperature": 0.3,
    "system_prompt": ""
}'

响应:

{
    "data": {
        "max_iterations": 20,
        "allowed_tools": ["knowledge_search", "web_search"],
        "temperature": 0.3,
        "system_prompt": "",
        "use_custom_system_prompt": false
    },
    "message": "Agent configuration updated successfully",
    "success": true
}

约束:

• agent-config: max_iterations 取值范围 (0, 30]；temperature 取值范围 [0, 2]。
• web-search-config: max_results 取值范围 [1, 50]。
• conversation-config: 包含多项阈值校验（如 keyword_threshold / vector_threshold ∈ [0, 1]，rerank_threshold ∈ [-10, 10]，temperature ∈ [0, 2]，max_completion_tokens ∈ [1, 100000] 等）。
• retrieval-config: embedding_top_k / rerank_top_k ∈ [0, 200]；阈值范围同上。
• storage-engine-config: default_provider 必须在 STORAGE_ALLOW_LIST 允许的列表内。
• chat-history-config: 启用且设置了 embedding_model_id 而尚未关联知识库时，会自动创建一个隐藏知识库并将其 ID 写入配置。