LangChat Pro 社交登录使用指南

本文档介绍如何配置和使用 LangChat Pro 的社交登录功能。

一、功能概述

LangChat Pro 支持以下社交登录方式：

登录方式	说明	状态
微信开放平台	适用于 C 端用户扫码登录	已实现
企业微信	适用于企业用户扫码登录	已实现
钉钉	适用于企业用户扫码登录	已实现
邮箱登录	使用邮箱验证码登录	已实现
手机登录	使用阿里云短信验证码登录	已实现

二、配置说明

2.1 配置文件

在 application-local.yml 或对应的环境配置文件中添加配置：

langchat:
  auth:
    # 社交登录配置
    social:
      # 是否启用社交登录
      enabled: true
      # 社交登录回调基础URL（用于扫码登录后重定向到前端页面）
      callback-url: ${SOCIAL_CALLBACK_URL}
      # 微信开放平台
      wechat:
        enabled: false
        app-id: ${WECHAT_APP_ID}
        app-secret: ${WECHAT_APP_SECRET}
        redirect-uri: ${WECHAT_REDIRECT_URI}
      # 企业微信
      enterprise-wechat:
        enabled: false
        corp-id: ${ENTERPRISE_WECHAT_CORP_ID}
        agent-id: ${ENTERPRISE_WECHAT_AGENT_ID}
        secret: ${ENTERPRISE_WECHAT_SECRET}
        redirect-uri: ${ENTERPRISE_WECHAT_REDIRECT_URI}
      # 钉钉
      dingtalk:
        enabled: false
        app-key: ${DINGTALK_APP_KEY}
        app-secret: ${DINGTALK_APP_SECRET}
        redirect-uri: ${DINGTALK_REDIRECT_URI}
      # 邮箱登录
      email:
        enabled: true
        host: smtp.example.com
        port: 465
        username: ${EMAIL_USERNAME}
        pass: ${EMAIL_PASSWORD}
        from: LangChat <${EMAIL_FROM}>
        ssl: true
      # 短信登录
      sms:
        enabled: false
        access-key-id: ${ALIYUN_SMS_ACCESS_KEY_ID}
        access-key-secret: ${ALIYUN_SMS_ACCESS_KEY_SECRET}
        sign-name: ${ALIYUN_SMS_SIGN_NAME}
        template-code: ${ALIYUN_SMS_TEMPLATE_CODE}

2.2 环境变量配置

创建 .env 文件或设置系统环境变量：

# 社交登录回调URL（前端页面地址，用于扫码登录后重定向）
export SOCIAL_CALLBACK_URL="https://your-domain.com"

# 微信开放平台
export WECHAT_APP_ID="your_app_id"
export WECHAT_APP_SECRET="your_app_secret"
export WECHAT_REDIRECT_URI="https://your-domain.com/auth/social/callback/wechat"

# 企业微信
export ENTERPRISE_WECHAT_CORP_ID="your_corp_id"
export ENTERPRISE_WECHAT_AGENT_ID="your_agent_id"
export ENTERPRISE_WECHAT_SECRET="your_secret"
export ENTERPRISE_WECHAT_REDIRECT_URI="https://your-domain.com/auth/social/callback/enterprise_wechat"

# 钉钉
export DINGTALK_APP_KEY="your_app_key"
export DINGTALK_APP_SECRET="your_app_secret"
export DINGTALK_REDIRECT_URI="https://your-domain.com/auth/social/callback/dingtalk"

# 阿里云短信
export ALIYUN_SMS_ACCESS_KEY_ID="your_access_key_id"
export ALIYUN_SMS_ACCESS_KEY_SECRET="your_access_key_secret"
export ALIYUN_SMS_SIGN_NAME="您的签名"
export ALIYUN_SMS_TEMPLATE_CODE="SMS_123456789"

# 邮箱
export EMAIL_USERNAME="your-email@example.com"
export EMAIL_PASSWORD="your-email-password"
export EMAIL_FROM="your-email@example.com"

三、API 接口

3.1 获取可用的登录类型

GET /auth/social/types

响应：
{
  "code": 200,
  "data": [
    {"code": "WECHAT", "name": "微信开放平台"},
    {"code": "ENTERPRISE_WECHAT", "name": "企业微信"},
    {"code": "DINGTALK", "name": "钉钉"},
    {"code": "EMAIL", "name": "邮箱"},
    {"code": "PHONE", "name": "手机"}
  ]
}

3.2 获取授权URL

GET /auth/social/authorize/{type}

参数：
  - type: 登录类型 (wechat/dingtalk/enterprise_wechat/email/phone)
  - redirect: 回调地址（可选）

响应：
{
  "code": 200,
  "data": {
    "authorizeUrl": "https://open.weixin.qq.com/...",
    "state": "xxx"
  }
}

3.3 社交登录

POST /auth/social/login

请求体：
{
  "type": "wechat",
  "code": "authorization_code",
  "state": "xxx"
}

响应：
{
  "code": 200,
  "data": {
    "success": true,
    "token": "xxx",
    "expiration": 86400,
    "userId": "xxx",
    "username": "xxx",
    "isNewUser": true,
    "userInfo": {...}
  }
}

