Deployment, Upgrade, and Backup

Many deployment questions are not really about installation commands. The real gaps are usually in post-deployment work, migration cutover, backup scope, and proxy behavior. This page collects those high-frequency operational FAQs.

What is most often missed during server migration?

The most common miss is: the new environment is installed, but networking, firewall rules, key reports, and rollback path were not fully verified before cutover.

A safer migration sequence is usually:

1. deploy and validate access on the new server first
2. stop services on the old server and export metadb plus MinIO data
3. import them into the new server
4. validate service state and key reports
5. only then switch the domain or traffic

The fourth step is the one teams skip most often.

During migration, what data must be backed up, and what usually does not need to move?

The highest-priority pieces are:

• metadb
• MinIO object storage

For built-in warehouse / engine data, many scenarios do not prioritize full migration. Instead, it is often better to restore the new environment first and then retrigger sync tasks.

Treating all data as "must be copied exactly as-is" usually increases migration time and rollback complexity.

What are the two most important actions before an upgrade?

1. Stop the old version cleanly
2. Confirm backup and rollback paths are really available

The upgrade steps themselves are usually clear. What often fails in practice is:

• the old service was not fully stopped
• backup availability was never confirmed
• when something goes wrong, nobody knows where the rollback package or rollback steps are

So do not focus only on the installer. Focus equally on how you retreat safely.

Why is the service reachable on the server itself but not from another machine?

Usually this does not mean the HENGSHI service is down. It usually means the port is not exposed, the firewall is not open, or the proxy is not configured correctly.

A common check order:

1. curl http://127.0.0.1:8080 on the server
2. curl http://IP:8080 from another machine
3. if local works but remote fails, check firewall and security-group rules first

Do not begin by assuming the application process is broken.

How should HENGSHI ports be exposed externally?

Do not expose internal service ports directly to the public internet.

A better pattern is:

• keep internal services running normally
• expose a unified external entry through Nginx or another reverse proxy
• expose HTTPS publicly

At the proxy layer, it is also recommended to enable:

• HTTP/2
• gzip

That affects both security posture and end-user experience.

Why does a proxied deployment show "page cache invalid, please refresh browser"?

A very common reason is that the proxy rewrites the cookie name or format, so the system can no longer parse it correctly and cannot obtain x-csrf-token.

So the issue is often not that the browser cache is really invalid. The proxy chain broke login-state cookies.

If proxied cookies change from csrf=... and sid=... into some unexpected prefixed format, inspect proxy rules before telling users to keep refreshing.

What is the most common mistake in backup and restore work?

The most common mistake is: backups exist, but restore was never rehearsed.

At minimum, make sure you know:

1. where backup files are stored
2. which services must be stopped and which old directories must be moved away during restore
3. how business availability will be validated after restore

Without restore rehearsal, many "successful" backups are not actually operationally ready.

When is an upgrade or migration truly complete?

Not when the process starts successfully. At minimum, all of these should be true:

1. service state is healthy
2. key reports open correctly
3. external access works through the real access path
4. a rollback path is available when needed

If the only success condition is "the process is active," many issues will surface after cutover instead of before it.

Further reading:

• Single-node Upgrade
• Backup and Restore
• Post-deployment Notes