tako 文档 GitHub

28 · 多租户运行时(个人 tenant 先行,团队 tenant 后开)

性质:已落地(2026-10-21 收口)。A0–A6 共 30 拍全部落地并 curl 验收过,随 9c21b66 入库(2026-10-19)。 验收结论(2026-10-21 活体抽验,引擎 127.0.0.1:8942、独立库、Redis db 8,本篇 18 项断言全过): 注册即建个人 tenant 且 role=owner;两个用户落在不同 tenant;跨租户读会话 log 回 404、读 run frames 回 200 且 status:"gone"(19v6-01 的 gone 契约,不是 404);建团队 → 切租户 → 邀成员 → 对方用邀请注册 → 切进团队拿到 role=member;member 再邀人回 403;owner 读成员列表 code=0。 施工期的逐拍实测实录在 tmp/28-多租户/(30 拍各自的 curl 与期望字节)与 doc/log/2026-10-19-多租户-handoff.md。 这一批明确没做的(是边界,不是待办):① 团队 model_ref / tools 未接,worker 仍用进程启动时的全局模型与全局 mcp.json, 不按 tenant_settings 装——「配置已落库」不等于「这场 run 换了模型」;② 团队前端页面(独立 loop, 见 doc/36,2026-10-21 已落地)。 A7 那一档的进度(2026-10-22):旧 runs/sessions/mcp/media/memory 成功体换 {code,message,data} 信封 已落地(见 doc/40);A7 剩下的计费/API key/SSO/组织共享 2026-10-22 已拍不做——与运行时关系不大的商业化、合规项,从路线图移除。 2026-10-18 已拍三条(A0 施工前):① A0-1/A0-2 先用静态 dev 用户脚手架——可以; ② A0-3/A0-4/A0-5 预计 90–100 行、略超 80 目标——接受;③ A0 期间现有业务端点仍裸奔——正常,A1 补门。 本篇替换 2026-10-18 之前的 doc/28 草稿:X-Tako-Tenant 声明式方案不再作为施工面。 范围:身份、租户、成员、角色、会话归属、notes、workspace、配额、后台管理、团队(A6 后端)。 不在本篇:团队前端页面、组织/跨租户共享、API key、SSO、账单。 关联:doc/16 #9、doc/17:362、doc/10:193、doc/03 多副本目标、doc/34(租户运行时装配)、 doc/36(团队前端)、doc/37(删除连带删)。

这版相对旧稿改了什么。

0. 大白话版

tako 要做的是什么。 不是“单机聊天工具”,是多租户 agent 运行时 + 会话:一个部署里有很多租户,每个租户有自己的用户、会话、agent、记忆、文件和配额;租户之间不能互相看见。

四层关系,一句话:

平台(platform)
  └─ 租户 tenant(隔离 + 计费 + 配额)
       ├─ 成员 tenant_members(user + role + status)
       ├─ 会话 sessions(tenant_id + user_id + visibility)
       │    └─ run(一次执行)
       ├─ agent(租户级资源,creator + visibility)
       ├─ notes(tenant 共享 / user 私有)
       └─ workspace / files / sandbox(租户级隔离)

团队功能已拍支持,怎么做。 每个用户注册时自动得到一个个人 tenant(单成员);团队是多成员 tenant。 A6 做团队后端 API(创建、邀请、成员/角色、团队 agent/notes);团队前端页面是独立 loop,但 A6 契约要够前端直接用。 用户可以在多个 tenant 之间切换,个人数据不搬家。

Alice 的一天。

Alice 注册
  → 自动建 personal tenant t_alice,Alice 是 owner
Alice 建 session s1(private)
  → s1.tenant_id=t_alice, s1.user_id=alice
Bob 和 Alice 在同一个团队 Acme(另一个 tenant)
  → Bob GET s1:404(private,不是他的)
Carol 在另一个 tenant
  → Carol GET s1:404(跨租户)
Alice 加入 Acme
  → 只多一条 tenant_members(t_acme, alice, member)
  → 她切到 Acme,看到 Acme 的 agent/notes;s1 仍在个人 tenant
Acme owner 邀请 Bob
  → Bob 接受后成为 member;团队共享 agent/notes,但 session 仍默认私有

五个关键决定。

  1. tenant 是一等公民:所有资源带 tenant_id;不搞“个人资源 + 可空 team_id”的双路径。
  2. 个人 tenant 先行,团队 tenant A6 后端落地:个人 tenant 现在就能用;团队后端 A6 做,团队前端页面独立 loop;表结构、token、切租户 API 从 A0 起按多租户做。
  3. session 默认私有:同租户普通成员也读不到别人的会话;团队共享要显式 visibility=tenant。
  4. notes 分 scope:user 私有、tenant 共享;模型默认只写个人记忆,团队记忆由 owner/admin 管。
  5. 文件/沙箱/配额是 P0:多租户 agent 运行时不能共用一个全局 workspace,也不能让一个租户占满所有并发。

分几步走。

