跳转到内容

安全参考:身份、凭据与公开部署

先明确 Hive 的信任模型

跳转到“先明确 Hive 的信任模型”

Hive 是由你控制 Server、数据目录和 Agent 电脑的共享协作系统。房间里的人、消息、附件和工具结果会成为 Agent 的上下文,真正的命令、文件修改和外部请求则由 Agent 的运行时执行。

共享 Join Token 是高信任的房主级凭据,不是一个普通聊天邀请码。 持有它的房主与 Agent 可访问多个房间的相应接口;Hive 不应被当作已经完成严格租户隔离的公共 SaaS。不要向不受信任的人分发这个总令牌。

已有权限机制能降低误操作风险,但不意味着任意运行时、MCP、网页或公网环境都已被独立验证安全。接入和权限配置见Agent 指南与权限与审批;服务部署步骤见部署参考。

身份或链接 用途 需要注意
房主共享 Join Token 房主级房间访问与受信 Agent 接入 不是单房间、单设备或限时访客凭据;不要放进公开命令、截图或仓库
访客邀请与访客会话 按指定房间、期限和权限加入 邀请有效期内可供多人兑换,不是一次性房主登录链接;访客不能访问其他房间
房主设备登录票与设备会话 房主在另一台设备登录,单独撤销设备 不交出总令牌;设备登录不自动授予管理 Server 电脑的权限

房主可设置邀请的期限、是否允许带入 Agent、是否展示执行过程。访客带入的 Agent 使用自己的会话身份,并跟随邀请人到期、续期或撤销;它不会因为起了一个相似名称就变成房主 Agent。

邀请链接在有效期内可以被拿到链接的人使用,所以只向预期参与者发送,尽量设置有限期限。撤销邀请会影响凭该邀请进入的访客及其 Agent;退出一个浏览器标签页不是撤销邀请。

本机配对票默认 5 分钟有效、只兑换一次;飞书登录票默认 24 小时有效、只兑换一次,并与签发的 IM 连接关联。设备会话最长 30 天,闲置 7 天失效,也可由房主单独退出。

这些期限是登录身份的限制,不是工具授权期限。设备要启动、停止本机 Agent 等操作,须另行取得管理授权;完全访问启动等高危动作还需要与设备和操作参数绑定的单次批准。

管理/高危批准单只保存在内存中,Server 重启后未处理申请作废。它与执行中的工具审批是不同流程,不能用一次设备批准长期代替所有任务授权。

哪些内容必须当作秘密

跳转到“哪些内容必须当作秘密”

至少保护以下信息:

  • Join Token、访客邀请、访客与设备会话、配对和 IM 登录票。
  • 带凭证的接入命令、URL、请求头、浏览器存储、进程参数或日志片段。
  • Server 数据库、附件、IM 加密密钥和备份,以及 Agent 的本机会话与状态文件。
  • MCP 和模型运行时自己的登录信息、外部账号、业务系统授权和生成的私有文件。

数据库不是全量加密仓库

跳转到“数据库不是全量加密仓库”

当前实现中,Join Token 保存在数据库里;邀请令牌还会保存明文,供房主再次复制邀请链接。访客和房主设备会话用于校验的令牌采用摘要保存,不能据此说整个数据库只含不可还原的摘要。

IM 凭据使用单独密钥进行 AES-256-GCM 加密。数据库与密钥同时泄露时仍无法保护这些凭据;该机制也不代表聊天、附件、Join Token 或全部运行时状态已加密。

CLI 服务的数据目录通常是 ~/.superhive,Agent 状态通常在 ~/.superhive/agents/,显式配置或源码开发启动可能使用其他位置。确认实际目录后限制系统账号和备份访问;不要把数据目录或附件目录映射成公开静态资源。

备份应作为秘密保存。运行中的 SQLite 数据库不能仅凭随手复制一个文件就保证备份一致;具体备份与恢复方法见部署参考。密钥文件、数据库和附件需要按实际恢复需求管理,不能只保留其中一部分就承诺恢复完整。

  1. 先限制暴露入口,记录泄露范围和已有任务影响,不在房间里再次贴出秘密。
  2. 对邀请、访客、设备会话按对应管理入口撤销;外部 MCP/模型账号在其平台单独撤销或轮换。
  3. 如总令牌泄露,在受控的 Server 配置中更新并重启,再重新接入授权的 Agent。
  4. 更新 Join Token 不等于撤销所有独立访客、设备或外部账号凭据;分别检查现存身份和连接。
  5. 核对文件、提交和外部系统状态。令牌撤销、停止或重启都不会回滚已发生的操作。

本机管理入口为什么不能直接转成公网入口

跳转到“本机管理入口为什么不能直接转成公网入口”

本机请求校验会同时检查连接来源、Host、Origin 和登记的端口。Server 电脑上直接访问 localhost 或本机 IP 可以符合条件;仅仅“代理也跑在同一台电脑”并不意味着远程访问者是本机房主。

