1. 项目概述：这不是一次普通升级，而是一次面向真实工作流的“可用性重校准”

Plone 4 的 Demo Site —— 别把它当成一个花哨的首页轮播图集合。我从 2009 年第一次在德国汉堡的 Plone Conference 上看到它起，就把它当作一个活体标本：它不展示“理论上能做什么”，而是持续暴露“实际工作中卡在哪”。这次“What’s New”更新，核心不是堆砌新功能列表，而是对过去三年社区反馈最密集的五个断点做了外科手术式修复。比如，内容编辑者反复抱怨“上传一张活动海报后，必须手动去三处地方填标题、摘要、SEO关键词”，这次直接在上传弹窗里集成了元数据预填区；又比如，前端开发同事总在问“为什么自定义主题后，搜索框位置会错位”，这次把主题钩子（theme hooks）的 DOM 插入点从模糊的#portal-searchbox改为精确到<div class="search-wrapper"><div class="search-wrapper">wget https://launchpad.net/plone/4.3/4.3.20/+download/Plone-4.3.20-UnifiedInstaller.tgz tar -xzf Plone-4.3.20-UnifiedInstaller.tgz cd Plone-4.3.20-UnifiedInstaller

验证：检查base_skeleton/目录是否存在，它是 Demo Site 的模板基础。

步骤 2：运行安装脚本（关键参数！）

sudo ./install.sh --target=/opt/plone4 --user=plone_daemon --password=your_strong_password --static-lxml=yes --no-supervisor

为什么加这些参数？

• --static-lxml=yes：强制静态编译lxml，避免在pip install时因系统libxml2版本不匹配而崩溃；
• --no-supervisor：Supervisor 在 Plone 4 环境中常与zeoctl冲突，直接用bin/instance start更可控；
• --user=plone_daemon：创建专用用户，杜绝root运行风险（Plone 官方安全指南第 3.2 条明令禁止）。

步骤 3：初始化 Demo Site

cd /opt/plone4/zinstance bin/buildout -c demo.cfg # 注意：不是 buildout.cfg，是 demo.cfg！ bin/instance fg # 前台启动，观察日志

验证：访问http://localhost:8080，应看到 Plone 安装向导页面，且Select a site profile下拉框中包含Plone Demo Site (4.3.20)选项。

步骤 4：创建站点并启用扩展

• 在向导中，Site ID填demo-site，Title填Plone 4 Demo Site；
• Profile选择Plone Demo Site (4.3.20)；
• 创建完成后，登录http://localhost:8080/demo-site/portal_quickinstaller；
• 勾选plone.app.contenttypes、plone.app.event、plone.app.widgets，点击Install；
• 终极验证：进入/demo-site/events/，点击Add new...→Event，页面应出现Registration标签页，且包含Enable registration复选框。

4.3 自定义主题部署：从零开始构建一个“可维护”的主题

我们以一个极简的my-demo-theme为例，展示如何规避传统主题开发的三大陷阱（样式污染、JS 冲突、更新失联）：

陷阱 1：样式污染
旧做法：直接修改plone.app.theming的less文件，导致升级后所有自定义样式丢失。
新做法：创建my-demo-theme包，结构如下：

my-demo-theme/ ├── setup.py ├── my_demo_theme/ │ ├── __init__.py │ └── profiles/ │ └── default/ │ ├── metadata.xml │ └── theme.xml # 指向外部 CSS/JS └── resources/ ├── css/ │ └── custom.less # 仅覆盖变量，如 @plone-primary-color: #2a5885; └── js/ └── custom.js # 仅封装业务逻辑，如 $('#register-btn').on('click', handleRegister);

theme.xml中指定：

<theme> <name>My Demo Theme</name> <development-css>++resource++my_demo_theme/css/custom.css</development-css> <production-css>++resource++my_demo_theme/css/custom.min.css</production-css> </theme>

构建时，custom.less编译为custom.css，再经cssmin压缩为custom.min.css，全程与 Plone 核心 CSS 分离。

陷阱 2：JS 冲突
旧做法：在custom.js里写$(document).ready(...)，与 Plone 的plone.formwidget.querystring初始化竞争。
新做法：利用 Plone 的requirejs配置，在profiles/default/registry.xml中：

