ThinkWo CMS 开发文档

ThinkWo CMS 是一套面向外贸企业站的内容管理系统：多语言子目录、服务端直出、静态化缓存、结构化数据全部内置。本文档面向使用者与二次开发者，从安装到改模板、写插件，一路讲完。

我要把站点装起来 → 环境要求、宝塔部署六步、伪静态、常见报错排查 我要改前台样式 → 模板目录规则、可用变量、继承与包含、换一套皮肤 我要写个插件 → 插件目录、钩子机制、配置读写、完整可跑示例 我要查某个字段叫什么 → 后台每个输入框 ↔ 数据库列 ↔ 模板变量，一张表查完

一、这套系统是什么

一句话：ThinkPHP 8 + LayUI 的原创外贸建站系统，产品形态参考主流国产 CMS 的使用习惯（栏目 / 内容 / 权限 / 插件），但代码全部自研，无任何第三方 CMS 依赖。

层	选型	说明
框架	ThinkPHP 8.1.4	多应用（index 前台 / admin 后台 / api 接口）
ORM	think-orm 4.0	表前缀 `tw_`，全部走查询构造器，无裸 SQL 拼接
模板	think-template 3.0	自定义标签库 `{tw:xxx}`，编译成原生 PHP
后台 UI	LayUI 2.12	纯前端库，无需 Node 构建
图片	GD	上传即转 WebP，自动生成 400 / 900 / 1600 三尺寸
缓存	文件 / Redis	整页静态化 HTML，命中直接输出不渲染

关于版本号

框架核心文件里 think\App::VERSION 常量被官方写死成 8.0.0，从来没跟着更新。判断真实版本只能看 vendor/composer/installed.json，本项目实际是 8.1.4。

二、目录结构

根目录下这 8 个文件夹就是全部，runtime/ 可随时清空，vendor/ 已内置无需 Composer。

网站根目录/ ├─ app/ 应用代码 │ ├─ common/ 公共库：标签库、SEO、URL、图片、插件… │ ├─ index/ 前台（路由分发器 + 接口） │ ├─ admin/ 后台（控制器 + LayUI 视图 + 菜单定义） │ └─ api/ 预留的独立接口应用 ├─ config/ 框架配置，tw.php 是 CMS 专属配置 ├─ template/ 前台模板（视图，一个主题一个目录） │ └─ {主题名}/ 视图文件，目录里必须有 theme.json ├─ public/ Web 根目录，站点要指到这里 │ ├─ index.php 前台入口 │ ├─ admin.php 后台入口（建议改名） │ ├─ install.php 安装向导（装完删掉） │ ├─ static/ 公共静态资源：layui、后台样式、品牌图、track.js │ ├─ template/ 前台模板的 CSS/JS/图片（可 URL 访问） │ └─ uploads/ 上传文件（含 demo 演示图） ├─ plugins/ 插件目录，一个插件一个文件夹 ├─ install/ install.sql + demo.sql（装完可删） ├─ vendor/ 依赖包（已精简内置，6.9MB） ├─ runtime/ 缓存、日志、编译后的模板（可清） └─ docs/ 本文档

三、五分钟跑起来

解压安装包到网站根目录，把站点运行目录指向 public
配置伪静态（Nginx 复制 public/nginx.conf.txt 的内容）
浏览器访问 http://你的域名/install.php
填数据库信息 + 管理员账号，勾选导入演示数据
装完删除 install/ 与 install.php，访问 /admin.php 登录

详细步骤和安全设置见安装部署。

四、后台功能地图

