编排文档

Appearance

SaaS 信任与安全模型（安装代理与控制面） ​

读者：租户管理员、安全评审、运维、售前。
目标：用非营销语言说明：平台默认不依赖对你机器的入站 SSH；安装与升级如何编排；密钥与数据面边界在哪里。便于与主仓库实现对照。
深度版（与代码同步维护）：主仓库 saas/docs/PUBLIC_TRUST_AND_OPERATIONS.md。

总原则 ​

原则说明
无入站依赖默认不假设 Portal 能随时 SSH、或反向 TCP 连到你侧租户栈；日常编排以 HTTPS 出站为主（安装代理 → Portal 心跳与领任务）。
任务公告板Portal 登记安装任务；代理 GET …/tasks/next 领取、本机执行、report / finish 上报。不是 Portal 对你进程做远程过程调用（RPC）。
SSH 为可选信使全托管可选用 PORTAL_PROVISION_COMMAND 等由控制面发起 SSH；推荐路径仍是 install-agent 拉制品，与自备机同一套任务模型。

安装代理能做什么、不能暗示什么 ​

能做的（已实现方向）

  • 领取 安装 / 升级 / 卸载 任务，拉取平台登记的 dispatcher 等制品，在本机执行安装脚本（与仓库 install.sh 约定一致）。
  • 在 与 dispatcher 同机可达 时，领取口令同步类任务，由代理 HTTP POST 本机接口完成工作台口令对齐（无额外制品下载场景下由平台排队）。

不应向终端用户暗示的

  • Portal 不会默认「随时登录你的机器」；没有代理在线、没有约定通道时，无法替你执行本机动作。
  • 控制面与代理之间不是实时双向长连接；延迟受轮询间隔与任务排队影响。

更细的代码锚点与两种「Portal—dispatcher 可达」路径，见上文深度版文档 §2–§3。

安装代理自动升级（可选） ​

为降低「客户现场装了一版后，后续只能靠人肉 SSH 升级」的运维成本，在 ROOT 维护 install_agent 制品、且现场已按文档挂载 compose 工程目录 与 docker.sock 的前提下，代理可在心跳后自动拉取新离线包、load-image、并 docker compose up -d 重建自身（与手机 App「可热更新」同类的客户端自升级链路）。

冷启动说明：从未包含自升级逻辑的极旧代理镜像，仍可能需要至少一次人工换包；之后即可依赖该链路与平台登记的 release_version 迭代。

dispatcher 升级与数据（简述） ​

租户栈 upgrade 任务成功时，约定为 先在新版本目录 docker compose up 成功，再切换 compose/current 软链；失败不切链，旧版仍为当前。细节见仓库 DISPATCHER_UPGRADE_AND_ITERATION.md 与根目录 install.sh。

轻量观测（可选） ​

Portal 可对安装代理心跳做异步 Webhook（脱敏 JSON），或向代理下发可选的 观测采集 URL；未配置则不下发字段，代理不向额外地址上报。完整口径见深度版 §5。

与公开文档的索引 ​

主题技术站 / 仓库
安装代理零基础安装代理
开通与 dispatcher 流仓库 TENANT_OPENING_AND_DISPATCHER_FLOW.md
全托管 Runbook仓库 MANAGED_PROVISION_RUNBOOK.md
信任与运维（深度）仓库 PUBLIC_TRUST_AND_OPERATIONS.md

本文与技术站其他页面随仓库演进；不替代正式合同、隐私政策或渗透测试结论。