太一文档
把太一部署在访客与源站之间，保护网站和 API。本指南从安装、登录和第一个站点开始，再带你完成业务上线、防护调优、自动化与日常运维。
从这里开始
第一次使用，从快速开始开始就好。安装、登录、创建第一个站点，再看 WAF 拦截真实攻击。完成后，可以继续实战与进阶中的练习，或在日常运维中接入自己的应用。
安装签名二进制，启动 systemd 服务，创建第一个站点，看 WAF 拦截真实攻击。五分钟。
一行安装、手动分步、自定义端口与离线安装，以及配置文件和服务管理。
升级前确认备份、全新状态与远程 Agent 重新入网要求。
站点、上游池、证书、WAF 策略、节点、遥测、审计链 —— 它们各是什么，又是如何配合的。
接入真实应用，查看流量与日志、调查拦截、调整策略，配置告警并管理节点。
继续使用演示站点，练习观察与阻断、规则调优、API 防护、自动化和恢复。
保留 Nginx 入口，在独立端口演练太一接入、查看真实拦截、调整误报并恢复原链路，附实测命令与后台截图。
配置安全阈值告警、全局 IP 自动封禁和固定有效期，核对实际处置，并掌握停止追加与解除封禁的方法。
从外到内诊断启动、登录、路由、TLS、WAF、Agent 与观测管道问题。
按资源整理当前命令与安全示例，并提醒使用每条命令的内置 help。
驱动 UI、CLI、节点流的 ConnectRPC 契约：鉴权、错误码与当前服务目录。
生产加固、远程 Agent 连续运行与 Controller 中断边界、SIEM 转发、可观测性与升级路径。
完整的启动配置和资源 YAML，附下载、应用与验证步骤。
可迁移站点包、冲突处理、证书选择与回滚。
API 发现、文档导入、JSON 学习、请求校验与文件要求。
配置拦截页面、响应状态与 API 错误格式。
查阅 RPC、字段、权限与 CLI 参数。
新增能力、使用边界与升级前的备份和迁移要求。
安装运维技能，通过太一支持的接口完成已授权任务。
设计哲学
三个架构决策塑造了后续所有页面：
- 一个二进制，零运行时依赖。无 Docker daemon、无 Nginx、无 Postgres、无 Redis。二进制内置 Caddy、Coraza、SQLite 与 Vben Admin UI。一个合格的运维应该能在五分钟内拉起一个可用实例。
- API 优先 + 声明式 YAML。ConnectRPC 负责经过认证的变更，UI 与 CLI 都是客户端。
tiyi apply -f site.yaml为受支持的资源字段提供严格、事务化的期望状态入口，并写入同一持久存储与审计链。 - 本地优先，按需远程。内置本地数据平面在进程内应用配置。远程 Agent 与 Controller 保持 ConnectRPC 长连接、校验签名 bundle、断线重连后继续协调，并在 Controller 中断时继续使用最后接受的 bundle 提供服务。
这些文档不是什么。它们覆盖运维表面 —— 安装、运行、加固。API 契约由已安装二进制对外提供；与日常运维无关的实现细节不会放进公开文档。
覆盖的版本
这些文档跟随当前发行版。替换二进制或移动状态前，请阅读升级与迁移。面向用户的行为变化记录在更新日志中。若示例与已安装二进制不一致，以 tiyi <command> --help 为准。
模板与完整参考
启动 tiyi.yaml · 最小建站 YAML · 四类资源 YAML · 站点导入 JSON · OpenAPI YAML · 本机测试 API · 拦截响应 JSON。
已有安装升级到 v3.8.0 必须先备份并重建状态，重新注册所有远端 Agent。 请先阅读v3.8.0 版本说明与迁移步骤，不要直接替换二进制后重启。 历史说明：v3.7.2 · v3.7.1 · v3.7.0。