应用配置
HWD POS 如何合并 config/app.php 与 storage/config.php，以及如何编辑每个安装实例的专属设置。
HWD POS 是原生 PHP 应用。其生效配置由两个文件组合而成：
| 文件 | 内容 |
|---|---|
config/app.php | 随应用发布的默认值。请勿编辑：更新时会被替换。 |
storage/config.php | 本安装实例专属的值：数据库连接、基础 URL、语言、时区以及可选服务。 |
浏览器中的安装向导会自动创建 storage/config.php。该文件可能包含密码，请妥善保管：它位于网站根目录（public/）之外，Web 服务器永远不会对外提供它。
编辑 storage/config.php
如需手动修改某个值，请编辑 /var/www/HWDPOS/storage/config.php。其结构如下：
<?php
return [
'app' => [
'name' => 'HWD POS',
'env' => 'production',
'debug' => false,
'base_url' => '',
'locale' => 'es',
'timezone' => 'America/Panama',
],
'db' => [
'driver' => 'mysql',
'socket' => '',
'host' => '127.0.0.1',
'port' => '3306',
'database' => 'hwd_pos',
'username' => 'hwdpos_manager',
'password' => 'YOUR_DB_PASSWORD',
'charset' => 'utf8mb4',
],
];修改文件后，在浏览器中重新加载应用即可。
生产环境中请保持 debug 为 false。详细的错误信息可能泄露内部信息。
选项
app
| 键 | 说明 |
|---|---|
name | 应用名称。 |
env | 运行环境。请使用 production。 |
debug | 显示详细错误。生产环境中为 false。 |
base_url | 基础 URL。通常留空：系统内部链接均为相对路径，因此在任意 IP 或端口上都能正常工作。 |
locale | 默认语言：es（西班牙语）、en（英语）或 zh（中文）。用户可在顶部栏切换。 |
timezone | 应用时区。系统使用巴拿马时间（America/Panama）。 |
typesense | 可选的搜索服务连接。参见 Typesense 搜索。 |
db
| 键 | 说明 |
|---|---|
driver | mysql（MariaDB 或 MySQL）。 |
socket | Unix 套接字路径。如果不为空，将优先于 host 和 port。 |
host | 数据库服务器。同一台服务器时为 127.0.0.1；在分离式安装中为数据库服务器的 IP。 |
port | 3306。 |
database | 数据库名称（默认为 hwd_pos）。 |
username | 数据库用户（由安装程序创建时为 hwdpos_manager）。 |
password | 数据库用户的密码。 |
charset | utf8mb4。请勿修改。 |
套接字还是 TCP
在 Linux 服务器和 Windows 上，请将 socket 留空，通过 TCP 连接到 host 和 port。安装程序默认就是这样配置的。
套接字仅用于特殊的本地环境。例如，在 macOS 上使用 XAMPP 时，套接字通常为 /Applications/XAMPP/xamppfiles/var/mysql/mysql.sock。
host 请使用 127.0.0.1 而不是 localhost。使用 localhost 时，MySQL 驱动会尝试使用套接字，可能报错“No such file or directory”。
数据库密码
如果在 MariaDB 中修改了数据库用户的密码，也要同步更新此处的 password。重新运行安装程序时会自动保持两者一致：它从 storage/config.php 读取密码并应用到数据库用户。可以通过 hwdpanel（选项 8）或以下命令查看当前凭据：
php /var/www/HWDPOS/scripts/hwd-admin.php db-info旧版 .env 文件
旧版本使用 .env 文件。现在已不再需要；仅在从旧版本迁移期间临时保留即可。无论如何，Web 服务器都会阻止访问 .env 文件。