Skip to content

Commit 54d9f73

Browse files
claudeclaude
committed
docs(zh-Hans): translate the new Configure admin pages (5 pages)
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0145MY7RdJr8KuRMyn5oKAR6
1 parent 11d1cec commit 54d9f73

5 files changed

Lines changed: 554 additions & 0 deletions

File tree

‎content/docs/configure/index.zh-Hans.mdx‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: 管理
3+
description: 系统管理员在哪里管理用户、访问、设置与集成 —— 以及哪个页面解决哪类任务。
4+
---
5+
6+
# 管理
7+
8+
本章面向 ObjectOS 部署的**系统管理员**：负责用户入职、授予访问权限、接通登录、邮件、存储与集成，并保持系统健康运转的人。你日常管理的是人和他们的权限；应用、对象和权限集本身则随平台及你安装的应用包一起交付。
9+
10+
> **权限在 Studio 中设计，在 Setup 中分配。**绝大多数管理工作都不会离开 Setup（管理后台）——只有编写权限集或运行解释引擎时才需要进入 Studio。
11+
12+
## Setup 控制台
13+
14+
内置的管理控制台位于 **`/apps/setup`**，需要 `setup.access` 权限。其左侧导航由运行时已加载的能力插件动态提供，因此你看到的菜单精确反映当前部署所运行的内容——未启用的能力不贡献任何菜单项，其分组保持为空。
15+
16+
稳定的导航分组：
17+
18+
| 分组 | 里面有什么 |
19+
|---|---|
20+
| **Overview**（概览） | System Overview 系统概览仪表盘 |
21+
| **People & Organization**（人员与组织） | 用户、业务单元、团队、组织、邀请 |
22+
| **Access Control**（访问控制） | 岗位、权限集、共享规则、记录共享、API Key |
23+
| **Approvals**（审批） | 审批流程（加载 approvals 插件时） |
24+
| **Configuration**（配置） | 全部设置、品牌、认证、邮件、文件存储、AI 与 Embedder、知识库、功能开关 |
25+
| **Diagnostics**（诊断） | 会话、通知事件、审计日志 |
26+
| **Integrations**（集成） | Webhooks |
27+
| **Advanced**（高级） | OAuth 应用、签名密钥（JWKS）、身份关联、用户偏好 |
28+
29+
## 任务地图
30+
31+
| 我需要 …… | 阅读 |
32+
|---|---|
33+
| 添加用户、搭建组织树、管理团队 | [用户与组织](/docs/configure/users) |
34+
| 为某人办理入职、离职或调整访问权限 | [权限分配](/docs/configure/permissions/managing-access) |
35+
| 理解整套访问模型 | [权限](/docs/configure/permissions) |
36+
| 配置登录、OAuth、SSO、双因素认证 | [认证](/docs/configure/authentication) |
37+
| 修改运行时和租户设置 | [系统设置](/docs/configure/system-settings) |
38+
| 配置事务性邮件发送 | [邮件](/docs/configure/email) |
39+
| 配置文件存储（S3、本地磁盘） | [存储](/docs/configure/storage) |
40+
| 连接外部业务数据库 | [数据源](/docs/configure/data-sources) |
41+
| 使用 REST API 和 API Key | [API 访问](/docs/configure/api-access) |
42+
| 发送出站 Webhook | [Webhooks](/docs/configure/webhooks) |
43+
| 配置 AI Provider、Embedder、RAG | [AI 服务](/docs/configure/ai) |
44+
| 接入 Claude 或其他 MCP 客户端 | [接入 AI 工具（MCP）](/docs/configure/mcp) |
45+
| 配置制品加载、数据库、缓存 | [运行时配置](/docs/configure/runtime) |
46+
| 规划备份与灾难恢复 | [备份](/docs/operate/backup) |
47+
| 安全地升级或回滚 | [升级](/docs/operate/upgrade) |
48+
| 为生产环境加固 | [生产就绪](/docs/operate/production) |
49+
| 查看日志、指标和审计记录 | [可观测性](/docs/operate/observability) |
50+
| 诊断故障部署 | [故障排查](/docs/operate/troubleshooting) |
51+
52+
## 下一步
53+
54+
| 任务 | 页面 |
55+
|---|---|
56+
| 你的第一项管理任务：添加人员并搭建结构 | [用户与组织](/docs/configure/users) |
57+
| 给新员工开通访问权限 | [权限分配](/docs/configure/permissions/managing-access) |
58+
| 学习分层访问模型 | [权限](/docs/configure/permissions) |
59+
| 上线前检查清单 | [生产就绪](/docs/operate/production) |

