奇点CMS 安装配置说明

本文档随交付包发布，描述 CMS 运行所需的网内配置与站外服务器配置和依赖。 后台「系统 → 部署检测」页面（admin/system-requirements.php）可对本文档全部项目做自动状态检测。

★ 维护约定：新增扩展/依赖时，必须同步更新 includes/SystemRequirements.php 注册表、 本文档、以及 docs/版本升级说明.md，打包时三者缺一不可（见 docs/打包说明.md）。

一、站外服务器配置与依赖

1. 基础环境

2. PHP 扩展

完整清单与逐项检测见后台「服务器状态」页（admin/server-status.php）。

3. php.ini 关键配置

4. 系统级依赖

5. nginx 站点配置（关键）

除常规 PHP-FPM 配置外（见 nginx.conf.example），强烈建议启用视频加载加速器：

# 视频加载加速器（X-Accel-Redirect 内部直发）
location ^~ /accel-media/ {
    internal;
    alias /你的站点目录/uploads/;
}

• 宝塔用户：粘贴到站点「伪静态」即可，改完重载 nginx
• 作用：付费视频由 nginx sendfile 直发，PHP-FPM 只做鉴权即释放，多人并发播放不卡顿
• 未配置时 CMS 自动回退 PHP 分块出流（功能正常，并发性能差）
• 强制关闭：settings 表设 media_accelerator = off

大文件上传容忍配置（server 块内添加，nginx.conf.example 已内置）：

client_max_body_size 600m;   # 与 php.ini post_max_size(600M) 对齐
client_body_timeout  300s;   # 默认 60s：弱网上传停顿 60s 即被 408/400 断开（浏览器报 ERR_CONNECTION_ABORTED / Failed to fetch）
send_timeout         300s;
fastcgi_send_timeout 300s;
fastcgi_read_timeout 300s;   # 默认 60s：大文件上传后落盘 + ffmpeg 缩略图处理超 60s 会 504

二、网内所需配置（CMS 内部）

1. 安装期生成

2. 目录与权限（Web 用户可写）

3. 运行期配置项（settings 表，后台可管理）

4. 数据表结构健康

• users.token_balance 必须为 DECIMAL(10,2) NOT NULL DEFAULT 0； 历史环境漂移为 NULL 会导致充值审核通过却不到账（NULL+增量=NULL）。 检测页会专项检查，修复执行 install/token-balance-fix-migration.sql（幂等）。
• token_expirations（Token 过期 / 返还流水表，已并入 database.sql）： 过期扣减逐户写一条（status=0 待返还），该用户充值订单审核通过时自动全额返还（status=1）。 已有站点升级执行 install/token-expirations-migration.sql（幂等，同时补齐 settings.token_expire_enabled / token_expire_months）；该表已纳入「部署检测 → 核心数据表完整性」清单，缺表会被标记为"不通过"并给出修复建议。 结算入口：后台「用户运营 → Token 数据面板 → 过期结算」（默认预览，需二次确认）， 或命令行 php cron-token-expiry.php（仅 CLI，支持 --dry-run / --asof=YYYY-MM-DD）， 建议在宝塔「计划任务 → Shell 脚本」配置每天一次。
• wxpay_receipts（微信收款回执流水，已并入 database.sql）：安卓设备监听微信收款通知后上报的回执。 只记录「设备看到的收款事实」，不作入账依据——到账仍由管理员审核 token_orders。 端点首次调用自动建表（settings.wxpay_receipt_schema_ready 标记），已纳入「部署检测 → 核心数据表完整性」清单；旧站点升级执行一次「数据库结构同步」即可（全新安装无需操作）。

5. 官方支付模块（可选，需手工建表与密钥目录）

官方支付（支付宝当面付 / 微信支付 APIv3）是可选模块：不启用时站点仍走「收款码 + 管理员人工审核」流程， 无需任何处理；启用前请按下表逐项配置。

6. Agent+ Go 加速服务（可选，Windows / Linux 双形态）

Agent+ 采用双实现：Go 常驻服务不可用时由 PHP 微内核自动接管（功能一致、性能降低）， 因此不部署 Go 服务不影响站点功能，检测页该组显示警告属预期状态。

Windows 关键提示

1. 编译需 Go 1.21+：cd <站点>\go-service → $env:GOPROXY='https://goproxy.cn,direct' → go build -trimpath -ldflags "-s -w" -o x-dream-go.exe .；不想装到系统时可用官方 go1.22.x.windows-amd64.zip 解压到任意目录当便携工具链
2. go-service/ 含 Go 源码与可执行文件，必须在 nginx 中拒绝公网访问；qdcms-go-win.ps1 会自动追加规则，但需重载 nginx 才生效
3. 心跳文件建议保持无 BOM 的 UTF-8 JSON：Windows PowerShell 5.1 的 Set-Content -Encoding UTF8 会写入 BOM（检测代码已对 BOM 容错，但启动器仍改用 .NET 无 BOM 写入，避免旧版检测逻辑误判"无心跳"）
4. 检测项按 PHP_OS_FAMILY 自动切换口径，Linux/Windows 共用同一份源码；完整步骤见 go-service/README.md 第六节
5. Windows 还有两个易漏点：计划任务默认 72 小时上限（须改 PT0S）与 SYSTEM 任务对非管理员不可见； 另有 .ps1 需 UTF-8 带 BOM、心跳 JSON 需无 BOM、open_basedir 要求产物位于站点内等 —— 汇总见 docs/Windows部署说明.md
6. FFmpeg（Windows）：包内 qdcms-ffmpeg-win.ps1 一键改写探测与后台压缩逻辑 （ffmpeg.exe 候选路径 + cmd if exist 探测 + 生成 .bat 压缩），未适配前 Windows 检测项会一直显示"未安装"

