核心概念

领域模型

太一的领域被刻意保持得很小。七个一等资源覆盖了所有运维动作、所有 CLI 命令、所有 UI 页面。理解了这些，产品的其他部分就显而易见了。

七个资源

站点（Site）: 太一代理的一个 HTTP 主机。携带 TLS 设置、上游池引用与挂载的 WAF 策略。是你启用或停用的最小单元。
上游池（Upstream pool）: 站点背后的一组后端。轮询或加权负载均衡、SNI 感知健康检查，可在多个站点之间共用。
证书（Certificate）: 一对 TLS 密钥。要么上传（自签、CA 购买、企业签发），要么ACME 签发（HTTP-01 或 DNS-01）。在静态用 KEK 信封加密。
WAF 策略（Policy）: Coraza 在每个请求上执行的编译产物。CRS Core 层 + HTTP 策略 + 限制 + 规则调优 + IP 列表 + 自定义规则 + 插件 + 限速 + 排除项。
节点（Node）: 运行 Caddy + Coraza 的数据平面。每个部署固定包含一个本机内置节点；授权允许时可添加从 Controller 接收签名 bundle 的远程 Agent。
遥测汇总（Telemetry rollup）: 开桶管道产生的计数器与 Top-K 采样。驱动 dashboard、Top-K 浏览器与 Prometheus 导出器。
审计行（Audit row）: 每一次变更对应一行哈希链记录，归属到 JWT subject。这是合规面 —— 每一次变更都有一份防篡改回执。

站点与上游池

站点把主机名绑到 TLS 设置、上游池与 WAF 策略上。写入器在 apply 时把每一个启用的站点翻译成一个 Caddy server 块 —— Caddy JSON 是编译目标，不是存储格式。

上游池默认与站点解耦。一个池可以背后挂多个站点；删除被引用的池会被拒绝并附带 UPSTREAM_IN_USE 与引用列表。站点也可以使用内联 upstream URL 作为不需要复用的特例。

访问日志录入模式

每个站点有一个 recording_mode 字段控制访问日志体量：

on（自 2026-05-26 起的默认值）—— 录入每一个请求。
sampled —— 录入可配置的百分比。如果没有设比例，写入器会折叠到 off。
off —— 不写入访问事件。

无论访问日志模式如何，安全事件（Coraza 规则命中）都会被写入。

证书

TLS 材料是一等资源 —— 永远不内联到站点上。太一支持四种签发路径，全部用从 crypto.kek_file 加载的 32 字节 KEK 在静态时信封加密：

上传 —— 粘贴或上传 PEM 密钥对。开发用自签，生产用 CA 购买或企业签发。
ACME HTTP-01 —— 多节点：每个节点都跑一个 loopback 响应器，并通过节点流广播 (token, key_authorization) 对，让任何节点都能应答挑战。
ACME DNS-01 —— 可插拔驱动注册表。Cloudflare 驱动已生产可用；Route53 与阿里云在 v3.0.4 中提供凭据校验桩。
通配符 —— 在混合 order 中对 *.example.com 自动选择 DNS-01。

Dashboard 把 certs_expiring_14d / certs_expiring_30d / acme_renewals_failed_24h / acme_orders_pending 暴露为 KPI。首次启动种入两个默认告警：证书即将到期 与 ACME 续期失败。

WAF 策略

策略是一个结构化的领域对象。apply 时太一为 CRS 与自定义规则编译 Coraza SecLang，并为 CIDR/geo:CC 匹配单独编译压缩原生 IP 列表产物。两套编译都是确定的。12 个可调层（按应用顺序）：

