Upgrade

Replace an existing installation with v3.5.0

A host that ran v3.4.0 or any earlier release must be completely uninstalled and initialized as a clean v3.5.0 service. This is not an in-place state migration.

High risk and irreversible. sudo tiyi uninstall --purge deletes all Tiyi history and configuration under /var/lib/tiyi and /etc/tiyi, removes the systemd unit, and removes the service identities. Stop and verify a complete backup before accepting the purge.

Why update followed by restart fails

sudo tiyi update --yes --mirror gitee can correctly install the v3.5.0 binary, but it does not restart the service or make v3.4 state compatible. Restart can then fail with either signature:

store: migration 0016_telemetry_rollups.sql sha256 drift ...
store: clean-break state reset required (schema=..., minimum=47) ...

Do not keep restarting and do not copy the old database into a new v3.5 state directory. Use the clean-install sequence below.

1. Record what must be recreated

tiyi version
sudo systemctl status tiyi --no-pager
sudo systemctl cat tiyi
sudo tiyi site list
sudo tiyi upstream list
sudo tiyi policy list
sudo tiyi cert list
sudo tiyi agents list
sudo tiyi user list

Also record custom listeners, DNS, upstream endpoints, WAF tuning, certificate source files, license path, identity-provider settings, SIEM destinations, and remote-Agent names. Never paste passwords, tokens, private keys, KEKs, license contents, or captured requests into tickets or chat.

2. Stop and back up the complete old installation

The default-path example below makes a consistent copy after stopping SQLite writes:

TIYI_BACKUP_DIR="/var/backups/tiyi-pre-v3.5-$(date +%Y%m%d-%H%M%S)"

sudo systemctl stop tiyi
sudo install -d -m 0700 \
  "$TIYI_BACKUP_DIR/state" "$TIYI_BACKUP_DIR/config"
sudo cp -a /var/lib/tiyi/. "$TIYI_BACKUP_DIR/state/"
sudo cp -a /etc/tiyi/. "$TIYI_BACKUP_DIR/config/"
sudo systemctl cat tiyi | sudo tee "$TIYI_BACKUP_DIR/tiyi.service" >/dev/null

sudo test -f "$TIYI_BACKUP_DIR/state/state.db"
sudo ls -ld "$TIYI_BACKUP_DIR"

Add every custom store.state_db, crypto.kek_file, certificate, license, log-partition, config, and service-environment path. Verify the copy before continuing. This archive contains secrets and unredacted operational history: restrict it to root, encrypt it at rest, and move it to operator-controlled storage. It is for retention and manual reconstruction, not for restoring the old database into v3.5.

3. Completely uninstall the old version

sudo tiyi uninstall --purge

Read the prompt and type yes only after accepting total data loss. Do not automate this decision. The purge removes the unit, state, configuration, service users/groups, KEK, logs, uploaded assets, users, policies, events, and Agent enrollment. The binary remains. Because the unit is gone, sudo systemctl restart tiyi is not the next command.

4. Install or confirm the signed v3.5.0 binary

# Gitee
curl -fsSL https://gitee.com/tiyisec/tiyi/raw/main/install.sh \
  | TIYI_MIRROR=gitee TIYI_VERSION=v3.5.0 bash

# Or the canonical site/GitHub path
curl -fsSL https://www.tiyisec.com/install.sh \
  | TIYI_VERSION=v3.5.0 bash

tiyi version

If the earlier update already left tiyi version at v3.5.0, another download is optional; the purge and fresh service installation are still mandatory.

5. Create and start a fresh service

tiyi doctor --no-color
tiyi install --print
sudo tiyi install --now
sudo systemctl status tiyi --no-pager
sudo tiyi system health

tiyi install --now recreates the service identities, directories, hardened unit, and fresh Controller database. Secure the new one-time administrator password printed by the installer.

6. Recreate configuration and re-enroll Agents

Recreate sites, upstreams, certificates, WAF policies, users/RBAC, alert channels, SIEM targets, identity providers, and license configuration through the supported UI or CLI. Every remote Agent needs a new one-use enrollment token and the newly generated v3.5.0 install command. Never reuse old identity markers, tokens, cached bundles, state.db, or log partitions.

7. Complete acceptance checks

tiyi version reports v3.5.0, the unit is active, and tiyi system health is healthy.
The new administrator can sign in and replace the one-time password.
Every site sends a benign Host/SNI request to the correct upstream.
A controlled CRS probe is blocked with a non-empty response.
TLS bindings, counters, request-ID correlation, logs, and the audit chain work.
Every remote Agent is freshly enrolled, online, and on the expected revision.

If the fresh service still fails, collect systemctl status tiyi and journalctl -u tiyi -n 200 --no-pager. Identify that new failure before considering another destructive action.