3.4 发送验证码

POST /auth/social/code/send

请求体：
{
  "type": "email",
  "target": "user@example.com"
}

或：

{
  "type": "phone",
  "target": "13800138000"
}

3.5 验证验证码并登录

POST /auth/social/code/verify

请求体：
{
  "type": "email",
  "code": "123456",
  "target": "user@example.com"
}

或：

{
  "type": "phone",
  "code": "123456",
  "target": "13800138000"
}

3.6 绑定社交账号

POST /auth/social/bind

请求体：
{
  "type": "wechat",
  "code": "authorization_code",
  "state": "xxx"
}

3.7 解绑社交账号

DELETE /auth/social/unbind/{type}

参数：
  - userId: 用户ID（从Token中获取）
  - type: 社交类型

3.8 获取已绑定账号

GET /auth/social/bindings

响应：
{
  "code": 200,
  "data": [
    {
      "socialType": "WECHAT",
      "openId": "xxx",
      "nickname": "xxx",
      "avatar": "xxx",
      "bindTime": 1234567890
    }
  ]
}

四、使用示例

4.1 微信扫码登录流程

// 1. 点击微信登录按钮，跳转到社交登录页面
// 前端会自动调用 /auth/social/authorize/wechat 获取授权URL
// 然后跳转到微信扫码页

// 2. 用户扫码后，微信会重定向到配置的 redirect_uri
// redirect_uri 会带上 code 和 state 参数

// 3. 前端检测到 URL 中有 code 和 state
// 自动调用 /auth/social/login 完成登录

4.2 邮箱验证码登录

// 1. 发送验证码
await fetch('/auth/social/code/send', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'email',
    target: 'user@example.com'
  })
});

// 2. 用户输入验证码后登录
await fetch('/auth/social/code/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'email',
    code: '123456',
    target: 'user@example.com'
  })
});

4.3 手机验证码登录

// 1. 发送验证码
await fetch('/auth/social/code/send', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'phone',
    target: '13800138000'
  })
});

// 2. 用户输入验证码后登录
await fetch('/auth/social/code/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'phone',
    code: '123456',
    target: '13800138000'
  })
});

4.4 cURL 命令测试

# 获取可用的登录类型
curl http://localhost:8100/auth/social/types

# 获取微信授权URL
curl "http://localhost:8100/auth/social/authorize/wechat"

# 微信登录
curl -X POST "http://localhost:8100/auth/social/login" \
  -H "Content-Type: application/json" \
  -d '{"type":"wechat","code":"xxx","state":"xxx"}'

# 发送邮箱验证码
curl -X POST "http://localhost:8100/auth/social/code/send" \
  -H "Content-Type: application/json" \
  -d '{"type":"email","target":"user@example.com"}'

# 发送手机验证码
curl -X POST "http://localhost:8100/auth/social/code/send" \
  -H "Content-Type: application/json" \
  -d '{"type":"phone","target":"13800138000"}'

五、第三方平台配置

5.1 微信开放平台

在微信开放平台注册开发者账号
创建网站应用，获取 AppID 和 AppSecret
配置授权回调域：https://your-domain.com/auth/social/callback/wechat
申请网站应用扫码登录权限

5.2 企业微信

登录企业微信管理后台
创建自建应用，获取 AgentId 和 Secret
配置应用主页：https://your-domain.com
在应用设置中配置：
- OAuth可信域名：your-domain.com
- IP白名单：服务器出口IP

5.3 钉钉

登录钉钉开放平台
创建应用，获取 AppKey 和 AppSecret
配置回调域：https://your-domain.com/auth/social/callback/dingtalk
申请扫码登录权限

5.4 阿里云短信

开通阿里云短信服务
创建签名（需要审核通过）
创建模板（需要审核通过）
获取 AccessKey ID 和 AccessKey Secret
配置白名单（可选）

六、数据库配置

系统会自动创建 aigc_user_social 表用于存储用户社交账号绑定：

CREATE TABLE `aigc_user_social` (
  `id` VARCHAR(64) PRIMARY KEY COMMENT '主键',
  `user_id` VARCHAR(64) NOT NULL COMMENT '用户ID',
  `social_type` VARCHAR(20) NOT NULL COMMENT '社交类型: WECHAT/DINGTALK/ENTERPRISE_WECHAT/EMAIL/PHONE',
  `open_id` VARCHAR(128) NOT NULL COMMENT '第三方开放ID',
  `union_id` VARCHAR(128) COMMENT '微信unionId',
  `nickname` VARCHAR(64) COMMENT '第三方昵称',
  `avatar` VARCHAR(512) COMMENT '第三方头像',
  `access_token` VARCHAR(512) COMMENT '访问令牌',
  `refresh_token` VARCHAR(512) COMMENT '刷新令牌',
  `expires_in` BIGINT COMMENT '令牌过期时间',
  `status` TINYINT DEFAULT 1 COMMENT '状态: 0-禁用, 1-启用',
  `create_time` BIGINT COMMENT '创建时间',
  `update_time` BIGINT COMMENT '更新时间',
  INDEX `idx_user_id` (`user_id`),
  INDEX `idx_social_type_open_id` (`social_type`, `open_id`)
) COMMENT '用户社交账号绑定表';

