开发文档 - TomdowCMS

01快速开始 · 安装教程

TomdowCMS 是纯原生 PHP 内容管理系统，无框架依赖，内置 RBAC 权限、文件缓存、钩子系统、RESTful API、主题插件机制，5 分钟完成安装。掌握 PHP + MySQL 即可二次开发。

环境要求

项目	要求
Web 服务器	Apache / Nginx / phpStudy 均可
PHP	7.4+（推荐 8.x），需开启 PDO、mbstring、fileinfo 扩展
数据库	MySQL 5.7+ 或 MariaDB，支持 utf8mb4
浏览器	Chrome / Edge / Firefox 现代版本

安装教程（详细）

以 Windows + phpStudy 为例，全流程 5 分钟完成部署：

准备环境：下载安装 phpStudy（或已有 Apache/Nginx + MySQL 环境），启动 Apache 与 MySQL 服务
下载程序：前往官方站「下载中心」下载最新版安装包（zip）
解压上传：将压缩包解压，把全部文件上传到网站根目录（如 D:\phpstudy_pro\WWW\mycms\）
创建数据库：进入 phpMyAdmin 新建数据库（如 tomdow_cms），字符集选 utf8mb4，可同时创建专用数据库账号
运行安装向导：浏览器访问 http://localhost/mycms/，自动进入安装向导，按提示填写后一键完成

安装向导字段说明

字段	填写说明
数据库主机	一般为 `localhost`（远程库填服务器地址）
数据库端口	默认 `3306`
数据库名	第 4 步创建的库名，如 `tomdow_cms`
数据库账号 / 密码	有权限读写该库的账号密码（本地可用 root）
数据表前缀	默认 `td_`，可自定义；多套系统共存时用于表隔离
管理员账号 / 密码	后台登录账号与密码，请牢记（预置账号 admin / 123456，登录后请立即修改）

完成与验证

安装成功提示后，访问前台首页确认页面正常渲染
访问 /td_admin 用管理员账号登录后台
登录后建议立即修改默认密码

常见安装报错

报错	解决办法
环境不满足（缺扩展）	phpStudy →「软件管理 → PHP 设置」，勾选 `pdo_mysql` / `mbstring` / `fileinfo`
数据库连接失败	核对主机 / 端口 / 账号密码，确认 MySQL 服务已启动、数据库已创建
目录无写入权限	Linux 下给根目录及 `uploads/`、`cache/` 执行 chmod 755/775；Windows 一般无此问题
页面 500 / 空白	开启 `display_errors` 查看具体错误；确认 PHP 版本 ≥ 7.4

本地调试建议：使用 phpStudy 搭建环境，在 php.ini 开启 display_errors，安装向导会自动检测环境是否满足要求。

升级方式

从官方站下载新版安装包，覆盖除 uploads/ 与 config.php（数据库配置）外的文件即可；核心升级不触碰主题、插件与数据表，你的扩展完全保留。

02后台使用

后台入口 /td_admin，登录后进入控制台。后台按功能划分为以下模块：

模块	说明
控制台	站点数据统计、系统状态、快捷入口
内容管理	文章管理、分类管理、评论管理、单页管理、回收站
外观	主题列表与启用、菜单管理（无限级）、侧边栏小工具
插件	插件安装 / 启用 / 停用 / 卸载
用户	用户列表、等级与状态管理
设置	站点信息、SEO、API、缓存、上传等系统设置
应用商店	在线浏览官方商店、安装主题插件、更新检测
商品审核	管理员审核开发者提交的主题/插件商品

控制台首页

展示文章数、评论数、用户数、下载量等核心指标，以及最近更新公告、系统运行状态（PHP 版本、MySQL 版本、缓存状态）。

菜单管理

菜单表 {prefix}menus 支持无限级嵌套：父级 parent_id 指向自身 ID。支持四种菜单类型：

url直接链接（任意地址）
page站内单页（关联 posts 单页）
cat栏目分类（关联 categories）
custom自定义（含 menu_key 用于页面高亮）

侧边栏小工具

后台「外观 → 小工具」可拖拽排序、启用/禁用。内置组件：最新文章、分类目录、标签云、搜索框、文章归档、站点介绍、友情链接、热门文章、随机文章、广告位、统计信息等。

03内容管理

内容体系基于 {prefix}posts 单表设计，用 post_type 区分文章与单页，用 post_status 区分发布与草稿。

文章管理

创建/编辑文章：标题、别名（slug）、正文（富文本）、摘要、分类、缩略图
批量操作：批量删除、批量移动分类、批量修改状态
回收站：删除文章先进回收站，可恢复或彻底删除
浏览量 views 字段自动累加

分类管理

{prefix}categories 支持父子多级分类（parent_id），每篇文章可关联多个分类（多对多，见 {prefix}post_category 关联表）。

单页管理

单页（post_type='page'）用于关于我们、用户协议、隐私政策等固定页面，通过 post_slug 访问，如官方站 page.php?slug=about。

评论管理

