配置说明

文档说明

本文档详细指导您完成油站管理系统的各项配置过程。正确的配置设置是系统功能正常运行的关键，请务必按照文档顺序进行操作，确保每个步骤都正确完成。

1. 环境准备

1.1 安装Node.js环境

系统前端功能依赖Node.js环境，请确保正确安装：

组件	最低版本	推荐版本	说明
Node.js	14.0	16.x LTS	提供JavaScript运行环境
NPM	6.0	8.x	Node.js包管理器

版本要求

请确保安装 Node.js 14.0 或更高版本，低版本可能导致前端编译失败或功能异常。

安装步骤：

1. 进入宝塔面板，点击"软件商店"
2. 搜索并安装"Node.js"模块
3. 选择推荐版本进行安装

安装Node环境

1.2 配置环境变量

确保Node.js命令可在全局使用：

1. 安装完成后，系统会自动配置环境变量
2. 如需手动配置，将Node.js安装路径添加到系统PATH环境变量中

设置Node环境变量

安装验证：

# 验证Node.js安装
node --version
# 应显示版本号，如v16.14.0

# 验证NPM安装
npm --version
# 应显示版本号，如8.3.1

性能提示

建议配置国内NPM镜像源，可显著提升依赖包下载速度：

npm config set registry https://registry.npmmirror.com

2. 项目初始化

2.1 安装项目依赖

前端资源需要通过NPM安装并编译：

操作	目的	必要性
安装依赖	获取项目所需的所有前端库	必需
资源编译	生成优化后的前端资源文件	必需

安装命令：

# 进入项目根目录
cd /www/wwwroot/你的站点目录

# 使用npm安装项目依赖
npm install

# 或使用yarn（如果已安装）
yarn install

安装项目依赖

常见问题

• 如遇到权限问题，可尝试使用 sudo npm install
• 如安装过程中断，可使用 npm install --force 强制继续安装
• 安装失败时检查服务器网络连接和Node.js版本

2.2 编译前端资源

安装依赖后，需要编译前端资源：

# 开发环境编译
npm run dev

# 生产环境编译（推荐用于正式部署）
npm run build

自动化部署

对于生产环境，建议配置自动化部署流程：

1. 代码拉取后自动安装依赖
2. 自动执行编译命令
3. 自动重启相关服务

3. 数据库配置

3.1 导入数据库

系统初始化需要导入基础数据：

1. 在宝塔面板中进入"数据库"模块
2. 点击目标数据库的"管理"按钮
3. 选择"导入"选项
4. 上传SQL文件或直接导入已存在的文件：

进入数据库目录

5. 选择数据库文件并点击"导入"：

选择SQL文件

数据备份

执行数据导入前，如数据库中已有数据，请务必先进行备份，避免数据丢失！

3.2 数据库优化设置

针对MySQL数据库的优化建议：

配置项	推荐值	目的
max_connections	200-500	增加最大连接数，应对高并发
innodb_buffer_pool_size	系统内存的50%	提高查询性能
query_cache_size	64M	优化查询缓存
wait_timeout	300	平衡连接资源利用

性能建议

对于高并发场景，建议考虑主从分离部署，将读写操作分离到不同服务器，提高系统整体性能。

4. 系统配置

4.1 环境配置文件

系统核心配置存储在.env文件中：

1. 进入项目根目录：

进入项目目录

2. 找到并编辑.env文件：

打开.env文件

重要提示

• 修改.env文件后需重启PHP服务才能生效
• 请勿在此文件中包含敏感注释
• 保持备份以便恢复

4.2 数据库连接配置

配置系统与数据库的连接参数：

# 数据库连接配置
DB_CONNECTION=mysql     # 数据库类型
DB_HOST=127.0.0.1       # 数据库服务器地址
DB_PORT=3306            # 数据库端口号
DB_DATABASE=youxiaoke   # 数据库名称
DB_USERNAME=your_username # 数据库用户名
DB_PASSWORD=your_password # 数据库密码

