第一步：先选对 Linux 安装包
Linux 包按 CPU 架构区分。普通 x86_64 服务器使用 HQControl-linux-x86_64.tar.gz；ARM64 / aarch64 服务器使用 HQControl-linux-aarch64.tar.gz。Parallels 中运行的 Ubuntu 如果 uname -m 显示 aarch64，就必须使用 aarch64 包，不能使用 x86_64 包强制安装。
- 先在服务器执行
uname -m。
x86_64 使用 HQControl-linux-x86_64.tar.gz。aarch64 或 arm64 使用 HQControl-linux-aarch64.tar.gz。- 架构不匹配时安装器会直接拒绝，避免装进去以后运行时才报 ELF 错误。
uname -m
# x86_64 服务器
tar -xzf HQControl-linux-x86_64.tar.gz
cd HQControl-linux-x86_64
# aarch64 / arm64 服务器
tar -xzf HQControl-linux-aarch64.tar.gz
cd HQControl-linux-aarch64
第二步：执行安装器
进入解压后的安装包目录后执行 sudo bash install.sh。安装器会把 HQControl 安装到 /opt/hqcontrol，准备数据库、缓存服务和主程序，并启用开机自启。最后会做健康检查；如果服务没起来，安装器会提示下一步查看状态或日志。
- 命令使用
bash，完整写法是 sudo bash install.sh。
sudo 写在 bash 前面。- 安装完成后会提示访问地址，默认是
http://127.0.0.1:8080。
- 安装器没有显示完成时，先看最后输出的服务日志。
sudo bash install.sh
磁盘空间和安装目录先确认
安装前要确认目标分区有足够空间。安装器会提前检查目标路径是否可写、是否在光盘或只读文件系统上、剩余空间是否足够；空间不足时会提前停止。
- 默认安装目录是
/opt/hqcontrol。
- 先执行
df -h 看 /opt 所在分区剩余空间。
- 虚拟机里如果挂了光盘或 ISO，不要把安装目录指向光盘挂载点。
- 空间不足时可以清理旧的半安装目录，或安装到更大的数据盘。
df -h
lsblk -f
sudo rm -rf /opt/hqcontrol/runtime/redis
sudo apt clean
# 安装到更大的数据盘
sudo INSTALL_ROOT=/data/hqserver bash install.sh
无图形界面的 Linux 打开方式设置和授权
/settings 和 /license 用于配置数据库、Redis、端口、授权服务、脚本 Python 路径和激活授权。本机访问不需要额外登录；远程访问时，先用最高管理员账号登录 HQControl 管理端，再打开这两个地址。服务器没有桌面浏览器时，也可以通过 SSH 隧道从本地电脑打开。
- 服务器本机地址：
http://127.0.0.1:8080/settings。
- 服务器本机授权页：
http://127.0.0.1:8080/license。
- 远程地址：
http://服务器IP:8080/settings 和 http://服务器IP:8080/license，需要已登录管理员。
- 未登录或普通账号只能看到页面外壳，读取和保存接口会被拒绝。
- SSH 隧道会让 HQControl 看到本机访问，适合没有桌面环境的 Linux 服务器。
ssh -L 8080:127.0.0.1:8080 user@SERVER_IP
# 然后在本地电脑浏览器打开
http://127.0.0.1:8080/settings
http://127.0.0.1:8080/license
其他电脑访问方式 HQControl
管理端和运行页面可以给局域网或公网访问。HQControl 默认监听所有网卡的 8080 端口；其他电脑可以访问 http://服务器IP:8080，如果主机名或域名能解析，也可以访问 http://主机名:8080 或反向代理域名。
- 同网段电脑访问：
http://服务器IP:8080。
- 主机名访问要求 DNS、hosts 或局域网名称解析可用。
- 云服务器要放行安全组或配置反向代理。
- 客户机只需要访问
8080。
- 数据库、缓存、脚本执行都是本机内部服务，不要直接开放到公网。
- IO State API 没有独立端口，走 HQControl 的
8080。
hostname -I
sudo hqcontrolctl ports
覆盖安装操作方式
升级或修复时，可以直接用同架构的新包再次执行安装器。覆盖安装会替换程序文件，同时保留运行配置、数据库数据、日志和运行目录。
- 保留
/opt/hqcontrol/config，避免覆盖现场配置。
- 保留
/opt/hqcontrol/data，避免重建数据库数据。
- 保留
/opt/hqcontrol/logs、/opt/hqcontrol/run 和 /opt/hqcontrol/runtime。
- 已有数据库数据时不会重新初始化数据库。
- 覆盖后会重新启用开机自启并重新验证 HTTP 健康状态。
tar -xzf HQControl-linux-aarch64.tar.gz
cd HQControl-linux-aarch64
sudo bash install.sh
安装后用 hqcontrolctl 验证
安装器会把 hqcontrolctl 安装到 /usr/local/bin/hqcontrolctl。以后用这个命令看状态、重启、查健康、看日志、查端口、查看配置，也可以在无图形环境导出或导入离线授权文件。
status 看 PostgreSQL、Redis、HQControl 三个服务状态。health 检查 HQControl 是否健康。restart 按 PostgreSQL、Redis、HQControl 顺序重启。logs 默认看主服务日志，logs postgres 看数据库日志，logs all 看全部日志。ports 看当前服务器监听端口，排查 8080 是否真的起来。license status/export/import 用于授权状态、离线请求导出和激活文件导入。
sudo hqcontrolctl status
sudo hqcontrolctl health
sudo hqcontrolctl restart
sudo hqcontrolctl logs
sudo hqcontrolctl logs postgres
sudo hqcontrolctl logs all
sudo hqcontrolctl ports
sudo hqcontrolctl config
sudo hqcontrolctl license status
服务停止了处理方式
Linux 安装器会把服务加入开机自启。程序异常退出时会自动尝试恢复；如果人工停止过服务，或配置错误导致服务反复失败，用 hqcontrolctl 查看状态和日志，再决定重启还是修配置。
- 先执行
sudo hqcontrolctl status 看哪个服务停了。
- 再执行
sudo hqcontrolctl logs 看 HQControl 主服务为什么退出。
- 数据库相关问题看
sudo hqcontrolctl logs postgres。
- Redis 相关问题看
sudo hqcontrolctl logs redis。
- 确认问题处理后执行
sudo hqcontrolctl restart。
sudo hqcontrolctl status
sudo hqcontrolctl logs
sudo hqcontrolctl logs postgres
sudo hqcontrolctl restart
网页打不开先按这个顺序查
浏览器打不开 127.0.0.1:8080 时，先确认浏览器运行在哪台机器上。Ubuntu 虚拟机里的 127.0.0.1 指 Ubuntu 系统本机；Mac 主机里的 127.0.0.1 指 Mac 本机。服务正常但在主机浏览器打不开时，用 Ubuntu 的 IP 地址访问，或直接在 Ubuntu 中打开浏览器。
- 在 Linux 服务器本机执行
sudo hqcontrolctl health，先确认服务是否健康。
- 执行
sudo hqcontrolctl ports，确认 8080 是否监听。
- 在虚拟机外访问时，使用虚拟机 IP。
- health 不通时，直接看
sudo hqcontrolctl logs。
- health 通但浏览器打不开时，再看防火墙、虚拟机网络模式和访问地址。
sudo hqcontrolctl health
sudo hqcontrolctl ports
hostname -I
默认目录和端口
默认安装根目录是 /opt/hqcontrol，网页端口默认 8080。数据库、缓存、脚本执行用的是本机内部端口，装好后默认锁在本机，不用对外开放。画面文件的运行目录在安装目录下的 screens/assets（Linux 默认 /opt/hqcontrol/screens/assets，Windows 在安装根目录下的 screens\assets）。现场如果改过配置，以 sudo hqcontrolctl config 显示的为准。
/opt/hqcontrol/config/hqcontrol.env 保存运行配置。/opt/hqcontrol/data/postgres 保存数据库数据。/opt/hqcontrol/data/redis 保存缓存数据。/opt/hqcontrol/screens/assets 保存画面文件，菜单配置的页面选择也从这里扫描。/usr/local/bin/hqcontrolctl 是安装后的系统命令。
sudo hqcontrolctl config
ls -la /opt/hqcontrol/screens/assets
