客户安装验收清单（拿到包 → 可用的最短路径）
本文由全新环境的实测得出：解压交付包 → 建库 → 装 → 登录 → 打开后台与聊天 → 自检通过。 结论：装完即可用，不依赖 Go 加速服务、FFmpeg、SMTP 等可选组件（缺失时功能降级但不报错）。
一、前置条件（缺一不可）
| 项 | 要求 | 说明 |
|---|---|---|
| PHP | >= 7.2，推荐 8.0+ | 需 pdo_mysql、mbstring、gd、session |
| MySQL | >= 5.7 / MariaDB >= 10.2 | 建议 8.0（实测 8.0.29） |
| Web 服务器 | nginx（推荐）或 Apache | nginx 必须按 nginx.conf.example 补拒绝规则 |
| 目录可写 | config/、uploads/、data/ | 安装向导与运行期写入 |
| 磁盘 | 建议 >= 5 GB | 含上传内容增长 |
二、两种安装方式（任选其一）
方式 A：浏览器向导（最常见）
- 上传整包到站点根目录（如
D:\wwwroot\你的站点） - 浏览器访问
http://你的域名/install/ - 按向导填：数据库信息 → 管理员账号 → 完成
- 向导会写
config/generated.php、install.lock，并清理安装文件
方式 B：CLI 非交互（适合批量/自动化）
# 环境变量传凭据（脚本内无任何硬编码默认凭据）
DB_HOST=127.0.0.1 DB_PORT=3306 DB_USER=root DB_PASS=你的密码 DB_NAME=你的库名 \
ADMIN_USER=admin ADMIN_PASS=你的管理员密码 ADMIN_EMAIL=admin@example.com \
php install/auto-install.php脚本依次完成：环境检测 → 建库建表（50 张表）→ 创建管理员（靓号 10000）→ 生成 config/generated.php
→ 写 install.lock → 创建 uploads 标准子目录 → 清理安装文件。
Windows 批量部署：也可用
qdcms-deploy.ps1 -Mode Deploy -Sites sites.json -Apply（多站点一键部署 + 自检）。
三、装完即可用（无需任何可选组件）
| 能力 | 状态 | 说明 |
|---|---|---|
| 前台首页 / 栏目页 / 详情页 | ✅ 可用 | 含示例新闻、百科、问答数据；小说/短剧/短视频为空属正常（自建内容） |
| 注册 / 登录 / 找回密码 | ✅ 可用 | 找回密码在未配 SMTP 时降级为"联系客服"引导 |
| 后台管理 | ✅ 可用 | admin/index.php，用安装时设的账号登录 |
| 聊天（IM） | ✅ 可用 | 4 秒增量轮询投递 + 已读回执；未部署 Go 时自动降级为纯轮询（令牌接口返回 enabled:false） |
| 站内信 / 好友 / 动态 / 问答 | ✅ 可用 | 均为内置功能 |
| 部署自检 | ✅ 可用 | admin/system-requirements.php 或包内 qdcms-selfcheck.ps1 |
四、可选增强（缺失不影响"能用"，但有则更好）
| 组件 | 未装时的表现 | 启用方式 |
|---|---|---|
| Agent+ Go 加速服务 | 检测项提示"未部署"；缓存/知识库走 PHP 回退路径，功能正常、并发略低 | qdcms-go-win.ps1（Windows）或 go-service/README.md（Linux） |
| IM 实时推送（SSE） | 聊天仍可用，靠 4 秒轮询（延迟 0–4 秒） | 部署 Go 服务 + 配 GO_API_KEY + nginx 加 /im-stream 反代（见 docs/聊天即时通信说明.md 第六节），延迟降到 <50 ms |
| FFmpeg | 缩略图降级为占位图、视频压缩跳过；上传不受影响 | 安装 ffmpeg（Windows：qdcms-ffmpeg-win.ps1） |
| SMTP 邮件 | 找回密码降级为引导联系客服 | 后台 → 系统设置 → 邮件 SMTP |
| 商用授权 | 基础功能正常，靓号业务锁定 | 后台 → 系统设置 激活 |
| 视频加载加速器 | 回退 PHP 分块出流（可用、并发低） | nginx 加 accel-media location（nginx.conf.example 已含） |
五、装完必做的两件事
- nginx 拒绝规则（否则敏感文件可被公网下载）：
nginx.conf.example已内置/config/ /includes/ /data/ /docs/ /reports/ /go-service/、可执行与备份后缀、 隐藏文件（保留.well-known）等规则。宝塔用户放进nginx/conf/proxy/<域名>/*.conf（须位于 PHP location 之前）。 - 域名绑定：后台 → 系统设置填写站点域名（决定授权域校验与
data/.license_domain）。
六、验收命令（客户自证，一条即可）
# Windows
powershell -ExecutionPolicy Bypass -File .\qdcms-selfcheck.ps1 -SiteRoot "D:\wwwroot\你的站点" -LogPath .\selfcheck.txt期望输出（全新站点实测）：
[PASS] 站点根目录 / CMS_VERSION / config/generated.php / 安装锁 / PHP CLI
[WARN] 检测注册表 通过 20 / 警告 3 / 不通过 0 / 信息 8 ← 3 项警告为 SMTP、FFmpeg、Go 产物（均为可选）
[PASS] Agent+ 组（9 项）
[PASS] 前台可用性（首页 / 短视频 / 登录页 / 静态资源）
[PASS] 安全规则（敏感路径 404 —— 需已在 nginx 配好规则）
结论: PASS —— 未发现必须处理的问题 退出码 0若安全规则整段报 FAIL 且提示"PHP 内置服务器不加载 nginx 规则"，说明当前是用 PHP 内置服务器访问的， 请在正式 nginx 环境复测。
七、本次实测发现并已修复的问题（v0.4.00）
| 级别 | 问题 | 修复 |
|---|---|---|
| 🟠 | CLI 安装（auto-install.php）把锁写在 install/install.lock，随后第 5 步清理安装文件时一并删除 → 装完站点没有任何锁，检测页报"未锁定"且可被重装 | 锁改写到站点根目录并保留（与浏览器向导口径一致） |
| 🟡 | 装完 uploads/ 只有 agent-icons，检测页提示"缺子目录: covers,avatars,..." | 安装脚本自动创建标准子目录 |
| 🟠 | 自检脚本在未打 Windows 补丁的全新站点上解析注册表失败（SystemRequirements 会向 stderr 输出 POSIX 命令噪音，2>&1 捕获污染 JSON），误报"检测注册表 FAIL" | 结果改为写 JSON 文件读取，stderr 丢弃；并对敏感路径提示"响应服务器类型"避免误判 |
八、结论
客户拿到包 → 按本文第二节装好 → 第三节的能力全部可用，无需等待任何可选组件； 第四节的可选增强可在上线后按需开启（其中 IM 实时推送可把聊天延迟从 0–4 秒进一步压到 <50 ms）。 实测环境：Windows + 宝塔 nginx + PHP 8.0.28 + MySQL 8.0.29，全新库、全新目录、由 CLI 安装脚本一键装成。