常见问题
安装和运行 HWD POS 时最常遇到的问题的症状、可能原因及解决方法。
开始之前
- 阅读安装程序输出的最终摘要。每个 ✗ 都指向一个组件。
sodium、Chrome/Chromium 或时区上的 ✗ 不会妨碍您继续；而pdo_mysql、MariaDB 或端口上的 ✗ 则会。 - 运行诊断：
sudo bash /var/www/HWDPOS/deploy/check.sh（参见使用 check.sh 进行诊断）。 - 请记住，重新运行安装程序是安全的：它不会删除数据，并会把权限、Web 服务器配置、服务和防火墙恢复到正确状态。
Web 访问
可能原因：端口未在监听，或被防火墙拦截。
检查是否有程序在监听该端口，以及 Web 服务器是否正在运行：
sudo ss -ltn | grep :80
sudo systemctl status apache2 # or httpd, or nginx如果您使用的不是 80 端口，请在命令中替换为实际端口。另外，请确认在地址中输入了端口（例如 http://192.168.1.50:8080/）。
可能原因：Web 服务器没有把 PHP 请求转交给 PHP-FPM。
重新运行安装程序；它会写入正确的 Web 服务器配置。
这并不是故障：站点使用的是另一个端口，而检查会从配置中读取该端口。如果问题持续存在，请检查 Web 服务器的 Listen 指令是否包含该端口。参见 Web 服务器配置。
数据库
可能原因：主机填写错误。localhost 会强制使用套接字（socket）连接。
在设置向导的第 2 步中，将主机填写为 127.0.0.1。
可能原因：密码错误。
查看安装程序生成的密码：
sudo cat /var/www/HWDPOS/deploy/DB-CREDENTIALS.txt
# On a database-only server:
sudo cat /root/HWDPOS-DB-CREDENTIALS.txt如果文件中的密码与数据库不一致，请重新运行安装程序：它会把配置（或凭据文件）中的密码应用到数据库用户上，使两者重新一致。参见升级与重新安装。
可能原因：数据库连接配额已满。
在 Sistema → Capacidad de conexiones（系统 → 连接容量）中调整，或使用 sudo hwdpanel → 选项 19。
权限与 SELinux
可能原因：文件权限问题，或 AlmaLinux 上的 SELinux。
-
Ubuntu/Debian：将该文件夹的所有权交给 Web 用户：
sudo chown -R www-data:www-data /var/www/HWDPOS -
AlmaLinux/Rocky/RHEL：重新运行
install-almalinux.sh，它会应用 SELinux 上下文。
可能原因：SELinux 未配置。没有任何错误信息会提到 SELinux，因此这个问题很难发现。
用以下命令确认：
sudo ausearch -m avc -ts recent然后重新运行 install-almalinux.sh。参见 AlmaLinux。
激活
可能原因：服务器无法访问互联网。激活需要服务器能够访问外部互联网。
在服务器上测试：
curl -sI https://3r.com.pa/pos | head -1如果没有响应，请检查服务器的 DNS、网关和防火墙。在 AlmaLinux 上，还要检查 SELinux（见上文）。
打印
可能原因：打印服务未运行。
sudo systemctl status hwpos-print
sudo journalctl -u hwpos-print -f使用 sudo hwdpanel → 选项 16 重新安装后台服务。参见打印。
可能原因：没有可用的 Chrome/Chromium。在 Ubuntu 上，chromium-browser 只是通往 Snap 的桥接程序，没有 snapd 就无法启动：sudo -u www-data chromium-browser --version 会返回“requires the chromium snap”。
-
Ubuntu/Debian（amd64）：从官方软件包安装 Google Chrome，或使用
check.sh→ “Chrome/Chromium”：curl -fsSLO https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb sudo apt-get install -y ./google-chrome-stable_current_amd64.deb -
AlmaLinux：
sudo dnf install -y chromium
确认它能以 Web 用户身份运行：
sudo -u www-data google-chrome-stable --version如果您使用其他浏览器，请在 HWD POS 的 Ajustes → chrome_path（设置 → chrome_path）中设置其路径。
可能原因：A4 打印机被配置成了热敏打印机。
在 Sistema → Impresoras（系统 → 打印机）中，将纸张设置为 «A4 documento»（A4 文档）。
安装脚本
典型信息：
Repository '…ondrej/php…' changed its 'Label' value … must be accepted explicitly脚本已经使用了 --allow-releaseinfo-change。如需手动修复：
sudo apt-get update --allow-releaseinfo-change输入路径时不要加引号：
/root/HWDPOS-v1.5.0.zip脚本也会尝试去掉误粘贴的引号。
进程在完成之前就停止了。请阅读之前显示的错误信息，然后再次运行脚本。这些脚本是幂等的：重新运行不会无谓地重装已经正常工作的组件。
脚本会检测实际使用的 PHP-FPM 版本，并用以下命令检查软件包：
dpkg -s phpX.Y-<extension>该检查不依赖终端中配置的 php 版本。请确认该扩展是为站点所用的 PHP-FPM 版本安装的。
可能原因：无法获取 install-workers.sh 或 hwdpanel.sh（.zip 软件包中不包含它们）。
请联系您的供应商，或将这些文件复制到 /var/www/HWDPOS/deploy/ 后重新运行安装程序。
您使用的是旧版本脚本，它会在 .zip 中查找安装程序。请重新下载 bootstrap.sh；当前版本会从分发服务器下载安装程序。
您使用的是旧版本脚本（它调用了 apt-get，而这些系统上没有该命令）。请重新下载：
curl -fsSL https://3r.com.pa/hwdpos_inst/bootstrap.sh | sudo bash如果该系统家族的安装程序仍然无法获取，请将 INSTALLER_URL=… 设置为其所在位置，或将 install-almalinux.sh 复制到服务器上直接运行。
这是旧版本：它用 dpkg 查询软件包，而这些系统上没有 dpkg。请重新下载；当前版本使用 rpm 查询，并通过运行 install-almalinux.sh 进行修复。
仍未解决？
请查看常见问答，或联系您的 HWD POS 供应商，并提供安装程序的最终摘要以及 CHECK_ONLY=1 bash /var/www/HWDPOS/deploy/check.sh 的输出。