安装
太一以签名 Linux 二进制形式分发。从公开发行渠道安装，写一份小 YAML 配置，然后运行完整 Controller 或入网一个远程 Agent。
用 v3.5.3 替换 v3.4.0 或更早版本时，必须执行破坏性完整卸载。停止旧服务，完成并验证完整备份，运行 sudo tiyi uninstall --purge，再安装全新的 v3.5.3 服务并重新注册全部 Agent。不要把旧数据库恢复进 v3.5；安装前先阅读专用升级指引。
安装签名二进制
太一是单一签名二进制 —— 在单节点上免费且功能完整。权威安装脚本发布在 https://www.tiyisec.com/install.sh：
$ curl -fsSL https://www.tiyisec.com/install.sh | bash
$ tiyi --version
tiyi v3.5.3 linux/amd64脚本会下载与平台匹配的二进制，比对 SHA-256 manifest，并放到 /usr/local/bin/tiyi。默认先尝试 GitHub，失败或过慢时回退到 Gitee Release 镜像；必要时可用 TIYI_MIRROR=gitee 强制使用 Gitee：
$ curl -fsSL https://gitee.com/tiyisec/tiyi/raw/main/install.sh | TIYI_MIRROR=gitee bash安装器环境变量：TIYI_MIRROR=auto|github|gitee、TIYI_REPO=zzmzm/tiyi、TIYI_GITEE_REPO=tiyisec/tiyi、TIYI_VERSION=v3.5.3 与 TIYI_PREFIX=/usr/local/bin。
公开分发仓库：GitHub zzmzm/tiyi 与 Gitee tiyisec/tiyi。
linux/amd64 与 linux/arm64 是一等目标。请在 Controller、远程 Agent 与独立 dashboard 主机上安装同一个签名版本。
配置文件
太一读取一份 Koanf 风格的 YAML 配置。从下面这份最小配置起步，其余靠默认：
# /etc/tiyi/tiyi.yaml
server:
addr: "0.0.0.0:8080"
store:
state_db: "/var/lib/tiyi/state.db"
crypto:
kek_file: "/etc/tiyi/kek.bin" # 32 字节静态加密密钥
auth:
jwt_secret: "<32+ 字节随机>" # HS256 签名密钥
proxy:
http_addr: ":80"
https_addr: ":443"
caddy_admin_socket: "/var/lib/tiyi/caddy-admin.sock"用 --config 传入。这份配置使用 /var/lib/tiyi 与 80/443 端口，因此请以 root 运行（或用下面的 systemd unit）：
$ sudo tiyi run --config /etc/tiyi/tiyi.yaml || sudo /usr/local/bin/tiyi run --config /etc/tiyi/tiyi.yaml若想以普通用户、不用 sudo 试用，可以不走配置文件，而是在命令行上传入可写路径与高端口 —— 见快速开始。
上线前两个字段必须显式设置。crypto.kek_file 与 auth.jwt_secret 都有不能跨重启幸存的开发友好回退。详见部署 → 生产加固。
配置环境变量
持久化服务配置优先写入 /etc/tiyi/tiyi.yaml。只有当 service manager、容器运行时或密钥管理器需要在运行时注入配置时，才使用环境变量。优先级是：内置默认值、tiyi.yaml、配置环境变量、显式 CLI 参数。
环境变量名与配置键一一对应：加 TIYI_ 前缀，转为大写，并把点替换为下划线。例如 auth.jwt_secret 对应 TIYI_AUTH_JWT_SECRET。
常用配置覆盖
| 变量 | 配置键 | 适用场景 |
|---|---|---|
TIYI_SERVER_ADDR | server.addr | 把 API / 控制台绑定到不同地址。 |
TIYI_STORE_STATE_DB | store.state_db | 移动 SQLite 状态数据库。 |
TIYI_LOG_LEVEL | log.level | 临时调整进程日志级别。 |
TIYI_PROXY_HTTP_ADDR | proxy.http_addr | 修改 HTTP 数据面监听地址。 |
TIYI_PROXY_HTTPS_ADDR | proxy.https_addr | 修改 HTTPS 数据面监听地址。 |
TIYI_PROXY_CADDY_ADMIN_SOCKET | proxy.caddy_admin_socket | 移动内嵌 Caddy admin socket。 |
TIYI_CRYPTO_KEK_FILE | crypto.kek_file | 为生产环境固定静态加密 KEK 路径。 |
TIYI_AUTH_JWT_SECRET | auth.jwt_secret | 为生产环境设置稳定 JWT 签名密钥。 |
TIYI_AUTH_BOOTSTRAP_ADMIN_USERNAME | auth.bootstrap_admin_username | 指定首个管理员用户名。 |
TIYI_AUTH_BOOTSTRAP_ADMIN_PASSWORD | auth.bootstrap_admin_password | 为自动化指定首个管理员密码。 |
TIYI_LICENSE_KEY_PATH | license.key_path | 启动时加载签名 license 文件。 |
TIYI_UPDATE_REPO | update.repo | 覆盖更新检查使用的 GitHub release 仓库。 |
TIYI_UPDATE_CHANNEL | update.channel | 为 tiyi update 使用 stable 或 prerelease。 |
TIYI_UPDATE_MIRROR | update.mirror | 更新检查/下载使用 auto、github 或 gitee。 |
较少使用的配置键也遵循同一规则，包括 auth.access_token_ttl、auth.refresh_token_ttl、auth.refresh_cookie_secure、auth.bootstrap_admin_email、auth.bootstrap_admin_name、auth.provider、auth.ldap.*、auth.radius.* 与 update.api_base_url。除非部署平台必须通过环境变量注入，否则这些项优先写 YAML。
运行命令
同一个二进制提供一个完整运行时与两个专用进程：
run- 一个始终可写的 Controller，包含本机数据平面、API 与管理界面。这是默认安装与五分钟路径。
agent- 远程数据平面：Caddy + Coraza，通过一条 ConnectRPC 长连接从唯一的 Controller URL 接收已签名 bundle。
dashboard- 仅 UI 的专用进程，不持有状态也不代理流量。
入网一个节点
打开节点 → 安装远端节点签发 Token，再按页面分别显示的二进制下载和 systemd 步骤操作。页面也会显示原始 Token、前台命令和完整下载启动脚本：
$ 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丢失 state 目录后，需要重新签发 Token 入网。
以 systemd 服务运行
长期运行的部署，让太一把自己装成一个加固过的 systemd 服务。tiyi install 会创建 tiyi 服务用户与 tiyi-admin 套接字组、写入 unit，加上 --now 则同时开机自启并立即启动：
$ sudo tiyi install --now不带 --now 执行 sudo tiyi install 时，安装器会按设计只写入并 reload unit，保持未启用、未启动，方便先完成各运行模式的配置。首次启动 Controller 时，请在原安装命令上补上 --now 后重新执行，不要直接用 systemctl 启动 unit。这样安装器能先创建管理员，并把一次性登录信息打印在当前终端，而不是把密码写入 system journal。
该服务以非 root 身份运行，通过 CAP_NET_BIND_SERVICE 绑定 80/443 端口。每次启动前，unit 会先用 root-only 的 pre-start 钩子把配置里的状态目录和 KEK 文件重新交给服务用户；之前 sudo 前台运行留下的 CRS 缓存、上传、排除包、release 暂存、日志、trust 快照或内嵌 agent 状态目录不会再阻塞运行期写入。首次安装时，--now 会预先创建管理员，并在启动服务后直接打印一次性登录信息（URL、用户名、密码）——无需再去 journal 里捞：
tiyi is enabled and running as tiyi.service.
Tiyi administrator created
URL: http://127.0.0.1:8080
username: admin
password: <生成的密码>
This password is shown once; change it after signing in.用 tiyi install --print 可在不改动系统的前提下预览生成的 unit。其关键指令：
# /etc/systemd/system/tiyi.service
[Service]
Type=simple
User=tiyi
Group=tiyi
PermissionsStartOnly=true
ExecStartPre=/usr/local/bin/tiyi systemd-prestart --config /etc/tiyi/tiyi.yaml --user tiyi --group tiyi
ExecStart=/usr/local/bin/tiyi run --config /etc/tiyi/tiyi.yaml --admin-socket /run/tiyi/admin.sock --admin-socket-group tiyi-admin --admin-socket-mode 0660 --caddy-admin-socket /run/tiyi/caddy.sock
Restart=on-failure
AmbientCapabilities=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
StateDirectory=tiyi
RuntimeDirectory=tiyi
ConfigurationDirectory=tiyi
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
PrivateTmp=yes
[Install]
WantedBy=multi-user.target用 tiyi doctor 检查 sudo PATH、systemd、配置加载、已安装服务的状态目录所有权，以及 80/443/8080 端口监听者。如果还没有安装 systemd unit,状态目录所有权检查会跳过,除非传入 --service-user/--service-group 或显式请求修复。如果它提示 sudo 找不到 tiyi，使用输出里的完整路径命令，或把 /usr/local/bin 加入 sudo secure_path。如果它提示状态目录里有 root 拥有的路径，显式运行 sudo tiyi doctor --fix-state-ownership 修复。如果它提示端口冲突，可以停止占用端口的服务，或通过 proxy.http_addr、proxy.https_addr、server.addr 修改太一端口。用 --mode run 检查 Controller，或用 --mode agent 检查远程 Agent。用 sudo tiyi uninstall 移除该服务：除非加上 --purge，否则 /var/lib/tiyi 下的状态、/etc/tiyi 下的配置以及服务用户都会保留。