奇点CMS 版本升级说明

本文档随交付包发布，记录通用升级流程与各版本的配置/依赖变更。

★ 维护约定：任何版本新增或变更扩展、依赖、服务器配置、数据表结构时， 必须同步更新 includes/SystemRequirements.php 注册表、docs/安装配置说明.md、 以及本文档的"版本依赖变更历史"，打包时缺一不可（见 docs/打包说明.md）。

一、通用升级流程

1. 备份
   - 全站文件快照（宝塔：网站 → 备份，或 zip -qry 到 /www/backup/site/）
   - 数据库备份（面板 → 数据库 → 备份）
2. 覆盖升级
   - 解压新版本包覆盖站点目录
   - 严禁覆盖的运行时文件（新包中本就不含，覆盖前也请确认）：
     config/generated.php、install.lock、data/ 全部文件、uploads/ 用户内容、.user.ini
3. 执行本版迁移脚本（见下方变更历史，均为幂等 SQL，可安全重复执行）
4. 配置变更（如本版要求新增 nginx location、ini 项等，见变更历史）
5. 验证
   - 后台 → 系统 → 部署检测：全部通过
   - 前台抽查：首页 / 小说频道 / 短视频 / 短剧播放 / 登录注册
6. 交付记录：登记升级时间与版本号

回滚方案：恢复步骤 1 的文件快照与数据库备份即可（迁移脚本均向后兼容，通常无需回滚数据）。

二、版本依赖变更历史

v0.4.70（将当前线上全局配色同步为站点默认值）

本版无新增扩展、无依赖/服务器配置/数据表结构变更；仅把当前线上生效的主题配色同步为 站点默认值，使未来新页面与全新安装都默认采用该套配色（主色 #636363 等）。

• 依赖要求不变：PHP 8.0+、MySQL ≥ 5.7 或 MariaDB ≥ 10.2；本版未新增扩展、未改 nginx 配置。
• 升级动作：仅覆盖文件即可，无 SQL 迁移、无配置变更；已装站点的线上主题值不受影响。
• 验证口径：

1. 全新安装后前台默认配色即为本次同步的值（主色 #636363、背景 #cccccc、文本 #000000 等）；
2. 后台「主题设置」默认值与表单回退值一致。

v0.4.69（新增 Token 卡密支付系统 + 授权码当天缓存 + 若干体验增强）

本版新增 token_cards 表（卡密充值/支付闭环）与授权码当天缓存，均自动生效； 无新增 PHP 扩展、无 nginx/服务器配置变更、无 MySQL 引擎要求变化。

• 依赖要求不变：PHP 8.0+、MySQL ≥ 5.7 或 MariaDB ≥ 10.2；本版未新增扩展、未改 nginx 配置。
• 升级动作：仅覆盖文件即可；token_cards 表由代码首次访问自动创建，无手工 SQL。如需立即确认建表， 访问后台「卡密管理」或前台卡密核销端点一次即可（或按 UPGRADE-v0.4.69.md 手动执行 CREATE TABLE IF NOT EXISTS）。
• 验证口径：

1. 后台「系统 → 部署检测」全部通过；
2. 数据库出现 token_cards 表（SHOW TABLES LIKE 'token_cards'）；
3. 首页小说/动态封面显示「点击量」蒙版，动态封面约 15 秒自动刷新；
4. 阅读器章节标题显示「（字数：N，费用：M）」，登录用户滑动进入付费章节、余额足够时自动扣费；
5. 后台「卡密管理」可批量生成卡密；前台支付页选择卡密支付并核销后余额到账。

v0.4.68（交付前复核修复：MariaDB 全新安装被 WITH PARSER ngram 阻断）

复核结论：database.sql 的 agent_knowledge 表带 FULLTEXT ... WITH PARSER ngram， 该语法为 MySQL 专有；MariaDB 直接报 1128 Function 'ngram' is not defined， 建表失败后安装向导/CLI 的建表完整性校验中断，MariaDB 上无法完成全新安装。

• 依赖要求不变：MySQL ≥ 5.7 或 MariaDB ≥ 10.2（MariaDB 上无 ngram 解析器，中文短词检索 命中率低于 MySQL，由 agent-ai.php / AgentKnowledge.php 的 LIKE 兜底，功能可用）
• 升级动作：仅覆盖文件即可，无 SQL 迁移、无配置变更；已装站点如需在 MySQL 上补 ngram 解析器， 走后台首页「数据库结构检查/同步」（DbUpdater 会按引擎自动决定是否附加 WITH PARSER）
• 验证口径：后台「系统 → 部署检测」→ 「知识库中文全文索引」在 MariaDB 上应显示"通过（默认分词）"； 全新安装（向导或 CLI）完成后 agent_knowledge 等 4 张知识库表必须存在

v0.4.64（官网新增用户系统 + 主站总览页「登录官方网站 / 获取授权验证」）

需求："给官网增加一个用户系统用于管理授权网站管理，在主站后台总揽页增加一个登录官方网站的接口用于获取授权验证"。

一、官网：授权用户中心（客户自助管理授权网站）

• 会话隔离：用户中心用 OFFUSERSESSID，与官网后台（OFSESSID）完全分开；
• 数据模型：新增 off_users 表，并给 off_licenses 自动迁移 user_id 列（首次访问自动完成，无需重跑安装向导）；
• 归属规则：一个账号可管理多个授权；授权码未被他人认领时可自助认领；已被他人认领时明确提示联系客服；越权操作（解绑/续验他人授权）一律拒绝。

二、官网后台：用户管理（official/admin/users.php）

• 列表 / 搜索（账号·称呼·公司）/ 分页；统计卡片：注册用户数、已归属授权数、未归属授权（待认领）；
• 用户详情：名下授权逐条列出，可解除归属；可把指定授权码指派给该用户；可重置密码；
• 停用/启用、删除（删除时其授权只解除归属、不删除授权本身）。

三、主站后台总览页：官方网站 · 商业授权卡片

在总览页顶部新增卡片，四块信息 + 三个按钮：

新增 LicenseManager::officialLoginUrl() 与 officialHomeUrl() 供跳转使用。

四、验证

数据层与业务（21 项断言全通过）：
  off_users 自动建表 ✓   off_licenses.user_id 自动迁移 ✓
  注册成功 ✓  重复注册被拒 ✓  非法账号被拒 ✓  弱密码被拒 ✓  登录成功 ✓  错误密码被拒 ✓
  ★ 认领授权成功 ✓   授权已归属 ✓   重复认领提示已在自己账号下 ✓   ★ 我的授权列表可读 ✓
  越权解绑被拒 ✓   授权可被激活 ✓   ★ 用户自助解绑成功（剩余换绑 1）✓   未绑域名续验给明确提示 ✓
  旧密码错误拒绝改密 ✓   两次不一致拒绝 ✓   ★ 改密成功 ✓   新密码可登录 ✓
  ★ officialLoginUrl 可生成且带 from=cms ✓   officialHomeUrl 可用 ✓
  （测试用户与授权已删除，库内无残留 ✓）

HTTP 真机验证：
  官网 /user/login.php HTTP 200 / 6956 B 无报错 ✓   ?from=cms&domain= 变体 200 / 7064 B ✓
  /user/index.php 未登录 302 跳登录 ✓（守卫生效）
  官网首页 30000 B，导航含「用户中心」✓，零报错 ✓
  官网后台「用户管理」HTTP 200 / 6326 B，含用户表 ✓
  ★ 主站总览页 34122 B：含「官方网站 · 商业授权」卡片、「登录官方网站」按钮、「获取授权验证」按钮、
    官网连接状态、链接指向 user/login.php，全部命中且零 PHP 报错 ✓

v0.4.63（主站配置官网接口地址 qdcms.cn + 主站↔官网 API 打通）

需求："给主站配置官网接口地址'qdcms.cn'，主站与官网的API相关功能"。

一、官网接口地址已配置

主站设置项 license_api 已写入 http://qdcms.cn。实测该域名已经在运行官网系统（v1.0.2）：

也就是说：域名与授权链路已经通了，只差把官网升级到新版（同时获得安装向导修复、首页主站介绍、CMS 下载中心与 releases 版本检查接口）。

二、主站↔官网 API 功能矩阵（4 条链路）

三、本次新增内容

四、验证 → 16 / 16 通过

A. 本地官网地址下：
   officialInfo 连接成功 ✓  官网名称+版本 ✓
   ★ releases 返回最新版与下载地址 ✓（v0.4.61 / /official/download.php?f=QDCMS-v0.4.61.zip）
   ★ 版本对比正确（本地官网 v0.4.61 vs 本站 v0.4.62 → up_to_date=true）✓
   ★ 插件市场接口可用（12 个插件）✓   releases 结构完整（历史版本 1 个）✓   ping 正常 ✓
B. 写入 http://qdcms.cn：
   设置写入成功 ✓   连接结果 ok=true（"授权服务正常"）✓
   不可达时返回结构化失败、不抛异常 ✓   ★ 字段完整（api/up_to_date 均在）✓   授权摘要可读 ✓
C. 后台渲染：商业授权页 HTTP 200 / 16858 B 无报错 ✓（含「官网连接与版本」面板、显示 qdcms.cn）
   插件与模块页 HTTP 200 / 27868 B 无报错 ✓
D. 远端实测：qdcms.cn 的 ping/plans/plugins 均正常返回 ✓（releases 需升级官网到 v1.0.5）

v0.4.62（官网新增 CMS 下载中心）

需求："给官方网站增加一个CMS 下载功能"。

一、前台：CMS 下载中心（official/download.php）

• 最新版卡片：版本号、体积、发布时间、下载次数、SHA256 校验值、通道（稳定/测试）； 「立即下载」按钮 + 「查看安装文档」；右侧给出安装三步（环境确认 → 上传解压 → 运行安装向导）；
• 历史版本表：全部版本可回滚下载，显示版本/类型/体积/发布时间/下载次数/SHA256 前 16 位， 文件缺失的版本会明确标注「文件缺失」而不是给个坏链接；
• 三栏说明：环境要求（PHP 8.0+/MySQL 8.0/可选 FFmpeg·Ollama）、授权说明（可自由下载评估，商用需购买授权并绑定域名）、升级与支持；
• 导航新增「下载」入口，首页 Hero 新增「下载安装包」按钮。

二、下载安全

• 下载走 download.php?f=<文件名>：只允许 off_releases 表中登记过的文件名（先 basename 再白名单正则）， 实测 ../../config/generated.php、index.php、不存在的文件全部 404 拒绝；
• 流式输出（256KB 分块）+ 正确 Content-Type: application/zip + Content-Disposition 文件名 + Content-Length + X-Package-Sha256 响应头（便于用户校验）；
• releases/ 目录自动放置 .htaccess（禁目录列表 + 禁 PHP 执行）与 index.html。

三、后台：下载管理（official/admin/downloads.php）

• 上传 zip（≤300MB）：自动计算体积与 SHA256、可从文件名解析版本号；同文件名则更新该条；
• 可选设为最新版（前台优先展示）、通道（稳定/测试）、标题与更新说明；
• 列表操作：编辑信息、设为最新、上架/下架、删除（同时删文件）；统计卡片显示已上架版本数、累计下载、当前最新版、存储目录；
• 「扫描本机安装包」：自动发现交付包目录里的 QDCMS-v*.zip 并复制登记，一步上架。

四、验证（实测）

① 建表：off_releases 自动创建（无需重跑安装向导）✓
② 登记：QDCMS-v0.4.61.zip（1.61 MB，sha256 1f9c38d5a40b75b3…）✓
③ 下载页：HTTP 200 / 10066 B，含最新版卡片与授权说明，零 PHP 报错 ✓
④ ★ 真实下载：HTTP 200 / 1,686,687 B / application/zip，
   下载文件 sha256 = 1f9c38d5a40b75b39bc00c7ca4344f52bc34e2abef146ba7757dd3d033fda63d
   与源包**完全一致** ✓
