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(删除连带删)。
这版相对旧稿改了什么。
- 身份:
X-Tako-Tenant声明式头 → JWT access + opaque refresh;role 每次从tenant_members查,不写进 token。 - 租户:单层
tenant_id→tenant + user + membership;个人 tenant 先行,团队 = 多成员 tenant。 - 会话:
session只加 tenant →tenant_id + user_id + visibility;默认 private。 - 记忆:notes 只加 tenant →
tenant_id + scope(user/tenant);个人记忆 / 团队记忆分开。 - 权限:只有 404 → 401/403/404/409 + 平台/租户/资源三层守卫。
- 新增:per-tenant workspace/files、per-tenant 配额、eino 并发决策、后台管理、A0-A7 阶段。
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 仍默认私有
五个关键决定。
- tenant 是一等公民:所有资源带
tenant_id;不搞“个人资源 + 可空 team_id”的双路径。 - 个人 tenant 先行,团队 tenant A6 后端落地:个人 tenant 现在就能用;团队后端 A6 做,团队前端页面独立 loop;表结构、token、切租户 API 从 A0 起按多租户做。
- session 默认私有:同租户普通成员也读不到别人的会话;团队共享要显式
visibility=tenant。 - notes 分 scope:
user私有、tenant共享;模型默认只写个人记忆,团队记忆由 owner/admin 管。 - 文件/沙箱/配额是 P0:多租户 agent 运行时不能共用一个全局 workspace,也不能让一个租户占满所有并发。
分几步走。
- A0 身份与个人 tenant:users/tenants/members、注册登录、refresh、切租户、system admin;个人 tenant 自动建。
- A1 会话归属:
sessions.tenant_id/user_id/visibility;建/读/停/拉 log/frames 全部按身份校验;store 层同事务守。 - A2 角色与后台:owner/admin/member/viewer、成员管理、最后一个 owner、system admin 路由、审计。
- A3 记忆:notes 的
tenant/userscope;快照、写入、定位、删除全部按 scope;个人记忆不串。 - A4 工作区与文件:每 tenant 一个 workspace 根;file tools/bash 按 tenant 解析;多副本共享存储。
- A5 并发与配额:按租户限并发/子代理/token/存储;eino #1177 的决策;两租户并发验收。
- A6 团队:创建团队、邀请、角色、切换、团队 agent/notes;session 仍默认私有。
- A7 以后:API key、组织/跨租户共享、SSO、账单。
故意不做。 不做公开注册以外的账号体系;不做 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 可空”,以后加团队会遇到:
- 每个查询都要分“个人资源”和“团队资源”两条路径;
- session/notes/files/usage 从个人转团队,要改 owner、改路径、改审计;
- “分享”是改
team_id,“取消分享”是改回去,权限和配额都跟着抖; - 团队里“这个 session 是谁的”和“这个 session 属于哪个团队”两套语义。
本方案选:tenant 从第一天就在;个人只是单成员 tenant。 以后加团队,只是 tenant_members 多一行,资源不搬家。
1.4 WeKnora 的可借鉴与不可借鉴
WeKnora 的权限模型值得看,但它是“多租户知识库 + 跨租户共享”,tako 是“agent 运行时 + 会话”,不能照抄。
可借鉴:
- 平台
is_system_admin与租户角色分离;tenant_member.go tenant_members.role是角色唯一真源,不放在users.role;RequireRole/RequireOwnershipOrRole/RequireSystemAdmin三层守卫;rbac.go- ownership 判定顺序:role 够就不查库,不够才查 creator;查不到让 handler 404,查库故障 503;ownership.go
Caller(授权身份)与WithExecutionTenant(数据作用域)分离;- 最后一个 owner / 最后一个 system admin 保护;
- 审计:角色变更、管理员操作、拒绝尝试。
不照抄:
- 组织/跨租户共享的三维取最小
min(share, org role, tenant cap)——等有跨团队共享再做; - API key capability 矩阵——等有程序化接入再做;
- 24h access token + token 原文落库——tako 用短 access + refresh hash;
- RBAC 的 fail-open rollout 开关——多租户默认全开。
2. 目标与非目标
2.1 目标
- tenant 隔离:session/run/log/frames/notes/files/usage/audit 不跨租户。
- 个人 tenant 先行:注册即用;不需要先建团队。
- 团队功能:团队 = 多成员 tenant;A6 做创建/邀请/成员/角色/团队 agent/notes 后端;用户可属于多个 tenant;切租户不搬数据。
- 角色与后台:平台 system admin + 租户 owner/admin/member/viewer;成员管理、审计、最后一个 owner 保护。
- 会话隐私:默认 private;团队共享显式开启;管理员默认不看内容。
- 记忆分 scope:个人记忆 / 团队记忆分开,写入和快照都不串。
- 文件隔离:每 tenant 一个 workspace 根;多副本共享存储。
- 配额与公平:按租户限并发、子代理、token、存储;不被一个租户拖垮。
- 多副本:身份、角色、refresh、配额都不放进程内。
2.2 非目标 / 后续 loop
- 团队前端页面(创建/邀请/成员页的交互)——独立 frontend loop;A6 后端 API 在本篇,契约要够前端直接用;
- 组织/跨租户共享(共享 agent、共享 KB)——以后;
- API key capability / 机器 principal——以后;
- OIDC/SSO、账单/席位、审计导出——以后;
- 团队嵌套/部门树——明确不做,用扁平 tenant + project 代替;
- 管理员默认读所有会话——不做;support access 单独设计。
2.3 信任模型与上线闸门
假设租户里的 agent 会跑 bash、写文件,默认按“不可信代码”设计。 只做路径隔离不够:bash 可以 cat /etc/passwd、读别的租户的绝对路径、访问网络。真正的隔离需要 per-tenant 沙箱(容器/命名空间/受限命令集 + 资源限制)。
因此设两道闸:
- A4 完成前:只允许个人 tenant、单用户/本地开发;不开放多租户。文件工具仍用全局 workspace,但部署只绑 loopback。
- A5 完成前:不开放外部团队;A4 的 per-tenant workspace 必须已完成,A5 还要有配额 + eino 并发决策;如果租户不可信,还要有沙箱。
这一版的沙箱不是容器,也不是「把工作目录当成牢笼」。本机的 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 名词
- platform:整个部署。平台管理员
is_system_admin管全局设置、所有租户、平台审计,不等于任何租户的 owner。 - tenant:隔离、计费、配额的单位。
kind=personal(单成员)或team(多成员)。个人 tenant 在注册时自动创建;团队 tenant 由用户创建/邀请加入。 - user:全局身份。一个 user 可以属于多个 tenant;角色在每个 tenant 不同。
- membership:
tenant_members(tenant_id, user_id, role, status)。这是角色唯一真源;active才参与鉴权。 - session:tenant 内的会话资源;
tenant_id必填,user_id是 owner,visibility=private|tenant。 - run:session 的一次执行。
runs.session_id指向 session;tenant/user 经 session 派生。 - agent:tenant 级 agent 定义;
created_by、visibility、is_builtin。 - note:tenant 级记忆;
scope=user|tenant。两档都写user_id。scope=tenant写的是创建者,列是not null default '',不是 NULL。 - workspace:tenant 的文件根;
<root>/tenants/<tenant_id>/...。 - api key:机器身份,后续 loop;不混入人类角色。
3.2 不变量
- 每个资源都有
tenant_id:session/agent/note/file/usage/audit 直接有;run/message/runlog 经 session 回查。 - 角色只从
tenant_members来;JWT 里不带 role,降级立即生效。 - session 默认 private;同 tenant 非 owner 也 404;
visibility=tenant才可读,写/stop 仍归 owner。 - notes 的 scope 写入时定死;个人记忆不会因为加入团队变成团队可见。
- 归属校验在 store 的同一笔事务里,不只在 handler;handler 的 404 是快路径,不是唯一防线。
- 不跨 tenant 引用:session 不能引用别的 tenant 的 agent;agent 不能引用别的 tenant 的 model/MCP;要共享就复制/导入,不做跨租户指针。
- 身份/角色/refresh/配额不放进程内;多副本共享 PG/Redis。
- 个人 tenant 自动建;团队是另一个 tenant;资源不搬家。
- 平台管理员与租户角色正交;平台管理员不自动是 tenant owner。
- 认证失败 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 决定它是个人记忆还是团队记忆:
scope=user:user_id是本人,只有本人读写;scope=tenant:user_id写创建者,不是 NULL。全租户可读,只有 owner/admin 能写(模型默认不能写)。
快照读取 tenant 共享 + 本人 user 私有;上限子和 advisory lock 按 (tenant_id, scope, user_id, workspace) 分开。
4.5 迁移与存量
- 当前未上线:dev 库直接 wipe,不做旧数据兼容;
dev/reset仍是 dev-only 全局归零。 - 如果一定要保留 dev 数据:建一个 bootstrap tenant + bootstrap user,把旧 session/notes 归到它;不要造一个公开的
defaulttenant。 sessions.tenant_id/user_id、notes.tenant_id/scope/user_id都NOT NULL。notes.user_id默认空串;scope=tenant仍写入创建者,不写 NULL。agentsDir现在全局;A0-A3 不落 agents 表,继续用全局内置 agent(sessions.agent_id=NULL表示默认);A6 起每个 tenant seed built-in agent,再开放租户自定义 agent,agents.tenant_id才非空。-workspace现在全局;A4 改成-workspace-root+ per-tenant 根;A4 完成前不开放多用户。
5. 身份、登录与租户上下文
5.1 Token
- Access token:JWT,15 分钟;claims:
sub(user_id)、tid(active tenant_id)、jti、ver、iat、exp、iss、aud。 - Refresh token:随机 256-bit opaque,30 天;PG 只存 SHA-256;刷新时旋转(旧 token revoked,新 token 同 family);旧 token 再用 → 撤销 family。
- 不在 JWT 里放 role:角色每次从
tenant_members解析;降级/移除立即生效。 - 签名密钥从环境变量加载;启动缺失 fail fast;多副本共享;校验算法白名单。
- 改密/禁用/移除成员:递增
users.token_version或撤销 refresh + 校验 membership;旧 AT 最多活 15 分钟,必要时加 denylist。
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
Identity里的Role来自 membership,缺失/非法时默认viewer(fail-closed)。SystemAdmin来自users.is_system_admin,与 tenant role 正交。Caller(授权身份)与execution tenant(数据作用域)分开;如果以后做共享资源,切换执行 tenant 不能改 Caller。- 不再使用
X-Tako-Tenant;active tenant 在 token 里,切租户走/auth/switch-tenant。API key 以后单独绑 tenant。
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:
- 管全局模型/provider、系统设置、所有租户(列表/暂停/配额)、平台审计、runtime 队列;
/api/system/admin/*全部RequireSystemAdmin;这些路由是 tenant-optional:只校验is_system_admin,不要求 active tenant,平台管理员可以是无 tenant 的账号;- 不能自动读租户会话内容;需要 support access 时单独走审计;
- 最后一个 system admin 不能撤销;
- 与 tenant role 无关:平台管理员在某个 tenant 里可能只是 viewer。
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 守卫原语与判定顺序
RequireSystemAdmin:平台管理员;始终生效。RequireTenantRole(min):owner/admin/member/viewer 阶梯;tenant role 来自 membership。RequireOwnershipOrRole(min, lookup):资源 creator 或 min 角色;用于 agent 等有 creator 的资源。RequireSessionAccess(action, lookup):owner / tenant-visible / admin metadata;session 专用。RequireTenantMatch:URL 里的 tenant id 必须等于 active tenant(如果 URL 有 tenant)。APIKeyGate:以后;机器身份单独 default-deny。
Ownership 判定顺序(照 WeKnora 的教训):
- role >= min → 放行,不查库;
- 不够 → 查资源归属;
- 资源不存在/不可见 → 交给 handler 出 404;
- 查库故障 → 503,不伪装 403;
- creator 匹配 → 放行;
- 其他 → 403。
6.5 最后一个 owner / 最后一个 system admin
- 降级/移除 owner 必须在事务里锁住该 tenant 的其他 active owner;若会是最后一个 →
409 last_owner;不能靠“先 count 再 update”。 - 撤销 system admin 同理:最后一个 →
409 last_system_admin。 - 移除成员时撤销该成员在该 tenant 的 refresh/token(不是他在其他 tenant 的登录)。
- 所有成员/角色变更写
audit_log。
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)事务内:
sessionID == "":INSERT sessions(tenant_id,user_id,visibility='private')+INSERT runs。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。
- 抢闸失败 → 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
postRuns把Identity放进worker.Run的 ctx(不是c.Request.Context(),run 生命周期不属于请求)。- worker 从 ctx 取
tenant_id/user_id,传给 notes 快照、memory 工具、workspace 解析、usage 记录。 runCancels仍是进程内注册表;跨副本 stop 靠 lease watchdog 收敛(现有机制,不新增跨副本语义)。one_live_run_per_session闸不变:session_id 全局唯一,tenancy 不改变它。
7.4 共享会话(以后)
visibility=tenant 第一版只读共享:同 tenant member 可读 log/frames;写/stop 仍归 owner。多人协作(多写、评论、协同停止)以后用 session_members 表,不用角色硬套。
8. 记忆(notes)
8.1 scope 语义
scope=user:个人记忆;user_id是本人;只有本人读写;快照里只出现本人的。scope=tenant:团队记忆;user_id写创建者,列不是 NULL。全 tenant 可读;只有 owner/admin 能写;模型默认不能写(防止一个 member 的 agent 污染团队记忆)。- 快照每一场 run 起手读:
tenant共享 + 本人user私有;渲染时分两段标清楚(“团队记忆”/“个人记忆”),避免模型把两者混为一谈。
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 写入入口
memory工具(模型调用)在 A3 只写scope=user;它从 ctx 的Identity取 tenant/user。- 团队记忆
scope=tenant只通过 owner/admin 的后台 API/UI 写入;以后若要让 agent 写团队记忆,单独加scope参数 + 角色校验 + 审计。 - 所有写入仍走
writeNote一个函数,经过同一套上限/原话/隐形字符检查。
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/ # 检索落盘
- 个人 tenant 也是这个结构,只是只有一个成员。
- 这一版真正建出来的目录是
<workspace>/tenants/<tenant_id>/sessions/<session_id>/。图里的shared/和agents/<agent_id>/还没有单独创建。 - 文件工具和 bash 每次从 ctx 里的
WorkspaceRef取会话根。没有身份的单测才回落到启动时捕获的根。 bash的 cwd 是这个会话根;环境白名单保留。cwd 不是安全边界,读宿主文件靠第 9.4 节的沙箱拒绝。
9.2 工具改造
worker.go:163 现在把 workspace 传进 NewWorker,worker.go:179 的文件工具和 worker.go:191 的 bash 都捕获它。改成:
- 构造工具时不再吃固定路径;工具执行时从 ctx 取
WorkspaceRef; worker.Run在 ctx 里放Identity+WorkspaceRef;memory/search_history的落盘也用同一个解析器;- 所有路径
resolveInWorkspace后再检查是否仍在 tenant 根内;防../symlink。
9.3 多副本存储
本地磁盘的 workspace 在多副本下不共享。A4 必须选:
- 共享 POSIX 卷(NFS/EFS)挂到同一路径;或
- 对象存储 + 文件服务适配层;或
- 按 tenant/session 粘到某个副本(不推荐,复杂度高)。
第一版建议共享卷;对象存储以后再说。否则多副本部署后,A 副本写的文件 B 副本读不到。
9.4 bash/sandbox
路径隔离挡不住 cat /etc/passwd、绝对路径、网络访问。多租户 agent 运行时默认按不可信代码设计:
- A4 做的是 per-tenant 根和路径检查,包括
..和符号链接。这不是安全边界。 - A5 在 macOS 上用
sandbox-exec:默认拒绝,会话目录可读写,显式拒绝/etc/passwd和/private/etc/passwd。binary 不在,或者sandbox_apply被拒绝,都拒绝执行,不把 cwd 当成隔离,也不把失败写成普通退出码。 - 2026-11-03 补 Linux 后端:Debian 12 用
bwrap(bubblewrap)。逐个卸 user/pid/ipc/uts/cgroup,不卸 net(D37 的出站网络要通);/usr只读、/etc只白名单文件、只 bind 会话根可写,绝不--ro-bind / /。启动时真跑探针,失败仍拒绝执行(不退回裸 bash);启动日志写bash sandbox: seatbelt|bwrap|none(原因)。租户 MCP 走同一个后端。 - 外部团队仍然不要只凭这条沙箱就放开。它挡的是本机绝对路径和默认网络,不是一套完整的多租户运行时隔离。
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 加:
max_concurrent_runs(默认 4/8)max_subagents(默认 2/4)daily_tokens(默认按 plan)max_storage_bytesmax_sessions
执行点:
POST /api/runs:查该 tenant 正在跑的 run 数;超 → 429tenant_quota_exceeded。- 子代理委派:按 tenant 计数;超 → 工具结果返回“配额不足”,父 run 不崩。
- 模型调用后:
usage落库 + Redis 日计数;超预算 → 后续调用拒绝。 - 文件写入:按 tenant 存储配额。
- 管理后台:owner/admin 看用量;platform admin 改配额。
10.2 当前进程级信号量的问题
agents.go:258 的 sem 是进程内 channel,容量 8,所有租户共享:
- 一个租户可以占满 8 个槽,别的租户饿死;
- 多副本下每个副本各自 8 个,配额不可控;
- 进程重启丢状态。
改成 per-tenant 配额 + 全局公平队列;计数放 Redis/DB,不用进程内 channel。
10.3 eino #1177
所有 run 共用 w.agent 一个 eino 实例;doc/17:217 的共享实例并发 race 在多租户下是跨租户风险(互相取消/串状态)。A5 必须做决策:
- 修上游 #1177;
- 每 run 一个 agent 实例(安全但贵);
- 每 tenant 一个实例 + 修 race(仍解决不了同 tenant 并发);
- 暂时串行(影响吞吐,不能作为长期)。
跟进(2026-10-23):委派路径已壳化(doc/25 §7 翻案,agents.go
subagentShell)——子代理委派不再共享实例,本节 race 故事对委派路径失效。仍共用的是主 run 实例(w.agent,跨租户共享):当前接线 nil 写 nil(doc/25 §6),启用adk.WithCancel前必须按上面四条决策。
在决策前,验收不能只跑“两租户串行”;必须加两租户并发用例。
11. 后台管理
11.1 平台后台
- 租户列表/暂停/配额;
- 用户列表/创建/禁用/重置密码;
- 全局模型/provider、系统设置;
- platform 审计、runtime 队列。
11.2 租户后台
- 成员/角色/邀请(owner);
- 审计日志(admin);
- 用量/配额(admin);
- agent 配置(admin/creator);
- 模型 provider/MCP/沙箱(admin);
- API key(owner,以后)。
11.3 前端
- 登录响应带
memberships+activeTenant+ role; - 工作区切换器;团队设置页;成员管理页;
- 只根据角色隐藏按钮;后端每个路由仍校验;
- session 列表只显示自己的;团队共享 session 单独标识。
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
- 建
users/tenants/tenant_members/refresh_tokens;注册自动建 personal tenant + owner membership;登录/刷新/登出/切租户;is_system_admin;auth middleware;错误语义。 - 验收:signup/login/me/refresh/switch;401/403/409;旧 refresh 复用失败。
- 第一个 action = signup 或 login,curl 可打。
- 已拍(2026-10-18):A0 期间现有业务端点保持裸奔,只在本机 dev 验收,A1 补门;A0-1/A0-2 静态 dev 用户可;A0-3/A0-4/A0-5 90–100 行接受。
A1 会话归属
sessions.tenant_id/user_id/visibility;建/读/列表/log/frames/stream/stop/post/resume/status 全部按Identity;store 层守卫;run经 session。- 所有非 dev 端点先挂 auth;
mcp/media/memory这三类还没有归属模型的端点先收紧到system_admin(见第 7.1 节的表),A3/A4/A6 再各自开。 - 验收:同 tenant 私有 404;跨 tenant 404;owner 200;tenant-visible 可读不可写;bob stop 404 且 alice 的 run 仍在跑;无 token 401。
- 闸门:本阶段只做会话归属;文件/配额仍未隔离,按第 2.3 节的上线闸门,A4 前不开放多用户。
A2 角色与后台
- owner/admin/member/viewer;成员增删改;邀请(可先不做 UI,做 API);最后一个 owner;system admin 路由;审计。
- 验收:owner 邀请/升降级;member 403;last owner 409;普通用户访问 system admin 403。
A3 记忆
notes.tenant_id/user_id/scope;所有 SQL 点位;快照;上限/锁;memory 工具只写 user scope;dev notes 探针。/api/memory/items|jobs|dialogue|recall从“system admin only”改成按 tenant/user scope;recall 只能召回本 tenant/本人的记忆。- 验收:个人记忆不串;团队记忆可读不可被模型写;bob 删不掉 alice 的;bob 的 recall 不返回 alice 的内容。
A4 工作区与文件
-workspace-root;per-tenant 路径;file tools/bash 从 ctx 解析;多副本共享卷;dev workspace 探针。/api/media从“system admin only”改成按 tenant/session 路径校验。登录后的入口图落在<workspace>/tenants/<tid>/sessions/<sid>/.media/。占位 path、GET /api/media和read_media_file共用sessions/<sid>/.media/<sha>.ext。sessions/<可见>/../<别人>/...先 Clean,再按清完的会话做访问检查;不带会话的.media/...直接 404。- 验收:A 租户文件 B 读不到;
../symlink 拒绝;多副本读同一文件;B 的/api/media?path=...读不到 A 的图。 - 闸门:A4 完成前不开放多用户。
A5 并发与配额
- per-tenant 配额;有 Redis 时子代理只走租户槽
tk:subagents:<tenant>,进程级 sem 只留给没有 Redis 的单测;两租户并发;429;用量落库。存储上限管整棵<workspace>/tenants/<tid>/,入口图超上限在抢闸前 429,不建 run。 - 验收:A 超额 429,B 仍 202;两租户并发无串状态;重启/多副本计数不丢。
- 闸门:A5 + 沙箱(如果租户不可信)完成前不开放外部团队。
A6 团队
- 正式创建 team tenant(
POST /api/tenants,替代POST /api/dev/tenants);列表/切换/设置/归档。 - 邀请:
tenant_invitations(email + 链接 token,待接受/撤销/过期);接受后写 active membership。 - 成员/角色:owner/admin/member/viewer;离开、移除、转移 owner;最后一个 owner 保护;移除成员撤销该 tenant 的 refresh。
- 团队 agent:
tenant_agents按 tenant 落库,id 前缀ag_,creator/visibility;团队 notes 用 A3 的scope=tenant。 - 团队运行时配置:model / MCP / 沙箱按 tenant 存进
tenant_settings.config这一列 JSON;admin 写、member 读。非空 secret 落库前封成seal1:(AES-GCM,密钥是TAKO_JWT_SECRET的 SHA-256)。GET 把非空 secret 显示成「••••」。客户端把这四个点原样 PUT 回去,或整段secrets不带,都沿用库里的密文。平台全局配置仍 system admin。读写接口已落地。worker 这一版仍用进程启动时的全局mcp.json,还没有按tenant_settings去装模型和 MCP。不要把「配置已落库」说成「这场 run 已经换了模型」。 - session 仍默认 private;
visibility=tenant只读共享,写/stop 仍归 owner。 - 验收:create/invite/accept/switch;团队 agent 可运行、不可被普通 member 改;个人 session 不搬;移除成员后其 token 在该 tenant 失效;最后 owner 409。
- 闸门:A4/A5 已完成;团队前端页面独立 loop。
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. 验收原则
- curl + 期望字节,不写“页面上看到 X”。
- 每个否定用例都要验无副作用:bob 的 404 之后,alice 的 run 仍在、runlogOffset 不变;bob 的删除失败后,alice 的笔记仍在。
- 401/403/404 按第 5.4 节;跨 tenant/private 一律 404。
- 角色:owner/admin/member/viewer 各跑一遍正向 + 反向。
- 最后 owner / 最后 system admin:409。
- 配额:A 429 时 B 202。
- 并发:两租户同时跑,不串 session、不互相取消。
kill -9:run 租约到期后 session 解锁;配额/refresh 不丢。- 多副本:至少手动起两个进程,验证共享 PG/Redis/workspace。
- dev-only 探针(notes/workspace)登记转正点,A6 后删。
14. 迁移与部署
- 未上线:dev 库 wipe;不写旧数据迁移;
dev/reset仍是 dev-only。 - 生产:
-dev=false;-engine按部署;-workspace-root共享卷;JWT/refresh 密钥从环境变量;TLS。 - 数据库迁移:显式 DDL(
NOT NULL、索引、唯一约束);不依赖 AutoMigrate 改已有索引;在有数据的库上验tenant_id IS NULL为 0。 - 多副本:PG 存 users/tenants/members/sessions/notes/refresh/usage/audit;Redis 存限流/并发计数/runlive;workspace 共享卷;进程内只留 runCancels(现有)。
- 可观测:日志带
tenant_id/user_id/session_id/run_id;审计表;指标:租户并发、429、token 用量、存储、run 失败率。 - 回滚:A0-A1 可回滚到旧库(wipe);A4 文件路径变更后回滚要保留旧路径;A6 团队上线前先备份。
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 + 资源归属”四重边界:
- 现在:每个用户有个人 tenant,session 私有,notes 个人,文件/配额/后台按租户;
- A6:团队只是多成员 tenant,用户切租户,团队 agent/notes 共享,个人数据不搬;
- 平台管理员与租户角色分开,最后一个 owner/system admin 有保护,拒绝和角色变更可审计。
仍然不解决的(明说):
- 团队前端页面/计费/SSO/API key——前端或后续 loop;团队后端 A6 在本篇;
- 组织/跨租户共享——后续;
- 不可信租户的完整沙箱——A5 的硬闸门;
- eino #1177 的并发 race——A5 必须决策;
- 文件/笔记的“管理员默认读内容”——不做,走 support access。
收口(2026-10-21)。 A0–A6 全部落地并 curl 验收过,随 9c21b66 入库;活体抽验结论见头注。 下一批是 A7 剩下的:团队计费、API key、SSO、账单、组织共享 2026-10-22 已拍不做:与运行时关系不大的商业化、合规项,从路线图移除;本篇收口,没有登记的下一批。 2026-10-23 复核,维持不做(用户 2026-10-23 复核确认):这一档整批(含审计导出)仍然不做。复核时把两样讲清楚了,留个底以便将来翻案时不重复讨论:
- API key = 给程序用的独立身份(今天每个认证调用方都是人,机器接不进来);SSO = 用公司已有账号登录(今天账号自建,与 IT 那套无联动,离职不联动、密码策略与 MFA 失效)。
- 两者都是**"对外卖 / 进公司大门"的门,不是运行时的门**;真要卖再翻案,底座不差:本地账号 + membership +
audit_log表都在,tenant_usage_daily已按租户按天记用量,缺的是定价/席位/账单与机器主体那几层。 - doc/16 §5.1 曾把这一档挂在「第 1 项待做」上——那是一处旧账(与本篇 10-22 的拍板打架),已于 2026-10-23 同批删掉,改记进 doc/16 的「已拍不做」清单。 A7 里的旧 runs/sessions/mcp/media/memory 成功体换
{code,message,data}信封已由 doc/40 单独落地(2026-10-22,A7-1…A7-8)。 团队前端页面已由 doc/36 单独落地(2026-10-21)。