ZhyCMS 内容管理系统
安装部署与使用指南

ZhyCMS 是一套面向企业的轻量级开源内容管理系统：前台负责展示，后台负责管理，插件负责扩展。它用 Python 技术栈替代传统 PHP CMS，在保持「轻」的同时覆盖企业建站的核心需求。

1.1核心定位

1.2技术栈

1.3典型使用场景

• 企业官网：公司介绍、新闻动态、产品展示、在线留言表单、招聘信息一站管理；
• 资讯门户 / 行业站：栏目体系 + 文章工作流 + 全文搜索 + SEO 伪静态；
• 多语言站点：内置英文主题与内容级多语言，适合外向型企业与涉外业务；
• Headless / 小程序后端：通过 /api/v1/ 只读 REST API 输出内容。

ZhyCMS 的能力按「前台展示、后台管理、扩展生态」三块组织，底层由统一的数据与基础设施支撑。

2.1能力清单

ZhyCMS 采用经典的分层架构：访问端 → Web 服务 → Flask 应用 → 数据与基础设施。配置 REDIS_URL 后可平滑扩展为多实例部署。

3.1关键设计

• 应用工厂：app/__init__.py 统一装配扩展，插件与主题通过运行时门控加载；
• 存储抽象层：所有上传走 app/utils/storage.py 同一入口，本地 / 云存储可无缝切换；
• 双轨渲染：页面构建器（已发布布局）与手写模板（themes/）双轨并存，老站升级零行为变化；
• 健康检查：/healthz 返回 200 即应用存活，Docker HEALTHCHECK 同此。

从零到可访问的站点，通常只需三条路径：本地开发、Docker 部署、生产部署。首次启动会自动进入初始化向导。

4.1环境要求

4.2本地开发安装

代码在 Gitee / GitCode / GitHub 三平台镜像同步，国内推荐 Gitee：

# 1. 克隆代码
git clone https://gitee.com/pollybird/zhycms
# git clone https://gitcode.com/pollybird/ZhyCMS
# git clone https://github.com/pollybird/zhycms
cd zhycms

# 2. 创建虚拟环境
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

# 3. 安装依赖（国内建议用镜像源）
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 4. 启动开发服务器
python run.py

浏览器访问 http://127.0.0.1:5000，首次访问自动跳转到 /admin/setup 初始化向导。

4.3Docker 部署

官方镜像已发布到 Docker Hub（pollybird/zhycms）、GitHub GHCR（ghcr.io/pollybird/zhycms）和阿里云 ACR，当前版本 v3.1.3，开箱即用：

# 1. 配置环境变量
cp docker/.env.example .env
# 编辑 .env，修改 SECRET_KEY 和数据库密码

# 2. 启动（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

# 3. 访问 http://localhost:5000 完成初始化

如需本地构建或使用 MariaDB 方案，用通用编排文件：

docker compose --profile mysql up -d      # 本地构建 + MySQL
docker compose --profile mariadb up -d    # 本地构建 + MariaDB 11.4
docker compose --profile postgres up -d   # 本地构建 + PostgreSQL

4.4生产部署

# 方式一：直接运行
ZHYCMS_ENV=production ZHYCMS_SECRET_KEY=your-secret python run.py

# 方式二：gunicorn（推荐）
gunicorn -w 4 -b 0.0.0.0:5000 "run:app"

# 方式三：Docker（见 4.3）

4.5部署方式对比

4.6初始化向导

首次访问任意页面时，系统自动跳转到 /admin/setup，按向导完成三步即可开始使用：

1. 创建管理员账号

   设置后台超级管理员用户名与强密码，同时可配置站点名称、站点描述等基础信息。

2. 配置数据库与密钥

   确认数据库连接（开发默认 SQLite）与 SECRET_KEY；Docker 场景对应 .env 中的 ZHYCMS_DB_URI。

3. 完成初始化

   系统自动建表、写入种子数据（含搜索设置、对象存储设置）并 stamp Alembic 基线，进入后台首页。

4.7目录结构

