goodbuddy/docs/features/share-server/prd.md

ShareServer PRD

文档信息

项目	内容
状态	设计中
版本	0.1
日期	2026-09-03
适用产品	独立部署的 ShareServer 与 Web 管理控制台
关联架构	共享网络总体设计
关联文档	功能逻辑、管理界面、技术设计

1. 背景

局域网配对适合附近设备，但不能统一解决跨网络访问、成员离职、组织策略、集中更新、审计和 跨组织协作。ShareServer 提供一个可自建的组织控制面，让设备通过主动出站连接注册能力并 接收任务，不要求为每台桌面设备开放公网端口。

2. 产品目标

1. 组织可在自有网络、私有云或公网独立部署 ShareServer。
2. 管理员可统一管理用户、组、设备、能力、权限、更新和审计。
3. 成员通过桌面端使用获准能力，无需日常进入管理控制台。
4. 设备离线、用户撤销或策略变化能准确影响新任务，不破坏历史证据。
5. 两个组织可经双边确认建立有限范围的联邦协作。
6. ShareServer 可以只运行控制面，也可按部署策略提供数据中继和包存储。

3. 产品范围

3.1 包含

• 本地账号及可配置 OIDC 身份源。
• 组织、成员、角色、用户组、设备组和服务账号。
• 设备注册、状态、撤销和合规元数据。
• 能力目录、Publication、Grant、强制策略和审批。
• 设备出站控制通道、任务路由、取消和可选中继。
• 签名能力包仓库、发布通道、更新策略和撤销。
• ShareServer 间双边联邦。
• 审计、用量、保留和导出。
• Web 管理控制台和成员自助页面。

3.2 不包含

• 远程管理设备桌面、任意 Shell 或任意文件系统。
• 发现未注册的局域网设备。
• 保存或分发用户 API Key、Cookie 和桌面登录状态。
• 默认查看任务正文、附件和模型输出。
• 未经提供者发布自动盘点设备能力。
• 自动信任同域邮箱、同一网络或其他 ShareServer。
• 公共开放市场、计费结算或匿名能力调用。
• 替代 GoodBuddy 官方客户端、模型和 Agent 发布源。

4. 功能需求

FR-1 实例初始化

• 首次启动通过一次性引导创建实例标识和首个系统管理员。
• 引导完成后永久关闭初始化入口，后续管理员通过正常身份流程创建。
• 实例公开描述包含名称、协议版本、登录方式和联邦端点，不包含内部拓扑。

FR-2 身份与组织

• 支持一个实例承载多个隔离组织，也支持部署为单组织模式。
• 支持本地账号和 OIDC；组织可限制允许的身份源。
• 成员可以属于多个组并拥有有界角色，角色不隐式跨组织。
• 停用用户立即停止签发新设备和任务凭据。

FR-3 设备管理

• 桌面端经用户登录、一次性挑战和设备签名完成注册。
• 设备条目显示所有者、平台、客户端版本、最近在线、连接和撤销状态。
• 设备主动建立出站控制连接；服务端不能借此调用未发布能力。
• 管理员可撤销设备并终止其新任务资格。

FR-4 能力目录

• 只接收已注册设备或服务节点提交的显式 Publication。
• 目录按调用者身份、设备状态、组织和策略过滤后返回。
• 支持同一能力多个版本和多个 provider，不掩盖来源。
• provider 离线时保留目录事实但显示不可用，不派发新任务。

FR-5 授权策略

• Grant 可绑定用户、组、设备、设备组和联邦组织。
• 可约束能力、版本、动作、输入类型、数据分类、提供者、时间、次数、并发和委托。
• 支持组织强制策略和用户可收紧偏好；拒绝优先。
• 每个决定返回稳定结果、命中策略和面向用户的原因。

FR-6 审批

• 调用、能力发布、权限扩大更新和联邦关系可以要求审批。
• 审批项显示申请人、对象、影响范围、数据类别、期限和策略依据。
• 批准结果有明确范围和有效期，不提供无边界“永久允许”。
• 申请内容变化后旧审批失效。

FR-7 任务路由

• 根据冻结 provider、在线连接和路由策略把任务声明发送给目标设备。
• 支持直连协商、网关中继和取消传播。
• 任务正文与控制元数据分离；默认审计不保存正文。
• 已接受任务断线后允许查询同一 task，不自动创建重复执行。

FR-8 能力包与更新

• 保存不可变签名 Package 和发布目录。
• 支持组织、组、平台、架构和维护窗口的更新策略。
• 支持固定版本、允许版本范围、暂停发布和紧急撤销。
• 权限扩大必须触发新批准，不能被普通自动更新策略覆盖。
• 包来源、大小、摘要、签名和下载结果可审计。

FR-9 联邦

• 两个 ShareServer 通过指纹交换和双方管理员确认建立关系。
• 双方分别配置公开能力、允许主体、数据范围、用量和期限。
• 最终权限取双方策略交集；任一端撤销后停止新任务。
• 不默认链式转发到第三个组织。

FR-10 审计与用量

• 记录身份、设备、发布、授权、审批、任务、包和联邦管理事件。
• 默认仅记录共享架构定义的有界元数据。
• 支持按组织隔离查询、条件筛选、分页和流式导出。
• 审计员只读，不能因查看日志取得任务正文或管理权限。

FR-11 管理控制台

• 提供概览、组织与成员、设备、能力目录、权限策略、审批、发布与更新、网关联邦、任务与 中继、审计、系统设置。
• 普通成员只看到自己的设备、授权和待办；管理员栏目按权限隐藏并在 API 再次校验。
• 所有高影响操作说明对象、范围和后果。

FR-12 可部署性

• 支持容器部署，配置与持久数据分离。
• 支持外部 PostgreSQL；对象存储和中继按功能启用。
• 提供健康、就绪、指标、结构化日志、备份和恢复说明。
• 服务升级不能要求同时升级所有在线桌面端；按协议版本协商兼容集合。

5. 产品验收

• 新实例可完成初始化、登录、创建组织、邀请成员和注册真实桌面设备。
• 两个不同组织不能通过 API、搜索、计数、错误或审计结果读取对方数据。
• 设备只有发布能力后才进入获准目录，撤销后不能接收新任务。
• 调用授权能同时处理用户、设备、组织、提供者、数据和联邦限制。
• 任务中继关闭时控制面仍可运行；中继开启时可取消并形成准确终态。
• 权限扩大的包更新不能自动部署。
• 两个独立 ShareServer 能建立、使用、暂停和撤销双边联邦。
• 备份恢复后组织、策略、发布和审计身份保持一致，短期连接和令牌不恢复。