---
title: "身份验证"
description: "管理用户和身份验证。"
---

import { Card, Cards } from 'mintlify';

<Card
  title="POST /api/auth/login"
  href="#login"
>
  登录以获取 JWT 令牌。
</Card>

<Card
  title="POST /api/auth/register"
  href="#register"
>
  注册一个新用户。
</Card>

<Card
  title="GET /api/auth/user"
  href="#get-current-user"
>
  获取当前已验证的用户。
</Card>

<Card
  title="POST /api/auth/change-password"
  href="#change-password"
>
  更改当前用户的密码。
</Card>

---

### 登录

验证用户身份并返回 JWT 令牌及用户详细信息。

- **端点**: `/api/auth/login`
- **方法**: `POST`
- **正文**:
  - `username` (string, 必填): 用户名。
  - `password` (string, 必填): 用户密码。
- **请求示例**:
  ```json
  {
    "username": "admin",
    "password": "your-admin-password"
  }
  ```
- **成功响应**:
  ```json
  {
    "success": true,
    "message": "登录成功",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "username": "admin",
      "isAdmin": true,
      "permissions": { ... }
    }
  }
  ```

---

### 注册

注册一个新用户并返回 JWT 令牌。

- **端点**: `/api/auth/register`
- **方法**: `POST`
- **正文**:
  - `username` (string, 必填): 新的用户名。
  - `password` (string, 必填): 新的用户密码 (至少6个字符)。
  - `isAdmin` (boolean, 可选): 用户是否应有管理员权限。
- **请求示例**:
  ```json
  {
    "username": "newuser",
    "password": "password123",
    "isAdmin": false
  }
  ```
- **成功响应**:
  ```json
  {
    "success": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "username": "newuser",
      "isAdmin": false,
      "permissions": { ... }
    }
  }
  ```

---

### 获取当前用户

检索当前通过身份验证的用户的个人资料。

- **端点**: `/api/auth/user`
- **方法**: `GET`
- **身份验证**: 需要承载令牌 (Bearer Token)。
- **成功响应**:
  ```json
  {
    "success": true,
    "user": {
      "username": "admin",
      "isAdmin": true,
      "permissions": { ... }
    }
  }
  ```

---

### 更改密码

允许通过身份验证的用户更改其密码。

- **端点**: `/api/auth/change-password`
- **方法**: `POST`
- **身份验证**: 需要承载令牌 (Bearer Token)。
- **正文**:
  - `currentPassword` (string, 必填): 用户的当前密码。
  - `newPassword` (string, 必填): 新的密码 (至少6个字符)。
- **请求示例**:
  ```json
  {
    "currentPassword": "oldpassword",
    "newPassword": "newpassword123"
  }
  ```
- **成功响应**:
  ```json
  {
    "success": true,
    "message": "密码更新成功"
  }
  ```

---

### 社交登录 (Better Auth)

MCPHub 通过集成 [Better Auth](https://www.better-auth.com/) 支持社交登录功能（GitHub, Google 等）。

**前提条件**:
1.  **数据库模式**: 必须配置 `DB_URL` 环境变量（Better Auth 需要 PostgreSQL 进行数据持久化）。
2.  **启动配置**: Better Auth 相关设置只会在启动时读取一次，因此改完后需要重启 MCPHub。
3.  **环境变量**:
  *   **全局**: `BETTER_AUTH_ENABLED`、`BETTER_AUTH_URL`、可选 `BETTER_AUTH_BASE_PATH`、可选 `BETTER_AUTH_TRUSTED_ORIGINS`。
  *   **GitHub**: `BETTER_AUTH_GITHUB_ENABLED`、`GITHUB_CLIENT_ID`、`GITHUB_CLIENT_SECRET`。
  *   **Google**: `BETTER_AUTH_GOOGLE_ENABLED`、`GOOGLE_CLIENT_ID`、`GOOGLE_CLIENT_SECRET`。
  *   **本地 OIDC**: `BETTER_AUTH_OIDC_ENABLED`、可选 `BETTER_AUTH_OIDC_PROVIDER_ID`、`BETTER_AUTH_OIDC_DISCOVERY_URL`（或兼容别名 `OIDC_DISCOVERY_URL`）、可选 `BETTER_AUTH_OIDC_SCOPES`、可选 `BETTER_AUTH_OIDC_PKCE`、可选 `BETTER_AUTH_OIDC_PROMPT`，以及 `OIDC_CLIENT_ID`、`OIDC_CLIENT_SECRET`。

非敏感的 Better Auth 配置也可以保存在 `systemConfig.auth.betterAuth` 中，但 `BETTER_AUTH_*` 环境变量会优先覆盖它们。

**端点**:
Better Auth API 挂载在 `${BASE_PATH}${betterAuthConfig.basePath}`。默认路径是 `/api/auth/better`；可以用 `BETTER_AUTH_BASE_PATH` 在启动时覆盖，也可以把 `systemConfig.auth.betterAuth.basePath` 作为后备值。构建回调 URL 时，`BETTER_AUTH_URL` 会优先于 `systemConfig.install.baseUrl` 生效。主要端点包括：

- **发起登录**:
  - `GET /api/auth/better/signIn/social?provider=github`
  - `GET /api/auth/better/signIn/social?provider=google`

- **会话管理**:
  - `GET /api/auth/better/session` (获取当前会话)
  - `POST /api/auth/better/signOut` (登出)

如需完整的端点列表和使用详情，请参阅 [Better Auth API 文档](https://www.better-auth.com/docs)。

**禁用 Better Auth**:

如果未配置 `DB_URL`、设置了 `BETTER_AUTH_ENABLED=false`，或者没有任何提供商在满足凭据条件后真正启用，Better Auth 都会自动禁用。
