feishu-sso-login

一个命令为任意静态网站叠加飞书扫码登录能力

零依赖 · 自包含 · npx 即用

npx feishu-sso-login --root ./dist --title "我的应用" --app-id cli_xxx --app-secret xxx

用户用飞书 App 扫码后，PC 浏览器直接跳转首页，无需手动刷新。

特性

• 零依赖 — 仅使用 Node.js 内置模块（http/https/fs/crypto）
• 自包含 — 认证服务器 + 登录页面全内嵌，不污染用户项目
• 官方 SDK — 使用飞书 QRLogin SDK，扫码后 PC 端自动回调
• 公网自适应 — 通过 X-Forwarded-Host 自动适配 localtunnel/Nginx
• 一键启动 — npx feishu-sso-login 或 npx feishu-sso-login --root ./dist

快速开始

前置条件

1. 飞书开放平台 创建自建应用
2. 应用能力 → 启用「网页应用」，桌面端主页 URL 填 http://localhost:8080
3. 权限管理 → 开通 contact:user.base:readonly
4. 安全设置 → 重定向 URL 添加 http://localhost:8080/auth/callback

启动

# 最简用法（在当前目录启动）
npx feishu-sso-login \
  --app-id cli_xxxxx \
  --app-secret xxxxxxxx

# 指定静态文件目录和品牌名
npx feishu-sso-login \
  --root ./dist \
  --title "我的应用" \
  --app-id cli_xxxxx \
  --app-secret xxxxxxxx \
  --port 3000

# 也支持环境变量
FEISHU_APP_ID=cli_xxx FEISHU_APP_SECRET=xxx npx feishu-sso-login --root ./dist

效果

1. 浏览器访问 http://localhost:8080 → 自动跳转 /login
2. 登录页显示飞书二维码 → 用飞书 App 扫码
3. 飞书 App 确认授权 → PC 浏览器直接跳转首页（无需手动刷新）
4. 首页正常显示你的项目内容

CLI 参数

| 参数 | 必填 | 默认值 | 说明 | |------|------|--------|------| | --root | 是 | 当前目录 | 要托管的静态文件目录 | | --title | 否 | 飞书扫码登录 | 登录页显示的品牌名称 | | --app-id | 是 | — | 飞书应用 App ID（也可用 FEISHU_APP_ID 环境变量） | | --app-secret | 是 | — | 飞书应用 App Secret（也可用 FEISHU_APP_SECRET 环境变量） | | --port | 否 | 8080 | 服务端口（也可用 PORT 环境变量） |

API 接口

脚本内置以下路由，用户项目可直接调用：

| 路由 | 方法 | 说明 | |------|------|------| | /login | GET | 返回内嵌的登录页面 | | /auth/qr-login-url | GET | 返回飞书 QRLogin SDK 所需的 goto URL | | /auth/login | GET | 重定向到飞书授权页（账号密码登录） | | /auth/callback | GET | OAuth 回调，code 换 token 获取用户信息 | | /auth/me | GET | 返回当前登录用户信息 JSON | | /auth/logout | GET | 退出登录，清除 session | | / 或 /*.html | GET | 受保护页面，未登录跳转 /login | | 其他路径 | GET | 直接返回静态文件 |

获取登录用户信息

在用户项目的页面中调用 /auth/me 即可获取当前登录用户：

fetch('/auth/me', { credentials: 'same-origin' })
  .then(r => r.json())
  .then(data => {
    if (data.logged_in) {
      console.log('用户:', data.user.name);
      console.log('头像:', data.user.avatar_url);
    }
  });

返回数据结构：

{
  "logged_in": true,
  "user": {
    "name": "张三",
    "en_name": "San Zhang",
    "avatar_url": "https://...",
    "open_id": "ou_xxx",
    "union_id": "on_xxx",
    "email": "[email protected]",
    "mobile": "+86xxx"
  }
}

公网部署

方式一：localtunnel（快速测试）

# 终端 1：启动服务
npx feishu-sso-login --root ./dist --app-id cli_xxx --app-secret xxx

# 终端 2：穿透公网
npx localtunnel --port 8080 --subdomain my-app

然后在飞书开放平台添加公网重定向 URL：https://my-app.loca.lt/auth/callback

脚本通过 X-Forwarded-Host 自动适配公网域名，无需修改代码。

方式二：Nginx 反向代理（生产环境）

server {
    listen 443 ssl;
    server_name auth.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

飞书重定向 URL 配置为：https://auth.example.com/auth/callback

在 AI Coding 工具中使用

方式一：npx（推荐，适用于任何 AI 工具）

只需告诉 AI：

"我想把这个文件发布到公网，需要飞书扫码访问"

AI 会执行：

npx feishu-sso-login --root ./dist --app-id cli_xxx --app-secret xxx

方式二：WorkBuddy Skill

本工具也作为 WorkBuddy Skill 分发，安装后支持自动触发。

架构

用户浏览器                  认证服务器 (feishu-sso-login)           飞书开放平台
     │                              │                                  │
     │  GET /                       │                                  │
     │  (未登录)                     │                                  │
     │ <──── 302 /login ─────────── │                                  │
     │                              │                                  │
     │  飞书 QRLogin SDK 渲染二维码    │                                  │
     │                              │                                  │
     │  飞书 App 扫码                │                                  │
     │  postMessage(tmp_code)        │                                  │
     │  → 跳转 passport.feishu.cn    │                                  │
     │                              │                                  │
     │ ────────────────────────────────── 授权确认 ─────────────────────>│
     │                              │                                  │
     │ <──── 302 /auth/callback ───────── code + state ─────────────────│
     │                              │                                  │
     │  code 换 token → 获取用户信息  │                                  │
     │                              │                                  │
     │ <──── 302 / + Set-Cookie ─── │                                  │
     │                              │                                  │
     │  GET / (带 sid cookie)        │                                  │
     │ <──── 用户项目的 index.html ──│                                  │

注意事项

• Session 存储：使用内存 Map，服务重启后 session 失效。生产环境建议接入 Redis
• HTTPS：飞书回调要求 HTTPS，公网部署时使用 localtunnel/Nginx 自动提供
• Code 一次性：授权码只能使用一次，有效期 5 分钟
• 应用发布：开发版本只能被应用管理员使用，如需全员使用请发布应用版本

License

MIT