API 概览
Tiyi 暴露唯一一份 ConnectRPC API。同一份 proto 同时为 Vben Admin UI（HTTP 上的 JSON）、tiyi CLI（HTTP 上的 JSON）与节点流（gRPC 双向）服务。proto/tiyi/v1/*.proto 是唯一的真相源 —— CLI 与 API 由架构保证同步。
传输
- JSON 用于 UI 与 CLI 客户端。默认
Content-Type: application/json；URL 遵循 ConnectRPC 约定/{service}/{Method}。 - gRPC 用于节点双向流以及任何偏好二进制协议的客户端。
- Connect-Web 用于嵌入式 Vben UI —— 无需独立 REST 适配器，无需独立网关。
鉴权
三种鉴权面，按部署上下文选用：
| 鉴权面 | 机制 | 使用方 |
|---|---|---|
| 本地管理 socket | admin.sock 上的 OS 文件权限 |
与服务端同主机的 tiyi CLI。 |
| HS256 JWT | HTTP 上的 Authorization: Bearer <jwt> |
Vben Admin UI、远程 CLI、任何从主机外驱动 API 的客户端。由 AuthService.Login 签发；RefreshToken 刷新。 |
| 节点流 token | 一次性入网 token → 长期流 token | 双向 AgentStream 上的节点。token 通过 AgentService.IssueEnrollmentToken 签发。 |
登录示例
$ curl -sS http://primary:8080/tiyi.v1.AuthService/Login \
-H "Content-Type: application/json" \
-d '{"username":"admin","password":"..."}'
{
"accessToken": "<jwt>",
"refreshToken": "<refresh>",
"user": { "id": "<uuid>", "role": "Administrator" }
}14 个服务
| 服务 | 范围 |
|---|---|
SystemService | 健康、版本、Dashboard 汇总、设置、发布、复制、提主/降级。 |
AuthService | 登录、登出、刷新、当前用户、OIDC 重定向、access code。 |
UserService | 用户 CRUD、锁定/解锁、密码重置。 |
RoleService | 角色 + 权限查询。RBAC 表内置。 |
SiteService | 站点 CRUD、启用/停用、预览、按站点策略覆盖。 |
UpstreamService | 上游池 CRUD；引用中拒绝删除。 |
CertService | 上传、ACME 签发/续期、DNS provider CRUD。 |
PolicyService | WAF 策略 CRUD、按层更新、版本快照、SecLang 预览、测试台。 |
RuleOverrideService | 按规则覆盖、自定义规则、IP 列表、限速端点。 |
CrsService | CRS 目录浏览 + 导入 + 排除包安装/挂载。 |
AgentService | 节点 CRUD、入网 token、安装脚本、命令、节点组、AgentStream。 |
TrustService | 客户端 IP 信任配置（租户 + 站点覆盖）、CDN 快照列表/刷新、explain。 |
AlertService | 告警规则 + 通道 CRUD、活动告警 ack/resolve、通道发送测试。 |
LogService | 安全/访问/错误/审计查询、获取、导出、实时跟踪。 |
错误码
Tiyi 返回标准 ConnectRPC 错误码（从 gRPC 映射）。CLI 与 UI 在标准码之上展现本地化消息：
| 码 | HTTP | 常见原因 |
|---|---|---|
invalid_argument | 400 | 参数形状或值被验证器拒绝。 |
unauthenticated | 401 | 缺失或无效 JWT。 |
permission_denied | 403 | JWT 没有所需 RBAC 权限。 |
not_found | 404 | 资源 ID 不存在或已软删除。 |
already_exists | 409 | 违反唯一性约束（站点名、策略名等）。 |
failed_precondition | 412 | 版本冲突、UPSTREAM_IN_USE、复制延迟门槛等。 |
unimplemented | 501 | RPC 未挂载（罕见 —— 2026-05-26 的 changelog 关闭了最后一批）。 |
internal | 500 | 服务端 bug 或基础设施失败。相关情况下审计链有一行。 |
RBAC
每一个 RPC 声明一个权限要求，例如 site:read、policy:write、log:read、system:write。中间件把 JWT subject 的角色与权限表比对；权威映射在 internal/api/middleware.go。v3.0.0-rc.1 中有 52 个细粒度权限。
流式 RPC
AgentService.AgentStream—— 长连双向流。节点发送 Hello、StateReport、AgentEventPush、ApplyResult、ChallengeResponse。服务端发送 Welcome、ConfigUpdate、Command、ChallengeDispatch。AlertService.StreamAlerts—— 服务端流。把告警生命周期事件推送到 dashboard，客户端使用退避重连。AgentService.StreamAgentEvents—— 服务端流。实时节点状态（在线/下线、指标）。LogService.TailSecurityEvents—— 服务端流。实时跟踪页的实时安全日志流。SystemService.StreamUpgradeRun—— 服务端流。按节点的升级运行进度事件。
权威规约
源码树中的 PRD-API 文档是每一个 RPC 的权威规约。它列出每个方法的请求/响应形状、RBAC 权限、错误码与审计行契约。本文档覆盖运维表面；那份文档覆盖 API 契约。它们应当一致 —— 不一致请提 issue。
生成式参考从 proto/ 重新生成 Connect Go 与 Protobuf Go：
$ make proto
$ ls internal/api/gen/tiyi/v1/
# 每个 .proto 对应 <service>.pb.go 与 <service>.connect.go