搭建部署教程

推荐使用宝塔面板操作。整套系统由「PHP 服务端 + Vue 管理后台 + uni-app 小程序」三部分组成，全新部署按本文顺序操作即可。

部署顺序总览：配置环境与站点 → 安装服务端（数据库 + 授权激活）→ 发布管理后台 → 配置小程序参数与解析接口 → 修改小程序接口地址并上传 → 配置合法域名与定时任务。

一、环境要求

组件	版本要求	说明
PHP	8.1 及以上（兼容 8.2）	需安装扩展：mysqli、pdo_mysql、mbstring、json、openssl、curl；`shell_exec`、`proc_open`、`flock` 不得被 disable_functions 禁用（授权心跳守护需要）
MySQL	5.7 及以上 / 8.0	字符集 utf8mb4，安装前先建好空数据库
PHP CLI	与 Web 端同版本	Linux 下需可用 `nohup` 以 PHP CLI 方式执行命令（堡塔防入侵需放行 www 用户）
Composer	2.x	安装/升级依赖时使用
Web 服务	Nginx（推荐）/ Apache	需支持伪静态与 HTTPS
SSL 证书	必须 HTTPS	微信小程序合法域名强制要求 HTTPS

二、宝塔创建站点与数据库

登录宝塔面板，进入「网站 → 添加站点」，填写已备案的域名，PHP 版本选择 8.1。
同步创建 MySQL 数据库（utf8mb4），记录好数据库名、用户名与密码。
在站点设置中进入「SSL」，申请 Let's Encrypt 免费证书并强制 HTTPS。
上传后端源码（qushuiyinadmin 目录全部文件）到站点目录。

域名必须已完成 ICP 备案，否则无法配置为微信小程序的 request / downloadFile 合法域名。

三、设置运行目录与伪静态

这是 ThinkPHP 8 部署最关键的一步，两项都在站点设置里完成：

网站运行目录设置为 public（ThinkPHP 8 统一入口，app 等目录不得暴露到 Web）。
伪静态选择 thinkphp 规则；Nginx 等价配置如下：

location / {
    if (!-e $request_filename) {
        rewrite ^(.*)$ /index.php?s=$1 last;
    }
}

如服务器未执行过依赖安装，先在项目根目录执行：

composer install

四、浏览器安装向导

环境扩展装好、数据库建好后，访问 https://你的域名/install.php，在同一张表单里填好数据库参数、超管账号和授权码，点击「点击安装并激活」即可一次完成，无需把任何信息发给授权方。

1. 环境检测（页面左侧，全部通过才能安装）

向导会自动逐项检测，任一项不通过请按提示在宝塔中调整后刷新：

未安装过（app/install/install.lock 不存在）；
PHP 版本 ≥ 8.0；
MySQLi 扩展、OpenSSL 扩展、cURL 扩展均已开启；
shell_exec、proc_open、flock 未被 disable_functions 禁用，并通过命令执行冒烟测试；
Linux 环境下 nohup + PHP CLI 可被站点运行用户（www）执行；若开启了堡塔防入侵（Nginx 防火墙），需在计划任务白名单中放行；
项目根目录、app/install、data 目录可写。

2. 填写安装参数（页面右侧）

数据库信息：数据库地址（默认 127.0.0.1）、端口（默认 3306）、库名、用户名、密码（本机无密码可留空）。数据库需提前在宝塔中创建为空白库（默认建议命名 qushuiyin），向导只建表不建库。
平台超级管理员：账号 3–12 位字母/数字/下划线（如 admin），密码 6–16 位且两次输入一致，用于登录平台后台。
授权信息：授权环境选择「生产环境」（默认推荐；开发调试才选开发环境）；授权码（格式 QSY-XXXX-XXXX-XXXX）提前向服务商购买获取，直接粘贴即可。
机器指纹：表单中的只读参考项，由本机主机名与网卡 MAC 自动生成，正常安装无需复制或发送给任何人；仅在日后需要换机、追加绑定机器时，把它提供给服务商处理。

3. 一键安装并激活

