文档手册

服务器迁移、备份和恢复：哪些文件必须带走

覆盖升级是在同一台机器上运行新安装包，安装器会保留运行配置和数据；换服务器是把项目迁到另一台机器，需要先备份旧机器，再在新机器安装、恢复数据、重新确认授权。

维护

维护: 服务器迁移、备份和恢复：哪些文件必须带走

迁移服务器时不要只复制安装目录，也不要只复制画面文件。正式迁移至少要处理数据库、配置、画面资源、画面历史、授权记录和交付说明；换硬件后还要重新走授权申请。

先分清是覆盖升级还是换服务器

同机覆盖升级：先备份，再运行同架构安装包，确认服务和画面。
换服务器：不要直接复制整个安装目录后启动，应按新机器重新安装。
分布式部署：先确认 database / app / io 角色，不能把 IO 节点当成数据库节点迁移。
更换硬件后旧机器授权文件不能直接复用，新机器需要新的授权请求。

必须备份的核心数据

核心数据分成三类：PostgreSQL 数据库、运行配置和画面资源。数据库里有站点、设备、Tag、菜单、权限、报警、趋势、事件记录和脚本配置；画面资源在 screens/assets；主机配置在 config。

PostgreSQL：主数据、Tag、报警、趋势、事件记录、权限、菜单和脚本配置的主要来源。
配置目录：hqcontrol.env、启动管理配置、安装清单和授权服务地址等主机级设置。
画面目录：PPT 导出的 HTML / SVG / JS / JSON / IMG 等运行资源。
画面历史：画面文件服务的上传、发布、恢复快照，默认保留最近历史。
日志可选备份：迁移排障时建议带上 logs，但日志不是恢复业务的主数据。

数据库备份方式选择方式

数据库备份优先使用 PostgreSQL 备份工具。pg_dump 适合按数据库导出迁移文件；外部数据库可以使用现场已有备份系统；冷备份只在明确停机窗口内使用。不要在服务运行时直接复制 PostgreSQL 数据目录。

单机内置数据库：优先导出数据库备份文件，再备份配置和画面目录。
外部 PostgreSQL：按数据库管理员提供的备份策略处理，并确认 TimescaleDB 扩展可恢复。
迁移窗口内建议暂停业务写入，避免备份期间配置继续变化。
备份文件应记录版本、导出时间、数据库名和来源服务器。
恢复前确认目标 HQControl 版本与数据库结构兼容。

# 示例命令需按现场数据库地址、端口、账号、库名和路径调整
pg_dump -h <db-host> -p <db-port> -U <db-user> -Fc <db-name> -f hqserver-db.dump

配置和资源备份分层

配置和资源不要只压缩整个安装目录。建议按主机配置、业务数据库、画面目录、画面历史、画面内容配置、脚本文件和日志分类保存。这样恢复时可以按顺序处理，也便于判断某个问题属于配置、数据还是资源缺失。

主机配置：config/hqcontrol.env、启动配置、安装清单。
业务数据库：通过 PostgreSQL 工具导出的数据库备份。
画面目录：screens/assets 下的运行页面包（PPT 导出的 HTML/SVG/JS 等）。
画面历史：data/screen-file-history 下的上传、发布和恢复记录。
画面内容配置：configs/popup-templates/ 下的弹窗模板（每个模板一个文件），以及 configs/ 下的菜单等配置。
脚本文件：configs/integration-scripts/integration-script 下的 .py、.toml、.trigger.toml。
日志资料：logs 作为迁移排查留档，不作为业务恢复主数据。

Windows 默认备份位置

Windows 默认安装根目录优先是 D:\HQCONTROL；如果 D 盘不是固定本地磁盘，安装器会回退到 C:\HQCONTROL。下面路径中的盘符按实际安装根目录替换。

D:\HQCONTROL\config\hqcontrol.env
D:\HQCONTROL\config\hqcontrol.launcher.json
D:\HQCONTROL\config\install.manifest.json
D:\HQCONTROL\data\postgres\
D:\HQCONTROL\data\redis\
D:\HQCONTROL\screens\assets\
D:\HQCONTROL\data\screen-file-history\
D:\HQCONTROL\configs\popup-templates\          # 弹窗模板（每个模板一个文件）
D:\HQCONTROL\logs\          # 可选，排障留档
D:\HQCONTROL\configs\integration-scripts\integration-script\  # 如现场使用文件式脚本迁移

Linux 默认备份位置

Linux 默认安装根目录是 /opt/hqcontrol。如果安装时使用了 INSTALL_ROOT=/data/hqserver，就把下面路径里的 /opt/hqcontrol 替换成实际安装根目录。

