宝塔面板部署说明

本文以宝塔 Linux 面板（nginx）为例，给出从建站到上线的完整步骤与安全加固建议。

一、准备

项目	建议
PHP	8.2（8.0+ 均可），需 `pdo_mysql`、`curl`、`openssl`、`mbstring`、`gd`
数据库	MySQL 5.7 / 8.0
站点目录	`/www/wwwroot/your-domain`

宝塔「软件商店」确认已安装 PHP 与 MySQL；PHP 扩展可在「PHP → 设置 → 扩展」中检查。

二、上传代码

面板 →「网站」→「添加站点」，填域名，PHP 版本选 8.2，不建 FTP、不建数据库（下一步单独建）。
把项目文件全部上传到站点根目录，确保 index.php、includes/、admin/ 在根目录下。
设置目录属主与权限：

cd /www/wwwroot/your-domain
chown -R www:www .
find . -type d -exec chmod 755 {} \;
find . -type f -exec chmod 644 {} \;
chmod -R 755 runtime

runtime/ 需要写权限（SQLite 数据文件、授权缓存、cron 日志）。

三、创建数据库

面板 →「数据库」→「添加数据库」：

数据库名：如 youxiang_finance
用户名 / 密码：按面板生成（密码请自行妥善保管）
访问权限：本地服务器（不要开所有人）

数据库不需要手动导入，安装向导会自动建表。

四、执行安装

浏览器访问：

https://your-domain/install/install.php

驱动选 MySQL，填入上一步的库名 / 账号 / 密码
若该账号无建库权限，请手动在面板建库
填管理员账号（≥3 位）与密码（≥8 位）
选择初始版本：普惠版 / 专业版 / 企业版

提交后出现「安装完成」，即完成 21 张表与默认数据写入。

五、安装后立即做的三件事

1. 限制 install 目录访问

宝塔 →「网站 → 你的站点 → 配置文件」，在 server {} 内加入：

# 安装完成后禁止访问安装向导
location ^~ /install/ {
    deny all;
    return 404;
}

# 保护敏感目录
location ^~ /runtime/ {
    deny all;
    return 404;
}
location ^~ /includes/ {
    deny all;
    return 404;
}
location ^~ /tools/ {
    deny all;
    return 404;
}
location ^~ /docs/ {
    deny all;
    return 404;
}
location ^~ /cache/ {
    deny all;
    return 404;
}

# 隐藏点文件与备份文件
location ~ /\.(?!well-known) {
    deny all;
}
location ~* \.(sql|db|log|bak|ini)$ {
    deny all;
}

保存后执行 /www/server/nginx/sbin/nginx -t && /www/server/nginx/sbin/nginx -s reload 重载。

注意：宝塔的站点模板默认已拦截 runtime/ 目录与 .env / .sql / .log / README.md 等敏感文件，但不会拦截 includes/、tools/、docs/，需按上面手工补上。另外请勿删除站点根目录的 404.html 与 favicon.ico：前者是 nginx error_page 404 的落地文件，缺失会导致每次 404 都写入错误日志；后者可避免浏览器自动请求 /favicon.ico 产生 404。

2. 关闭调试模式并保护配置文件

编辑 includes/config.php：

'app' => [
    ...
    'debug' => false,   // 生产环境必须为 false
],

同时确认 includes/config.php 权限为 644、属主 www:www（写权限的窗口期仅在安装时）。

3. 配置 HTTPS

宝塔 →「网站 → SSL」→ 申请 Let's Encrypt 或上传证书 → 开启「强制 HTTPS」。

六、配置定时任务

面板 →「计划任务」→ 添加：

任务类型：Shell 脚本
任务名称：优享财务系统 - 到期与续费
执行周期：每 5-10 分钟
脚本内容：

php /www/wwwroot/your-domain/tools/cron.php --token=你的任务令牌

「你的任务令牌」在后台 系统设置 → 定时任务 → 生成任务令牌 获取。

若服务器 PHP 不在默认 PATH，请用绝对路径，例如宝塔 PHP：

/www/server/php/82/bin/php /www/wwwroot/your-domain/tools/cron.php --token=xxxx

本任务不只是"可选优化"，而是必需品：cron 每次会执行

到期业务标记
自动续费（需在系统设置开启 auto_renew）
执行异步任务队列（上游开通 / 续费 / 开关机 / 重装 / 销毁、下游事件回调，含失败退避重试）
清理过期接口 nonce、接口日志与历史任务
授权巡检

未配置计划任务时：客户付款后业务会一直停留在「待开通」，上游不会收到开通请求，下游也收不到事件回调。

六之二、代码升级与数据库迁移

更新代码后（覆盖文件时不要覆盖 includes/config.php 与 runtime/），执行：

cd /www/wwwroot/your-domain

# 1) 先备份数据库
cp -a runtime/youxiang.db /root/youxiang.db.$(date +%Y%m%d%H%M%S)   # SQLite
# MySQL 请用面板「数据库 → 备份」或 mysqldump

# 2) 查看将要执行的变更
php tools/upgrade.php --dry-run