<records interface="Products.CMFPlone.interfaces.IResourceRegistry"> <value key="plone.bundles/my-demo-theme.deps">['plone.jquery', 'plone.formwidgets.querystring']</value> <value key="plone.bundles/my-demo-theme.resources">['my-demo-theme-js']</value> </records>

这样，custom.js会在plone.formwidgets.querystring加载完毕后才执行，$('#querystring-form')必然存在。

陷阱 3：更新失联
旧做法：主题 CSS 直接写死在portal_css，Plone 升级后需手动重新注册。
新做法：my-demo-theme作为一个标准 Egg 包，通过bin/buildout安装。升级时，只需：

1. 修改setup.py中install_requires=['Plone>=4.3.20']；
2. bin/buildout；
3. bin/instance restart。
   Plone 会自动检测my_demo_theme的新版本，并重新注册所有资源。

5. 常见问题与排查技巧实录：那些让你凌晨三点还在查日志的“幽灵错误”

5.1 “上传图片后，预览图显示为红叉” —— 不是权限问题，是 MIME 类型白名单

现象：在/demo-site/news/下上传report.png，内容编辑器中显示红叉，但文件实际已存入portal_resources。
根因：Plone 4 默认 MIME 类型白名单过于保守，image/png被列为unsafe，导致@@images视图拒绝渲染。
排查命令：

# 查看当前白名单 curl -u admin:your_password http://localhost:8080/demo-site/portal_properties/mimetypes_registry/properties # 检查 image/png 的 safe_flag curl -u admin:your_password "http://localhost:8080/demo-site/portal_properties/mimetypes_registry/mime_types/image_png/properties"

解决方案：

1. 进入http://localhost:8080/demo-site/portal_properties/mimetypes_registry；
2. 找到image/png条目 → 点击Properties；
3. 将safe_flag从False改为True；
4. 点击Save Changes。

实操心得：同理处理image/webp（需先在mimetypes_registry中添加该类型，mime_type填image/webp，glob填*.webp）。别忘了重启实例，因为 MIME 类型注册是启动时加载的。

5.2 “启用 event.registration 后，报名表单提交无反应” —— CSRF 令牌未正确传递

现象：点击Submit Registration按钮，页面无跳转、无提示，浏览器控制台报403 Forbidden。
根因：Plone 4 的 CSRF 保护机制要求所有 POST 请求必须携带_authenticator隐藏字段，而event.registration的表单模板未自动注入。
临时修复（快速验证）：
在event_registration_form.pt中，<form>标签内手动添加：

<input type="hidden" name="_authenticator" tal:attributes="value view/authenticator/token" />

永久修复：

1. 进入http://localhost:8080/demo-site/portal_view_customizations；
2. 找到event_registration_form→ 点击Customize；
3. 在form标签内插入上述代码行；
4. 点击Save。

注意：此问题在 Plone 4.3.19 修复，但 Demo Site 基于 4.3.20，故默认已包含。若你遇到，大概率是手动降级了plone.app.event包。

5.3 “主题切换后，搜索框消失” ——><metal:main-macro define-macro="main"> <div metal:fill-slot="main"> <!-- 你的主题 HTML --> </div> <!-- 关键！必须显式调用 search viewlet --> <div metal:use-macro="context/@@main-template/macros/viewlets"> <div metal:fill-slot="viewlets"> <div metal:use-macro="context/@@viewletmanager?name=plone.portalheader" /> <div metal:use-macro="context/@@viewletmanager?name=plone.searchbox" /> </div> </div> </metal:main-macro>

若省略<div metal:use-macro="context/@@viewletmanager?name=plone.searchbox" />，># 在 ZMI 的 portal_javascripts 中，选中所有 jquery 相关项 → Properties → merge=True # 同理处理 portal_css 中的 plone*, base*, collective* 等

步骤 2：配置资源压缩
在portal_registry中，设置：

• plone.resources/jquery-compressed→enabled=True
• plone.resources/plone-compressed→enabled=True
• plone.resources/tinymce-compressed→enabled=True

步骤 3：CDN 回源配置（可选但推荐）
若使用 Nginx 前置，添加：

location ~ ^/++resource\+\+/.*$ { proxy_pass http://plone_backend; proxy_cache plone_cache; proxy_cache_valid 200 302 1h; expires 1h; }

实测数据：优化后，/demo-site/首屏加载时间从 3.2s 降至 1.2s（WebPageTest，3G 网络模拟），Time to Interactive从 5.8s 降至 2.1s。

6.2 权限模型加固：堵住“编辑者越权”的三个隐秘通道

Plone 4 的权限模型强大但复杂，Demo Site 默认配置存在三个常见越权点：

越权点 1：Review portal content权限泄露
现象：普通编辑者可审核他人提交的内容。
根因：plone.app.workflow的simple_publication_workflow将Review portal content赋予Editor角色。
加固：

• 进入http://localhost:8080/demo-site/portal_workflow；
• 点击simple_publication_workflow→States→pending；
• 在Permissions表中，将Review portal content的Acquire列取消勾选，并将Roles设为['Manager', 'Reviewer']。

越权点 2：Delete objects权限未限制
现象：编辑者可删除整个Events文件夹。
根因：Folder类型的Delete objects权限默认授予Owner和Manager，但Owner是内容创建者，非管理员。
加固：

• 进入http://localhost:8080/demo-site/portal_types/Folder；
• Security标签页 →Delete objects→ 取消Owner勾选，仅保留Manager。

越权点 3：Manage portlets权限开放过度
现象：编辑者可修改首页的News Portlet，导致重要公告被误删。
根因：plone.portlet.collection的Manage portlets权限默认开放。
加固：

• 进入http://localhost:8080/demo-site/portal_portlets；
• 点击Collection Portlet→Security→Manage portlets→ 仅勾选Manager,Site Administrator。

最后一步验证：用一个新建的Editor账号登录，尝试删除/demo-site/events/，应收到You are not authorized to perform this action.提示。

6.3 日志审计配置：让每一次“谁在何时做了什么”都有据可查

Plone 4 默认日志不记录内容级操作。要实现完整的操作审计，需启用Products.CMFCore的事件日志：

步骤 1：启用事件日志
在portal_registry中，设置：

• plone.audit.enabled→True
• plone.audit.log_level→INFO
• plone.audit.log_file→/opt/plone4/zinstance/var/log/audit.log

步骤 2：配置日志轮转
在zinstance/etc/zope.conf中，添加：

<eventlog> level INFO <logfile> path /opt/plone4/zinstance/var/log/audit.log format %(asctime)s %(levelname)-8s %(name)s %(message)s </logfile> </eventlog>

并确保logrotate配置：

/opt/plone4/zinstance/var/log/audit.log { daily missingok rotate 30 compress delaycompress notifempty }

步骤 3：审计日志解读
audit.log中典型条目：

2024-05-21 14:22:31,123 INFO Products.CMFCore.AuditTool User 'editor1' created object '/demo-site/events/python-conference-2024' of type 'Event' 2024-05-21 14:23:05,456 INFO Products.CMFCore.AuditTool User 'editor1' modified field 'title' of object '/demo-site/events/python-conference-2024' from 'PyCon 2024' to 'Python Conference 2024'

这为合规审计（如等保 2.0 第六章）提供了原始依据。

我在某政务网项目中，正是依靠这份日志，在一次误操作后 3 分钟内定位到是editor2在/news/2024/下误删了policy-update-january.pdf，并立即从portal_history中恢复了前一版本。没有它，找回文件至少需要 2 小时。

7. 后续演进与个人经验：一个老 Ploneer 的真实体会

这个 Demo Site 的更新，对我而言，不是一次技术升级，而是一次认知刷新。十年前，我痴迷于“能做什么”——能集成 LDAP、能对接 Solr、能跑在 Docker 里。现在，我更关注“谁在用，怎么用得顺”。Plone 4 Demo Site 的这次迭代，恰恰印证了这一点：它没有加入一个新数据库引擎，却让内容编辑的平均任务完成时间缩短了 37%；它没有宣传“毫秒级响应”，但通过>