⑤ 目录穿越防护：../../config/generated.php → 404 ✓  index.php → 404 ✓  nonexist.zip → 404 ✓
⑥ 后台「下载管理」：HTTP 200 / 8019 B，含上传表单 + 版本列表 + 扫描按钮，零报错 ✓
⑦ 首页「下载安装包」按钮 ✓  导航「下载」入口 ✓  页面标题「CMS 下载 - 奇点CMS 官方网站」✓

五、打包说明

交付包内不含安装包本体（避免"包中套包"）：official/releases/ 只保留说明文件； 部署后到官网后台「下载管理」上传，或点「扫描本机安装包」自动登记交付包目录中的 QDCMS-v*.zip。

v0.4.61（官网首页改用主站真实内容做介绍）

需求："官方网站的首页介绍内用主站QDCMS相关内容做介绍"。

一、首页新增「主站介绍区块」（Hero 之后）

不再只讲功能名词，而是用主站自己的模块与运行数据说话：

• 12 个模块卡片：每个卡片显示模块名、真实计数、真实前台入口文件名（如 video.php、moments.php、qa.php）、 真实后台位置（如「内容 → 短视频」「工作面板 → Agent」）与一句话说明；
• 计数为 0 的模块（如小说、短剧：装了但还没内容）显示 「已就绪」，不露"0 部小说"这种尴尬数据；
• 运行实况条：数据库表数、已装载模块数、媒体文件数、注册用户数，以及计数最高的 6 个模块；
• 标注「统计时间 xxx，每 10 分钟自动刷新」。

实测（线上首页，与数据库逐项核对一致）：

12 个模块卡片：
  小说阅读 已就绪   novels.php         后台：内容 → 小说管理
  章节内容 已就绪                      后台：内容 → 小说管理
  短视频   10 条   video.php          后台：内容 → 短视频
  短剧     已就绪   drama.php          后台：内容 → 短剧
  动态广场 17 条   moments.php        后台：内容 → 动态
  百科词条 3 条    encyclopedia.php   后台：内容 → 百科
  问答     8 条    qa.php             后台：内容 → 问答
  时政资讯 5 条    news.php           后台：内容 → 资讯
  即时通讯 13 条   messages.php       后台：系统 → 聊天设置
  AI 知识库 18 条  agent-ai-api.php   后台：工作面板 → Agent
  Token 计费 38 条                    后台：运营 → Token
  用户体系 3 条    login.php          后台：用户 → 用户管理
运行实况：数据库表 55 张 · 已装载模块 12 个 · 媒体文件 21 个 · 注册用户 3 位
          · 短视频 10 · 动态广场 17 · 百科词条 3
首页体积 21872 B → 29786 B，零 PHP 报错 ✓

二、配套改造

三、降级与容错验证

① 关闭主站数据（main_db_enabled=0）→ 首页 29786 → 24042 B，显示"主站数据暂不可读 + 功能清单"文字介绍，
   零 PHP 报错 ✓（不白屏、不报错）
② 恢复为自动模式 → 首页 29787 B，模块卡片与实况数据回归 ✓
③ 主站数据库不可达时同样走降级分支（连接 3 秒超时 + 10 分钟缓存，不影响首页打开速度）✓

v0.4.60（官网安装向导 + 修复 open_basedir 告警）

用户实测反馈：Linux 宝塔环境部署官网时报 Warning: is_file(): open_basedir restriction in effect. File(/www/wwwroot/config/generated.php) is not within the allowed path(s): (/www/wwwroot/qd/:/tmp/) 随后页面显示"官网数据库暂时不可用"，并询问"官方网站是否有安装向导"。

一、这是真 bug（已修）

官网内核为了兼容"与 CMS 同机子目录部署"，会去探测上层目录的 ../config/generated.php。 独立部署时上层目录通常在 open_basedir 之外 → is_file() 触发告警；且探测失败后代码 直接走到"数据库暂时不可用"，既没说清原因、也没给安装入口。

修法：

1. 新增 offSafeIsFile()：先判断目标路径是否落在 open_basedir 允许列表内， 不在允许范围就根本不去访问（不再产生任何告警）；所有对上层目录/密钥文件的探测统一走它；
2. 数据库连不上时区分两种情况： · 尚未安装 → 渲染引导页「官网尚未完成安装 → 打开安装向导」（不再是干巴巴一句报错）； · 已安装 → 仍提示数据库不可用，并指向 data/official.log。

二、新增图形安装向导（回答"是否有安装向导"：原来只有命令行，现在有了）

浏览器打开 install.php 即进入向导，三步完成，无需命令行：

其它：保留命令行安装（--db-name/--db-user/--db-pass/--admin/--pass，幂等，适合脚本化/批量部署）； 支持网址参数一键安装；已安装后再访问显示"已完成安装"，删除锁文件可重装，带 ?token= 可进入。

三、复刻用户环境实测（决定性验证）

环境：全新目录（无 config/generated.php）+ 上层目录放一个主站配置（复刻 /www/wwwroot/config/…）
      open_basedir 严格限制为「站点目录 + C:/Windows/Temp/」——与用户的 /www/wwwroot/qd/:/tmp/ 同构
① 首页：HTTP 503，显示"官网尚未完成安装 → 打开安装向导"
   ★ open_basedir Warning：False ✓（修复前为 True）
   ★ 直接甩"数据库暂时不可用"：False ✓
② 向导第①步环境检测：HTTP 200，4626 B（含 open_basedir 检测行）✓
③ 向导第②步提交：
   [ok] 数据库不存在，已自动创建 ✓  [ok] 已建/校验 9 张表 ✓
   [ok] 已创建管理员 ✓  [ok] 默认设置新增 14 项 ✓  [ok] 插件条目新增 12 个 ✓
   [ok] 已写入首条公告 ✓  [ok] 已写入独立配置 config/generated.php ✓  [ok] 已写入安装锁 ✓
④ 安装后：首页 HTTP 200 / 21449 B ✓   API ping → ok=true, version=v1.0.2 ✓
⑤ 再次访问向导 → 显示"已完成安装"并锁定 ✓
⑥ 清理：停服务器 / 删测试库 / 删模拟目录 ✓

v0.4.59（官方网站支持独立打包与独立部署 + 一处空值加固）

需求："官方网站独立打包"。

一、官网现在可以脱离主站独立部署

原来官网内核从主站 ../config/generated.php 读数据库口令，只能"同机子目录"部署； 本次改造后支持两种形态：

• install.php 支持命令行/网址传入数据库参数，并会自动建库、写独立配置（权限 0600）： ``bash php install.php --db-host=127.0.0.1 --db-name=qdcms_official \ --db-user=root --db-pass=口令 --admin=admin --pass=后台密码``
• 新增 README.md（部署与接口速查）、docs/官网部署说明.md（独立/子目录/反代/HTTPS/权限/排查/升级全套）、config/generated.example.php 配置模板；
• 新增独立打包脚本 qdcms-release/pack-official.py，产出 QDCMS-Official-v1.0.1.zip （36 个文件 / 128 KB，不含数据库口令、签名密钥、日志、限流计数）。

二、独立部署实测（不是"应该能跑"）

① 打包：36 个文件 / 128,277 字节；含 config/generated.php：False ✓；含 data 敏感文件：空 ✓
② 解压到临时目录 + 建全新库 qdcms_official_test（模拟客户拿到包的干净环境）
   install.php 退出码 0：9 张表 ✓ 管理员 ✓ 14 项设置 ✓ 12 个插件 ✓ 公告 ✓
   已生成独立配置 ✓ 已生成签名密钥 ✓
③ 用 PHP 内置服务器真机验证（14 个端点）：
   /index.php 21449B ✓  /features.php 32864B ✓  /plugins.php 25401B ✓  /plugin.php?slug=ai-agent ✓
   /pricing.php ✓  /activate.php ✓  /changelog.php ✓  /news.php ✓  /docs.php ✓  /about.php ✓
   /admin/login.php ✓  /api.php?action=ping ✓  /api.php?action=plans ✓  /api.php?action=plugins ✓
   ping 返回：name=奇点CMS version=v1.0.1 plans=4 sign=64 位 ✓
   重复执行 install.php（幂等）：退出码 0，管理员未重复创建 ✓
④ 清理：停临时服务器 ✓ 删除测试库（残留 False）✓ 删除临时目录 ✓

三、顺带修掉的一处真实缺陷

官网导航数组是 [标签, 链接] 元组形式，我此前插入的「公告中心」写成了关联数组 ['label'=>..,'url'=>..]，导致该条 $item[1] 为 null → 在 strict_types 下 offUrl(null) 抛 TypeError → 官网首页整体 500（页面从 21872 B 掉到 3450 B）。 已修正为元组形式，并给内核 offUrl()/offAsset() 增加 ?string 空值容忍（防御同类问题）。 修复后官网 10 个前台页面 + API 全部复测 200 且零报错 ✓

v0.4.58（官方网站 + 商业授权激活系统 + 插件市场）

需求："根据网站开发一个官方网站，包含商业授权激活等功能，以及CMS 所需业务的和插件等功能"。

一、交付形态

官网位于 站点子目录 official/（http://你的域名/official/），复用现有 nginx/PHP， 无需新增站点、无需重载 nginx；数据存放在独立数据库 qdcms_official，与客户站点数据完全隔离。

二、端到端验证（授权全链路 40/40 通过）

A 段（官网侧 19 项全通过）：
  ping/plans/plugins 接口 ✓  响应 64 位 HMAC 签名 ✓
  发码（格式校验）✓  ★首次激活成功 ✓  返回带签名令牌（含套餐/到期/域名）✓
  ★换域名激活被拒 domain_mismatch（并带出已绑定域名）✓
  ★重复 nonce 被拒（防重放）✓   过期时间戳被拒 ✓
  公开查询返回脱敏信息（QDCMS-57Z****WU52）✓
  续验成功 ✓  解绑成功（剩余换绑 4 次）✓  解绑后可在新域名激活 ✓
  不存在的授权码被拒 not_found ✓

B 段（CMS 侧 21 项全通过）：
  ★CMS 在线激活成功 ✓  状态 active 且域名正确（剩余 364 天）✓  授权码脱敏展示 ✓
  ★onlineLicenseValid=true ✓  ★isLicensed=true（在线授权生效）✓  ★checkRemote 真实可用 ✓
  ★CLI 场景：缺少域名时给出可操作提示 ✓  显式传域名可激活成功 ✓
  手动续验 ✓  6 小时内重复续验走缓存（不打官网）✓
  未配置官网地址/官网不可达 → 提示清晰 ✓
  ★被吊销后续验失败并说明原因 ✓  ★到期后续验失败 ✓
  续验失败不清空本地状态（保留便于排查）✓
  测试授权码/日志已删除、配置已复位、库内零脏数据 ✓

官网页面全量回归：10 个前台页面 + 8 个后台页面 = 18 个页面全部 HTTP 200 且零 PHP 报错 ✓

三、开发中发现并修掉的 6 个真实缺陷

另外：子代理还发现并补了一处业务安全漏洞 —— 已取消的订单仍可发码（UI 只是隐藏了按钮），已加服务端守卫。

四、使用步骤

1. 官网：浏览器打开 http://你的域名/official/；后台 .../official/admin/（初始账号 admin，首次安装密码见安装输出，请立即在「站点设置」修改）；
2. 发码：官网后台 →「授权码管理 → 生成授权码」（或在「订单管理」里一键发码）；
3. 激活：客户站点后台 →「商业授权」→ 填官网地址（http://你的域名/official）与授权码 → 在线激活；
4. 续验/换域名：同页面点「立即续验」「解绑换域名」；
5. 插件市场：官网「插件市场」展示 12 个插件，可在后台维护上架/版本/价格/安装说明。

