部署

把太一 Controller 投入生产，需要决定密钥放在哪、需要哪些远程数据平面、日志去哪，以及如何备份恢复和升级。

生产加固

有两个配置字段带不能跨重启幸存的开发友好回退。上线前显式设定它们。

KEK —— 静态加密密钥

crypto:
  kek_file: "/etc/tiyi/kek.bin"     # 32 字节静态密钥

所有信封加密的 blob（TLS 私钥、ACME 账户密钥、ACME DNS provider 凭据、bundle 签名密钥）用这个 KEK 解密。生成一次并备份到 state 数据库旁边：

$ install -m 0600 /dev/null /etc/tiyi/kek.bin
$ head -c 32 /dev/urandom > /etc/tiyi/kek.bin

JWT 签名密钥

auth:
  jwt_secret: "<32+ 字节随机>"     # 或通过 TIYI_AUTH_JWT_SECRET 环境变量

Access token 的 HS256 签名密钥。字段为空时，太一在每次重启时生成 32 字节临时密钥并打印 WARNING；已有会话会在重启时失效。

Bundle 签名密钥

服务端的 ed25519 配置签名密钥落在 bundle_signing_key 单例行,使用 KEK 信封加密。节点首次接入时固定公钥(TOFU),之后拒绝重新固定。轮换需要重新入网 —— 用 tiyi agents issue-token 签新 token,把节点重新拉起。

一个 Controller，可选远程 Agent

只运行一个 tiyi run Controller。它始终拥有可写 SQLite 状态、API、管理界面与一个本机内置数据平面。需要流量扩展或不同位置时添加远程 Agent；节点数量变化不会改变 Controller 的运行模式。

安装远程 Agent

打开节点 → 安装远端节点，选择 URL、标签和 Token 有效期，再签发 Token。页面会分别显示二进制下载、原始 Token、推荐 systemd 步骤、前台命令和完整脚本：

$ sudo curl -fsSL -o /usr/local/bin/tiyi 'https://tiyi.example.com/download/tiyi'
$ sudo chmod 0755 /usr/local/bin/tiyi
$ sudo mkdir -p /etc/tiyi
$ printf 'TIYI_CONTROLLER_URL=https://tiyi.example.com\nTIYI_AGENT_ENROLLMENT_TOKEN=<一次性Token>\n' | sudo tee /etc/tiyi/tiyi-agent.env >/dev/null
$ sudo chmod 0600 /etc/tiyi/tiyi-agent.env
$ sudo tiyi install --mode agent --unit-name tiyi-agent --now

节点页随后固定先显示本机，再显示已入网的远程 Agent。

Controller 中断边界

Controller 停止后，远程 Agent 继续使用最后一次已接受的签名 bundle 代理和执行 WAF。配置变更、入网、中央管理界面和汇总视图会不可用，直到同一个逻辑 Controller 地址恢复。Agent 按退避重连并恢复收敛，不存在备用 Controller URL 或自动角色切换。

客户端 IP 信任配置

太一在 CDN 或 L4 LB 后时,到达 WAF 的客户端 IP 不是真实 IP —— 那是前面的代理。信任配置告诉太一哪些代理可信、哪个 header 携带真实 IP。

从 UI(设置 → 信任配置标签)或 CLI 设置一次:

$ tiyi trust set \
    --proxy 10.0.0.0/8 \
    --proxy 172.16.0.0/12 \
    --cdn cloudflare \
    --header CF-Connecting-IP \
    --header X-Forwarded-For

# 自动拉取 CDN 段:
$ tiyi trust show
$ tiyi trust refresh cloudflare
$ tiyi trust refresh fastly

# 把任意 (peer, headers) 元组回溯到解析后的客户端 IP:
$ tiyi trust test --peer 10.0.0.5 --header "X-Forwarded-For: 1.2.3.4, 10.0.0.5"

默认开启的 Origin Bypass Attempt 告警在请求通过 XFF 声称客户端 IP 但 peer 不是受信任代理时触发。

SIEM 转发

太一把安全、访问、错误、(可选)审计事件以 RFC 5424、CEF 或 LEEF 通过尽力的 TCP / UDP / unixgram 转发出去。从 设置 → SIEM 标签 或 CLI 配置一次:

$ tiyi system settings update \
  --set siem.enabled=true \
  --set siem.endpoint=tcp://siem.internal:514 \
  --set siem.transport=tcp \
  --set siem.format=RFC5424 \
  --set siem.filter.include_audit=true

SIEM 转发是有意尽力的。接收端健康、可靠投递、回放属于 SIEM 管道,而不是太一。转发器为每个 dispatcher 缓存一条 net.Conn,出错时重连。

可观测性

• Prometheus 导出器位于本地管理 socket 的 /metrics。从 sidecar 抓取;指标来自驱动 dashboard 的同一条遥测管道。
• /healthz 报告 Controller 身份、数据库、代理、配置、站点与远程 Agent 事实。可用于服务健康检查。
• /debug/logsink/stats 在本地管理 socket 暴露每种类别的 attempted/written/dropped_full/panicked/queue_depth/last_error 计数。panicked 计数是边界 defer recover 处理器的跨层金丝雀。
• 遥测深度视图 UI 位于 /telemetry/explorer,可在不离开 dashboard 的情况下做按需 Top-K 与采样浏览。

远程 Agent 滚动升级

对于兼容且已注册的 Agent，导入二进制 release 后，tiyi release apply 会把 APPLY_BINARY 命令发给 OS/arch 匹配的 Agent。每个 Agent 下载替换、校验 SHA-256 与 Ed25519 发布签名，然后退出，由 supervisor 用新二进制重启。

$ tiyi release import --tarball ./tiyi_3.5.2_linux_amd64.tar.gz
$ tiyi release list
$ tiyi release apply <release-id>             # 所有匹配节点
$ tiyi release apply <release-id> --agent-id A  # 灰度部署
$ tiyi release runs                          # 进行中的滚动
$ tiyi release rollback                      # 回滚到上一个二进制

备份

有三样东西要备份:

• state.db —— SQLite 控制平面数据库。WAL 模式;sqlite3 state.db ".backup '/path/to/backup.db'" 在太一运行时也工作。
• kek.bin —— 静态加密密钥。丢失即不可恢复。备份到与其他长期密钥相同的保险库。
• jwt_secret —— 已经在你的配置仓库里,但要确认那个仓库也备份了。

使用 SQLite 在线备份机制，或停止 Controller 后做一致的文件系统副本。通过网络文件系统复制正在运行的 WAL 数据库目录不是受支持的故障转移方案。logs/ 分区文件是有独立保留周期的运营数据。

上线检查表