feat: add NocoBase browser OAuth login
This commit is contained in:
nac
+36
-20
@@ -1,23 +1,23 @@
|
||||
# 安装 NocoBase CRM MCP
|
||||
|
||||
这是一份供终端型 AI Agent 执行的通用安装协议，不依赖任何特定 Agent 或 MCP 客户端。用户只需要提供本链接、确认本机变更，并在隐藏提示中输入自己的 NocoBase Authorize Key。
|
||||
这是一份供终端型 AI Agent 执行的通用安装协议，不依赖任何特定 Agent 或 MCP 客户端。用户只需要提供本链接、确认本机变更，并在浏览器中登录自己的 NocoBase 账号完成授权。
|
||||
|
||||
如果你是安装 Agent，请直接执行流程，不要让用户逐条尝试命令。只有在确认系统工具变更、要求用户创建 Key，或让用户在隐藏提示中粘贴 Key 时才中断用户。
|
||||
如果你是安装 Agent，请直接执行流程，不要让用户逐条尝试命令。只有在确认系统工具变更或等待用户在 NocoBase 网页登录授权时才中断用户。
|
||||
|
||||
## 完成标准
|
||||
|
||||
- 下载本文件所在的同一固定 Release，不使用默认分支；
|
||||
- 只连接固定的 NocoBase API `https://justconn.top/api`；
|
||||
- MCP 在用户本机以 stdio 运行，默认只读；
|
||||
- 认证属于当前用户自己的个人 Authorize Key 和业务角色；
|
||||
- 通过 NocoBase 原生 OAuth 2.1 认证当前用户，权限仍跟随本人的业务角色；
|
||||
- 当前 MCP 客户端已注册 `nocobase-crm`；
|
||||
- `crm_health` 返回 `ok=true`。
|
||||
|
||||
## 安全规则
|
||||
|
||||
- 不索取账号密码，不使用共享服务账号或管理员 Key。
|
||||
- 不让用户把 Key 发到聊天、命令参数、环境变量、剪贴板日志或 MCP 配置。
|
||||
- Key 只能由用户输入到安装程序的本机隐藏 TTY 提示。
|
||||
- 不索取账号密码、OAuth Token 或 Authorize Key，不使用共享服务账号或管理员身份。
|
||||
- 用户只能在 `https://justconn.top` 的 NocoBase 页面输入账号信息并确认授权。
|
||||
- OAuth Token 不得进入聊天、命令参数、环境变量、CRM 配置、剪贴板日志或 MCP 客户端配置。
|
||||
- 不使用 `sudo`，不执行 `curl | sh` 或 `wget | sh`。
|
||||
- 不静默安装 Git、Node.js、包管理器或其他系统工具。
|
||||
- 修改 MCP 客户端配置前展示目标文件与新增项，创建备份，并结构化合并；不得覆盖其他 server。
|
||||
@@ -35,7 +35,7 @@
|
||||
- `donaldttt-nocobase-crm-mcp-<version>.tgz`；
|
||||
- `SHA256SUMS`。
|
||||
|
||||
仓库为 Private 时，必须使用当前用户已经授权的 GitHub 连接读取 Release；无权访问时停止，不得退回默认分支、源码 clone 或索取用户 GitHub Token 到聊天。
|
||||
仓库访问受限时，必须使用当前用户已经授权的代码托管平台连接读取 Release；无权访问时停止，不得退回默认分支、源码 clone 或索取用户的访问令牌到聊天。
|
||||
|
||||
### 2. 一次性说明本机变更
|
||||
|
||||
@@ -46,7 +46,7 @@
|
||||
正常安装只会留下：
|
||||
|
||||
- 应用数据目录中的 npm 包；
|
||||
- 不含 Key 的 CRM `config.json`；
|
||||
- 不含凭据的 CRM `config.json`；
|
||||
- 权限受限的本机凭证文件；
|
||||
- MCP 客户端配置及其备份。
|
||||
|
||||
@@ -54,7 +54,7 @@
|
||||
|
||||
### 3. 下载并验证固定发布物
|
||||
|
||||
通过已授权的 GitHub API/连接下载两个 Release 资产到新建的临时目录。验证 tarball 的 SHA-256 与 `SHA256SUMS` 完全一致；不一致立即停止并删除未使用的下载文件。
|
||||
通过当前 Gitea 实例或经批准分发渠道的已授权 API/连接，将两个 Release 资产下载到新建的临时目录。验证 tarball 的 SHA-256 与 `SHA256SUMS` 完全一致；不一致立即停止并删除未使用的下载文件。
|
||||
|
||||
选择用户级安装前缀，例如：
|
||||
|
||||
@@ -70,19 +70,33 @@ npm install --prefix <install-prefix> --omit=dev <verified-release.tgz>
|
||||
|
||||
定位安装后的命令：POSIX 为 `<install-prefix>/node_modules/.bin/nocobase-crm-mcp`，Windows 为相同目录下的 `nocobase-crm-mcp.cmd`。
|
||||
|
||||
### 4. 个人 Key 设置
|
||||
### 4. 浏览器登录 NocoBase
|
||||
|
||||
先引导用户在 NocoBase 个人设置中创建可撤销、有合理有效期、绑定本人普通业务角色的个人 Authorize Key。不要让用户把 Key 发给 Agent。
|
||||
|
||||
在用户可直接控制的本机终端运行：
|
||||
运行：
|
||||
|
||||
```bash
|
||||
<installed-command> setup --json
|
||||
```
|
||||
|
||||
安装程序会先验证安全 TTY，再显示固定 API 地址和隐藏 Key 提示；没有安全 TTY 时会在写文件前停止。Key 通过 `https://justconn.top/api/roles:check` 验证成功后才保存，并立即执行 `crm_health`。凭证文件只保存 Key，不保存或接受 API 地址。Key 不会出现在返回 JSON、命令参数、MCP 配置或日志中。
|
||||
安装程序通过 NocoBase 的 OAuth 发现接口动态注册本机公共客户端，请求 `api offline_access` 权限，并自动打开带确认码的 NocoBase 设备授权页。用户在网页中登录、核对确认码并点击授权；程序随后取得短期访问令牌和可撤销的刷新令牌，通过 `https://justconn.top/api/roles:check` 验证成功后保存，并立即执行 `crm_health`。
|
||||
|
||||
POSIX 凭证目录使用 `0700`，凭证文件使用 `0600`。Windows 使用当前用户应用数据目录。不要复制其他用户的凭证文件；每个操作系统用户都必须单独设置自己的 Key。
|
||||
浏览器没有自动打开时，安装程序会继续显示完整授权链接和确认码。可重新运行：
|
||||
|
||||
```bash
|
||||
<installed-command> setup --no-browser --json
|
||||
```
|
||||
|
||||
然后由用户手动打开链接。设备授权约十分钟后失效；密码和浏览器会话始终留在 NocoBase，安装程序不会读取浏览器 Cookie。访问令牌临近过期时会自动使用刷新令牌续期，不影响日常 MCP 调用。
|
||||
|
||||
POSIX 凭证目录使用 `0700`，凭证文件使用 `0600`。Windows 使用当前用户应用数据目录。凭证文件不保存或接受 API 地址，Token 不会出现在返回 JSON、命令参数、MCP 配置或日志中。不要复制其他用户的凭证文件；每个操作系统用户都必须单独登录。
|
||||
|
||||
只有在 OAuth 暂时不可用、管理员明确要求且用户拥有个人 Authorize Key 时，才使用：
|
||||
|
||||
```bash
|
||||
<installed-command> setup --manual-key --json
|
||||
```
|
||||
|
||||
该备用模式必须在用户可直接控制的安全 TTY 中隐藏输入 Key；仍不得让用户把 Key 发给 Agent。
|
||||
|
||||
### 5. 注册并验证 MCP
|
||||
|
||||
@@ -94,7 +108,7 @@ POSIX 凭证目录使用 `0700`，凭证文件使用 `0600`。Windows 使用当
|
||||
4. 重载或重启 MCP 客户端；
|
||||
5. 调用 `crm_health`，要求 `ok=true`。
|
||||
|
||||
最终只报告 Release、安装目录、配置备份位置和只读/写入模式，不显示任何 Key。
|
||||
最终只报告 Release、安装目录、配置备份位置、认证方式和只读/写入模式，不显示任何 Token 或 Key。
|
||||
|
||||
## 可选写入
|
||||
|
||||
@@ -102,14 +116,16 @@ POSIX 凭证目录使用 `0700`，凭证文件使用 `0600`。Windows 使用当
|
||||
|
||||
## 故障处理
|
||||
|
||||
- `nocobase_auth_failed`：让用户撤销失效 Key，重新运行同一个 setup 命令并在隐藏提示输入新 Key。
|
||||
- `nocobase_request_failed` / `NO_PERMISSIONS`：检查用户角色、字段权限、行级权限与 `config.json` 映射，不得换用共享高权限 Key。
|
||||
- 浏览器未打开：使用 `setup --no-browser`，让用户手动打开终端显示的 `justconn.top` 授权链接。
|
||||
- 授权超时或被取消：重新运行 `setup`，再次核对确认码并授权。
|
||||
- `nocobase_auth_failed`：重新运行 `setup` 完成浏览器登录；不要换用共享高权限 Token 或 Key。
|
||||
- `nocobase_request_failed` / `NO_PERMISSIONS`：检查用户角色、字段权限、行级权限与 `config.json` 映射，不得换用共享高权限身份。
|
||||
- Node.js 缺失：报告前置条件并请求用户授权正规安装，不退回 Python/uv/nb CLI 方案。
|
||||
- Private Release 无权访问：报告分发权限问题，不退回 clone 默认分支。
|
||||
- 受限 Release 无权访问：报告 Gitea 或分发渠道的权限问题，不退回 clone 默认分支。
|
||||
|
||||
## 用户可发送给 Agent 的最短指令
|
||||
|
||||
```text
|
||||
请按这个固定 Release 的协议帮我完成本机安装。默认只读，使用我自己的 NocoBase Authorize Key；只让我在本机隐藏提示中输入 Key，不要静默安装系统工具。完成前必须验证 crm_health：
|
||||
请按这个固定 Release 的协议帮我完成本机安装。默认只读；请运行 setup，让我只在 NocoBase 官方网页登录并确认授权。不要向我索要密码、Token 或 Authorize Key，也不要静默安装系统工具。完成前必须验证 crm_health：
|
||||
<固定 Release 的 INSTALL.md 链接>
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user