参数说明：

参数	说明	默认值	是否必填
DB_CONNECTION	数据库类型	mysql	是
DB_HOST	数据库主机地址	127.0.0.1	是
DB_PORT	数据库端口	3306	是
DB_DATABASE	数据库名称	-	是
DB_USERNAME	数据库用户名	-	是
DB_PASSWORD	数据库密码	-	是

安全警告

数据库密码是系统安全的核心要素：

• 使用强密码（至少12位，包含大小写字母、数字和特殊字符）
• 定期更换数据库密码（建议90天一次）
• 限制数据库用户权限，遵循最小权限原则

4.3 Redis缓存配置

Redis作为系统缓存和队列服务，需要正确配置：

# Redis服务配置
REDIS_HOST=127.0.0.1     # Redis服务器地址
REDIS_PASSWORD=null      # Redis密码，如无密码则保持null
REDIS_PORT=6379          # Redis端口号
REDIS_DB=0               # Redis数据库索引

参数说明：

参数	说明	默认值	是否必填
REDIS_HOST	Redis服务器地址	127.0.0.1	是
REDIS_PASSWORD	Redis访问密码	null	否
REDIS_PORT	Redis服务端口	6379	是
REDIS_DB	使用的数据库索引	0	是

性能优化

Redis配置优化建议：

• 生产环境务必设置密码保护
• 考虑启用Redis持久化功能（AOF或RDB）
• 针对大型部署，可配置Redis集群提高可用性
• 适当配置最大内存和内存策略以避免OOM

4.4 应用基本配置

系统核心配置参数：

# 应用基本配置
APP_DEBUG=false          # 是否开启调试模式
APP_URL=your-domain.com  # 应用访问URL
APP_KEY=您的授权密钥     # 应用密钥

参数说明：

参数	说明	推荐值	环境
APP_DEBUG	调试模式开关	false	生产环境
APP_URL	系统访问地址	your-domain.com	所有环境
APP_KEY	授权通信和验证	系统商发放	所有环境

安全设置

• 生产环境必须设置APP_DEBUG=false，避免泄露敏感信息
• APP_KEY用于加密会话和敏感数据，切勿外泄
• 确保APP_URL配置正确，否则可能导致资源加载错误

4.5 WebSocket服务配置

实时通信服务配置，用于站点数据实时同步：

# WebSocket服务配置
WEBSOCKET_PORT=2348       # WebSocket服务端口
REGISTER_ADDRESS=127.0.0.1:1236 # 注册中心地址
GATEWAY_WORKER_COUNT=1    # 网关工作进程数
GATEWAY_LAN_IP=127.0.0.1  # 内网IP地址
GATEWAY_START_PORT=2000   # 起始端口号
BUSINESS_WORKER_COUNT=4   # 业务工作进程数

参数说明：

参数	说明	推荐值	调优建议
WEBSOCKET_PORT	对外服务端口	2348	确保防火墙开放
GATEWAY_WORKER_COUNT	网关进程数	CPU核心数	高并发时可适当增加
BUSINESS_WORKER_COUNT	业务进程数	CPU核心数x2	处理业务逻辑的进程数

性能调优

• 对于高并发系统，建议增加GATEWAY_WORKER_COUNT值
• 内存充足的情况下，可适当增加BUSINESS_WORKER_COUNT
• 单服务器连接数超过5000时，考虑集群部署方案

4.6 队列服务配置

后台任务队列配置，用于处理耗时操作：

# 队列服务配置
QUEUE_NAME=default          # 队列名称默认就好
QUEUE_DRIVER=redis          # 队列驱动类型
QUEUE_REDIS_HOST=127.0.0.1  # 队列使用的Redis服务器地址
QUEUE_REDIS_PASSWORD=       # 队列使用的Redis密码，如无密码则保持null
QUEUE_REDIS_PORT=6379       # 队列使用的Redis端口号
QUEUE_REDIS_DB=0            # 队列使用的Redis数据库索引

