x-server-mobile/docs/modules/auth

认证模块 (Auth Module)

概述

认证模块负责用户登录、登出、token 管理等功能。支持多种登录方式：

登录方式	说明	文档
飞书内免登	在飞书客户端内自动登录	feishu-login.md
飞书外扫码登录	普通浏览器扫码登录	feishu-qrcode.md
邮箱密码登录	传统账号密码登录	-
飞书消息通知	飞书卡片消息通知	feishu-notification.md

---

核心功能

1. 飞书免登

用户在飞书客户端内打开应用时，自动完成登录，无需输入密码。

关键点：

• 使用 H5 JSSDK (h5-js-sdk-1.5.19.js)
• 调用 tt.requestAuthCode() 获取授权码
• 支持多租户（通过 company 参数）

2. Token 自动刷新

当 API 返回 401 时，在飞书环境中自动刷新 token，用户无感知。

流程：

API 返回 401
  ↓
检测飞书环境
  ↓
调用 tt.requestAuthCode 获取新授权码
  ↓
用新授权码登录获取新 token
  ↓
用新 token 重试原始请求

3. 扫码登录

用户在普通浏览器中使用飞书 APP 扫码登录。

---

API 接口

接口	方法	说明
/api/v1/auth/feishu-login	POST	飞书免登/扫码登录
/api/v1/auth/feishu-config	GET	获取公司飞书应用配置
/api/v1/auth/qrcode-login	POST	生成扫码登录二维码
/api/v1/auth/qrcode-login/status	GET	轮询扫码状态
/login/callback	GET	飞书授权回调
/api/v1/auth/login	POST	邮箱密码登录

---

前端关键文件

frontend/src/
├── pages/login/
│   ├── index.tsx           # 登录页主逻辑
│   └── QRCodeLogin.tsx     # 扫码登录组件
├── services/
│   └── api.ts              # API 封装（含 401 token 刷新）
└── stores/
    └── user.ts             # 用户状态管理

---

后端关键文件

backend/app/
├── Controller/
│   └── AuthController.php  # 认证控制器
├── Service/
│   └── FeishuService.php   # 飞书服务
└── Model/
    ├── User.php            # 用户模型
    └── CompanyFeishuApp.php # 飞书应用配置

---

环境变量

# 飞书应用配置（多租户时在数据库中配置）
FEISHU_APP_ID=cli_xxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxx
FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxxxxxxxx
FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxxxxxxxx

---

URL 参数

参数	说明	示例
company	公司ID（必需）	?company=2
app_id	飞书应用ID（可选）	?app_id=cli_xxx
redirect	登录成功后跳转地址	?redirect=/dashboard

---

常见问题

Q1: 飞书免登失败 "invalid appId"

A: 确保 URL 中有 company 参数，或直接传 app_id 参数。

Q2: 扫码后没反应

A: 检查飞书开放平台是否配置了正确的重定向 URL 白名单。

Q3: Token 过期后需要重新登录

A: 已实现自动刷新，在飞书环境中会自动获取新 token。

---

相关文档

• 飞书登录完整经验
• 飞书扫码登录详解
• 环境配置说明

---

负责人: mzl 最后更新: 2026-02-28