docs(hub): document HUB_DEV_LOGIN_BYPASS dev login in database README

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-20 21:09:14 +08:00
parent df66691d24
commit 5df1900ca8
1 changed files with 42 additions and 0 deletions
@@ -11,6 +11,48 @@
 登录走平台既有的飞书 OAuth：登录页的按钮指向 `/auth/feishu/<orgSlug>`，
 回调由 `src/admin/routes/authRoutes.ts` 处理并种下 session cookie。

+## 开发模式：用环境变量开启一键登录
+
+本地开发没有真实飞书 app 时，可以用环境变量开启一键登录，跳过飞书 OAuth，
+直接以现有 OWNER/ADMIN 身份登入后台。**仅限开发，不是生产登录路径。**
+
+### 怎么开
+
+在 `hub/.env` 里设：
+
+```sh
+HUB_DEV_LOGIN_BYPASS="true"
+```
+
+改完重启服务（`npm run dev`，或本地手动 `npx tsx src/server.ts`）。启动日志会
+打印一行 `DEV login bypass enabled: /database/dev-login ...` 作为确认。
+
+开启后：
+
+- `/database/admin` 登录页显示「⚡ 一键登录管理员」按钮
+- 后端注册 `/database/dev-login` 端点：按钮就是打它，它签发一个和飞书 OAuth
+  回调完全一样的 session，然后跳到 `/database/dashboard`
+
+### 怎么关
+
+把值设成 `false`（或 `0` / `no` / `off`），或删掉这一行。关闭后按钮消失、
+`/database/dev-login` 返回 404 —— 按钮和端点同进同退。
+
+### 双重门禁（重要）
+
+真正的开关是两个条件的**与**（判断在 `plugin.ts`）：
+
+```
+allowDevLoginBypass = (NODE_ENV !== "production") && HUB_DEV_LOGIN_BYPASS 为真
+```
+
+即：**只要 `NODE_ENV=production`，无论 `HUB_DEV_LOGIN_BYPASS` 设成什么，一键登录
+都强制关闭。** 生产始终只能走真实飞书 OAuth。
+
+> 提醒：`HUB_DEV_LOGIN_BYPASS` 是敏感开关，别把开着它的 `.env` 带到任何联网 /
+> 共享环境。整个旁路逻辑自包含在本目录（`plugin.ts` + `routes/databaseRoutes.ts`），
+> `src/admin` 的登录路由未受影响。
+
 ## 文件

 | 文件 | 职责 |