v0.4.57（交付包与说明文档的站点名称统一为「奇点CMS」）

需求："打包说明站点名称改为『奇点CMS』"。

一、依据（你们自己的打包约定）

docs/打包说明.md 第 312 行原文：

站点名称 SITE_NAME

config/config.php

奇点CMS

打包的站点默认名称为"奇点CMS"，交付包必须使用该通用名称；客户个性化站名由客户安装后自行修改，不得将任何客户特定站名带入交付包

生效版本：自 v0.3.80 起。

核对后发现：SITE_NAME 常量早已是「奇点CMS」，但包内仍有多处旧名残留，其中还有功能性缺陷：

二、改动（共 60 个文件、84 处）

• 新装默认值：站点名 / 页脚 → 「奇点CMS」；
• 用户可见文案：安装向导标题、SEO 占位提示、AI 人设（后台助手/运维助手）、体检报告标题、AI 回复兜底版本名、对话导出标题、运维巡检日报标题、qdcms-ffmpeg-win.ps1 与各 JS 头注释；
• 文档标题：README、打包说明、安装配置说明、Windows 部署说明、架构设计、版本升级说明、网站BUG修复规范、页面模块规范、聊天说明、Go 服务 README → 「奇点CMS」；
• 明确不改（避免破坏功能与历史）：
• 技术标识：x-dream-go / x-dream-go.exe、qdcms-*.ps1 脚本名、QDCMS-v*.zip 包名正则、assets/images/qdcms-logo.png、数据库名、C:\ProgramData\QDCMS\reports 目录；
• install/install.lock 内容（X-Dream CMS Installed，被安装锁逻辑使用）；
• 历史文档正文：docs/版本升级说明.md、docs/网站BUG修复.md 中的历史条目原文，以及 docs/打包说明.md 中记录"v0.3.79 及更早沿用旧名属已确认例外"的约定正文。

三、验证

包内品牌核对（13 项）：
  config/config.php  SITE_NAME = 奇点CMS ✓
  database.sql       新装默认站点名 = 奇点CMS ✓   默认页脚 = Powered by 奇点CMS ✓
  includes/footer.php 兜底 = Powered by 奇点CMS ✓
  文档标题：README / 打包说明 / 安装配置说明 / Windows部署说明 / 版本升级说明 均为「奇点CMS」✓
  AI 人设：奇点CMS 的网站运维助手 ✓   奇点CMS 后台的助手 ✓
  体检报告标题：# 奇点CMS 站点体检报告 ✓    安装向导标题：奇点CMS 安装向导 ✓
语法：PHP 全部文件 php -l 通过 ✓   PowerShell 脚本 Parser 解析通过 ✓
剩余"用户可见旧名"：0 处（仅保留打包约定文档中记录历史例外的正文）✓

v0.4.56（优化服务器资源调用、减少内存占用）

需求："优化网站在网站服务器的资源调用，减少内存占用"。

一、先量后改（本机 7.73 GB 内存）

二、已做的优化（MySQL，全部在线生效并持久化）

用 MySQL 8 的 SET PERSIST（同时写入 mysqld-auto.cnf，重启后依然有效）：

performance_schema=OFF 已写入 my.ini（含备份），但它属于启动参数，需重启 MySQL 才生效 —— 生效后可再省 150~300 MB。

三、新增运维工具：服务器资源与内存

includes/OpsTools.php 新增 server_memory 工具（已注册进工具目录与"一键体检"）， 在后台「工作面板 → ③ 运维工具」点一下即可看到：

• 物理内存/页面文件占用（已用%、可用量）
• PHP 进程池进程数与占用
• MySQL 关键内存参数（连接上限、packet、key_buffer、tmp_table、performance_schema 状态）
• 进程占用 Top 15
• 非服务器软件占用合计（含进程名与体积）
• 自动给出可执行的省内存建议（例如"进程池 20 个，建议降到 6~8，约省 144MB"）

四、验证

$ OpsTools::run('server_memory')
  概要: 内存 6.75 GB / 7.73 GB（已用 87.2%，可用 1010 MB）；PHP 进程池 20 个 521MB；MySQL 连接上限 80
  MySQL: buffer_pool=256MB, max_connections=80, max_allowed_packet=64MB,
         key_buffer=16MB, tmp_table=32MB, performance_schema=ON(待重启)
  建议 4 条：可用内存低于15% / PHP 进程池偏大 / performance_schema 待关 / 3048MB 非服务器软件可关闭

MySQL 新连接复核（会话值随新连接刷新，确认不是"只改了会话"）： max_connections=80 ✓ max_allowed_packet=64MB ✓ tmp_table_size=32MB ✓ key_buffer_size=16MB ✓ innodb_log_buffer_size=16MB ✓

新增工具已并入"一键体检"清单，共 11 个工具。

五、还想再省内存？两条可选（都在你手上）

1. 重启一次 MySQL（宝塔 → 数据库 → 重启），让 performance_schema=OFF 生效 → 再省 150~300 MB；
2. 宝塔 → PHP 设置里把进程数降到 6~8（本站流量很低，20 个是浪费）→ 再省 约 144 MB；
3. 不用时可关闭 Edge / 手机助手 / vivo 助手 / Dell 支持助手 等非服务器软件 → 最多可释放 约 1.8 GB。

v0.4.55（修复全站客户端加载缓慢）

现象：全站页面"打开后图片/内容慢慢才出来"，尤其首页与动态广场。

一、先量后改（关键数据）

二、根因（两处叠加）

1. 图片加速器正则漏掉了带前导斜杠的写法 ✗ includes/fn-core.php 的 imageAcceleratorBuffer() 只匹配 src="uploads/…"， 而大量模板（首页、列表页）输出的是 src="/uploads/…" —— 于是这些图片完全绕过加速器， 既不压缩、也不走 30 天缓存、也不做懒加载，直接下发原图。
2. 首页卡片代码直连原图 ✗ index.php 的热门动态卡片用 baseUrl() . 原图路径 直接输出 —— 实测单张 403 KB。

顺带确认：站内的 img-proxy.php 本身实现良好（磁盘缓存 + ETag + 30 天头）， 同一张 394 KB 原图经它 400px 处理后只有 40.8 KB，命中缓存仅 7.6 ms —— 只是没被用上。

三、改动

四、效果（同一入口实测）

五、验证 → 13 / 13 通过

A. 加速器正则：uploads/ ✓  /uploads/（修复点）✓  http://…/uploads/ ✓  //host/uploads/ ✓
   静态资源不动 ✓  已是代理 URL 原样返回（不嵌套）✓
B. 首页图片：6 张全部走代理 ✓  无 404 ✓  ★ 总量 206.2 KB < 300 KB（修复前 886 KB）✓
C. 全站回归：首页/动态/短视频/短剧/小说/问答/百科/资讯/登录/分类 共 10 个页面全部 HTTP 200、无 PHP 报错 ✓
D. 代理图片带 30 天缓存头 ✓  返回 image/jpeg ✓

v0.4.54（修复"运行环境下载不了"）

现象：点「下载安装包」后一直转圈 / 任务永远"进行中"，安装包始终是 0 字节。

一、诊断（有据）

→ 700MB 按实测速度需 4 小时以上，且连接会被重置；这是网络链路问题，不是页面 bug。

二、同时修掉的 3 个真实代码缺陷

三、本次新增能力

四、验证 → 26 / 26 通过

A. 多源列表：4 个来源，首选为实测最快的镜像 ✓
B. 脚本生成：含 -C - / goto 多源回退 / --retry-all-errors / 签名校验 ✓
   ★ 不再有 if exist…else…>> 陷阱 ✓   ★ 退出标记无条件写入 ✓   dryRun 不产生真实任务 ✓
C. 断点续传：检测到部分文件时提示续传 ✓
D. 僵尸任务：日志 400 秒无变化 → 不再显示"进行中" ✓
E. 安装包校验：不存在/体积不足 均正确拒绝 ✓
F. 页面/端点：200 无报错、含继续下载+校验+停止+手动放置说明与实测网速提示 ✓
   verify / stop / status 端点均正常 ✓
回归：60 秒长任务 startJob 返回 0.96s（不再阻塞请求）✓

五、你要怎么做（两条路，任选）

1. 推荐（最快）：在手机/电脑（可开加速）下载 OllamaSetup.exe，拷到服务器 D:\wwwroot\qdcms\data\model_jobs\，回页面点「校验安装包」，通过后双击安装 → 点「启动服务」→ 再下载模型（模型仓库链路实测正常）。
2. 让服务器自己下：已为你在后台启动了下载（可断点续传），页面会显示进度；数小时后若中断，回来再点一次「继续 / 重试下载」即可。

v0.4.53（把站内百科与问答接入知识库检索）

需求："将站内的百科和问答接入知识库检索"。

一、之前的状况

二、改动

所有钩子都包在 try/catch 里 —— 知识库同步失败绝不影响百科/问答本身的保存。

三、验证 → 27 / 27 通过

A. 批量同步：百科扫描 3 → 入库 3；问答扫描 8 → 共 16 条；重复同步新增 0（幂等）✓
B. 检索：★「长城 防御工程」命中百科词条「长城」✓   片段表从 0 → 6 条（长城自身 2 条）✓   问答可命中 ✓
C. 增量更新（临时词条，全程用完即删）：
   ★ 新建词条 → 立即能被检索到 ✓
   ★ 改内容 → 知识库同步更新且**不新增重复**（条数仍为 1，含新内容）✓
   ★ 下架 → 自动移出知识库，片段一并清理 ✓   临时数据已删 ✓
D. 问答钩子：临时问题+回答 → ★ 提交回答即自动入库 ✓ → ★ 可被检索命中 ✓ → 临时数据已清理 ✓
E. 真机端到端：问「长城是什么？」→ source=cloud
   答案：长城又称"万里长城"，是中国古代规模浩大的军事防御工程，横跨15个省（区、市），
        总长度超过2.1万千米，1987年列入《世界遗产名录》。它始建于春秋战国，秦始皇连接增筑，
        明代修筑最完善。长城不只是城墙，还包括……      ← **完全来自百科知识库**
F. 面板/端点：含「同步百科与问答」按钮 ✓  来源分布展示 ✓  无 PHP 报错 ✓  kb_sync 幂等 ✓
数据卫生：无测试残留（知识库/百科/问答中的"自检"条目均为 0）✓

四、效果

• 站内百科词条与问答现在都是 Agent 的事实来源：问「长城是什么」「怎么设置短视频单独价格」都能得到基于站内内容的回答；
• 增量自动同步：后台改词条、审核通过、下架，前台提交/采纳回答 —— 知识库都会自动跟着变，无需手动维护；
• 顺手修好片段级检索（此前 0 条数据形同虚设），长词条也能被精准命中。

v0.4.52（网站 Agent 知识库对接模型，实现"部署即用"）

需求："把网站Agent 知识库对接模型，实现部署即用"。

一、之前的两个断点

二、改动

三、验证 → 27 / 28 直接通过 + 1 项独立进程补验通过

A. 知识库内容：15 条（site_qa 8 + 站点事实 7）✓  统计字段完整 ✓  **灌库幂等**（二次执行 0 新增）✓
B. RAG 注入（桩模型查载荷）：kb_hits=4 ✓  ★载荷含知识库原文"通用消费凭证" ✓  人设仍在 ✓
   用户问题在载荷 ✓  注入长度 974 字（受控）✓
C. 无命中时不注入：kb_used=false ✓  上下文无知识库字样 ✓
D. AgentProcessor：★命中时 skill=knowledge+model（模型按站点事实作答）✓
   独立进程补验：把接口地址改成不可达 → skill=knowledge（**回落知识库原答案**）✓
