feat: add secure personal key setup
This commit is contained in:
nac
+12
-17
@@ -2,7 +2,7 @@
|
||||
|
||||
## 交付模型
|
||||
|
||||
每位用户在自己的电脑运行 MCP，并使用自己的 NocoBase 账号登录 `nb` CLI：
|
||||
每位用户在自己的电脑运行 MCP，并使用绑定本人普通业务身份/角色的个人 API Key 登录 `nb` CLI：
|
||||
|
||||
```text
|
||||
本机 AI 客户端 → 本机 NocoBase CRM MCP → 本机 nb CLI 登录态 → 远程 NocoBase ACL
|
||||
@@ -20,7 +20,7 @@ MCP 不保存公共业务账号，也不需要部署一个多人共用的远程
|
||||
|
||||
## 推荐：链接驱动的 Agent 安装
|
||||
|
||||
正式发布后，优先把对应 Release Tag 下的 [`INSTALL.md`](../INSTALL.md) 不可变链接交给用户。该入口不是 Codex 专用插件：任何能够读取链接、执行本机终端并结构化修改 MCP 客户端配置的 Agent，都可以按协议完成安装。确定性工作由 `scripts/agent_install.py` 处理；Agent 负责识别操作系统与客户端、解释变更、备份并合并客户端配置；用户本人完成 OAuth 登录。
|
||||
正式发布后，优先把对应 Release Tag 下的 [`INSTALL.md`](../INSTALL.md) 不可变链接交给用户。该入口不是 Codex 专用插件：任何能够读取链接、执行本机终端并结构化修改 MCP 客户端配置的 Agent，都可以按协议完成安装。确定性工作由 `scripts/agent_install.py` 处理；Agent 负责识别操作系统与客户端、解释变更、备份并合并客户端配置；用户只在 NocoBase 获取个人 Key，并把它粘贴到本机隐藏提示。
|
||||
|
||||
发布方必须保证安装 Agent 能读取链接和相同版本的代码。当前仓库为 private 时，用户需要已经连接有仓库权限的 GitHub 账号；面向普通外部用户的一条链接安装，则必须公开该版本的 `INSTALL.md` 与发布物，或放到用户 Agent 可认证访问的分发渠道。不要把开发分支链接当作交付链接。
|
||||
|
||||
@@ -35,15 +35,14 @@ uv sync --locked
|
||||
cp config.example.json config.json
|
||||
```
|
||||
|
||||
`config.json` 中的 `env` 默认是 `nb-mcp`。用自己的账号创建并登录同名环境：
|
||||
`config.json` 中的 `env` 默认是 `nb-mcp`。正式终端用户不应手动尝试 `nb env add/auth`；安装 Agent 在用户可直接控制的本机终端中运行：
|
||||
|
||||
```bash
|
||||
nb env add nb-mcp --api-base-url https://nocobase.example/api --auth-type oauth
|
||||
nb env auth nb-mcp
|
||||
nb env info nb-mcp
|
||||
uv run --no-project --python 3.12 python scripts/agent_install.py \
|
||||
--project-root . connect-key --api-base-url https://nocobase.example --env-name nb-mcp --json
|
||||
```
|
||||
|
||||
`nb env auth` 会打开浏览器。用户必须亲自完成登录；不要向用户分发共享 API Key，也不要复制其他人的 `nb` 配置目录。
|
||||
Agent 先引导用户在 NocoBase 个人设置中创建可撤销、有合理有效期、绑定本人普通业务角色的 API Key。用户只把 Key 粘贴到 `nb` CLI 的隐藏 TTY 提示；脚本不接收或回显 Key，也不会把它放入命令参数、聊天、环境变量、临时文件或 MCP 配置。不要分发共享管理员 Key，也不要复制其他人的 `nb` 配置目录。
|
||||
|
||||
先进行健康检查：
|
||||
|
||||
@@ -51,11 +50,7 @@ nb env info nb-mcp
|
||||
uv run nocobase-crm-mcp --config config.json
|
||||
```
|
||||
|
||||
然后让 MCP 客户端调用 `crm_health`。如果返回 `nb_auth_failed`，重新执行：
|
||||
|
||||
```bash
|
||||
nb env auth nb-mcp
|
||||
```
|
||||
然后让 MCP 客户端调用 `crm_health`。如果返回 `nb_auth_failed`，由 Agent 重新启动 `connect-key`，用户在新的本机隐藏提示中输入新 Key；不要让用户手动尝试 `nb` 命令。
|
||||
|
||||
## MCP 客户端配置
|
||||
|
||||
@@ -98,7 +93,7 @@ Linux 用户也可以执行 `bash scripts/mcp_service.sh start` 安装用户级
|
||||
|
||||
交付前至少使用两个权限不同的测试账号验证：
|
||||
|
||||
1. 两台电脑或两个隔离的操作系统账号分别执行 `nb env auth nb-mcp`。
|
||||
1. 两台电脑或两个隔离的操作系统账号分别通过 Agent 的 `connect-key` 流程录入各自个人 Key。
|
||||
2. 使用相同参数调用 `list_customers`、`list_contacts`、`list_followups` 和 `list_projects`。
|
||||
3. 确认各自只能看到 NocoBase UI 中本人有权查看的数据。
|
||||
4. 对无项目写权限的账号调用 `create_project`，确认 NocoBase 拒绝。
|
||||
@@ -106,11 +101,11 @@ Linux 用户也可以执行 `bash scripts/mcp_service.sh start` 安装用户级
|
||||
6. 对有写权限的账号创建测试项目并完成上传、关联和移除，确认审计字段记录的是该用户，而不是共享服务账号。
|
||||
7. 退出或使 Token 过期后，确认 MCP 返回 `nb_auth_failed`，且不会降级使用其他凭证。
|
||||
|
||||
修改测试账号角色后，如果 `roles:check` 仍返回旧角色，先由管理员执行 `nb api app clear-cache`，再重新执行 `nb env auth <环境名>`。这是服务端角色缓存刷新，不应通过共享 Token 绕过。
|
||||
修改测试账号角色后，如果 `roles:check` 仍返回旧角色，先由管理员清理服务端角色缓存，再由 Agent 使用新签发的个人 Key 重新运行 `connect-key`。不应通过共享 Token 绕过。
|
||||
|
||||
## 凭证安全
|
||||
|
||||
- NocoBase Token 由 `nb` CLI 保存，不能写入 `config.json` 或 MCP 客户端配置。
|
||||
- 个人 API Key 由 `nb` CLI 保存，不能写入 `config.json`、MCP 客户端配置、聊天、Shell 历史或命令参数。
|
||||
- MCP 获取附件请求凭证时，Token 只存在于进程内存，不进入子进程参数和错误日志。
|
||||
- `.runtime/` 只保存本机 HTTP MCP 的独立 Bearer Token，并已被 Git 忽略。
|
||||
- 不要共享操作系统账号运行 MCP；本机权限隔离依赖每位用户拥有独立的 `nb` 登录存储。
|
||||
@@ -147,7 +142,7 @@ bash scripts/mcp_service.sh start
|
||||
|
||||
发布交付必须来自工作区干净、CI 全绿的带注释 Git Tag；不要从开发分支任意提交直接打包给用户。
|
||||
|
||||
需要备份的业务配置是 `config.json`。它不应包含 Token，可以进入受控版本库或企业配置备份。`.runtime/nocobase-crm-mcp.env` 只包含本机 HTTP Token 和运行参数；丢失后运行 `bash scripts/mcp_service.sh new-token` 重新生成即可。不要备份、复制或分发用户的 `nb` OAuth Token；恢复电脑后重新执行 `nb env add` 和 `nb env auth`。
|
||||
需要备份的业务配置是 `config.json`。它不应包含 Token，可以进入受控版本库或企业配置备份。`.runtime/nocobase-crm-mcp.env` 只包含本机 HTTP Token 和运行参数；丢失后运行 `bash scripts/mcp_service.sh new-token` 重新生成即可。不要备份、复制或分发用户的个人 Key；恢复电脑后重新签发 Key，并由 Agent 运行 `connect-key`。
|
||||
|
||||
建议监控：
|
||||
|
||||
@@ -160,7 +155,7 @@ bash scripts/mcp_service.sh start
|
||||
常见故障：
|
||||
|
||||
- `nb_not_found`：确认 `nb` 在 PATH 中，或设置 `NOCOBASE_MCP_NB_BIN` 为绝对路径。
|
||||
- `nb_auth_failed`：执行 `nb env auth nb-mcp`。
|
||||
- `nb_auth_failed`：由 Agent 重启 `connect-key`，用户只在本机隐藏提示中输入新 Key。
|
||||
- `NO_PERMISSIONS`：由 NocoBase 管理员调整该用户的角色、字段或行级数据权限。
|
||||
- 附件返回 `nb_upload_unauthorized`：重新登录后重试；不要把其他用户的 Token 写入环境变量。
|
||||
- 附件返回 `nb_upload_forbidden`：当前角色没有项目 create/update；不要为了绕过门禁而改用共享高权限账号。
|
||||
|
||||
Reference in New Issue
Block a user