身份验证

---

​

登录

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

• 端点: /api/auth/login
• 方法: POST
• 正文:
  • username (string, 必填): 用户名。
  • password (string, 必填): 用户密码。
• 请求示例:
  {
    "username": "admin",
    "password": "your-admin-password"
  }
  
• 成功响应:
  {
    "success": true,
    "message": "登录成功",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "username": "admin",
      "isAdmin": true,
      "permissions": { ... }
    }
  }
  
• 已禁用密码登录：当 Better Auth 的 disablePasswordLogin 生效时，该端点返回 403，正文为 {"success": false, "message": "..."}。参见 仅允许 SSO 登录。

---

​

注册

注册一个普通用户并返回 JWT 令牌。 本地自助注册要求 systemConfig.auth.allowRegistration: true（默认关闭）且密码登录可用，否则返回 HTTP 403。新账号始终为普通用户；isAdmin 参数不生效。密码至少八位，包含字母、数字和特殊字符。

• 端点: /api/auth/register
• 方法: POST
• 正文:
  • username (string, 必填): 新的用户名。
  • password (string, 必填): 新的用户密码（至少八位，包含字母、数字和特殊字符）。
  • 不能申请管理员权限；isAdmin 参数会被忽略。
• 请求示例:
  {
    "username": "newuser",
    "password": "Password123!"
  }
  
• 成功响应:
  {
    "success": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "username": "newuser",
      "isAdmin": false,
      "permissions": { ... }
    }
  }
  

---

​

获取当前用户

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

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

---

​

更改密码

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

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

---

​

社交登录 (Better Auth)

MCPHub 通过集成 Better Auth 支持社交登录功能（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 文档。 禁用 Better Auth: 如果未配置 DB_URL、设置了 BETTER_AUTH_ENABLED=false，或者没有任何提供商在满足凭据条件后真正启用，Better Auth 都会自动禁用。