读 Octop 源码(8):多用户隔离,一层真边界和三层纸糊的

文章目录

前面读了启动链路和 Agent 运行时,这篇读隔离。

之所以单独拎出来,是因为"多用户"这三个字在自托管项目里最容易含混:有的项目是"多用户登录",有的是"多租户隔离",两者差着十万八千里。 看 README 看不出来,只能读代码。

读完之后我的判断是:Octop 属于前者,而且它自己知道。

版本锚点:本文基于 octop v1.0.2(commit dd9dce4)。隔离相关的代码集中在三个小文件,加起来不到 600 行:infra/users/permissions.py(319 行)、api/common/agent.py(79 行)、infra/users/resource_policy.py(207 行)。

环境准备

验证隔离不需要读全部代码,先看清"默认状态下到底有什么边界"。

第一步,看配额表是不是空的。 这是最能说明问题的一条命令:

cd ~/WorkBuddy/Claw/octop
sqlite3 .home/.octop/octop.db "select * from user_policies;"

我这份实例(装完用了几天,2 个用户、4 个 Agent)跑出来是一行都没有。这意味着 workspace_root_dir、token_quota、max_agents 三个策略全是"不存在",而三个策略的语义都是 None = 不限制。

开箱即用的多用户部署,配额是全开的。

第二步,看用户和 Agent 的归属关系。

sqlite3 .home/.octop/octop.db \
  "select u.username, u.role, count(a.agent_id) \
   from users u left join agents a on a.user_id = u.id group by u.id;"
admin            | admin | 3
sso_ce043de81a9c | user  | 1

归属确实落在行上(agents.user_id),这一步是真的。

第三步,看权限位怎么分配。

sqlite3 .home/.octop/octop.db "select username, role, permissions from users;"

想看完整的权限目录,直接 import 出来数更快:

.venv/bin/python -c "
import sys; sys.path.insert(0,'src')
from octop.infra.users.permissions import PERMISSIONS, BASELINE_PERMISSIONS
from collections import Counter
print(len(PERMISSIONS), Counter(p.category for p in PERMISSIONS.values()))
print('默认给新用户:', len(BASELINE_PERMISSIONS))
"
# 35 Counter({'admin': 18, 'settings': 10, 'control': 4, 'nav': 3})
# 默认给新用户: 13

35 个权限位,新用户默认拿 13 个,默认不给 22 个。

带着这三个数字往下读,四层边界就很清楚了。

流程

一、先把"隔离"拆成四层

一个多用户系统要回答四个不同的问题,很多人把它们混成一个:

层问题实现文件管不管用
一、模块权限这个人能不能进这个管理页?permissions.py真,但只到"页面"粒度
二、行级归属这个人能不能动这条数据?api/common/agent.py真,这是唯一的硬边界
三、文件系统这个人能不能碰到别人的文件?resource_policy.py + host_dirs.py看部署方式,默认不能
四、配额这个人能用多少?resource_policy.py真,但默认全关

下面一层层看。

二、第一层:权限只管"看得见什么"

permissions.py 开头的 docstring 把话说得很清楚,而且说得很诚实:

A permission is a module key (e.g. "browser", "users"). Possessing a key grants access to that module’s management page and write/configure actions. Read access and agent use in chat are never gated. admin bypasses all.

“聊天里的读访问和 Agent 使用从不设限。”

这句话定下了整层的性质:权限控制的是管理面板的可见性,不是数据的访问控制。给它起名叫"权限"容易误会,叫"模块开关"更准。

35 个 key 分四类:

category数量内容新用户默认
nav3专家、自动化、Token 统计给
settings10个性化各 tab、通道、连接器、技能包、知识库给
control4工作台/终端、工作台/浏览器、远程桌面、远程手机不给
admin18用户、SSO、模型、存储、插件、安全、备份、TLS、更新…不给

默认集合就一行代码,按 category 算:

