# Support Matrix

Waterfall AI 目前处于公开 Beta 阶段。社区支持边界是可信环境、单租户、
单应用实例和 Linux/amd64 Docker。

本页描述技术兼容边界；问题处理方式见 [SUPPORT.md](../SUPPORT.md)。

## 部署环境

| 场景 | 状态 | 说明 |
| --- | --- | --- |
| 单一组织、受控网络、可信账号 | 支持 | 当前安全模型的基础假设 |
| Linux/amd64 Docker 单实例 | 支持 | 使用确实存在且已验证的对应 Release bundle/digest，或从固定 source release 构建 |
| TLS 反向代理 | 必需 | 平台不直接向公网暴露 |
| Linux 本地开发与测试 | 尽力支持 | 不等同于生产部署承诺 |
| Linux/arm64、Windows/macOS 原生生产部署 | 不支持 | 可用于个人开发或模拟，但不作为发行门槛 |
| 公网开放注册或匿名访问 | 不支持 | 无不可信用户安全承诺 |
| 多租户共享实例 | 不支持 | 无租户级隔离保证 |
| 多副本或高可用 | 不支持 | 当前存在进程内锁和任务状态 |
| Kubernetes、无服务器或跨区域 | 不支持 | 未验证调度、存储和迁移语义 |
| Podman 及其他容器运行时 | 未验证 | 社区可提供最小复现后讨论 |

“支持”表示维护者接受符合边界、可复现且已脱敏的问题，不表示提供服务等级协议或生产责任承诺。

## 组件兼容

| 组件 | 支持范围 |
| --- | --- |
| 应用镜像 | Release 元数据固定的 GHCR digest；源码重建镜像须另行记录摘要 |
| Python | 当前 source release 的构建清单所选版本 |
| Node.js | 当前 source release 的构建清单所选版本 |
| Playwright | 当前 release 锁定的包和浏览器组合 |
| 浏览器 | source release 构建清单安装并经过测试的 Playwright 浏览器 |
| MySQL | 当前 release CI 或发布验证使用的版本 |
| OpenCode/模型服务 | 满足当前配置和 API 契约、由部署者批准的服务 |
| TLS 代理 | 能正确转发普通 HTTP 与 SSE 的受维护代理 |
| Git | 当前 source release 构建清单安装并验证的版本 |

精确版本以 release notes、依赖锁文件，以及部署者从最终镜像生成的元数据和
SBOM 为准。主分支上的偶然可运行组合不自动成为受支持组合。

平台容器与 OpenCode 服务显示健康，仅表示进程和本地服务检查通过。Agent 能力还
要求单独配置组织批准的模型 Provider，并成功完成最小认证推理冒烟；两种状态不能
合并报告。

## 存储

| 存储形态 | 状态 | 说明 |
| --- | --- | --- |
| Linux 本地持久化卷 | 支持 | 必须同时保存文件和 `.git` |
| 由单个应用实例独占的托管块存储 | 支持 | 需保持普通文件系统语义 |
| 临时容器文件系统 | 不支持 | 容器重建会丢失项目和 revision |
| 多实例共享网络文件系统 | 未验证 | 锁、原子替换和 Git 语义可能不同 |
| 对象存储直接替代工作区 | 不支持 | 当前实现需要文件系统和 Git |

`mysql_data`、`platform_projects`、`platform_workspaces` 及其 `.git`、OpenCode
config/data/cache/state 四卷和 `config.json`/`.env`/Release 元数据必须作为一致
恢复点加密备份。只恢复其中一部分可能造成 revision、文件和会话状态不一致。

## 被测系统和模型

| 场景 | 状态 |
| --- | --- |
| 经授权、隔离、可恢复的测试系统 | 支持 |
| 受限网络中的组织批准模型服务 | 支持 |
| 包含脱敏测试数据的非生产环境 | 支持 |
| 生产系统或真实客户数据 | 不支持 |
| 不受限模型工具访问宿主机或公网 | 不支持 |
| 未知来源的浏览器扩展、脚本或模型插件 | 不支持 |

被测系统凭据、模型凭据和页面数据由部署者负责管理。模型/平台服务凭据不得进入
测试链路；被测系统凭据可能进入 Prompt、脚本、仓库和日志，因此只能使用可撤销、
最小权限的非生产账号。任何凭据和内部数据都不得进入公开诊断材料。

## 发行与定制

| 版本或修改 | 状态 |
| --- | --- |
| 最新受支持 Beta release | 仅在公开 Release 实际存在且 Minisign 签名与附件验证通过时支持；Draft 不算公开发行 |
| 默认分支最新提交 | 尽力支持 |
| 历史标签 | 不支持 |
| 自定义基础镜像 | 不支持 |
| 修改依赖锁文件或浏览器版本 | 不支持 |
| 第三方重打包 | 不支持 |
| 本地补丁或长期 fork | 尽力定位上游可复现问题 |

报告定制环境的问题时，应先在未修改的当前发行物中复现。安全漏洞无论是否来自支持环境，都应按私密报告流程提交。

## 安装与升级

| 来源 | 状态 | 说明 |
| --- | --- | --- |
| 空白目标上的公开 Beta | 条件支持 | 仅在公开 Release 实际存在且附件验证通过时，使用新数据库、工作区和 OpenCode config/data/cache/state 四卷 |
| 当前公开 Beta 原地升级 | 不支持 | 当前 `upgrade_paths` 为空 |
| 旧内部安装包或增量包 | 不支持 | 已退役，不属于公开 Release |
| 缺少有效 Release 元数据的部署 | 不支持 | 未知来源默认拒绝 |
| 手工复用旧数据库或命名卷 | 不支持 | 可能绕过 schema 与部署契约检查 |
| 历史数据自动导出/导入 | 不提供 | 当前 Release 没有公开迁移工具 |

未来只有 [upgrade matrix](../deploy/upgrade-matrix.json) 同时精确匹配来源和目标的
version、完整 revision 与部署契约版本，并且对应 Release Notes 提供迁移与回滚
说明时，才视为受支持升级路径。完整规则见[安装与升级策略](./upgrade-policy.md)。

## 浏览器端访问

平台 UI 以当前仍接收安全更新的主流桌面浏览器为目标。发行测试覆盖的具体浏览器及版本应记录在对应 release 中。

以下场景目前不作为兼容门槛：

- 移动浏览器；
- 嵌入式 WebView；
- 禁用 Cookie 或 JavaScript；
- 旧版企业兼容模式；
- 修改 CSP、代理头或静态资源顺序的自定义代理。

## 提交可支持的问题

Issue 应包含：

- release、提交 SHA 或镜像摘要；
- Linux、Docker、MySQL、Python、Node.js、Playwright 和浏览器版本；
- 是否使用默认发行物；
- 最小复现步骤；
- 已脱敏的最短日志；
- 预期行为和实际行为。

不要附加配置原件、数据库转储、完整报告、trace、视频、Cookie、Token、密码、个人路径或内部地址。

## 相关文档

- [社区支持政策](../SUPPORT.md)
- [部署指南](./deployment.md)
- [安全模型](./security-model.md)
- [配置指南](./configuration.md)
- [安装与升级策略](./upgrade-policy.md)
- [架构概览](./architecture.md)