Cheatsheets

Appearance

钉钉登录接入说明 ​

项目已增加钉钉扫码登录门禁，未登录用户无法访问 index.html 和 /api/* 接口。 当前登录页采用"点击按钮后跳转钉钉官方登录授权页"的方式完成扫码登录。

必填环境变量 ​

  • SESSION_SECRET：Session 会话密钥，生产环境务必使用高强度随机字符串
  • DINGTALK_CLIENT_ID：钉钉开放平台应用的 Client ID / AppKey
  • DINGTALK_CLIENT_SECRET：钉钉开放平台应用的 Client Secret / AppSecret

可选环境变量 ​

  • DINGTALK_REDIRECT_URI：钉钉回调地址；不填时默认使用当前访问域名自动拼接 /auth/dingtalk/callback
  • SESSION_COOKIE_SECURE=true：HTTPS 环境建议开启
  • DINGTALK_ALLOWED_USER_IDS：逗号分隔的员工 userId 白名单
  • DINGTALK_ALLOWED_UNION_IDS：逗号分隔的员工 unionId 白名单

钉钉开放平台配置 ​

在钉钉开放平台应用中配置回调地址，必须与实际登录使用的回调地址完全一致，例如：

https://your-domain.com/auth/dingtalk/callback

登录流程 ​

  1. 用户访问 / 时，如果未登录，会被重定向到 /login
  2. 点击"使用钉钉扫码登录"后跳转到钉钉授权页
  3. 浏览器跳转到钉钉官方授权页
  4. 用户使用钉钉 App 扫码确认后，钉钉回调 /auth/dingtalk/callback
  5. 服务端使用 code 换取用户令牌，并拉取当前员工信息
  6. 校验通过后写入 Session，进入主界面

本地运行 ​

bash
make run

如果你在本地联调钉钉登录，请确保回调地址已经在钉钉开放平台中备案，并且浏览器访问域名与回调地址一致。

登录页说明 ​

  • 登录页不会内嵌二维码，而是跳转到钉钉官方登录授权页
  • 如果钉钉侧返回无权限，通常是开放平台应用类型、授权范围或回调地址配置问题