BASELINE_PERMISSIONS: set[str] = {
    key for key, p in PERMISSIONS.items() if p.category in {"settings", "nav"}
}

注意 control 这 4 个默认不给,这是对的。 terminal 和 browser 是"操作用户机器"的能力,一旦给出去,下面三层全部作废——终端里 cat /Users/xxx/.ssh/id_rsa 谁也拦不住。desktop(远程桌面)和 mobile(远程手机)同理。

判定函数很短,两个细节值得注意:

def user_has_permission(user: PermissionUser, key: str) -> bool:
    if key not in PERMISSIONS:
        return False          # 未知 key 一律拒绝,fail closed
    if user.is_admin:
        return True
    return key in (user.permissions or [])

未知 key 返回 False 而不是 True,是 fail-closed。但如果 key 拼错了呢?在 require_permission() 那一侧会直接炸——上一篇讲过,if key not in PERMISSIONS: raise RuntimeError。两边配合起来,拼错既不放过也不静默。

实际用法上,require_permission(...) 在整个路由层出现 228 次,require_admin() 只有 5 次。比例说明这套设计更偏向"给模块授权"而不是"只有管理员能碰",符合它"多用户协作"的定位。

三、第二层:行级归属,全部实现 79 行

这是唯一真正的硬边界,也是我最喜欢的一段代码——总共 79 行,没有一个多余的分支。

核心就一个判断:

def _user_may_access(row: Any, user: Any) -> bool:
    if user.is_admin:
        return True
    if row.user_id is not None and row.user_id == user.id:
        return True
    return bool(agent_is_shared(row))

三个条件,或的关系:管理员、所有者、被标记为共享。 就这些。

读和写分开成两个函数:

def assert_agent_owner(row: Any, user: Any) -> None:
    """Raise if the user may not mutate this agent row (admin bypasses)."""
    if user.is_admin:
        return
    if row.user_id is None or row.user_id != user.id:
        raise OctopError(ErrorCode.FORBIDDEN, "agent not owned by user")


def assert_agent_access_row(row: Any, user: Any) -> None:
    if not _user_may_access(row, user):
        raise OctopError(ErrorCode.FORBIDDEN, "agent not accessible to user")

一层管"改",一层管"用"。注意 assert_agent_owner 里 row.user_id is None 也会被拒绝——无主的 Agent 不能改,防止系统预置 Agent 被普通用户篡改。

还有一层 as_user,给管理员代查用的:

if as_user is not None and as_user != user.id:
    if not user.is_admin:
        raise OctopError(ErrorCode.FORBIDDEN, "as_user requires admin")
    target = server.user_manager.get_by_id(as_user)
    if target is None:
        raise OctopError(ErrorCode.NOT_FOUND, f"user {as_user} not found")
    if row.user_id is not None and row.user_id != as_user:
        raise OctopError(ErrorCode.FORBIDDEN, "agent not owned by as_user")

最后那个 row.user_id != as_user 有点绕:管理员可以代任意用户查,但只能查属于那个用户的 Agent。看着多余(管理员本来就绕过),实际是在防止"用 as_user 查别人的 Agent 却不自知"——前端拿着 as_user 参数请求,后端如果直接放行,页面上会显示错的归属。

覆盖面我数了一下,归属校验在路由层一共 63 处:

校验函数语义调用数
require_agent_row / require_agent_owner_row取行 + 校验(读 / 写两档)39
assert_agent_owner只校验写权限19
assert_agent_access只校验读权限5

63 处分布在 12 个路由文件里,而且集中度很说明问题:memory_storage 6 处、cron 6 处、skills 5 处、chat/history 5 处、agent_files 4 处——全是最能碰到数据的地方。纯配置类路由(i18n、health、settings)一处都没有。

这种分布不是巧合,它等于一张"高风险模块名单":要审计这个项目,从这五个文件看起就行。

skills.py 里还有个用法挺巧:

