系统要求
HWD POS 会安装哪些组件、支持哪些操作系统，以及所需的硬件和网络条件。
HWD POS 是一个原生 PHP 系统：不使用框架、Composer、Node 或 Docker。因此安装只需三个必需组件和少量可选组件。安装程序会为你完成全部配置；本页说明每个组件的用途，便于你规划服务器并看懂安装程序最后输出的摘要。
必需组件
| 组件 | 版本 | 在 HWD POS 中的作用 |
|---|---|---|
| PHP | 8.2 或更高（8.1 可以运行，但安装向导要求 8.2） | 这就是系统本身。同一个 PHP 会安装两种形态：FPM，负责提供浏览器打开的页面；CLI，负责运行两个后台服务（打印和插件）以及维护任务。 |
| MariaDB | 10.4 或更高（或 MySQL 8） | 存储所有数据：商品、库存、客户、报价单、发票、收银、赊账和审计日志。系统更新会使用 ADD COLUMN IF NOT EXISTS，MySQL 5.x 不支持该语法，因此低于 10.4 时更新会中途失败。 |
| Web 服务器 | Apache 2.4 或 Nginx 1.18+ | 接收请求，并将应用的请求转交给 PHP-FPM。其文档根目录必须指向 public/ 文件夹，绝不能指向项目根目录。 |
为什么是 public/ 而不是项目根目录
项目文件夹中包含配置（含数据库密码）、备份和源代码。将文档根目录设为 public/ 后，即使有人猜到文件名，也无法通过网络访问这些内容。安装程序会按此方式配置，并且还会显式屏蔽 .env、.sql、.md、.sh 和 .lock 文件。
PHP 扩展
安装程序会安装以下全部扩展。浏览器中的安装向导会再次检查，并在允许继续之前显示 ✓ / ✗。
| 扩展 | 是否必需 | 缺少时哪些功能失效 |
|---|---|---|
| pdo_mysql | 是 | 一切都无法工作：它就是数据库连接。 |
| mbstring | 是 | 带重音符号和 ñ 的文本会被截断或损坏（客户和商品名称、搜索）。 |
| curl | 是 | 所有需要访问互联网的功能：许可证激活、更新检查、电子发票、Yappy、SMTP 邮件和帮助助手。 |
| zip | 推荐 | 安装和更新插件、应用系统更新、从电子表格导入客户和商品，以及导出到 Excel。 |
| gd | 推荐 | A4 单据上的水印以及送货时客户的签名。 |
| xml | 推荐 | 读取客户和商品的导入电子表格。 |
| opcache | 推荐 | 不会出错，但系统明显变慢：每个页面在每次请求时都会重新编译。 |
| sodium | 推荐 | 验证许可证签名。缺少时会使用内置的备用实现：功能相同，只是更慢。 |
| pcntl（仅 CLI） | 推荐 | 缺少时，两个后台服务在更新后无法自行加载新代码；需要手动重启。 |
可选组件
| 组件 | 用途 | 缺少时 |
|---|---|---|
| CUPS | 在 A4 打印机（喷墨或激光）以及通过 IPP/AirPrint 的网络打印机上打印。 | 热敏打印机（ESC/POS，80 mm 和 58 mm）仍可正常工作：它们不经过 CUPS。 |
| Google Chrome（或 Chromium） | 将完整的 A4 单据（设计好的发票和报价单）渲染为 PDF。在 Ubuntu/Debian（amd64）上，安装程序会从官方软件包安装 Google Chrome，因为 Ubuntu 的 chromium-browser 只是指向 Snap 的桥接程序，没有 snapd 就无法运行，尽管该命令存在。 | 小票式打印仍然可用；无法生成设计好的 A4 单据。 |
| Typesense | 为所有搜索提供容错拼写搜索。参见 Typesense 搜索。 | 使用常规的 SQL 搜索。无需配置。 |
使用 WITH_PRINTING=no 时，安装程序会跳过 CUPS 和 Chrome/Chromium。适用于不打印的服务器，例如只承载数据库的服务器。
后台服务
安装程序会保留两个运行中的服务：
| 服务 | 作用 | 检查方法 |
|---|---|---|
hwpos-print | 逐个打印系统放入队列的单据。 | systemctl status hwpos-print |
hwpos-plugins | 运行插件的后台任务（例如由服务器向客户发送邮件，收银员无需等待）。 | systemctl status hwpos-plugins |
两者都必须处于 active（运行中）和 enabled（开机自动启动）状态。安装程序的最终摘要会检查这两项。
支持的操作系统
每个系统家族对应一个安装程序，提问相同、模式相同、最终摘要也相同。
| 系统 | 版本 | 安装程序 |
|---|---|---|
| Ubuntu Server （推荐） | 24.04 LTS（推荐）、22.04 LTS | install-ubuntu.sh |
| Debian | 12 | install-ubuntu.sh |
| AlmaLinux | 9（推荐）、8 | install-almalinux.sh |
| Rocky Linux / RHEL / CentOS Stream | 9、8 | install-almalinux.sh |
表中的所有系统都能正常运行，最终功能完全相同。
尽管如此，我们仍推荐 Ubuntu Server 24.04 LTS，因为 HWD POS 主要在该系统上配置和测试。它的官方软件源自带 PHP 8.3，所需手动步骤更少，出现问题时也更容易诊断。实用原则：如果还能选择服务器的操作系统，就选 Ubuntu。如果服务器已经存在且运行的是 AlmaLinux、Rocky、RHEL 或 CentOS，也可以放心安装；它们受支持且有专用的安装程序。请先阅读 AlmaLinux 说明。
不支持： Windows Server（系统依赖 systemd 服务、Linux 打印路径和 pcntl），以及任何 PHP 版本低于 8.1 的 Linux。
硬件
| 最低配置 | 推荐配置（有 3–8 台终端的门店） | |
|---|---|---|
| CPU | 2 核 | 4 核 |
| 内存 | 2 GB | 4 GB 或以上 |
| 磁盘 | 20 GB | 40 GB SSD |
| 系统 | 64 位 | 64 位 |
内存决定了服务器能同时处理多少笔销售。 安装程序按每个进程约 60 MB 来确定 PHP 进程数，最少 10 个、最多 80 个，并始终低于数据库连接上限（300）。2 GB 内存约可运行 33 个进程；4 GB 约 68 个。之后可以在 «Sistema → Capacidad de conexiones»（系统 → 连接容量）中以及通过 hwdpanel（选项 19）查看和调整。
磁盘占用主要随三类内容增长：数据库备份、商品照片以及送货照片和签名。对于典型的五金店，40 GB 足够使用多年。
虚拟机（Proxmox 等）
- 虚拟机（KVM）还是 LXC 容器： LXC 容器更轻量，但要将 USB 打印机传入 LXC，需要特权容器并绑定挂载
/dev/usb/lp0。在虚拟机中则使用 USB 直通（在 Proxmox 中：Hardware → Add → USB Device）。 - 最简单的方案：网络（IP）打印机。 完全不需要 USB 直通：打印服务通过 9100 端口套接字（热敏）或 IPP/AirPrint 队列（A4）打印。推荐用于虚拟化环境。
- 单个门店的典型资源：2 个 vCPU、2–4 GB 内存、20 GB 磁盘。
- 为虚拟机或容器在局域网中分配固定 IP，以便终端和平板能够访问。
网络
| 要求 | 说明 |
|---|---|
| 局域网固定 IP | 终端、平板和打印机通过 IP 指向服务器。IP 变化后需要重新配置它们。可在服务器上设置，或在路由器中保留该地址。 |
| 出站互联网访问 | 激活许可证、检查更新和发送邮件时需要。服务器不需要能从互联网访问。 |
| 在局域网中开放站点端口 | 默认为 80 端口。参见网络安装。 |
| 3306 端口 | 仅当数据库运行在另一台服务器上时需要。只对 Web 服务器的 IP 开放。 |
无需将服务器发布到互联网：所有功能在局域网内即可工作。只有在需要从门店外部访问时才需要发布，此时应添加 HTTPS（例如使用 Let's Encrypt）。安装程序不会配置 HTTPS。
安装前准备
- 一台运行受支持系统的全新服务器。
root权限或具有sudo权限的用户。- 服务器本身能够访问互联网（用
ping -c2 3r.com.pa测试）。 - 供应商提供的激活密钥和客户代码。
然后继续进行网络安装。