菜单	路径	能做什么
控制台	`admin.php/index/dashboard`	实时访客指标条（在线/今日访客/今日浏览/近 10 分钟/平均停留，10 秒自刷）、内容数量、未读询盘、运行环境、快捷入口
内容列表	`admin.php/content/index`	按栏目/语言/状态筛选，编辑、预览、删除
栏目管理	`admin.php/sort/index`	树形栏目，含 SEO 字段与模板指定
附件管理	`admin.php/attachment/index`	上传图片，自动 WebP + 多尺寸；后台所有「选择图片」弹层（媒体库）的数据都来自这里，可复用已上传文件
授权	`admin.php/system/license`	授权状态、输入授权码激活 / 刷新 / 解绑、授权站地址与公钥指纹；自用版显示"无需授权"
在线更新	`admin.php/system/update`	检查更新 → 签名清单 → 下载 SHA256 校验 → 备份 → 冲突跳过 → 覆盖，失败可回滚
语言列表	`admin.php/language/index`	增删语言，决定 `/en/`、`/zh-cn/` 前缀
询盘列表	`admin.php/inquiry/index`	状态流转（新/已读/已报价/已回复/成交/关闭）
访客记录	`admin.php/visit/index`	每次访问一行：来源、落地页、页数、停留时长、设备、IP、在线状态；30 秒自动刷新
页面热度	`admin.php/visit/pages`	按浏览量排行的页面榜（PV / 独立访客 / 平均停留）
询价车	`admin.php/inquiry/cart`	客户在前台攒的产品清单
SEO 概览	`admin.php/seo/index`	静态化开关、缓存统计、一键清理、预热
301 跳转	`admin.php/redirect/index`	老站 URL 迁移，保住权重
插件管理	`admin.php/plugin/index`	扫描 `plugins/`，启用/停用/配置
站点设置	`admin.php/setting/index`	公司信息、联系方式、SEO 默认值、邮件 SMTP
管理员 / 角色组	`admin.php/admin/index`	账号与权限（按菜单节点授权）

五、访客统计怎么工作（v1.0.15+）

系统自带一套轻量访客统计，不依赖第三方工具，也不采集任何表单内容与个人身份信息。整条链路只有四处：

环节	文件 / 地址	说明
前台打点脚本	`public/static/track.js`	约 2KB，由 `Frontend::render()` 自动注入到所有主题页面，换模板不用改
上报接口	`POST /api/visit`	接收 `pv`（页面浏览）/ `hb`（20 秒心跳）/ `bye`（离开）三种事件，恒返 204
记录库	`app/common/library/Visit.php`	会话归并、停留时长累加、UA 解析、Bot 过滤、超期清理
后台展示	`admin.php/visit/index`	控制台指标条 + 访客记录 / 访问详情 / 页面热度三页

开关与保留期在 站点设置 → 代码与统计：

设置项	默认	作用
`visit_enable`	1 开	关闭后前台不再加载打点脚本，后台显示开启引导
`visit_keep_days`	90	超过天数的记录自动清理；填 `0` 永久保留

为什么测试时不落库

Visit::isBot() 会过滤掉 HeadlessChrome、curl、python-requests 等 UA。用自动化脚本或命令行 curl 打点请把 UA 换成正常浏览器串，否则会被当成爬虫丢弃——这是设计行为，不是 bug。

六、文档约定

模板标签统一写作 {tw:list}…{/tw:list} 这种形式，尖括号形式的 PHP 代码一律放在深色代码块里
必填表示该属性不写会报错或缺数据，可选表示可省略
所有路径示例以「站点根目录」为基准，URL 示例以 / 为站点根
文档里的代码可以直接复制走——右上角「复制」按钮已铺在每个代码块上

七、遇到问题怎么办

现象	先看这里
前台 404 / 全站打不开	安装部署 → 常见错误（90% 是运行目录或伪静态）
模板改了不生效	模板入门 → 缓存与生效规则
标签不输出、页面空白	标签与函数 → 排查清单
插件启用了没反应	插件开发 → 钩子未触发
收录慢、收录少	SEO 运维 → 上线检查清单
栏目「模板设置」下拉里看不到新模板	模板入门 → 新增页面模板（下拉扫描的是主题目录，文件没放进去就不会出现）
后台没有「访问统计」菜单	安装部署 → 升级旧站（升级后需删 runtime 缓存并重新登录）

八、版本更新记录

完整更新日志见源码根目录 README.md，这里只记开发文档同步过的关键版本：