/opt/hqcontrol/config/hqcontrol.env
/opt/hqcontrol/data/postgres/
/opt/hqcontrol/data/redis/
/opt/hqcontrol/screens/assets/
/opt/hqcontrol/data/screen-file-history/
/opt/hqcontrol/configs/popup-templates/          # 弹窗模板（每个模板一个文件）
/opt/hqcontrol/logs/          # 可选，排障留档
/opt/hqcontrol/configs/integration-scripts/integration-script/  # 如现场使用文件式脚本迁移

备份数据库时不要热复制数据目录

PostgreSQL 数据目录不能在服务运行时随手复制。推荐使用数据库备份工具；如果必须做冷备份，先停 HQControl、PostgreSQL 和 Redis，确认服务完全停止后再复制数据目录。

Windows 先通过启动设置或服务管理停止 HQControl、HQControlPostgreSQL、HQControlRedis。
Linux 可先执行 sudo hqcontrolctl disable，再 sudo hqcontrolctl stop，避免 watchdog 自动拉起。
数据库恢复后再启动服务，确认数据库迁移记录和系统状态正常。
迁移前记录旧版本和目标版本，避免数据库 schema 与应用版本不兼容。

迁移到新服务器的推荐顺序

先记录旧服务器状态，再安装新服务器，再恢复数据，最后重新授权并完成交付确认。不要把旧机器的授权文件、运行时二进制和可再生成目录当成项目数据直接复制过去。

旧服务器：记录版本、安装根目录、/settings、/license、系统状态和当前画面目录。
旧服务器：备份 PostgreSQL、config、screens/assets、data/screen-file-history，必要时备份 logs。
新服务器：安装同版本或目标版本 HQControl，确认 8080 能打开。
新服务器：恢复数据库和画面资源，检查 /settings 中 PostgreSQL、Redis、公开主机名和授权服务地址。
新服务器：进入 /license 导出新的授权请求，按在线或离线流程完成授权。
交付确认：系统状态、设备连接、Tag 诊断、画面菜单、报警趋势、脚本接口各走一遍。

恢复顺序和配置校准

新服务器恢复时，先让干净安装的 HQControl 能打开，再恢复数据库和画面资源。恢复后必须重新校准主机相关配置，尤其是公开主机名、数据库地址、Redis 地址、授权服务地址、脚本 Python 路径和反向代理配置。

先安装目标版本 HQControl，并确认 /settings 和 /license 能进入。
停止服务或进入维护窗口，再恢复数据库和资源目录。
恢复后打开 /settings，检查对外访问地址是否仍指向旧服务器。
检查数据库、缓存、画面目录、脚本 Python 和授权服务地址。
进入 /license 为新机器重新处理授权，不直接复用旧机器授权文件。
恢复完成后，按系统状态、主数据、画面菜单、报警趋势、接口脚本的顺序确认。

脚本和第三方接口迁移后确认方式

迁移后不要只看脚本文件是否存在，还要确认脚本元数据、触发器、工作目录、本地包目录、外部系统地址和访问 Key。第三方系统通常还需要更新 HQControl 地址、访问 Key 或反向代理入口。

Integration Script 页面应能看到脚本、触发器和最近执行记录。
脚本工作目录下的 libs、packages、site-packages 应随项目一起恢复。
外部 HTTP、MQTT、SQL 地址如果包含旧服务器地址，需要逐项更新。
IO State API 访问 Key 如已轮换，应同步给第三方系统。
WebSocket 订阅经过反向代理时，确认 Upgrade 配置仍然生效。

哪些目录通常不要当作项目备份

运行时程序和离线依赖可以通过安装包恢复，不应该和业务数据混在一起长期备份。除非正在执行完整镜像回滚，否则不要把这些目录当成项目迁移的主资料。

bin、web/admin/dist、modules/packages：随安装包恢复。
runtime/python、runtime/postgresql、runtime/redis：运行时依赖，不是项目业务数据。
run、缓存目录、安装器展开目录：可重新生成。
Redis 是热缓存和实时分发组件；正式历史和主数据仍以 PostgreSQL 为准。

迁移后最常见的 5 个检查点

迁移后如果页面能打开但数据不对，优先按这五项检查。它们覆盖大多数现场迁移问题。

设置页里的对外访问地址是否还是旧服务器地址。
/license 是否仍显示旧机器授权或未激活。
画面文件页显示的运行目录里是否有 screens/assets/<screen-code>/index.html。
系统状态里的 PostgreSQL、Redis、IO State API、Integration Script、WebSocket 是否健康。
Tag 诊断是否能读到关键点；如果只是部分点 bad/stale，到 Bad 检查里复核，不要把整个设备直接判为不可用。