WeKnora/website-docs/04-api/02-api-auth.md

295 lines
12 KiB
Markdown
Raw Normal View History

# API 参考:认证与用户
提供注册、登录、令牌刷新、个人资料和邀请处理接口。认证要求随接口而异,公开接口在各条目中标注。
除特别标注外,本组接口在认证中间件之后仅要求“已登录”(无角色下限)。免认证接口见各条目。
## 认证(/api/v1/auth)
### POST /api/v1/auth/register
用途:注册新用户(自助注册模式)。免认证。Handler: `internal/handler/auth.go`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
docs: sync website-docs, homepage and changelog for v0.8.2 (#3632) * docs: sync website-docs with changes since v0.8.0 Audit every change between v0.8.0 and the v0.8.2 release against the documentation site, adding what users and operators need and correcting statements that no longer match the code. - Add local browser (BrowserSkill), built-in MCP Server endpoints, the toolbox, conversation steer/fork/rewind and reasoning effort, the artifacts library, sandbox terminal and desktop, the Lite host sandbox, the rebuilt model catalog (including a protocol-compat field reference), Confluence and DingTalk Docs sources, Bocha/Serply search, per-channel IM locale, whitelist-only outbound, admin user creation, new configuration variables and migrations 000091-000110. - Fix wrong API examples and parameters (model type values, knowledge search params, FAQ match_count cap, Notion credentials), tenant deletion semantics, default timeouts, parser engine claims, removed tables and commands, stale navigation paths, and route locations after the router split into routes_*.go. - Add screenshots for the new pages and refresh outdated ones. * fix(frontend): link the protocol-compat field to its documentation The model editor told users to read catalog/compat.go on the backend, a path that no longer exists after the model catalog refactor. The hint now says when the override is needed and links to the field reference in website-docs/03-features/06-models.md; the config examples and the API type comment point to the same place. * feat(website): showcase v0.8.2 on the homepage - Add a v0.8.2 section for the local browser (BrowserSkill), the built-in MCP Server and conversation control, and turn the v0.8.0 release block into a standing skills & sandbox topic with the sandbox desktop and terminal. - Replace the three-up galleries with a feature list beside one large screenshot: every item's text stays visible, clicking an item or one of its views switches the image with a cross-fade, and the list plays itself while on screen until the visitor picks something. - Add Confluence, DingTalk, BrowserSkill and more model vendors to the integrations, bump the header badge to v0.8.2 and link the changelog. - check-site reports missing docs screenshots as pending instead of failing, since the Screenshot component renders a placeholder for them. * docs(changelog): add v0.8.2 release notes * docs(website): add per-version release notes pages Add a "版本发布" docs section with one page per release, starting with v0.8.2 and a backfilled v0.8.0. Each page walks through the highlights with the existing product screenshots, the other improvements and fixes, and an upgrade checklist with the actions each breaking change needs. The sidebar orders these pages by version, newest first; the docs header gains a 版本 entry, and the homepage's v0.8.2 section now links to the release notes page instead of the raw CHANGELOG. * feat(website): let the site image listen on a configurable port The Docker image hard-coded `listen 80`, so running it with host networking or on a platform that assigns the container port required editing the Nginx config and rebuilding. The image now renders its config from the official nginx template directory at startup and reads the listen port from `PORT` (default 80); deploy/nginx.conf stays a plain config for static deployments. test-docker starts a second container with PORT=8080 and checks the rendered config and that the site answers on that port; the README documents the variable. * fix(website): namespace the nginx listen port variable * fix(website): support bash-wrapped container startup * fix(website): align nginx startup with frontend entrypoint * fix(website): pin nginx runtime for older host compatibility * fix(website): bake the configured nginx port into the image
2026-09-24 03:26:34 +00:00
| `username` | string | 是 | 用户名,2–50 字符 |
| `email` | string | 是 | 邮箱 |
| `password` | string | 是 | 密码(8–32 位,字母+数字;复杂模式另需大小写和特殊字符) |
是否自动创建个人空间由服务端的 `auth.default_tenant_mode` 决定,请求体不能指定。`invite_register`(仅限邀请注册)和 `invite_only`(禁止注册)模式下返回 403。
响应:201 `{"success":true,"message":"...","user":{User}}`
```bash
curl -X POST $BASE/api/v1/auth/register -H 'Content-Type: application/json' \
-d '{"username":"alice","email":"a@ex.com","password":"secret123"}'
```
### POST /api/v1/auth/register-by-invite
仅 `self_serve` 和 `invite_register` 模式允许凭有效邀请链接注册;`invite_only` 模式返回 403。
用途:通过邀请/分享链接 token 注册并加入空间。免认证,IP 限流 30 次/分钟。Handler: `internal/handler/auth_register_by_invite.go`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `token` | string | 是(`binding:"required"`) | 邀请 token |
| `email` | string | 是(`binding:"required,email"`) | 邮箱 |
| `username` | string | 是(`binding:"required"`) | 用户名 |
| `password` | string | 是(`binding:"required,min=6"`) | 密码(8–32 位,字母+数字;复杂模式另需大小写和特殊字符) |
响应:201,同 Login(`user/active_tenant/memberships/token/refresh_token`)。
```bash
curl -X POST $BASE/api/v1/auth/register-by-invite -H 'Content-Type: application/json' \
-d '{"token":"<invite_token>","email":"a@ex.com","username":"alice","password":"secret123"}'
```
### POST /api/v1/auth/invitations/lookup
用途:匿名查询邀请 token 对应的空间信息(注册前预览)。免认证,IP 限流。Handler: `internal/handler/auth_register_by_invite.go`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `token` | string | 是(`binding:"required"`) | 邀请 token |
响应:200 `{"success":true,"data":{"tenant_id","tenant_name","role","expires_at"}}`
```bash
curl -X POST $BASE/api/v1/auth/invitations/lookup -H 'Content-Type: application/json' -d '{"token":"<invite_token>"}'
```
### POST /api/v1/auth/login
用途:邮箱密码登录。免认证。Handler: `internal/handler/auth.go`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `email` | string | 是(`binding:"required"`) | 邮箱 |
| `password` | string | 是(`binding:"required"`) | 密码 |
响应:200 `{"success":true,"user":{...},"active_tenant":{...},"memberships":[...],"token":"...","refresh_token":"..."}`
```bash
curl -X POST $BASE/api/v1/auth/login -H 'Content-Type: application/json' -d '{"email":"a@ex.com","password":"secret123"}'
```
### POST /api/v1/auth/auto-setup
用途:原生桌面 Lite 自动建号、建空间及登录。必须携带桌面原生桥接提供的每进程随机 `X-WeKnora-Desktop-Token`,不接受匿名 HTTP 请求。普通浏览器使用注册/登录接口。Handler: `internal/handler/auth.go`
响应:200,同 Login;缺少或错误的桌面凭据返回 401。
### GET /api/v1/auth/config
用途:查询注册模式等认证配置。免认证。Handler: `internal/handler/auth.go`
响应:200 `{"success":true,"registration_mode":"self_serve|invite_register|invite_only","complex_password_enabled":false}`
```bash
curl $BASE/api/v1/auth/config
```
### POST /api/v1/auth/switch-tenant
用途:切换当前活跃空间并换发 token。需登录(无空间也可调用)。Handler: `internal/handler/auth.go`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `tenant_id` | uint64 | 是(`binding:"required"`) | 目标空间 ID |
| `refresh_token` | string | 否 | 用于换发新 token |
响应:200,同 Login。
换签成功会把目标空间写入账号级「最近活跃租户」偏好,下次登录(密码/OIDC/换设备)与 refresh 都回到该空间。refresh JWT 不含 `tenant_id`,因此偏好写入失败则整次换签失败、不会发出新 token。API 客户端无需再补发 `PUT /auth/me/preferences`。Web UI 切空间不走本接口。一次换签会改变该用户所有设备的下次落点。
```bash
curl -X POST $BASE/api/v1/auth/switch-tenant -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"tenant_id":2}'
```
### GET /api/v1/auth/oidc/config
用途:查询 OIDC 是否启用及显示名。免认证。Handler: `internal/handler/auth.go`
响应:200 `{"success":true,"enabled":bool,"provider_display_name":"..."}`
```bash
curl $BASE/api/v1/auth/oidc/config
```
### GET /api/v1/auth/oidc/start
免登录,直接返回 302 和指向 IdP 的 Location,可供企业门户链接使用。无需先请求 JSON 授权地址;回调由请求 origin 构造为 `/api/v1/auth/oidc/callback`。回调后的登录结果与原 OIDC 链路一致。
```bash
curl -i "$BASE/api/v1/auth/oidc/start"
```
### GET /api/v1/auth/oidc/url
用途:获取 OIDC 授权跳转 URL。免认证。Handler: `internal/handler/auth.go`
| 查询参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `redirect_uri` | string | 是 | 回调地址 |
响应:200 `{"success":true,"authorization_url":"...","nonce":"..."}`
```bash
curl "$BASE/api/v1/auth/oidc/url?redirect_uri=https://app.example.com/callback"
```
### GET /api/v1/auth/oidc/callback
用途:OIDC 授权回调(浏览器重定向进入)。免认证。Handler: `internal/handler/auth.go`
查询参数:`code`、`state`、`error`、`error_description`(均由 OIDC 提供方带回)。
响应:302 重定向到前端,成功携带 `#oidc_result=<base64url>`,失败携带 `#oidc_error=...`。
```bash
curl -i "$BASE/api/v1/auth/oidc/callback?code=xxx&state=yyy"
```
### POST /api/v1/auth/refresh
用途:用 refresh token 换发新 token。免认证。Handler: `internal/handler/auth.go`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `refreshToken` | string | 是(`binding:"required"`) | refresh token |
响应:200 `{"success":true,"access_token":"...","refresh_token":"..."}`
```bash
curl -X POST $BASE/api/v1/auth/refresh -H 'Content-Type: application/json' -d '{"refreshToken":"<rt>"}'
```
### GET /api/v1/auth/validate
用途:校验当前 token 是否有效。需登录(无空间可调用)。Handler: `internal/handler/auth.go`
响应:200 `{"success":true,"message":"Token is valid","user":{UserInfo}}`
```bash
curl $BASE/api/v1/auth/validate -H "Authorization: Bearer $TOKEN"
```
### POST /api/v1/auth/logout
用途:登出(失效当前 token)。需登录。无请求体。Handler: `internal/handler/auth.go`
响应:200 `{"success":true,"message":"Logout successful"}`
```bash
curl -X POST $BASE/api/v1/auth/logout -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/auth/me
用途:查询当前调用者身份(用户/空间/成员关系/能力)。需登录;API key 亦可(策略 `apiKeyAny()`,任何有效 key)。Handler: `internal/handler/auth.go`
响应:200 `{"success":true,"data":{"user":{UserInfo},"tenant":{TenantResponse},"memberships":[...],"tenant_required":bool,"capabilities":{"can_create_tenant":bool,"auto_accept_invitation":bool}}}`
```bash
curl $BASE/api/v1/auth/me -H "X-API-Key: $API_KEY"
```
### PUT /api/v1/auth/me/preferences
用途:更新个人偏好(最近活跃空间)。需登录。Handler: `internal/handler/auth.go`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `last_active_tenant_id` | *uint64 | 否 | 正整数设置/替换;`0` 清除(下次登录回 home);省略则不改。`POST /auth/switch-tenant` 成功时服务端会写同一字段。 |
响应:200 `{"success":true,"data":{UserPreferences}}`
```bash
curl -X PUT $BASE/api/v1/auth/me/preferences -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"last_active_tenant_id":2}'
```
密码策略由 `GET /auth/config` 提供。复杂模式允许的特殊字符集为 `!@#$%^&*()_+-=[]{}|;:,.<>?`;不能只根据结构体 binding 的长度标签推导完整校验规则。
### POST /api/v1/auth/change-password
用途:修改密码。需登录。Handler: `internal/handler/auth.go`
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `old_password` | string | 是(`binding:"required"`) | 旧密码 |
| `new_password` | string | 是(`binding:"required"`) | 新密码(8–32 位,字母+数字;复杂模式另需大小写和特殊字符) |
响应:200 `{"success":true,"message":"Password changed successfully"}`
```bash
curl -X POST $BASE/api/v1/auth/change-password -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -d '{"old_password":"old","new_password":"NewPass123!"}'
```
修改密码必须提供正确的旧密码,新密码不能与旧密码相同。成功后撤销全部会话,需要重新登录。默认策略 8–32 位、字母和数字;复杂模式要求大小写字母、数字和特殊字符。错误详情可为 `invalid_old_password`、`password_policy`、`same_password`,均返回 400。
### POST /api/v1/me/invitations/accept-by-token
需登录,仅操作当前用户,无空间的新用户也可调用。请求 `{"token":"<invite-token>"}`;有效共享邀请使当前用户加入对应空间。无效、过期、撤销的链接返回 410;空 token 返回 400。成功响应为 `{success:true,data:{membership:{tenant_id,role,status,joined_at},tenant_name}}`,前端据此切换空间。
```bash
curl -X POST "$BASE/api/v1/me/invitations/accept-by-token" \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"token":"<invite-token>"}'
```
## 我的邀请(/api/v1/me/invitations)
服务层保证“仅被邀请人可接受/拒绝”;无角色下限(无空间的新用户也可用)。Handler: `internal/handler/tenant_invitation.go`
### GET /api/v1/me/invitations
用途:列出发给我的邀请。
| 查询参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `include_terminal` | bool | 否 | `true` 时包含已完结的邀请 |
响应:200 `{"success":true,"data":{"invitations":[TenantInvitationResponse],"total":N}}`
```bash
curl $BASE/api/v1/me/invitations -H "Authorization: Bearer $TOKEN"
```
### GET /api/v1/me/invitations/pending-count
用途:待处理邀请计数(轻量轮询)。
响应:200 `{"success":true,"data":{"pending_count":N}}`
```bash
curl $BASE/api/v1/me/invitations/pending-count -H "Authorization: Bearer $TOKEN"
```
### POST /api/v1/me/invitations/:inv_id/accept
用途:接受邀请,写入成员关系。路径参数:`inv_id` 邀请 ID。无请求体。
响应:200 `{"success":true,"data":{"membership":{"tenant_id","role","status","joined_at"}}}`
```bash
curl -X POST $BASE/api/v1/me/invitations/12/accept -H "Authorization: Bearer $TOKEN"
```
### POST /api/v1/me/invitations/:inv_id/decline
用途:拒绝邀请。路径参数:`inv_id`。无请求体。
响应:200 `{"success":true}`
```bash
curl -X POST $BASE/api/v1/me/invitations/12/decline -H "Authorization: Bearer $TOKEN"
```
## 实现参考
docs: sync website-docs, homepage and changelog for v0.8.2 (#3632) * docs: sync website-docs with changes since v0.8.0 Audit every change between v0.8.0 and the v0.8.2 release against the documentation site, adding what users and operators need and correcting statements that no longer match the code. - Add local browser (BrowserSkill), built-in MCP Server endpoints, the toolbox, conversation steer/fork/rewind and reasoning effort, the artifacts library, sandbox terminal and desktop, the Lite host sandbox, the rebuilt model catalog (including a protocol-compat field reference), Confluence and DingTalk Docs sources, Bocha/Serply search, per-channel IM locale, whitelist-only outbound, admin user creation, new configuration variables and migrations 000091-000110. - Fix wrong API examples and parameters (model type values, knowledge search params, FAQ match_count cap, Notion credentials), tenant deletion semantics, default timeouts, parser engine claims, removed tables and commands, stale navigation paths, and route locations after the router split into routes_*.go. - Add screenshots for the new pages and refresh outdated ones. * fix(frontend): link the protocol-compat field to its documentation The model editor told users to read catalog/compat.go on the backend, a path that no longer exists after the model catalog refactor. The hint now says when the override is needed and links to the field reference in website-docs/03-features/06-models.md; the config examples and the API type comment point to the same place. * feat(website): showcase v0.8.2 on the homepage - Add a v0.8.2 section for the local browser (BrowserSkill), the built-in MCP Server and conversation control, and turn the v0.8.0 release block into a standing skills & sandbox topic with the sandbox desktop and terminal. - Replace the three-up galleries with a feature list beside one large screenshot: every item's text stays visible, clicking an item or one of its views switches the image with a cross-fade, and the list plays itself while on screen until the visitor picks something. - Add Confluence, DingTalk, BrowserSkill and more model vendors to the integrations, bump the header badge to v0.8.2 and link the changelog. - check-site reports missing docs screenshots as pending instead of failing, since the Screenshot component renders a placeholder for them. * docs(changelog): add v0.8.2 release notes * docs(website): add per-version release notes pages Add a "版本发布" docs section with one page per release, starting with v0.8.2 and a backfilled v0.8.0. Each page walks through the highlights with the existing product screenshots, the other improvements and fixes, and an upgrade checklist with the actions each breaking change needs. The sidebar orders these pages by version, newest first; the docs header gains a 版本 entry, and the homepage's v0.8.2 section now links to the release notes page instead of the raw CHANGELOG. * feat(website): let the site image listen on a configurable port The Docker image hard-coded `listen 80`, so running it with host networking or on a platform that assigns the container port required editing the Nginx config and rebuilding. The image now renders its config from the official nginx template directory at startup and reads the listen port from `PORT` (default 80); deploy/nginx.conf stays a plain config for static deployments. test-docker starts a second container with PORT=8080 and checks the rendered config and that the site answers on that port; the README documents the variable. * fix(website): namespace the nginx listen port variable * fix(website): support bash-wrapped container startup * fix(website): align nginx startup with frontend entrypoint * fix(website): pin nginx runtime for older host compatibility * fix(website): bake the configured nginx port into the image
2026-09-24 03:26:34 +00:00
路由注册:`internal/router/routes_auth_tenant.go` 的 `RegisterAuthRoutes` 与 `RegisterMyInvitationRoutes`。Handler:`internal/handler/auth.go`、`internal/handler/auth_register_by_invite.go`、`internal/handler/tenant_invitation.go`。