故意不做。 不做公开注册以外的账号体系;不做 OIDC/SSO;不做组织/跨租户共享;不做 API key capability;不做计费;不做团队嵌套/部门树;不做“管理员默认读所有会话”。这些都留了缝,但不在本方案施工。

所以这解决了什么。 tako 从“谁有 sessionId 谁就是主人”变成“tenant + user + role + 会话归属”四重边界;个人用户今天就能用,团队以后只是多一条 membership,不用搬 session/notes/files;后台管理有平台管理员和租户角色两条轴,不会把“空间管理员”和“平台管理员”混成一个 role。

1. 背景与病灶

1.1 代码现状(2026-10-18 核对)

事实 出处
HTTP 面不止四个:/api/runs(POST/stop/resume)、/api/runs/:id(status)、frames、stream、/api/sessions/:id(status/log)、/api/mcp/servers、/api/media、/api/memory/*;全部无鉴权 server.go:61-90
sessions 只有 ID/Title/CreatedAt,没有 tenant/user pgstore.go:26
POST 带 sessionId 只查“存在吗”,不查“是谁的” server.go:187
AcquireRun 无条件 INSERT sessions ... ON CONFLICT DO NOTHING,不看 tenant/user store.go:136
SessionStatus/ReadLog/StopRun 只按 sessionId/runId pgstore.go:179、pgstore.go:348、store.go:571
ReadFrames 只按 runId 读 Redis,不查归属 redisstore.go:169
notes 按全局 workspace 分区,与 session/user 无关 notes.go:106
notes 的快照/定位/写入都只看 workspace notes.go:336、notes.go:350、notes.go:614
file tools/bash/memory 在 NewWorker 启动时捕获一个全局 workspace worker.go:163、worker.go:179、worker.go:191
子代理并发闸是进程级 channel,全部租户共享 agents.go:258
-dev 默认 true,dev/reset 全局清库 main.go:95

1.2 病灶:四个具体的失败故事

故事一:跨租户读会话。 Alice 在 tenant A 建了 session s_1,把链接贴给 Bob。Bob 在 tenant B,直接 GET /api/sessions/s_1。今天服务端只问“s_1 存在吗”,存在就返回 200;Bob 读到 Alice 和 agent 的整场对话,还能 POST /api/runs 往会话里投消息、POST /stop 停掉 Alice 的 run。

故事二:笔记暗道。 Alice 让 agent 记下“deck 在 output/deck.html,不要重建”。Bob 在 tenant B 开自己的 run,agent 起手读 notes 快照——notes 按全局 workspace 分区,Bob 读到的是 Alice 的记忆,并在回答里把路径说出来。API 全守住了,记忆这条暗道照旧全通。

故事三:文件暗道。 文件工具和 bash 共用一个 -workspace 根。Bob 不需要碰 Alice 的 session:自己开一个 run,让 agent cat 共享目录里的文件,就能读到 Alice 的方案、代码、上传的文档。

故事四:配额与并发。 tenant A 开了 50 个会话、每会话一个 run,把模型配额和子代理的 8 个槽位占满;tenant B 的 run 排队等不到子代理。更糟的是,所有租户共用同一个 eino agent 实例,doc/17 的 #1177 共享实例并发 race 从“同一个人多标签页”升级成“两个租户并发可能互相取消/串状态”。

四个故事同根:系统里没有“tenant/user/role”这三个概念。 只加一个 tenant_id 列不够:session 还需要 owner,notes 需要 scope,文件需要租户根,后台需要角色,并发需要配额。这是数据模型变更,不是加一个 middleware。

1.3 为什么“先不做团队,以后加 team_id”会返工

如果今天做成“资源归 user,team_id 可空”,以后加团队会遇到:

本方案选:tenant 从第一天就在;个人只是单成员 tenant。 以后加团队,只是 tenant_members 多一行,资源不搬家。

1.4 WeKnora 的可借鉴与不可借鉴

WeKnora 的权限模型值得看,但它是“多租户知识库 + 跨租户共享”,tako 是“agent 运行时 + 会话”,不能照抄。

可借鉴:

不照抄:

2. 目标与非目标

2.1 目标

  1. tenant 隔离:session/run/log/frames/notes/files/usage/audit 不跨租户。
  2. 个人 tenant 先行:注册即用;不需要先建团队。
  3. 团队功能:团队 = 多成员 tenant;A6 做创建/邀请/成员/角色/团队 agent/notes 后端;用户可属于多个 tenant;切租户不搬数据。
  4. 角色与后台:平台 system admin + 租户 owner/admin/member/viewer;成员管理、审计、最后一个 owner 保护。
  5. 会话隐私:默认 private;团队共享显式开启;管理员默认不看内容。
  6. 记忆分 scope:个人记忆 / 团队记忆分开,写入和快照都不串。
  7. 文件隔离:每 tenant 一个 workspace 根;多副本共享存储。
  8. 配额与公平:按租户限并发、子代理、token、存储;不被一个租户拖垮。
  9. 多副本:身份、角色、refresh、配额都不放进程内。

2.2 非目标 / 后续 loop

2.3 信任模型与上线闸门

假设租户里的 agent 会跑 bash、写文件,默认按“不可信代码”设计。 只做路径隔离不够:bash 可以 cat /etc/passwd、读别的租户的绝对路径、访问网络。真正的隔离需要 per-tenant 沙箱(容器/命名空间/受限命令集 + 资源限制)。

因此设两道闸:

这一版的沙箱不是容器,也不是「把工作目录当成牢笼」。本机的 sandbox-exec 要真正 apply 成功,生产 run 里的 bash 和 -dev 探针才套同一份配置:默认拒绝,只允许读写当前会话目录,并显式拒绝读 /etc/passwd 和 /private/etc/passwd。命令的 cwd 只决定它启动时站在哪个目录,挡不住绝对路径。binary 不在,或者系统拒绝 apply 时,bash 直接拒绝,不退回去跑一条裸命令,dev 探针也不报 sandboxed: true。时长上限到点后,工具结果写成「bash 超时」,父 run 不因此失败。2026-10-18 在这台 Mac 上打过:cat /etc/passwd 得到 Operation not permitted,pwd 和写会话根里的文件仍然成功。那次 apply 是被允许的。后来同一台机器上 apply 会被拒绝,这种时候不能把「退出码」当成已经隔离。

3. 核心模型与不变量

3.1 名词

3.2 不变量

  1. 每个资源都有 tenant_id:session/agent/note/file/usage/audit 直接有;run/message/runlog 经 session 回查。
  2. 角色只从 tenant_members 来;JWT 里不带 role,降级立即生效。
  3. session 默认 private;同 tenant 非 owner 也 404;visibility=tenant 才可读,写/stop 仍归 owner。
  4. notes 的 scope 写入时定死;个人记忆不会因为加入团队变成团队可见。
  5. 归属校验在 store 的同一笔事务里,不只在 handler;handler 的 404 是快路径,不是唯一防线。
  6. 不跨 tenant 引用:session 不能引用别的 tenant 的 agent;agent 不能引用别的 tenant 的 model/MCP;要共享就复制/导入,不做跨租户指针。
  7. 身份/角色/refresh/配额不放进程内;多副本共享 PG/Redis。
  8. 个人 tenant 自动建;团队是另一个 tenant;资源不搬家。
  9. 平台管理员与租户角色正交;平台管理员不自动是 tenant owner。
  10. 认证失败 401,授权失败 403,资源不可见 404;不用 403 泄露存在性。

4. 数据模型

4.1 表

ID 沿用现有 s_/r_ 前缀风格:u_/t_/a_/n_ + ULID。所有表在 PG;dev 清库重来,不做旧数据兼容。

users(
  id            text primary key,          -- u_<ULID>
  email         text not null unique,
  password_hash text not null,             -- bcrypt/argon2id
  is_system_admin boolean not null default false,
  disabled      boolean not null default false,
  token_version int not null default 0,    -- 改密/禁用时递增,旧 AT 失效
  default_tenant_id text,                  -- UX 偏好,不是授权真源
  created_at    timestamptz not null
)

tenants(
  id         text primary key,             -- t_<ULID>
  kind       text not null,                -- personal | team
  name       text not null,
  status     text not null default 'active', -- active | suspended | deleted
  plan       text not null default 'free',
  created_by text not null,
  created_at timestamptz not null,
  max_concurrent_runs int not null default 8,
  max_subagents       int not null default 8,
  daily_tokens        bigint not null default 0, -- 0 = 不限制
  max_storage_bytes   bigint not null default 0  -- 0 = 不限制
)

tenant_members(
  tenant_id  text not null,
  user_id    text not null,
  role       text not null,                -- owner | admin | member | viewer
  status     text not null default 'active', -- active | invited | suspended
  invited_by text,
  joined_at  timestamptz,
  primary key (tenant_id, user_id)
)

tenant_settings(
  tenant_id  text primary key,
  config     text not null,                -- JSON:modelRef / mcp / sandbox / secrets
  updated_by text not null default '',
  updated_at timestamptz not null
)

tenant_invitations(
  id         text primary key,             -- in_<ULID>
  tenant_id  text not null,
  email      text not null,
  role       text not null,                -- admin | member | viewer(owner 只走转移)
  token_hash text not null unique,         -- 邀请链接 token 的 SHA-256
  status     text not null,                -- pending | accepted | revoked | declined
  expires_at timestamptz not null,
  created_by text not null,
  created_at timestamptz not null
)

sessions(
  id         text primary key,             -- s_<ULID>
  tenant_id  text not null,
  user_id    text not null,
  agent_id   text not null default '',     -- 空 = 还没绑定助手
  visibility text not null default 'private', -- private | tenant
  title      text not null,
  created_at timestamptz not null
)

runs(
  id          text primary key,            -- 现有 r_<ULID>
  session_id  text not null,
  status      text not null,
  lease_until timestamptz,
  created_at  timestamptz not null,
  finished_at timestamptz
)

run_model_messages(...)  -- 现有,session_id/run_id 不变
runlog_entries(...)      -- 现有,session_id/run_id 不变

tenant_agents(
  id         text primary key,             -- ag_<ULID>
  tenant_id  text not null,
  name       text not null,
  spec       text not null,                -- 这场 run 的 prompt 正文
  model_ref  text not null default '',     -- 已落库;worker 这一版还不换模型
  tools      text not null default '',
  visibility text not null default 'private', -- private | tenant
  is_builtin boolean not null default false,
  created_by text not null,
  created_at timestamptz not null
)

notes(
  id            text primary key,          -- n_<ULID>
  tenant_id     text not null default '',
  user_id       text not null default '',  -- scope=tenant 也写创建者,不写 NULL
  scope         text not null default 'user', -- user | tenant
  workspace     text not null,
  kind          text not null,
  content       text not null,
  quote         text,
  source_run_id text not null,
  source_seq    bigint not null,
  superseded_by text,
  created_at    timestamptz not null
)

refresh_tokens(
  id          text primary key,
  user_id     text not null,
  tenant_id   text not null default '',
  token_hash  text not null unique,        -- SHA-256,不存原文
  family_id   text not null,
  expires_at  timestamptz not null,
  revoked_at  timestamptz,
  replaced_by text,
  created_at  timestamptz not null
)

usage(
  id          text primary key,
  tenant_id   text not null,
  session_id  text not null,
  run_id      text not null,
  user_id     text not null,
  model       text not null,
  input_tokens  int not null default 0,
  output_tokens int not null default 0,
  created_at  timestamptz not null
)

audit_log(
  id            text primary key,
  tenant_id     text,                      -- system 事件可为 NULL
  actor_user_id text,
  actor_role    text,
  action        text not null,
  target_type   text,
  target_id     text,
  outcome       text not null,             -- success | denied
  details       jsonb,
  created_at    timestamptz not null
)

4.2 索引

create unique index on tenant_members(tenant_id, user_id);
create index on tenant_members(user_id);
create index on tenant_members(tenant_id, role);

create index on sessions(tenant_id, user_id, created_at desc);
create index on sessions(tenant_id, visibility, created_at desc);

create index on runs(session_id, status, lease_until);
create index on tenant_agents(tenant_id, visibility);

create index on notes(tenant_id, scope, user_id, workspace);
create index on notes(tenant_id, workspace, superseded_by);

create index on usage(tenant_id, created_at);
create index on audit_log(tenant_id, created_at desc);
create index on refresh_tokens(user_id, expires_at);

4.3 为什么 run/message/runlog 不加 tenant_id

读它们本来就从 session/run 进;tenant_id 只在 session 上,回查一次就够。每表加 tenant_id 会造多个事实源,写入路径漏一次就串。但 store 层的每个入口必须在同一笔事务里回查 session 的 tenant/user/visibility;不能只在 handler 查。

4.4 为什么 notes 必须加 tenant_id + scope

notes 按 workspace 分区、与 session 无关;不加 tenant_id 堵不住“Bob 的 run 读 Alice 记忆”。scope 决定它是个人记忆还是团队记忆:

快照读取 tenant 共享 + 本人 user 私有;上限子和 advisory lock 按 (tenant_id, scope, user_id, workspace) 分开。

4.5 迁移与存量

5. 身份、登录与租户上下文

5.1 Token

5.2 注册、登录、刷新、切租户、登出

POST /api/auth/signup    {email,password}
  → 201 {user, activeTenant, memberships, accessToken, refreshToken}
  → 同一笔事务:users + tenants(personal) + tenant_members(owner)

POST /api/auth/login     {identifier,password}
  → 200 同上
  → identifier 带 @ 按邮箱查,否则按用户名查(users.username,可空;非空全局唯一,大小写不敏感)

POST /api/auth/refresh   {refreshToken}
  → 200 {accessToken, refreshToken}
  → 旧 refresh 旋转/撤销;active tenant 按最后一次选择/默认 personal 重新解析

POST /api/auth/switch-tenant {tenantId, refreshToken?}
  → 200 新 token 对,active tenant 切换
  → 必须是 active membership;旧 refresh 撤销;更新 last active

POST /api/auth/logout
  → 204;撤销当前 refresh(或该用户全部 refresh,按产品选择)

GET  /api/auth/me
  → 200 {user, activeTenant, role, memberships}

登录响应里的 memberships(tenant_id、name、role)是给前端工作区切换器/按钮显隐用的;后端每个路由仍自己查角色,不信前端。

5.3 中间件与租户上下文

请求 → Auth middleware
  → 白名单(signup/login/refresh/健康检查)放行
  → Bearer AT:验签/exp/ver → user(disabled?)
  → 取 tid;查 tenant_members(tenant_id=tid,user_id=sub,status=active)
      ├─ 没有:403 tenant_forbidden(token 有效,但已不属于该 tenant)
      ├─ 有:Identity{UserID, TenantID, Role, SystemAdmin}
      └─ tenant 路由且 tid 为空:409 TENANT_REQUIRED
  → 注入 request.Context

5.4 错误语义

/api/auth 的成功和失败用同一套信封,字段顺序 code → message → data:

{"code":0,"message":"","data":{"accessToken":"…","tokenType":"Bearer","expiresIn":900}}
{"code":111101,"message":"账号或密码不正确","data":null}

前端拦截器只认这一套。code 是业务码,数字,0 表示成功。message 是弹窗文案,成功时为空字符串,前端只在 code 不是 0 时弹出。data 是具体内容:成功时放原来的业务体,失败且没有额外细节时为 null。你记得的 body 就是这个位置,现在常见的字段名是 data。

HTTP 状态照旧返回 400/401/403/404/409/429/500,不把所有失败都收成 HTTP 200。状态告诉网关这一类请求怎么样,业务码告诉页面具体哪一种。

业务码 6 位。前两位是模块:11 身份,12 会话与运行,13 配额。身份模块里 1110xx 是参数,1111xx 是登录与 token,1112xx 是权限,1114xx 是冲突,1119xx 是这一模块里的内部失败。

情况 HTTP code message
成功 200/201 0 空。204 没有 body
请求体不是合法 JSON 400 111001 请求格式不对
邮箱或密码不符合要求 400 111002 邮箱或密码不符合要求
工作区名称是空的 400 111003 请填写工作区名称
登录失败(含账号停用,不透露哪一个错) 401 111101 账号或密码不正确
没带 token 401 111102 请先登录
token 签名错或被改过 401 111103 登录已失效,请重新登录
access token 过期 401 111104 登录已过期,请重新登录
refresh 不存在、过期或已撤销 401 111105 登录已失效,请重新登录
不是该工作区的有效成员 403 111201 你不是这个工作区的成员
角色不够 403 111203 没有权限做这件事
看得到会话但不是本人,尝试写或停止 403 111204 只有本人能修改
邮箱已注册 409 111401 这个邮箱已经注册
邀请无效/过期/已撤销 404 111405 邀请无效或已过期
已经是该工作区成员 409 111406 已经是这个工作区的成员
邀请不能授予 owner 400 111407 邀请不能授予所有者
模型未配置,或 ref 解析失败 409 111408 这个工作区的模型还不可用
工具名不在池里,或租户子代理的 allow 超出根助手 400 111409 工具策略里有不认识的工具;子代理越权时是「子代理不能使用根助手没有的工具」
MCP 密钥没配,或环境里直接放了密文 400 111410 有一项 MCP 密钥还没配;密文直放时是「MCP 环境不能直接放密文」
自定义 MCP 连不上 503 111411 自定义 MCP 连不上
同名助手已经有租户配置 409 111412 这个名字已经有一份配置
需要工作区但 token 里没有 409 111402 请先选择工作区
会变成最后一个 owner 409 111403 至少要留一个所有者
会变成最后一个平台管理员 409 111404 至少要留一个平台管理员
会话不可见 404 112001 找不到这场会话
run 不可见 404 112002 找不到这次运行
agent 不可见 404 112003 找不到这个 agent
配额超限 429 113001 这个工作区的额度用完了
登录或刷新太频繁 429 113002 操作太频繁,请稍后再试
身份模块内部失败 500 111901 服务暂时不可用,请再试一次

2026-10-22 起全部换信封(doc/40 已落地):上面这张表起初只覆盖 auth 与租户管理那批新接口; runs/sessions/mcp/media/memory 这五组旧接口的成功体与原有 404/409/413 当时仍是旧体 (如 {"error":"session_not_found"})。A7 那一档已把它换完:现在所有 JSON 接口一律 {code,message,data},业务体进 data,失败是数字业务码 + 弹窗文案。 本表是码表的真源(新码也在 doc/40 §4 登记),端点逐条对照见 doc/40。 两样不进信封:GET /api/media 的成功体是图片字节、SSE 帧面(doc/31)。

6. 角色与权限

6.1 平台管理员

users.is_system_admin:

6.2 租户角色

角色 能做什么
owner 租户生命周期、成员、所有权转移、配额/账单、租户 API key、删除租户
admin 模型/provider、MCP、沙箱、工具、agent 配置、成员日常管理;不能删租户/改 owner
member 建/跑自己的 session,建自己的 agent,上传文件;用团队共享 agent;只看自己的 session
viewer 只读团队共享的 agent/资源;不能跑、不能建

tenant_members.role 是唯一角色源;一个 user 可以在 A 是 owner、在 B 是 member。

6.3 资源可见性

资源 读 写/管理
session private owner owner
session tenant-visible 同 tenant 所有 active member owner(多人协作以后再加 session_members)
session metadata(列表/用量) owner;tenant admin 可看元数据 不改内容
agent private creator creator
agent tenant-visible 同 tenant member creator/admin
agent builtin 同 tenant member tenant admin
notes user 本人 本人
notes tenant 同 tenant member owner/admin(模型默认不能写)
workspace/files tenant 内按 session/agent 规则 tenant 内按角色

管理员默认不看会话内容。 需要支持排查时,走 support_access:填原因、限时、审计、通知用户;不要用 role >= admin 直接放开。

6.4 守卫原语与判定顺序

Ownership 判定顺序(照 WeKnora 的教训):

  1. role >= min → 放行,不查库;
  2. 不够 → 查资源归属;
  3. 资源不存在/不可见 → 交给 handler 出 404;
  4. 查库故障 → 503,不伪装 403;
  5. creator 匹配 → 放行;
  6. 其他 → 403。

6.5 最后一个 owner / 最后一个 system admin

6.6 后台管理端点(草案)

/api/system/admin/tenants                 GET/POST   system admin
/api/system/admin/users                   GET/POST   system admin
/api/system/admin/audit-log               GET        system admin
/api/system/admin/settings                GET/PUT    system admin

/api/tenants/:id/members                  GET        viewer+
/api/tenants/:id/members                  POST/PUT/DELETE  owner
/api/tenants/:id/invitations              GET        viewer+;POST/DELETE owner
/api/tenants/:id/audit-log                GET        admin+
/api/tenants/:id/usage                    GET        admin+
/api/tenants/:id/agents                   GET        member+;写 creator/admin
/api/tenants/:id/models                   GET        admin+;写 admin
/api/tenants/:id/mcp                      GET        admin+;写 admin
/api/tenants/:id/api-keys                 GET/POST   owner(以后)

前端只根据 memberships/role 隐藏按钮;后端每个路由仍然校验。

7. 会话与运行

7.1 会话 API 的访问规则

端点 规则
POST /api/runs 不带 sessionId 在 active tenant 建 private session,owner=当前 user
GET /api/sessions 只列自己的;tenant admin 的“元数据列表”另开,不含正文
GET /api/sessions/:id owner;tenant-visible 可读;其他 404
GET /api/sessions/:id/log 同上
GET /api/runs/:id/frames run→session→同上;无权 200 gone,不泄露
POST /api/runs 带 sessionId owner 才能投;tenant-visible 非 owner 403;跨 tenant 404
POST /api/runs/:id/stop owner;tenant-visible 非 owner 403;跨 tenant 404
PATCH /api/sessions/:id visibility owner;改成 tenant 需 owner/admin 确认(产品)
DELETE /api/sessions/:id owner/admin;软删;保留审计

现有端点不止四个。 A1 不是“只守 runs/sessions”,而是给下面这张表的每一行定归属;没有归属模型的端点先保守收紧,不能默认放行:

端点 数据 A1 先怎么守 什么时候开
/api/runs POST/stop/resume、/api/runs/:id、frames、stream session/run 按 session owner/visibility;跨 tenant 404;无权 frames/stream 200 gone A1
/api/sessions/:id、/log session 按 session owner/visibility A1
/api/mcp/servers 全局 mcp.json 先只允许 system_admin;普通用户 403 A6 改成租户级 MCP 配置后再开 admin/member
/api/media 全局 media 根 先只允许 system_admin(或 dev-only);没有 owner 元数据前不对普通用户开 A4 按 tenant/session 路径落盘后再开
/api/memory/items、jobs、dialogue、recall 全局 memory 先只允许 system_admin;recall 也不对普通用户开 A3 按 tenant/user scope 后再开
/api/dev/* dev 全局 保持 dev-only;-dev=false 不注册;只绑 loopback —

“先只允许 system_admin”不是最终产品语义,是没有归属模型时的保守闸;A3/A4/A6 把它们各自做正。不允许“先加 auth 中间件、这些端点先放所有人”——那等于把全局 media/memory/mcp 暴露给任意登录用户。

7.2 store 层守卫

AcquireRun 改成带身份:

type Identity struct {
    UserID      string
    TenantID    string
    Role        TenantRole
    SystemAdmin bool
}

func (s *Store) AcquireRun(ctx context.Context, id Identity, sessionID SessionID, runID RunID, user Row) (bool, error)

事务内:

  1. sessionID == "":INSERT sessions(tenant_id,user_id,visibility='private') + INSERT runs。
  2. sessionID != "":SELECT tenant_id,user_id,visibility FROM sessions WHERE id=? FOR UPDATE;
    • 无行 / tenant 不符 → not found(handler 404);
    • visibility=private 且 user 不符 → not found;
    • visibility=tenant 且 user 不符 → forbidden(handler 403,因为可见已不泄露);
    • 通过 → INSERT runs。
  3. 抢闸失败 → 409 session_busy;整笔回滚。

其他读/写入口同理:

方法 现在 改成
Exists id only 保留内部存在性;新增 SessionVisibleTo(id, identity)
SessionStatus id only 查 session 的 tenant/user/visibility;无权 404
ReadLog Exists(id) SessionVisibleTo;无权 404
ReadFrames runId only 先 RunSession(runID),再 SessionVisibleTo;无权 200 gone
StopRun runId only 先 RunSession,owner 校验;无权 404/403
writeNote workspace identity + scope;user scope owner,tenant scope admin
listLiveNotes workspace tenant + scope + user
Reset 全局 保持 dev-only 全局

预检顺序:postRuns 的 tenant/owner 检查必须在 AdmitText 之前;stopRun 的 owner 检查必须在 StopRun 之前。否则 bob 用超长 text 打 alice 的 session 会拿到 413、或者 404 是在 run 已被停掉之后才返回——响应绿了,副作用已经发生。验收必须验“404 之后 alice 的 run 仍在跑 / 没有新 run 行”。

7.3 run ctx 与 worker

7.4 共享会话(以后)

visibility=tenant 第一版只读共享:同 tenant member 可读 log/frames;写/stop 仍归 owner。多人协作(多写、评论、协同停止)以后用 session_members 表,不用角色硬套。

8. 记忆(notes)

8.1 scope 语义

8.2 写入、定位、删除的 SQL 点位

点位 现状 要改
writeNote 起手读 notes.go:206 带 tenant/scope/user
locateLiveNote notes.go:336 带 tenant/scope/user;否则 Bob 可按 content 删 Alice 的笔记
DELETE / UPDATE superseded_by notes.go:238、notes.go:267 WHERE id=? AND tenant_id=?(scope 已由 locate 限定)
两条 INSERT notes.go:261、notes.go:280 带 tenant/user/scope
写后重读 notes.go:288 带 tenant/scope/user
主快照 notes.go:614 读 tenant + user
子代理快照 agents.go:397 同上
notes_live 索引 notes.go:108 (tenant_id, scope, user_id, workspace)
上限子 / advisory lock notes.go:202 上限按 scope;锁 key 至少含 tenant+scope

8.3 写入入口

8.4 验收(必须能 curl)

A3 需要 dev-only notes 探针端点(登记转正点;A6 后台 notes 管理上线后删):

# alice 写个人记忆
curl -X POST .../api/dev/notes -H "Authorization: Bearer $ALICE_AT" \
  -d '{"scope":"user","workspace":"w1","content":"N","quote":"..."}'
# alice 读得到;bob 读不到
# bob 用 N 的 content 调 memory remove → 失败;alice 的 N 仍在
# bob 的 run 快照日志没有 N;alice 的快照有 N

只验“alice 的行 tenant_id=alice”不够,必须验“bob 读不到 + bob 删不掉”。

9. 工作区、文件与沙箱

9.1 路径

<workspace-root>/
  tenants/<tenant_id>/
    shared/                  # 团队共享文件
    sessions/<session_id>/   # 会话文件
    agents/<agent_id>/       # agent 文件
    .tako/search/            # 检索落盘

9.2 工具改造

worker.go:163 现在把 workspace 传进 NewWorker,worker.go:179 的文件工具和 worker.go:191 的 bash 都捕获它。改成:

9.3 多副本存储

本地磁盘的 workspace 在多副本下不共享。A4 必须选:

第一版建议共享卷;对象存储以后再说。否则多副本部署后,A 副本写的文件 B 副本读不到。

9.4 bash/sandbox

路径隔离挡不住 cat /etc/passwd、绝对路径、网络访问。多租户 agent 运行时默认按不可信代码设计:

9.5 验收

A4 加 dev-only workspace 探针(读文件/列目录),否则无法用 curl 证明隔离:

# alice 写 /tenants/t_alice/shared/a.txt
# bob(t_bob)读同路径 → 404
# alice 读 → 200
# bob 的 bash `cat /tenants/t_alice/shared/a.txt` → 拒绝/不可见

10. 并发与配额

10.1 每租户限额

tenants 或 tenant_quotas 加:

执行点:

10.2 当前进程级信号量的问题

agents.go:258 的 sem 是进程内 channel,容量 8,所有租户共享:

改成 per-tenant 配额 + 全局公平队列;计数放 Redis/DB,不用进程内 channel。

10.3 eino #1177

所有 run 共用 w.agent 一个 eino 实例;doc/17:217 的共享实例并发 race 在多租户下是跨租户风险(互相取消/串状态)。A5 必须做决策:

  1. 修上游 #1177;
  2. 每 run 一个 agent 实例(安全但贵);
  3. 每 tenant 一个实例 + 修 race(仍解决不了同 tenant 并发);
  4. 暂时串行(影响吞吐,不能作为长期)。

跟进(2026-10-23):委派路径已壳化(doc/25 §7 翻案,agents.go subagentShell)——子代理委派不再共享实例,本节 race 故事对委派路径失效。仍共用的是主 run 实例(w.agent,跨租户共享):当前接线 nil 写 nil(doc/25 §6),启用 adk.WithCancel 前必须按上面四条决策。

在决策前,验收不能只跑“两租户串行”;必须加两租户并发用例。

11. 后台管理

11.1 平台后台

11.2 租户后台

11.3 前端

12. 分阶段与验收

每个 action 的详细四要素在点头后写进 tmp/28-多租户/planning.md + todos.md;这里只定阶段和闸门。 2026-10-21 收口:A0–A6 共 30 拍全部落地并 curl 验收过,随 9c21b66 入库。下面各拍的「验收」是该拍当时的 判据,已全部打过。A7 的信封那一档已于 2026-10-22 落地(见 doc/40); A7 剩下的(计费/API key/SSO/组织共享)2026-10-22 已拍不做——与运行时关系不大的商业化、合规项,移出路线图(清单见 §15 与头注)。

A0 身份与个人 tenant

A1 会话归属

A2 角色与后台

A3 记忆

A4 工作区与文件

A5 并发与配额

A6 团队

A7 以后

API key、组织/跨租户共享、SSO、账单、审计导出——这一批 2026-10-22 已拍不做(与运行时关系不大的商业化、合规项,移出路线图)。

A7 里已落地的那一笔:旧 runs/sessions/mcp/media/memory 响应体整体换 {code,message,data} 信封 (2026-10-22,见 doc/40;码表在 §5.4,端点对照在 doc/40 §5)。

团队 agent 的 model_ref / tool_policy、子代理 md、租户 model key、系统/自定义 MCP 的运行时装配, 见 doc/34。本文不重复那层的装配细节。

13. 验收原则

  1. curl + 期望字节,不写“页面上看到 X”。
  2. 每个否定用例都要验无副作用:bob 的 404 之后,alice 的 run 仍在、runlogOffset 不变;bob 的删除失败后,alice 的笔记仍在。
  3. 401/403/404 按第 5.4 节;跨 tenant/private 一律 404。
  4. 角色:owner/admin/member/viewer 各跑一遍正向 + 反向。
  5. 最后 owner / 最后 system admin:409。
  6. 配额:A 429 时 B 202。
  7. 并发:两租户同时跑,不串 session、不互相取消。
  8. kill -9:run 租约到期后 session 解锁;配额/refresh 不丢。
  9. 多副本:至少手动起两个进程,验证共享 PG/Redis/workspace。
  10. dev-only 探针(notes/workspace)登记转正点,A6 后删。

14. 迁移与部署

15. 待 Yk 拍的决定

已拍(2026-10-18):支持团队功能;A6 做团队后端 API,团队前端页面独立 loop。 2026-10-21 收口核对:下表「推荐」列的取值已在 A0–A6 里按推荐落地——access TTL 15min 且 refresh 旋转、 kind=personal / kind=team 两者都有(个人先行)、session 默认 private 且显式 visibility=tenant、 团队记忆 user 默认(tenant 由 owner/admin 管)、任何登录用户可建团队、租户默认不可信(A5 沙箱)、 多副本 workspace 走共享 POSIX 卷、团队邀请走邮箱+链接。标「不做 / 以后」的那几行是终态裁定,不是待办。 A7 剩下的那些已整批拍掉:团队计费、API key、SSO、账单、组织共享 2026-10-22 用户裁不做——与运行时关系不大的商业化、合规项,移出路线图(旧成功体换信封那一笔 已由 doc/40 在 2026-10-22 落地,与本批无关)。

决定 推荐 影响
团队功能 已拍支持;A6 后端、前端独立 loop A6 范围
tenant 是团队空间还是个人空间 两者都要:kind=personal / kind=team;个人先行 表结构/注册流程
session 默认可见性 private;显式 visibility=tenant 访问规则/前端
团队记忆 user 默认;tenant 由 owner/admin 管 notes scope/模型工具
团队创建权限 任何登录用户可建;平台管理员可禁用 滥用/配额
租户是否可信 默认不可信;A5 沙箱 A4/A5 闸门
多副本 workspace 共享 POSIX 卷;以后对象存储 部署/成本
access/refresh TTL 15min / 30d;refresh 旋转 安全/体验
团队邀请方式 邮箱 + 链接;A6 产品流程
团队计费 不做(2026-10-22 裁,2026-10-23 复核维持)——原推荐「按 tenant;A7」作废 商业化(不做了)
API key 不做(同上)——原推荐「以后;独立 principal」作废;真要对外卖再翻案 集成(不做了)
管理员读会话 不做;support access 审计 隐私
个人 tenant 删除 不删;可归档 数据保留
跨 tenant 移动资源 不做;复制/导入 权限简化

16. 闭环

所以这解决了什么。 tako 从“sessionId 是钥匙”变成“tenant + user + role + 资源归属”四重边界:

仍然不解决的(明说):

收口(2026-10-21)。 A0–A6 全部落地并 curl 验收过,随 9c21b66 入库;活体抽验结论见头注。 下一批是 A7 剩下的:团队计费、API key、SSO、账单、组织共享 2026-10-22 已拍不做:与运行时关系不大的商业化、合规项,从路线图移除;本篇收口,没有登记的下一批。 2026-10-23 复核,维持不做(用户 2026-10-23 复核确认):这一档整批(含审计导出)仍然不做。复核时把两样讲清楚了,留个底以便将来翻案时不重复讨论: