核心概念与边界

本页帮助你判断该改哪个对象，以及由哪一层权限控制。理解模型不需要账号；查看实际项目需要平台会话和项目成员资格，编辑内容需要项目 developer 或以上，发布需要项目 admin 或 owner。

实例、项目与端点树

实例是一套服务端部署，拥有平台账号、激活状态、服务配置和 PostgreSQL 平台数据库。多个服务进程可以共享该数据库；创建项目不等于再部署一台服务器。

项目拥有自己的 API 资产和协作者成员关系。slug 在实例内唯一。对外前缀为 /p/<slug>，管理路由使用 /projects/<slug>。项目 slug 不是访问凭据。

端点树组织项目路由。新项目有一个挂载于根路径的 default 树。目录节点组织后代，可调用叶节点具有 HTTP 方法和目标。路径片段不一定是脚本名；同一脚本可以绑定多个端点，分别使用不同方法和访问规则。

例如：

对象	示例	含义
实例基础 URL	`https://api.example.com`	要连接的部署；请替换成自己的 URL
项目 slug	`hello-lab`	项目命名空间
脚本资产	`hello`	可复用的执行定义
端点	`POST /hello`	项目内已发布的 HTTP 契约
调用 URL	`https://api.example.com/p/hello-lab/hello`	完整对外请求地址

反向代理挂载前缀也应包含在实例基础 URL 中。CLI 登录的 server URL 不要包含 /ui 或 /p/<slug>。

三个身份平面，不是一张角色表

平面	代表谁	如何决定访问
平台用户	登录控制台、CLI 或原生应用的人	平台角色：`owner`、`admin`、`developer`、`operator`
项目协作者	加入某个项目的平台用户	独立成员角色：`owner`、`admin`、`developer`、`operator`
项目终端用户 / 机器调用者	消费已发布项目 API 的用户或程序	项目认证器、终端用户角色和属性，以及授权模型

平台 operator 可以同时是项目 owner。平台 owner 不会自动成为每个项目的协作者。改变平台角色不会改变项目成员角色；添加终端用户也不会赋予控制台访问权限。

viat user 管平台人员，viat project member 管协作者，viat p-user、viat role、viat authorizer 管项目调用者身份。完整流程见平台用户与创建项目并协作。

脚本、工作流与资源

脚本是有名称、语言和版本的可执行资产。工作流编排执行目标与控制流，并不是端点目录。草稿测试执行当前定义，可能产生真实副作用，不会自动变成离线模拟。

资源保存可复用连接或平台管理的能力，如数据库、HTTP API、存储、邮件服务或密码学密钥。资源配置区分非秘密的 plain 数据和秘密字段。普通管理读取会脱敏秘密值，平台代理的资源操作会在平台侧应用凭据。

但这不是 1.1.0 所有脚本资源视图均不含凭据的保证：部分旧式数据库、缓存、消息和 S3 投影仍包含带凭据的字段。优先使用代理 helper，切勿返回或打印资源对象，并查看各类型的资源参考。有意提供秘密值的 secret / config 资源，与提供商认证凭据属于不同契约。

不要把保存业务表的 PostgreSQL 资源与 PostgreSQL 平台数据库混为一谈。sqlite 资源访问经过允许的服务端文件，也不能替代平台数据库。

草稿、发布与回滚

编辑端点目标、认证或输入契约，改变的是草稿。对外分发读取当前已发布快照。发布捕获路由契约和目标定义；测试运行不等于发布。执行 viat publish apply 前，先看 viat publish plan。

依赖处理需要特别注意：

已发布的脚本端点，在整个依赖图没有 (live) 引用时，会捕获普通 Python/TypeScript uses: 导入。
1.1.0 的工作流步骤脚本是例外：主脚本源码在发布时固定，但其 uses: 依赖（含嵌套工作流步骤）仍在每次运行工作流前实时解析。
# uses: shared/util (live) 这样的指令每次运行读取实时源码，并使用新工作进程，而不是预热工作池路径。
草稿测试和直接调度的目标实时解析依赖，因为它们不执行端点的冻结快照。
没有冻结依赖数据的旧快照也会退回实时解析。升级旧端点后，如需明确冻结依赖图，应重新发布。

所以不能笼统承诺“所有导入都是实时的”，也不能说“所有依赖都会随回滚恢复”。实际结果取决于端点快照和依赖模式。资源凭据和上游配置仍是实时状态；轮换凭据不是部署端点代码。

发布在所有部署设置下都不保证运行环境已准备成功。默认同步构建，但 VIAT_PUBLISH_BUILD_BLOCK=0 允许依赖构建失败后仍发布；VIAT_PUBLISH_BUILD_ASYNC=1 允许后台构建。判断发布健康前，应检查构建结果。

认证不等于授权

认证器回答“调用者是谁”。端点向上继承时，最近一层明确声明的认证器列表会替换祖先列表，并不是把父节点允许的凭据类型全部合并。

授权门禁（authz_gates，元素为 {type, action}）回答“已识别的调用者能否调用路由”。门禁沿树累积，直到 override_permissions 停止继承。它们在业务对象尚不存在时，对 subject 做判断；对象和行权限还属于授权模型及具体业务操作。

内置 anonymous 认证器允许明确公开的路由，但不能代替敏感业务数据的权限检查。控制台登录令牌不能与项目终端用户令牌或 API key 互换。

执行与证据

执行记录包含 request_id、状态、耗时等元数据，行日志是目标捕获的输出。端点拒绝也可能生成执行记录而不启动工作进程。日志受配置的存储后端和保留策略影响，不能当永久备份。

完成第一个端点中的登录和项目选择后，可以只读检查：

viat project list
viat endpoint list --json
viat publish plan --json
viat logs query --limit 10 --json

预期分别获得可访问项目、可编辑端点记录、待发布变更，以及包含 items 和 next_before 的执行分页。新项目返回空列表是正常情况。这些命令不会发布或运行脚本。

定位边界误用

现象	检查方向
平台 Admin 看不到项目	将账号加入项目；平台角色不绕过成员检查
Developer 可编辑但不能发布	请项目 Owner/Admin 操作，不只是平台 Admin
有效终端用户令牌收到 `403`	检查已发布认证器列表和所有继承门禁
草稿响应变了，调用响应没变	发布，并核对实例、项目和活动快照
回滚没有恢复上游凭据	凭据是实时资源状态，不是快照内容
配了 `sqlite`，服务仍要求 PostgreSQL	资源数据库和平台持久化是两层概念

清理实验时，先取消发布路由，再删除端点及执行目标。移除项目成员不会删除其项目内容；清空 CLI 会话也不会删除项目。具体清理步骤见第一个端点。

核验依据

契约源码 03751a67：crates/viat-core/src/types/{project,script,resource,snapshot}.rs、crates/viat-db/src/projects.rs、crates/viat-db/src/endpoints.rs、crates/viat-api/src/handlers/snapshots.rs、crates/viat-cli/src/main.rs。