# 3) 正式升级（只建缺失表 / 补缺失列与索引，不删列不删表）
php tools/upgrade.php

# 4) 收回权限
chown -R www:www runtime && chmod 600 runtime/youxiang.db

# 5) 自检
php tools/selftest.php

也可用浏览器访问 tools/cron.php 触发升级（需带 ?token= 任务令牌）。注意 nginx 默认已拦截 /tools/，如需 URL 触发请单独放行该文件。

七、支付通道配置

后台 →「系统设置」填写：

配置项	说明
支付网关地址	如 `https://pay.example.com`（不含 `/mapi.php`）
支付商户号（pid）	网关分配的商户号
支付商户密钥（key）	网关分配的密钥；留空表示不修改，页面不会回显已保存的值

回调地址（在网关后台填写）：

https://your-domain/api/pay_notify.php

签名规则为「参数排序拼接 + 追加密钥 → MD5」（易支付 / 聚合码通用协议）。若你的通道协议不同，只需修改 includes/payment.php 中的 yx_pay_sign() 与 YxPayment::buildSubmitForm()。

未配置通道时，充值页会退回线下汇款流程，由管理员在后台「订单管理 → 线下收款」标记到账并自动入账。

八、授权中心对接

场景 A：本站作为被授权方

后台 →「系统设置 → 官方授权服务器地址」填写授权中心地址（如 https://license.example.com），保存后自动按域名校验。「授权中心」页面可看到当前域名结论、结果来源与到期时间，也可随时「立即复核」。

场景 B：本站作为授权中心

把系统部署在授权域名上，后台「版本与模块」切换到企业版。
「授权中心」→ 新增授权记录（域名 / 版本 / 到期日 / 状态），或使用「按域名签发授权码」生成授权码。
对外查询接口：

GET https://license.example.com/api/license.php?domain=客户域名

若需签名校验，在 includes/config.php 的 license.channel_secret 填入共享密钥（客户端 sign = HMAC-SHA256("domain=..&ts=..&version=..", secret)）。

九、Logo 生成

cd /www/wwwroot/your-domain
php tools/gen_logo.php

产出在 assets/logo/。若服务器没有中文字体，横版位图会自动跳过；可安装字体后重跑，或指定字体：

# 安装中文字体（CentOS）
yum install -y wqy-microhei-fonts

# 或指定已有字体
php tools/gen_logo.php --font=/usr/share/fonts/truetype/wqy/wqy-microhei.ttc

然后在后台「系统设置」中可改系统名称，Logo 文件可直接替换 assets/logo/ 下的同名文件。

十、上线前自检清单

cd /www/wwwroot/your-domain

# 1) 语法检查
find . -name '*.php' -print0 | xargs -0 -n1 php -l

# 2) 端到端自检（使用独立临时库，不影响正式数据）
php tools/selftest.php

人工确认：

☐ 访问 /install/install.php 已返回 404（安装目录已封闭）
☐ includes/config.php 中 debug = false
☐ /runtime/、/includes/、/tools/ 无法通过浏览器访问
☐ 全站已开启 HTTPS 且强制跳转
☐ 后台密码已改为强密码；管理员账号不是 admin
☐ 后台「授权中心」显示「域名已正版授权」（或已知悉未授权状态）
☐ 支付通道下单 → 回调 → 余额到账全流程实测一次
☐ 计划任务已添加且 runtime/cron.log 有执行记录
☐ 数据库已开启定期备份（宝塔「计划任务 → 备份数据库」）

十一、备份与迁移

内容	路径
MySQL 数据	面板「数据库 → 备份」，或 `mysqldump`
SQLite 数据	`runtime/youxiang.db`（连同 `-wal`、`-shm`）
上传/附件	本项目未内置上传目录；如有自行新增，请一并备份
配置	`includes/config.php`（含数据库密码与 `app.key`）

迁移注意：app.key 必须一并迁移，否则已加密存储的业务登录密码、节点密钥将无法解密。

十二、常见问题

Q：安装时提示数据库连接失败？ A：核对库名/账号/密码；确认已在宝塔把该库的访问权限设为「本地服务器」；MySQL 端口是否为 3306。

Q：后台某些菜单点进去跳回仪表盘？ A：该功能超出当前版本能力。到「版本与模块」切换版本，或查看功能对照表中「当前可用」列。

Q：页面一直显示「域名未在官方授权」？ A：这是正常的未授权提示。可在「授权中心」新增本站域名的授权记录，或把「官方授权服务器地址」指向你的授权中心。如需未授权时限制功能，开启「系统设置 → 未授权时强制收敛为普惠版」。

Q：改成 MySQL 后想换回 SQLite？ A：重新运行安装向导，驱动选 SQLite 并指定数据文件路径即可（原 MySQL 数据不会被删除）。

Q：充值后余额没变？ A：检查支付通道是否配置、网关回调是否可达（api/pay_notify.php）、回调验签是否通过（后台「操作日志」中有 pay.notify_reject 记录即为验签失败）。未配置通道时请用后台「订单管理 → 线下收款」人工入账。