feat: add NocoBase browser OAuth login

2026-08-18 04:08:27 +00:00
parent 5c2cbac5b1
commit 4c53f90947
16 changed files with 1138 additions and 143 deletions
@@ -2,13 +2,13 @@

 ## 交付模型

-每位用户在自己的电脑运行 MCP，并使用绑定本人业务身份的个人 Authorize Key：
+每位用户在自己的电脑运行 MCP，并通过 NocoBase 原生 OAuth 登录本人业务身份：

 ```text
 本机 AI 客户端 → 本机 TypeScript MCP → https://justconn.top/api → 本人 ACL
 ```

-项目不保存共享业务账号，也不需要多人共用的远程 MCP 服务。
+项目不保存共享业务账号，也不需要多人共用的远程 MCP 服务。个人 Authorize Key 仅作为显式备用认证方式。

 ## Release 发布物

@@ -17,7 +17,7 @@ Release workflow 会在带版本 Tag 时执行锁定安装、类型/格式检查
 - npm tarball；
 - `SHA256SUMS`。

-源码仓库保持 Private 时，外部用户必须具有 Release 下载权限，或通过另一个经过身份认证的分发渠道取得相同资产。Private GitHub 链接本身不能成为任意用户可访问的一键安装链接。
+Gitea 仓库访问受限时，外部用户必须具有 Release 下载权限，或通过另一个经过身份认证的分发渠道取得相同资产。受限仓库链接本身不能成为任意用户可访问的一键安装链接。

 ## 用户电脑上的内容

@@ -33,24 +33,26 @@ Release workflow 会在带版本 Tag 时执行锁定安装、类型/格式检查

 至少使用两个权限不同的真实测试账号：

-1. 分别签发个人 Key，并在隔离的 OS 用户/凭证路径运行 setup。
+1. 分别使用两个账号在隔离的 OS 用户/凭证路径运行 setup，并在 NocoBase 网页授权。
 2. 使用相同参数调用 `list_customers`、`list_contacts`、`list_followups`、`list_projects`。
 3. 确认返回范围与各自在 NocoBase UI 中的 ACL 一致。
 4. 无项目写权限账号在 `--enable-writes` 下调用 `create_project`，确认 NocoBase 拒绝。
 5. 有权限账号创建和更新测试项目，确认审计身份属于该用户。
-6. 撤销 Key 后确认 MCP 返回 `nocobase_auth_failed`，且不会降级使用其他凭证。
-7. 检查错误与日志，确认没有 Key、Authorization header 或业务原始行泄漏。
+6. 让其中一个账号的 OAuth 会话失效，确认 MCP 自动刷新失败后返回 `nocobase_auth_failed`，且不会降级使用其他凭证。
+7. 检查错误与日志，确认没有访问令牌、刷新令牌、Authorization header、Key 或业务原始行泄漏。

 ## 更新与回滚

 Agent 下载新的固定 Release tarball并验证 SHA-256，再对同一隔离前缀运行 `npm install --prefix ... --omit=dev <tarball>`。安装前备份 MCP 客户端配置和非秘密 CRM 配置。

-回滚时重新安装上一固定 Release 的已验证 tarball。凭证文件与 CRM 配置位于包目录之外，更新和回滚不应复制、覆盖或删除个人 Key。
+回滚时重新安装上一固定 Release 的已验证 tarball。凭证文件与 CRM 配置位于包目录之外，更新和回滚不应复制、覆盖或删除个人 OAuth 凭据。

 ## 常见故障

- `nocobase_auth_failed`：重新运行 setup，让用户在隐藏提示输入新签发 Key。
+- `nocobase_auth_failed`：重新运行 setup，让用户在 NocoBase 网页重新授权。
+- 浏览器无法启动：使用 `setup --no-browser` 并手动打开显示的授权链接。
+- OAuth 服务暂时不可用：先报告服务状态；只有管理员明确要求时才使用 `setup --manual-key`。
 - `nocobase_request_timeout`：检查 NocoBase 可用性或缩小查询。
 - `nocobase_request_failed` / `NO_PERMISSIONS`：检查该用户 ACL 和字段/行级权限。
 - 凭证文件权限错误：POSIX 下修复为 `0600`，父目录为 `0700`，不要放宽为共享可读。
- 跨源重定向错误：检查 `https://justconn.top/api` 的反向代理配置；不要关闭同源保护。
+- OAuth 来源校验错误：检查 `https://justconn.top/api` 的反向代理与发现元数据；不要放宽固定来源保护。