STACIO WIKI · 集成规范

堡垒机与 Stacio 集成适配规范

本规范定义堡垒机与 Stacio 的两类集成方式：连接文件导入与通过 stacio:// URL Scheme 直接调起。

1. 文档目的

本规范定义堡垒机与 Stacio 的两类集成方式：

堡垒机导出远程连接文件，用户导入 Stacio；
堡垒机 Web 页面通过 stacio:// URL Scheme 直接调起 Stacio。

厂商可以只实现文件导入，也可以同时实现 Web 调起。推荐同时支持两种方式：文件导入适合迁移和批量配置，URL 调起适合用户在堡垒机 Web 控制台中点击即连。

2. 安全边界

连接文件和 URL 中不得放置明文密码、私钥、长期 Token 或 OTP。
Stacio 只接受明确声明的协议和字段，不执行 URL 中携带的任意 Shell 命令。
URL 请求必须包含过期时间、请求 ID 和一次性 nonce；建议使用厂商签名。
首次使用某厂商或签名校验失败时，Stacio 必须显示确认界面。
导入密码字段时只提示用户重新在 Stacio 钥匙串中配置，不写入普通会话数据库。
厂商不得通过此协议绕过堡垒机权限、审批、审计或二次认证。

3. 文件导入

3.1 推荐文件类型

Stacio 适配器按文件格式识别，不以文件扩展名作为唯一依据：

OpenSSH config；
Xshell .xsh；
Xftp 会话文件；
SecureCRT session/INI；
厂商自定义 INI、JSON、XML、TXT；
多会话 ZIP 包。

3.2 标准字段映射

标准字段	必填	说明
`name`	是	Stacio 会话名称
`protocol`	是	`ssh`、`sftp` 等
`gatewayHost`	是	堡垒机或代理入口
`gatewayPort`	是	堡垒机 SSH/SFTP 端口
`gatewayUsername`	否	堡垒机登录用户
`targetHost`	否	目标资产地址
`targetPort`	否	目标资产端口
`targetUsername`	否	目标资产账号
`assetId`	否	堡垒机资产 ID/资源 ID
`accountId`	否	堡垒机账号 ID
`privateKeyPath`	否	仅保存本地路径，不复制私钥内容
`proxyCommand`	否	受限的 OpenSSH 代理模板
`tags`	否	厂商、项目或环境标签

如果堡垒机要求特殊账号格式，例如 SSH@account@asset，适配器应将最终登录用户名保存为实际连接所需的值，不能自行拆解后丢失语义。

3.3 导入流程

用户选择或拖入文件；
Stacio 根据扩展名、MIME、文件头和内容特征识别格式；
解析为标准字段；
展示主机、端口、用户名、资产和认证方式预览；
对重名会话提示覆盖、跳过或重命名；
敏感字段脱敏并忽略明文密码；
用户确认后写入会话数据库；
用户选择立即连接或稍后连接。

3.4 厂商适配提交材料

每个厂商/版本至少提供：

一份脱敏的单会话导出文件；
一份脱敏的多会话导出文件；
文件格式和字段说明；
堡垒机地址、端口和用户名拼接规则；
资产 ID/账号 ID 是否必填；
SFTP 是否复用 SSH 字段；
是否依赖本地插件、CLI 或证书；
认证字段的生命周期和过期规则；
正常连接、过期和权限拒绝样例。

4. Web 页面直接调起 Stacio

4.1 URL Scheme

Stacio 注册自定义 Scheme：

stacio://

打开已有会话：

stacio://open-session/{sessionID}

其中 sessionID 必须进行 URL 编码。

创建临时连接请求：

stacio://connect?v=1&vendor=example&request_id=req-123&expires_at=2026-07-21T12%3A00%3A00Z&nonce=abc123&payload=...&signature=...

4.2 连接请求字段

推荐载荷字段如下：

{
  "version": 1,
  "vendor": "example",
  "protocol": "ssh",
  "gatewayHost": "bastion.example.com",
  "gatewayPort": 60022,
  "gatewayUsername": "SSH@account@asset",
  "targetHost": "10.0.0.8",
  "targetPort": 22,
  "targetUsername": "root",
  "assetId": "asset-123",
  "accountId": "account-456",
  "requestId": "req-123",
  "nonce": "abc123",
  "expiresAt": "2026-07-21T12:00:00Z"
}

推荐使用 Base64URL 编码的 JSON 作为 payload，并对规范化后的载荷进行签名。签名算法和公钥分发方式由厂商与 Stacio 另行约定。

4.3 Stacio 处理行为

已安装 Stacio：唤起应用并处理请求；
未安装 Stacio：跳转官网安装页；
参数缺失、过期、签名错误或协议不支持：拒绝连接并显示原因；
未知厂商：按通用 SSH 处理，但必须显示用户确认；
请求包含保存标记时，默认仍先创建临时会话，由用户确认是否保存；
URL 调起不得静默保存密码或长期凭据。

4.4 浏览器页面示例

<a href="stacio://connect?v=1&amp;vendor=example&amp;request_id=req-123&amp;expires_at=2026-07-21T12%3A00%3A00Z&amp;nonce=abc123&amp;payload=PAYLOAD&amp;signature=SIGNATURE">
  使用 Stacio 连接
</a>

厂商应同时提供“下载连接文件”和“使用 Stacio 连接”两个入口，避免用户未安装 Stacio 时无法继续工作。

5. 代理和 CLI 型堡垒机

部分产品不是普通 SSH 入口，而是依赖本地 CLI 或代理，例如 Teleport、AWS SSM、Azure Bastion、GCP IAP、Boundary 等。此类厂商应提供：

CLI 名称和最低版本；
本地可执行文件路径发现规则；
目标资源 ID；
受限的 ProxyCommand 模板；
CLI 登录状态检查方式；
退出码和错误码映射。

Stacio 只允许使用内置适配器生成的命令模板，不直接执行未经校验的 URL 文本。

6. 厂商适配优先级

第一阶段：OpenSSH、Xshell、SecureCRT、JumpServer、天融信、深信服、奇安信、安恒、阿里云、腾讯云、华为云。

第二阶段：360、Teleport、AWS SSM、Azure Bastion、GCP IAP、CyberArk、BeyondTrust 及其他依赖 CLI/代理的产品。

同一厂商的公有云、私有化和不同大版本必须分别登记格式版本，不能默认互相兼容。

7. 验收清单

能识别并导入单会话和多会话文件；
预览显示的网关、端口、账号、资产与厂商客户端一致；
导入后能通过堡垒机完成 SSH 连接；
SFTP/Xftp 场景不会误当成普通 SSH；
密码、Token、私钥不会出现在日志、URL、导出 JSON 或诊断包中；
过期 URL、重复 nonce、无效签名会被拒绝；
未安装 Stacio 时网页有降级路径；
厂商版本变化时能给出“不支持的格式版本”而不是静默连接错误；
所有适配器都有脱敏样例和自动化解析测试。

8. 联系与版本登记

厂商接入时应提交：厂商名称、产品名称、部署形态、版本号、文件格式版本、URL 调起协议版本、签名公钥、测试环境和联系人。Stacio 官网 Wiki 应为每个厂商维护独立的适配状态、支持版本和已知限制。