feat: use each user's local NocoBase login

2026-08-14 11:33:14 +00:00
parent 76e4cbf58a
commit 51d1493a2f
20 changed files with 1561 additions and 315 deletions
@@ -0,0 +1,151 @@
+# 本机交付与登录手册
+
+## 交付模型
+
+每位用户在自己的电脑运行 MCP，并使用自己的 NocoBase 账号登录 `nb` CLI：
+
+```text
+本机 AI 客户端 → 本机 NocoBase CRM MCP → 本机 nb CLI 登录态 → 远程 NocoBase ACL
+```
+
+MCP 不保存公共业务账号，也不需要部署一个多人共用的远程 MCP 服务。NocoBase 仍是最终权限裁决者；同一个工具由不同用户调用时，只能返回或修改其账号 ACL 允许的数据。
+
+## 环境要求
+
+- Python 3.12 或更高版本
+- `uv`
+- NocoBase `nb` CLI 2.1 或更高版本
+- 可通过浏览器访问目标 NocoBase
+- 管理员已为用户配置所需的 NocoBase 角色与数据权限
+
+## 首次安装
+
+```bash
+git clone https://github.com/Donaldttt/nocobase-mcp.git
+cd nocobase-mcp
+uv sync --locked
+cp config.example.json config.json
+```
+
+`config.json` 中的 `env` 默认是 `nb-mcp`。用自己的账号创建并登录同名环境：
+
+```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
+```
+
+`nb env auth` 会打开浏览器。用户必须亲自完成登录；不要向用户分发共享 API Key，也不要复制其他人的 `nb` 配置目录。
+
+先进行健康检查：
+
+```bash
+uv run nocobase-crm-mcp --config config.json
+```
+
+然后让 MCP 客户端调用 `crm_health`。如果返回 `nb_auth_failed`，重新执行：
+
+```bash
+nb env auth nb-mcp
+```
+
+## MCP 客户端配置
+
+推荐使用 stdio。把绝对路径替换成用户电脑上的实际安装目录：
+
+```json
+{
+  "mcpServers": {
+    "nocobase-crm": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/absolute/path/to/nocobase-mcp",
+        "run",
+        "--no-sync",
+        "nocobase-crm-mcp",
+        "--config",
+        "/absolute/path/to/nocobase-mcp/config.json"
+      ]
+    }
+  }
+}
+```
+
+默认只读。如需项目创建和更新，在参数末尾加入 `--enable-writes`。这些写工具只允许预先定义的项目字段，不提供删除或任意资源访问能力。
+
+附件上传需要可选的本机 HTTP 模式。它默认只监听 `127.0.0.1:10087`，不得暴露到局域网或公网：
+
+```bash
+NOCOBASE_MCP_TOKEN='<随机长字符串>' \
+  uv run nocobase-crm-mcp --transport streamable-http --config config.json
+```
+
+Linux 用户也可以执行 `bash scripts/mcp_service.sh start` 安装用户级 systemd 服务。
+
+## 权限验收
+
+交付前至少使用两个权限不同的测试账号验证：
+
+1. 两台电脑或两个隔离的操作系统账号分别执行 `nb env auth nb-mcp`。
+2. 使用相同参数调用 `list_customers`、`list_contacts`、`list_followups` 和 `list_projects`。
+3. 确认各自只能看到 NocoBase UI 中本人有权查看的数据。
+4. 对无项目写权限的账号调用 `create_project`，确认 NocoBase 拒绝。
+5. 对有写权限的账号创建测试项目，确认审计字段记录的是该用户，而不是共享服务账号。
+6. 退出或使 Token 过期后，确认 MCP 返回 `nb_auth_failed`，且不会降级使用其他凭证。
+
+## 凭证安全
+
+- NocoBase Token 由 `nb` CLI 保存，不能写入 `config.json` 或 MCP 客户端配置。
+- MCP 获取附件请求凭证时，Token 只存在于进程内存，不进入子进程参数和错误日志。
+- `.runtime/` 只保存本机 HTTP MCP 的独立 Bearer Token，并已被 Git 忽略。
+- 不要共享操作系统账号运行 MCP；本机权限隔离依赖每位用户拥有独立的 `nb` 登录存储。
+- `NOCOBASE_MCP_API_TOKEN` 只为旧部署兼容保留，不用于终端用户交付。
+- `include_raw=true` 默认被 MCP 拒绝。只有在管理员审核 `config.json` 字段和 AI 数据使用政策后，才可在该用户本机设置 `NOCOBASE_MCP_ENABLE_RAW_DATA=1`。
+
+## 更新、回滚与恢复
+
+更新前记录当前版本，更新后重新同步锁定依赖并运行测试：
+
+```bash
+git rev-parse HEAD
+git pull --ff-only
+uv sync --locked
+uv run python -m unittest discover -s tests
+```
+
+使用 systemd 本机 HTTP 服务时，再执行：
+
+```bash
+bash scripts/mcp_service.sh start
+bash scripts/mcp_service.sh status
+journalctl --user -u nocobase-crm-mcp.service -n 200 --no-pager
+```
+
+如果新版本验收失败，切回上一步记录的已发布 Tag 或 Commit，然后重新同步并启动：
+
+```bash
+git switch --detach <previous-release-tag-or-commit>
+uv sync --locked
+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`。
+
+建议监控：
+
+- MCP 客户端定期调用 `crm_health`。
+- 本机 HTTP 用户执行 `bash scripts/mcp_service.sh status`，确认 systemd active 且 HTTP probe reachable。
+- 日志只检查错误码和命令退出状态；发现业务原始数据或 Token 时立即停止交付并按安全事件处理。
+
+## 常见故障
+
+常见故障：
+
+- `nb_not_found`：确认 `nb` 在 PATH 中，或设置 `NOCOBASE_MCP_NB_BIN` 为绝对路径。
+- `nb_auth_failed`：执行 `nb env auth nb-mcp`。
+- `NO_PERMISSIONS`：由 NocoBase 管理员调整该用户的角色、字段或行级数据权限。
+- 附件返回 `nb_upload_unauthorized`：重新登录后重试；不要把其他用户的 Token 写入环境变量。
+- 环境连接错误：执行 `nb env info nb-mcp`，确认 `apiBaseUrl` 指向目标环境的 `/api`。