# BeeX 管理后台登录说明

更新日期：2026-07-17
适用站点：`https://admin.beexofficial.com`

## 给运营的一句话

BeeX 管理后台使用飞书组织账号登录。打开后台后会跳转到飞书授权；授权成功才会显示页面。切换印尼测试、印尼生产等环境，只改变当前操作的数据环境，不需要重新申请一套后台账号。

## 正常登录步骤

1. 打开 `https://admin.beexofficial.com`。
2. 页面跳转到 `https://sso.beexofficial.com/admin/auth/feishu/login`。
3. 使用 BeeX 已授权飞书组织内的账号完成授权。
4. SSO 校验账号所属组织，创建会话并跳回管理后台。
5. 后台顶部显示当前登录人。配置保存、回滚、灰度和发布会记录该操作人。

## 常见问题

### 显示“没有权限”

优先检查：

- 当前飞书账号是否属于已配置的 BeeX 飞书组织；
- 飞书应用是否已对该成员或对应部门开放；
- SSO 环境变量中的 Tenant Key 是否是飞书返回的 `tenant_key`，而不是企业编号；
- 浏览器是否禁用了跳转、Cookie 或本地存储。

### 登录后又跳回登录页

通常表示会话不存在、已过期，或 SSO 与当前国家 admin-service 没有读取同一套 Redis 会话数据。清除站点本地存储后重登；若仍复现，检查 Redis 地址、库号及 `bx:prd:session:*`。

### 本地打开页面为什么不跳飞书

`localhost`、`127.0.0.1`、局域网地址和 `.local` 域名只跳过前端页面守卫，方便开发预览。它们不会绕过服务端鉴权：调用 admin-service 业务接口仍需要有效的 `Authorization: Bearer <sessionId>`。

## 当前技术实现

### 1. 前端页面守卫

`beex-admin-page/console-core.js` 中的 `authGuard`：

- SSO 固定入口：`https://sso.beexofficial.com`；
- 会话保存在 `localStorage.bx_admin_session`；
- 首次回跳从查询参数 `prd_session` 取回会话，再清理 URL；
- 页面展示前调用 `GET /admin/auth/feishu/verify`；
- 校验失败、网络异常或 CORS 异常均清理登录态并重新进入登录流程，不再失败放行；
- 已验证会话在前端缓存 5 分钟，减少多页后台和 iframe 重复校验。

### 2. 独立 SSO 服务

仓库 `beex-sso`，公开域名 `sso.beexofficial.com`：

| 接口 | 作用 |
| --- | --- |
| `GET /admin/auth/feishu/login?redirect=<url>` | 生成一次性 state 并跳转飞书授权页 |
| `GET /admin/auth/feishu/callback?code=&state=` | 校验 state、换取飞书用户、校验组织、创建会话并回跳 |
| `GET /admin/auth/feishu/verify` | 通过 Bearer session 校验当前登录人 |

state 使用 Redis key `bx:prd:oauth:state:*`，有效期 5 分钟；会话使用 `bx:prd:session:*`，默认有效期 7 天。登录后的回跳地址必须命中 `beexofficial.com` 白名单，防止开放重定向泄露会话。

### 3. admin-service 接口守卫

各国家环境的 `beex-admin-service` 通过 `AdminApiAuthInterceptor` 默认拦截服务内所有 `/api/v1/**` 接口：

- 必须携带 `Authorization: Bearer <sessionId>`；
- admin-service 从与 SSO 共享的 Redis 校验 `bx:prd:session:*`；
- 无会话或会话过期返回 `401 UNAUTHORIZED`；
- 校验通过后把飞书用户写入请求属性，供审计和操作人记录使用。

明确的机器接口或特殊入口采用单独 token/白名单校验，不依赖浏览器飞书会话：

- H5 包注册：`POST /api/v1/admin/h5-packages`，生产和测试都必须配置 `X-Pipeline-Token`；
- TikTok 只读诊断接口：必须配置并携带诊断 token；
- App 内文案编辑：由接口自身校验 BeeX 用户及审校人员白名单；
- 云监控、CI 图片上传等机器回调：由各自控制器的 token 或签名规则负责。

## 当前边界与后续要求

- **已经完成**：飞书登录、Tenant 校验、Redis 会话、前端失败关闭、admin-service 默认接口鉴权、操作人透传。
- **仍需完善**：按菜单、动作、国家和环境划分细粒度 RBAC。目前已认证的后台用户仍可能拥有过大的业务操作范围。
- **发布硬约束**：`SEAHUB_ADMIN_API_AUTH_ENABLED` 在线上必须为 `true`；H5 流水线注册 token 不能为空；新增 `/api/v1/**` 接口默认继承拦截器，禁止通过前端隐藏按钮代替服务端授权。

详细架构与时序见 [管理后台鉴权方案](./auth-design.html)。