Initialize cross-platform workspace host scaffold

2026-09-29 11:30:51 +08:00
commit 4bc3552167
56 changed files with 2627 additions and 0 deletions
@@ -0,0 +1,17 @@
+# 平台发布与部署
+
+| 项目 | Windows | Linux |
+| --- | --- | --- |
+| 发布 RID | `win-x64`、`win-arm64` | `linux-x64`、`linux-arm64` |
+| 产品入口 | `WorkspaceAccessHost.exe host` / `agent` | `WorkspaceAccessHost host` / `agent` |
+| 服务管理 | SCM 注册、启动类型和账户配置 | systemd unit、服务账户和目录权限 |
+| 用户代理启动 | 用户登录启动任务或用户启动项 | 用户上下文启动组件或 user unit |
+| 本机通信路径 | 命名管道 | `/run` 下受控 socket 路径 |
+
+NUKE `Publish` 先执行 Verify，再发布单一产品的 self-contained 产物，并复制平台部署模板。输出位于 `artifacts/publish/<runtime>/`，根目录包含可执行文件、配置与运行时依赖，`deploy/` 包含部署模板。Host 和 Agent 使用同一可执行文件，通过启动参数选择角色，整套产物统一部署和更新。
+
+服务配置使用发布目录中的 `appsettings.json` 和 .NET 环境变量覆盖。初始 HTTP 端点位于 loopback。远程传输集成时由受控 TLS 入口提供 WSS，并配置 host 白名单、认证及 Origin 策略。
+
+x64 的 Windows 与 Linux 验证流程由 CI 分别执行。ARM64 产物通过指定 RID 发布，并在对应硬件或虚拟机完成运行验收。
+
+部署步骤见 [Windows](../../deploy/windows/README.md) 与 [Linux](../../deploy/linux/README.md)。服务安装由部署人员执行。
@@ -0,0 +1,16 @@
+# 进程权限与隔离
+
+| 层次 | Windows | Linux |
+| --- | --- | --- |
+| 账户权限 | 用户访问令牌、SID 与文件 ACL | UID、GID、附加组与文件权限 |
+| 代理 IPC | 命名管道 ACL 与对端身份校验 | socket 路径权限与 peer credentials |
+| 进程归属 | Job Object 与进程句柄 | 进程组与 systemd/cgroup |
+| 系统管理 | 令牌权限及提升策略 | capabilities、sudo、polkit |
+
+网络宿主以服务账户执行网络与授权逻辑；用户代理以目标账户执行终端程序。身份切换或代理创建接口接受经过验证的账户映射和限定启动参数。
+
+工作区清理追踪完整进程树。显式结束先执行有序退出，再按策略终止剩余进程，并释放 PTY 及本机通信资源。
+
+完全复用用户环境时，终端具备该用户相应的系统访问能力。部署权限策略决定进程提升、系统管理和共享目录访问范围。文件权限在实际存储后端验收，见[存储说明](storage.md)。
+
+验收包括不同账户的代理访问、伪造映射、越权工作目录、子进程清理，以及普通账户的管理权限边界。
@@ -0,0 +1,16 @@
+# 服务宿主与本机通信
+
+| 平台 | 系统入口 | 用户代理通信 |
+| --- | --- | --- |
+| Windows | Windows Service Control Manager；`AddWindowsService` | 带 SID ACL 的命名管道 |
+| Linux | systemd system unit；`AddSystemd` | 带文件权限和对端凭据检查的 Unix domain socket |
+
+Host 负责远程连接与控制权仲裁，用户代理持有工作区。服务账户具备配置读取与本机通信所需的权限。IPC 连接建立后验证协议版本、对端系统身份和目标账户。
+
+Windows 代理在目标用户登录时启动。Linux 用户代理由用户上下文启动组件管理。本机通信路径按 host 与系统用户标识确定，进程启动后执行注册握手。
+
+当前 Host 已集成系统服务生命周期与健康检查。IPC 注册属于后续集成项。部署入口见 [Windows](../../deploy/windows/README.md) 与 [Linux](../../deploy/linux/README.md)。
+
+验收：服务随系统启动；服务停止完成资源清理；代理识别正确服务身份；其他账户访问 IPC 时按规则返回拒绝结果。
+
+参考：[Windows Service](https://learn.microsoft.com/en-us/dotnet/core/extensions/windows-service)、[systemd 集成](https://devblogs.microsoft.com/dotnet/net-core-and-systemd/)。
@@ -0,0 +1,16 @@
+# 会话生命周期
+
+| 事件 | Windows | Linux |
+| --- | --- | --- |
+| 创建工作区 | 已登录用户代理建立 ConPTY | 用户上下文中的代理建立 PTY |
+| 网络断开 | 代理继续持有终端和进程 | 代理继续持有终端和进程 |
+| 同身份重新连接 | 重新授权并附着原工作区 | 重新授权并附着原工作区 |
+| 锁屏或关闭桌面连接 | 用户登录会话仍存在时保持工作区 | 按用户代理所属服务生命周期保持工作区 |
+| 用户注销 | 用户代理及进程受 Windows 登录会话清理影响 | 按 user service、会话清理及 linger 配置执行 |
+| 系统启动 | 等待目标用户代理注册后建立新工作区 | 服务准备用户上下文后建立新工作区 |
+
+持久性范围为系统本次运行期间、用户代理存活时的工作区。客户端断线仅解除连接；工作区终止是独立的授权操作。
+
+连接归属在断线后保留。同一身份重连获取新控制权，接管撤销旧连接。会话管理器完成进程清理后释放工作区归属。broker 重启后的代理重新登记属于协议集成验收范围。
+
+验收分别执行网络断开、浏览器关闭、锁屏、用户注销、代理退出和显式终止，记录工作区状态与进程结果。系统重启后验证新环境的建立条件。
@@ -0,0 +1,30 @@
+# 文件存储与 VirtioFS
+
+| 项目 | Windows | Linux |
+| --- | --- | --- |
+| 本地文件 | NTFS 等本地卷，使用 Windows 文件 API 与权限 | 原生文件系统，使用 POSIX 文件 API 与权限 |
+| 宿主共享目录 | Windows VirtioFS 驱动与 WinFsp | VirtioFS 客户端与宿主目录 |
+| 身份映射 | 验证 SID、挂载配置和宿主 UID/GID 的关系 | 验证 UID/GID、附加组及宿主权限 |
+| 变更与锁 | 验证 Windows 通知、共享模式和锁的传播 | 验证文件通知、锁及跨挂载访问行为 |
+
+## 路径安排
+
+服务配置、运行元数据及用户配置优先放在操作系统本地卷。项目文件可放在 VirtioFS 工作目录。挂载可用性和目标用户访问检查在创建工作区前执行。
+
+并行编辑为本地操作与远程操作分配独立工作目录。代码项目可以采用独立 clone 或 Git worktree，通过版本控制整合修改。远程连接独占管理客户端控制权，文件写入由应用与存储权限决定。
+
+## 兼容性记录
+
+每个部署记录 PVE、virtiofsd、Windows virtio-win / WinFsp 版本、宿主文件系统、导出路径和挂载选项。
+
+| 验证项 | 场景 |
+| --- | --- |
+| 可见性 | 目标用户代理上下文访问预期盘符或挂载点 |
+| 权限 | 两个系统账户分别读取、创建、修改和删除文件 |
+| 外部变更 | Windows 本地程序、宿主和其他 guest 修改文件后，编辑器观察变化 |
+| 锁 | 不同进程及不同访问入口的独占锁和共享模式 |
+| 保存 | 临时文件写入后重命名替换、刷新、重复保存 |
+| 路径 | Unicode、大小写、长路径与符号链接 |
+| 开发工具 | Git 操作、构建输出、文件监听和高频小文件访问 |
+
+参考：[Windows VirtioFS](https://github.com/virtio-win/kvm-guest-drivers-windows/wiki/Virtiofs:-Shared-file-system)、[Git worktree](https://git-scm.com/docs/git-worktree)。
@@ -0,0 +1,17 @@
+# 系统管理权限
+
+| 能力 | Windows | Linux |
+| --- | --- | --- |
+| 本机关机和重启 | 系统用户权限分配，包含 `SeShutdownPrivilege` | 登录会话授权、polkit、sudo 或 root 权限 |
+| 网络发起系统关机 | 对应远程管理权限及服务策略 | 对应远程管理服务和账户策略 |
+| 提升执行权限 | Windows 用户令牌与提升机制 | sudo、capabilities 及服务管理接口 |
+
+终端使用目标系统账户的权限。部署阶段明确该账户的系统管理能力，并使用操作系统策略控制可执行的管理操作。通过远程终端运行的程序属于目标机器上的本地进程。
+
+复用登录用户时，账户级权限策略也作用于该用户的其他程序。需要不同权限边界的部署使用专用执行账户或经过验证的受限上下文。
+
+管理入口与普通终端输入分别授权。系统管理操作记录请求身份、目标、时间和执行结果。系统启动后的工作区状态由[用户环境](user-environment.md)和[生命周期](session-lifecycle.md)定义。
+
+验收使用系统权限查询和具有代表性的系统管理 API，确认工作区与管理入口符合配置。PTY 输入作为终端字节流处理。
+
+参考：[Windows 关机 API 权限](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-exitwindowsex)。
@@ -0,0 +1,16 @@
+# 终端后端
+
+| 项目 | Windows | Linux |
+| --- | --- | --- |
+| 伪终端 | ConPTY | POSIX PTY master/slave |
+| 进程连接 | 伪控制台通过扩展启动属性关联用户进程 | session、控制终端、标准流和前台进程组 |
+| 尺寸变更 | `ResizePseudoConsole` | 窗口尺寸 ioctl 与终端信号行为 |
+| 生命周期 | 用户进程、管道和伪控制台句柄 | 子进程、进程组和 PTY 文件描述符 |
+
+共享接口为 `IPtySessionFactory` 与 `IPtySession`。终端输入输出按字节传递；用户代理负责持续读出、缓冲边界及终端状态。平台实现明确句柄所有权、取消和资源释放顺序。
+
+Windows 后端在用户代理上下文中创建 shell。Linux 后端使用适合托管运行时的原生启动边界完成进程和终端设置，子进程进入目标程序前完成系统调用配置。
+
+验收覆盖交互 shell、UTF-8、方向键、Ctrl+C、全屏编辑器、尺寸变更、大量输出、子进程退出及显式终止。断线后的输出持续被消费，重连恢复见[连接协议](../connection-protocol.md)。
+
+参考：[ConPTY 会话](https://learn.microsoft.com/en-us/windows/console/creating-a-pseudoconsole-session)、[Linux PTY API](https://man7.org/linux/man-pages/man3/openpty.3.html)。
@@ -0,0 +1,20 @@
+# 用户执行环境
+
+| 平台 | 环境建立 | 身份标识 | 就绪条件 |
+| --- | --- | --- | --- |
+| Windows | 复用目标用户登录后的代理上下文 | Windows SID | 指定用户的代理已注册 |
+| Linux | 为现有系统账户设置 UID、GID、附加组及用户会话 | UID 与组信息 | 账户解析、权限设置及代理启动完成 |
+
+## Windows
+
+标准部署使用目标用户登录后启动的 Agent。它继承用户权限和用户配置，终端启动时设置工作目录、环境变量和 shell 参数。专用本地账户可以作为远程工作区账户。
+
+Host 根据外部身份映射匹配该用户的 SID。目标用户代理尚未注册时，工作区状态为 `WaitingForUserSession`。锁屏状态下保留用户会话；用户注销后的行为见[生命周期](session-lifecycle.md)。
+
+## Linux
+
+系统账户由操作系统维护。启动组件按授权映射查询账户，初始化附加组、主组、UID、HOME、工作目录和登录环境；部署所需的 PAM account/session 处理归入该组件。用户代理以目标账户身份持有 PTY。
+
+## 验收
+
+检查终端中的系统身份、主目录、配置目录、环境变量和文件访问结果。Windows 验证登录前的等待状态与登录后的代理注册；Linux 验证无人交互登录时的用户上下文建立。认证归属与系统账户映射见[认证文档](../authentication.md)。