# ShareServer PRD

## 文档信息

| 项目 | 内容 |
| --- | --- |
| 状态 | 设计中 |
| 版本 | 0.1 |
| 日期 | 2026-09-03 |
| 适用产品 | 独立部署的 ShareServer 与 Web 管理控制台 |
| 关联架构 | [共享网络总体设计](../../architecture/share-network-architecture.md) |
| 关联文档 | [功能逻辑](./logic-design.md)、[管理界面](./ui-design.md)、[技术设计](./technical-design.md) |

## 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 能建立、使用、暂停和撤销双边联邦。
- 备份恢复后组织、策略、发布和审计身份保持一致，短期连接和令牌不恢复。