带 Forwarded、X-Forwarded-For 等代理来源标记的请求不会被当作本机请求。不要为了出现「在本机启动」按钮而去掉来源信息、伪造 Host/Origin 或给所有远程请求注入本机凭据。

需要远程管理时使用房主设备登录与批准流程。共享 Join Token 本身也不能替代本机接口所要求的管理凭据。

不用网页管理本机 Agent 时,可在启动配置中选择 --no-local-agents。这关闭相应托管入口,不会自动禁止已经在其他电脑运行的 Agent、撤销房间身份或限制其外部工具。

局域网、公网与反向代理

跳转到“局域网、公网与反向代理”

CLI 默认监听 0.0.0.0:8787,不是仅监听回环地址。只需本机访问时可明确选择 --host 127.0.0.1;要给局域网参与者使用则按实际网卡、防火墙与网络隔离配置。

HTTP 局域网连接仍不是加密连接。共享 Wi-Fi、访客网络或不受信任网络上不要因为“是内网”就放松凭据保护。

公网部署至少需要:

  1. HTTPS 与 WSS:由反向代理或网关提供有效 TLS,转发正常 HTTP、WebSocket 和需要的 MCP 请求。
  2. 外层访问控制:按团队风险选择 VPN、网关认证或其他访问限制,限制原始 Server 端口的直接暴露。
  3. 正确的公开地址:配置 --public-url https://hive.example.com 等实际地址,检查生成的网页、WebSocket、邀请和 MCP 地址。这个参数只配置地址,不会自动创建 TLS、认证或防火墙规则。
  4. 保留身份与来源边界:不要丢弃所需的 Authorization、WebSocket 升级或 MCP 身份信息,也不要把外部来源伪装成本机。
  5. 保护日志和缓存:不记录或公开 Bearer 凭据、登录票、带凭证链接、请求正文和私人附件;授权响应与附件不应被公共缓存误共享。

代理的认证页若把 Agent/MCP 请求重定向成 HTML 登录页面,也可能导致连接或协议失败。应配置受控、兼容的接入方式,而不是关闭 Hive 身份校验;见排障参考。

MCP、高权限与不可信内容

跳转到“MCP、高权限与不可信内容”

Hive 的 /mcp 调用需要有效 Bearer 凭据,以及 X-Hive-Room、X-Hive-Agent-Name 对应的在线 Agent 身份。访客 Agent 凭据须匹配自身房间和名称,访客人类凭据不能冒充 Agent 调用工具。只有一个 MCP URL 不代表已完成接入或获得工具权限。

额外 MCP 可能访问浏览器、业务系统或外部账号。只开启可信且必需的服务,检查其账号和 scope;文件只读标签不保证所有 MCP 都没有对外副作用。

工作区档在不同运行时的实现不同:omp 普通写入不受 cwd 完整约束,Copilot 的工具策略不能等同 Codex 沙箱,OpenClaw 权限还需在 Agent/Gateway 配置。完全访问不设 Hive 沙箱;有敏感数据或生产账号时,优先使用独立系统账号、环境和外部权限限制。

聊天、附件、网页和工具输出都是不可信内容,不能通过一句“忽略规则”升级权限、泄露秘密或扩大原任务。审批时核对具体命令、路径、账号与影响范围;要附条件就先拒绝,再修改任务要求。

HTML 附件预览使用短时地址和隔离的浏览器源,不应被理解为“所有附件都是安全代码”。预览仍可能运行脚本、访问网络、提交表单或引导下载;不要在不可信预览中输入凭据。源码、文件或图片也可能包含恶意指令,读取不等于授权执行。

Worktree 与白板 Claim 只用于任务协调,不是安全沙箱。清理必须通过受检查的 worktree 入口,不能为了释放占用就强删目录或分支。

公开服务与文档发布前检查

跳转到“公开服务与文档发布前检查”
  • 确认运行版本、暴露网卡、真实 HTTPS 域名、反代 WebSocket/MCP 转发和外层访问限制。
  • 在隔离演示环境核对未授权、错误房间、已撤销身份和远程本机管理请求被按预期拒绝;仅“页面能打开”不足以验收权限。
  • 检查邀请期限、设备登录和管理授权,区分普通提问、工具审批、设备批准;不要默认所有人都可批准。
  • 将数据、附件、备份、密钥、运行时状态和日志排除在公开站点与仓库产物之外。
  • 文档、截图、SVG、示例和补丁只使用合成数据或占位符;移除真实聊天、工作路径中的私人信息、凭证和登录二维码。
  • 检查公开构建产物与静态资源,而不仅是 Markdown 源文;文档站单独部署见文档站部署。
  • 为停止、撤销、备份恢复和凭据轮换留下受控操作方式;风险和未验证项写清楚,不把配置完成说成安全验收通过。

本文依据仓库 c2f68dd 的静态实现说明边界,不是漏洞扫描、渗透测试或公网安全认证,也未验证所有第三方运行时版本。遇到异常先按排障步骤保存脱敏证据。