文章评论存 {prefix}comments，支持状态审核（正常/待审/垃圾），管理员可在后台一键通过或删除。

媒体管理

上传安全校验：白名单扩展名（jpg/png/gif/webp/zip 等）+ 文件类型检查
媒体列表、使用统计、未使用媒体清理

04主题开发

主题就是 td_themes/ 下的一个文件夹，极简结构即可运行，升级核心不影响主题。

目录结构

td_themes/mytheme/
├── style.css            # 主题信息头（名称/作者/版本/描述）
├── index.php            # 首页模板
├── single.php           # 文章详情页
├── page.php             # 单页模板
├── archive.php          # 分类/标签列表页
├── search.php           # 搜索结果页
├── sidebar.php          # 侧边栏（渲染小工具）
├── inc/                 # 公共 include 文件（全站模板共用）
│   ├── header.php       # 公共头部（导航）—— 每个模板顶部 include
│   └── footer.php       # 公共底部 —— 每个模板底部 include
└── static/              # css / js / 图片资源

公共 inc 文件调用

公共头部（导航）与公共底部统一放在 inc/ 目录，所有模板通过 include 引入，保证全站头部导航、页脚一致：

<?php include __DIR__ . '/inc/header.php'; ?>   // 页面顶部：输出公共头部（导航）

<!-- 页面正文内容 -->

<?php include __DIR__ . '/inc/footer.php'; ?>   // 页面底部：输出公共底部

导航高亮约定：公共头部 inc/header.php 内通过「页面标识 + 高亮变量」判断当前页，如 $activePage = 'home'; 传入后对比菜单 menu_key 输出 active 样式，实现菜单自动高亮。

模板调用规则

模板文件	对应页面
`index.php`	首页
`single.php`	文章详情
`page.php`	单页（关于我们等）
`archive.php`	分类 / 标签列表
`search.php`	关键词搜索
`inc/header.php` / `inc/footer.php`	公共头部（导航）/ 公共底部，各模板 include 引入

常用函数

函数	说明
`get_option($db, 'key', '默认')`	读取站点配置
`html_e($str)`	HTML 转义输出（防 XSS）
`get_menu_tree($db, $prefix, 'main')`	读取导航菜单树（无限级）
`get_cat_tree($db, $prefix)`	读取分类树
`td_themes_url()`	当前主题 static 目录 URL

创建主题步骤

在 td_themes/ 新建文件夹，如 td_themes/mytheme/
创建 style.css 并填写主题信息头（后台以此识别主题）
编写模板文件，用系统函数读取数据并循环输出
后台「外观 → 主题」点击启用，立即生效
打包为 .zip，可在官方站「开发者中心」上传上架

安全红线：模板中所有动态输出必须经 html_e() 转义；后台富文本内容属管理员可信内容，可原样输出。

05插件开发

插件通过钩子系统（Hook）在不修改核心代码的前提下注入功能。挂载点覆盖前台查询、后台列表、设置页面、内容保存、上传、评论、用户、附件等场景。

钩子机制

函数	说明
`do_action('hook', $args)`	核心触发动作（执行点）
`add_action('hook', '回调', 优先级)`	插件监听动作，优先级数字越小越先执行
`apply_filters('hook', $value)`	过滤器：修改数据后返回
`add_filter('hook', '回调')`	插件挂载过滤器

插件目录结构

plugins/myplugin/
├── myplugin.php        # 主文件（插件信息头 + 钩子注册）
├── install.php         # 安装时执行（建表、初始化数据）
├── uninstall.php       # 卸载时执行（清理数据）
├── admin/              # 可选：自定义后台菜单页面
└── static/             # 可选：插件自带 css / js / 图片

生命周期

阶段	说明
安装	执行 `install.php`，创建数据表、写入配置，登记到 `{prefix}plugin`
启用	主文件加载，钩子开始生效，`is_enable=1`
停用	钩子卸载，数据保留，`is_enable=0`
卸载	执行 `uninstall.php`，删除数据表与配置，移除登记

常用挂载点示例

// 监听文章保存后触发
add_action('post_saved', function($postId){
    // 同步数据、发通知等
});
// 修改前台文章查询
add_filter('posts_query', function($sql){
    return $sql . ' AND views > 10';
});

插件内也可自定义后台菜单与 API 端点：注册菜单后自动出现在后台侧栏；注册路由后在 api.php 增加对应 action。

06RESTful API

系统原生提供 JSON 格式 API，入口统一为 api.php，默认开启跨域（CORS），适合 Vue 主题、小程序、移动端与第三方客户端接入。

通用返回格式

{
  "code": 1,          // 1 成功，0 失败
  "msg":  "ok",
  "data": { ... }     // 业务数据
}

接口列表

接口	说明
`api.php?action=posts`	文章列表（分页、分类筛选、关键词搜索）
`api.php?action=post&id=1`	文章详情
`api.php?action=pages`	单页列表 / 详情
`api.php?action=categories`	分类列表（树形）
`api.php?action=tags`	标签列表
`api.php?action=comments&post_id=1`	文章评论
`api.php?action=menus&group=main`	导航菜单（无限级树）
`api.php?action=options`	站点信息（名称、描述、URL）
`api.php?action=user&id=1`	用户公开信息

