OpenSourcePOS CI4 版本安装指南与常见问题解决

环境准备与基本安装

OpenSourcePOS 的 CI4 版本是基于 CodeIgniter 4 框架重构的开源销售点系统。在开始安装前，需要确保系统已安装以下组件：

1. PHP 7.4 或更高版本
2. Composer 包管理工具
3. Node.js 环境
4. 数据库服务(MySQL/MariaDB)

安装过程首先需要克隆或下载项目代码，然后执行以下命令安装依赖：

composer install
npm install
npm run build

配置文件设置

项目中有两个关键的配置文件需要特别注意：

1. App.php 中的 $baseURL 参数必须正确指向项目目录。例如：

public string $baseURL = 'http://localhost/ci4/public/';

2. .env 文件需要包含数据库连接信息和其他关键配置。典型配置应包括：

database.default.hostname = localhost
database.default.database = ospos_db
database.default.username = db_user
database.default.password = db_pass

服务器配置

Apache 配置

确保项目目录下的 .htaccess 文件配置正确，典型配置如下：

RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php?/$1 [L]

开发服务器启动

可以使用 CodeIgniter 4 内置的开发服务器进行测试：

php spark serve

常见安装问题解决

1. 显示 CodeIgniter 默认页面而非 OSPOS 登录界面

   • 检查 $baseURL 配置是否正确
   • 确保 .env 文件中的配置完整
   • 确认所有依赖已正确安装

2. 前端资源加载问题

   • 确保执行了 npm install 和 npm run build
   • 检查 public 目录下的资源文件是否完整

3. "Whoops" 错误页面

   • 检查 .env 文件是否存在且配置正确
   • 确保数据库连接信息准确
   • 查看日志文件获取详细错误信息

最佳实践建议

1. 在开发环境中，建议将 .env 中的 CI_ENVIRONMENT 设置为 development 以便显示详细错误信息
2. 生产环境中务必设置 app.forceGlobalSecureRequests = true 强制使用 HTTPS
3. 定期备份 .env 文件，因为它包含敏感信息
4. 使用版本控制系统时，确保将 .env 添加到忽略列表

通过以上步骤和注意事项，大多数用户应该能够顺利完成 OpenSourcePOS CI4 版本的安装和配置。如遇特殊问题，建议检查日志文件获取更详细的错误信息以便针对性解决。