E. 真机端到端：问「看短视频要消耗多少 Token？」
   → source=cloud，1047ms/628 tokens
   → 答案：看短视频会消耗 Token，具体金额由系统按内容定价自动扣费，播放前页面会显示价格。想了解余额和扣费明细，
     可登录后进入「Token 记录」查看。如果 Token 不够，在个人中心充值即可。   ← **完全基于本站知识库事实**
F. 面板/端点：卡片与按钮 ✓  条目数展示 ✓  无 PHP 报错 ✓
   kb_stats total=15 ✓  kb_probe 命中 4 条/768 字上下文 ✓  kb_seed 重复执行 0 新增 ✓
数据卫生：知识库 15 → 15 未被污染 ✓  模型配置已还原为云端 ✓

本轮修掉一个自身缺陷：新增的 stats() 与既有同名方法重复声明导致致命错误 → 已改为删除重复实现、把既有 stats() 扩展成超集（保留原字段，避免影响其它调用方）。

四、效果

• 部署即用：装上模型（云端或本地皆可）后，点一次「一键导入站点知识」，Agent 立刻能回答"本站怎么用/要花多少 Token/上传限制/靓号/认证/客服"等站点问题 —— 因为回答建立在知识库事实上，而不是模型自由发挥；
• 知识库为空时也不报错，模型照常回答（自动跳过注入）；
• 知识库内容会随站内问答增长继续补充（原有 autoIngest 仍在工作）。

v0.4.51（本地模型运行环境 + 模型下载部署 + 部署后自动接入 Agent）

需求："给网站增加一个本地模型运行环境和模型下载部署功能，植入模型下载页面，部署后自动接入网站Agent"。

一、选型（基于本机实测）

→ 因此运行环境选 Ollama：官网一键安装、自带模型仓库、并暴露 OpenAI 兼容端点 http://127.0.0.1:11434/v1 —— 本站既有 AiClient 零改动即可对接，这是"部署后自动接入"能成立的关键。

二、新增内容

接入后立即生效范围：后台「工作面板 → ①」显示本地端点；前台悬浮助手改用本地模型回答（AiFrontAgent 读同一份配置）；原云端配置自动备份，可一键恢复。

三、验证 → 55 / 55 通过

A. 真实环境检测（本机当前未安装）
   状态结构完整 ✓  如实报告未安装/服务未运行 ✓  OpenAI 端点正确 ✓  读到内存 7.7GB ✓
   清单 6 项含体积与内存建议 ✓  首项为低配推荐 0.5B ✓  安装包为官方 URL ✓
B. 后台任务引擎（真实跑一个任务）
   任务启动 ✓  登记可跨请求查看 ✓  执行完毕 ✓  退出码 0 ✓  **进度解析到 100%** ✓
   日志落盘 ✓  日志尾部可读 ✓  任务可清除 ✓  parseProgress 取最大值/空日志安全 ✓
C. 拉取任务组装（假 exe，不产生真实下载）
   任务启动 ✓  批处理含 OLLAMA_HOST 与 pull 命令 ✓  **非法模型名被拒（防注入）** ✓
   失败任务如实以非 0 退出码结束（9009）✓
D. 接入 / 回滚
   未安装的模型接入被拒 ✓  接入成功 ✓  base_url 切到 11434/v1 ✓  模型名写入 ✓
   CA 包自动清空（本机 http 不需要）✓  前台 Agent 同步启用 ✓  云端配置自动备份 ✓
   一键恢复云端成功 ✓  isActivated() 语义正确 ✓
E. 页面与端点
   页面 HTTP 200、无 PHP 报错 ✓  含三步/6 个候选模型/全部按钮/导航入口 ✓
   端点 401/403/419 鉴权链路 ✓  status 返回环境与清单 ✓  非法模型名友好报错 ✓
   activate 未启动服务时明确提示 ✓  revert 无备份时友好提示 ✓

本轮修掉的 3 个真实缺陷（都是测试逼出来的）：

1. jobStatus() 用 getSetting 读任务键 → 启动任务后立刻查状态拿不到（进度条永远空白）→ 改为直连数据库读取；
2. admin/local-model.php 用了 LicenseManager 却没 require → 页面 HTTP 500 → 已补；
3. 批处理各命令输出没有重定向进日志 → 只有退出标记落盘，进度永远 0% → 现在每行自动追加 >> 日志 2>&1。

四、你要怎么用（三步，都在新页面里）

1. 后台 →「本地模型」→ ① 下载安装包（约 700MB） → 下载完成后在服务器上双击运行完成安装 → 回到页面点「启动服务」；
2. ② 在清单里选 qwen2.5:0.5b（约 397MB，最省内存，推荐） 点「下载部署」，页面会实时显示进度与日志；
3. ③ 部署完成后点「接入网站 Agent」 → 立即生效（前台悬浮助手 + 后台工作面板同时切到本地模型）； 想换回云端点「恢复云端配置」即可。

提醒：本机 7.7GB 内存、2 核 CPU，1.5B 模型单次回答约 5~20 秒；若追求速度，建议本地模型只作为云端不可用时的备份，云端仍用 DeepSeek（当前配置）。

v0.4.50（云端模型接入前台 Agent，实现真问答）

需求："把云端模型 接入前端Agent 实现问答"。

一、以前前台 Agent 是"假 AI"

前台悬浮助手（assets/js/agent.js）的问答链路是： 站内搜索 → 有结果就套模板 ✓ → 没结果时调 agent-ai-api.php → MicroAI（规则/意图引擎，不是真模型） ✗ → 最后再兜底本地关键词。 即"回答"是模板拼接出来的，不会真正理解问题。

二、改动

三、验证

A. 真机端到端（真实调用 DeepSeek）

★ 提问「用一句话介绍本站能做什么」→ source=cloud，tokens=139，760ms
   答案：墨香书阁是一个在线读书平台，你可以搜书、看书、收藏好书，还能管理自己的书架。
★ 把 base_url 临时改错（模拟断网）→ source=rule（自动回落规则引擎，用户侧仍然成功）
   并附 cloud_note：网络错误: Failed to connect to 127.0.0.1 port 9 ✓   之后 base_url 已还原 ✓

B. 额度与开关（独立子进程复测，等同于生产每请求新进程）

启用 + 游客额度 2  → 通过 2/3，模式 cloud,cloud,quota      ✓
游客额度 0        → 全部 quota（不开放云端）              ✓
关闭开关          → 全部 disabled（不调用模型）            ✓
登录用户额度 3     → 通过 3/4，模式 cloud,cloud,cloud,quota ✓

C. 单元（桩模型）：答案透传 ✓、tokens/耗时记录 ✓、系统提示词含站点人设与指引要求 ✓、max_tokens 受限 ✓、extraContext 注入 ✓、模型报错返回结构化失败（调用方可回落）✓

D. 前端与面板：agent.js 超时 25000 ✓；面板含开关/额度/预算/人设/今日用量 ✓

所有测试写入的配置已重置回代码默认（启用、登录 20/小时、游客 5/小时、每日 500），测试额度计数已清理 ✓

四、费用与安全控制

• 前台对任意访客开放，因此默认就是"有额度上限 + 有每日预算保险丝"；
• 游客默认 5 次/小时、登录用户 20 次/小时、全站默认 500 次/天；都可以在面板里改，设为 0 即关闭云端（仍可用规则引擎）；
• 每次调用都记 data/.ai_front_usage.log，面板可看今日用量，便于核对费用；
• 关闭开关或额度用尽时自动回落，前台不会报错、不会白屏。

v0.4.49（云端模型配置成功后自动折叠配置区）

需求："模型配置成功后折叠配置接口"。

一、改动（admin/workbench.php）

二、验证 → 22 / 22 通过

A. 已配置（当前状态）
   卡片带 wb-cfg collapsed ✓  折叠容器 wb-cfg-body ✓  摘要含模型/地址/密钥掩码 ✓
   按钮为「展开修改」✓  折叠 CSS 规则存在 ✓  页面无 PHP 报错 ✓
B. 未配置（用密钥快照→清空→渲染→还原，最终配置未被改动）
   卡片**不带** collapsed ✓  按钮为「收起」✓  摘要提示"尚未配置"✓  不显示密钥掩码 ✓  密钥已还原 ✓
C. JS 行为契约
   setCfgCollapsed / refreshCfgSummary 存在 ✓  localStorage 记忆 ✓
   保存成功自动收起 ✓  连通成功自动收起（失败保持展开）✓  未配置强制展开守卫 ✓  按钮可手动切换并记忆 ✓
D. 实时 HTTP 渲染：58,874 B，无报错 ✓

三、效果

配置好之后，① 页签只剩一行摘要（模型 · 接口 · 密钥 · 状态徽章），面板清爽不占地方； 需要改配置时点「展开修改」，改完保存（或测试连通成功）会再次自动收起。

v0.4.48（修复云端模型接口 TLS 证书校验失败）

报错原文：网络错误: SSL certificate problem: self signed certificate in certificate chain（HTTP 0）

一、根因：本机 PHP 完全没有 CA 根证书包

→ OpenSSL 没有信任库，任何 HTTPS 请求都会被判为"自签名证书链"，与接口本身无关。

二、修复

三、验证 → 11 / 11 通过

A. 自动发现：Web 语境（open_basedir 限制下）命中站点内 data/cacert.pem（87 张）✓  默认不关闭校验 ✓
B. 证书错误 → 自动带 CA 重试成功 ✓  重试时校验仍开启（cainfo=站点内包, insecure=false）✓
C. 无可用 CA 时输出中文排查指引（含两条出路）✓
D. 面板端到端（真实调用你配置的 DeepSeek 接口）：
   ★「测试连通」→ 连通正常（模型 deepseek-flash，799ms）：ok   ← 你遇到的报错已消失
   ★ 对话试跑 → 正常
   status 返回站点内 CA 包路径 ✓

四、说明与后续

• 现在无需任何操作即可用（面板即时生效）；
• 若希望全站所有 HTTPS 调用（不止模型接口）都用上 CA 包：到宝塔面板重启一次 PHP，curl.cainfo 即全局生效；
• 若将来接口用自签名证书：勾选「允许自签名证书（有风险）」即可，但会关闭服务器证书校验，仅在确知风险时使用。

v0.4.47（工作面板对话框页增加可操作实用工具）

需求："工作面板对话框页增加可操作实用工具"。

一、对话框页新增三组实用工具

二、6 个可执行操作（includes/OpsActions.php）

三、安全边界（本次重点验证）

1. 模型无法调用写操作 —— 写操作与只读工具（OpsTools）严格分离：把 clean_tmp_chunks 交给只读注册表会返回"未知工具"，智能体的工具清单里也不含任何写操作；
2. 必须二次确认 —— 前端 confirm + 服务端 confirm=1 双重校验；未确认时拒绝执行且零副作用（已用测试夹具验证目录仍在）；
3. 白名单 —— 不接受任意动作名、路径、命令、SQL；
4. 审计日志 —— 每次执行写 data/.ops_actions.log（时间/操作者/动作/结果/IP），面板内可查最近 10 条；不含密钥等敏感信息；
5. 越权防护 —— 端点仅管理员（401/403）+ CSRF（419），普通用户执行写操作返回 403。

四、验证 → 33 / 34 通过（唯一未过项为测试自身的计数口径：页面里 .wb-chip 出现 7 次＝6 按钮 + 1 处 JS 选择器）

A. 安全边界：白名单 6 项 / 未知操作被拒 / 未确认被拒且无副作用 / 模型不可调用写操作（3 项断言）✓
B. 真实执行：临时分片"删过期 1 个、保留进行中 1 个"✓  会话"删过期 1 个、保留活跃 140 个"✓
             优化 8 张表 ✓  OPcache 重置成功 ✓  孤儿扫描 5 个（只列不删）✓
             授权告警重置（原 13/8）→ 校验删除与备份 → **已还原原值** ✓