任务队列注意事项

• 确保配置了系统命令中的队列监听服务
• 队列服务异常可能导致数据同步延迟或失败
• 定期检查失败队列以处理异常任务

5. Web服务器配置

5.1 WebSocket代理配置

WebSocket服务需要特殊的Nginx代理配置：

注意事项

正确配置WebSocket代理对于实时通信功能至关重要。确保Nginx版本支持WebSocket代理(1.3.13+)。

配置步骤：

1. 进入Nginx配置目录：

进入Nginx配置目录

2. 编辑站点配置文件，添加WebSocket代理配置：

# WebSocket代理配置
location /wss {
    proxy_pass http://127.0.0.1:2348;  # 配置WebSocket服务端口
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header X-Real-IP $remote_addr;
    
    # 稳定性配置
    proxy_read_timeout 60s;
    proxy_send_timeout 60s;
}

Nginx WebSocket配置

3. 保存配置并重启Nginx服务：

5.3 配置验证

完成配置后，请执行以下验证步骤：

验证项	验证方法	预期结果
网站访问	浏览器访问站点	页面正常加载
HTTPS	查看浏览器地址栏	显示安全锁图标
WebSocket	控制台Network标签	WS连接成功
静态资源	查看页面资源加载	无404错误

验证工具

可使用以下工具进行全面验证：

• Chrome DevTools：检查网络请求和WebSocket连接
• SSL Labs：验证SSL证书配置安全性
• PageSpeed Insights：检查页面加载性能

6. 系统安全配置

6.1 文件权限设置

正确的文件权限是系统安全的基础：

目录/文件	推荐权限	说明
应用目录	755	一般目录权限
配置文件	644	只允许所有者写入
.env文件	600	只允许所有者读写
runtime目录	777	需要写入日志和缓存
public/uploads	777	需要上传文件权限

权限设置命令：

# 设置基本权限
chmod -R 755 /www/wwwroot/your-site
chmod 600 /www/wwwroot/your-site/.env
chmod -R 777 /www/wwwroot/your-site/runtime
chmod -R 777 /www/wwwroot/your-site/public/uploads

6.2 防火墙配置

限制服务器端口访问，提升系统安全性：

端口	服务	访问控制
80	HTTP	允许所有
443	HTTPS	允许所有
3306	MySQL	仅允许内网
6379	Redis	仅允许内网
22	SSH	限制IP访问

安全警告

数据库和缓存服务端口(3306, 6379)不应直接暴露在公网，请务必配置防火墙限制仅内网访问！

7. 故障排除

7.1 常见问题及解决方案

问题现象	可能原因	解决方法
网站无法访问	Nginx配置错误或未启动	检查Nginx状态和错误日志
数据库连接失败	数据库配置错误或服务未启动	验证数据库连接参数和服务状态
WebSocket连接失败	端口未开放或代理配置错误	检查防火墙和Nginx配置
页面样式异常	静态资源编译失败或路径错误	重新执行资源编译或检查URL配置
执行超时错误	PHP执行时间限制过短	增加PHP执行时间限制

7.2 日志位置

系统关键日志位置：

# Nginx访问日志
/www/wwwlogs/your-domain.access.log

# Nginx错误日志
/www/wwwlogs/your-domain.error.log

# PHP错误日志
/www/wwwlogs/php_error.log

# 应用运行日志
/www/wwwroot/your-site/runtime/log/

# Supervisor服务日志
/var/log/supervisor/

故障排查

解决问题时，首先查看相关日志是关键步骤。大多数问题的原因和解决方案都可以从日志中找到线索。

8. 后续步骤

配置完成后，请参考以下文档继续操作：

1. 参照系统命令文档配置后台服务和定时任务
2. 查看管理后台文档了解系统使用方法
3. 定期检查系统运行状态和安全更新