zhycms/
├── app/
│   ├── admin/              # 后台模块（栏目、文章、用户、角色、审计、备份、设置等）
│   ├── frontend/           # 前台模块（含 themes/ 主题目录）
│   ├── models/             # 数据模型（用户、RBAC、审计、工作流、备份、上传等）
│   ├── translations/       # 国际化翻译文件
│   ├── utils/              # 工具模块（上传、通知、备份、存储、主题等）
│   ├── builder/            # 页面构建器（组件注册表 / Schema / 渲染器）
│   ├── plugin_system.py    # 插件运行时
│   └── plugin_api.py       # PluginBase 基类
├── plugins/                # 插件目录（banner / product / recruit / member …）
├── migrations/             # Alembic 数据库迁移脚本
├── docker/                 # Docker 部署辅助文件（.env.example 等）
├── instance/               # 实例数据（数据库、配置、备份、搜索索引、上传等）
├── Dockerfile              # 多阶段构建镜像
├── docker-compose*.yml     # 编排文件（通用 / MySQL / PostgreSQL）
├── wsgi.py                 # 生产 WSGI 入口
├── run.py                  # 开发启动入口
└── requirements*.txt       # 依赖清单（核心 / 生产）

后台默认地址为 /admin（可在系统设置中自定义前缀）。本节按后台菜单顺序，介绍每个功能模块的使用方法。

5.1登录与仪表盘

访问 /admin 输入管理员账号密码登录。登录环节内置多项安全防护：

• 连续失败锁定：多次密码错误将临时锁定账号，防止暴力破解；
• 图形验证码：登录页提供图形验证码；
• 异地 IP 提醒：检测到非常用 IP 登录时给出提示。

登录后进入仪表盘：展示站点内容概览（文章 / 栏目数量、审核待办等），并提供常用入口。后台首页同时显示当前版本号，提交 issue 求助时请带上该版本号。

5.2栏目管理

栏目是内容组织的骨架，支持层级结构（父栏目 → 子栏目）。每个栏目可独立设置：

• 列表页 / 内容页 / 单页模板：栏目级模板选择，可让不同栏目呈现不同版式；
• 伪静态别名（slug）：决定前台访问路径，如 /news.html；
• 会员可见性：设置 member_only 后，未登录访客无法访问该栏目内容（配合前台会员插件）；
• SEO 配置：sitemap 更新频率 / 优先级、栏目描述等。

5.3文章管理与内容工作流

文章编辑页支持富文本（CKEditor5）、封面图、摘要、自定义字段与多语言版本 Tab。保存时自动生成版本快照，可在历史版本中对比差异、一键还原。

文章状态按内容工作流流转，实现「谁写、谁审、谁发」的权限分离：

文章列表支持批量操作：发布、撤回、删除、归档、移动栏目、提交审核，批量操作会逐篇同步更新搜索索引。

5.4碎片管理

内容碎片（Fragment）用于维护站点中的零散内容块——页脚版权、联系方式、公告栏等。碎片支持多语言版本，在模板中通过全局函数按语言取用，一处修改、全站生效。

5.5主题管理

• 一键切换：后台主题列表展示已安装主题，启用即时生效（缓存自动刷新）；
• 上传主题：支持 .zip / .tar.gz / .tgz 压缩包，经 8 步安全校验（格式 → 完整性 → 路径穿越 → symlink → manifest 与 slug → 必备模板 → 形态归一 → 禁覆盖）后解压；
• 打包下载：可将当前主题打包导出，跨站复用；
• 安全兜底：启用主题缺失必备模板时自动回退 default 主题，杜绝白屏；
• 资源隔离：每套主题独立拥有 css / js / images / fonts 子目录。

5.6页面构建器（可视化建页）

v3.0.0 起内置自研轻量拖拽构建器，无需任何前端构建链，在后台「页面构建」中即可搭建页面：

