# Viat 是什么

> 核验版本：1.1.0；通道：stable；文档 ID：overview.platform

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

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

## 开始前

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

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

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

## 工作模型

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

设计共享认证或回滚流程前，先阅读[核心概念](concepts.md)。

## 一次请求如何流转

以 `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 的部分旧式脚本资源投影仍可能携带连接凭据，具体限制见[概念说明](concepts.md)及各类资源参考；管理 API 脱敏并不能证明所有脚本视图都不含凭据。

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

## 安全的首次检查

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

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

预期响应体：

```json
{"status":"ok"}
```

这只能证明 HTTP 正在服务，**不能**证明实例已激活、数据库已就绪或项目已存在。登录后可用 `viat version` 查看 CLI 与服务端版本；完整登录步骤见[第一个端点](../getting-started/first-endpoint.md)。

## 限制与常见误区

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

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

## 核验依据

稳定 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`。