点击「点击安装并激活」后，系统自动按顺序执行：先联网校验并激活授权码（激活通过才会继续）→ 连接数据库 → 写入根目录 .env 配置 → 创建全部数据表并初始化默认租户、平台配置与超管账号 → 拉起授权心跳常驻守护 → 写入安装锁 app/install/install.lock，页面提示「安装成功，授权已激活」即完成。

若检测到数据库中已存在本系统的数据表，页面会橙色提示表名与行数，勾选确认覆盖后按钮变为「确认覆盖并激活」再提交；勾选覆盖会清空这些表中的旧数据，请谨慎操作。

安装成功后请立即删除 public/install.php，避免被重复访问。

五、发布管理后台

管理后台为独立的 Vue3 + Vite 工程（qushuiyin-admin-vue），本地构建后发布到后端：

pnpm install
pnpm dev      # 本地开发，默认 http://localhost:3000
pnpm build    # 产物输出到 dist/

将 dist/ 目录内的全部文件上传到后端站点根目录的 public/ 下。
访问站点根路径，服务端会自动跳转后台登录页。
后台使用 hash 路由，部署在子目录也无需改写路由。

六、后台配置小程序参数与解析接口

使用安装时设置的平台超管账号登录后台，新增/进入商户后台后完成：

小程序配置（必填）：填写小程序 AppID 与 Secret（在 mp.weixin.qq.com 获取），系统据此识别租户并完成登录态换取。
解析接口：在接口管理中录入第三方聚合解析接口地址，并按接口返回结构配置 video / pics / cover / title / desc / audio / lives / subtitles 等字段映射；可配置多个接口按排序轮询。
运营配置：会员套餐、积分规则、广告位、客服、首页 DIY 等按需配置。
虚拟支付（可选）：填写 OfferID、AppKey、推送 Token、AESKey 与道具映射，详见后台虚拟支付设置页。

七、小程序端配置与上传

交付包内已附带编译好的微信小程序产物，产品不支持二次开发，无需也无法使用 HBuilderX 自行编译，只需把产物中的接口占位域名替换为你的后端域名即可发布：

打开已编译好的 unpackage/dist/build/mp-weixin/common/vendor.js。
按 Ctrl + F 搜索「你的域名」，替换为实际后端域名（必须 https），保存。
用微信开发者工具导入 unpackage/dist/build/mp-weixin 目录，填好小程序 AppID，选择「不使用云服务」。
在微信开发者工具右上角点击「上传」，再到小程序管理后台提交审核发布。

八、配置微信合法域名

小程序发布前必须在微信公众平台配置服务器域名：request 合法域名 与 downloadFile 合法域名 都要加入后端域名，且全部要求 HTTPS。详细操作与常见报错见微信合法域名配置。

九、配置定时任务

使用虚拟支付时必须配置对账任务；授权心跳在安装激活成功后已由系统自动拉起常驻守护进程、并随后台访问自动触发，无需额外配置计划任务。在宝塔「计划任务」或 crontab 中添加：

# 虚拟支付兜底查单 / 补发货：建议每 5 分钟（使用虚拟支付时必配）
*/5 * * * * cd /www/wwwroot/你的项目目录 && php think vpay:reconcile

# 授权心跳兜底（可选）：仅当服务器禁用了常驻进程、守护无法运行时才需要
30 3 * * * cd /www/wwwroot/你的项目目录 && php think license:heartbeat

对账任务会扫描近 2 小时创建、满 2 分钟仍未终态的订单（每轮最多 200 单），主动向微信查单并补发或关单，兜住发货推送丢失的情况。可随时用 php think license:heartbeat --status 查看授权状态与守护进程运行情况。

遇到用户「扣款但长时间未发货」，可先在服务器手动执行一次 php think vpay:reconcile 立即补单。

十、版本升级命令

覆盖新版代码后，按升级说明执行对应命令，两者均为幂等，可重复执行：

php think saas:upgrade    # SaaS 底座升级：租户表、tenant_id 字段、索引等
php think vpay:upgrade    # 虚拟支付升级：vpay_order 表与默认配置种子

部署支持

部署过程中遇到问题可联系作者协助；购买系统、授权码、搭建同款或代部署也可直接咨询（请说明来意）：微信 idcxsy，QQ 522605223。线上演示可在微信搜索小程序「聚合一键去水印」体验。