require = require_agent_owner_row if owner_only else require_agent_row

一个布尔参数决定调哪级校验,避免在十几个端点里复制粘贴。

这 79 行是整个项目里我最愿意照抄的一段代码。 边界清楚、读写分离、admin 显式绕过、错误码分开(AGENT_NOT_FOUND vs FORBIDDEN)——后者对排查很重要,404 和 403 混着返会让人搞不清是"没有这个"还是"不给你看"。

四、第三层:文件系统,默认没有边界

这层最有意思,因为它表面上有,实际上没开。

先看默认路径长什么样:

def agent_workspace(self, agent_id: str) -> Path:
    """Global agent workspace: ~/.octop/agents/<agent_id>/"""
    return self.agents_dir / agent_id

只按 agent_id 分,不按 user_id 分。 所有用户的 Agent 工作区都平铺在同一个目录下。

那用户级的文件隔离靠什么?靠 workspace_root_dir 策略。而上一节已经验证过:这份实例里 user_policies 是空表,所以这个策略是 None。

None 意味着什么?看目录选择器的默认值:

allowed = _user_workspace_root(server, user)
if allowed:
    return {"default_root_dir": allowed, "tree_root": allowed, "browse_roots": [allowed], ...}
root = host_fs_tree_root()
return {"default_root_dir": root, "tree_root": root, "browse_roots": host_browse_roots(), ...}

没有策略 → host_fs_tree_root(),也就是宿主机的 /(Windows 下是每个就绪盘符)。新建 Agent 时选目录,对话框从根目录开始。

就算配了策略,也不等于有了沙箱。filesystem_defaults 返回里有个字段专门说实话:

"jail_enforced": host_jail_enforced(),

它的实现:

def host_jail_enforced() -> bool:
    """True when a non-root ``root_dir`` gets real OS-level confinement.

    Only Linux + bubblewrap qualifies. Elsewhere ``root_dir`` bounds the
    agent's *tool* paths, but the agent process still runs with the server
    user's own filesystem access — so the UI must not describe it as a sandbox.
    """
    if os.name != "posix":
        return False
    return _bwrap_on_path()

这段注释我认为是整个项目里最有工程良心的一段话。翻译一下:

只有 Linux + bubblewrap 才算真正的 OS 级隔离。其他情况下 root_dir 只约束 Agent 的工具路径,进程本身仍然拥有服务器运行用户的完整文件权限——所以 UI 不能把它描述成沙箱。

也就是说,在 macOS 上、或者没装 bubblewrap 的 Linux 上,workspace_root_dir 是协作式约束:Agent 的工具会老老实实只在那个目录里操作,但它要真想跑 os.system("cat /etc/passwd"),进程本身的权限拦不住。

这也是为什么容器部署里这个策略直接失效:

def normalize_workspace_root_dir(raw: str | None) -> str | None:
    if running_in_container():
        raise OctopError(
            ErrorCode.WORKSPACE_ROOT_CONTAINER_UNSUPPORTED,
            "workspace root policy is unavailable in container deployments",
        )

注释说得干脆:「容器的文件系统本身就是隔离边界」。既然边界已经在外面了,里面再画一条就没意义。

所以第三层的真相是:docker run 才叫隔离,其他都叫自律。

五、第四层:配额全关,还有两个洞

resource_policy.py 207 行,三个策略,写法高度一致:

POLICY_WORKSPACE_ROOT_DIR = "workspace_root_dir"
POLICY_TOKEN_QUOTA = "token_quota"
POLICY_MAX_AGENTS = "max_agents"

判定都是"取不到就返回 None",None 一律解释为不限制。前面验证过,默认部署下三个都是 None。

Token 配额的实现方式值得一看,因为它不在路由层,而是在 Agent 中间件里:

