opensource/WeKnora
3
0
Fork 0
mirror of https://github.com/Tencent/WeKnora.git synced 2026-09-01 14:53:07 +08:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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 分类" 表中重复。
This commit is contained in:
nullkey
2026-05-11 17:37:14 +08:00
committed by lyingbug
parent 1c7171b2c6
commit c8b2129853
3 changed files with 330 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/README.md
+12 -1
View File
@@ -3,6 +3,7 @@
## 目录
- [概述](#概述)
- [最权威参考：Swagger UI](#最权威参考swagger-ui)
- [基础信息](#基础信息)
- [认证机制](#认证机制)
- [错误处理](#错误处理)
@@ -12,6 +13,14 @@
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`
@@ -59,7 +68,7 @@ WeKnora API 按功能分为以下几类：
| 分类 | 描述 | 文档链接 |
|------|------|----------|
| 认证管理 | 用户注册、登录、令牌管理 | [OIDC认证调用流程.md](../OIDC认证调用流程.md) |
| 认证管理 | 用户注册、登录、令牌管理；OIDC 流程 | [auth.md](./auth.md) · [OIDC认证调用流程.md](../OIDC认证调用流程.md) |
| 租户管理 | 创建和管理租户账户 | [tenant.md](./tenant.md) |
| 知识库管理 | 创建、查询和管理知识库 | [knowledge-base.md](./knowledge-base.md) |
| 知识管理 | 上传、检索和管理知识内容 | [knowledge.md](./knowledge.md) |
@@ -80,3 +89,5 @@ WeKnora API 按功能分为以下几类：
| Skills | 预装智能体技能 | [skill.md](./skill.md) |
| 网络搜索 | 网络搜索服务商 | [web-search.md](./web-search.md) |
| 向量存储 | 向量数据库连接管理 | [vector-store.md](./vector-store.md) |
| IM 渠道 | 企业微信 / 飞书 / Slack 等 IM 平台对接，含渠道 CRUD 与回调 | [../IM集成开发文档.md](../IM集成开发文档.md) |
| 数据源导入 | 飞书 / 企微 / Notion / Confluence 等外部数据源接入与同步 | [../数据源导入开发文档.md](../数据源导入开发文档.md) |
docs/api/auth.md
+317
View File
@@ -0,0 +1,317 @@
# 认证管理 API
[返回目录](./README.md)
OIDC 完整调用流程见 [../OIDC认证调用流程.md](../OIDC认证调用流程.md)。本文档作为端点参考。
## 说明
WeKnora 的 `/auth/*` 端点本身**不需要 X-API-Key**，但部分端点需要在 `Authorization: Bearer <token>` 头中携带由 `/auth/login` 或 `/auth/oidc/callback` 返回的 JWT：
| 端点 | 鉴权方式 |
| --- | --- |
| `/auth/register` `/auth/login` | 无 |
| `/auth/oidc/config` `/auth/oidc/url` `/auth/oidc/callback` | 无 |
| `/auth/refresh` | refresh_token（请求体携带） |
| `/auth/validate` `/auth/me` `/auth/logout` `/auth/change-password` | Bearer JWT |
注册接口可通过环境变量 `DISABLE_REGISTRATION=true` 关闭。
## 端点一览
| 方法 | 路径 | 描述 |
| ---- | -------------------------- | ------------------------------------------ |
| POST | `/auth/register` | 用户注册 |
| POST | `/auth/login` | 用户登录 |
| GET | `/auth/oidc/config` | 获取 OIDC 配置元数据 |
| GET | `/auth/oidc/url` | 获取 OIDC 授权链接 |
| GET | `/auth/oidc/callback` | OIDC 授权回调（由 IdP 重定向触发） |
| POST | `/auth/refresh` | 用 refresh_token 换新的 access_token |
| GET | `/auth/validate` | 验证 JWT 有效性 |
| POST | `/auth/logout` | 退出登录 |
| GET | `/auth/me` | 获取当前用户信息 |
| POST | `/auth/change-password` | 修改密码 |
---
## POST `/auth/register` - 用户注册
**参数说明（请求体）**:
| 字段 | 类型 | 必填 | 校验 | 说明 |
| -------- | ------ | ---- | -------------------------- | --------- |
| username | string | 是 | 长度 2-50 | 用户名 |
| email | string | 是 | 邮箱格式 | 邮箱 |
| password | string | 是 | 最少 6 位 | 密码 |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/auth/register' \
--header 'Content-Type: application/json' \
--data '{
"username": "alice",
"email": "alice@example.com",
"password": "secret123"
}'
```
**响应**（201 Created）:
```json
{
"success": true,
"message": "Registration successful",
"user": {
"id": "usr-...",
"username": "alice",
"email": "alice@example.com",
"tenant_id": 1,
"is_active": true,
"created_at": "2026-05-11T10:00:00+08:00",
"updated_at": "2026-05-11T10:00:00+08:00"
},
"tenant": {
"id": 1,
"name": "alice's workspace",
"api_key": "sk-..."
}
}
```
**错误**: 注册被禁用 → 403；参数校验失败 → 400。
---
## POST `/auth/login` - 用户登录
**参数说明（请求体）**:
| 字段 | 类型 | 必填 | 说明 |
| -------- | ------ | ---- | ------------- |
| email | string | 是 | 注册邮箱 |
| password | string | 是 | 密码 |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/auth/login' \
--header 'Content-Type: application/json' \
--data '{
"email": "alice@example.com",
"password": "secret123"
}'
```
**响应**:
```json
{
"success": true,
"message": "Login successful",
"user": { "id": "usr-...", "username": "alice", "email": "alice@example.com" },
"tenant": { "id": 1, "name": "alice's workspace", "api_key": "sk-..." },
"token": "eyJhbGciOi...",
"refresh_token": "eyJhbGciOi..."
}
```
**错误**: 邮箱或密码错误 → 401；账号被禁用 → 403。
---
## GET `/auth/oidc/config` - 获取 OIDC 配置元数据
返回 OIDC 是否启用以及 Provider 显示名，前端登录页据此决定是否展示 OIDC 登录按钮。
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/auth/oidc/config'
```
**响应**:
```json
{
"success": true,
"enabled": true,
"provider_display_name": "WeKnora SSO"
}
```
---
## GET `/auth/oidc/url` - 获取 OIDC 授权链接
返回前端应跳转的 OIDC IdP 授权页 URL 与状态码。
**查询参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---------- | ------ | ---- | ------------------------------------------------------- |
| redirect | string | 否 | 登录成功后前端期望落地的路径（如 `/dashboard`），透传到 state |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/auth/oidc/url?redirect=%2Fdashboard'
```
**响应**:
```json
{
"success": true,
"provider_display_name": "WeKnora SSO",
"authorization_url": "https://idp.example.com/oauth/authorize?client_id=...&state=...",
"state": "abcdef..."
}
```
---
## GET `/auth/oidc/callback` - OIDC 授权回调
由 IdP 在用户授权后重定向到此端点。一般不需要客户端代码直接调用——它的作用是把登录结果通过浏览器 hash 传回前端首页。
**查询参数**:
| 字段 | 类型 | 必填 | 说明 |
| ----------------- | ------ | ---- | ----------------------------- |
| code | string | 是 | IdP 颁发的 authorization code |
| state | string | 是 | 与 `/auth/oidc/url` 返回值一致 |
| error | string | 否 | IdP 返回的错误标识 |
| error_description | string | 否 | IdP 返回的错误详情 |
**响应**：始终返回 `302 Found`，跳转到 `/`，并把结果编码进 URL hash：
- 成功：`/#oidc_result=<base64url(JSON payload)>`，其中 payload 包含 `success` / `user` / `tenant` / `token` / `refresh_token` / `is_new_user`，与登录响应一致。
- 失败：`/#oidc_error=<reason>[&oidc_error_description=<message>]`，常见 reason 包括 `invalid_state`、`missing_code`、`login_failed`、`payload_encode_failed`。
---
## POST `/auth/refresh` - 刷新令牌
**参数说明（请求体）**:
| 字段 | 类型 | 必填 | 说明 |
| ------------- | ------ | ---- | ----------------- |
| refreshToken | string | 是 | 登录时颁发的 refresh_token |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/auth/refresh' \
--header 'Content-Type: application/json' \
--data '{
"refreshToken": "eyJhbGciOi..."
}'
```
**响应**:
```json
{
"success": true,
"message": "Token refreshed successfully",
"access_token": "eyJhbGciOi...",
"refresh_token": "eyJhbGciOi..."
}
```
**错误**: refresh_token 无效或过期 → 401。
---
## GET `/auth/validate` - 验证 JWT
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/auth/validate' \
--header 'Authorization: Bearer eyJhbGciOi...'
```
**响应**:
```json
{
"success": true,
"valid": true,
"user_id": "usr-...",
"tenant_id": 1
}
```
无效 token 返回 401。
---
## POST `/auth/logout` - 退出登录
**请求**:
```curl
curl --location --request POST 'http://localhost:8080/api/v1/auth/logout' \
--header 'Authorization: Bearer eyJhbGciOi...'
```
**响应**: `{ "success": true, "message": "Logged out successfully" }`
---
## GET `/auth/me` - 获取当前用户信息
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/auth/me' \
--header 'Authorization: Bearer eyJhbGciOi...'
```
**响应**:
```json
{
"success": true,
"user": {
"id": "usr-...",
"username": "alice",
"email": "alice@example.com",
"avatar": "",
"tenant_id": 1,
"is_active": true,
"can_access_all_tenants": false,
"created_at": "2026-05-11T10:00:00+08:00",
"updated_at": "2026-05-11T10:00:00+08:00"
}
}
```
---
## POST `/auth/change-password` - 修改密码
**参数说明（请求体）**:
| 字段 | 类型 | 必填 | 校验 | 说明 |
| ------------- | ------ | ---- | ------- | --------- |
| old_password | string | 是 | | 旧密码 |
| new_password | string | 是 | 最少 6 位 | 新密码 |
**请求**:
```curl
curl --location 'http://localhost:8080/api/v1/auth/change-password' \
--header 'Authorization: Bearer eyJhbGciOi...' \
--header 'Content-Type: application/json' \
--data '{
"old_password": "secret123",
"new_password": "newsecret456"
}'
```
**响应**: `{ "success": true, "message": "Password changed successfully" }`
**错误**: 旧密码不匹配或新密码不满足校验 → 400。
docs/wiki/API参考/API文档概览.md
+1 -1
View File
@@ -45,7 +45,7 @@ API Key 在 Web 页面完成账户注册后，前往账户信息页面获取。
| 分类 | 描述 | 详细文档 |
|------|------|----------|
| 认证管理 | 用户注册、登录、令牌管理 | [OIDC认证调用流程.md](../安全认证/OIDC认证调用流程.md) |
| 认证管理 | 用户注册、登录、令牌管理；OIDC 流程 | [auth.md](../../api/auth.md) · [OIDC认证调用流程.md](../安全认证/OIDC认证调用流程.md) |
| 租户管理 | 创建和管理租户账户 | [tenant.md](../../api/tenant.md) |
| 知识库管理 | 创建、查询和管理知识库 | [knowledge-base.md](../../api/knowledge-base.md) |
| 知识管理 | 上传、检索和管理知识内容 | [knowledge.md](../../api/knowledge.md) |