CRS Core —— 偏执等级、阻断与执行 PL、入站/出站阈值、采样。
HTTP 策略 —— 方法、版本、Content-Type、字符集、受限扩展名/Header、方法覆盖。
限制 —— 6 个数值字段：最大请求体、最大响应体等，CRS 默认值作为 placeholder。
规则调优 —— 按规则的覆盖：DEFAULT、DISABLE、LOG_ONLY、SCORE_OVERRIDE，可选限定到单个站点。
IP 列表 —— 允许 / 拒绝 / 监控列表。条目可以是 CIDR 或 geo:CC 伪条目（alpha-2/alpha-3 国家代码加 PRIVATE / LOOPBACK）。国家与 CIDR 展开编译进 Coraza 之前的原生 tiyi_iplist 处理器，绝不会膨胀进 SecLang；重叠名单中允许优先于拒绝。
自定义规则 —— 运维写的 SecLang 或可视化规则，ID 在 8000000–8999999 区间。
插件 —— CRS 排除包（WordPress、Drupal、Nextcloud、phpBB、phpMyAdmin、XenForo、cPanel、DokuWiki）。支持离线归档导入。
限速 —— 按端点与按客户端范围的桶，动作可选阻断或仅记录。
排除项 —— 阶段-1 的 tx.crs_exclusions_<slug> 选项，可选用 @beginsWith 限定。
预览 —— 当前版本的只读 SecLang dump。
版本 —— 每次保存一个快照，任意两个版本之间并排 diff。
测试台 —— 用 fixture 请求打编译后的 bundle，不会触碰生产数据平面。

按站点覆盖会把标量字段（偏执、阈值、采样）以及站点级规则覆盖、自定义规则、IP 列表绑定、限速端点叠加到挂载的策略上而不必 fork 它。

本机节点与远程 Agent

Controller 固定拥有一个进程内本机数据平面。它使用同一套签名与验证流程应用配置，但不会作为 Agent 入网、持久化、心跳或接收命令。节点页把它固定显示在第一行：本机 · 本地 · 内置。

远程 Agent 只连接配置的 Controller URL。它校验 ed25519 签名、拒绝重放和乱序、把已接受 bundle 应用到本地 Caddy 并上报结果。Controller 不可用时，Agent 按退避重连，同时继续使用最后一次已接受的配置代理流量。

一个拓扑，不切角色。添加或移除远程 Agent 只改变节点数量，Controller 不会切换模式或角色；远程数据平面的连续代理能力也不等于 Controller 高可用。

遥测

遥测作为一条并行管道运行，结束了每事件 SQL 写入。路径：

分片入流环 —— 日志转发器事件按站点 key 散到分片环。
10 秒开桶聚合 —— 分片 worker 把计数器累加到 10 秒桶。
Misra-Gries Top-K —— 高基数维度（客户端 IP、路径、UA、ASN、攻击标签）的有界摘要，带 __other__ 桶让 SUM(*) 等于真实流量。
每日 SQLite 分区位于 logs/rollup_10s/YYYY-MM-DD.db；降采样器把它们幂等地折叠成 rollup_hour → rollup_day → rollup_month。
采样环 —— 按 IP 的 LRU + 全局环，带启动时回放的循环文件 WAL。
API 树 —— 按站点的 URL 前缀树，节点数与深度均有上限；空闲叶子撤入 api_tree_archive。
读路径 —— REST API 位于 /api/v1/telemetry/*，本地管理 socket 上的 Prometheus 导出器位于 /metrics。

审计链

每一次变更（站点、上游、证书、策略、IP 列表绑定、限速端点、信任配置、自定义规则、告警规则等）都会向 audit_event 追加一行。每一行存：

动作 —— 固定的字符串，例如 policy.update_layer、trust.update_profile、rule_override.create。
资源类型与 ID —— 变更的范围。
操作者 —— JWT subject，归属到真实用户 UUID（而不是泛化的 "local-admin"）。
变更前/后 JSON —— 该行规范视图的扁平 diff。
哈希链 —— 每一行哈希前一行加自身的规范 payload。每日锚点提交链头。

Vben Admin 上的校验链按钮会走完整条链并确认每一段。SIEM 转发可在 siem.filter.include_audit 下把每一行审计转发到 Splunk / Elastic / Sentinel 管道。

这就是整个模型。每一个 CLI 命令、每一个 UI 页面、每一个 RPC 都作用于这七个资源中的一个。文档其余部分按名引用，不再重复定义。