登录与 SSO

平台支持账号密码登录与企业单点登录（SSO）。登录成功后以 JWT 作为管理端访问令牌，并进入项目选择。

账号密码登录

1. 打开前端地址，例如本地 http://localhost:7001。
2. 输入账号与密码，点击登录。
3. 登录成功后进入【工作台】，并弹出项目选择。

登录过程中的安全规则：

项目	规则
传输安全	登录页必须部署在 HTTPS 下；密码不会以明文存储
密码存储	服务端仅保存 BCrypt 哈希，无法逆向还原
令牌类型	JWT，默认有效期 2 小时（7200000 ms）
令牌失效	过期后返回 401 / 41005，需要重新登录
无角色	账号未分配角色不允许登录，返回 41003
无菜单	角色未关联任何菜单不允许登录，返回 41004
登录失败	账号或密码错误返回 41001

生产部署

请务必启用 HTTPS，修改默认管理员密码，并按最小权限原则为账号分配角色。不要在公网环境使用默认账号密码。

登录态与项目上下文

• 前端把登录响应中的令牌写入 Cookie，后续请求自动携带 Authorization。
• 登录后必须选择项目；管理端业务请求会自动携带 X-Project-Id。
• 刷新页面不会丢失登录态，除非令牌过期或用户主动退出。
• 修改密码后，建议重新登录以刷新令牌。

企业微信扫码登录

登录页提供企业微信入口，点击后：

1. 前端向后端请求企业微信授权参数。
2. 页面加载企业微信官方扫码脚本，在弹层中展示二维码。
3. 扫码确认后跳转到回调地址。
4. 后端换取企业微信用户身份，与本平台账号绑定或匹配。
5. 登录成功，进入项目选择。

钉钉登录

钉钉采用跳转授权：

1. 点击钉钉登录。
2. 浏览器跳转到钉钉授权地址。
3. 授权完成后回调平台。
4. 后端校验 state 并换取用户信息，完成登录或绑定。

飞书

当前版本前端未开放飞书登录入口；如部署环境已配置飞书 SSO，可通过后端接口与回调地址接入，具体以部署配置为准。

SSO 回调处理

回调负责：

• 解析回调参数与 state。
• 调用后端交换登录令牌。
• 成功后写入登录态并跳转工作台。
• 失败时展示错误原因，并提供返回登录页的入口。

常见失败原因：

原因	处理
state 不匹配或过期	重新发起 SSO，不要复用旧回调地址
企业应用未配置可信域名	在企微/钉钉后台配置回调域名
用户未绑定平台账号	由管理员在系统中绑定，或按部署策略自动创建
授权参数获取失败	检查企业应用 Secret、AgentId、回调地址配置

退出登录

点击右上角用户菜单中的退出，平台会清除本地令牌并回到登录页。退出仅影响当前浏览器会话，不会禁用账号。

与开放接口认证的区别

场景	认证方式
管理端页面与后台接口	JWT（账号登录 / SSO）
开放 REST 接口	无认证 / 简单认证（AppKey）/ 签名认证（AppKey + AppSecret）
MCP（凭证）	X-AppKey
MCP（智能体）	X-Agent-Key

开放接口不使用管理端 JWT，管理端令牌也不能直接调用开放接口。

相关阅读：权限模型、签名认证。