给要改内核、做深度定制或参与贡献的人。YeCha 的设计取向是「少魔法、可读源码」:没有容器、没有编译步骤,请求从 index.php 进,一路是普通 PHP 函数调用。
本页导航
请求生命周期
浏览器 → Web 服务器伪静态 → index.php
1. require config.inc.php + core/bootstrap.php(常量、自动加载、会话)
2. Plugins::boot() 加载启用插件(注册钩子 / 页面 / 后台菜单)
3. Router::resolve($path) 解析成 kind + 参数
4. 页缓存命中判断(home/post/meta_list/… 可缓存)
5. Front::home() / Front::post() / Front::metaList() …
取数据 → Markdown::render() / Changelog::render() → 组装 $main / $side / $toc
6. View 渲染主题 views/layout.php(含导航、侧栏、资源版本号)
7. Hooks::run('front.shell', …) 外壳注入 → 输出 HTML/admin/ 是独立的后台入口,结构相同但走 Auth 鉴权与 Csrf 校验。
目录与核心类
| 文件 | 职责 |
|---|---|
index.php / admin/index.php | 前台 / 后台唯一入口与分发 |
core/Router.php | 路径解析、保留词、越界页码判定 |
core/Front.php | 首页、内容页、分类/标签/归档/搜索的数据与渲染组装 |
core/Db.php | PDO 封装、表前缀 ye_、预处理 |
core/View.php | 主题定位、模板回落、View::asset() 版本化 |
core/Markdown.php | Markdown → HTML(转义优先、锚点、表格、围栏代码 data-lang) |
core/Changelog.php | /changelog 结构化时间线渲染器(1.2.5 起) |
core/Nav.php | 导航单一数据源,顶部/页脚/下拉分组 |
core/Lang.php / core/Poly.php / core/ZhTw.php | 界面语言包、内容译文、繁简 |
core/Plugins.php / core/Hooks.php / core/Upgrade.php | 插件引导、动作总线、迁移执行 |
core/Cache.php | 文件缓存(pages / blocks) |
core/Csrf.php / core/Auth.php / core/Uc.php | 表单令牌、鉴权、用户中心 |
core/Mail.php / core/Feed.php / core/Market.php | 邮件、RSS/sitemap、云市场 |
core/Str.php / core/helpers.php / core/version.php | 字符串、全局辅助函数、版本号 |
路由解析顺序
Router::resolve() 从上到下依次命中,先到先得:
- 空路径 →
home(含/page/N/页码) /healthz→ 健康检查- 语言段(仅
Poly::on()且语言已启用时递归剥掉/en/、/ja/…) /category/…、/tag/…、索引页、/archives/YYYY[/MM][/page/N]/search、/login、/register、/logout、/count、/feed、/sitemap.xml、/pages、/user/…- 业务前缀
mall/site/ai(插件停用则回落 404) docs、changelog干净 URL → 同名内容页/{slug}.html→ 文章或页面- 插件独立页
/{slug}[/...] - 其余 404
Router::RESERVED 里的词不能被内容 slug 占用;越界页码与非法页码(page/0、page/abc)统一判 404,判据只在 Router::pageBeyond() 一处实现,避免重复内容页与自指 canonical。
数据库与索引
| 表 | 用途 |
|---|---|
ye_contents | 文章 / 页面(type、status、slug、content_format、published_at、deleted_at…) |
ye_poly_contents | 内容译文(group_id + lang + status + manual_override…) |
ye_metas | 分类 / 标签(type、name、names_i18n、slug_i18n、count 预计算) |
ye_relationships | 内容 ↔ 术语(content_id、meta_id) |
ye_options | 站点选项(name / value / autoload) |
ye_users / ye_comments | 用户、评论 |
ye_views / ye_attachments | 阅读量明细、附件 |
ye_migrations | 迁移执行历史 |
要点:
- 所有前台列表都带
type='post' AND status='publish' AND deleted_at IS NULL;写新查询时照抄这个条件,别漏软删过滤。 count是预计算列,术语列表/侧栏直接读;不要在列表页写(SELECT COUNT(*) FROM ye_relationships …)子查询(1.2.0 已从xinglan、wenshu主题清掉这种反模式)。- 首页文章总数走
Front::postsTotal():优先ye_options.stats.posts_total(O(1))→ 缓存(3600s) → 现算(最后兜底)。 - 深翻页(offset 很大)走
ye_meta_page_bounds键序快路径;1.2.4 起繁体(tw)也接入该快路径,子集不足时安全回退旧路径。 - 索引设计见
install/schema.sql与tools/optimize-indexes.php;改查询先用EXPLAIN看真实行数。
多语机制
- 语言靠 URL 前缀(
/en/…),不靠 cookie;Poly::on()/Poly::enabled()决定是否解析。 - 内容译文
Poly::row($baseId, $lang),术语名Poly::termName($row, $lang),术语链接Poly::termUrl();无译文回退基准语言。 - 界面文案在
lang/zh_CN.php、lang/en_US.php等语言包里,用__('key')取;新增键要各语言同时补。 - 完整说明见多语言与 AI 翻译。
缓存
| 位置 | 内容 | 清理时机 |
|---|---|---|
var/cache/pages/ | 全页缓存(home/post/meta_list/…) | 改内容、主题、菜单后 |
var/cache/blocks/ | 侧栏与区块缓存 | 改侧栏、插件后 |
var/home-static/ | 首页烘焙件(含 /en/) | 改首页、主题、统计代码后 |
Cache::flush('pages') / Cache::flush('blocks') 是唯一入口;改数据后要主动清,否则会看到旧页。详见运维:缓存。
编码规范
- PHP 8.1+,
declare(strict_types=1);类文件放core/,全局辅助函数放helpers.php。 - 服务端直出:页面主体内容必须在 HTML 源码里可见,JS 只做交互增强,不用客户端渲染主体列表/详情。
- 所有输出过
e();SQL 一律预处理,表名走Db::t();表单写操作带Csrf::field()+Csrf::check()。 - 密钥不进源码/仓库/日志;
DEBUG=true只在本机临时使用。 - 改动前先
php -l,改完跑源站 curl 冒烟(首页、内容页、后台、sitemap、feed)。 - 注意行尾:仓库里个别文件是 CRLF(如
plugins/market/showcase.php),批量补丁脚本不要整文件转 LF,否则会产生虚假大 diff。
调试与性能
php -l core/Front.php
php -r 'chdir("/www/wwwroot/yecha.org"); require "config.inc.php"; require "core/bootstrap.php"; Cache::flush("pages");'
curl -s -o /dev/null -w '%{http_code} %{time_total}s\n' -H 'Host: example.com' http://127.0.0.1/排查顺序:instrument → measure → isolate → fix → re-measure。慢查询先看 EXPLAIN 与慢日志指纹,再从 SQL、PHP-FPM 并发、缓存命中次序、OPcache、页面资源体积与图片尺寸逐项隔离;详见运维:性能。
发版流程
YeCha 的更新日志有两份内容源,改版时都要动:
- 仓库根
CHANGELOG.md:面向开发者的完整记录(根因 / 修复 / 判据 / 验收 / 部署 / 回滚)。 - 线上
/changelog是数据库内容页(ye_contents.slug=changelog),结构化时间线由core/Changelog.php渲染;英文译文在ye_poly_contents。发布新版本要同步更新这两处(含英文)。 core/version.php的YC_VERSIONbump。- 按仓库
RELEASE.md五步走:更新日志检查 → 功能完全性检查 → 出包(git archive <tag>,注意 gzip 非确定性,验证要解压后比内容 SHA)→ GitHub 发布(tag + Release + tar 资产)→ 收尾验收。 - 清页缓存(
/changelog为Cache-Control: no-cache,不需清 CDN)。
/changelog 的版本标题格式固定为 ## YYYY-MM-DD · YeCha <版本> · <标题>,首页「最新更新」区块也按这个格式解析,别随意改。