class TokenQuotaMiddleware(AgentMiddleware[Any, Any]):
    """Check the acting user's lifetime token total before an agent turn."""

    def _enforce(self) -> None:
        user_id = configurable_user_id()
        if user_id is not None:
            assert_token_quota_available(self._policies, self._usage, user_id)

    def before_agent(self, state: Any, runtime: Any) -> None:
        del state, runtime
        self._enforce()

挂在 before_agent 上,每轮对话前查一次。user_id 是从 LangGraph 的 configurable 里取的,不是从 HTTP 请求——这意味着 IM 通道、cron 定时任务走的是同一条检查,不会因为入口不同就漏掉。这个设计比在路由层加装饰器更彻底。

但有两个洞。

洞一:token_quota 是终身累计,不是周期性的。

def assert_token_quota_available(policy_repo: Any, usage_repo: Any, user_id: int) -> None:
    quota = token_quota_of(policy_repo.get(user_id, POLICY_TOKEN_QUOTA))
    if quota is None:
        return
    used = int(usage_repo.total_tokens_for_user(user_id))   # ← 累计值
    if used >= quota:
        raise OctopError(ErrorCode.TOKEN_QUOTA_EXCEEDED, "token quota exceeded",
                         details={"used": used, "quota": quota})

total_tokens_for_user,字面意思就是"该用户历史总量"。用完之后不是等下个月重置,而是永远不能再用,除非管理员手动调高。作为"防跑爆账单"的保险丝够用,作为"月度额度"就不合适了。

洞二:max_agents 只数专家,不数团队。

def assert_agent_quota_available(policy_repo: Any, agent_repo: Any, user_id: int) -> None:
    """Raise when the user already owns ``max_agents`` expert agents."""
    limit = max_agents_of(policy_repo.get(user_id, POLICY_MAX_AGENTS))
    if limit is None:
        return
    owned = int(agent_repo.count_by_user(user_id, kind="expert"))   # ← 只数 expert

kind="expert" 把 team 排除在外了。而 Agent 的 kind 只有 expert 和 team 两种(create() 里的 spec.kind if spec.kind in {"expert", "team"} else "expert")。

所以:给一个用户设 max_agents=1,他建 1 个专家之后就建不了第二个专家,但可以建无限个团队。 每个团队也是一个 Agent 行、一个 harness 实例、一个常驻内存的运行时——从资源消耗的角度看,这个额度形同虚设。

不确定这是刻意的(团队算"组织级资源")还是疏漏。但代码里没有注释解释,我倾向于是漏了。

还有一个共同点:两个配额都只在 create() 时检查一次。 后来把 max_agents 从 10 改成 2,已经建了 10 个的用户不会被回溯限制,只是再也建不了新的。对"限制增长"够用,对"逼用户删减"无效。

六、共享 Agent:一个 flag,三重后果

前面反复出现 is_shared,值得单独一节。它的实现是一行:

def agent_is_shared(row: Any) -> bool:
    return int(getattr(row, "is_shared", 0) or 0) == 1

设上这个 flag,任何登录用户都能用这个 Agent。听上去只是"开放使用",但它同时带来三个后果,而且这三个都是设计的必然结果,不是 bug。

后果一:工作区共享。 前面看过,workspace_dir 是 ~/.octop/agents/<agent_id>/,跟用户无关。这个 Agent 只有一份工作区。B 用户借 A 的共享 Agent 干活,工具读写的就是 A 的那个目录——A 的私人文件 B 全看得见。

后果二:连接器身份回退到 owner。

def _connector_uid_for(self, row: AgentRow, *, connector_user_id: int | None = None) -> int | None:
    override = self._connector_user_override.get(row.agent_id)
    if override is not None:
        return override
    if connector_user_id is not None:
        return connector_user_id
    return row.user_id          # ← 回退到 Agent 所有者

三个优先级:显式覆盖 > 传入的会话用户 > Agent 所有者。