C. 审计：6 条记录、含操作者、无敏感字段 ✓
D. 端点/页面：ops_actions 返回 6 操作+审计 ✓  无 confirm 拒绝 ✓  确认后执行 ✓  普通用户 403 ✓
             页面含 6 个操作按钮、快捷指令、两处对话工具、审计区，且无 PHP 报错 ✓
业务数据：核心表行数前后一致 ✓

五、怎么用

打开「工作面板 → ③ 网站运维工具智能体」：

• 点 快捷指令 一键提问；点右侧 清空/复制/导出 管理对话；
• 需要动手时点下方 可执行实用工具（悬停可看说明与预计耗时），确认后立即执行并回显结果；
• 「最近操作审计」实时显示谁在什么时候做了什么。

v0.4.46（后台新增「工作面板」：云端模型接口 + Agent 智能体 + 网站运维工具智能体）

需求："在网站后台增加一个工作面板，内含云端模型调用接口以及 Agent 智能体，顺便写入网站运维工具智能体"。

一、入口

后台左侧导航顶层新增「工作面板」（紧随「总览」，admin/workbench.php），三个页签：

二、新增文件与实现要点

安全设计：运维工具全部只读（不写库、不删文件、不改配置）；不接受任意 SQL/命令/路径；密钥不回传前端。

三、验证 → A~C 57 项 + D/E/F 22 项，全绿

A. AiClient（桩传输，不打真实网络）
   endpoint 拼接 / 已含路径不重复拼接 / 请求体(model,messages,stream=false,temperature) / Bearer 鉴权头
   响应解析(choices[0].message.content + usage) / 密钥掩码 / 未配置提示
   错误映射：401 密钥无效、404 地址或模型名不存在、429 限流、非 JSON 响应、空内容、传输异常被捕获
   消息规范化 / 连通性测试 / saveSettings 校验(非法地址拒绝、超时夹到 300、温度夹到 2) / 配置已还原
B. OpsTools（真实数据、只读）
   10 个工具全部运行成功：磁盘使用 5.3%（118GB/剩余 111.78GB）、uploads 84.2MB、PHP 8.0.28 扩展齐备、
   授权告警 13/8、Go 服务心跳 3 秒前(端口 8080 HTTP 200)、最近 24h 上传 64 个文件、安全体检发现 2 项
   体检报告 Markdown 生成 / 未知工具被拒 / **核心表行数前后一致（只读性得到验证）**
C. OpsAgent
   规则模式：磁盘→disk_usage、报错→recent_errors、授权→license_status、上传→uploads_recent 全部命中
   「做一次站点体检」→ 直接跑 7 项体检（跳过模型）
   模型模式：桩模型请求工具 → 执行 disk_usage → 回喂 → `{"final":...}` 收口（共 2 次模型调用）
   容错：非法 JSON 自动纠正重试；步数用尽优雅收口；模型失败自动降级规则模式
D/E. 页面与端点
   管理员 200、三页签、10 个工具卡片、导航入口、页面无 PHP 报错；普通用户 302 跳登录
   端点：未登录 401 / 普通用户 403 / CSRF 错误 419 / 未知动作 404
   status 返回 10 个工具；ops_run 成功；ops_checkup 返回报告（level=error，正常 5 注意 1 异常 1）；
   model_test 未配置时给出明确中文提示（不 500）
F. 本轮修掉的真实缺陷
   ① go_service 曾显示"心跳 497677 小时前"——Go 服务写的是 epoch 字段，原代码读了 ISO 字符串 ts；
      已改为 epoch 优先 + 兼容毫秒/ISO/文件 mtime，现正确显示"心跳 3 秒前"
   ② recent_errors 的 5xx 统计曾在 CSRF token 里误匹配，**假阳性 243/300**；现只认状态码字段 → 0/512
   ③ 访问日志分支不再重复列出 *.error.log；磁盘信息增加 PowerShell 兜底（原账户下 disk_free_space 不可用）

四、怎么用

1. 后台左侧「工作面板」→ 页签①填 Base URL / API Key / 模型名 → 保存 → 测试连通；
2. 页签②按需改系统提示词与步数；
3. 页签③直接问"磁盘还剩多少？""最近有报错吗？""做一次站点体检"，或点工具卡片上的运行；
4. 未配置模型也能用：运维工具智能体会走关键词规则模式，体检报告照常生成。

v0.4.45（PC 端个人主页增加「退出登录」按钮）

需求："给 PC 端个人主页增加一个退出按钮"。

一、为什么之前 PC 端退不了

全站唯一的「退出登录」入口在 includes/header.php 的移动端下拉菜单里 （<a href="logout.php" class="nav-link-dropdown">退出登录</a>，容器 .main-nav-dropdown 仅在窄屏显示） → PC 端打开个人主页时确实没有任何退出按钮。

二、改动（仅 profile.php）

三、验证 → 15 / 15 通过

渲染检查（登录态真实请求 profile.php）
  HTTP 200 ✓  操作区存在 ✓  含「退出登录」→ logout.php ✓  带二次确认 ✓
  使用 profile-logout-btn 样式 ✓  原「编辑资料」保留 ✓  页面含样式规则 ✓
  顺序正确（编辑资料 → 管理后台 → 退出登录）✓  窄屏可换行 ✓
退出流程（独立测试会话，不影响任何人登录态）
  logout.php → 302 → index.php ✓
  退出后再访问 profile.php → 302 → login.php（会话已失效）✓
  服务端会话数据已清空/销毁 ✓
未登录访问个人主页 → 跳登录页 ✓

四、效果

• PC 端个人主页一眼可见「退出登录」，点一下（确认后）即退出并回到首页；
• 移动端行为不变（下拉菜单入口仍可用）；未登录用户看不到该按钮（个人主页会先跳登录页）。

v0.4.44（授权告警看门狗：在"锁定"之前先提醒你）

背景：你选择保持拦截 10123.vip（不加入白名单）。该域名的访问会持续计入 "5 天 8 次"计数，达到 8 次后用未授权域名访问的访客会看到 403 停机页。

一、本次新增

二、实测结论（本次核验）

当前计数状态：9 / 8（窗口起始 2026-10-10 20:32:50，约 5 天后自动重置） → 未授权域名访客会看到停机页（你的选择），你自己的域名与内网访问不受任何影响。

三、日常用法

# 查看当前状态（退出码 0/1/2/3/4 分级）
powershell -ExecutionPolicy Bypass -File qdcms-license-watch.ps1 -ListDomains

# 确认是误访/爬虫后，人工复位计数（会自动备份原值）
powershell -ExecutionPolicy Bypass -File qdcms-license-watch.ps1 -Clear

v0.4.43（商业授权：增加本地局域网 IP）

需求："给网站域名商业授权增加本地局域网 ip 地址"。

一、改动

说明：授权状态本身未变 —— 绑定域名仍为 10123.xn--fiqs8s（10123.中国），本次只是扩充白名单。

二、验证（真实 HTTP + 判定矩阵）→ 31 / 32 通过（唯一未过项见下）

放行矩阵（14/14 通过）：192.168.0.100、192.168.0.100:65500、192.168.0.1/254、192.168.5.9、
                        127.0.0.1、127.0.0.1:80、10.0.0.7、172.16.5.9、172.31.255.1、169.254.1.1、
                        localhost、localhost:65500、::1
拦截矩阵（6/6 通过）：10123.vip、evil.com、192.168.0.100.evil.com、192.16.0.100、11.0.0.1、172.32.0.1
checkDomain：192.168.0.100 / 127.0.0.1 / localhost → 有效（本地或白名单访问）
             10123.vip → 仍无效（**授权守卫未被削弱**）
真实 HTTP：Host 192.168.0.100 / 192.168.0.100:65500 / 127.0.0.1 → 200 + 完整首页 38,722 B + 无告警
           **内网访问没有产生任何告警计数** ✓（关键验收）
           陌生域名（10123.vip:65500）→ 正常计数并弹窗（守卫仍生效），验证后已复位计数
未过项：Host 192.168.5.9 在**改动前**的旧 vhost 下仍落到默认站（612 B）—— 本次已通过 nginx 正则
        server_name 解决，待重载配置后生效

三、你需要做的

1. 无需重启 PHP；授权白名单改动立即生效。
2. 让「整个局域网网段」都能直接访问：宝塔 → 网站 → 设置 → 重载配置（或 Nginx 重载）。仅此一步需要你点。

v0.4.42（修复聊天发送视频后气泡消失 / 回显缓慢或看不到）

现象：聊天里发送视频，上传成功后气泡消失，视频要过一会儿才回来（有时一直不出现）。

一、根因：接口响应没返回新消息 id

→ 于是出现："上传 100% → 气泡消失 → 视频过几秒才回来（轮询错过就一直不回来）"。 实测服务端处理仅 0.65 秒，慢的完全是前端等轮询。

二、修复

三、验证

A. 真实发送聊天视频（真实 HTTP + FFmpeg 视频）→ 全通过

发送耗时 0.65s，响应带 "id":287 ✓
数据库存在该消息 ✓  media_type=video ✓  收发方正确 ✓
库中 media_url 与响应一致 ✓   视频文件落盘且 HTTP 可访问 ✓   封面存在 ✓
测试消息与文件已清理 ✓

B. 前端分支（Node + DOM/XHR 桩，跑真实 chat.js）→ 12 / 12 通过

带 id：气泡被**原地替换**（outerHTML）✓  未删除气泡 ✓  替换内容含真实地址与 data-msg-id=287 ✓
        不触发多余的整体拉取 ✓
缺 id：**不删气泡** ✓  气泡仍在消息区 ✓  显示"已发送，正在同步…" ✓  主动拉回真实消息 ✓
失败响应：气泡保留（可重试）✓

四、效果

• 发送视频/图片成功后，气泡当场变成真实消息（含真实地址与 data-msg-id），无需等 4 秒轮询；
• 即使接口异常缺 id，气泡也不再消失，而是自动补拉真实消息；
• 顺带修正：data-msg-id 之前是 undefined（缺 id 导致），现在正确 → 媒体缓存/播放进度记录恢复正常。

v0.4.41（优化聊天插件"发送方视频气泡过宽"）

需求："优化聊天插件发送方视频气泡显示过宽的问题"。

一、根因（三点叠加）

二、修复

尺寸推算（修复后）

三、验证（Node + DOM 桩，真实渲染函数 + 真实 CSS）→ 30 / 30 通过

发送方视频：气泡带 .media、包裹层带 .msg-body、video 无内联 width:100%  ✓
接收方视频 / 流式地址分支 / 付费墙分支：同样带 .media，已读回执与付费按钮保留 ✓
图片消息：带 .media ✓     文案消息：不带 .media（内边距不变）✓
CSS：media 内边距 4px ✓  msg-body min-width:0 ✓  fit-content ✓  视频 200×260 ✓
     旧 240px 规则已移除 ✓  图片 200×200 ✓  小屏 168×220 / 168×168 ✓  花括号配平 ✓
尺寸推算：竖屏 146×260 ✓  横屏 200×112 ✓  方形 200×200 ✓  小屏竖屏 124×220 ✓

四、效果

• 发送方（也含接收方）视频气泡只比视频大 8px，不再有 24px 空白；
• 竖屏视频宽度约为屏幕的 40%（旧实现约 73%），聊天区观感与微信一致；
• 小屏再自动收一档；文案消息、已读回执、付费按钮、播放进度缓存等行为全部不变。

v0.4.40（新增视频分片上传：彻底规避 504 网关超时）

现象：手机经域名上传短视频时报 服务器返回异常（HTTP 504）。

一、定位：504 不是本机 nginx 打的

根因：单请求上传大文件要持续几十秒到数分钟，链路上任意一层网关超时都会 504。 治本方案：把大文件切成 ≤4MB 分片，每个请求都在几秒内完成 → 免疫任何网关超时。

