Viat 是什么

Viat 是什么

Viat 是可自行部署、以端点为中心的 API 平台。你创建项目，编写脚本或工作流，将它绑定到 HTTP 路径，再发布。平台负责接收请求、识别调用者、绑定输入、执行目标并记录结果。脚本本身不会自动成为 API：发布端点才是把接口契约提供给调用者的步骤。

本手册的稳定基线是 server 与 CLI 1.1.0。原生客户端使用独立的 0.1 版本线。源码检出、客户端构建和已发布服务端镜像是不同的产物；尚未发布的加密 APNs Widget 快照不属于本稳定基线。

开始前

先确定自己要完成的任务：

任务	前提与权限	从这里开始
安装实例	Docker 主机、持久化存储、密钥、有效激活码，以及主机运维权限	Docker Compose 安装
加入已有实例	实例 URL、平台账号；操作项目还需项目成员资格	平台用户
构建 API	项目 developer 可编辑；项目 owner 或 admin 可发布	第一个端点
连接 Mac 或 iOS 应用	适用的已签名客户端产物，且设备能访问实例	客户端

不要把产品仓库的开发 Compose 栈当成客户安装器。它提供测试依赖；真正的部署栈还要运行服务端，提供 DATABASE_URL、VIAT_MASTER_KEY，并设置生产用 VIAT_JWT_SECRET。

工作模型

1. 实例： 一套部署，具有 PostgreSQL 平台数据库、认证配置、激活状态，以及一个或多个服务进程。
2. 项目： 协作和 API 的命名空间。项目 slug 会出现在 /p/hello-lab/hello 这样的对外路径中。
3. 资产： 脚本、工作流、资源、认证器和端点树都属于项目。
4. 端点草稿： 可编辑的路径、HTTP 方法、执行目标、输入以及认证和授权设置；编辑不会立即改变已发布 API。
5. 已发布快照： 请求分发实际使用的版本，而不是最新的可编辑端点行。
6. 执行： 一次请求或触发运行及其日志，与编辑和发布是不同的操作。

设计共享认证或回滚流程前，先阅读核心概念。

一次请求如何流转

以 POST /p/hello-lab/hello 为例：

1. Viat 选择项目中已发布的路由并检查 HTTP 方法。
2. 路由允许的认证器识别调用者；授权门禁决定其能否继续。
3. 按照端点契约，将路径、查询参数和请求体绑定为目标输入。
4. 脚本、工作流、代理、CRUD 或 WebSocket 目标走各自的执行路径。
5. Viat 返回结果并记录执行信息。被拒绝的 HTTP 请求也有执行记录；出现记录不代表脚本一定运行了。

因此，一个返回 JSON 的 Python 函数无需另写 HTTP 服务即可成为接口。但这不免除你设计输入结构、授权规则、上游错误处理和业务写入幂等性的责任。

凭据与数据放在哪里

平台数据库是 PostgreSQL。sqlite 资源是应用数据连接，不是可替换的平台数据库，也不代表独立的桌面本地模式。

资源连接凭据由平台保存，并在平台执行资源操作时应用。不要让脚本依赖获取原始数据库密码、私钥或上游认证请求头。秘密值资源和配置有各自明确的语义；不要将凭据写入非秘密的 plain 配置或日志。主密钥应与数据库分开备份：丢失密钥可能使加密的资源凭据无法使用。

1.1.0 的部分旧式脚本资源投影仍可能携带连接凭据，具体限制见概念说明及各类资源参考；管理 API 脱敏并不能证明所有脚本视图都不含凭据。

脚本是可执行代码。工作进程账号隔离、超时和容器限制是有用的防护措施，但不等于面向恶意租户的隔离承诺。给编写者和上游服务账号分配完成任务所需的最小权限。

安全的首次检查

对你获准使用的实例，读取进程存活探针：

curl --fail --silent --show-error http://127.0.0.1:8080/healthz

预期响应体：

{"status":"ok"}

这只能证明 HTTP 正在服务，不能证明实例已激活、数据库已就绪或项目已存在。登录后可用 viat version 查看 CLI 与服务端版本；完整登录步骤见第一个端点。

限制与常见误区

• 403 license_required： 进程可以健康，但受保护的产品路由仍被锁定。按激活处理，不要反复重启。
• 项目列表为空： 平台账号不等于项目成员。请项目 Owner/Admin 将账号加入项目。
• 草稿测试成功，HTTP 仍返回旧结果： 编辑后需要发布。普通 uses: 依赖在发布时冻结，显式 (live) 依赖和草稿测试的行为不同。
• 上游连接失败： 检查资源和服务端的网络路径。笔记本能访问内网服务，不代表容器也能访问。
• 客户端 Widget 时间戳较旧： 缓存状态不等于实时监控连接，刷新时机由操作系统控制。

能力地图可帮助选择操作入口。首次实验请使用第一个端点中的独立项目，完成后取消发布并移除端点和脚本；不要覆盖其他项目的路由。

核验依据

稳定 server/CLI 产物：1.1.0（fd340879）；契约源码：03751a67。主要实现依据：crates/viat-api/src/handlers/dispatch.rs、crates/viat-api/src/registry.rs、crates/viat-core/src/types/snapshot.rs、crates/viat-api/src/handlers/health.rs。