• 四种页面类型：首页、单页、列表页、文章详情页，覆盖企业站全部页面形态；
• 24 个内置组件：布局（section / grid）、基础（标题 / 文本 / 富文本 / 图片 / 按钮）、数据（文章列表 / 轮播 / 友情链接 / 联系卡）三组；
• 草稿 / 发布 / 修订回滚：匿名访客只见已发布版本，修订可随时回滚；
• 中英双语与可见性：组件文案中英 Tab，支持节点语言白名单与会员限定；
• 三端预览：桌面 / 平板 / 手机预览与全屏预览，iframe 内服务端真实渲染；
• 插件开箱即用：轮播图、产品、招聘、教程插件启用后自动贡献组件与首页默认布局片段。

5.7插件管理

插件是 ZhyCMS 扩展能力的主要方式。后台「插件管理」页可查看全部插件，启停即时生效、无需重启：

• 启用 / 禁用：以 site_settings.enabled_plugins 门控，禁用即隐身、不删数据；
• 依赖强校验：manifest.json 中的 min_core_version → requires → extends 依次校验，禁用被依赖插件会被拦截并提示先禁用哪些插件；
• 加载失败提示：插件 import 出错会在启动日志标红并继续加载其余插件，后台显示「加载失败」及原因；
• 删除保护：内置插件不可卸载，删除需一次性验证码，启用中的插件需先禁用。

5.8用户与角色（RBAC）

后台「用户管理」维护管理员账号，「角色管理」维护权限体系：

• 两级权限模型：角色（编辑、审核、运营等）→ 权限点（菜单权限、按钮权限）；
• 栏目级内容粒度：可为角色授权到具体栏目，实现「只管理自己负责的栏目」；
• 工作流配合：无发布权限的作者提交后进入审核队列，编辑审核后发布，实现内容审核闭环。

5.9表单收集

「自定义表单」插件提供可视化表单设计器：拖拽字段搭建表单（联系表单、在线留言、报名登记等），嵌入前台页面。访客提交后：

• 数据入库，后台可查看、导出提交记录；
• 实时通知：提交触发邮件或企业微信消息，第一时间收到线索。

5.10系统设置

「系统设置」聚合站点运行的关键开关，分页签管理：

5.11审计日志

系统对关键操作全量留痕：登录 / 登出、配置变更、内容增删改、备份恢复、权限调整、插件与主题操作等。支持按模块、操作类型、操作人、时间范围多维度检索；详情人性化展示——键名中文翻译、状态语义化、变更对照（旧值 → 新值）、ID 自动显示名称。

5.12备份与恢复

后台「备份与恢复」一键操作，产物存 instance/backups/（含数据库 + 上传目录）：

• 三种备份方式：MySQL / PostgreSQL 原生导出、JSON 全量导出；
• 恢复：选择备份文件一键还原；恢复到旧版本库后启动新代码会自动 upgrade head 补齐迁移；
• 建议：每季度做一次恢复演练；生产环境另可用 mysqldump / pg_dump 兜底。

5.13REST API

ZhyCMS 提供 /api/v1/ 只读端点，适合小程序、Headless 前端与第三方系统读取内容：

• Token 鉴权：后台生成 API Token，请求携带令牌访问；
• CORS 支持：允许跨域调用；
• 覆盖栏目与文章等核心内容的读取，插件可通过扩展机制贡献自有 API 端点。

前台体验由「主题 × 搜索 × 多语言 × 会员」四件事构成。默认情况下，前台访问无需任何配置即可浏览已发布内容。

6.1多主题切换

系统内置 6 套主题（含 default_en、manufacturing_en 两套英文主题）。管理员在后台「主题管理」启用某套主题后，前台全局即时切换；不同栏目还可通过「栏目级模板」呈现不同版式。每套主题自带独立的 css / js / images / fonts 资源目录，互不干扰。

6.2全文搜索

前台搜索框支持中文分词检索，命中关键词高亮显示并分页。索引范围包括：文章（标题 + 正文去 HTML + 摘要 + 栏目名）、产品（含规格参数）、招聘岗位（含部门 / 地点 / 薪资）。

6.3多语言（国际化）

