<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>ZhyCMS v3.2.6 使用手册</title>
<style>
:root { --brand:#2e6df6; --brand-dark:#1b4fd0; --bg:#f6f8fb; --code-bg:#f2f4f8; --border:#e2e8f0; }
* { box-sizing:border-box; }
body { margin:0; font-family:-apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Microsoft YaHei",sans-serif;
color:#1f2933; background:var(--bg); line-height:1.75; }
.layout { display:flex; max-width:1280px; margin:0 auto; }
nav.toc { position:sticky; top:0; align-self:flex-start; width:280px; height:100vh; overflow-y:auto;
padding:20px 14px; background:#fff; border-right:1px solid var(--border); font-size:13.5px; }
nav.toc h2 { font-size:14px; color:var(--brand); margin:0 0 10px; text-transform:uppercase; letter-spacing:0.5px; }
nav.toc a { display:block; color:#4a5568; text-decoration:none; padding:4px 8px; border-radius:5px; line-height:1.6; }
nav.toc a:hover { background:var(--bg); color:var(--brand); }
nav.toc a.sub { padding-left:20px; font-size:12.5px; color:#64748b; }
nav.toc a.sub2 { padding-left:32px; font-size:12px; color:#94a3b8; }
nav.toc .toc-group { margin-bottom:14px; padding-bottom:10px; border-bottom:1px solid var(--border); }
nav.toc .toc-group:last-child { border-bottom:none; }
main { flex:1; min-width:0; padding:36px 44px; background:#fff; }
header.hero { background:linear-gradient(135deg,var(--brand) 0%,var(--brand-dark) 100%);
color:#fff; padding:32px 40px; border-radius:12px; margin-bottom:28px; }
header.hero h1 { margin:0 0 6px; font-size:28px; }
header.hero p { margin:0; opacity:.92; font-size:15px; }
h2 { font-size:22px; margin-top:44px; padding-bottom:8px; border-bottom:2px solid var(--border); color:#1e293b; }
h3 { font-size:18px; margin-top:30px; color:#334155; }
h4 { font-size:15px; margin-top:22px; color:#475569; }
p, li { font-size:15px; }
code { background:var(--code-bg); padding:2px 6px; border-radius:4px; font-size:13px;
font-family:"SFMono-Regular",Consolas,"Liberation Mono",Menlo,monospace; color:#c7254e; }
pre { background:#1e293b; color:#e2e8f0; padding:16px 18px; border-radius:10px; overflow-x:auto;
font-size:13px; line-height:1.6; }
pre code { background:none; color:inherit; padding:0; }
table { border-collapse:collapse; width:100%; margin:14px 0; font-size:14px; }
th, td { border:1px solid var(--border); padding:8px 11px; text-align:left; vertical-align:top; }
th { background:var(--bg); font-weight:600; }
tr:nth-child(even) td { background:#fafbfc; }
.note { background:#eef5ff; border-left:4px solid var(--brand); padding:12px 16px; border-radius:0 8px 8px 0; margin:14px 0; }
.warn { background:#fff7ed; border-left:4px solid #ea8a2e; padding:12px 16px; border-radius:0 8px 8px 0; margin:14px 0; }
.tip { background:#f0fdf4; border-left:4px solid #22c55e; padding:12px 16px; border-radius:0 8px 8px 0; margin:14px 0; }
.tag { display:inline-block; background:var(--brand); color:#fff; font-size:11px; padding:1px 7px; border-radius:10px; vertical-align:middle; margin-left:4px; }
.tag-new { background:#16a34a; }
.tag-beta { background:#ea580c; }
ul.check { list-style:none; padding-left:0; }
ul.check li::before { content:"\2610"; margin-right:8px; color:var(--brand); }
footer { margin-top:48px; padding-top:18px; border-top:1px solid var(--border); color:#94a3b8; font-size:13px; }
a { color:var(--brand); }
.version-badge { display:inline-block; background:rgba(255,255,255,0.2); color:#fff; font-size:13px; padding:2px 10px; border-radius:12px; margin-left:8px; vertical-align:middle; }
@media (max-width:900px){ nav.toc{display:none;} main{padding:20px;} header.hero{padding:24px;} }
</style>
</head>
<body>
<div class="layout">
<nav class="toc">
<div class="toc-group">
<h2>快速入门</h2>
<a href="#intro">项目简介</a>
<a href="#features">特性一览</a>
<a href="#structure">目录结构</a>
<a href="#install">安装与初始化</a>
<a href="#install-env" class="sub">环境要求</a>
<a href="#install-step" class="sub">安装步骤</a>
<a href="#install-setup" class="sub">初始化向导</a>
<a href="#install-db" class="sub">数据库选择</a>
<a href="#deploy">部署方式</a>
<a href="#deploy-dev" class="sub">开发模式</a>
<a href="#deploy-prod" class="sub">生产部署</a>
<a href="#deploy-docker" class="sub">Docker 部署</a>
<a href="#deploy-env" class="sub">环境变量</a>
<a href="#demo">演示数据与主题</a>
</div>
<div class="toc-group">
<h2>使用指南</h2>
<a href="#identity">CMS 与网站标识</a>
<a href="#sitegroup">站群模式(多站点) <span class="tag tag-new">v3.2.0</span></a>
<a href="#rbac">用户、角色与权限</a>
<a href="#workflow">内容工作流与版本</a>
<a href="#editor">Markdown 编辑模式 <span class="tag tag-new">v3.1.5</span></a>
<a href="#backup">备份与恢复</a>
<a href="#notify">表单消息通知</a>
<a href="#seo">SEO 与站点性能</a>
<a href="#seo-rewrite" class="sub">伪静态 URL</a>
<a href="#seo-cache" class="sub">页面缓存与图片 ALT</a>
<a href="#builder">可视化页面构建器 <span class="tag tag-new">v3.0.0</span></a>
<a href="#builder-ui" class="sub">编辑器与发布流程</a>
<a href="#builder-widgets" class="sub">24 个内置组件</a>
<a href="#builder-dev" class="sub">组件开发 API</a>
<a href="#security">安全加固</a>
<a href="#sec-login" class="sub">登录防暴破</a>
<a href="#sec-upload" class="sub">上传安全</a>
<a href="#sec-audit" class="sub">审计日志</a>
</div>
<div class="toc-group">
<h2>扩展开发</h2>
<a href="#template">主题模板开发 API</a>
<a href="#tpl-mech" class="sub">机制与解析链</a>
<a href="#tpl-dir" class="sub">目录结构与 manifest</a>
<a href="#tpl-base" class="sub">base.html 契约</a>
<a href="#tpl-vars" class="sub">全局模板变量</a>
<a href="#tpl-funcs" class="sub">全局函数与过滤器</a>
<a href="#tpl-ctx" class="sub">页面上下文与对象字段</a>
<a href="#tpl-url" class="sub">URL 生成与分页</a>
<a href="#tpl-i18n" class="sub">i18n 与图片占位</a>
<a href="#tpl-alt" class="sub">备选模板与打包校验</a>
<a href="#tpl-check" class="sub">制作检查清单</a>
<a href="#theme-mgr">主题管理</a>
<a href="#plugins">插件机制</a>
<a href="#pl-arch" class="sub">架构总览</a>
<a href="#pl-official" class="sub">官方内置插件</a>
<a href="#pl-ui" class="sub">插件管理页</a>
<a href="#pl-pkg" class="sub">上传/卸载/下载</a>
<a href="#api">REST 内容 API</a>
<a href="#i18n">国际化</a>
<a href="#i18n-config" class="sub">后台配置</a>
<a href="#i18n-dev" class="sub">翻译工作流</a>
<a href="#i18n-plugin" class="sub">插件国际化</a>
<a href="#i18n-content" class="sub">内容级多语言(v2.5)</a>
</div>
<div class="toc-group">
<h2>插件开发实战</h2>
<a href="#plugin-dev">插件开发手册</a>
<a href="#pd-arch" class="sub">机制总览</a>
<a href="#pd-quick" class="sub">五分钟上手(示例插件)</a>
<a href="#pd-manifest" class="sub">manifest 字段参考</a>
<a href="#pd-baseapi" class="sub">PluginBase API 参考</a>
<a href="#pd-models" class="sub">数据模型与开发要点</a>
<a href="#pd-search" class="sub">全站搜索提供者</a>
<a href="#pd-life" class="sub">打包上传与生命周期</a>
<a href="#pd-test" class="sub">自测清单</a>
<a href="#pd-common" class="sub">常见陷阱</a>
</div>
<div class="toc-group">
<h2>运维进阶</h2>
<a href="#upgrade">v1.1 → v2.0 升级</a>
<a href="#alembic">数据库迁移 (Alembic)</a>
<a href="#search">全文搜索</a>
<a href="#docker">Docker 容器化</a>
<a href="#oss">对象存储 OSS</a>
<a href="#redis">Redis 缓存与 Session</a>
<a href="#faq">运维故障排查 FAQ</a>
<a href="#faq-db" class="sub">数据库与 Alembic 迁移</a>
<a href="#faq-cache" class="sub">缓存与 Redis</a>
<a href="#faq-theme" class="sub">主题与插件</a>
<a href="#faq-rewrite" class="sub">伪静态与路由</a>
<a href="#faq-docker" class="sub">Docker 专项</a>
</div>
</nav>
<main>
<header class="hero">
<h1>ZhyCMS 使用手册 <span class="version-badge">v3.2.6</span></h1>
<p>基于 Flask 的轻量级企业网站 CMS — 快速入门 · 使用指南 · 扩展开发 · 运维进阶</p>
</header>
<section id="intro">
<h2>项目简介</h2>
<p>ZhyCMS 是一个基于 <b>Flask + SQLAlchemy</b> 的轻量级企业内容管理系统,采用「插件优先、主题驱动」架构,适合搭建企业官网、资讯门户、产品展示站等。</p>
<p>系统严格区分「CMS 自身标识」与「前台企业标识」,后台品牌固定不可改,前台信息独立配置。</p>
<div class="warn"><b>从 v1.1 升级:</b>v2.0 起新增 9 张数据表、旧表补 12 列,请先阅读项目根目录 <b>UPGRADE.md</b> 并执行 <code>scripts/upgrade_v2.py</code> 完成迁移。</div>
</section>
<section id="features">
<h2>特性一览</h2>
<table>
<tr><th>能力</th><th>说明</th><th>版本</th></tr>
<tr><td>多主题模板系统</td><td>8 套内置主题(含 2 套英文),后台一键切换,栏目级模板选择</td><td>v1.0</td></tr>
<tr><td>插件机制</td><td>零侵入扩展,启停即时生效,内置 8 个官方插件 + 3 个社区插件</td><td>v2.2</td></tr>
<tr><td>国际化 i18n</td><td>Flask-Babel 中英文切换,插件独立翻译域</td><td>v2.3</td></tr>
<tr><td>数据库迁移</td><td>Flask-Migrate (Alembic),支持回滚与插件迁移脚本</td><td>v2.4</td></tr>
<tr><td>数据库迁移插件</td><td>内置插件 <code>db_migrator</code>(默认不启用):后台一键把 SQLite 开发库迁移到 MySQL/PostgreSQL,支持免重启热切换</td><td>v3.1.0</td></tr>
<tr><td>全文搜索</td><td>默认 Tantivy + pkuseg 中文分词,可选 Meilisearch,SQL LIKE 兜底</td><td>v2.4</td></tr>
<tr><td>对象存储 OSS</td><td>阿里云/腾讯云/七牛云,一键迁移,默认本地零变化</td><td>v2.4</td></tr>
<tr><td>Docker 部署</td><td>官方镜像 pollybird/zhycms 已发布,MySQL/PostgreSQL 一键启动,支持本地构建</td><td>v2.4</td></tr>
<tr><td>RBAC 权限</td><td>角色/权限点两级模型,菜单与按钮级授权,栏目级内容粒度</td><td>v2.0</td></tr>
<tr><td>内容工作流</td><td>草稿 → 待审核 → 已发布/已驳回,版本快照与对比还原</td><td>v2.0</td></tr>
<tr><td>后台编辑器双模式</td><td>富文本(CKEditor)/ Markdown 一键切换,实时预览,全局设置可改默认模式</td><td>v3.1.5</td></tr>
<tr><td>审计日志</td><td>登录、配置变更、内容 CRUD 全量留痕,多维度检索</td><td>v2.0</td></tr>
<tr><td>SEO 优化</td><td>伪静态、sitemap、robots.txt、页面缓存、图片默认 ALT</td><td>v2.0</td></tr>
<tr><td>表单收集</td><td>可视化表单设计,提交后邮件/企微实时通知</td><td>v2.0</td></tr>
<tr><td>备份恢复</td><td>MySQL/PostgreSQL/JSON 三种方式,一键备份与恢复</td><td>v2.0</td></tr>
<tr><td>可视化页面构建器</td><td>拖拽搭建首页/单页/列表/文章详情:24 组件、草稿/发布/修订回滚、双语与会员可见性、默认布局按主题 fixture + 插件片段三层合并;插件可注册组件并贡献默认布局;无布局永久回退手写模板</td><td>v3.0.0</td></tr>
<tr><td>异常留痕治理</td><td>全库通用异常捕获统一中文 warning 留痕,可判定场景收窄为具体异常类型;插件隔离处保留宽捕获并注释;新增 CI 门禁防止新增静默吞噬</td><td>v3.1.6</td></tr>
<tr><td>稳定性修复</td><td>批量操作 403 与批量勾选丢失修复;全站索引重建改为后台异步 + 进度轮询,增量变更自动补索引;数据库迁移新增外键孤儿预检与可空列自动置空</td><td>v3.1.7</td></tr>
<tr><td>安全加固</td><td>SAST 深度审计 P0+P1 修复:主题模板 SSTI 沙箱 + 上传审计、插件直传默认关闭 + 源码审计、敏感凭证 Fernet 加密入库、Webhook 与短信接口 SSRF 防护、JWT 密钥独立;新增 CSP 第三方资源白名单(后台可配)</td><td>v3.1.8</td></tr>
</table>
</section>
<section id="structure">
<h2>目录结构</h2>
<pre><code>zhycms/
├── app/
│ ├── admin/ # 后台模块
│ ├── frontend/ # 前台模块
│ │ └── templates/themes/ # 主题目录(8 套内置主题)
│ ├── models/ # 数据模型
│ ├── translations/ # 核心国际化翻译文件
│ ├── utils/ # 工具模块(上传、通知、存储、主题等)
│ ├── static/ # 静态资源
│ ├── __init__.py # 应用工厂
│ ├── config.py # 配置
│ ├── plugin_system.py # 插件运行时
│ ├── plugin_api.py # PluginBase 基类
│ └── extensions.py # 扩展初始化
├── plugins/ # 插件目录(7 个官方内置 + 3 个社区插件)
├── migrations/ # Alembic 迁移脚本
├── docker/ # Docker 部署辅助
├── instance/ # 实例数据(数据库、配置、备份等)
├── requirements.txt
├── Dockerfile
├── docker-compose.yml # 通用编排(--profile,本地构建)
├── docker-compose.mysql.yml # MySQL 独立编排(拉取 pollybird/zhycms:mysql)
├── docker-compose.postgresql.yml # PostgreSQL 独立编排(拉取 pollybird/zhycms:postgresql)
├── docker/
│ ├── install.sh # 一键安装脚本
│ ├── uninstall.sh # 卸载脚本
│ ├── entrypoint.sh # 容器入口
│ └── .env.example # 环境变量模板
├── wsgi.py / run.py
└── wiki.html # 本手册</code></pre>
<div class="note"><code>instance/</code> 存放数据库、配置、备份等敏感数据,已在 <code>.gitignore</code> 中排除,切勿提交到版本库。</div>
</section>
<section id="install">
<h2>安装与初始化</h2>
<h3 id="install-env">环境要求</h3>
<ul>
<li>Python 3.10+(CI 覆盖 3.10 / 3.11 / 3.12 / 3.13,3.14 实验性)</li>
<li>数据库:MySQL 5.7+ / PostgreSQL 12+(生产推荐)/ SQLite(仅开发)</li>
</ul>
<div class="warn"><b>生产环境请使用 MySQL 或 PostgreSQL。</b>SQLite 不支持并发写入,容易锁表。</div>
<h3 id="install-step">安装步骤</h3>
<pre><code>git clone https://gitee.com/pollybird/zhycms
cd zhycms
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
python run.py</code></pre>
<h3 id="install-setup">初始化向导</h3>
<p>首次访问 <code>http://127.0.0.1:5000</code> 自动跳转 <code>/admin/setup</code>,需配置:</p>
<ul>
<li>管理员账号(≥3 字符)与密码(默认 ≥12 位且含大小写、数字、特殊字符,可在后台安全中调整)</li>
<li>数据库类型(MySQL / PostgreSQL / SQLite)</li>
<li>演示数据:不生成 / 制造业 / 服务业 / 教育行业 / 餐饮行业 / Manufacturing (EN) / English Default</li>
</ul>
<h3 id="install-db">数据库选择</h3>
<table>
<tr><th>类型</th><th>说明</th><th>需填写</th></tr>
<tr><td><b>MySQL</b></td><td>生产首选,默认端口 3306</td><td>主机、端口、库名、用户名、密码</td></tr>
<tr><td><b>PostgreSQL</b></td><td>生产可选,默认端口 5432</td><td>主机、端口、库名、用户名、密码</td></tr>
<tr><td><b>SQLite</b></td><td>零配置,仅开发/测试</td><td>无</td></tr>
</table>
<div class="note">数据库 URI 优先级:环境变量 <code>ZHYCMS_DB_URI</code> > <code>instance/db_config.json</code> > 默认 SQLite。</div>
</section>
<section id="deploy">
<h2>部署方式</h2>
<h3 id="deploy-dev">开发模式</h3>
<pre><code>python run.py
# 监听 0.0.0.0:5000,DEBUG 模式,代码/模板改动自动重载</code></pre>
<h3 id="deploy-prod">生产部署</h3>
<pre><code># 方式一
ZHYCMS_ENV=production ZHYCMS_SECRET_KEY=your-secret python run.py
# 方式二(推荐)
gunicorn -w 4 -b 0.0.0.0:5000 "run:app"
# 或
python -m gunicorn -w 4 -b 0.0.0.0:5000 wsgi:app</code></pre>
<div class="warn">生产环境务必设置 <code>ZHYCMS_SECRET_KEY</code>;建议前置 Nginx 反向代理并托管静态资源。</div>
<h3 id="deploy-docker">Docker 部署 <span class="tag tag-new">v2.4</span></h3>
<p>官方镜像已发布到 Docker Hub(<code>pollybird/zhycms</code>)、GitHub Container Registry(<code>ghcr.io/pollybird/zhycms</code>)和阿里云 ACR(<code>crpi-9u7ztjb0thx22k1a.cn-hangzhou.personal.cr.aliyuncs.com/pollybird/zhycms</code>),当前版本 <b>v3.2.6</b>,开箱即用,无需本地构建。一键安装(推荐,自动生成密钥与密码、配置镜像加速):</p>
<pre><code>bash docker/install.sh</code></pre>
<p>或手动配置(拉取预构建镜像):</p>
<pre><code>cp docker/.env.example .env
# 编辑 .env 修改 SECRET_KEY 和数据库密码
# MySQL 8.4 方案(镜像 pollybird/zhycms:mysql)
docker compose -f docker-compose.mysql.yml up -d
# PostgreSQL 16 方案(镜像 pollybird/zhycms:postgresql)
docker compose -f docker-compose.postgresql.yml up -d
# 访问 http://localhost:5000 完成初始化</code></pre>
<p>也可直接拉取镜像(Docker Hub / GitHub GHCR / 阿里云 ACR 任选其一,国内推荐阿里云):</p>
<ul>
<li>Docker Hub:<code>docker pull pollybird/zhycms:mysql</code>(或 <code>:postgresql</code> / <code>:latest</code> / <code>:v3.2.6</code>)</li>
<li>GitHub GHCR:<code>docker pull ghcr.io/pollybird/zhycms:mysql</code>(或 <code>:postgresql</code> / <code>:latest</code> / <code>:v3.2.6</code>)</li>
<li>阿里云 ACR(国内推荐):<code>docker pull crpi-9u7ztjb0thx22k1a.cn-hangzhou.personal.cr.aliyuncs.com/pollybird/zhycms:mysql</code>(或 <code>:postgresql</code> / <code>:latest</code> / <code>:v3.2.6</code>)</li>
</ul>
<p>三个 tag(<code>mysql</code> / <code>postgresql</code> / <code>latest</code>)指向同一镜像,内置 MySQL + PostgreSQL 驱动,通过 <code>ZHYCMS_DB_URI</code> 切换数据库。容器启动时自动执行:数据库迁移 → 恢复演示图片 → 编译 i18n → 启动 gunicorn。<code>instance/</code> 和上传目录通过 volume 持久化。卸载运行 <code>bash docker/uninstall.sh</code>。</p>
<h3 id="deploy-env">环境变量</h3>
<table>
<tr><th>变量</th><th>默认值</th><th>说明</th></tr>
<tr><td><code>ZHYCMS_ENV</code></td><td>development</td><td>development / production</td></tr>
<tr><td><code>ZHYCMS_SECRET_KEY</code></td><td>内置默认值</td><td><b>生产必须修改</b></td></tr>
<tr><td><code>ZHYCMS_DB_URI</code></td><td>sqlite:///...</td><td>数据库 URI,优先级最高</td></tr>
</table>
<div class="note">v2.1 起前缀统一为 <code>ZHYCMS_</code>;旧前缀 <code>ZHOCMS_</code> 仍兼容但将在未来版本移除。</div>
</section>
<section id="demo">
<h2>演示数据与行业主题</h2>
<table>
<tr><th>选项</th><th>生成内容</th><th>自动主题</th></tr>
<tr><td>不生成</td><td>空站点</td><td>default</td></tr>
<tr><td>制造业</td><td>产品中心、新闻中心等栏目 + 文章 + 碎片 + 友链 + 演示图</td><td>manufacturing</td></tr>
<tr><td>服务业</td><td>服务项目、客户案例等栏目 + 文章 + 碎片 + 友链 + 演示图</td><td>service</td></tr>
<tr><td>教育行业 <span class="tag tag-new">v2.6.3</span></td><td>课程中心、师资力量、校园动态等栏目 + 文章(亮色调主题)</td><td>education</td></tr>
<tr><td>餐饮行业 <span class="tag tag-new">v2.6.3</span></td><td>招牌菜品、门店信息、美食资讯等栏目 + 文章(暖色调主题)</td><td>catering</td></tr>
<tr><td>Manufacturing (EN)</td><td>全英文栏目/文章/产品/轮播/友链/表单,自动启用 i18n</td><td>manufacturing_en</td></tr>
<tr><td>English Default</td><td>空白站,自动启用 i18n</td><td>default_en</td></tr>
</table>
<div class="note">演示数据由 <code>app/utils/bootstrap.py</code> 生成,每次生成前先清理旧数据;插件演示数据由各插件 <code>generate_demo_data</code> 钩子自行生成。</div>
</section>
<section id="identity">
<h2>CMS 标识与网站标识</h2>
<table>
<tr><th>概念</th><th>显示位置</th><th>来源</th><th>可否修改</th></tr>
<tr><td>CMS 名称</td><td>后台顶栏 / 登录页</td><td><code>Setting.CMS_NAME</code> 常量</td><td>❌ 不可改</td></tr>
<tr><td>后台版权</td><td>后台底部</td><td><code>Setting.CMS_COPYRIGHT</code> 常量</td><td>❌ 不可改</td></tr>
<tr><td>网站名称</td><td>前台导航 / 首页</td><td><code>Setting 'site_name'</code></td><td>✅ 网站设置可改</td></tr>
<tr><td>前台版权</td><td>前台底部</td><td><code>Setting 'footer_copyright'</code></td><td>✅ 网站设置可改</td></tr>
</table>
<div class="note">后台模板用 <code>cms_name</code> / <code>cms_copyright</code>;前台模板用 <code>site_settings.site_name</code> / <code>site_settings.footer_copyright</code>,不得混用。</div>
</section>
<section id="sitegroup">
<h2>站群模式(多站点)<span class="tag tag-new">v3.2.0</span></h2>
<p>后台菜单:<b>全局设置 → 站点管理</b>。一个实例 + 一个数据库按「站点」维度切分内容,同一套 CMS 同时服务多个独立前台站点。</p>
<table>
<tr><th>能力</th><th>说明</th></tr>
<tr><td>站点寻址</td><td>独立域名(<code>sites.domain</code> 精确匹配)或泛解析子域(<code>sites.subdomain</code> 标签,配合 <code>*.main.com</code>);未命中回退默认站点 0</td></tr>
<tr><td>后台切换</td><td>顶部下拉选择当前管理站点(仅可见有权限的站点);栏目/文章/碎片/表单/友链/产品/招聘/轮播均按当前站点过滤</td></tr>
<tr><td>站点级配置</td><td>站点名称、SEO、主题、统计代码等按站点覆盖;上传/API/搜索/插件等全局键各站共享</td></tr>
<tr><td>会员归属</td><td><b>共享</b>(默认,与单站一致)/ <b>独立</b>(各站会员互不相通),超管在站点设置页切换</td></tr>
<tr><td>站点状态</td><td><code>open</code> 正常访问 / <code>closed</code> 前台返回 503(维护模式)</td></tr>
</table>
<div class="note">默认站点 <code>site_id=0</code> 恒等变换:单站点部署 URL、行为、SEO 完全不变。不同站点可复用 <code>about</code>、<code>news</code> 等 slug。</div>
<div class="warn">站点 slug / 域名 / 子域标签三者均需唯一;默认站点不可删除,仍有栏目的站点不可删除。第三方插件自定义内容表需按开发者文档 §8.9 接入 <code>site_id</code>。</div>
</section>
<section id="rbac">
<h2>后台菜单结构 <span class="tag tag-new">v3.2.6</span></h2>
<p>侧边栏按作用域组织,站点级配置与平台级配置分区展示:</p>
<ul>
<li><b>站点设置(当前站点)</b>:网站设置、SEO 默认配置、SEO 高级、主题管理、消息通知、编辑设置、内容 API;切换当前站点后,修改作用于该站点。</li>
<li><b>全局设置(全站共用)</b>:站点管理、插件管理、上传配置、上传安全、后台安全、国际化、搜索设置、Redis 缓存;其中「站点管理」「插件管理」仅超级管理员或具备 <code>site:manage</code> 的账号可见,「Redis 缓存」仅超级管理员可见。</li>
<li><b>日志审计</b>:操作审计、登录日志;仅超级管理员与站点管理员可见,站点管理员只看到自己授权站点的记录。</li>
</ul>
<h2>用户、角色与权限(RBAC)</h2>
<p>后台菜单:<b>用户权限 → 用户列表 / 角色与权限</b></p>
<ul>
<li><b>权限点两级授权</b>:角色勾选权限点,同时控制后台<b>菜单可见性</b>与<b>操作按钮/接口</b>。</li>
<li><b>多角色并集</b>:一个用户可绑定多个角色,权限取并集。</li>
<li><b>内容粒度授权</b>:可按栏目授予文章管理权限(如「只管理新闻中心」)。</li>
<li><b>超级管理员</b>:内置超管不受权限限制;未授权菜单不可见,接口返回 403 并记录审计。</li>
<li><b>站点管理员(v3.2.3)</b>:拥有指定站点的全部后台管理权限(设置、用户、审计、栏目、内容、页面构建、表单),不含站点增删改与备份迁移等平台级功能。</li>
<li><b>角色按站分配(v3.2.3)</b>:站点管理员、内容审核员、内容编辑、只读查看员均绑定到具体站点;同一账号可拥有多个站点角色,登录后切换站点生效。</li>
<li><b>添加边界(v3.2.3)</b>:超级管理员可为任意站点分配角色;站点管理员只能在自己有权限的站点内添加角色,也只能管理角色全部落在该范围内的账号;「角色权限」页仅平台管理员可访问。</li>
</ul>
<div class="note">角色删除前自动解除用户绑定;用户禁用后立即无法登录,已有会话下次请求时失效。</div>
</section>
<section id="workflow">
<h2>内容工作流与版本管理</h2>
<h3>状态流转</h3>
<pre><code>草稿(draft) ──提交审核──→ 待审核(pending) ──审核通过──→ 已发布(published)
↑ │
└────────驳回──────────────┘ 已驳回(rejected)</code></pre>
<ul>
<li>无发布权限的作者只能保存草稿并提交审核;有权限的编辑可直接发布。</li>
<li>待审核文章仅具备审核权限的用户可见,前台不展示。</li>
<li>驳回时必须填写原因,作者可修改后重新提交。</li>
</ul>
<h3>版本快照</h3>
<p>文章每次保存自动生成版本快照,支持<b>查看差异</b>与<b>一键还原</b>(还原动作本身也生成新版本,可安全撤销)。</p>
</section>
<section id="editor">
<h2>Markdown 编辑模式 <span class="tag tag-new">v3.1.5</span></h2>
<p>后台所有富文本输入框(文章正文、单页栏目内容、富文本碎片,含各自多语言译文字段)均支持 <b>富文本(CKEditor)/ Markdown</b> 双模式编辑,编辑器顶部「富文本 | Markdown」分段控件一键切换。</p>
<h3>使用要点</h3>
<ul>
<li><b>默认仍为富文本</b>:升级后老内容以 CKEditor 打开,操作习惯零变化;新建内容默认模式可在 <b>站点设置 → 编辑设置</b> 中改为 Markdown(仅影响新建内容,v3.2.6 起按站点独立配置)。</li>
<li><b>Markdown 模式</b>:等宽编辑区 + 实时预览(输入停顿约 300ms 后渲染),支持插入图片(复用后台上传接口)与全屏编辑。</li>
<li><b>切换即转换</b>:富文本 → Markdown 由 turndown.js 转换,反向由 marked.js 转换;<b>切向 Markdown 时会弹二次确认</b>——表格样式、字体字号、颜色、对齐等 Markdown 无法表达的排版会丢失,未保存前刷新即可放弃。</li>
<li><b>存储约定</b>:无论哪种模式,<code>content</code> 列始终保存 HTML(Markdown 保存时服务端用 python-markdown 渲染),前台主题、搜索、内容 API 全部零改动;Markdown 原文另存 <code>*_md</code> 列,供再次编辑时原样回填。</li>
<li><b>版本回滚</b>:快照只存 HTML,回滚后该内容强制以富文本格式打开。</li>
<li><b>依赖兜底</b>:若服务器未安装 <code>markdown</code> 包(<code>pip install "markdown>=3.7,<4.0"</code>),后台不报错,Markdown 内容降级为纯文本转义;「编辑设置」页会展示依赖状态。</li>
</ul>
</section>
<section id="backup">
<h2>备份与恢复</h2>
<p>后台菜单:<b>备份运维 → 备份列表</b></p>
<table>
<tr><th>方式</th><th>适用</th><th>说明</th></tr>
<tr><td>MySQL 逻辑备份</td><td>MySQL / MariaDB</td><td><code>mysqldump</code> 导出,gzip 压缩</td></tr>
<tr><td>PostgreSQL 备份</td><td>PostgreSQL</td><td><code>pg_dump</code> 导出,gzip 压缩</td></tr>
<tr><td>JSON 备份</td><td>任意数据库</td><td>通用格式,适合小站迁移</td></tr>
</table>
<div class="warn">恢复操作会<b>覆盖当前数据库全部数据</b>,恢复前自动释放连接池避免锁表。建议先下载当前备份再执行恢复。</div>
</section>
<section id="notify">
<h2>表单消息通知</h2>
<p>后台菜单:<b>站点设置 → 消息通知</b>(仅对当前站点生效)</p>
<p>配置后,前台表单每收到一条提交都会实时推送。v2.3 起自定义表单已转为官方内置插件,配置页与设置键保持不变。v3.2.6 起该配置按站点独立:不同站点可分别设置收件人与推送渠道,前台表单通知会发送到所属站点的配置。</p>
<h3>邮件通知</h3>
<table>
<tr><th>配置项</th><th>示例</th></tr>
<tr><td>SMTP 服务器 / 端口 / SSL</td><td><code>smtp.exmail.qq.com</code> / <code>465</code> / 开启</td></tr>
<tr><td>SMTP 账号 / 密码</td><td>邮箱与授权码</td></tr>
<tr><td>发件人 / 发件地址</td><td>「官网线索」/ <code>noreply@example.com</code></td></tr>
<tr><td>收件人列表</td><td>逗号分隔多个</td></tr>
</table>
<p>邮件正文为 HTML 表格,含表单名、提交时间、访客 IP、来源页面与全部字段值。</p>
<h3>企业微信通知</h3>
<p>填写群机器人 Webhook 地址,支持 <code>@ 手机号列表</code>,消息为 markdown 格式。</p>
<h3>开关逻辑</h3>
<ul>
<li>邮件、企微两个渠道均有<b>独立开关</b>。</li>
<li>「全局通知开关」总控:关闭时静默跳过,不影响表单正常提交。</li>
<li>配置保存与每次通知触发均写入审计日志。</li>
</ul>
</section>
<section id="seo">
<h2>SEO 与站点性能</h2>
<p>后台菜单:<b>站点设置 → SEO 高级</b></p>
<h3 id="seo-rewrite">伪静态 URL</h3>
<table>
<tr><th>URL</th><th>含义</th><th>等价动态 URL</th></tr>
<tr><td><code>/about.html</code></td><td>栏目页(第 1 页)</td><td><code>/column/about</code></td></tr>
<tr><td><code>/about-2.html</code></td><td>栏目列表页第 2 页</td><td><code>/column/about?page=2</code></td></tr>
<tr><td><code>/article-12.html</code></td><td>文章详情</td><td><code>/column/{slug}/article/12</code></td></tr>
</table>
<ul>
<li>开关即时生效,无需重启;关闭后伪静态地址返回 404。</li>
<li>分页链接统一使用 <code>frontend_pager_url(column, page)</code> 助手,自动适配伪静态开关。</li>
<li><code>/about-1.html</code> 自动 301 规范到 <code>/about.html</code>。</li>
</ul>
<h3>sitemap 与 robots</h3>
<ul>
<li><b>sitemap.xml</b>:自动收录栏目与文章,独立配置更新频率/优先级;插件 URL 自动聚合。</li>
<li><b>robots.txt</b>:内置默认规则,支持追加自定义;后台前缀变更后自动跟随。</li>
</ul>
<h3 id="seo-cache">页面缓存与图片 ALT</h3>
<ul>
<li><b>页面缓存</b>:基于 Flask-Caching,首页/栏目/文章独立 TTL(默认 3600/1800/7200 秒);内容变更后自动清理对应缓存。</li>
<li><b>图片默认 ALT</b>:为缺失或空 <code>alt</code> 的 <code><img></code> 自动填充默认值。</li>
<li><b>图片 ALT 批量管理</b>:后台工具页,批量排查全站图片 ALT 缺失情况。</li>
</ul>
</section>
<section id="builder">
<h2>可视化页面构建器 <span class="tag tag-new">v3.0.0</span></h2>
<p>v3.0.0 新增自研轻量构建器:<b>原生 HTML5 拖拽 + JSON Schema 组件注册 + iframe 内服务端真实渲染</b>。布局以 JSON 存数据库(不生成磁盘文件),只有<b>已发布</b>布局的页面才走构建器,其余页面继续使用手写主题模板;删除构建记录即回退,老站升级零行为变化。构建器只接管内容区,header/导航/footer 与 SEO 基础信息仍由主题统一控制。</p>
<table>
<tr><th>作用域</th><th>页面</th><th>数据上下文</th></tr>
<tr><td>首页</td><td><code>/</code></td><td>全站最新文章</td></tr>
<tr><td>单页</td><td>type=page 叶子栏目</td><td>栏目正文、自定义字段</td></tr>
<tr><td>列表页</td><td>type=list 叶子栏目</td><td>当前栏目文章、分页(伪静态/缓存规则沿用)</td></tr>
<tr><td>文章详情</td><td>文章页</td><td>正文、字段、上下篇;栏目级缺省回退全局默认</td></tr>
</table>
<h3 id="builder-ui">编辑器与发布流程</h3>
<ul>
<li><b>左栏组件库</b>:布局/基础/数据三组,按页面作用域过滤;插件组件禁用时置灰。</li>
<li><b>中栏画布</b>:iframe 内是当前主题 + 真实数据的服务端渲染页面,支持桌面/平板/手机三宽;组件点击选中、拖拽排序与跨容器移动,蓝色指示条显示落点。</li>
<li><b>右栏属性/图层</b>:表单按 Schema 自动生成(文本/多行/富文本/数字/下拉/开关/颜色/图片/图标/栏目/重复项),文案支持中英 Tab,节点可设语言白名单与会员限定;图层树支持删除/复制/上下移。</li>
<li><b>草稿与发布</b>:修改 800ms 防抖自动存草稿(访客不可见);发布生成修订快照;修订历史一键回滚(回滚即发布并再记快照);支持「载入默认布局」向导。</li>
<li><b>权限</b>:<code>builder:manage</code>(编辑/草稿/预览,auditor+editor)与 <code>builder:publish</code>(发布/回滚/删除,仅 auditor),操作写审计日志。</li>
</ul>
<p>安全约束:服务端 allowlist 校验,单页深度 ≤ 8、节点 ≤ 300、体积 ≤ 256KB;单组件取数/渲染异常被隔离(前台跳过、画布黄色占位);插件禁用后其组件前台为空、画布提示,卸载前有引用则拒绝。</p>
<h3 id="builder-widgets">24 个内置组件</h3>
<table>
<tr><th>分组</th><th>组件</th></tr>
<tr><td>布局 ×6</td><td>section、container、grid-row、grid-col、spacer、divider</td></tr>
<tr><td>基础 ×8</td><td>heading、text、richtext、image、button、icon-box、alert、video-embed</td></tr>
<tr><td>数据 ×10</td><td>article-list、article-detail、page-content、breadcrumb、fragment、carousel、contact-card、cta-banner、friend-links、stat-numbers</td></tr>
</table>
<h3 id="builder-layouts">默认布局三层合并 <span class="tag tag-new">v3.0.0</span></h3>
<p>「新建构建页 / 载入默认布局」时按三层合并成初始草稿(<b>一次性快照</b>,之后切主题、启停插件均不回填已有草稿):</p>
<table>
<tr><th>层级</th><th>来源</th><th>说明</th></tr>
<tr><td>① 主题 fixture</td><td><code>themes/<主题>/builder/<scope>.json</code></td><td>主题未提供时回退核心 fixture;8 套官方主题必备首页布局,第三方上传主题可自带(上传时校验,非法整包拒绝)</td></tr>
<tr><td>② 插件贡献片段</td><td><code>plugins/<slug>/builder/<scope>.json</code></td><td>仅合并<b>当前已启用</b>插件的片段;<code>position</code> 支持 prepend(插最前)/append(追加,默认)+ 可选 <code>after</code> 锚点;多插件按 slug 升序</td></tr>
<tr><td>③ 校验与容错</td><td>—</td><td>撞节点 id 自动加 <code>n_<插件>__</code> 前缀重写;单片段失败只跳过自身;插件启用前片段强校验,非法拒绝启用</td></tr>
</table>
<p>轮播图(首屏轮播 prepend)、产品展示、招聘管理、教程中心四个内容型插件启用后,新首页默认布局自动带上对应区块,可在编辑器中调整或删除。</p>
<h3 id="builder-dev">组件开发 API</h3>
<p>组件 = <code>Widget</code> 子类(元数据 + <code>prop_schema</code> + <code>context()</code> 取数)+ Jinja partial。模板解析链:<code>themes/<主题>/builder/widgets/<type>.html</code> → <code>builder/widgets/<type>.html</code>(含插件模板目录)。核心代码位于 <code>app/builder/</code>(registry/schema/renderer/service/contrib/widgets)。插件经 <code>get_builder_widgets()</code> 钩子注册组件(owner=插件 slug,随启用状态门控),经 <code>get_builder_layouts()</code> 贡献默认布局片段(默认自动扫描插件包内 <code>builder/*.json</code>)。完整 API 与模板变量见仓库 <a href="https://github.com/pollybird/zhycms/blob/main/docs/PAGE_BUILDER.md">docs/PAGE_BUILDER.md</a>。</p>
<pre><code>from app.builder.registry import Widget
from app.constants import Builder as B
class PromoWidget(Widget):
type = 'mypromo-promo'
label = '促销横幅'
category = B.CAT_DATA
scopes = B.SCOPES
default_props = {{'text': '限时优惠'}}
prop_schema = [{{'key': 'text', 'label': '文案', 'type': 'text'}}]
def context(self, node, page_ctx):
return {{'rows': []}}
# 插件入口
class MyPlugin(PluginBase):
def get_builder_widgets(self):
return [PromoWidget]</code></pre>
</section>
<section id="security">
<h2>安全加固</h2>
<h3 id="sec-login">登录防暴破</h3>
<ul>
<li>连续输错密码 <b>5 次</b>(可配置)自动锁定 <b>10 分钟</b>(可配置),锁定期内正确密码也被拒绝。</li>
<li>登录页图形验证码:错误不累计密码失败次数。</li>
<li>异地 IP 登录提醒:检测到不同城市 IP 时顶部展示一次性安全横幅。</li>
<li>所有登录行为写入<b>登录日志</b>。</li>
</ul>
<h3>后台路由前缀</h3>
<p><b>全局设置 → 后台安全</b> 中修改前缀(如 <code>admin</code> → <code>manage-x8y2</code>)后<b>即时生效</b>,无需重启。旧前缀立即 404,页内跳转自动使用新前缀。忘记路由可删除 <code>instance/admin_config.json</code> 恢复默认。</p>
<h3 id="sec-password-policy">管理员密码复杂度(v3.2.4)</h3>
<p><b>全局设置 → 后台安全 → 管理员密码复杂度</b>(仅超级管理员可见):</p>
<ul>
<li>最低位数可在 <b>6-64</b> 位之间调整;</li>
<li>大写字母、小写字母、数字、特殊字符四项可分别勾选是否必须包含;</li>
<li>默认沿用 v3.1.10 严格策略:至少 12 位且四类字符齐全;</li>
<li>最低位数低于 8 位时,保存前弹出确认框提示安全风险;</li>
<li>策略对全部后台账号生效,初始化向导、个人改密、账号新建/重置密码的表单校验同步变化;存量密码不回溯校验。</li>
</ul>
<h3 id="sec-upload">上传安全与图片优化</h3>
<p>后台菜单:<b>全局设置 → 上传安全</b>,默认全部开启:</p>
<ul>
<li><b>后缀 + MIME 双重校验</b>:检查文件真实内容(magic bytes),伪装成图片的脚本直接拒绝。</li>
<li><b>SHA-256 内容去重</b>:相同内容只存一份,多处引用自动计数。</li>
<li><b>图片自动压缩 + 缩略图</b>:JPG/PNG 压缩(默认质量 80)并生成 300px 缩略图。</li>
<li><b>单文件上限</b>默认 10MB,可配置。</li>
</ul>
<h3 id="sec-audit">审计日志</h3>
<p>后台菜单:<b>日志审计 → 操作审计</b>。登录/登出、配置变更、内容增删改、备份恢复、权限调整等关键操作全量留痕,记录<b>操作人、IP、时间、类型与详情</b>;支持按模块、操作类型、操作人与时间范围检索。v3.2.6 起审计日志与登录日志仅超级管理员、站点管理员可见,站点管理员只看到自己授权站点的记录(筛选、导出与清理同步受限)。</p>
</section>
<section id="template">
<h2>主题模板开发 API <span class="tag tag-new">v2.6.4 全量整理</span></h2>
<p>前台基于 <b>Jinja2 + Bootstrap 4.6</b>,采用「多主题 + 栏目级模板」双层机制。内置 8 套主题:<code>default / blue / manufacturing / service / default_en / manufacturing_en / education / catering</code>。权威文档见仓库 <code>docs/THEME_TEMPLATE_API.md</code>。</p>
<h3 id="tpl-mech">机制与解析链</h3>
<pre><code>主题覆盖 themes/<active_theme>/<name>.html
↓ 不存在
插件自带 plugins/<slug>/templates/<name>.html(如 banner/hero_carousel.html)
↓ 不存在
default 主题兜底 themes/default/<name>.html</code></pre>
<p>创建新主题:<code>cp -r themes/default themes/green</code> → 修改 <code>css/style.css</code> 与 <code>manifest.json</code>(slug 需与目录名一致)→ 后台 <b>站点设置 → 主题管理</b> 启用。主题自动发现,无需代码注册。</p>
<h3 id="tpl-dir">主题目录结构与 manifest</h3>
<pre><code>themes/<slug>/
├── manifest.json # 主题元数据(builtin=true 内置保护)
├── base.html # 基础布局(必备)
├── index.html # 首页(必备)
├── list.html # 列表页默认(必备)
├── article.html # 文章详情默认(必备)
├── page.html # 单页默认(必备)
├── 404.html / 500.html # 错误页(必备)
├── closed.html # 维护/关闭提示(建议)
├── column_children.html # 父栏目子列表页(可选)
├── search.html # 搜索结果页(建议)
├── list_card.html … # 栏目级备选模板(可选)
└── css/ js/ images/ fonts/ # 静态资源(仅这四个子目录对外可访问)</code></pre>
<table>
<tr><th>manifest 字段</th><th>说明</th></tr>
<tr><td><code>slug</code></td><td>主题标识,<b>必须与目录名一致</b></td></tr>
<tr><td><code>name / version / description / author</code></td><td>展示信息</td></tr>
<tr><td><code>builtin</code></td><td><code>true</code> 内置主题:禁止覆盖上传与删除</td></tr>
<tr><td><code>template_required</code></td><td>追加必备模板声明(数组或逗号分隔),与系统必备集合并</td></tr>
</table>
<div class="note">系统必备模板 7 个:<code>index/list/article/page/base/404/500.html</code>。上传/启用前强制检查,任一缺失拒绝启用。</div>
<h3 id="tpl-base">base.html 契约</h3>
<p>所有页面通过 <code>{% extends theme_base %}</code> 继承当前主题 base.html,必须提供 <b>5 个 block</b>:</p>
<pre><code>{% block title %}{{ seo.title }}{% endblock %} {# <title>,拼接 site_settings.site_name #}
{% block css %}{% endblock %} {# 子页附加样式 #}
{% block locale_switcher %}…{% endblock %} {# 语言切换器(子页可整体替换) #}
{% block content %}{% endblock %} {# 页面主体 #}
{% block js %}{% endblock %} {# 子页附加脚本 #}</code></pre>
<p>标准骨架要素:样式(Bootstrap 4.6.2 / Font Awesome 5.15.4 / 主题 CSS)、SEO meta(<code>seo.keywords / seo.description</code>)、导航(末尾 <code>{{ member_user_menu() }}</code> + 语言切换器)、搜索框(<code>action="{{ url_for('frontend.search') }}"</code> 参数名 <code>q</code>)、flash 消息、统计代码位(<code>analytics_head()/analytics_body()</code>)、页脚(<code>footer_copyright</code> + ICP 碎片)。</p>
<h3 id="tpl-vars">全局模板变量(每页自动注入)</h3>
<table>
<tr><th>变量</th><th>类型</th><th>说明</th></tr>
<tr><td><code>site_settings</code></td><td>dict</td><td>全部站点设置(site_name / site_subtitle / site_logo / footer_copyright 等)</td></tr>
<tr><td><code>site_fragments</code></td><td>dict</td><td>碎片,键为 slug,取值 <code>{{ site_fragments.icp.value }}</code></td></tr>
<tr><td><code>nav_columns</code></td><td>list</td><td>顶层启用栏目树</td></tr>
<tr><td><code>nav</code></td><td>list</td><td>当前页导航树(节点结构见下)</td></tr>
<tr><td><code>current_theme</code></td><td>str</td><td>当前主题 slug</td></tr>
<tr><td><code>theme_base</code></td><td>str</td><td>当前主题 base.html 路径</td></tr>
<tr><td><code>cms_name / cms_copyright / cms_version</code></td><td>str</td><td><b>CMS 自身标识</b>(固定常量,仅供后台模板;前台用 <code>site_settings</code>)</td></tr>
</table>
<h3 id="tpl-funcs">Jinja 全局函数与过滤器</h3>
<table>
<tr><th>函数</th><th>说明</th></tr>
<tr><td><code>admin_url_for(endpoint, **values)</code></td><td>生成后台地址(自动跟随自定义前缀)</td></tr>
<tr><td><code>frontend_pager_url(column, page)</code></td><td><b>列表分页专用</b>:伪静态开 → <code>/{slug}.html</code> <code>/{slug}-{N}.html</code>;关 → <code>/column/{slug}?page=N</code>。切换设置后链接自动适配</td></tr>
<tr><td><code>t(obj, field)</code></td><td>内容级多语言取值,无翻译回退主表(v2.5)</td></tr>
<tr><td><code>_p('<插件slug>', '原文')</code> / <code>_('原文')</code></td><td>插件域翻译 / 核心域翻译</td></tr>
<tr><td><code>available_locales()</code> / <code>current_locale()</code></td><td>启用语言列表(<code>{'code','label','active'}</code>)/ 当前语言</td></tr>
<tr><td><code>banner_items(slug, limit)</code></td><td>轮播图分组:<code>[{'title','image_url','link_url','link_target'}]</code>,禁用返回 []</td></tr>
<tr><td><code>member_user_menu()</code></td><td>右上角会员菜单(HTML);会员插件禁用返回空串</td></tr>
<tr><td><code>current_member</code> / <code>friend_links()</code> / <code>notices(limit)</code> / <code>recruit_jobs(limit, only_open)</code> / <code>tutorials(limit)</code> 等</td><td>各插件模板函数(均可能返回空值,模板需 <code>{% if %}</code> 包裹)</td></tr>
</table>
<table>
<tr><th>过滤器</th><th>示例 / 输出</th></tr>
<tr><td><code>date</code> / <code>datetime</code> / <code>datetime_format</code></td><td><code>{{ a.published_at|date }}</code> → 2026-08-06;<code>|datetime</code> → 2026-08-06 22:30:00</td></tr>
<tr><td><code>truncate_text</code></td><td><code>{{ a.summary|truncate_text(80) }}</code> 截断加 ...</td></tr>
<tr><td><code>highlight</code></td><td>搜索关键词 <code><mark></code> 高亮(内部已转义防 XSS)</td></tr>
<tr><td><code>status_label / filesize / op_type_label / audit_detail</code></td><td>后台模板用</td></tr>
</table>
<h3 id="tpl-ctx">页面上下文与对象字段</h3>
<table>
<tr><th>模板</th><th>收到的变量</th></tr>
<tr><td><code>index.html</code></td><td><code>nav first_page latest_articles about_col products/services/news/cases courses/teachers/campus_news dishes/food_news</code>(各含 _col 与列表对)<code>seo</code></td></tr>
<tr><td><code>list*.html</code></td><td><code>column articles pagination nav seo</code></td></tr>
<tr><td><code>page*.html</code></td><td><code>column fields nav seo</code></td></tr>
<tr><td><code>column_children.html</code></td><td><code>column children nav seo</code></td></tr>
<tr><td><code>article*.html</code></td><td><code>column article fields latest_articles prev_article next_article nav seo</code></td></tr>
<tr><td><code>search.html</code></td><td><code>keyword results total page per_page nav seo</code></td></tr>
<tr><td><code>closed.html</code></td><td><code>seo</code>(状态码 503)</td></tr>
</table>
<pre><code>{{ article.title }} {{ article.summary }} {{ article.content|safe }}
{{ article.cover }} {{ article.published_at|date }} {{ article.get_field_value(field.id) }}
{{ column.name }} {{ column.slug }} {{ column.type }} {{ column.page_content|safe }}
{{ column.link_url }} / {{ column.link_target }} {{ column.parent_mode }} {{ column.member_only }}
{{ pagination.page }} / {{ pagination.pages }} / {{ pagination.total }}
{% for p in pagination.iter_pages() %} … {% endfor %} {# None 为省略号 #}
{{ site_fragments.contact_phone.value }} {# 碎片取值 #}</code></pre>
<p><code>seo</code> 统一为 <code>{'title','keywords','description'}</code>,文章页自动回退栏目/站点设置。导航节点为 <code>{'node': Column, 'children': […]}</code>,外链栏目用 <code>col.link_url</code> + <code>col.link_target</code>。</p>
<h3 id="tpl-url">URL 生成与分页</h3>
<pre><code>{{ url_for('frontend.index') }}
{{ url_for('frontend.column_detail', slug=column.slug) }}
{{ url_for('frontend.article_detail', slug=column.slug, aid=article.id) }}
{{ url_for('frontend.search') }}
{# 主题静态资源(仅 css/js/images/fonts 四目录,带 1 天浏览器缓存) #}
<link rel="stylesheet" href="{{ url_for('frontend.theme_asset', slug=current_theme, filename='css/style.css') }}">
{# 分页链接必须走 frontend_pager_url(伪静态开关自动适配、缓存按页独立) #}
{% if pagination.has_prev %}<a href="{{ frontend_pager_url(column, pagination.page - 1) }}">上一页</a>{% endif %}
{% for p in pagination.iter_pages() %}
{% if p %}<a class="{{ 'active' if p == pagination.page }}" href="{{ frontend_pager_url(column, p) }}">{{ p }}</a>{% else %}<span>…</span>{% endif %}
{% endfor %}</code></pre>
<h3 id="tpl-i18n">i18n 与图片占位</h3>
<ul>
<li>界面文案 <code>{{ _('首页') }}</code>;插件文案 <code>{{ _p('member', '登录') }}</code>;内容字段 <code>{{ t(article, 'title') }}</code>(未启用 i18n 直接返回主表字段)。</li>
<li>语言切换器用 <code>available_locales()</code> + <code>current_locale()</code>,切换链接 <code>{{ request.path }}?lang={{ loc.code }}</code>。</li>
<li>封面位逻辑:<code>{% if a.cover %}真图{% else %}渐变+图标占位{% endif %}</code>;正文/摘要图片缺 ALT 时视图层自动注入,模板无需处理。</li>
<li>富文本一律 <code>|safe</code>;其他用户可控内容<b>禁止</b> <code>|safe</code>。</li>
<li>整页缓存按「页面+参数+语言+主题」键控:模板内不要输出 per-user 内容(登录态走 <code>member_user_menu()</code> 等函数位)。</li>
</ul>
<h3 id="tpl-alt">备选模板与打包校验</h3>
<p>创建 <code>list_xxx.html</code> / <code>article_xxx.html</code> / <code>page_xxx.html</code>,后台栏目编辑页自动出现在下拉选项中。受保护模板(不会列为备选):<code>base, 404, 500, closed, form_closed, index, search, column_children, form</code>。栏目指定模板缺失时自动回退默认模板,不报错。</p>
<table>
<tr><th>上传校验</th><th>规则</th></tr>
<tr><td>格式</td><td>仅 <code>.zip / .tar.gz / .tgz</code>;含 manifest.json + 7 必备模板</td></tr>
<tr><td>安全</td><td>路径穿越拒绝、symlink 跳过、损坏包拒绝</td></tr>
<tr><td>slug</td><td>合法 JSON、正则校验、与目录名一致</td></tr>
<tr><td>形态</td><td>形态 A(根目录即主题)/ B(单层子目录)自动归一化</td></tr>
<tr><td>覆盖</td><td>内置主题禁覆盖;同名自定义主题需先删再传(删除需验证码)</td></tr>
<tr><td>启用</td><td>写 OP_CONFIG_CHANGE 审计日志,并无条件清空整页缓存</td></tr>
</table>
<h3 id="tpl-check">主题制作检查清单</h3>
<ul class="check">
<li>7 个必备模板齐全,manifest.json 的 slug 与目录名一致</li>
<li>所有页面 <code>{% extends theme_base %}</code>,base 提供 5 个 block</li>
<li>分页链接统一 <code>frontend_pager_url(column, p)</code></li>
<li>富文本 <code>|safe</code>,用户可控字符串不 <code>|safe</code></li>
<li>导航包含 <code>member_user_menu()</code> 与语言切换器位</li>
<li>接入 <code>analytics_head()/analytics_body()</code></li>
<li><code>closed.html / search.html / 403.html</code> 已适配</li>
<li>伪静态开关两种模式下列表/详情链接均正确</li>
<li>静态资源仅放 css/js/images/fonts 四个白名单目录</li>
</ul>
</section>
<section id="theme-mgr">
<h2>主题管理 <span class="tag tag-new">v2.2</span></h2>
<p>入口:<b>站点设置 → 主题管理</b>(权限 <code>system:settings</code>)。</p>
<h3>主题列表</h3>
<ul>
<li><b>使用中</b>(绿色高亮):当前启用主题。</li>
<li><b>未启用</b>:可一键启用。</li>
<li><b>模板不完整</b>(标红):缺失必备模板,操作按钮灰显。</li>
</ul>
<h3>上传主题</h3>
<p>支持 <code>.zip / .tar.gz / .tgz</code>,8 步校验:</p>
<ol>
<li>扩展名白名单</li>
<li>压缩包完整性</li>
<li>路径穿越拦截(预检 + <code>_safe_join</code>)</li>
<li>符号链接/特殊文件静默跳过</li>
<li>manifest 合法 JSON + slug 格式正则</li>
<li>必备模板 7 个全量存在</li>
<li>单目录/平铺形态自动归一化</li>
<li>内置主题禁止覆盖;同名自定义主题先删后传</li>
</ol>
<div class="note">全程临时目录,任何失败不写入 <code>themes/</code>,finally 彻底清理。</div>
<h3>启用 / 删除 / 下载</h3>
<ul>
<li><b>启用</b>:启用前再次强检必备模板;前台即时生效,无需重启。</li>
<li><b>删除</b>:红色警告模态框 + 图形验证码确认;内置/启用中主题不可删。</li>
<li><b>下载</b>:打包为 zip(含全部静态资源),可在其他站点直接上传复用。</li>
</ul>
<h3>安全兜底</h3>
<p><code>get_active_theme()</code> 在主题目录不存在或模板不全时自动回退 <code>default</code>,杜绝前台白屏。</p>
</section>
<section id="plugins">
<h2>插件机制 <span class="tag tag-new">v2.2</span></h2>
<h3 id="pl-arch">架构总览</h3>
<ul>
<li><b>发现与加载</b>:启动时扫描 <code>plugins/*/__init__.py</code>,导入失败仅标红不拖垮启动。</li>
<li><b>门控</b>:以 <code>Setting('enabled_plugins')</code> 逗号分隔 slug 集合为唯一真值。</li>
<li><b>启用</b>:幂等写入权限点 → 预设角色补授权 → <code>db.create_all()</code> 建表 → 写启用清单。</li>
<li><b>禁用</b>:仅从清单移除 slug,<b>不删表、不清数据</b>;前台/后台/API 即时隐身。</li>
</ul>
<h3 id="pl-official">官方内置插件</h3>
<table>
<tr><th>slug</th><th>名称</th><th>关键接口</th></tr>
<tr><td>banner</td><td>轮播图</td><td><code>banner_items('home-hero')</code>;<code>GET /api/v1/banners/<slug></code></td></tr>
<tr><td>product</td><td>产品展示</td><td><code>product_latest()</code>;<code>/product-<id>.html</code>;<code>GET /api/v1/products/<id></code>;全站搜索提供者</td></tr>
<tr><td>friend_link</td><td>友情链接</td><td><code>friend_links()</code>;后台 <code>/friend-links</code></td></tr>
<tr><td>form</td><td>自定义表单</td><td>后台 <code>/forms</code>;前台 <code>/form/<slug></code>;v2.3 由核心转插件</td></tr>
<tr><td>analytics</td><td>统计代码</td><td><code>analytics_head()|safe</code> / <code>analytics_body()|safe</code>;v2.3 新增</td></tr>
<tr><td>oss_storage</td><td>对象存储</td><td>阿里云/腾讯云/七牛云;v2.4 新增</td></tr>
<tr><td>recruit</td><td>招聘管理</td><td><code>recruit_jobs()</code>;<code>/job-<id>.html</code>;简历上传;全站搜索提供者;v3.0.0 起含构建器组件与默认布局片段(社区插件)</td></tr>
<tr><td>auto_translate</td><td>一键翻译</td><td>编辑页多语言 Tab 一键调用百度/有道/Google/DeepSeek 翻译;v2.5.2 新增</td></tr>
<tr><td>db_migrator</td><td>数据库迁移</td><td>后台把 SQLite 开发库一键迁移到 MySQL/PostgreSQL:建表、按外键依赖逐表复制、PostgreSQL 重置序列、同步 Alembic 版本号;目标库非空保护、连接测试、迁移后免重启热切换;v3.1.0 新增(默认不启用)</td></tr>
<tr><td>tutorial</td><td>教程中心</td><td><code>/tutorials</code> 前台教程列表与详情、难度/时长、分类管理;v3.0.0 新增,含构建器组件与默认布局片段(社区插件)</td></tr>
<tr><td>member</td><td>前台用户中心</td><td>注册/登录/资料/改密/找回密码、微信/QQ 一键登录、短信验证码登录、注册协议、栏目会员可见性;v2.6.4 新增(社区插件,<code>builtin=false</code>)</td></tr>
</table>
<h3 id="pl-ui">插件管理页</h3>
<p>后台 <b>系统 → 插件管理</b>(权限 <code>system:plugins_manage</code>)。列出全部已发现插件,导入失败的标红显示错误栈;启用/禁用写入审计日志。v2.6.4 起列表中以徽章展示插件的最低核心版本(蓝)、依赖插件(黄)、父插件(紫)。</p>
<h3 id="pl-pkg">上传 / 卸载 / 打包下载</h3>
<ul>
<li><b>上传</b>:<code>.zip/.tar.gz/.tgz</code>,8 层校验后解压至 <code>plugins/</code>;失败零写入。</li>
<li><b>下载</b>:打包 zip,可在其他站点直接上传复用;写入导出审计。</li>
<li><b>卸载</b>:验证码确认后物理删除目录;内置/启用中不可卸载;<b>数据表保留</b>。</li>
</ul>
</section>
<section id="api">
<h2>REST 内容 API <span class="tag tag-new">v2.2</span></h2>
<p>前缀 <code>/api/v1</code>,只读端点,供小程序/Headless 前端消费。</p>
<h3>配置与鉴权</h3>
<ul>
<li><b>总开关</b>(<code>api_enable</code>):关闭后所有端点返回 404。</li>
<li><b>鉴权模式</b>(<code>api_auth_mode</code>,v2.6.3):<code>token</code>(仅 X-API-Token)/ <code>jwt</code>(仅 Bearer JWT)/ <code>both</code>(默认,优先 JWT 回退 Token)。</li>
<li><b>静态 Token</b>(<code>api_token</code>):非空时要求请求头 <code>X-API-Token</code>。</li>
<li><b>JWT 登录</b>(v2.6.3):<code>POST /api/v1/auth/login</code> 用用户名密码换取 <code>access_token</code>(15min)+ <code>refresh_token</code>(7d),请求头 <code>Authorization: Bearer <access_token></code>。</li>
<li><b>JWT 刷新</b>:<code>POST /api/v1/auth/refresh</code>(Header 带 refresh_token)换新 access_token。</li>
<li><b>速率限制</b>(v2.6.3,<code>api_rate_limit_enable</code>):登录 5 次/分钟、只读 GET 120 次/分钟,超限返回 429。</li>
<li><b>按站点独立配置</b>(v3.2.6):<code>api_enable</code> / <code>api_auth_mode</code> / <code>api_token</code> / <code>jwt_secret_key</code> / 缓存 TTL / CORS / 速率限制均为站点级,可在「站点设置 → 内容 API」为每个站点分别设置;JWT 按当前站点密钥签发与校验,跨站 token 不通用。</li>
<li><b>CORS</b>(<code>api_cors_origins</code>):<code>*</code> 或逗号分隔域名。</li>
<li><b>缓存 TTL</b>(<code>api_cache_ttl</code>):默认 300 秒。</li>
</ul>
<h3>统一响应格式</h3>
<pre><code>{
"code": 0, // 0=成功
"message": "ok", // 错误时为中文说明
"data": ..., // 成功数据
"meta": {...} // 列表分页信息
}</code></pre>
<h3>核心端点</h3>
<table>
<tr><th>端点</th><th>说明</th></tr>
<tr><td><code>POST /api/v1/auth/login</code></td><td>JWT 登录,返回 access/refresh token <span class="tag tag-new">v2.6.3</span></td></tr>
<tr><td><code>POST /api/v1/auth/refresh</code></td><td>刷新 access_token <span class="tag tag-new">v2.6.3</span></td></tr>
<tr><td><code>POST /api/v1/auth/logout</code></td><td>登出(客户端删除 token)<span class="tag tag-new">v2.6.3</span></td></tr>
<tr><td><code>GET /api/v1/columns</code></td><td>栏目导航树</td></tr>
<tr><td><code>GET /api/v1/columns/<slug></code></td><td>栏目详情</td></tr>
<tr><td><code>GET /api/v1/columns/<slug>/articles</code></td><td>栏目文章分页(<code>page/per_page/keyword</code>)</td></tr>
<tr><td><code>GET /api/v1/articles/<id></code></td><td>文章详情(含 prev/next)</td></tr>
<tr><td><code>GET /api/v1/banners/<slug></code></td><td>轮播图分组(banner 插件)</td></tr>
<tr><td><code>GET /api/v1/columns/<slug>/products</code></td><td>产品列表(product 插件)</td></tr>
<tr><td><code>GET /api/v1/products/<id></code></td><td>产品详情(product 插件)</td></tr>
</table>
<div class="note">第三方插件开发时把端点挂在核心 <code>api_bp</code>(<code>get_api_routes(api_bp)</code> 钩子),自动享受总开关、鉴权、CORS、缓存与审计。</div>
</section>
<section id="i18n">
<h2>国际化 <span class="tag tag-new">v2.3</span></h2>
<p>基于 Flask-Babel,前台+后台全站生效。<b>默认关闭</b>(<code>i18n_enable=0</code>),不影响现有站点;仅界面文案翻译,内容数据不翻译。</p>
<h3 id="i18n-config">后台配置</h3>
<p>入口:<b>全局设置 → 国际化</b>(权限 <code>system:settings</code>)。</p>
<table>
<tr><th>设置项</th><th>默认值</th><th>说明</th></tr>
<tr><td><code>i18n_enable</code></td><td>关闭</td><td>总开关</td></tr>
<tr><td><code>i18n_default_locale</code></td><td><code>zh</code></td><td>兜底语种</td></tr>
<tr><td><code>i18n_available_locales</code></td><td><code>zh</code></td><td>逗号分隔,如 <code>zh,en</code></td></tr>
</table>
<h4>Locale 选择优先级</h4>
<ol>
<li>URL 参数 <code>?lang=en</code>(一次性,写回 session)</li>
<li>session 中记录的语种</li>
<li>cookie 中的语种</li>
<li>浏览器 <code>Accept-Language</code> 自动匹配</li>
<li>默认语种 <code>zh</code> 兜底</li>
</ol>
<h3 id="i18n-dev">翻译工作流</h3>
<p>模板中用 <code>_()</code> 标记可翻译字符串:</p>
<pre><code><p>{{ _('仪表盘') }}</p>
<input placeholder="{{ _('搜索文章') }}"></code></pre>
<p>翻译文件位于 <code>app/translations/<lang>/LC_MESSAGES/messages.po</code>(当前提供英文 <code>en</code>)。<code>.po</code> 入库,<code>.mo</code> 不入库,<b>部署前需编译</b>:</p>
<pre><code># 提取
pybabel extract -F babel.cfg -o app/translations/messages.pot app/
# 更新
pybabel update -i app/translations/messages.pot -d app/translations
# 编译(部署前必做)
pybabel compile -d app/translations
# 新增语种
pybabel init -i app/translations/messages.pot -d app/translations -l ja</code></pre>
<h3 id="i18n-plugin">插件国际化</h3>
<p>每个插件拥有<b>独立翻译域</b>,在 <code>plugins/<slug>/translations/</code> 下维护 <code>.po/.mo</code>,核心启动时自动发现。</p>
<h4>模板层:_p() 函数</h4>
<pre><code><!-- 插件模板中 -->
<h3>{{ _p('product', '产品列表') }}</h3>
<a href="...">{{ _p('product', '上一个产品') }}</a></code></pre>
<h4>Python 层:plugin._()</h4>
<pre><code>from . import plugin
title = plugin._('产品详情') # 等价于 _p('product', '产品详情')</code></pre>
<h4>提取/编译命令</h4>
<pre><code># 提取插件模板和 Python 代码
pybabel extract -F babel.cfg -o plugins/product/translations/messages.pot plugins/product/
# 初始化/更新/编译(与核心相同,指定插件目录)
pybabel init -i ... -d plugins/product/translations -l en
pybabel update -i ... -d plugins/product/translations
pybabel compile -d plugins/product/translations</code></pre>
<div class="warn"><code>.mo</code> 文件在 <code>.gitignore</code> 中排除,<b>部署前必须对每个插件执行 pybabel compile</b>。</div>
<h3 id="i18n-content">内容级多语言(i18n 2.0)<span class="tag tag-new">v2.5</span></h3>
<p>v2.3 的国际化是<b>界面文案级别</b>(后台按钮、菜单等固定文案的中英文切换)。v2.5 新增<b>内容级多语言</b>:文章标题、栏目名称、碎片内容、产品详情、表单说明、岗位描述、友情链接名称等<b>动态数据</b>也支持多语言版本存储,前台按当前 locale 自动渲染对应语言内容。</p>
<h4>翻译表设计</h4>
<table>
<tr><th>主表</th><th>翻译表</th><th>翻译字段</th></tr>
<tr><td>articles</td><td>article_translations</td><td>title, summary, content, seo_title, seo_keywords, seo_description</td></tr>
<tr><td>columns</td><td>column_translations</td><td>name, summary, page_content, seo_title, seo_keywords, seo_description</td></tr>
<tr><td>fragments</td><td>fragment_translations</td><td>value(仅内容值,名称不翻译)</td></tr>
<tr><td>products</td><td>product_translations</td><td>title, summary, content, seo_*;specs(规格参数 JSON,v2.5.2)</td></tr>
<tr><td>forms</td><td>form_translations</td><td>name, description, success_message</td></tr>
<tr><td>recruit_jobs</td><td>recruit_job_translations</td><td>title, description;department, location, salary(v2.5.2)</td></tr>
<tr><td>friend_links</td><td>friend_link_translations</td><td>name(仅名称,URL 不翻译)</td></tr>
</table>
<div class="note"><b>设计原则</b>:主表保留默认语言字段(冗余),翻译表仅存非默认语言。查不到翻译时 fallback 主表默认语言,不会出现空白。<code>slug</code> 不随语言变化,URL 保持稳定。<b>v2.5.2 起结构化字段同样可翻译</b>:产品规格参数(JSON,结构同主表,留空回退主表)、岗位的部门/工作地点/薪资待遇(短文本,留空回退主表),对应 Alembic 迁移 <code>0007</code>。</div>
<h4>前台模板:t() 全局函数</h4>
<pre><code><!-- 6 套主题模板已接入,自定义主题按此模式适配 -->
<h1>{{ t(article, 'title') }}</h1>
<p>{{ t(article, 'summary') }}</p>
<div>{{ t(article, 'content')|safe }}</div>
<!-- 栏目名称 -->
<a href="...">{{ t(column, 'name') }}</a>
<!-- 碎片内容 -->
{{ t(fragment, 'value')|safe }}
<!-- 友情链接名称 -->
<a href="{{ l.url }}">{{ t(l, 'name') }}</a></code></pre>
<div class="note">页面缓存键自动加入 locale,不同语言互不串扰。产品 API 缓存键同样加入 locale。</div>
<h4>后台编辑:多语言版本 Tab</h4>
<p>在文章/栏目/碎片/产品/表单/岗位/友情链接编辑页,开启 i18n 后显示「多语言版本」Tab,按语种切换录入翻译。富文本翻译字段使用 CKEditor5,与主编辑器配置一致。</p>
<div class="tip">碎片仅翻译内容值(名称不随语言变化);友情链接仅翻译名称(URL/LOGO 不随语言变化)。</div>
</section>
<section id="plugin-dev">
<h2>插件开发手册 <span class="tag tag-new">v2.6.4 全量整理</span></h2>
<p>插件是 ZhyCMS 的核心扩展机制:后台菜单、前台页面、模板函数、导航、sitemap、全站搜索、REST API、存储驱动、演示数据,全部通过统一钩子接入。<b>启用/禁用即时生效,无需重启。</b>本章为完整手册(权威文档见仓库 <code>docs/PLUGIN_DEV.md</code>),第 2 节内嵌一个可直接落地的最小示例插件;<code>plugins/recruit</code>(招聘管理)为完整实战样板,可在后台「插件管理」下载源码对照学习。</p>
<h3 id="pd-arch">1. 机制总览</h3>
<pre><code>plugins/<slug>/
├── manifest.json # 纯元数据(上传校验、后台展示用)
├── __init__.py # PluginBase 子类 + 模块级 plugin 实例(必需)
├── models.py # 数据模型(可选,导入即注册进 db.metadata)
├── admin.py # 后台路由(可选,挂核心 admin_bp)
├── frontend.py # 模板函数(可选)
├── frontend_routes.py# 前台蓝图(可选)
├── search.py # 全站搜索提供者(可选)
├── migrations/versions/*.py # 插件自有 Alembic 迁移(可选,自动合并)
├── translations/ # 插件独立翻译域(可选)
├── static/ # 前台静态资源(可选)
└── templates/ # 模板(后台 admin/<slug>/,前台 <slug>/)</code></pre>
<pre><code>启动期(discover_and_load):
全量导入所有插件 → 注册蓝图/模板函数/菜单/API/权限点/迁移/驱动 → 门控交给运行时
运行期:
enabled_plugins 设置项(DB)单一开关 →
视图守卫(未启用 404)、菜单隐藏、模板函数返回 fallback 值
→ 启停只改一个设置值,多 worker 天然一致,无需重启</code></pre>
<table>
<tr><th>操作</th><th>行为</th><th>数据保留</th></tr>
<tr><td>启用</td><td>种子权限 → 角色授权 → 建表 → 写清单</td><td>复用历史数据</td></tr>
<tr><td>禁用</td><td>从清单移除 slug + <code>on_disabled()</code> 回调</td><td>表与数据保留</td></tr>
<tr><td>卸载</td><td>验证码确认后物理删目录</td><td>数据表保留</td></tr>
<tr><td>上传/下载</td><td>8 层校验解压 / 一键 zip 打包</td><td>—</td></tr>
</table>
<div class="note">模板解析链:<b>主题覆盖 → 插件自带 → default 主题兜底</b>。</div>
<h3 id="pd-quick">2. 五分钟上手:最小完整示例插件</h3>
<p>以下是完整可运行的「公告板」插件(slug: <code>notice</code>):后台管理页 + 前台列表页 + 模板函数 + 导航贡献。新建 <code>plugins/notice/</code> 放入以下文件,后台「插件管理」刷新即可启用。</p>
<p><b>manifest.json</b></p>
<pre><code>{
"slug": "notice",
"name": "公告板",
"version": "1.0.0",
"description": "站点公告发布与前台展示,插件开发示例。",
"author": "ZhyCMS 社区示例",
"builtin": false,
"min_core_version": "2.6.4",
"requires": [],
"extends": ""
}</code></pre>
<p><b>__init__.py</b>(入口,必需)</p>
<pre><code>from app.plugin_api import PluginBase
from .models import Notice # 顶部导入,保证 db.create_all() 前注册
from .frontend import notice_list
class NoticePlugin(PluginBase):
slug = 'notice'
name = '公告板'
version = '1.0.0'
permissions = [('notice:manage', '公告管理', '站点公告的发布与维护')]
preset_role_grants = {'content_editor': ['notice:manage']}
audit_modules = [('notice', '公告板')]
def get_admin_routes(self, admin_bp):
from . import admin # 导入即向 admin_bp 注册路由
def get_admin_menu(self):
return [{'label': '公告管理', 'endpoint': 'admin.notice_index',
'icon': 'fa-bullhorn', 'permission': 'notice:manage'}]
def get_frontend_blueprint(self):
from .frontend_routes import notice_frontend
return notice_frontend
def get_jinja_globals(self):
return {'notices': notice_list}
def get_jinja_fallbacks(self): # 禁用时模板函数返回空值,主题无需判空报错
return {'notices': []}
def get_frontend_menu(self):
return [{'label': '网站公告', 'url': '/notices', 'target': ''}]
plugin = NoticePlugin() # 必需!核心通过模块级 plugin 变量识别</code></pre>
<p><b>models.py</b></p>
<pre><code>from datetime import datetime
from app import db
class Notice(db.Model):
__tablename__ = 'notices'
STATUS_ON = 'on'
STATUS_OFF = 'off'
id = db.Column(db.Integer, primary_key=True)
title = db.Column(db.String(200), nullable=False)
content = db.Column(db.Text) # 富文本,前台 |safe 输出
status = db.Column(db.String(10), default=STATUS_ON)
sort_order = db.Column(db.Integer, default=0)
is_deleted = db.Column(db.Boolean, default=False)
created_at = db.Column(db.DateTime, default=datetime.now)
@classmethod
def visible(cls):
return (cls.query.filter_by(is_deleted=False, status=cls.STATUS_ON)
.order_by(cls.sort_order.desc(), cls.id.desc()))</code></pre>
<p><b>admin.py</b>(后台路由,挂核心 admin_bp,三层守卫)</p>
<pre><code>from functools import wraps
from flask import abort, flash, redirect, render_template, request
from app import db
from app.admin import bp as admin_bp # 核心 admin_bp,不要自建后台蓝本
from app.decorators import permission_required
from app.models.audit import audit_log
from app.plugin_system import plugin_enabled
from .models import Notice
def _gate(view):
@wraps(view)
def wrapper(*args, **kwargs):
if not plugin_enabled('notice'): # 守卫一:插件启用
abort(404)
return view(*args, **kwargs)
return wrapper
@admin_bp.route('/notice')
@_gate
@permission_required('notice:manage') # 守卫二:权限点
def notice_index():
page = request.args.get('page', 1, type=int)
pager = (Notice.query.filter_by(is_deleted=False)
.order_by(Notice.sort_order.desc(), Notice.id.desc())
.paginate(page=page, per_page=20, error_out=False))
return render_template('admin/notice/index.html', pager=pager)
@admin_bp.route('/notice/add', methods=['POST'])
@_gate
@permission_required('notice:manage')
def notice_add():
title = (request.form.get('title') or '').strip()
if not title:
flash('标题不能为空', 'danger')
return redirect(url_for('admin.notice_index'))
row = Notice(title=title, content=request.form.get('content') or '',
sort_order=request.form.get('sort_order', 0, type=int))
db.session.add(row); db.session.commit()
audit_log('notice', 'create', f'新增公告 #{row.id}', {'id': row.id, 'title': title})
flash('公告已发布', 'success')
return redirect(url_for('admin.notice_index'))
@admin_bp.route('/notice/<int:nid>/delete', methods=['POST'])
@_gate
@permission_required('notice:manage')
def notice_delete(nid):
row = db.session.get(Notice, nid) or abort(404)
row.is_deleted = True # 软删除,与核心内容一致
db.session.commit()
audit_log('notice', 'delete', f'删除公告 #{nid}', {'id': nid})
flash('公告已删除', 'success')
return redirect(url_for('admin.notice_index'))</code></pre>
<p><b>frontend.py</b>(模板函数)</p>
<pre><code>from .models import Notice
def notice_list(limit=10):
"""模板函数:主题里 {{ notices(5) }} 直接取最新公告。"""
return [{'id': n.id, 'title': n.title, 'url': f'/notice-{n.id}.html'}
for n in Notice.visible().limit(limit)]</code></pre>
<p><b>frontend_routes.py</b>(前台蓝图:启用守卫 + 主题覆盖解析)</p>
<pre><code>from functools import wraps
from flask import Blueprint, abort, render_template, request
from app.plugin_system import plugin_enabled
from .models import Notice
import os
notice_frontend = Blueprint('notice_frontend', __name__,
template_folder='templates',
static_folder='static',
static_url_path='/plugins-static/notice')
def _gate(view):
@wraps(view)
def wrapper(*args, **kwargs):
if not plugin_enabled('notice'):
abort(404)
return view(*args, **kwargs)
return wrapper
def _resolve_template(name):
"""主题覆盖 → 插件自带 → default 兜底。"""
theme = get_active_theme()
if os.path.isfile(os.path.join('app/frontend/templates/themes', theme, name)):
return f'themes/{theme}/{name}'
return f'notice/{name}'
@notice_frontend.route('/notices')
@_gate
def notice_page():
page = request.args.get('page', 1, type=int)
pager = Notice.visible().paginate(page=page, per_page=15, error_out=False)
return render_template(_resolve_template('notices.html'), pager=pager)</code></pre>
<p><b>templates/notice/notices.html</b>(前台,继承当前主题)</p>
<pre><code>{% extends theme_base %}
{% block title %}网站公告 - {{ site_settings.site_name }}{% endblock %}
{% block content %}
<div class="container py-4">
<h2>网站公告</h2>
<ul class="list-group">
{% for n in pager.items %}
<li class="list-group-item d-flex justify-content-between">
<span>{{ n.title }}</span>
<small class="text-muted">{{ n.created_at|date }}</small>
</li>
{% else %}
<li class="list-group-item text-muted">暂无公告</li>
{% endfor %}
</ul>
</div>
{% endblock %}</code></pre>
<div class="warn"><b>导入顺序陷阱</b>:模型导入必须在顶部完成;后台路由 endpoint 归入 <code>admin.*</code> 命名空间,重定向用 <code>url_for('admin.notice_index')</code> 以兼容后台前缀切换。</div>
<h3 id="pd-manifest">3. manifest.json 字段参考</h3>
<table>
<tr><th>字段</th><th>必填</th><th>说明</th></tr>
<tr><td><code>slug</code></td><td>✅</td><td>插件标识,<code>^[a-zA-Z0-9_-]{2,32}$</code>,与目录名一致</td></tr>
<tr><td><code>name / version / description / author</code></td><td>✅/建议</td><td>展示信息</td></tr>
<tr><td><code>builtin</code></td><td>建议</td><td><code>true</code> 内置保护:禁止卸载/覆盖上传</td></tr>
<tr><td><code>min_core_version</code></td><td>建议</td><td>最低核心 CMS 版本,低于拒绝启用(v2.6.4)</td></tr>
<tr><td><code>requires</code></td><td>可选</td><td>依赖插件 slug 列表,启用前须已启用(v2.6.4)</td></tr>
<tr><td><code>extends</code></td><td>可选</td><td>父插件 slug(二次开发),须已安装且启用(v2.6.4)</td></tr>
</table>
<div class="note">启用校验顺序:<b>最低核心版本 → requires → extends</b>;禁用被依赖插件会被反向拦截。详见 <code>PLUGIN_DEPENDENCIES.md</code>。</div>
<h3 id="pd-baseapi">4. PluginBase API 参考</h3>
<table>
<tr><th>钩子</th><th>说明</th></tr>
<tr><td><code>get_admin_routes(admin_bp)</code></td><td>核心后台蓝本注册路由(endpoint 归入 admin.*,兼容前缀切换)</td></tr>
<tr><td><code>get_frontend_blueprint()</code></td><td>前台蓝本,建议命名 <code><slug>_frontend</code></td></tr>
<tr><td><code>get_api_routes(api_bp)</code></td><td>向 /api/v1 注册只读端点,自动享受鉴权/CORS/缓存</td></tr>
<tr><td><code>get_jinja_globals()</code> / <code>get_jinja_fallbacks()</code></td><td>模板全局函数(核心自动包裹启用守卫)/ 禁用时的空值声明</td></tr>
<tr><td><code>get_admin_menu()</code></td><td>后台菜单 <code>{'label','endpoint','icon','permission','active_prefix'}</code></td></tr>
<tr><td><code>get_frontend_menu()</code></td><td>前台导航 <code>{'label','url','target'}</code>,仅启用时聚合</td></tr>
<tr><td><code>get_frontend_guard()</code></td><td>v2.6.4 前台登录守卫(会员体系):<code>{'is_authenticated': fn, 'login_url': fn}</code></td></tr>
<tr><td><code>get_builder_widgets()</code></td><td>v3.0.0 返回 <code>Widget</code> 子类列表,向页面构建器注册组件(owner=插件 slug,禁用门控、卸载引用拦截)</td></tr>
<tr><td><code>get_builder_layouts()</code></td><td>v3.0.0 返回 <code>{scope: [片段, ...]}</code> 贡献默认布局片段;默认自动扫描插件包内 <code>builder/<scope>.json</code>,启用前强校验、仅快照合并</td></tr>
<tr><td><code>get_sitemap_urls()</code></td><td>yield <code>{'loc','lastmod','changefreq','priority'}</code></td></tr>
<tr><td><code>get_search_provider()</code></td><td>v2.5.2 全站搜索提供者(SearchProvider 子类实例)</td></tr>
<tr><td><code>get_migration_files()</code></td><td>自动发现 migrations/versions/*.py,一般无需覆写</td></tr>
<tr><td><code>get_storage_drivers()</code></td><td>存储驱动注册(oss_storage 使用,禁用即回退本地)</td></tr>
<tr><td><code>generate_demo_data(industry)</code></td><td>演示数据钩子,仅启用时调用</td></tr>
<tr><td><code>get_i18n_dir()</code> / <code>_(msg)</code> / <code>ngettext(s,p,n)</code></td><td>插件独立翻译域与便捷翻译函数</td></tr>
<tr><td><code>on_disabled()</code></td><td>禁用回调:清理外部资源(如搜索索引残留)</td></tr>
</table>
<table>
<tr><th>常用核心工具</th><th>位置</th></tr>
<tr><td><code>plugin_enabled(slug)</code></td><td><code>app.plugin_system</code>(视图守卫)</td></tr>
<tr><td><code>permission_required(code)</code></td><td><code>app.decorators</code></td></tr>
<tr><td><code>audit_log(module, action, detail, data)</code></td><td><code>app.models.audit</code></td></tr>
<tr><td><code>reindex_object() / unindex_object()</code></td><td>搜索索引同步</td></tr>
<tr><td><code>save_upload_file(file, exts)</code></td><td><code>app.utils.helpers</code>(原始文件名取后缀,兼容中文名)</td></tr>
<tr><td><code>api_ok() / api_err() / api_cache()</code></td><td>REST 端点统一响应与缓存</td></tr>
<tr><td><code>t_field(obj, field)</code></td><td><code>app.utils.i18n_content</code>(内容级多语言)</td></tr>
</table>
<h3 id="pd-models">5. 数据模型与开发要点</h3>
<ul>
<li><b>自动建表</b>:启用时 <code>db.create_all()</code> 幂等补齐;模型必须在插件 <code>__init__.py</code> 顶部导入。</li>
<li><b>schema 变更</b>:新字段需在 <code>plugins/<slug>/migrations/versions/</code> 放 Alembic 脚本,核心启动自动合并。</li>
<li><b>多语言</b>:主表存默认语言 + <code><table>_translations</code> 翻译表(locale + CASCADE 外键);前台 <code>t(obj,'field')</code>、Python <code>t_field</code>,空回退主表。</li>
<li><b>后台</b>:三层守卫(启用 → 权限 → 业务校验);模板继承 <code>admin/base.html</code>,脚本块用 <code>{% block js %}</code>。</li>
<li><b>前台</b>:视图套启用门控;模板函数返回 dict/list 并声明 fallback;含验证码/flash 的交互页不接页面缓存。</li>
<li><b>伪静态</b>:详情页同时提供动态路由与 <code>/<前缀>-<id>.html</code>;关闭伪静态时伪静态路由 404;不得与核心 <code>article-</code> 前缀冲突。</li>
</ul>
<h3 id="pd-search">6. 全站搜索提供者(v2.5.2)</h3>
<pre><code>from app.utils.search import SearchProvider
class NoticeSearchProvider(SearchProvider):
type = 'notice' # 全局唯一,索引 uid 前缀
def iter_docs(self, locale): # 重建索引:逐条产出可见文档
for n in Notice.visible():
yield self._doc(n, locale)
def get_doc(self, obj_id, locale): # 实时索引;返回 None 表示移出索引
n = db.session.get(Notice, obj_id)
return self._doc(n, locale) if n and not n.is_deleted else None
def sql_search(self, keyword, locale, page=1, per_page=20):
... # 索引故障时的 LIKE 兜底,返回 (items, total)
def build_url(self, item):
return f'/notice-{item["id"]}.html'</code></pre>
<div class="note">文档 dict 字段:<code>id, title, summary, content(可含 HTML,核心自动去标签), column_id, column_name, column_slug, published_at</code>。<b>iter_docs/get_doc 必须自己过滤下架/删除内容</b>。</div>
<h3 id="pd-life">7. 打包、上传与生命周期</h3>
<table>
<tr><th>事项</th><th>规则</th></tr>
<tr><td>压缩包格式</td><td>仅 <code>.zip / .tar.gz / .tgz</code>;必须含 manifest.json 与 __init__.py</td></tr>
<tr><td>slug 校验</td><td>合法 JSON 对象且 slug 匹配正则</td></tr>
<tr><td>路径安全</td><td>含 ../ 越界、绝对路径、symlink/hardlink/fifo 的包被拒绝或跳过</td></tr>
<tr><td>上传过程</td><td>全程临时目录,失败不写入 plugins/;同名插件先备份删除再覆盖</td></tr>
<tr><td>危险操作</td><td>卸载/删除需独立验证码确认;启用中或内置插件拒绝删除</td></tr>
</table>
<h3 id="pd-test">8. 自测清单</h3>
<ul class="check">
<li>启动无异常,插件管理页显示「已加载」;启用后权限点/角色授权/数据表/菜单就绪</li>
<li>后台 CRUD 正常且审计有记录;无权限用户 403</li>
<li>前台动态 200;伪静态开关两种模式均正常</li>
<li>禁用后:后台 404、前台 404、导航/sitemap/API 消失、模板函数返回 fallback</li>
<li>搜索:保存可搜到、删除后消失、禁用插件无索引残留</li>
<li>多语言:翻译留空回退默认语言</li>
<li>卸载目录删除、重新上传可恢复;路径穿越包被拒绝</li>
</ul>
<h3 id="pd-common">9. 常见陷阱</h3>
<ul>
<li>忘写 <code>plugin = MyPlugin()</code> → 核心识别不到插件。</li>
<li>模型导入晚于 <code>db.create_all()</code> → 表缺失,SQL 报 1146/no such table。</li>
<li>后台路由自建蓝本 → 后台前缀切换后路由失效。</li>
<li>模板里 <code>{{ j.url }}</code> 而模型无该属性 → Jinja 静默输出空 href(应用注册的 URL 函数)。</li>
<li><code>get_jinja_fallbacks()</code> 漏声明 → 禁用插件后主题渲染报错。</li>
<li>交互页接了页面缓存 → 验证码/flash 错乱、用户间串数据。</li>
<li>伪静态前缀与核心 <code>article-</code> 冲突 → 路由劫持。</li>
<li>SearchProvider 未过滤下架内容 → 已下架内容仍可被搜到。</li>
<li>后台模板用 <code>scripts</code> block → 脚本不执行(正确为 <code>{% block js %}</code>)。</li>
<li>字典取值 <code>g.items</code> 命中 dict 方法 → 应为 <code>g['items']</code>。</li>
</ul>
</section>
<section id="upgrade">
<h2>v1.1 → v2.0 升级迁移</h2>
<p>运行 v1.1 及更早版本升级到 v2.0+ 前,请务必阅读项目根目录 <b>UPGRADE.md</b>。本章为速览。</p>
<h3>升级前必读:四个关键变化</h3>
<table>
<tr><th>变化</th><th>说明</th><th>需做的事</th></tr>
<tr><td>用户权限语义</td><td>v1.1 所有用户默认超管;v2.0 引入 RBAC</td><td>升级后审查超管标志并分配角色</td></tr>
<tr><td>文章状态机</td><td><code>is_enabled</code> 升级为工作流状态</td><td>迁移自动回填,确认隐藏文章仍不可见</td></tr>
<tr><td>登录安全</td><td>失败 5 次锁定 10 分钟、验证码、异地提醒</td><td>告知后台用户;弱密码建议改密</td></tr>
<tr><td>上传行为</td><td>MIME 双重校验/去重/压缩默认开启</td><td>伪装脚本将无法上传</td></tr>
</table>
<h3>升级步骤</h3>
<pre><code># 0. 备份站点目录与数据库(必做!)
# 1. 停服并更新代码
git fetch && git checkout v2.4.0
# 2. 更新依赖
pip install -r requirements.txt
# 3. 执行迁移(幂等,可重复运行)
.venv/bin/python scripts/upgrade_v2.py
# 4. 启动服务,按 UPGRADE.md 逐项核对</code></pre>
<h3>为什么必须运行迁移脚本</h3>
<div class="warn">v2.0 新增 <b>9 张表</b>、旧表补 <b>12 列</b>。仅启动程序无法完成迁移:<code>db.create_all()</code> 只建新表、不给旧表加列;跳过数据回填会让<b>原本隐藏的文章被错误公开</b>。</div>
<h3>小版本升级</h3>
<ul>
<li><b>v2.2.x → v2.3.0</b>:无数据库变更,覆盖代码即可;首次启动自动启用表单插件一次。</li>
<li><b>v2.3.x → v2.4.0</b>:覆盖代码 + 装依赖;首次启动自动 stamp Alembic baseline 并执行增量迁移。</li>
</ul>
</section>
<section id="alembic">
<h2>数据库迁移 (Alembic) <span class="tag tag-new">v2.4</span></h2>
<p>v2.4.0 引入 <b>Flask-Migrate(封装 Alembic)</b> 统一管理 schema 版本,支持升级/回滚与插件迁移脚本接入。</p>
<h3>旧站自动迁移</h3>
<ol>
<li>检测旧库(存在核心表但无 <code>alembic_version</code>)</li>
<li>自动 stamp baseline(标记为 <code>0001</code>,对应 v2.3.0 schema)</li>
<li>执行增量迁移(<code>0002</code> 建搜索索引表 → <code>0003</code> 插入搜索设置 → <code>0004</code> 加 storage 列)</li>
</ol>
<div class="note">v2.3.x → v2.4.0 <b>无需手动操作</b>,覆盖代码后首次启动自动完成。</div>
<h3>CLI 命令</h3>
<pre><code>flask db upgrade # 升级到最新
flask db downgrade -1 # 回滚一版
flask db current # 查看当前版本
flask db history # 查看迁移历史
flask db migrate -m "xxx" # 新建迁移脚本(开发用)</code></pre>
<div class="warn">生产环境慎用 downgrade;SQLite batch 模式下回滚会重建整表,大表可能耗时较长。</div>
<h3>插件迁移钩子</h3>
<p>插件通过 <code>PluginBase.get_migration_files()</code> 返回 <code>migrations/versions/</code> 下脚本路径,核心自动合并到 Alembic <code>version_locations</code>:</p>
<pre><code>def get_migration_files(self):
mig_dir = Path(self.get_plugin_dir()) / 'migrations' / 'versions'
return sorted(str(p) for p in mig_dir.glob('*.py') if not p.name.startswith('__'))</code></pre>
<div class="note">无迁移文件的插件仍由 <code>db.create_all()</code> 兜底建表;迁移钩子仅用于表结构变更场景。</div>
<h3>数据库类型一键迁移 <span class="tag tag-new">v3.1.0</span></h3>
<p>官方内置插件 <code>db_migrator</code>(<b>默认不启用</b>),解决「本地用 SQLite 开发、上线换 MySQL/PostgreSQL」的迁移需求。后台 <b>插件管理</b> 启用后,<b>系统设置 → 数据库迁移</b>:</p>
<ol>
<li>填写目标库类型(MySQL / PostgreSQL)、主机、端口、库名、账号密码,先在数据库服务器上建好空库;点「测试连接」确认可达。</li>
<li>点「开始迁移」:目标库建表 → 按 <code>metadata.sorted_tables</code> 拓扑序逐表复制行数据(每批 500 行、单事务失败整体回滚)→ PostgreSQL 自动重置自增序列(<code>setval</code>)→ 同步源库 <code>alembic_version</code> 版本号(重启时不重复执行增量迁移)。</li>
<li>生效方式二选一:勾选「迁移后立即切换」复用安装向导同款 <code>switch_engine</code> 热切换引擎,免重启即时生效(失败自动回滚配置继续用旧库);不勾选则写入 <code>instance/db_config.json</code>,重启后生效,删除该文件即可放弃切换。</li>
</ol>
<div class="warn">高危操作:迁移会读取当前库全部业务表并写入目标库,请在维护时段执行并提前备份;目标库与本系统同名的表已有数据时拒绝迁移,确认清空重迁需勾选「覆盖目标库已有数据」(<code>drop_all</code> 仅删除本系统已知表)。搜索引擎索引与上传文件不受迁移影响,无需重新处理。权限点 <code>db_migrator:manage</code> 不向预设角色默认授权,仅超管或显式授权角色可用。</div>
</section>
<section id="search">
<h2>全文搜索 <span class="tag tag-new">v2.4</span></h2>
<p>前台 <code>/search</code> 优先走索引,故障时自动回退 SQL LIKE。</p>
<h3>三种后端</h3>
<table>
<tr><th>后端</th><th>依赖</th><th>适用</th><th>默认</th></tr>
<tr><td><b>Tantivy + pkuseg</b></td><td>Rust 内核(tantivy-py)+ spacy-pkuseg 分词</td><td>中小站点,零外部服务</td><td>✅</td></tr>
<tr><td><b>Meilisearch</b></td><td>独立进程</td><td>文章 > 5 万的大型站点</td><td>可选</td></tr>
<tr><td><b>SQL LIKE</b></td><td>无</td><td>索引未建或故障兜底</td><td>自动</td></tr>
</table>
<h3>索引与更新</h3>
<ul>
<li><b>索引范围</b>:文章(标题 + 正文去 HTML + 摘要 + 栏目名)+ 插件内容(产品、招聘岗位,v2.5.2)</li>
<li><b>自动更新</b>:文章与插件内容保存/删除时通过钩子触发,<b>独立于缓存开关</b></li>
<li><b>重建索引</b>:后台「搜索设置」一键重建,未索引前自动回退 SQL LIKE</li>
<li><b>索引位置</b>:<code>instance/search_index/<locale>/</code>(按语言分目录)</li>
</ul>
<div class="note">6 套主题搜索模板均支持分页与关键词高亮(<code>|highlight(keyword)|safe</code>)。</div>
<h3>多语言检索 <span class="tag tag-new">v2.5.1</span></h3>
<p>开启内容级多语言后,搜索<b>按当前语言检索对应语言的内容</b>,三个后端均已适配:</p>
<ul>
<li><b>Tantivy</b>:按语言分索引目录 <code>instance/search_index/<locale>/</code>;<b>Meilisearch</b>:按语言分索引 <code>zhycms_articles_<locale></code></li>
<li>每篇内容对每种语言写入一份索引,内容经 <code>t_field</code> 解析——有翻译用翻译、无翻译回退默认语言(未翻译内容不会因切语言而搜不到)</li>
<li>搜索结果的标题、摘要、栏目名均随当前语言显示;前台 <code>/search</code> 按 <code>?lang=xx</code> / session 自动选索引</li>
<li>该语言索引尚未建立时自动回退默认语言索引;i18n 关闭时仅维护默认语言单一索引,行为不变</li>
<li><b>插件内容同样本地化检索(v2.5.2)</b>:产品的规格参数、岗位的部门/工作地点/薪资待遇均按语言索引与兜底匹配(如英文搜 <code>Model</code>、<code>Shanghai</code> 可命中)</li>
</ul>
<div class="tip">升级到 v2.5.1 后,到后台「全局设置 → 搜索设置」点击一次<b>「重建索引」</b>即可生成各语言索引;内容保存/删除会自动同步全部语言索引,无需手动维护。</div>
<h3>插件内容接入搜索(SearchProvider) <span class="tag tag-new">v2.5.2</span></h3>
<p>插件通过 <code>get_search_provider()</code> 钩子返回一个 <code>SearchProvider</code> 实例,自有内容即可进入全站搜索(官方「产品展示」「招聘管理」已接入)。协议四方法:</p>
<table>
<tr><th>方法</th><th>职责</th></tr>
<tr><td><code>type</code></td><td>内容类型标识(全局唯一,如 <code>product</code> / <code>recruit_job</code>),与 id 组成索引唯一键 <code>uid = "类型:id"</code></td></tr>
<tr><td><code>iter_docs(locale)</code></td><td>重建索引时产出该语言下全部可见文档</td></tr>
<tr><td><code>get_doc(id, locale)</code></td><td>单条文档(保存时实时索引);返回 <code>None</code> 表示下架/删除,核心自动移出索引</td></tr>
<tr><td><code>sql_search(kw, locale, page, per_page)</code></td><td>SQL LIKE 兜底检索(索引故障/未建时),需自行匹配翻译表</td></tr>
<tr><td><code>build_url(item)</code></td><td>搜索结果 → 详情页 URL(伪静态两种模式),核心统一分发</td></tr>
</table>
<div class="note">完整示例见「插件开发指南 → 全站搜索贡献」。文档以 <code>uid</code> 区分类型,文章与产品/岗位互不覆盖;插件禁用时核心回调 <code>on_disabled()</code> 清理索引残留。产品/岗位保存、删除、批量上下架均实时同步索引。</div>
</section>
<section id="docker">
<h2>Docker 容器化部署 <span class="tag tag-new">v2.4</span></h2>
<h3>一键安装(推荐)</h3>
<p>项目提供交互式安装脚本,只需一条命令,按提示选择数据库、自动生成密钥,无需手动编辑任何文件:</p>
<pre><code>bash docker/install.sh</code></pre>
<p>脚本会引导你完成 5 步:选择数据库(MySQL/PostgreSQL)→ 自动生成安全密钥与密码 → 国内镜像加速(可选)→ Meilisearch 搜索引擎(可选)→ 端口与 Worker 数量。配置确认后自动生成 <code>.env</code>、拉取基础镜像、构建并启动服务。</p>
<div class="note">脚本自动生成的 <code>.env</code> 包含随机密钥和密码,安全可靠。卸载时运行 <code>bash docker/uninstall.sh</code>,可选择保留或删除数据。</div>
<h3>手动配置(进阶)</h3>
<p>如需完全手动控制,可直接编辑配置文件。官方镜像已发布到 Docker Hub、GitHub GHCR 和阿里云 ACR,拉取即用:</p>
<pre><code>cp docker/.env.example .env
# 编辑 .env 修改 SECRET_KEY 和数据库密码
# MySQL 8.4(镜像 pollybird/zhycms:mysql)
docker compose -f docker-compose.mysql.yml up -d
# PostgreSQL 16(镜像 pollybird/zhycms:postgresql)
docker compose -f docker-compose.postgresql.yml up -d</code></pre>
<p>也可直接拉取(Docker Hub / GitHub GHCR / 阿里云 ACR 任选其一,国内推荐阿里云):</p>
<ul>
<li><code>docker pull pollybird/zhycms:mysql</code>(或 <code>:postgresql</code> / <code>:latest</code> / <code>:v3.2.6</code>)</li>
<li><code>docker pull ghcr.io/pollybird/zhycms:mysql</code>(或 <code>:postgresql</code> / <code>:latest</code> / <code>:v3.2.6</code>)</li>
<li><code>docker pull crpi-9u7ztjb0thx22k1a.cn-hangzhou.personal.cr.aliyuncs.com/pollybird/zhycms:mysql</code>(或 <code>:postgresql</code> / <code>:latest</code> / <code>:v3.2.6</code>)</li>
</ul>
<h3>镜像特点</h3>
<ul>
<li><b>已发布到多镜像源</b>:Docker Hub(<code>pollybird/zhycms</code>)、GitHub GHCR(<code>ghcr.io/pollybird/zhycms</code>)、阿里云 ACR(<code>crpi-9u7ztjb0thx22k1a.cn-hangzhou.personal.cr.aliyuncs.com/pollybird/zhycms</code>),均提供 <code>mysql</code> / <code>postgresql</code> / <code>latest</code> / <code>v3.2.6</code> 四个 tag(同一镜像,内置 MySQL + PostgreSQL 驱动,通过 <code>ZHYCMS_DB_URI</code> 切换)。</li>
<li><b>多阶段构建</b>:builder 阶段编译依赖,runtime 阶段基于 <code>python:3.12-slim</code>,体积约 495MB。</li>
<li><b>非 root 运行</b>:uid 1000 的 <code>zhycms</code> 用户,增强安全性。</li>
<li><b>自动初始化</b>:entrypoint.sh 执行迁移 → 恢复演示图 → 编译 i18n → 启动 gunicorn。</li>
<li><b>健康检查</b>:<code>GET /healthz</code> 返回数据库状态,豁免初始化拦截,供探针使用。</li>
</ul>
<h3>环境变量</h3>
<table>
<tr><th>变量</th><th>说明</th><th>必填</th></tr>
<tr><td><code>ZHYCMS_SECRET_KEY</code></td><td>Flask 会话密钥</td><td>✅</td></tr>
<tr><td><code>ZHYCMS_DB_URI</code></td><td>数据库 URI(compose 按 profile 自动注入)</td><td>✅</td></tr>
<tr><td><code>APT_MIRROR</code></td><td>构建期 apt 镜像源(如 <code>mirrors.tuna.tsinghua.edu.cn</code>)</td><td>❌</td></tr>
<tr><td><code>PIP_INDEX_URL</code></td><td>构建期 pip 镜像源</td><td>❌</td></tr>
</table>
<div class="note">裸机部署无需迁移到 Docker,v2.4.0 代码在裸机环境同样正常运行。</div>
</section>
<section id="oss">
<h2>对象存储 OSS <span class="tag tag-new">v2.4</span></h2>
<p>官方内置插件 <code>oss_storage</code>,支持阿里云 OSS / 腾讯云 COS / 七牛云 Kodo。<b>默认本地存储、零行为变化</b>:升级后自动启用但不配置凭证不产生任何云端调用。</p>
<h3>架构</h3>
<ul>
<li><b>核心抽象层</b> <code>app/utils/storage.py</code>:定义 <code>StorageDriver</code> 协议与本地驱动;上传入口 <code>save_upload_file()</code> 先在本地完成校验/压缩,再发布到当前驱动。</li>
<li><b>云驱动在插件中</b>:SDK 可选依赖、运行时懒加载,未安装时配置页给出 <code>pip install</code> 指引。</li>
<li><b>文件归属</b>:<code>uploaded_files.storage</code> 列标记文件存于哪个驱动;切换驱动后历史 URL 不受影响。</li>
<li><b>禁用回退</b>:禁用插件时自动把存储驱动重置为本地。</li>
</ul>
<h3>配置步骤</h3>
<ol>
<li>安装对应 SDK:<code>pip install oss2</code> / <code>cos-python-sdk-v5</code> / <code>qiniu</code></li>
<li>云厂商控制台创建 Bucket,<b>使用 RAM 子账号</b>(仅授予目标 Bucket 读写权限)</li>
<li>后台 <b>系统设置 → 对象存储</b> 填写凭证并连接测试</li>
</ol>
<h3>一键迁移</h3>
<p>配置页提供 dry-run 预览(待传文件数、内容引用链接数)与一键执行:</p>
<ul>
<li>逐文件上传,云端已存在自动跳过(可中断、可重入)</li>
<li>上传成功后批量改写内容中的本地链接为云域名</li>
<li>本地原文件保留不删;<code>uploads/demo/</code> 不迁移</li>
</ul>
<h3>安全设计</h3>
<ul>
<li>云端上传失败显式报错,不静默回退本地</li>
<li>备份恢复文件强制存本地(<code>storage_scope='local'</code>)</li>
<li>凭证存数据库 settings 表,不写入仓库文件</li>
<li>七牛云必须绑定自有 CDN 域名(默认下载域名 30 天过期)</li>
</ul>
</section>
<section id="redis">
<h2>Redis 缓存与 Session <span class="tag tag-new">v2.5</span></h2>
<p>v2.5.0 引入 Redis 作为可选的缓存后端与服务端 Session 存储,适合<b>多实例负载均衡</b>场景。未启用 Redis 时回退 SimpleCache + Cookie Session,单机部署零依赖。</p>
<h3>自动检测机制</h3>
<p>应用启动时检测环境变量 <code>REDIS_URL</code>:</p>
<ul>
<li><b>有值且 Redis 可达</b> → 启用 RedisCache(Flask-Caching)+ 服务端 Session(Flask-Session 存 Redis)</li>
<li><b>有值但不可达</b> → 回退 SimpleCache + Cookie Session,日志输出警告</li>
<li><b>未设置</b> → SimpleCache + Cookie Session(与 v2.4.x 行为一致)</li>
</ul>
<h3>启用方式</h3>
<pre><code># 源码部署:设置环境变量后启动
export REDIS_URL=redis://127.0.0.1:6379/0
python run.py
# 带密码的 Redis
export REDIS_URL=redis://:yourpassword@127.0.0.1:6379/0
# Docker 部署:install.sh 交互选择启用 Redis
bash docker/install.sh
# 自动在 .env 中写入 REDIS_URL,启动时携带 --profile redis
# 独立 compose 文件:取消注释文件中的 redis 服务块与 redis_data 卷
# docker-compose.mysql.yml 或 docker-compose.postgresql.yml 内已预置(默认注释)
# 也可用通用编排文件:
docker compose --profile mysql --profile redis up -d</code></pre>
<h3>后台状态页</h3>
<p>后台「全局设置 → Redis 缓存」提供<b>只读</b>状态展示(v3.2.6 起仅超级管理员可见):</p>
<ul>
<li><b>已启用</b>(绿色):显示连接地址,说明 RedisCache + 服务端 Session 已生效</li>
<li><b>未启用</b>(黄色):提示安装 Redis 并设置环境变量的步骤</li>
<li><b>连接失败</b>(红色):显示错误信息,引导排查 Redis 服务状态与连接参数</li>
</ul>
<div class="note">Redis 后端在应用启动时初始化,运行时不可切换。修改 <code>REDIS_URL</code> 后需重启应用生效。后台不提供手动开关,避免运行时切换导致缓存与 Session 状态不一致。</div>
<h3>安全建议</h3>
<ul>
<li>Redis 配置密码(<code>requirepass</code> 或 ACL),<code>REDIS_URL</code> 中携带密码</li>
<li>Redis 仅监听内网地址(<code>bind 127.0.0.1</code> 或内网 IP)</li>
<li>生产环境通过防火墙限制 6379 端口访问</li>
<li><code>REDIS_URL</code> 含密码属敏感信息,<code>.env</code> 已在 <code>.gitignore</code> 中排除</li>
</ul>
</section>
<section id="faq">
<h2>运维故障排查 FAQ <span class="tag tag-new">v2.6.4</span></h2>
<p>常见报错、迁移失败处理方案速查。权威文档见仓库 <code>docs/OPERATIONS_FAQ.md</code>。通用排查:<b>看日志</b>(journalctl / <code>docker compose logs -f app</code>)→ <b>健康检查</b>(<code>curl http://127.0.0.1:5000/healthz</code>)→ <b>核对后台设置开关</b>(很多「突然失效」是 settings 表开关被改动)。</p>
<h3 id="faq-db">数据库与 Alembic 迁移</h3>
<table>
<tr><th>迁移版本</th><th>Revision</th><th>内容</th></tr>
<tr><td>baseline</td><td>0001</td><td>v2.3.0 基线</td></tr>
<tr><td>v2.4.0</td><td>0002 / 0003 / 0004</td><td>search_index 表 / 搜索设置种子 / 对象存储设置</td></tr>
<tr><td>v2.5.x</td><td>0005 / 0006 / 0007</td><td>内容级 i18n / 插件 i18n / 插件 i18n 结构化字段</td></tr>
<tr><td>v2.6.4</td><td>0008</td><td>栏目 member_only</td></tr>
<tr><td>v3.0.0</td><td>0009</td><td>页面构建器 builder_pages / builder_revisions</td></tr>
</table>
<p>启动时 <code>_alembic_bootstrap()</code> 自动判断:全新安装 stamp 0001;v2.3.0 及更早旧库 stamp 0001 后 upgrade 增量;bootstrap 异常仅记 <code>WARNING(非致命)</code> 不阻断启动,<b>但需尽快手工修复</b>:</p>
<pre><code>python - <<'PY'
from app import create_app
from flask_migrate import upgrade
app = create_app()
with app.app_context():
upgrade(directory='migrations')
PY</code></pre>
<table>
<tr><th>报错</th><th>原因</th><th>处理</th></tr>
<tr><td><code>Can't locate revision 'xxxx'</code></td><td>alembic_version 指向不存在/已删的历史版本</td><td>确认库结构后 <code>stamp</code> 到正确版本(如 0008);字段缺失先补对应迁移</td></tr>
<tr><td><code>Table 'xxx' already exists</code></td><td>手工建过表或 create_all 与迁移并发</td><td>表已在则跳过对应迁移;或迁移脚本加存在性判断</td></tr>
<tr><td><code>Duplicate column name</code></td><td>字段已手工加过</td><td>跳过或改判断式迁移</td></tr>
<tr><td>迁移卡死/超时</td><td>大表加索引锁等待</td><td>低峰执行;MySQL 查 <code>SHOW PROCESSLIST</code></td></tr>
<tr><td>插件迁移 rev 链断裂</td><td>插件被卸载致迁移文件消失</td><td>重装该插件目录,或备份后从 alembic_version 删除对应 revision</td></tr>
<tr><td><code>Access denied for user</code></td><td>账号密码错误;Docker 数据卷以旧密码初始化</td><td>见 Docker 专项(改 .env 密码不影响已初始化卷)</td></tr>
</table>
<ul>
<li><b>降级</b>:不承诺自动降级(迁移含数据变更),标准做法是恢复升级前备份,而非 downgrade。</li>
<li><b>SQLite 换 MySQL/PG</b>:无自动搬迁。新库安装最新版 → 导出导入数据 → 复制 <code>app/static/uploads/</code> 与 <code>instance/</code>。</li>
<li><b>MySQL 建库</b>:统一 <code>utf8mb4</code> 字符集。</li>
</ul>
<h3 id="faq-cache">缓存与 Redis</h3>
<ul>
<li>日志 <code>[Redis] 连接失败,回退 SimpleCache</code>:自动降级仍可用;多 worker 部署建议修复 REDIS_URL(格式 <code>redis://:密码@host:6379/0</code>)。</li>
<li>改内容/设置前台不生效:后台保存会自动清缓存,直改数据库不会;手工清空可重启应用或 <code>redis-cli FLUSHDB</code>。</li>
<li>主题切换后样式仍旧:确认 ≥ v2.6.3(缓存键含主题 + 切换清缓存已修复)。</li>
<li>多 worker 登录态丢失:Session 依赖 Redis;回退 Cookie Session 时需固定 <code>SECRET_KEY</code>。</li>
</ul>
<h3 id="faq-theme">主题与插件</h3>
<ul>
<li><code>TemplateNotFound</code>:查双后缀拼接错误 → 文件是否在正确目录 → 自定义主题缺必备模板被拒启用 → default 主题文件是否完整。</li>
<li>主题上传被拒:按 8 步校验排查(格式/完整性/路径穿越/symlink/manifest/必备模板/形态归一化/覆盖保护),报错指明失败步骤。</li>
<li>插件启用失败:v2.6.4 按 min_core_version → requires → extends 强校验,按提示升级核心或先启用依赖;禁用被依赖插件会被反向拦截并列出依赖方。v3.0.0 起还会校验插件自带的构建器布局片段(builder/*.json),片段非法会拒绝启用并提示具体错误。</li>
<li>插件「加载失败」:启动日志该插件的 traceback 即原因(模型字段不匹配/依赖缺失/忘写 <code>plugin = XxxPlugin()</code>)。</li>
<li>页面构建器相关:页面发布后前台未生效 → 确认点的是「发布」而非仅存草稿(匿名访客只见已发布版);删除构建记录即回退手写模板;新建页默认布局与当前主题不一致 → 默认布局按启用主题 fixture 解析,切主题只影响之后新建的页面;启停插件不回填已有草稿(v3.0.0)。</li>
<li>删除需验证码:危险操作独立一次性验证码(/captcha/delete-confirm);内置或启用中的对象拒绝删除。</li>
</ul>
<h3 id="faq-rewrite">伪静态与路由</h3>
<ul>
<li>伪静态第 2 页 404:Nginx 需把 <code>*.html</code> 转发到应用(<code>try_files $uri $uri/ @app;</code>);动态形式 <code>/column/<slug>?page=2</code> 始终兼容 200,可用来区分是 Web 服务器转发问题还是应用问题。</li>
<li><code>/article-5.html</code> 被劫持:article- 前缀规则优先级最高;排查插件是否注册了同名冲突路由。</li>
<li>改后台前缀后打不开:修改即时生效;使用了保留字(如 form)会与前台冲突,改回即可(settings 表 admin_prefix)。</li>
<li>robots.txt / sitemap.xml / favicon.ico 404:三者在初始化拦截/维护模式中豁免,正常始终可访问;404 多为应用没启动成功。</li>
</ul>
<h3 id="faq-upload">上传与搜索</h3>
<ul>
<li>中文文件名后缀丢失:上传类型判断从原始文件名取后缀(已修复);自查是否绕过核心 <code>save_upload_file()</code>。</li>
<li>上传 413:调大 Nginx <code>client_max_body_size</code> 与后台上传限制。</li>
<li>图片不显示:查 <code>app/static/uploads/</code> 写权限(Docker uid 1000);缩略缓存 <code>instance/image_cache/</code> 损坏可清空重建。</li>
<li>搜不到新内容:保存时实时索引,异常时自动 SQL 兜底;连兜底都无结果查文章 status/is_deleted/栏目启用。</li>
<li>搜索报错:后台重建索引;必要时删 <code>instance/search_index/</code> 对应语言目录再重建(无数据风险)。</li>
</ul>
<h3 id="faq-docker">Docker 专项</h3>
<ul>
<li>反复重启 <code>database not reachable after 60s</code>:entrypoint 等库 60 秒超时;检查 db 健康状态与 ZHYCMS_DB_URI,首次初始化慢需等待。</li>
<li><code>Access denied(数据卷由旧密码初始化)</code>:改 .env 密码不影响已初始化卷。方案 A:旧密码重装(install.sh 选复用已有数据);方案 B(清数据):<code>docker compose --profile <mysql|mariadb|postgres> down -v</code>。</li>
<li>Permission denied 写 instance/:entrypoint root 自愈 chown 1000:1000 后降权;仍失败查 SELinux/挂载参数。</li>
<li>镜像拉取超时:install.sh 内置多源回退(daocloud → 1ms.run → xuanyuan.me → hub.rat.dev,每站重试 2 次)。</li>
<li>unhealthy:<code>docker exec <容器> curl -s http://localhost:5000/healthz</code> 看返回。</li>
</ul>
<h3 id="faq-backup">备份与快速诊断</h3>
<ul>
<li>内置备份存 <code>instance/backups/</code>(数据库 + uploads);手动兜底:mysqldump / pg_dump / SQLite 文件 + uploads + instance 目录。</li>
<li>恢复后 alembic_version 随库走,恢复旧库后启动新代码自动 upgrade head 补齐。</li>
<li>诊断命令:<code>curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:5000/healthz</code>;<code>docker compose --profile mysql logs -f app</code>;缩略缓存 <code>rm -rf instance/image_cache/*</code> 可安全清空。</li>
</ul>
<div class="note">提交 issue/求助时请附:版本号(后台首页可见)、启动日志最后 50 行、复现步骤。</div>
</section>
<footer>
<p>ZhyCMS 使用手册 · 基于 Apache License 2.0 开源 · 本页为离线 HTML 单文件,可直接在浏览器打开。</p>
</footer>
</main>
</div>
</body>
</html>