分页与筛选参数

参数	说明
`page` / `per_page`	页码 / 每页条数
`cat`	按分类 ID 筛选文章
`q`	关键词搜索（标题/摘要/正文）

安全提示：所有写入接口（发布、评论、点赞、上传）要求登录态（$_SESSION['user_uid']），服务端必须二次校验权限与内容，禁止仅凭前端参数信任。

07数据表结构

所有表统一前缀（默认 td_，安装时可自定义），完整建表语句见安装包 install/install.sql。

核心内容表

数据表	用途
`{prefix}options`	站点配置（键值对，含缓存类型配置）
`{prefix}users`	用户：昵称、QQ、头像、性别、等级、在线状态、主页封面
`{prefix}posts`	文章与单页（post_type / post_status / 浏览量 / 缩略图）
`{prefix}categories`	分类（无限级 parent_id）
`{prefix}post_category`	文章-分类多对多关联
`{prefix}comments`	文章评论（父评论、审核状态）

扩展与商店表

数据表	用途
`{prefix}menus`	导航菜单（无限级、menu_key 高亮、类型）
`{prefix}themes`	主题登记（目录名唯一、启用标记）
`{prefix}plugin`	插件登记（安装/启用状态）
`{prefix}widgets`	侧边栏小工具（JSON 配置、排序）
`{prefix}apps`	应用商店已安装应用登记（类型、版本、来源）
`{prefix}store_devs`	开发者申请与状态
`{prefix}store_products`	商店商品（名称、版本、类型、价格、下载量、审核状态）
`{prefix}store_downloads`	用户下载记录（关联商品）

社交功能表

社区动态相关：{prefix}feeds（动态）、{prefix}feed_likes（点赞）、{prefix}feed_comments（评论）；另有 {prefix}follows（关注）、{prefix}relations（亲密关系）、{prefix}visits（访客记录）、{prefix}messages（留言板）、{prefix}groups 系列（群聊）。

注：{prefix} 为安装时用户设置的表前缀占位符，编写 SQL 时请用真实前缀或保持 {prefix} 模板写法。

08应用商店

商店生态完整闭环：开发者提交 → 管理员审核 → 商城上架 → 用户在线安装。

成为开发者

注册 / 登录本站账号，前往「开发者中心」提交申请（填写开发者昵称、简介）
管理员审核通过后，账号自动获得开发者权限（导航出现「开发者中心」入口）
在开发者中心上传主题 / 插件安装包（zip），填写名称、版本、简介、价格（可免费）

审核与上架

管理员在后台「商品审核」查看待审商品，检查安装包结构与安全性
审核通过 → 前台商城上架；驳回 → 开发者收到原因，修改后可重新提交
上架商品自动出现在官方首页「热门应用推荐」

用户安装

用户在「官方商城」浏览主题 / 插件，一键下载安装包
客户端后台「应用商店」在线安装并启用，无需人工上传
下载记录写入 {prefix}store_downloads，累计下载量实时更新
更新检测带缓存，减少 CMS 后台频繁请求官方站的性能压力

付费与安全

付费应用按后台安装流程授权识别，禁止通过直接输入文件链接绕过授权下载
安装包存储目录规范化，上传与下载均校验文件类型与来源

立即前往开发者中心 →

09常见问题

安装时提示环境不满足怎么办？

按提示逐项开启：PHP 需开启 pdo_mysql、mbstring、fileinfo 扩展（phpStudy 在「软件管理 → PHP 设置」中勾选扩展）。

忘记后台密码？

进入 phpMyAdmin，执行：UPDATE {prefix}users SET user_pass='$2y$10$92IXUNpkjO0rOQ5byMi.Ye4oKoEa3Ro9llC/.og/at2.uheWG/igi' WHERE user_login='admin'; 密码即重置为 123456，登录后请立即修改。

文章图片不显示？

检查 uploads/ 目录写入权限（Linux 下需 755/775）；确认后台「设置 → 上传」中允许的图片扩展名包含 jpg/png/gif/webp。

主题或插件安装失败？

确认 zip 包根目录包含主文件（主题为 style.css，插件为 插件名.php）；不要在外层多包一层文件夹；zip 内不得包含可执行危险文件。

如何接入小程序 / App？

直接调用 api.php RESTful 接口即可，默认已开启跨域。建议服务端配置 HTTPS，并为写入接口补充自己的鉴权逻辑。

开发者申请多久通过？

管理员在后台「商品审核 → 开发者申请」实时审核，一般 1-2 个工作日内；审核结果在「开发者中心」可见。

如何彻底卸载插件？

后台「插件」先停用再卸载；卸载会执行 uninstall.php 删除插件数据表与配置。若插件无卸载脚本，请手动删除插件目录并清理 {prefix}plugin 登记记录。