• 界面文案：前台 + 后台界面支持中英文切换（Flask-Babel），默认关闭，开启后即时生效；
• 内容级多语言：文章、栏目、碎片、产品、表单、岗位、友情链接支持多语言翻译表，前台模板通过全局 t(obj, field) 按当前语言取翻译，无翻译时回退默认语言；
• 结构化字段：产品「规格参数」（JSON）、岗位「部门 / 工作地点 / 薪资待遇」支持按语言维护，翻译留空回退默认语言；
• 一键翻译：编辑页多语言 Tab 可一键调用百度 / 有道 / Google / DeepSeek 翻译回填（需启用并配置 auto_translate 插件）。

6.4前台会员（社区插件）

启用 member 插件后，前台支持完整的会员体系：注册 / 登录 / 资料维护 / 修改密码 / 找回密码，微信 / QQ 一键登录、短信验证码登录，注册协议确认；配合栏目的「会员可见性」，可构建仅会员可访问的内容专区。

ZhyCMS 的扩展能力全部通过插件提供：官方内置插件 8 个（不可卸载），社区插件 3 个（随包分发、可卸载）。

7.1内置与社区插件一览

7.2插件开发机制

开发新插件只需在 plugins/<slug>/ 目录放置 manifest.json 与插件类文件，遵循 PluginBase 基类约定：

插件详细开发规范见仓库 docs/PLUGIN_DEV.md（含可直接复制的最小示例插件）。

ZhyCMS 内置存储抽象层：所有上传走同一入口，本地存储与云存储可无缝切换，历史文件支持一键迁移上云。

8.1支持的厂商

8.2配置与迁移

1. 启用插件并配置凭证

   后台「插件管理」启用 oss_storage，在对象存储设置页填写厂商凭证。未配置凭证时行为与本地存储完全一致，零侵入、不产生云端调用。

2. 新上传文件自动上云

   启用后新上传的图片与附件自动写入云端，正文 / 封面等链接使用云域名。

3. 一键迁移历史文件

   在设置页触发「迁移本地文件」：批量上传本地历史文件，自动改写文章正文、封面等链接为云域名，完成平滑上云。

ZhyCMS 从访问控制、登录、上传、输入、运维五个层面构建纵深防御。

以下内容整理自官方运维文档 docs/OPERATIONS_FAQ.md，适用 ZhyCMS ≥ 2.6.4。排查问题先做「三板斧」：看日志、查健康检查、核对系统设置。

cd 项目根
python - <<'PY'
from app import create_app
from flask_migrate import upgrade
app = create_app()
with app.app_context():
    upgrade(directory='migrations')
PY

# 应用存活
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:5000/healthz

# 查看当前迁移版本
python -c "
from app import create_app
from sqlalchemy import text
app = create_app()
with app.app_context():
    from app.extensions import db
    print(db.session.execute(text('SELECT version_num FROM alembic_version')).all())
"

# 缩略图缓存可安全清空重建
rm -rf instance/image_cache/*

# Docker 常用
docker compose --profile mysql logs -f app
docker compose --profile mysql ps
docker compose --profile mysql down -v   # 注意：清空数据卷

ZhyCMS 自 2026 年 8 月发布以来快速迭代，从内容管理核心走向「插件生态 + 可视化建站」的完整平台。

11.1升级原则

• 一般升级：覆盖代码 + pip install -r requirements.txt + 重启应用即可，首次启动自动执行 Alembic 增量迁移；
• 数据库结构变更：迁移涉及建表、补列、数据回填，仅启动程序即可完成（v1.1 → v2.0+ 除外，需备份后执行 scripts/upgrade_v2.py 专用脚本）；
• 升级前必做：备份站点目录与数据库；v2.3.0 及更早旧库覆盖代码后首次启动自动 stamp 基线，仅执行增量迁移；
• 行为兼容：v2.6.x → v3.0.0 升级后所有页面默认仍走手写模板，行为与旧版完全一致；到「页面构建」创建并发布布局后，对应页面才切换为构建器渲染。

完整升级对照表与注意事项见仓库 UPGRADE.md 与 CHANGELOG.md。

仓库镜像：GitHub pollybird/zhycms · Gitee pollybird/zhycms · GitCode pollybird/ZhyCMS，三平台同步更新。