三、安装步骤速览

1. 服务器装好 PHP/MySQL/nginx，按第一节核对扩展与 ini
2. 上传 CMS 到站点目录，配置 nginx（含 accel-media location）
3. 浏览器访问 /install/ 走向导（数据库默认值 127.0.0.1/root/空密码/dream_cms，管理员必填）
4. 登录后台 → 系统 → 部署检测，处理全部"不通过"与"警告"项
5. 按需配置 SMTP（系统设置页），发测试邮件验证
6. 交付前跑一次包内自检脚本（Windows：powershell -ExecutionPolicy Bypass -File .\qdcms-selfcheck.ps1； Linux：同上方式运行或直接看后台部署检测页），确认无 FAIL 后再签收。详见 docs/Windows部署说明.md 第七节
7. 一台服务器部署多个站点（Windows）：用 qdcms-deploy.ps1 批量部署/巡检（默认只预演，-Apply 写盘）， 见 docs/Windows部署说明.md 第八节；巡检模式 -Discover 可一次列出本机所有 QDCMS 站点的版本、数据库与自检结论， 加 -Report 还能生成巡检日报（文件 + 可选邮件，邮件复用站点自身 SMTP），并可注册为每日定时任务

四、检测页使用说明

• 入口：后台左侧菜单「系统 → 部署检测」
• 分三组展示：🏠 网内所需配置 / 🖥️ 站外服务器配置与依赖 / 🤖 Agent+ 智能体服务环境与依赖
• 状态：通过（绿）/ 警告（黄，功能受损）/ 不通过（红，功能不可用）/ 信息（灰）
• 每项附当前值与修复建议；处理后点「重新检测」
• 检测项定义集中在 includes/SystemRequirements.php，新增依赖按文首维护约定登记

五、Agent+ 智能体服务环境与依赖（可选增强）

对应部署检测页第三组（🤖 Agent+ 智能体服务环境与依赖）。 Agent+ 为双实现架构：Go 常驻服务不可用时由 PHP 微内核自动接管， 功能一致、性能降低，因此该组异常项多为"警告/信息"而非"不通过"； 未部署 Go 服务时该组呈"信息/警告"属预期状态，站点功能不受影响。

1. Go 常驻服务（可选，用于性能提升）

• 编译、安装与加固步骤见 go-service/README.md；检测页会比对"源码 vs 已部署二进制"的时间，提示重新编译
• config/config.php（+ generated.php）须对运行 Go 服务的 www 用户可读；Go 侧复用该配置连库，不另行落盘口令
• 前端浏览器直连 Go 服务默认关闭（settings.go_service_url 留空），统一由 PHP GoAdapter 走回环调用
• 安装/重装容错：安装向导（install/auto-install.php、install/index.php）生成 config/generated.php 时只重写 DB_*， 其余配置项（含 GO_API_KEY）原样保留；若该常量缺失，则按「环境变量 → systemd 单元（含 .d/*.conf）→ 运行中的 x-dream-go 进程」 顺序探测实际生效值并继承，以 Go 侧为准（Go 是校验方：密钥不匹配返回 401、密钥非默认且无签名返回 403）。 探测到多个来源互相矛盾时只输出提示、不猜测、不写入。因此重装不会造成「PHP 侧无密钥 / Go 侧仍持自定义密钥」的静默退化。
• 密钥取不到时的显式告警：Web 安装进程常受 open_basedir 限制读不到 /etc/systemd、/proc，此时向导对回环 /api/stats 发起一次不带签名的只读探测：若返回 403「缺少 CSRF 签名」，说明 Go 侧使用的是非默认密钥，向导会在生成配置前显著告警， 并提示改用命令行安装（站点根目录执行 php install/auto-install.php，可正常继承密钥）、或安装后在 config/generated.php 手工写入与 systemd 单元一致的 GO_API_KEY；探测不可达或返回 200 时不告警。

2. 知识库数据表与索引

• 需 MySQL 5.7+（内置 ngram 解析器）；不支持 ngram 的数据库无法建立该索引，检索自动降级为 LIKE
• 建表与索引定义见 database.sql 的 agent_knowledge 段；修复走后台首页「数据库结构检查/同步」（DbUpdater 增量 DDL，不删表）

3. PHP 侧依赖