版本	主要内容
v1.0.45	站点设置进一步精简：任何主题专属的文案都不再放进后台通用设置，模板要维护的内容改由栏目内容承载；前台不再为某个主题兜底文案
v1.0.44	栏目自定义字段：新增 `tw_sort_field` 表，栏目上可定义 text / textarea / select / switch 四类字段，值以 JSON 存进内容表 `meta`，模板用 `{$list.字段键}` 取值（详见自定义字段）
v1.0.43	内容表新增 `meta` 扩展列（varchar 1000），供模板自定义文本与字段值使用；`{tw:list}` 增加 `lines` 拆行、`{tw:sort}` 支持按 slug 取栏目
v1.0.35	后台控制台「运行环境」新增授权状态 / 授权到期 / 升级服务到期（状态行可点击直达授权页）；发版流程强制更新日志：打包器 `--notes` 必填，包内自带 `changelog.txt`，授权站上传时自动提取展示，客户升级页可见本次更新说明
v1.0.34	品牌版权体系：官网地址统一到 `config/tw.php` 的 `brand.url`（后台框架页/登录页/授权页/各主题页脚/安装向导全部带链接）；版权防篡改：`Brand::audit()` 文件级审计 + 后台顶部告警条 + 前台缺链接时中间件补右下角徽标 + 心跳上报授权站「匿名探测」新增版权列（只留痕，不限制客户站点）
v1.0.33	升级器两处硬修：①清单/版本号写入加文件级自愈（root 属主文件 chmod→删了重建）②清单错位死循环解开（程序文件升级必覆盖，客户数据才做冲突保护；未入包文件基线按站点现状重对齐）
v1.0.25	匿名心跳（分发版后台上报域名/版本/激活状态到授权站，6h 节流；授权站新增「匿名探测」页，未激活域标红）+ 通用客户包策略（不再一客一包）+ 自用母包纳入 build/server + build/make.php 双击出包向导
v1.0.24	静态代码指纹（序列号散布 11 个明文文件，模板注释编译时剥离、前台零输出）+ Signature 归属类 + 鉴定工具 build/fingerprint.php（只读扫描可疑副本：是否本系统 / 发给谁 / 水印是否被清除）
v1.0.23	逐客户水印（--customer 写入 Build::CUSTOMER/FINGERPRINT + config 明文标记 + 后台「构建信息」卡，泄露可溯源；出包记录入 build/watermarks.json）+ 多 PHP 版本加密（--php=80,81,82 逐版本出包）+ 严格加密模式（--encrypt=ioncube 失败即中止，绝不明文外发）
v1.0.22	双轨出包（自用完整版 / 客户加密授权版，build/build.php，支持 ionCube）+ RSA 签名授权（离线验签、失效不锁站）+ 在线升级（清单验签 → SHA256 → 备份 → 客户改动冲突跳过 → 回滚）+ 独立授权站（server/，JSON 存储零依赖）
v1.0.21	后台媒体库：所有上传位（内容缩略图/图集、栏目图标/大图、设置图片字段、富文本插图）统一为「选择图片」弹层，可复用已上传文件也可直接上传，图集支持多选；修复 TP8 上传接口 500 与超大长图内存溢出
v1.0.20	主题营销文案词条化：模板文案抽到 `lang/theme/{主题}.{语言}.php`，多语言自动合并加载，后台同步可生成其他语言，JS 文案随语言切换
v1.0.19	询价表单支持图纸附件（5 个 × 50MB，白名单校验，后台可点链接下载）；翻译同步在引擎无返回时明确报错不再写原文；tags 纳入翻译
v1.0.18	控制台「实时访客」只保留标题栏 + 五个指标，浏览流水移到访客记录页
v1.0.17	主题支持「定制服务」「联系我们」两类整页版式；询价验证码跟随后台开关；栏目模板下拉加中文说明
v1.0.16	控制台实时访客版块 + 访客记录 30 秒自动刷新
v1.0.15	访客统计（访客记录 / 访问详情 / 页面热度 + track.js 打点）
v1.0.14	URL 别名按外贸 SEO 规则自动生成（中文标题译英 → 拼音 → 哈希兜底）
v1.0.13	栏目「模板设置」由自由输入改为下拉选择，保存时校验模板文件是否存在

ThinkWo CMS v1.0.45 开发文档 · 基于 ThinkPHP 8.1.4 + LayUI 2.12 · 文档随代码更新