A local-first multi-agent app development platform, built on PenguinHarness
title: 安全模型 description: Adelie 的访问机制如何运作:从认领新服务器到收回会话,以及底层的实现细节。
Adelie 用真实凭据在真实机器上运行 Agent,所以值得弄清楚:谁能做什么,凭什么。本页按你遇到这些场景的顺序依次讲解,最后集中说明底层机制(会话令牌、磁盘内容、网络暴露面)。
- 第一次启动新服务器? 参见认领新服务器。
- 需要设置、修改或找回密码? 参见管理密码。
- 要在同一台机器上跑脚本或用 CLI? 参见在本机自动化。
- 要通过 ssh 操作其他机器? 参见通过 ssh 管理远程机器。
- 需要收回访问权限? 参见收回访问权限。
所有场景都贯穿着同一条原则:
能读到数据根目录,就等于拥有它。 数据根目录(默认为
~/.adelie/data)存放着全部模型凭据和全部对话。在它们旁边再藏一个秘密,也拦不住本来就能读到这些内容的人,所以这套安全模型从不假装做得到。它做的反而是让这种所有权可以放心使用:有效期短、随时可收回,而且从不要求存储或发送密码。
功能一览
| 能力 | 位置 |
|---|---|
| 通过启动时打印的登录链接认领新服务器;此时还不存在密码,也不会显示任何密码 | 启动提示 |
| 用密码登录;密码以 scrypt 哈希存储,登录尝试有频率限制 | Web 登录页、penguin auth login |
| 桌面应用静默登录自己的窗口 | 窗口打开时的一次性令牌 |
| 凭本地所有权铸造会话,全程不需要密码 | penguin auth token |
| 通过 ssh 管理机器,网络上不传密码 | 机器管理页面 |
| 会话是服务端的一行记录:可逐个收回、重启后依然存在、使用期间自动续期(30 天) | 所有场景 |
| 每个会话都记录自己的建立方式 | 会话的 via 值(见下文) |
| 收回单个会话,或收回某个用户的全部会话 | 登出、管理员重置用户密码 |
| 就在这台机器上找回丢失的管理员密码 | penguin server reset-admin-password |
每个会话的 via 值记录它的建立方式:
password:手动输入的密码,或由penguin auth token铸造的会话desktop:桌面应用自己的窗口setup:新服务器上的登录链接token:请求在 Bearer 头里携带本地 API token;不存储会话
认领新服务器
全新的服务器没有可用的密码:预置值生成后完成哈希便立即丢弃,没人见过明文。为了让你照样能进去,在设置密码之前,服务器每次启动都会打印一个登录链接:
+---------------------------------------------------------------------------------------+
| This server has no admin password yet. Open this link to claim it: |
| |
| http://localhost:7364/api/auth/claim?token=... |
| |
| The link lasts 30 days or until a password is set; restarting prints a fresh one. |
+---------------------------------------------------------------------------------------+
- 启动服务器。
- 从启动输出中复制登录链接。
- 在浏览器中打开链接,即以内置的
admin账户身份登录。 - 设置密码。
为什么可以放心打印链接
这个链接不是一次性的,因为邮件客户端可能抢在你之前抓取它,第二次打开也必须仍然有效。真正让它能放心打印到控制台的,是另外三条限制:
- 它只在服务器尚未认领时有效,且最长 30 天。一旦设置了密码,服务器就拒绝这个链接,所以翻控制台的历史输出也进不去。
- 链接比对用的值存在内存里,每次重启都会更换。上一次运行打印的链接不再有效;错过了提示,重启服务器就能看到新的。
- 错误的 token 和已认领的服务器得到同一个答复,所以过期的链接连是哪种情况都区分不出来。
[!NOTE] 在容器里,这条提示输出到容器日志(
docker logs)。链接中的localhost是服务器眼中的自己。按文档给出的回环端口映射来部署时,这也是你眼中的它,所以在运行 Docker 的那台机器上按打印的原样打开链接即可。如果容器发布到了网络上,就把localhost换成你实际访问所用的主机;无论哪种情况,token 都保持原样。
也可以改用 ADELIE_SEED_ADMIN_PASSWORD 直接固定密码,但只在数据根目录为空的首次启动时生效。
链接授予的会话带有 via: setup。它只有一项特殊许可:设置密码时不必输入旧密码(反正也不存在);除此之外没有任何特权,尤其拿不到任何仅限桌面应用的路由。
从桌面应用登录
桌面应用的外壳拥有它内嵌的服务器进程,仅凭这一点,窗口即可进入。窗口的首次导航会兑换外壳铸造的一次性令牌,随后以 via: desktop 登录。令牌一经兑换即作废,URL 泄露也无法重放。
管理密码
密码至少 8 个字符,存储方式只有一种:scrypt 哈希(N=16384,每个密码各带一个盐值,参数与哈希存放在一起,以便日后提高计算成本)。按操作者不同,设置密码有四种方式。
修改自己的密码
如果你知道当前密码,在用户设置里使用修改密码(见修改密码)。操作会先验证当前密码。
不提供旧密码设置密码
setup 会话(见认领新服务器)和桌面应用自己的窗口都可以在不出示旧密码的情况下设置新密码。这两种会话所在的账户,密码本来就是无人见过的随机值,没有旧密码可填。会话的建立方式本身就是授权。
重置其他用户的密码
管理员在用户管理里用重置密码为其他账户设置一个新的初始密码(见重置用户密码)。用户下次登录时要先修改这个密码,名下所有会话同时收回。见收回访问权限。
找回管理员密码
开始之前
- 能访问服务器所在的机器,且服务器已停止。本地文件系统的访问权就是授权。
- 运行
penguin server reset-admin-password。 - 启动服务器,它会打印一个新的登录链接。
- 打开链接并设置密码,方法同认领新服务器。
管理员账户回到未认领状态,名下所有会话全部收回。整个恢复过程不产生任何需要记下来的东西。
登录尝试限制
无论来自哪里,密码登录都按用户名限速,采用指数退避。失败五次后,每次新的尝试要先等 1 秒,逐次翻倍,最长 60 秒。不存在的用户名也按同样方式限速,因此限流本身不会暴露账户是否存在。响应耗时同样不会:不存在的用户名会拿一个占位哈希来校验,因此每次尝试都恰好做一次 scrypt 推导。
在本机自动化
脚本和 CLI 从来不需要密码,因为本地所有权本来就高于密码。
CLI 命令访问本机上的服务器时,用本地 API token 认证;服务器每次启动都会把它写入 <root>/api-token。参见 CLI 参考。
本地 API token 不能改变 Agent 的对外暴露:开启 Agent 的 API、无密钥访问、审批模式、密钥,以及整台服务器的 Agent API 开关,都需要人的登录,因为每个 Agent 的命令都带着这个 token。服务器以 403 human_required 拒绝携带 token 的这类请求,在 Session 之外,CLI 随即带着你保存的登录(如果有)把请求再发一次;下文的 penguin auth token 能为 CLI 提供这样的登录。这防止 Agent 借 harness 交给它的凭据自行对外开放,但不是边界:以数据根目录所属操作系统账号运行的进程同样能铸造会话。约束 Agent 的是沙盒。
脚本需要自己的会话时,就自己铸造一个。会话是数据根目录下 web.db 里的一行记录,所以 CLI 直接写入一行:
penguin auth token # no password, no prompt: inserts a session row
能读写数据根目录就是全部授权,而且它不会授予任何新东西:数据根目录本来就存着这个 token 能触达的每一份凭据。服务器在不在运行都可以铸造,与运行中的服务器并存也安全。前提是服务器至少在这个根目录上启动过一次:铸造所用的账户就存放在这个根目录的 web.db 里。
铸造出的 token 默认有效期一小时,等同普通的密码会话,绝不是桌面会话。用 --ttl-seconds 指定其他有效期(最长 30 天),或用 --user-id 为 admin 以外的账户铸造。
在多用户机器上,这道限定正是关键。数据根目录属于运行服务器的操作系统账户,所以只有这个账户能铸造。其他人一律用密码登录:penguin auth login --server <url>。
通过 ssh 管理远程机器
机器管理页面通过 ssh 管理其他机器,一切操作都以 ssh 账户的身份运行。
要对一台机器的 API 执行操作,控制器通过 ssh 在那台机器上运行 penguin auth token。机器自己的 CLI 往机器自己的数据库里写入一行会话记录。经过网络的只有会话令牌,有效期一小时。
密码永远不经过网络。一台机器的管理员密码就留在那台机器上,因为 ssh 已经证明了密码所能证明的一切。
[!WARNING] 这种信任是双向的。任何能 ssh 到一台机器的人都能亲手读取它的数据根目录,所以铸造 token 并不会带来 ssh 之外的任何权限。正因如此,你的 ssh 密钥就是它能到达的每台机器的主凭据。请按这个级别保管。
把模型凭据同步到自己各台机器的 Project,会把这批 API key 放进每台机器自己的 Project 配置(权限 0600)。运行你的 Agent 的机器,必然持有这些 Agent 运行所用的 key。
收回访问权限
会话是服务器上的一行记录,删掉这一行,会话立刻失效。
| 收回对象 | 操作 | 生效时机 |
|---|---|---|
| 单个会话 | penguin auth logout,或在 Web App 里登出 |
立即:删除对应记录 |
| 某个用户的全部会话 | 管理员重置这个用户的密码 | 立即:删除这个账户的所有记录 |
| 管理员自己的会话 | penguin server reset-admin-password(服务器停止时) |
下次启动时,同时打印新的首次登录链接 |
| 本地 API token | 重启服务器 | 下次启动时,同时写入新 token |
| 模型 API key | 先在供应商处轮换,再更新 Project 配置 | 在供应商处生效 |
备份泄露时
整套设计围绕最坏情况构建:数据根目录的完整备份泄露。应对办法就是轮换其中的模型 API key,再重启服务器,仅此而已。备份里的密码只是 scrypt 哈希;会话表里也只有每个 token 的 sha256,绝没有 token 本身。
备份里唯一可用的凭据,是做备份那次服务器启动写入的本地 API token,而一次重启就会更换它。此后,从备份里复制出来的任何东西都无法向运行中的服务器出示。
工作原理
会话
每个 cookie 携带一个 32 字节的随机 token。会话就是 auth_sessions 表里以 token 的 sha256 为键的那一行,其中记录着账户、建立方式(via)和过期时间。正因为这一行就是会话本身,删掉它就等于立即收回会话,而重启不会让任何人退出登录。
浏览器会话有效期 30 天。签发或上次续期之后满一天再使用,会话就原地续期 30 天:只更新记录里的过期时间,cookie 值保持不变。因此这 30 天相当于空闲超时:经常使用的会话永不过期,也不会冒出需要追查的第二份副本。只有自身寿命能撑到续期窗口的会话才会顺延,所以铸造的一小时 token 到一小时就到期。
Cookie 设置为 HttpOnly 和 SameSite=Lax。请求确实是 https,或者受信任的代理声明如此(ADELIE_TRUST_PROXY=1)时,还会加上 Secure。默认忽略 x-forwarded-proto 头。
磁盘上存了什么
| 文件 | 内容 | 保留多久 |
|---|---|---|
web.db |
密码哈希、会话哈希、应用数据 | 永久 |
<project>/.project_config.toml |
模型 API key,直接内联存放,权限 0600 | 直到下次编辑 |
cli-session.json |
一个有效的会话令牌,权限 0600 | 直到登出或过期 |
api-token |
本地 API token,权限 0600:任何请求只要在 Bearer 头里带上它,就拥有管理员权限 | 直到下次服务器启动 |
磁盘上从不以可用形式保存会话令牌(只存 sha256)和密码。你选定的密码只以 scrypt 哈希存在;预置的密码生成后立即丢弃。
本地 API token 是有意放在磁盘上的。能读到它就证明能访问数据根目录,而这本身就是管理员权限;每次启动服务器也都会更换它。
模型 API key 是唯一无法进一步降低暴露的秘密:必须原文送达供应商,因此无法哈希。它们只存在 Project 配置里,在所有 API 响应和界面中都显示为掩码,只有在真正发起请求的那一刻才以明文读取。
网络暴露面
服务器默认绑定 127.0.0.1。要对外暴露(HOST=0.0.0.0),那是部署层面的决定,必须放在 TLS 终结之后,并由代理设置 x-forwarded-proto。
API 只在规范的应用主机名下应答,这样用户生成的预览内容与应用的 cookie 就处于不同的浏览器源(origin)。
跨站请求伪造要面对两层相互独立的防线:SameSite=Lax 的 cookie,以及 Content-Type 检查:凡是 HTML 表单能产生的 Content-Type,对应的写请求一律拒绝。