mirror of https://github.com/Tencent/WeKnora.git synced 2026-06-04 21:34:31 +08:00

Files

nullkey c8b2129853 docs(api): restore auth.md and update README/wiki links

Fixes #958.

- 新建 docs/api/auth.md：覆盖 10 个 /auth/* 端点
  register / login / oidc 三件套（config/url/callback）/ refresh /
  validate / logout / me / change-password。
  说明各端点的鉴权方式（无 / refresh_token / Bearer JWT），并对齐
  /auth/oidc/callback 的真实行为（始终 302 跳到 / 并把结果编码进
  URL hash）。
- docs/api/README.md：
  - 增加"最权威参考：Swagger UI"段落，引导读者优先访问
    /swagger/index.html（swagger 由 swag 注解自动从代码生成）。
  - "认证管理"行链接由仅指向 OIDC 流程文档改为同时指向 auth.md
    与 OIDC 流程文档。
  - 新增 "IM 渠道" 行指向 docs/IM集成开发文档.md。
  - 新增 "数据源导入" 行指向 docs/数据源导入开发文档.md。
- docs/wiki/API参考/API文档概览.md：随 api/README.md 的"认证管理"
  行同步更新即可——IM 与数据源在该文件原有的"相关主题"/"反向链接"
  小节已经登记，不在 "API 分类" 表中重复。

2026-05-12 13:16:58 +08:00

4.0 KiB

Raw Permalink Blame History

WeKnora API 文档

概述

WeKnora 提供了一系列 RESTful API，用于创建和管理知识库、检索知识，以及进行基于知识的问答。本文档详细描述了这些 API 的使用方式。

最权威参考：Swagger UI

WeKnora 同时提供基于 OpenAPI 的 Swagger 文档。启动服务后访问 http://localhost:8080/swagger/index.html，可看到所有端点的完整参数、请求/响应 schema，并可直接在浏览器内试调——它随代码自动更新，是最准确的接口参考。

本目录下的 markdown 文档提供更易读的示例与场景说明，与 swagger 同步维护；当二者出现差异时，以 swagger 为准。

Swagger UI 仅在非 release 模式（GIN_MODE != release）下挂载；生产部署默认关闭。

基础信息

基础 URL: /api/v1
响应格式: JSON
认证方式: API Key

认证机制

所有 API 请求需要在 HTTP 请求头中包含 X-API-Key 进行身份认证：

X-API-Key: your_api_key

为便于问题追踪和调试，建议每个请求的 HTTP 请求头中添加 X-Request-ID：

X-Request-ID: unique_request_id

获取 API Key

在 web 页面完成账户注册后，请前往账户信息页面获取您的 API Key。

请妥善保管您的 API Key，避免泄露。API Key 代表您的账户身份，拥有完整的 API 访问权限。

错误处理

所有 API 使用标准的 HTTP 状态码表示请求状态，并返回统一的错误响应格式：

{
  "success": false,
  "error": {
    "code": "错误代码",
    "message": "错误信息",
    "details": "错误详情"
  }
}

API 概览

WeKnora API 按功能分为以下几类：

分类	描述	文档链接
认证管理	用户注册、登录、令牌管理；OIDC 流程	auth.md · OIDC认证调用流程.md
租户管理	创建和管理租户账户	tenant.md
知识库管理	创建、查询和管理知识库	knowledge-base.md
知识管理	上传、检索和管理知识内容	knowledge.md
模型管理	配置和管理各种AI模型	model.md
分块管理	管理知识的分块内容	chunk.md
标签管理	管理知识库的标签分类	tag.md
FAQ管理	管理FAQ问答对	faq.md
智能体管理	创建和管理自定义智能体	agent.md
会话管理	创建和管理对话会话	session.md
知识搜索	在知识库中搜索内容	knowledge-search.md
聊天功能	基于知识库和 Agent 进行问答	chat.md
消息管理	获取和管理对话消息	message.md
评估功能	评估模型性能	evaluation.md
初始化管理	知识库模型配置与 Ollama 管理	initialization.md
系统管理	系统信息、解析引擎、存储引擎	system.md
MCP 服务	MCP 工具服务管理	mcp-service.md
组织管理	组织、成员、知识库/智能体共享	organization.md
Skills	预装智能体技能	skill.md
网络搜索	网络搜索服务商	web-search.md
向量存储	向量数据库连接管理	vector-store.md
IM 渠道	企业微信 / 飞书 / Slack 等 IM 平台对接，含渠道 CRUD 与回调	../IM集成开发文档.md
数据源导入	飞书 / 企微 / Notion / Confluence 等外部数据源接入与同步	../数据源导入开发文档.md

4.0 KiB Raw Permalink Blame History Unescape Escape