也就是说,如果 A 给自己的 Agent 配了企业微信连接器,然后设成共享,B 用这个 Agent 发消息时,发出的身份是 A。代码里有个 _connector_user_override 部分缓解了这点(共享 Agent 的 user_id 为空时用当前聊天用户),但它只是"有则覆盖",默认行为仍然是回退 owner。

从产品角度这可能是有意的(共享一个"客服 Agent",当然要用统一的对接身份)。但从安全角度,共享 Agent 等于把 owner 的对外身份借出去了,这件事应该在被勾选时明说。

后果三:team 不能共享。 这是唯一一处硬拦:

if shared and is_team_agent(existing):
    raise OctopError(ErrorCode.TEAM_NOT_SHAREABLE, "teams cannot be shared")

团队里有一堆成员的 Agent 和彼此的会话,共享出去牵扯面太大,索性能不开这个口子。这个取舍是对的。

所以在 Octop 里,“共享"不是一个轻量开关,它等于「共享工作区 + 共享对外身份」。带私人资料的 Agent 不要设共享——这不是使用建议,是硬约束。

七、这套设计的定位

四层看完,可以给它定性了。

它不是多租户 SaaS 的强隔离,是"一个人部署、几个人用"的协作式隔离。

证据不是我的推测,是四条能直接看到的事实:

  1. ADR 001 明确选单进程,所有 Agent 的运行时都在一个进程里,一个漏洞就是全穿。
  2. 配额默认全关,user_policies 空表就是出厂的默认状态。
  3. 文件系统默认无边界,目录选择器从 / 开始,jail_enforced 在 macOS 上恒为 false。
  4. 共享 Agent 会连工作区和对外身份一起共享。

这些放在"给团队内部用、大家都是同事"的场景里,全部合理——你不需要给同事设 token 上限,同事之间也不需要防着对方的文件。但如果拿它去做对外 SaaS,这四条每一条都会变成事故。

那什么时候必须换部署方式?我给三个触发条件,任一条成立就别用裸进程:

  • 给不完全信任的人开号(客户、外包、公开注册)→ 必须容器,一人一容器,或者至少一人一实例。
  • 处理敏感数据(法务、医疗、财务)→ 容器 + 配 workspace_root_dir 双保险,且只在 Linux 上才有意义。
  • 要对外暴露到公网 → 容器 + 反向代理 + 关掉 control 类权限,尤其 terminal。

其余情况(自己用、小团队内部、内网),裸进程 + 别设共享 + 别给 terminal 权限,就够了。

总结

四层边界,一句话各记一条:

  1. 模块权限(319 行)只管"看得见什么”。 35 个 key,新用户默认拿 13 个,control 类(终端/浏览器/远程桌面/远程手机)默认不给——这条默认很关键,给了它下面三层就全废。
  2. 行级归属(79 行)是唯一的硬边界。 admin / owner / is_shared 三个条件,读写分两个函数,404 和 403 分开返回。全篇最值得照抄的代码。
  3. 文件系统默认没有边界。 workspace_dir 只按 agent_id 分不按用户分;没有 workspace_root_dir 策略时目录选择器从 / 开始;jail_enforced 只在 Linux + bubblewrap 下为真。作者把这件事写进了注释和 API 字段,没有粉饰。
  4. 配额默认全关,且有两个洞。 token_quota 是终身累计不是周期额度;max_agents 只数 kind="expert",团队不占额度,而团队同样是常驻内存的 Agent。

加一条关于"共享"的:is_shared=1 同时意味着共享工作区、共享对外身份、共享会话历史里的工具产物。它不是"开放使用",是"开放一切"。

写这一篇时我刻意没有写得像在挑刺。这套设计放在自托管场景里是站得住的,代码里那些诚实的注释(“the UI must not describe it as a sandbox”)说明作者清楚边界在哪。问题只出在把自托管产品当 SaaS 卖的时候——那时候默认值就是漏洞。

下一篇是这个系列的最后一刀:(9)infra/gateway,IM 通道与会话线程状态机。

参考链接