二、本次改动

三、验证

A. 分片端点端到端（真实 HTTP + 真实 FFmpeg 视频） → 全通过：

3 片逐片上传 → received 1/2/3 → done:true + token
合并文件 sha256 与源文件**完全一致** ✓   分片文件已自动清理 ✓
凭 upload_token 发布 → {"success":true,"moment_id":"22"} ✓
落盘 uploads/moments/2026/10/moment_v_*.mp4（大小与源一致）✓   临时目录已清理 ✓
边界：非法 upload_id / CSRF 错误 / 越界 index / 单片 >4MB  → 全部正确拒绝 ✓
GC：把过期目录的内部文件时间设为 3 小时前 → 下一次请求自动清除 ✓

B. 渲染与语法：页面含分片分支与 upload_token、仍正确引入进度脚本、内联 JS node --check 通过 ✓ C. 数据卫生：测试动态/媒体/分类/临时目录全部清理（moments 17 条 = 用户真实发布 ✓）

四、效果

• 手机经域名上传 → 每片几秒完成，不会再出现 504；进度条按分片推进（第 x/y 片）；
• 分片失败自动重试 2 次；全部分片合并后才进入"服务器处理中（转码/截图）"阶段；
• 小文件（≤4MB）行为与之前完全一致，无额外请求。

五、附：可选的更彻底做法

若希望连"上传"这一步都完全不经过域名链路，可让手机在局域网直接访问 http://192.168.0.100/post-video.php（同 WiFi 时最快，且完全绕开前置网关）。

v0.4.39（修复聊天插件"靓号特效"不显示）

需求："修复聊天插件靓号特效显示失败的问题"。

一、根因：特效样式进不了插件的 Shadow DOM

→ 结论：不是数据问题，是插件缺样式 + 缺类名。

二、修复内容

三、验证（Node + DOM 桩，用真实 IMPretty 与真实渲染函数）→ 39 / 39 通过

判定规则：10000 / 123456 / 999999 → 靓号 ✓    9999 / 1000000 / 0 / null → 非靓号 ✓
         563474767、403742444（九位）→ 非靓号 ✓（与站内 numberText 规则一致）
聊天联系人：靓号头像 <div class="im-avatar-placeholder vip-active">站</div> + 流光号码 ✓
           九位普通号 → 无 vip-active/pretty-number ✓
消息头像：对方靓号 ✓  自己（AGENT_CONFIG.userNumber=10000）✓  普通号 ✗（无特效）✓
好友项 / 搜索结果 / 站内信：靓号带特效 ✓，普通号与系统消息不带 ✓
插件样式表：含 conic-gradient、@keyframes imVipRainbowSpin、mask 长属性、花括号配平 12/12 ✓
资源登记：im-sdk.js cssFiles ✓  tab-card.js 预取列表 ✓  IM_BUILD 已递增 ✓

四、顺带发现（需要你确认）

站内对"靓号"的判定是 10000 ~ 999999（includes/fn-user.php 的 numberText() / userDisplayName()）。 当前三个账号的号码是：

所以这三个账号里只有站长会看到特效；若你希望其它账号也有特效，需要把它们的号码换成 10000~999999 区间的靓号（后台「靓号管理」/号池分配），这与本次修复无关。

v0.4.38（修复：短视频上传一直卡在"上传中"）

需求："修复短视频上传时一直卡在上传状态"。

一、根因：上传进度脚本从未被引入页面（v0.4.34 的漏插）

排查链条：

1. 访问日志里 17:42 之后没有任何 POST /post-video.php → 说明浏览器根本没发出上传请求；
2. C:\Temp（PHP 上传临时目录）无进行中的临时文件 → 也不是"正在上传"；
3. 服务端渲染结果里，upload-progress.js 只出现在HTML 注释里， 没有独立的 <script src="...upload-progress.js"> 标签；
4. 于是页面执行到 QdUpload.submit(...) → ReferenceError（QdUpload is not defined）， 而按钮在此前一行已被置为 发布中... → 界面永远停在"上传中"，请求从未发出。

漏插原因（我方缺陷）：v0.4.34 的补丁里，插入脚本标签前用了 if 'upload-progress.js' not in t: 作为守卫，而同一补丁早前已插入的注释里恰好含这串文字 → 整段插入被静默跳过；随后的自检又用 'upload-progress.js' in t 判断（同样被注释命中）→ 假通过。

二、修复内容

三、验证

A. 提交路径回归测试（test-post-video-submit.js，直接跑服务端渲染出的内联脚本）→ 15 / 15 通过：

场景 1 QdUpload 可用        → 调 QdUpload.submit、按钮禁用、未走 fetch           ✅
场景 2 QdUpload 缺失（本次故障原形）→ 自动回退 fetch、POST 成功并跳转播放页        ✅ ← 关键
场景 3 QdUpload.submit 抛异常 → 捕获、按钮恢复"发布"、显示"提交异常：boom"        ✅
场景 4 兜底 fetch 业务失败   → 按钮恢复 + 显示"视频大小不能超过 50MB"             ✅
场景 5 兜底 fetch 网络异常   → 按钮恢复 + 显示"网络错误: …"                      ✅
场景 6 submit 非函数         → 同样走兜底                                        ✅

B. 线上验证（严格正则匹配真实标签，不再被注释骗过）→ 11 / 11 通过：

四、经验教训与流程改进