‎content/docs/configure/mcp.zh-Hans.mdx‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
---
2+
title: 接入 AI 工具（MCP）
3+
description: 把 Claude Code、Claude Desktop 或任意 MCP 客户端指向你的 ObjectOS 应用，让 Agent 在你的权限模型约束下处理你的数据。
4+
---
5+
6+
# 接入 AI 工具（MCP）
7+
8+
每个 ObjectOS 部署天生就是一个 MCP 服务器。运行时在 **`/api/v1/mcp`** 上提供 [Model Context Protocol](https://modelcontextprotocol.io) 服务——默认开启，无需安装插件，无需配置步骤。你的对象和已暴露的操作在定义的那一刻就成为带类型的工具；剩下唯一要做的就是接入一个客户端并验证它能用。
9+
10+
> 要关闭这个入口，设置 `OS_MCP_SERVER_ENABLED=false`——端点将返回 404，**Setup → Connect an Agent**（接入 Agent）页面也随之消失。
11+
12+
本页讲的是把*外部* AI 工具接入你的应用。服务端 AI 栈——聊天 Provider、Embedder、RAG，以及在代码中显式注册 MCP 服务器插件——参见 [AI 服务](/docs/configure/ai)。
13+
14+
## Claude Code（一条命令）
15+
16+
交互式客户端使用 OAuth——每个部署本身就是一个 OAuth 2.1 授权服务器，因此不存在需要管理员签发再分发的凭据。第一次工具调用会打开浏览器登录，你**以自己的身份**接入：
17+
18+
```bash
19+
# 本地开发服务器
20+
claude mcp add --transport http my-app http://localhost:3000/api/v1/mcp
21+
22+
# 已部署的实例
23+
claude mcp add --transport http my-app https://your-deployment.example.com/api/v1/mcp
24+
```
25+
26+
无头场景（CI、容器）跳过 OAuth，改为附加 [API Key](#headless-api-keys)：
27+
28+
```bash
29+
claude mcp add --transport http my-app https://your-deployment.example.com/api/v1/mcp \
30+
--header "x-api-key: osk_..."
31+
```
32+
33+
## Claude Desktop 与 claude.ai
34+
35+
**Settings → Connectors → Add custom connector**（设置 → 连接器 → 添加自定义连接器），然后粘贴 MCP URL（`https://your-deployment.example.com/api/v1/mcp`）。首次使用时会走同样的浏览器登录流程。
36+
37+
## 任意 MCP 客户端（`.mcp.json`）
38+
39+
读取 `mcpServers` 映射的客户端以同样方式接入。使用 API Key：
40+
41+
```json
42+
{
43+
"mcpServers": {
44+
"objectstack": {
45+
"type": "http",
46+
"url": "https://your-deployment.example.com/api/v1/mcp",
47+
"headers": { "x-api-key": "osk_..." }
48+
}
49+
}
50+
}
51+
```
52+
53+
## 无头场景：API Key
54+
55+
在 **Setup → Connect an Agent**（接入 Agent，那里还提供各客户端可直接复制粘贴的接入片段）中签发 Key，或通过 REST：
56+
57+
```bash
58+
curl -b cookies.txt -X POST https://your-deployment.example.com/api/v1/keys
59+
# → { "key": "osk_..." } —— 只显示一次；存入你的 secret manager
60+
```
61+
62+
每次请求以三种等价形式之一携带它：
63+
64+
| 请求头 | 示例 |
65+
|---|---|
66+
| `x-api-key` | `x-api-key: osk_...` |
67+
| `Authorization: ApiKey` | `Authorization: ApiKey osk_...` |
68+
| `Authorization: Bearer` | `Authorization: Bearer osk_...`（通过 `osk_` 前缀识别） |
69+
70+
> OAuth 要求 TLS——纯 HTTP 部署（`localhost` 除外）会回退到**仅 API Key** 模式：浏览器登录通道被禁用，而不是被允许以不安全的方式运行。
71+
72+
对于长期集成，把 Key 绑定到带最小权限集的专用服务用户——参见[服务账号与 API Key](/docs/configure/users#service-accounts--api-keys)。
73+
74+
## Agent 能得到什么
75+
76+
十个数据与操作工具，由你的元数据生成：
77+
78+
| 工具 | 用途 |
79+
|---|---|
80+
| `list_objects` / `describe_object` | 发现有哪些对象及其字段 |
81+
| `query_records` / `get_record` | 读取数据（列表查询默认每页上限 50 行） |
82+
| `aggregate_records` | 分组聚合（当前驱动支持时才注册） |
83+
| `create_record` / `update_record` / `delete_record` | 写入数据 |
84+
| `list_actions` / `run_action` | 按名称发现并调用你的业务操作 |
85+
86+
要了解的两条暴露规则：
87+
88+
- **对象自动暴露**——但 `sys_*` 系统对象除外，它们以 fail-closed 方式被拦截。
89+
- **操作需要作者显式选择加入**：`ai: { exposed: true }` 加上不少于 40 个字符的 `ai.description`，且该操作必须可以在无 UI 的情况下调用（带 body 或已注册 handler 的 `script`，或 `flow`）。
90+
91+
## 权限强制执行
92+
93+
- **每次调用都以调用者身份运行。**MCP 桥接解析的执行上下文与 REST 请求相同，因此对象权限、[记录访问](/docs/configure/permissions/record-access)和[字段级安全](/docs/configure/permissions/field-level-security)对 Agent 的作用与对 UI 中的真人完全一致。结果稀疏或写入被拒，通常意味着治理在*正常工作*，而不是连接坏了。
94+
- **OAuth scope 会收窄工具集。**Token 携带 `data:read`、`data:write` 和 `actions:execute` 这些 scope——不在已授予 scope 内的工具，在该会话中根本不会被注册。API Key 和会话调用者获得完整工具集，但每次调用仍会做权限检查。
95+
- **操作体一经调用即作为可信应用代码运行**（`ai.exposed` 门槛和 `requiredPermissions` 在*调用*时检查）。把编写操作当作值得代码评审的行为——那才是真正的安全边界。
96+
- 操作还可以声明 `ai.requiresConfirmation`；看起来具有破坏性的操作默认要求确认。
97+
98+
## 验证连接
99+
100+
问 Agent 一个只有实时 schema 才能回答的问题：
101+
102+
```text
103+
What objects does this app have, and what fields does the main one carry?
104+
```
105+
106+
你应该看到 `list_objects` 和 `describe_object` 被触发。Agent 的自然工作模式是 `list_objects` → `describe_object` → `query_records` → `run_action`——四者都能跑通，连接就完全就绪了。
107+
108+
> 配上应用的 **skill 文件**，Agent 的表现会明显更好：从 `GET /api/v1/mcp/skill` 下载它，或安装[官方 Claude 插件](https://github.com/objectstack-ai/claude-plugin)（`claude plugin marketplace add objectstack-ai/claude-plugin`），后者打包了该 skill 和一个引导式的 `/objectstack:connect` 命令。
109+
110+
## 故障排查
111+
112+
| 症状 | 原因 → 解决 |
113+
|---|---|
114+
| `/api/v1/mcp` 返回 `404` | 入口被禁用——取消设置 `OS_MCP_SERVER_ENABLED`（默认开启） |
115+
| `501 Not Implemented` | 此构建不包含 MCP 插件——检查你的栈的插件配置 |
116+
| 每次调用都 `401` | 匿名或凭据无效。交互式客户端：完成浏览器登录。无头场景：检查 `osk_` Key 和请求头拼写 |
117+
| `403 insufficient_scope` | OAuth token 缺少该工具族所需的 scope（例如没有 `data:write` 却尝试写入）——重新连接并授予该 scope |
118+
| 某个操作没出现在 `list_actions` 中 | `ai.exposed` 不为 `true`、`ai.description` 短于 40 个字符、类型不可无头调用（`url` / `modal` / `form` 永远不会出现）、目标是 `sys_*` 对象，或调用者未通过其 `requiredPermissions` |
119+
| 读取返回的行很少 / 写入被拒 | 符合设计——调用者的权限和记录访问在生效。用同一用户在 UI 中验证 |
120+
121+
## 下一步
122+
123+
| 任务 | 页面 |
124+
|---|---|
125+
| 配置 AI Provider、Embedder 和 MCP 服务器插件 | [AI 服务](/docs/configure/ai) |
126+
| 创建服务用户和 API Key | [用户与组织](/docs/configure/users) |
127+
| 理解 Agent 被允许看到什么 | [权限](/docs/configure/permissions) |
128+
| REST API 与 Key 管理 | [API 访问](/docs/configure/api-access) |
129+
| 验证某个用户的访问权限 | [权限分配](/docs/configure/permissions/managing-access) |

‎content/docs/configure/permissions/field-level-security.zh-Hans.mdx‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
title: 字段级安全
3+
description: 隐藏或锁定单个字段 —— 授予语义、服务端强制执行，以及 FLS 在表单、视图和 API 中的行为。
4+
---
5+
6+
# 字段级安全
7+
8+
字段级安全（FLS）控制单个字段的可见性与可编辑性，作用于对象权限和[记录访问](/docs/configure/permissions/record-access)已经允许用户触达该记录*之后*。它是实现"支持人员能看到客户，但看不到其 `annual_revenue`"和"销售代表能读外部 id 但永远不能改"的那一层。
9+
10+
FLS 规则存在[权限集](/docs/configure/permissions/permission-sets)中——本页比那里的[字段安全附录](/docs/configure/permissions/permission-sets#field-security-appendix)更深入地讲解授予语义与强制执行。
11+
12+
## 字段权限授予
13+
14+
字段权限以 `<object>.<field>` 为键，使用 `readable` / `editable`：
15+
16+
```ts
17+
fields: {
18+
// 只读：可见但不可编辑
19+
'account.annual_revenue': { readable: true, editable: false },
20+
'account.description': { readable: true, editable: true },
21+
// 隐藏：完全不可见
22+
'account.ssn': { readable: false, editable: false },
23+
'opportunity.amount': { readable: true, editable: true },
24+
'opportunity.probability': { readable: true, editable: false },
25+
}
26+
```
27+
28+
两个标志产生三种状态：
29+
30+
| 状态 | 规则 | 效果 |
31+
|---|---|---|
32+
| **隐藏** | `{ readable: false, editable: false }` | 字段完全不可见——从每个响应中剥离 |
33+
| **只读** | `{ readable: true, editable: false }` | 字段会返回，但对它的写入会被拒绝 |
34+
| **可编辑** | `{ readable: true, editable: true }` | 字段可见且可写 |
35+
36+
> 字段权限键务必写成**带对象限定**的形式（`crm_lead.budget`，而不是 `budget`）——自 ObjectStack 14.4 起，`security-fls-unqualified-key` lint 会在编译时拒绝裸键，因为它们会静默地匹配不到任何东西。
37+
38+
## 授予如何合并
39+
40+
FLS 使用**默认可见（黑名单）语义**：没有显式规则的字段原样通过——既可读*又*可写。权限集只约束它显式列出的字段。
41+
42+
字段授予在用户的多个权限集之间按**最宽松**方式取并集：一个权限集的 `readable: true` 会压过另一个权限集的 `false`。在减法式屏蔽层落地之前（已保留为 ADR-0066 ⑧），`{ readable: false }` 规则只有在**用户持有的其他任何权限集**都没有声明该字段 `readable: true` 时才会遮蔽它。实际影响：
43+
44+
- 保护敏感字段的方式是**只**在需要它们的权限集中授予——绝不要指望某个权限集里的 `false` 规则去覆盖别处的 `true`。
45+
- 把出现在广泛授予的对象上的敏感字段视为评审警讯。
46+
47+
已声明的规则本身以 fail-closed 方式强制执行：被遮蔽的字段在读取时被剥离，对不可编辑字段的写入会抛错。
48+
49+
## API 中的强制执行
50+
51+
SecurityPlugin 中间件在服务端强制执行字段规则，与请求来路无关——REST、ObjectQL 或任何其他路径。不存在通过更底层 API 的后门。
52+
53+
**读取时**——`find` / `findOne` 的结果在响应离开引擎之前，会从每条记录中剥离不可读字段。
54+
55+
**写入时**——`insert` / `update` 请求在操作到达驱动**之前**被检查。如果请求体包含任何调用者无权编辑的字段，引擎抛出 `PermissionDeniedError`（HTTP 403），并附上违规字段名：
56+
57+
```json
58+
{
59+
"error": {
60+
"code": "PERMISSION_DENIED",
61+
"message": "[Security] Field write denied: not permitted to edit [salary, ssn] on 'employee'",
62+
"details": {
63+
"operation": "insert",
64+
"object": "employee",
65+
"forbiddenFields": ["salary", "ssn"]
66+
}
67+
}
68+
}
69+
```
70+
71+
**为什么抛错而不是静默剥离？**静默剥离对诚实的客户端隐藏了安全边界（它们的更新"存不上"却不知道为什么），*同时*对探测型客户端也不给任何信号。抛错让边界在两个方向上都可观测——正当的 UI 得到可据以修复的错误；探测型客户端学不到任何它本来推断不出的东西。
72+
73+
另外两个强制执行细节：
74+
75+
- **批量插入**逐行检查；任意一行中出现一个违规字段，整个批次会被原子性拒绝。
76+
- **系统操作**（`ExecutionContext { isSystem: true }`）完全绕过该检查——用于迁移、种子数据加载和审计日志写入。
77+
78+
## FLS 在表单和视图中
79+
80+
生成的表单和内联表格会在 UI 中隐藏不可编辑字段——但那只是 **UX 层**。上文的服务端检查才是事实来源，因此行为在所有地方保持一致：
81+
82+
| 界面 | 隐藏字段 | 只读字段 |
83+
|---|---|---|
84+
| 记录表单 / 内联表格 | 不渲染 | 渲染但无可编辑控件；直接尝试写入会被 403 拒绝 |
85+
| 列表视图、相关列表、导出 | 列值从响应中剥离 | 值正常显示 |
86+
| REST / ObjectQL | 从结果中剥离 | 读取时返回；写入抛出带 `forbiddenFields` 的 `PERMISSION_DENIED` |
87+
| MCP / AI Agent | 剥离——Agent [以调用用户身份运行](/docs/configure/mcp#permission-enforcement) | 与 REST 相同 |
88+
89+
由于读取是剥离而不是报错，隐藏字段对该用户来说就像不存在一样——这正是目的所在。
90+
91+
## 验证与评审 FLS
92+
93+
- **按判定、在运行时**——[解释引擎](/docs/configure/permissions#diagnose--audit)会连同其他每一层一起报告 FLS 层的判定结果，并点名起作用的权限集。当用户反馈字段"不见了"时用它。
94+
- **按变更、在构建时**——如果你的应用启用了访问矩阵快照门禁，`os compile` 会把推导出的（权限集 × 对象）能力矩阵与已提交的 `access-matrix.json` 做 diff，并在漂移时失败，让能力变更以可评审的语义 diff 形式随 Pull Request 流转：
95+
96+
```bash
97+
os compile --update-access-matrix
98+
```
99+
100+
> 当字段承载敏感数据时，默认选**隐藏**而不是只读——只读仍会把值泄漏进响应和日志。把字段规则打包进匹配真实职能的权限集，并为合规场景配套审计日志留存。更多编写模式：[权限集](/docs/configure/permissions/permission-sets#field-security-appendix)。
101+
102+
## 下一步
103+
104+
| 任务 | 页面 |
105+
|---|---|
106+
| 在权限集中编写字段规则 | [权限集](/docs/configure/permissions/permission-sets) |
107+
| 控制哪些行完全可触达 | [记录访问](/docs/configure/permissions/record-access) |
108+
| 纵览整套分层模型 | [权限](/docs/configure/permissions) |
109+
| 验证某个用户的访问权限 | [权限分配](/docs/configure/permissions/managing-access) |
110+
| 检查 AI Agent 能读到什么 | [接入 AI 工具（MCP）](/docs/configure/mcp) |

0 commit comments

Comments
 (0)