Upgrade and migrate Tiyi

Update a compatible signed binary in place, reset state when a release is incompatible, or move a complete Controller installation to another host.

Choose the workflow

The updater validates release metadata, checksums, and signatures. It has no hard-coded minimum release and does not determine stored-data compatibility; read the target release notes first.

Routine signed update

sudo tiyi update --check
sudo tiyi update --yes                 # GitHub, with Gitee fallback
sudo tiyi update --yes --mirror gitee # force Gitee
sudo systemctl restart tiyi
tiyi --version
sudo tiyi system health
sudo journalctl -u tiyi -b -n 200 --no-pager

update atomically replaces the verified executable but does not restart the running process.

Incompatible-state update

v3.6.0 cannot open state created by earlier releases. For that transition, preserve an offline rollback archive, purge the old state/config, update the retained binary, then install a new service. The old archive is not imported.

sudo systemctl stop tiyi
stamp=$(date -u +%Y%m%dT%H%M%SZ)
sudo install -d -m 0700 /var/backups/tiyi
sudo tar --xattrs --acls -C / \
  -czf "/var/backups/tiyi/tiyi-before-update-${stamp}.tar.gz" \
  var/lib/tiyi etc/tiyi etc/systemd/system/tiyi.service usr/local/bin/tiyi
sudo sha256sum "/var/backups/tiyi/tiyi-before-update-${stamp}.tar.gz"

sudo /usr/local/bin/tiyi uninstall --purge
sudo /usr/local/bin/tiyi update --yes --mirror gitee
sudo /usr/local/bin/tiyi doctor --mode run
sudo /usr/local/bin/tiyi install --now
sudo systemctl status tiyi --no-pager
sudo journalctl -u tiyi -b -n 200 --no-pager

uninstall --purge removes the unit, state/config, and service identities but deliberately keeps /usr/local/bin/tiyi; update overwrites that file. If the retained binary has no update command, verify the archive, remove only that binary, and use the public installer. Save the new administrator password and re-enroll Agents when required.

Move a Controller to another host

Stop the source and copy the complete /var/lib/tiyi directory, not only state.db. It may include WAL files, KEK, log/detail partitions, request evidence, CRS data, releases, bundles, and identity. Also copy /etc/tiyi and every externally referenced KEK, license, certificate, or secret file.

# Source
tiyi --version
systemctl cat tiyi
sudo systemctl stop tiyi
stamp=$(date -u +%Y%m%dT%H%M%SZ)
sudo install -d -m 0700 /var/backups/tiyi
sudo tar --xattrs --acls -C / \
  -czf "/var/backups/tiyi/tiyi-migrate-${stamp}.tar.gz" \
  var/lib/tiyi etc/tiyi
sudo sha256sum "/var/backups/tiyi/tiyi-migrate-${stamp}.tar.gz"

# Clean destination: replace vX.Y.Z and the archive name.
source_tag=vX.Y.Z
archive=/secure/path/tiyi-migrate-YYYYMMDDTHHMMSSZ.tar.gz
curl -fsSL https://www.tiyisec.com/install.sh \
  | TIYI_VERSION="$source_tag" bash
sudo /usr/local/bin/tiyi install
sudo sha256sum "$archive"
sudo tar --xattrs --acls -C / -xzf "$archive"
sudo chown -R tiyi:tiyi /var/lib/tiyi
sudo chgrp -R tiyi /etc/tiyi
sudo chmod -R g+rX /etc/tiyi
sudo /usr/local/bin/tiyi doctor --mode run --fix-state-ownership
sudo /usr/local/bin/tiyi install --now

Verify the checksum before extraction; recreate reviewed unit options, drop-ins, injected environment, and external files before doctor. Check health, sites, certificates, remote Agents, bundle revision, tiyi audit verify, logs, and /metrics. For rollback, stop the destination before restarting the unchanged source; never merge two state trees that both accepted writes.

Diagnose failures

sudo /usr/local/bin/tiyi doctor --mode run
systemctl status tiyi --no-pager
journalctl -u tiyi -b -n 200 --no-pager
journalctl -u tiyi -f
ss -ltnp

• Installer refusal means the new-host installer found an existing binary, state, config, or unit; use the appropriate upgrade or migration workflow.
• An incompatible-schema error means the target binary cannot open that state; use the matching binary or restore/reset the intended state.
• Use the full binary path when sudo secure_path cannot find tiyi.
• An update error leaves the current binary untouched; fix mirror/network, disk, or permissions and retry.

See Prometheus integration and general troubleshooting.