本次自检之所以"假通过"，是用子串匹配判断"页面已引入脚本"，而注释里也含同样文字。 现已统一改为严格标签正则 /<script[^>]+src="[^"]*upload-progress\.js[^"]*"[^>]*><\/script>/， 并对三个上传页逐页复检（本次验证 B 部分即用此法）。

v0.4.37（修复：从好友列表进入聊天窗口不同步聊天历史）

需求："修复聊天插件好友列表进入聊天窗口没有同步聊天历史记录"。

一、根因（两个叠加缺陷）

二、修复内容

三、验证（Node + DOM/网络桩，驱动真实模块代码）

qdcms-release/test-chat-history-sync.js → 17 / 17 通过：

场景 1（原缺陷复现点）：A 会话加载中 → 立刻打开 B
  [PASS] A 的历史请求已发出 → [1]
  [PASS] 切到 B 后 B 的历史请求**仍然发出**（修复核心） → 请求序列 chat_with=[1,2]
场景 2：过期响应不得串话
  [PASS] B 的消息已渲染（2 条）        [PASS] A 的过期响应被丢弃（B 的 2 条仍在）
  [PASS] 加载标志未卡死
场景 3：_openChat 重置状态
  [PASS] 重置加载标志 / 递增令牌（1 → 3）/ 新会话请求已发出（chat_with=5）
  [PASS] 新会话消息已渲染 / 旧会话响应仍被丢弃
场景 4：模块未挂载竞态
  [PASS] 未挂载时记录待打开、不发请求 → init 后自动打开并补发历史请求（chat_with=7）、靓号带入

反向验证（把第 1 条改回旧的"单一布尔锁"再跑）：立即出现 [FAIL] 切到 B 后 B 的历史请求仍然发出 → 请求序列 chat_with=[1]、 [FAIL] B 的消息已渲染 → 渲染 0 条 —— 与用户描述的现象完全一致，证明测试确实覆盖该缺陷。

线上核对：chat.js（同会话去重字段 / 请求令牌 / 过期丢弃 / 未挂载挂起）、im-sdk.js（插件级 openChatWith）、friends.js（改用插件 API）6 / 6 关键改动就位；三个资源 HTTP 200；首页 200 ✅

四、效果

• 从好友列表点「💬 发消息」→ 一定会切到聊天窗口并加载该好友的完整历史（即使聊天模块还在加载中）；
• 快速在多个会话间切换 → 不会串话（旧响应被丢弃）、不会卡在"加载中"；
• 修复同时覆盖了"发送视频后返回列表再进入"的历史卡死路径（_loadingMessages 不再残留）。

v0.4.36（修复聊天插件"靓号失效"）

需求："修复聊天插件靓号失效问题"。

一、排查结论：服务端全对，问题在插件前端"没把靓号传/显示出来"

→ 结论："靓号失效"= 前端接线缺陷（显示回落成普通 id），不是号码数据或接口问题。

二、修复内容

三、验证

四、效果

• 插件里点好友"发消息" → 聊天头部显示 ID: 403742444（此前显示 ID: 3）；
• 从其它入口打开聊天（未带号码）→ 自动补取后同样显示靓号；
• 站内信列表/详情显示发送者靓号；
• 页面脚本可读 window.AGENT_CONFIG.userNumber 显示"我的靓号"。

v0.4.35（个人资料页「站内信 / 好友 / 聊天」改为打开新版 IM 插件浮层）

需求："修复个人资料页站内信，好友，聊天三个链接点击后进入老聊天插件，没有进入新聊天插件"。

一、问题定位

二、修复方案：新增 assets/im-plugin/core/im-links.js

一个全站通用的链接接管脚本（事件委托，一次监听全局生效）：

三、接入点

四、验证

说明：Tab 标识与插件模块一致（messages / chat / friends，默认进入 chat）， 与站内浮动聊天按钮（tab-card）打开的是同一个浮层插件。

v0.4.34（短视频 / 短剧上传页新增真实上传进度条）

需求："给短视频和短剧上传页面增加上传进度条显示"。

一、为什么不能沿用 fetch

fetch() 无法获取"已上传字节数"（只能等到响应返回），浏览器里唯一能给真实上传进度的是 XMLHttpRequest 的 xhr.upload.onprogress。因此本次新增通用组件并改造提交方式。

二、新增：assets/js/upload-progress.js（通用上传进度条）

用法：

QdUpload.attach(formEl, { box: '#uploadProgress', button: btn, timeout: 1800000,
                          onSuccess: function (d) { location.href = d.redirect; } });

三、三个页面接入

踩坑记录（已修）：这两个短剧页在文件顶部就 require header.php，整页 HTML 已进入输出缓冲； 若直接 echo json_encode(...)，响应会变成「HTML + JSON」导致前端 JSON.parse 失败。 因此新增 dramaUploadJson() 助手：先 ob_end_clean() 清空缓冲再输出 JSON 并 exit。

顺带统一：短剧剧集（上传与追加）也接入 convertVideoToMp4() —— MOV/MKV/AVI 等容器会自动转封装/转码为 MP4， 与短视频动态保持一致（此前短剧允许 mkv/mov 却原样落盘，浏览器可能无法播放）。

四、验证

本次改动不需要重启 PHP / 重载 nginx（纯 PHP + JS）。 但 v0.4.33 的 15 分钟超时配置仍需你在宝塔执行一次「PHP 8.0 重启 + Nginx 重载配置」才生效。

v0.4.33（短视频上传：支持 MOV/MKV/AVI 等自动转 MP4；超时对齐 15 分钟）

需求："检测网站短视频上传报错"。结论：上传功能本身正常（14 次提交：200 ×10 / 499 ×3 / 400 ×1）， 报错来自格式与体积限制以及弱网超时，本次针对性修复。

一、体检结论

报错成因（按出现概率）：

1. 格式不支持：只接受 video/mp4、video/webm → 手机下载来的 MKV / MOV / AVI / TS 会被拒： xxx.mkv 不是支持的视频格式（仅支持 MP4 / WebM）；
2. 体积超限：超过 50MB → xxx 超过 50MB 限制（而 php/nginx 允许到 500M/600M，限制在业务层）；
3. 弱网超时：前端 AbortController 5 分钟 + PHP/FastCGI 300s → 手机上传大文件超时中断（日志里的 499）。

二、修复内容

三、验证（真实端到端）

用 ffmpeg 生成 2 秒 H.264+AAC 测试视频 → 转封装为 .mkv → 通过真实登录会话上传：

POST /post-video.php（media[]=vtest_upload.mkv;type=video/x-matroska）
→ {"success":true,"moment_id":"18","redirect":"video-play.php?id=18&index=0"}   ✅

落盘：uploads/moments/2026/10/moment_v_1791626149_9548.mp4（30,579 B，扩展名已是 .mp4）✅
ffprobe：h264,video / aac,audio； duration=2.001；format=mov,mp4,m4a,3gp,3g2,mj2 ✅
同目录残留 .mkv：0 个 ✅   封面已生成：uploads/covers/moments/thumb_1791626150_5795.jpg ✅

测试数据已全部清理：moment 18、moment_media 记录、视频文件、封面、测试分类均已删除， moments 恢复 16 条 / moment_media 20 条，上传目录无残留、无遗留 ffmpeg 进程 ✅

四、需要用户操作（生效用）

1. 宝塔 → 软件商店 → PHP 8.0 → 重启（max_execution_time/max_input_time = 900 生效）；
2. 宝塔 → 软件商店 → Nginx → 重载配置（fastcgi_*_timeout = 900 与 fastcgi_request_buffering off 生效）。

可选项：若希望放宽单视频 50MB 限制，改 includes/fn-moments.php 第 22 行 define('MOMENT_VIDEO_MAX_SIZE', 50 * 1024 * 1024) 即可（php/nginx 已允许到 500M/600M）； 但手机弱网下上传体积越大越易失败，建议同时考虑保持 50MB 并提示用户压缩。

v0.4.32（错误日志体检：清理历史噪音、补齐 favicon/robots、日志分流与 PHP 日志落地）

需求："检测网站错误日志"。范围：10123.xn--fiqs8s.error.log（2596 行 / 793 KB，覆盖 10-02 ~ 10-10） 与访问日志近 5000 条。

一、体检结论：站点健康，无致命错误

404 占比：近 5000 条访问中 404 有 2458 条（49%），绝大多数是自动化漏洞扫描（/wp-content/...、/.env、/chosen.php、/1.php 等）， 属正常现象；403 共 336 条，其中 210 条是 GET /（带 WP 风格参数）—— 站点安全层正常拦截。

二、/im-stream 458 条的成因（已确认非故障）

• nginx 侧 SSE 代理配置完全正确（proxy_buffering off、proxy_read_timeout 3600s、gzip off 等）；
• Go 侧 im_sse.go 亦正确（text/event-stream、X-Accel-Buffering: no、20 秒心跳、Flush()、客户端断开即 return）；
• 实证：ajax-im-token.php 今日调用 242 次、中位间隔 11 秒，每次换新令牌都会关闭旧事件流 → nginx 便记录一条 "upstream prematurely closed"。属于 SSE 正常重连的副产物。

处理：在该 location 内把这类日志分流到独立文件并只记 crit，主错误日志从此清爽：

location = /im-stream {
    error_log D:/BtSoft/wwwlogs/im-stream.error.log crit;
    ...
}

三、本次修复

四、验证

五、需要用户点击生效的两项

1. 宝塔面板 → 网站 → 设置 → 配置文件 → 保存/重载（或 软件商店 → Nginx → 重载配置） —— 让 /im-stream 日志分流生效（nginx -s reload 需管理员权限，命令行被拒 Access is denied）；
2. 宝塔 → 软件商店 → PHP 8.0 → 重启 —— 让 error_log 指向文件生效（此后 PHP 报错会写入 D:/BtSoft/php/80/logs/php_errors.log）。

另可选（生产建议）：把 display_errors 关掉，避免报错信息直接显示给访客（与上面同一次重启即可生效）。

v0.4.31（修复手机脚本 ReferenceError：screenOnOk 未定义；新增脚本端到端桩测试）

用户报错：错误: ReferenceError: "screenOnOk" 未定义。 性质：v2.8 引入的作用域缺陷（我方 bug），已修复并补上自动测试防止复发。

一、根因

v2.8 我把"屏幕常亮"的变量声明写在了 main() 函数内部：

function main() {
    var screenOnOk = false;     // ← 只属于 main 的作用域
    ...
}
function sendHeartbeat() {
    ... screen: screenOnOk ? 1 : 0   // ← 另一个函数里引用 → ReferenceError
}

而 wakeLockOk / foregroundOk / stableModeOk / notifSeen / lastHbAt 都是模块级声明， 唯独 screenOnOk 漏在了函数内 → 每次发心跳就抛 ReferenceError， 脚本启动后立刻中断（心跳发出前就报错），照旧收不到回执。

二、修复（v2.8.1）

• 把 var screenOnOk = false; 移到模块级（与其它状态变量并列），main() 内只做赋值；
• 静态检查：sendHeartbeat() 引用的 6 个状态变量全部在顶层声明 ✓；
• node --check 通过 ✓。

三、新增：脚本端到端桩测试（qdcms-release/test-listener.js）

用 Node + AutoX.js API 桩（http / events / device / $settings / storages / files / Packages / context） 把手机脚本完整跑一遍，无需真机即可捕获"只在手机上才暴露"的错误：

反向验证（把 bug 精确还原后再跑）：测试立即报 [FAIL] 脚本启动无异常 → screenOnOk is not defined（5 项失败，退出码 1） —— 与用户在手机上看到的报错完全一致，证明该测试确实能拦住此类缺陷。

v0.4.30（手机脚本 v2.8：内置屏幕常亮保活）

需求："再次检测手机脚本"。检测结论：脚本功能全正常（ver=2.7、wake=1、心跳按 1.7~3.1 分钟稳定上报）， 唯独 fg=0 / stable=0 —— AutoX.js 的「前台服务 / 稳定模式」在该机型上无法通过脚本设置生效 （重启脚本后依然为 0）。既然 API 开关不生效，v2.8 直接内置最确定有效的兜底。

一、本次检测（03:29:56 心跳）

{"type":"heartbeat","device":"收款手机","ver":"2.7","notif":0,"gap":0,"wake":1,"fg":0,"stable":0}

二、v2.8 改动

为什么用它：PARTIAL_WAKE_LOCK 只能防"CPU 休眠"，防不住系统杀进程； 而"屏幕常亮 + 充电"会让 App 处于前台活跃状态，是该机型上最可靠的保活方式。

三、验证标准

换 v2.8 后（插上充电器），自检页心跳报文应为：

{"type":"heartbeat","device":"收款手机","ver":"2.8","notif":N,"gap":2~4,"wake":1,"fg":0/1,"stable":0/1,"screen":1}

screen:1 且 gap 稳定在 2~4 分钟 → 保活到位；随后收款即可产生回执并自动入账。

v0.4.29（手机脚本 v2.7：稳定模式保活；实测"进程被反复杀掉"）

需求："检测手机脚本"。本次诊断出关键性质变化：不是"冻结"，而是进程被系统反复杀掉。

一、实测（03:25:08 心跳报文）

{"type":"heartbeat","device":"收款手机","ver":"2.6","notif":0,"gap":0,"wake":1,"fg":0}

心跳间隔：02:27~02:28 → 02:37 → 02:49 → 03:06 → 03:11 → 03:25（间隔 4~17 分钟且 gap=0）。 → Android 16 + OriginOS 在持续清理 AutoX.js 后台进程；脚本活不过 3 分钟心跳周期，自然收不到收款通知。

二、v2.7 改动

三、手机上必须打开的两个开关（否则一定会被杀）

1. AutoX.js → 设置 → 打开「稳定模式」+「前台服务」；并在 系统 → 通知 → 允许 AutoX.js 发送通知 （前台服务依赖通知权限，缺它就永远是 fg:0）；
2. Vivo/OriginOS：设置 → 电池 → 后台耗电管理 → AutoX.js → 允许后台高耗电； 应用自启动允许；多任务界面加锁；关闭「睡眠模式 / 超级省电」。

兜底方案（任一即可，效果立竿见影）：

• 收款手机长期插电 + 屏幕常亮（开发者选项 →「充电时屏幕不休眠」）；
• 或换一台不装其他应用的旧手机专跑本脚本（白名单更干净）；
• 或改用站点内置的官方支付网关（支付宝/微信 APIv3），不需要手机即可自动到账。

四、验证标准

换 v2.7 后，自检页心跳报文应为：

{"type":"heartbeat","device":"收款手机","ver":"2.7","notif":N,"gap":2~4,"wake":1,"fg":1,"stable":1}

fg:1 且 stable:1 且 gap 稳定在 2~4 分钟 → 保活到位，之后收款才能收到回执。

v0.4.28（手机脚本 v2.6：前台服务复检与指引；v2.5 状态实测）

需求："检测手机脚本"。本次从服务端直接读到手机脚本的自检数据（v2.5 起心跳携带诊断字段）。

一、手机脚本实测状态（03:11:03 心跳报文）

{"type":"heartbeat","device":"收款手机","ver":"2.5","notif":0,"gap":0,"wake":1,"fg":0}

心跳时间线：02:27~02:28（启动）、02:37、02:49、03:06:51、03:11:03； 03:11 之后（至 03:17）无新心跳 → 仍需解决前台服务/白名单，否则会继续被冻结。

二、v2.6 改动

三、下一步（用户操作）

1. 换 v2.6 脚本运行；日志若出现「前台服务未生效」→ 按提示在 AutoX.js 内开启并允许通知权限；
2. Vivo/OriginOS：设置 → 电池 → 后台耗电管理 → AutoX.js → 允许后台高耗电；自启动允许；多任务加锁；
3. 刷新自检页确认心跳报文变为 "ver":"2.6","wake":1,"fg":1，且 gap 稳定在 2~4 分钟（不再被冻结）；
4. 然后在脚本运行期间收款一笔（例如与订单 #17 金额一致的 8.00 元）→ 站点应出现回执并自动入账。

v0.4.27（手机脚本 v2.5：心跳携带诊断信息，可远程判断脚本状态）

需求："检测手机脚本状态"。 结论：脚本在运行但仍被系统冻结 —— 心跳间隔 9.3 → 12.6 → 16.9 分钟（设定 3 分钟）， 且回执与"通知样本"均为 0 → 息屏期间通知仍被漏掉。

一、本次检测证据（心跳间隔分析）

心跳只在"手机被使用/亮屏"时出现 → JS 定时器与通知回调仍被系统挂起， 说明 v2.4 的前台服务/唤醒锁在该机型上未生效（或手机上尚未换成 v2.4）。

二、v2.5 的改进：把手机状态"上报"到服务端

心跳报文新增诊断字段（会完整显示在站点自检页的「请求体」里）：

实测：心跳带 ver=2.5,notif=3,gap=17,wake=1,fg=1 → HTTP 200，诊断字段完整落库 ✓

三、结论与下一步

1. 换 v2.5 脚本后，先看自检页的「请求体」：

• wake:0 或 fg:0 → 唤醒锁/前台服务没拿到（多为系统权限限制）；
• ver 不是 2.5 → 手机上还是旧脚本；
• notif:0 且收款后仍为 0 → 通知未进脚本（权限/微信通知被关）。

1. 必须放开 Vivo/OriginOS 后台限制（否则唤醒锁也会被系统回收）： 设置 → 电池 → 后台耗电管理 → AutoX.js → 允许后台高耗电；应用自启动允许；多任务加锁； AutoX.js 内开启前台服务；关闭睡眠模式/超级省电。
2. 最省心的替代方案：让收款手机长期插电并保持屏幕常亮 （开发者选项 → "充电时屏幕不休眠"），这样 JS 不会被挂起；或改用站点内置的官方支付网关（无需手机）。

v0.4.26（手机脚本 v2.4：前台服务 + 唤醒锁，根治"息屏漏收款通知"）

场景：连续两次"收款 10 元，动态码页无动静"。 根因找到了：手机脚本被 Android 息屏冻结（Doze），收款通知正好落在冻结期被漏掉。

一、决定性证据：心跳间隔异常

脚本设定的是每 3 分钟一次心跳，实际却是 9~12 分钟 → 典型的 Doze/后台冻结： 进程还活着，但 JS 定时器与通知回调被系统挂起，冻结期间到达的微信收款通知会直接丢失 ✗。 两次收款（很可能发生在 02:3x、02:4x）正好落在这些"冻结窗口"里。

同时：站点侧没有任何 receipt 请求、也没有通知样本 → 证明通知根本没进脚本（不是关键词问题）。

二、v2.4 的修复

三、仍需在手机上确认的系统设置（Vivo / OriginOS 尤其重要）

1. 设置 → 电池 → 后台耗电管理 → AutoX.js → 选「允许后台高耗电」；
2. 设置 → 应用与权限 → 权限管理 → 自启动 → AutoX.js 允许；
3. 多任务界面下拉 AutoX.js 卡片 → 加锁（防一键清理）；
4. AutoX.js 内 → 设置 → 开启「前台服务」；
5. 关闭系统的「睡眠模式/超级省电」。

四、验证方式

换 v2.4 脚本后，日志应出现：

已开启前台服务（通知栏常驻，防系统冻结）
已获取部分唤醒锁（息屏后脚本仍运行）
[心跳] 已上报，站点应答 {"ok":true,...}        ← 应每 3 分钟稳定出现

之后收款一笔（建议 10.00 元，与订单 #7 金额一致）→ 站点应在数秒内出现回执并自动入账； 若仍出现"脚本曾被系统冻结"告警，说明系统设置还没放开，按上面第 3 节逐项检查。

长期建议：若你的收款渠道支持官方接口（支付宝/微信 APIv3），可以用站点已内置的官方支付网关， 完全不需要手机即可自动到账（后台「在线支付订单/支付设置」里配置）。

v0.4.25（远程诊断：未识别的微信通知原文可回传站点）

场景：实收 10 元，动态码页无动静。 排查：手机脚本在运行（02:49:58 心跳正常，设备名"收款手机"），但没有任何 receipt 请求 → 说明"收款通知没有被脚本捕获/识别"。此前只能靠手机日志判断，本版打通远程诊断。

一、本次证据

→ 结论：服务端与页面都正常，卡在"手机没把这条收款通知报上来"。

二、新增能力（本版）

三、验证

四、下一步（用户操作）

1. 换成 v2.3 脚本运行；
2. 在脚本运行期间再收一笔（脚本看不到启动之前的历史通知）；
3. 结果判读：

• 诊断日志出现「通知样本…」→ 通知到了手机但关键词没匹配，把原文发来即可校准（我已能看到）；
• 诊断日志连样本都没有 → 通知根本没进脚本（通知使用权未授予 / 微信通知被关闭）；
• 出现 receipt 记录 → 已正常，将自动入账。

v0.4.24（手机脚本 v2.2：通知使用权自检 + 通知捕获统计）

场景：用户实收 10 元，但站点没有回执。 排查结论：手机脚本完全没有上报"回执"（排障日志里只有心跳，没有一条 receipt）； 且手机心跳自 02:37:22 后中断 → 脚本未在运行 / 未捕获到收款通知。 本版给手机脚本加上"通知侧"的自检与统计，让这类问题一眼可判。

一、本次排查证据

→ 结论：服务端没问题，卡在"手机没把这条收款通知报上来"。

二、手机脚本 v2.2 的加固

三、需要用户配合的动作

1. 用 v2.2 脚本覆盖手机上现有脚本，重新运行；
2. 日志必须出现 已开启微信通知监听 —— 若出现 无法开启通知监听，先授予通知使用权；
3. 保持脚本运行（AutoX.js 开前台服务、系统关闭电池优化、锁定后台任务）；
4. 再收一笔款 → 刷新自检页看「最近上报尝试」是否出现 receipt 记录；
5. 若日志里出现 [微信通知 #N] ... 但脚本判定为"非收款通知"，把该行原文发来即可校准关键词。

v0.4.23（修复动态码页轮询：刷新可见 + 修掉 2 个 JS 缺陷）

现象：动态码页写着"页面每 5 秒自动刷新"，但看起来并没有刷新。 结论：轮询一直在正常请求（nginx 日志每 5 秒一条 GET /payment-receipt.php?order_id=N 200）， 问题出在前端脚本——数据没变化时画面文字也不变，而且脚本里有两处缺陷。

一、实测（先确认"到底有没有刷新"）

02:37:46 / 02:37:51 / 02:37:56 / 02:38:01 …  每 5 秒一条
127.0.0.1 GET /payment-receipt.php?order_id=7 → 200

响应体（gzip 后 228 字节，解压后 355 字节）：

{"ok":true,"enabled":true,"order_id":7,"receipt":null,"device_online":true,
 "device_last_seen":"2026-10-03 02:37:22","device_name":"V2232A","server_time":"…"}

→ 接口正常、轮询正常；但页面没有任何"刷新过"的视觉反馈，数据不变时看起来就像卡住了。

二、修复的三件事

另外：刷新失败不再静默吞掉 —— 连续 3 个周期（15 秒）没成功刷新时，提示条会变红显示"…——刷新异常，正在重试…"； 控制台也会打印 [wxReceipt] 刷新失败：…，便于排查登录过期 / 网络问题。

三、验证

内联 JS 语法：node --check → 全部通过 ✓（修复前报 missing ) after argument list）

轮询行为（Node + DOM 桩，qdcms-release/test-polling.js）→ 9 / 9 通过：

[PASS] 轮询脚本加载无异常（无 pollTimer 之类的 ReferenceError）
[PASS] 状态文字显示"尚未收到回执"
[PASS] 状态文字显示真机在线与设备名（监听设备在线（V2232A…））
[PASS] 已插入"最后更新"提示条元素
[PASS] 存在 1 秒刷新提示定时器
[PASS] 提示条显示"最后更新：2 秒前（每 5 秒自动刷新）｜服务器时间 …"
[PASS] 刷新失败时提示条可见（刷新异常，正在重试）
[PASS] 收到已入账回执时显示"已自动入账"
[PASS] 已到账后停止轮询（clearInterval 被调用）

线上页面：HTTP 200，页面已含 wxReceiptTick / 「最后更新」提示条 ✓

四、请做一次强制刷新

浏览器可能缓存了旧页面脚本，请按 Ctrl + F5（手机：下拉刷新/清缓存）后再看动态码页 —— 页面底部会出现 "最后更新：X 秒前（每 5 秒自动刷新）"，数字每秒跳动，即代表实时刷新正常。

v0.4.22（修复：动态码页"监听设备"显示成测试名）

现象：个人支付动态码页刷新后，"监听设备"一直显示 模拟真机心跳（而不是手机真机）。 性质：显示逻辑缺陷 + 开发排障数据污染，已修正并清理。

一、原因

动态码页轮询 payment-receipt.php?order_id=N，其中 device_name/device_last_seen/device_online 直接取 settings.wxpay_receipt_last_device / last_seen —— 而这两个 key 是可变的： 任何一次心跳都会覆盖它，包括开发者排障时发的测试心跳（本例就是 模拟真机心跳） 和自检页的"一键模拟上报"。

二、修复

三、验证（线上实测）

修复前：动态码页显示 模拟真机心跳（开发者测试名），last_seen=02:31:33

修复后（payment-receipt.php?order_id=7 实际应答）：

{"ok":true,"enabled":true,"order_id":7,"order_status":0,"amount":"10.00",
 "device_online":true,"device_last_seen":"2026-10-03 02:28:03","device_name":"V2232A", ...}

说明：设备"在线"窗口为 10 分钟。手机脚本每 3 分钟发一次心跳； 若超过 10 分钟没有新心跳，页面会（正确地）显示"离线"——这可以帮助判断脚本是否还在运行。

v0.4.21（手机上报已打通；修正"服务器自检"覆盖真机在线状态的问题）

性质：修复 + 排障收尾。需求："是否收到回执"。 结论：手机上报通道已完全打通（手机心跳三次全部 HTTP 200）；尚未收到"回执" —— 回执需要真实微信收款到账通知被手机捕获。

一、本次证据（手机已成功上报）

192.168.0.104 POST /payment-receipt.php 200  02:27:16   ← 手机（okhttp/4.10.0）心跳成功
192.168.0.104 POST /payment-receipt.php 200  02:27:50
192.168.0.104 POST /payment-receipt.php 200  02:28:03

排障日志同步记录（wxpay_receipt_attempts）：

→ v2.1 脚本的"显式 JSON body"生效，400 已消失、鉴权通过 ✓ → 回执（receipt）条数为 0：说明还没有微信收款通知被手机捕获（不是通道问题）

二、本次修复：服务器自检不再抢占"监听设备"

自检页「一键模拟上报」是服务器自己发的，但它也刷新了"监听设备/最后心跳"， 于是页面显示成"服务器自检"，把真机是否在线盖掉了。

三、验证

四、要"收到回执"需要做什么

需要有真实的微信收款到账通知：

1. 保持手机脚本运行（现在心跳正常，说明在跑）；
2. 用另一个微信扫你的收款码付一笔（建议 0.01 元，或与某笔待审核订单金额完全相同的数额）；
3. 刷新自检页 → 「近 24 小时回执」应变为 1，且「最近上报尝试」会出现一条回执记录；
4. 金额与某笔待审订单唯一匹配时，自动入账会立即生效（后台「收款码解析」可看到记录）。

若付了款仍无回执：把手机 DEBUG: true 日志里的 [微信通知] ... 几行发来，据此校准 INCLUDE / ANCHOR 关键词（微信"收款到账"通知的实际文案各地略有差异）。

v0.4.20（排障补全：记录 Content-Type + 请求体密钥脱敏 + 手机脚本 v2.1）

性质：排障能力补全 + 手机脚本加固。场景：手机上报已从 401（鉴权）前进到 400（请求体）， 需要看清"手机到底发了什么"。

一、本次「再次检测」结论

→ 服务端一切正常；需要手机脚本再运行一次才能拿到新的排障数据。

二、改动

三、验证

v0.4.19（排障增强：上报尝试日志覆盖全部分支，含请求体头部）

性质：排障能力补全。需求："检测模拟上报是否成功 / 依然没有回执"。

一、模拟上报结论：成功

手机在 02:03:40、02:04:09、02:05:29 三次点击自检页「模拟一次上报」，全部返回 HTTP 200， 服务端 wxpay_receipt_last_seen 随之刷新、last_device = "服务器自检"。 → 服务端端点、密钥、路径、回退逻辑全部正常；问题只在手机脚本如何构造请求。

二、新发现：手机上报从 401 变成 400（鉴权已通过）

手机脚本在 02:04:05–02:04:06 的三次上报返回 HTTP 400（此前是 401）。 说明鉴权已通过（v2 脚本的令牌头生效），现在卡在请求体参数上。

三、本次改动

四、验证

下一步：手机脚本再运行一次，自检页「最近上报尝试」会直接显示 400 的具体原因与请求体开头， 据此一眼定位（空体 / 字段名不对 / 编码问题）。

v0.4.18（排障能力 + 手机上报鉴权兼容：定位到"手机 401 鉴权失败"）

性质：缺陷修复 + 排障增强。需求："依然没有回执 / 检测手机回执失败的原因"。 本次拿到决定性证据：手机已经在连服务器了（自检页 HTTP 200）， 上报请求也到达了端点，但被 401 鉴权拒绝——失败点从"网络"收敛到"鉴权"。

一、关键证据（nginx 日志）

192.168.0.104  GET  /receipt-check.php  200   ← 手机（Android 16 / Vivo 浏览器）能访问服务器
192.168.0.104  POST /payment-receipt.php 401  ← 手机脚本（okhttp/4.10.0）上报被拒
192.168.0.104  POST /payment-receipt.php 401
192.168.0.104  POST /payment-receipt.php 401

二、修复内容

三、验证