七、常见问题

Q1: 微信登录返回 code 无效？

原因：授权码只能使用一次，且有效期为 5 分钟。解决：重新获取授权 URL，使用新的 code。

Q2: 企业微信扫码提示 “redirect_uri 与配置的授权完成回调域名不一致”？

解决：

检查 redirect-uri 配置是否与后台配置的可信域名一致
确保配置的域名是企业微信后台设置的 OAuth 可信域名
callback-url 必须配置为前端可访问的地址

Q3: 验证码发送失败？

检查：

邮箱配置是否正确（langchat.auth.social.email）
短信配置是否正确（langchat.auth.social.sms）
阿里云短信签名和模板是否审核通过

Q4: 回调地址被拒绝？

解决：检查 redirect-uri 配置是否与第三方平台配置的回调地址一致。

Q5: 登录后用户名为空或异常？

解决：

邮箱登录：用户名使用完整邮箱地址
手机登录：用户名使用完整手机号
其他登录：使用类型前缀 + 昵称/随机后缀

Q6: 新用户没有菜单权限？

解决：系统默认会在用户无权限时返回探索首页菜单。如需修改，配置：

langchat:
  auth:
    defaultMenu:
      enabled: true
      homeMenuId: acd27abc0fb323ef1a4f4c3581795690

八、版本历史

版本	日期	变更
2.3.3	2026-01-16	更新配置结构为 langchat.auth.social，支持企业微信、钉钉扫码登录
1.0.0	2024-01-15	初始版本

配置指南

使用指南

实现文档

内网穿透

社交登录使用指南

LangChat Pro 社交登录使用指南

一、功能概述

二、配置说明

2.1 配置文件

2.2 环境变量配置

三、API 接口

3.1 获取可用的登录类型

3.2 获取授权URL

3.3 社交登录

3.4 发送验证码

3.5 验证验证码并登录

3.6 绑定社交账号

3.7 解绑社交账号

3.8 获取已绑定账号

四、使用示例

4.1 微信扫码登录流程

4.2 邮箱验证码登录

4.3 手机验证码登录

4.4 cURL 命令测试

五、第三方平台配置

5.1 微信开放平台

5.2 企业微信

5.3 钉钉

5.4 阿里云短信

六、数据库配置

七、常见问题

Q1: 微信登录返回 code 无效？

Q2: 企业微信扫码提示 “redirect_uri 与配置的授权完成回调域名不一致”？

Q3: 验证码发送失败？

Q4: 回调地址被拒绝？

Q5: 登录后用户名为空或异常？

Q6: 新用户没有菜单权限？

八、版本历史

配置指南

使用指南

实现文档

内网穿透

​LangChat Pro 社交登录使用指南

​一、功能概述

​二、配置说明

​2.1 配置文件

​2.2 环境变量配置

​三、API 接口

​3.1 获取可用的登录类型

​3.2 获取授权URL

​3.3 社交登录

​3.4 发送验证码

​3.5 验证验证码并登录

​3.6 绑定社交账号

​3.7 解绑社交账号

​3.8 获取已绑定账号

​四、使用示例

​4.1 微信扫码登录流程

​4.2 邮箱验证码登录

​4.3 手机验证码登录

​4.4 cURL 命令测试

​五、第三方平台配置

​5.1 微信开放平台

​5.2 企业微信

​5.3 钉钉

​5.4 阿里云短信

​六、数据库配置

​七、常见问题

​Q1: 微信登录返回 code 无效？

​Q2: 企业微信扫码提示 “redirect_uri 与配置的授权完成回调域名不一致”？

​Q3: 验证码发送失败？

​Q4: 回调地址被拒绝？

​Q5: 登录后用户名为空或异常？

​Q6: 新用户没有菜单权限？

​八、版本历史

LangChat Pro 社交登录使用指南

一、功能概述

二、配置说明

2.1 配置文件

2.2 环境变量配置

三、API 接口

3.1 获取可用的登录类型

3.2 获取授权URL

3.3 社交登录

3.4 发送验证码

3.5 验证验证码并登录

3.6 绑定社交账号

3.7 解绑社交账号

3.8 获取已绑定账号

四、使用示例

4.1 微信扫码登录流程

4.2 邮箱验证码登录

4.3 手机验证码登录

4.4 cURL 命令测试

五、第三方平台配置

5.1 微信开放平台

5.2 企业微信

5.3 钉钉

5.4 阿里云短信

六、数据库配置

七、常见问题

Q1: 微信登录返回 code 无效？

Q2: 企业微信扫码提示 “redirect_uri 与配置的授权完成回调域名不一致”？

Q3: 验证码发送失败？

Q4: 回调地址被拒绝？

Q5: 登录后用户名为空或异常？

Q6: 新用户没有菜单权限？

八、版本历史