# shuiyin

**Repository Path**: mo3408/shuiyin

## Basic Information

- **Project Name**: shuiyin
- **Description**: 一套开箱即用的短视频 / 图集去水印解析站点，支持 18 个主流平台的无水印视频与图集解析，内置会员套餐、在线支付、余额系统、后台管理与数据库备份恢复，前后台界面完善，可直接上线运营。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: http://new.snowytime.cn
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-05
- **Last Updated**: 2026-10-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 全网去水印系统

一套开箱即用的**短视频 / 图集去水印解析站点**，支持 18 个主流平台的无水印视频与图集解析，内置会员套餐、在线支付、余额系统、后台管理与数据库备份恢复，前后台界面完善，可直接上线运营。

- **技术栈**：纯 PHP 8.0–8.5（零 Composer 依赖）+ MySQL 5.7+/8.0 + Layui 2.13.9 + wangEditor v5 / UEditorPlus
- **部署形态**：单站点，运行目录即项目根（不是 `public` 子目录）
- **授权方式**：自用/二开随意，请遵守目标平台的服务条款，勿用于违法用途

---

## 目录

- [功能特性](#功能特性)
- [支持的环境](#支持的环境)
- [安装步骤](#安装步骤)
  - [方式一：网页向导安装（推荐）](#方式一网页向导安装推荐)
  - [方式二：命令行安装](#方式二命令行安装)
  - [安装后收尾](#安装后收尾)
- [伪静态与部署配置](#伪静态与部署配置)
- [目录结构](#目录结构)
- [后台管理](#后台管理)
- [插件体系](#插件体系)
- [支持的解析平台](#支持的解析平台)
- [常见问题 FAQ](#常见问题-faq)
- [安全建议](#安全建议)

---

## 功能特性

### 解析能力
- **18 个平台**的无水印视频 / 图集解析（见下方[平台清单](#支持的解析平台)）
- **自研解析优先 + 三方接口回落**：平台改版时自动走备用通道，无需停服
- **多级备用解析地址**：每个解析器可配置多条 fallback API（一行一个，依次尝试）
- 解析结果含：无水印视频直链、图集原图、封面、标题、作者、背景音乐

### 会员与支付
- 套餐体系：体验 / 周卡 / 月卡 / 季卡 / 年卡 / 永久 / 次数包（10000 次）
- **套餐展示三页同源，样式永远一致**：个人中心「升级会员」与「会员套餐」页均按**会员类型选项卡**切换（会员时长 / 次数包 / 组合套餐，数量角标实时统计）；首页套餐区为**横向轮播**（左右翻页 + 圆点指示 + 4.5 秒自动播放，鼠标悬停 / 触摸时暂停，内容不足一屏自动隐藏控件）
- 三处共用同一份数据（`app/common/library/PlanService.php`）与同一张卡片模板（`themes/default/public/plan_card.html`），改样式只需改这两处
- 用户余额系统：充值、消费、流水记录，扣款与发权益同事务（行锁保护）
- 支付网关插件化：易支付（epay）、码支付（mpay）、余额支付（balance），一个网关可展开多个收银台渠道（微信 / 支付宝 / QQ 钱包）
- 支付回调全量校验：签名 + 金额一致性 + 订单状态幂等

### 后台管理
- 仪表盘、用户管理、会员套餐、订单管理、解析记录、插件管理、系统配置
- **数据库管理**：一键备份 / 恢复 / 下载 / 删除 SQL 备份文件（存于 `data/backup/`）
- 插件管理按类型分选项卡：解析器插件 / 支付插件 / 通用插件
- 基于角色的权限（`admin_group.rules`，`*` = 超级管理员），按钮级接口校验
- 短信三渠道（阿里云 / 腾讯云 / 通用网关），**设置页按渠道选项卡切换**，各渠道参数相互独立
- **账号头像**：个人资料页可上传头像（≤5MB），顶栏实时展示，留空回落昵称首字
- **会员新增/编辑**：按「基本信息 / 会员权益 / 状态与备注」分组卡片呈现，含头像上传、余额-积分-次数指标网格
- **富文本编辑器**：wangEditor v5 / UEditorPlus 工具栏均为**吸顶固定**，长表单滚动时不随页面移动
- 邮件系统：SMTP 发信（SSL 465 / STARTTLS 587 / 明文 25），后台**一键测试发送**（发送后 60 秒防轰炸倒计时）；前台验证码发送后自动进入 60 秒重发倒计时
- 邮箱模版三场景（登录 / 注册 / 找回密码）：**三套内置样式可选**（卡片风格 / 简约清爽 / 品牌渐变，默认卡片）+ **实时预览**；占位符支持站点名称、用户名、邮箱、验证码、有效期、发送时间，可一键应用所选样式默认正文
- **安全设置**：自定义后台登录入口（设置后登录页仅可通过 `/admin/login/index?entry=入口名` 访问，验证通过后同一浏览器 7 天内免带参数，其余访问一律 404）

### 前台
- 响应式界面，支持批量解析、解析历史（登录用户）
- **登录/注册页可扩展第三方登录**：插件通过 `user_login_extra` / `user_register_extra` / `user_profile_extra` 钩子注入入口，当前已内置**微信公众号扫码登录与账号绑定**（见「微信公众号登录」小节）
- **会员头像**：个人中心「资料设置」可直接上传/更换头像（jpg/png/gif/webp，≤2MB），侧栏与前台同步展示，留空回落昵称首字
- **移动端适配**：表格窄屏横向滚动、长内容断行、小屏顶栏自动换行，无页面级横向滚动条
- 富文本编辑器可切换：wangEditor v5 / UEditorPlus
- 平台图标自动识别（图片 / 字体图标 / 首字兜底）

---

## 支持的环境

| 项目 | 要求 | 说明 |
|---|---|---|
| PHP | **8.0.0 – 8.5.x** | 最低 8.0；≥ 8.6 安装向导会警告（未充分测试） |
| MySQL | 5.7+ / 8.0（字符集 utf8mb4） | 数据库不存在时安装向导会自动创建 |
| Web 服务器 | Nginx / Apache / PHP 内置服务器 | 伪静态规则见下文 |
| 操作系统 | Linux / Windows / macOS 均可 | 生产环境建议 Linux + 宝塔或 Docker |

**必需 PHP 扩展**（安装向导第一步会逐项检测）：

| 扩展 | 用途 |
|---|---|
| pdo / pdo_mysql | 数据库 |
| curl | 远程请求（解析必需） |
| json | JSON 处理 |
| mbstring | 多字节字符串 |
| openssl | 加密与 HTTPS |

**建议开启的可选扩展**：

| 扩展 | 用途 |
|---|---|
| gd | 图片处理（缩略图、二维码） |
| fileinfo | 上传文件类型嗅探 |
| zip | 后台插件上传安装 |

**目录权限**：以下目录需要 Web 运行用户**可写**：

- `data/`（缓存、备份、运行数据）
- `uploads/`（用户上传）
- `config/`（安装向导写入数据库配置）

---

## 安装步骤

### 方式一：网页向导安装（推荐）

1. **上传代码**
   把整个项目上传到站点目录（如 `/www/wwwroot/shuiyin`），确认：
   - 网站运行目录 = **项目根目录**（`index.php` 所在处，不要指向 `public/`）
   - 已配置伪静态（见[下文](#伪静态与部署配置)）

2. **访问安装向导**
   浏览器打开 `http://你的域名/install/`，向导共 4 步：
   1. **环境检测** —— 自动检查 PHP 版本、必需扩展、目录可写性，全部通过后才能下一步
   2. **配置信息** —— 填写数据库地址 / 端口 / 用户名 / 密码 / 库名 / 表前缀，以及**管理员账号密码**（请勿使用默认弱口令）
   3. **执行安装** —— 自动建库（utf8mb4）、导入 `install/install.sql` 与初始数据、创建管理员、注册并启用插件
   4. **安装完成** —— 展示后台入口

3. **登录后台**
   访问 `http://你的域名/admin/login/index`，用第 2 步设置的管理员账号登录。
   （本地调试默认库连接参考：host `127.0.0.1`，库名随意，表前缀 `sy_`）

### 方式二：命令行安装

适合无浏览器环境或批量部署：

```bash
php install/cli-install.php          # 交互式引导，自动完成建库 + 导数据 + 管理员
php install/cli-plugins.php          # 安装收尾后补注册插件
php install/cli-plugins.php --force  # 强制重装（重置插件配置）
```

> 安装向导收尾会自动执行插件注册（`install/plugin-setup.php`），正常流程无需手动跑 `cli-plugins.php`。

### 版本升级（覆盖代码后）

用新版本覆盖了旧代码、但数据库还是老结构时，跑一次升级脚本即可：

```bash
php install/cli-upgrade.php          # 应用缺失的结构变更
php install/cli-upgrade.php --dry    # 只预览将要执行什么，不落库
```

脚本是**幂等**的：按 `INFORMATION_SCHEMA` 判断现状，只补差量，重复执行安全，也不会重建表或丢数据。升级完成后同样要删除 `install/` 目录。

### 安装后收尾

- ⚠️ **务必删除 `install/` 目录**——伪静态规则虽然拦截了直接访问，但物理删除才是唯一保险
- 登录后台 → 系统配置，核对站点名称、解析回落接口等配置
- 配置支付网关（后台 → 插件管理 → 支付插件）后再开放充值功能

---

## 伪静态与部署配置

系统把入口 `index.php`、静态资源 `static/`、上传目录 `uploads/` 统一放在**项目根目录**，因此无需把运行目录指到子目录。

### Nginx

把 `docs/nginx.conf` 中的 `server` 块整体贴入站点配置（宝塔：站点设置 → 配置文件）。要点：

```nginx
root  /www/wwwroot/shuiyin;          # 指向项目根目录
index index.php index.html;

location / {
    try_files $uri $uri/ /index.php$is_args$args;
}

location = /index.php {
    include        fastcgi_params;
    fastcgi_param  PATH_INFO $uri;
    fastcgi_param  SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_pass   127.0.0.1:9000;   # 按实际 PHP-FPM 监听改（宝塔常见 unix:/tmp/php-cgi-80.sock）
}

# 代码目录 / 配置 / 运行数据 / 安装程序 一律拒绝
location ~ ^/(app|core|config|data|plugins|themes|install)/ { deny all; return 404; }

# 敏感文件（.sql/.md/.log/.bak 等）拒绝下载
location ~* \.(sql|md|lock|ini|log|bak)$ { deny all; return 404; }
```

### Apache

项目根目录已自带 `.htaccess`（所有请求转发到 `index.php` + 拦截敏感目录/文件），确保：

- 开启了 `mod_rewrite`，且 `AllowOverride All`
- 若在子目录部署，检查 `.htaccess` 中的 `RewriteBase`

### 伪静态与功能的对应关系

系统所有后台功能（含邮件测试发送端点 `/admin/config/testmail`、数据库管理等）都运行在 `/admin` 前缀下，前台为常规路由，**默认规则已全部覆盖**，无需为新增功能追加放行规则。若后续二开新增了以下情况，需同步更新 `docs/nginx.conf` 与 `.htaccess` 并在本文档登记：

1. 新增了**独立入口脚本**（类似 `install/`）→ 加入拦截列表；
2. 新增了**对外暴露的静态资源目录**（类似 `static/`、`uploads/`）→ 确保不被 `deny` 规则误拦；
3. 新增了插件带自己的**公开回调/资源路径** → 同步两个规则文件。

**已登记的前台公开路由**（均走 `index.php` 常规路由，无需额外规则）：

| 路由 | 用途 | 说明 |
|---|---|---|
| `/home/upload/avatar` | 会员头像上传 | POST，仅登录会员可用，图片 ≤ 2MB，落盘 `uploads/avatar/YYYY/mm/dd/` |
| `/admin/upload/index` | 后台统一上传 | POST，`type=image/video/audio/file`，同时兼容 UEditor 协议 |

### PHP 内置服务器（本地开发）

```bash
php -S 127.0.0.1:8899 -t . data/tmp/dev-router.php
```

> 调试模式：环境变量 `SY_DEBUG=1` 会输出详细错误；生产环境**务必关闭**。

---

## 目录结构

```
shuiyin/
├── index.php              # 唯一入口
├── .htaccess              # Apache 伪静态
├── app/                   # 应用代码（三段式）
│   ├── home/              #   前台控制器与视图逻辑
│   ├── admin/             #   后台控制器（含 database.php 数据库备份恢复）
│   └── common/            #   公共库
├── core/                  # 框架内核（bootstrap.php / Db.php / Parser.php / Plugin.php …）
├── plugins/               # 插件目录（每个插件 = plugin.json + Plugin.php）
├── themes/                # 视图模板（含 themes/admin 后台主题）
├── config/                # 数据库等配置（安装向导写入）
├── data/                  # 运行数据（缓存、backup/ 数据库备份、tmp/）
├── static/                # 静态资源（css/js/img，平台图标在 static/img/platform/）
├── uploads/               # 用户上传
├── install/               # 安装向导（装完删除！）
└── docs/                  # nginx.conf 部署参考
```

---

## 后台管理

入口：`http://你的域名/admin/login/index`

| 模块 | 说明 |
|---|---|
| 仪表盘 | 站点概览、解析量统计 |
| 用户管理 | 用户列表、余额调整、会员状态 |
| 会员套餐 | 套餐价格 / 时长 / 次数配置 |
| 订单管理 | 支付订单查询、补单处理 |
| 解析记录 | 全站解析流水 |
| 插件管理 | 按类型分选项卡：解析器 / 支付 / 通用；在线启停与配置 |
| 数据库管理 | 一键备份、恢复、下载、删除备份文件（`data/backup/`） |
| 系统配置 | 站点信息、短信/邮箱渠道、解析回落接口等 |

权限说明：管理员分组 `rules` 字段为 `*` 即超级管理员；普通分组按规则串控制，按钮级权限在接口层二次校验。

---

## 插件体系

插件位于 `plugins/<name>/`，每个插件必须包含 `plugin.json`（元信息 + `type`/`sort`/`fallback`/`default_enabled`）和 `Plugin.php`（主类 `plugins\<name>\Plugin`）。

| 类型 | 插件 | 说明 |
|---|---|---|
| 解析器 parser | douyin / kuaishou / xiaohongshu / bilibili / weibo / pipixia / pipigx / izuiyou / weishi / toutiao / ixigua / haokan / huoshan / channels / youtube / doubao / jimeng / qianwen | 各平台本地解析；非 fallback 解析器安装时自动启用 |
| 三方回落 parser | thirdparty | 公开解析接口池，本地解析失败时的兜底渠道 |
| 支付 pay | epay（易支付）/ mpay（码支付）/ balance（余额） | 收银台渠道来源 = 后台已启用的支付插件 |
| 编辑器 general | wangeditor / ueditorplus | 前后台富文本编辑器，可切换 |
| 登录扩展 general | wechatmp（微信公众号） | 关注公众号 / 发送验证码口令登录，支持个人订阅号 |

**解析回落机制**：本地解析失败 → 依次尝试该插件 `fallback_api` 配置的多个三方接口（每行一个 URL 模板，`{url}` 占位符）→ 全部失败才报「暂不支持」。

### 微信公众号登录（wechatmp 插件）

以插件方式接入公众号，实现「关注即登录」与「发送验证码口令登录」两条通道，并支持**已注册会员绑定微信**。

**前台入口**（全部为页面内联面板，不使用遮罩弹窗）

| 位置 | 表现 |
|---|---|
| 登录页 | 表单**上方**的「账号密码登录 / 微信扫码登录」切换栏，默认停在账号密码；切到扫码后表单隐藏、二维码面板原地展开 |
| 注册页 | 表单下方「微信扫码登录 / 注册」按钮，点击就地展开二维码面板 |
| 个人中心 → 资料设置 | 「微信绑定」卡片：未绑定时展示二维码，绑定成功后展示状态与「解除绑定」按钮 |

> 绑定后可直接用微信扫码登录，无需再输入账号密码；解绑后 `openid` 置为 `NULL`（未绑定会员可以有任意多个）。

**启用步骤**

1. 后台「插件管理 → 通用插件」确认 `wechatmp` 已安装启用（全新安装默认启用）；
2. 「插件设置 → 微信公众号登录」填写：公众号 AppID / AppSecret、服务器 Token（自定义串）、回调地址；
3. 微信公众平台「设置与开发 → 基本配置 → 服务器配置」把 URL 填为该回调地址（形如 `https://你的域名/home/wechatmp/callback`），Token 与后台一致；**消息加解密方式推荐选「明文模式」**（最省事）。若选了「兼容模式 / 安全模式」，必须同时把平台生成的 **EncodingAESKey**（43 位）填进后台插件设置，否则用户给公众号发口令时收不到任何回复；
4. 按需填写「固定二维码图片」（关注引导图），并开启「关注即登录」/「验证码口令登录」开关。

> **消息加解密方式（重要）**：插件三种模式都支持 —— 明文模式直接解析 XML；兼容 / 安全模式
> 下微信推送的是 `<Encrypt>` 密文，插件会自动识别并解密，被动回复也自动加密回包。
> 判定**以报文内容为准**（不依赖 URL 上的 `encrypt_type` 参数），避免混合下发时被误判。
> 若选了安全模式却漏填 EncodingAESKey，站点会写入明确日志，并让登录面板直接提示「配置异常」，
> 不会再出现「发了消息毫无反应」这种情况。

**公众号类型**（设置项「公众号类型」，决定可用通道）

| 类型 | 带参二维码 | 可用登录通道 |
|---|---|---|
| 个人订阅号（未认证） | 不支持 | **仅「发送验证码口令」**：引导用户关注后发送站点给出的 6 位口令 |
| 已认证订阅号 / 服务号 / 测试号 | 支持 | 扫码即登录（关注事件）+ 发送口令，双通道 |

**关键配置项**

| 配置 | 说明 |
|---|---|
| 关注即登录 | 用户扫带参二维码并关注 → 事件推送 → 自动登录 |
| 验证码口令登录 | 用户关注后发送站点显示的 6 位口令 → 被动回复确认 → 自动登录 |
| 自动注册 | 关闭时，未注册的微信用户扫码只提示「请先注册并绑定」，不自动建号 |
| 固定二维码图片 | 未配置 AppID/Secret 或使用个人订阅号时展示的关注引导图 |

> **安全**：跳转只允许站内相对路径（`safeRedirect()`）；登录票据（`scene`）10 分钟过期且一次性消费；
> 绑定票据额外记录发起绑定时的会员 ID，轮询时必须与当前登录态一致，票据被挪用也无法绑到他人账号；
> 解绑接口要求已登录且当前账号确有绑定；回调走签名校验（`sha1(sort(token,timestamp,nonce))` + `hash_equals`），
> GET 请求原样回显 `echostr` 完成微信服务器验证。
> 插件**不新建数据表**，微信 `openid` 复用会员表的 `openid` 唯一列（未绑定时为 `NULL`）。

---

## 支持的解析平台

| 平台 | 支持内容 | 平台 | 支持内容 |
|---|---|---|---|
| 抖音 | 视频 / 图集 | 微视 | 视频 |
| 快手 | 视频 / 图集 | 今日头条 | 视频 / 图集 |
| 小红书 | 视频 / 图集 | 西瓜视频 | 视频 |
| B 站 | 视频 | 好看视频 | 视频 |
| 微博 | 视频 / 图集 | 火山小视频 | 视频 |
| 皮皮虾 | 视频 / 图集 | 微信视频号 | 视频 |
| 皮皮搞笑 | 视频 / 图集 | YouTube | 视频 |
| 最右 | 视频 / 图集 | 豆包 | 视频 |
| 即梦 AI | 视频 | 千问 | 视频 |

> 平台支持范围以后台「解析器插件」实际启用情况为准；启停某个解析器后，前台平台列表自动同步。
> 微信视频号支持 `channels.weixin.qq.com` 全部链接形态（`/web/feed/`、`feed_id=`、`/finder/`）；其内容受微信登录态保护，本地通道仅能提取元数据，视频直链依赖「备用解析地址」（后台可换自购接口）。
> 最右支持 `share.izuiyou.com` / `share.xiaochuankeji.cn` / `m.izuiyou.com` / `ixiaochuan.cn` / `zuiyou.tv` 全部链接形态（短链自动跟随）；带查询参数的链接（如 `?pid=`、`?v=`、`?id=`）均完整识别。

---

## 常见问题 FAQ

**Q1：访问首页 404 / 所有页面都 404？**
伪静态未配置或配置错误。检查：Nginx 的 `try_files ... /index.php$is_args$args` 是否生效；运行目录是否指向项目根而不是 `public/`；Apache 是否开启 `mod_rewrite` 且 `AllowOverride All`。

**Q2：安装向导第一步「目录不可写」？**
给 `data/`、`uploads/`、`config/` 目录加 Web 运行用户写权限：
```bash
chown -R www:www /www/wwwroot/shuiyin
chmod -R 755 /www/wwwroot/shuiyin/data /www/wwwroot/shuiyin/uploads /www/wwwroot/shuiyin/config
```

**Q3：某平台解析失败，提示「暂不支持」？**
按顺序排查：
1. 后台 → 插件管理 → 解析器插件，确认该平台插件已启用；
2. 平台官方接口被风控（典型如抖音游客通道），属正常现象——系统会自动走回落渠道，可检查插件配置里的 `fallback_api` 是否有可用的三方接口；
3. 三方接口本身失效：更换 / 追加新的回落接口（一行一个 URL，含 `{url}` 占位符）；
4. 部分平台（如最右）已删除的帖本来就是 404，无法解析。
5. 前台失败提示只展示用户可读的原因，**不会显示备用接口/上游服务的域名**；完整明细（含各端点失败原因）已记入后台日志与解析记录，排障时到后台查看。

**Q4：解析能拿到直链，但视频无法播放 / 下载失败？**
部分平台 CDN 有防盗链（如 B 站需要 `Referer`），直接把直链贴进浏览器可能被拒。系统的下载代理会自动补齐请求头；若是前端播放问题，确认站点是 HTTPS 且平台直链也是 HTTPS（混合内容会被浏览器拦截）。

**Q5：支付下单成功，但订单一直「待支付」？**
支付回调未送达或验签失败。排查：
1. 回调地址必须公网可达（本地调试无法收到回调，可用工具模拟）；
2. **`notify_url` 必须与签名时提交的参数完全一致**，不能带额外路由参数，否则验签必失败；
3. 回调地址为**绝对地址**（含协议+域名），由系统按当前访问域名自动生成；若站点走 CDN / 反向代理，确保已透传 `X-Forwarded-Proto`，否则生成的可能是 http 地址而被网关拒绝；也可在后台「支付设置 → 异步回调地址」显式填写固定地址；
4. 后台订单列表确认网关侧订单状态；码支付（mpay）可在网关后台查单核对。

**Q6：支付完成后没有返回本站，停留在第三方支付平台？**
同步跳转地址（`return_url`）必须是绝对地址，第三方平台拿到相对地址会按它自己的域名跳转。系统自 v2026.10 起已自动生成绝对地址；若在 CDN / 反向代理后仍异常，请在后台「支付设置 → 同步跳转地址」显式填写 `https://你的域名/home/pay/return`。正常流程：支付成功 → 跳回本站「支付结果页」（订单未确认时会自动轮询补单，几秒内刷新为已支付）。

**Q7：后台登录不上 / 忘记管理员密码？**
密码是加盐哈希存储的，直接改库无效。用 CLI 重建管理员：
```bash
php install/cli-install.php   # 重新走一遍配置（数据可选保留）
```
或在测试环境重置后再把 `admin` 表该行的 password/salt 拷贝过去。

**Q8：插件上传安装失败？**
需要 PHP `zip` 扩展（可选扩展），开启后重试。也可以手动解压到 `plugins/` 目录后到后台刷新。

**Q9：换服务器怎么迁移？**
1. 旧站后台 → 数据库管理 → **备份**，下载 `.sql` 文件；
2. 打包整个项目目录（排除 `data/backup/` 可选）上传新服务器；
3. 修改 `config/` 里的数据库配置为新库信息；
4. 通过 phpMyAdmin 或后台数据库管理导入备份 SQL。

**Q10：恢复备份后数据没变化 / 报错？**
恢复是按备份文件内的 SQL 逐条执行、失败即中止：确认备份文件完整（未被截断）、表前缀一致、当前数据库用户有 DROP/CREATE 权限。

**Q11：报错页空白，怎么查问题？**
本地开发设环境变量 `SY_DEBUG=1` 开启调试输出；生产环境查看 `php_errors.log` 与 `data/` 下的运行日志。部署后若一直白屏，优先检查 PHP 版本（≥8.0）和必需扩展是否齐全。

**Q12：可以二开吗？目录里的代码能直接访问吗？**
可以二开，框架是三段式 PSR-4 自动加载（`core/` / `app/` / `plugins/`），无 Composer 依赖。`app`、`core`、`config`、`data`、`plugins`、`themes` 目录已被伪静态规则拦截，Web 无法直接访问，只有 `index.php` / `static/` / `uploads/` 对外暴露。

**Q13：金额为什么用整数存？**
系统全部金额以**整数分**（BIGINT）存储，显示时再除以 100，避免浮点精度问题。二开涉及金额的字段请遵守同一约定。

**Q14：邮件发不出去，怎么排查？**
按顺序检查：
1. 「解析设置 → 邮件功能」开关是否开启，且「邮件设置」已填 SMTP 参数；
2. QQ / 163 等个人邮箱必须填**授权码**，不是邮箱登录密码（QQ 邮箱：设置 → 账户 → 开启 SMTP 并生成授权码）；
3. 端口与加密方式要匹配：SSL 用 465，STARTTLS 用 587；
4. 服务器出站防火墙需放行对应端口（很多云服务器默认封 25 端口，推荐直接用 SSL 465）；
5. 配置好后用后台「邮件设置 → 测试发送」真实发一封验证，发送后有 60 秒倒计时防止误触发频控；
6. 报「无法连接邮件服务器 / Connection timed out」时，点后台「邮件设置 → **连接诊断**」：它会实测 DNS 与 25/465/587 三个端口的出站连通性并逐项回报——全被拦请到云控制台「安全组 → 出站规则」放行 TCP 465、587；安全组已放行仍不通则查服务器本机防火墙（firewalld / iptables）；
7. 系统会自动按「配置端口 → 465/SSL → 587/STARTTLS」顺序尝试，并在连接前自行解析 IPv4（A 记录）逐个直连，可绕开部分 Linux 服务器 IPv6 残缺导致的连接超时；
8. 旧版本存在 SMTP DATA 结束符缺少 CRLF 导致发送超时的核心 bug，若历史部署发信一直超时，请更新到包含 2026-10-05 修复的 `core/Mailer.php`。

**Q15：后期新功能如何扩展？会不会改坏核心？**
新功能（解析平台、支付渠道、短信渠道、页面模块等）一律以**插件**方式增加（`plugins/<name>/`，含 `plugin.json` + `Plugin.php`），不修改 `core/` 核心文件；`core/` 仅允许最小化 bug 修复。后台可通过「插件管理」启停、配置插件，无需改动代码。

**Q16：自定义登录入口忘了，进不了后台怎么办？**
入口名保存在数据库 `sy_config` 表（`key` = `admin_alias`）。用 phpMyAdmin / 命令行连接数据库后，将该行 `value` 清空或删除该行，即可恢复默认地址 `/admin/login/index`：

```sql
DELETE FROM sy_config WHERE `key` = 'admin_alias';
```

**Q17：前台发送验证码提示失败，但邮件收到了？**
这是旧版本前端脚本的问题（已修复）：发送接口成功返回后，前端误判了响应结构。若仍遇到，先强刷浏览器缓存（Ctrl+F5）；同时确认后台「邮件设置」已正确配置并点「测试发送」验证链路。

**Q18：前台注册报错 `1062 Duplicate entry '' for key 'uk_openid'`，一个账号都注册不上？**
旧版本会员表把 `openid` / `api_token` 定义成 `NOT NULL DEFAULT ''` 并各加了唯一索引。MySQL 的唯一索引会把**多个空串当成同一个值**，于是一整张表只容得下**一个**「未绑定」会员——第二个注册的人必然撞唯一键失败，现象就是「注册永远报错」。

修复方式（v2026.10.05 起）：这两列改为可空的 **NULL 语义**（`NULL` = 未绑定），唯一索引保留。MySQL 认为多个 `NULL` 互不相同，未绑定会员因此可以有任意多个，而真实的 openid / API 密钥仍然保持唯一。

- **全新安装**：`install/install.sql` 已是正确结构，无需处理；
- **已有站点**：覆盖新代码后执行一次

```bash
php install/cli-upgrade.php
```

或手动执行（表前缀非 `sy_` 请自行替换）：

```sql
ALTER TABLE `sy_user` MODIFY `openid`    VARCHAR(64) NULL DEFAULT NULL;
ALTER TABLE `sy_user` MODIFY `api_token` VARCHAR(64) NULL DEFAULT NULL;
UPDATE `sy_user` SET `openid`    = NULL WHERE `openid`    = '';
UPDATE `sy_user` SET `api_token` = NULL WHERE `api_token` = '';
```

> 若表上缺少 `uk_openid` / `uk_api_token` 唯一索引，升级脚本会一并补齐；执行完后清理一次 `data/cache/`。
> 后台「新增会员」走的是同一张表，旧结构下同样会失败 —— 上面这一步一并修好。

**Q19：微信公众号「服务器配置」保存时提示 token 验证失败？**
微信服务器会主动请求你的回调地址（`GET` 携带 `signature/timestamp/nonce/echostr`），插件校验签名后**原样回显 `echostr`**。逐项检查：① 回调地址必须公网可访问，`localhost` / 内网地址不行；② 后台「服务器 Token」与微信平台填的**完全一致**（区分大小写、前后无空格）；③ 站点走 HTTPS 或 80 端口；④ 中间层（CDN / 防火墙）未改写或缓存该路径的响应，PHP 未被拦截输出额外内容。

**Q20：个人订阅号扫码后没有反应 / 拿不到二维码？**
个人订阅号（未认证）**没有带参二维码接口**，因此没有「扫码即登录」。请在插件设置中把「公众号类型」选为**个人订阅号**，并开启「验证码口令登录」——用户关注公众号后，向公众号发送页面显示的 6 位口令即可登录。同时确认微信后台未用其他自动回复规则占用消息。

**Q21：给公众号发送了口令，公众号一直没反应？**
按顺序排查（插件在关键分支都会写日志，看 `data/logs/plugin-日期.log` 能直接定位）：
1. **消息加解密方式不匹配**（最常见）：微信后台若选了「兼容模式 / 安全模式」，推送的是 `<Encrypt>` 密文，
   后台必须填写与平台一致的 **EncodingAESKey**；漏填时日志会出现「收到加密推送但解密失败」，
   登录面板也会直接提示「配置异常」。
2. **服务器配置没生效**：微信后台的「服务器配置」要处于**启用**状态。未启用时微信根本不会把消息推给你的站点，
   用户发什么都得不到回复（此时你的日志里一条回调记录都没有）。
3. **口令过期**：有效期 10 分钟，超时后重发会收到引导文案，回网页重新获取即可。
4. **微信后台配了关键词自动回复**占用了该文本，消息可能不再转给开发者服务器。
5. **Token 不一致**：日志出现「回调验签失败」即为此项，逐字符核对后台与平台的 Token。

---

## 安全建议

- 安装完成后**立即删除 `install/` 目录**
- 修改默认管理员账号密码，并在「系统配置 → 安全设置」设置**自定义登录入口**隐藏登录页
- 生产环境关闭 `SY_DEBUG`
- 定期用后台「数据库管理」备份，并把 `data/backup/` 纳入异地备份
- 及时更新三方回落接口，失效接口在后台插件配置中移除
- 站点启用 HTTPS（支付回调与混合内容都依赖它）