servd

Servd — Craft CMS 托管服务

Servd（servd.host）的参考资料，这是一个专为 Craft 打造的托管平台。涵盖 Git 推送部署和 servd.yaml 构建配置、本地 → 预发布 → 生产环境工作流、servd/craft-asset-storage 插件、Servd 的静态缓存（以及如何同时运行 Blitz）、通过 SSH 访问数据库、备份、队列运行器、临时文件系统，以及 Servd 与 Craft Cloud 的区别。

本技能专门针对 Servd——说明 Servd 与在 Forge 或裸机上自行运行 Craft，以及与 Pixel & Tonic 的 Craft Cloud 有何不同。有关通用的 Craft 部署，请参阅 craftcms 技能中的 deployment.md。有关 Craft Cloud，请参阅 craft-cloud 技能。

配套技能 — 按需加载

• craftcms — 当 Servd 主题涉及插件或模块 PHP（临时文件系统检查、队列任务设计、资源文件系统代码）时。
• craft-site — 当 Servd 涉及前端模板（缓存页面中的 {% dynamicInclude %} 岛、变换用法、缓存表单中的 CSRF）时。
• ddev — 用于本地开发；Servd 没有官方本地环境，因此 DDEV 是标准的本地技术栈。
• craft-php-guidelines — 修改插件 PHP 以添加临时文件系统检查时。

文档

编写本技能时使用的权威资料来源（Servd 官方文档）：

• 文档首页：https://servd.host/docs
• Servd 工作流：https://servd.host/docs/the-servd-workflow
• Node 构建步骤（servd.yaml）：https://servd.host/docs/node-build-step
• 资源卷和文件系统：https://servd.host/docs/servd-asset-volumes-and-filesystems
• 安装插件：https://servd.host/docs/installing-the-servd-plugin
• 静态缓存：https://servd.host/docs/static-caching
• 使用 Blitz 缓存：https://servd.host/docs/caching-with-blitz
• 处理运行时创建的文件：https://servd.host/docs/handling-runtime-created-files
• 专用队列运行器：https://servd.host/docs/dedicated-queue-runner
• 备份与恢复：https://servd.host/docs/backup-restore
• 插件控制台命令：https://servd.host/docs/servd-plugin-console-commands
• 插件源码：https://github.com/servdhost/craft-asset-storage

各项说明对应的 URL 出现在每个参考文件中。最近一次根据文档核实的日期为 2026-05-30。部分运维细节（cron、具体套餐层级）未见于公开文档，并在相应位置标注为 待核实。

Servd 与自托管有何不同

每一行都指出了自托管习惯可能让你产生误解的地方。

关注点	自托管	Servd
配置文件	.env、config/*.php、Web 服务器配置	仓库根目录中的 servd.yaml，用于构建步骤（可选；会覆盖控制面板设置）；平台设置和运行时环境变量在 Servd 控制面板中配置
部署	你自行配置的任何方式	Git 推送即部署（GitHub/GitLab/Bitbucket 或任何 SSH 主机）→ Composer 安装 + 可选的 Node 构建
环境	由你自行定义	固定为 local → staging → production，且只能单向推进；除 local 外，所有环境中的 allowAdminChanges 均关闭
文件系统	本地磁盘	临时性 + 负载均衡——磁盘写入不会持久保存；使用 Redis（Craft 数据缓存）或远程资源卷
资源	本地资源或你自己的 S3 配置	servd/craft-asset-storage——由 S3 提供支持、位于 *.files.svdcdn.com CDN 上的 Flysystem，按环境自动隔离
图像转换	在服务器上使用原生功能 / Imager-X / ImageOptimize	通过 Servd Asset Platform 在服务器外转换；Imager-X 使用 transformer: 'servd'
数据库	你安装的任何数据库	MariaDB 或 MySQL 8，通过 SSH 隧道连接
页面缓存	Blitz 或类似工具	内置 Servd 静态缓存；Blitz 以反向代理模式与其并行运行（而非替代它）
队列	由你运行工作进程	默认由 AJAX 触发；可选择启用 Dedicated Queue Runner（付费方案），以隔离方式立即处理
Cron	crontab	未记录为用户可配置功能——请围绕队列设计（具体方案需核实）
Redis	由你安装	已提供——Craft 的数据缓存会自动映射到有状态 Redis
SSH	ssh user@server	支持——SSH 会话（例如用于数据库隧道）
环境变量	.env	由控制面板按环境管理（不使用已提交的 .env）

Servd 与 Craft Cloud（快速对比）

两者都是托管式 Craft 主机服务，均支持 Git 部署、临时文件系统、S3 资源、服务器外图像转换和控制面板环境变量。对开发者而言，主要区别如下：

	Servd	Craft Cloud
仓库配置	servd.yaml（构建）+ 控制面板	craft-cloud.yaml
资源层	servd/craft-asset-storage 插件	craftcms/cloud 捆绑文件系统
数据库	MariaDB 或 MySQL 8	MySQL 8 / Postgres 15（不支持 MariaDB）
SSH	支持	不支持
官方 CLI	无（插件控制台命令 + 控制面板）	craftcms/cloud + php craft cloud/up
缓存	Servd 静态缓存；Blitz 与其并行运行	边缘静态缓存；Blitz 功能重复
图像转换	Servd Asset Platform（svdcdn.com）	在边缘使用 Cloudflare Images
队列	Dedicated Queue Runner（付费）	自动处理

常见陷阱（跨领域）

• 写入磁盘并期望数据持久保存。 文件系统是临时的，并且采用负载均衡——写入内容会消失，也不会在各实例间共享。请使用 Craft 的数据缓存（自动映射到 Redis）或远程资源卷。参见 references/limitations.md。
• 在本地以外的环境更改架构或项目配置。 Servd 会在暂存环境和生产环境中设置 allowAdminChanges: false，并进行单向同步（本地 → 暂存环境 → 生产环境）。请在本地进行更改、提交并部署。参见 references/deploy-and-environments.md。
• 将 Blitz 当作 Servd 缓存的替代品。 在 Servd 上，你需要以反向代理模式（Yii Cache Storage + HTTP Generator + Servd Static Cache Purger）将 Blitz 与静态缓存配合使用——Blitz 自带的服务器重写模式会因 Servd 的负载均衡而无法正常工作。参见 references/caching.md。
• 提交用于运行时配置的 .env。 运行时环境变量应在 Servd 控制面板中按环境配置，而不是提交 .env。SERVD_PROJECT_SLUG / SERVD_SECURITY_KEY 来自控制面板的 Assets 页面。
• 使用本地资源卷。 用户资源必须使用 servd/craft-asset-storage 文件系统，以便将其存放到 Servd Asset Platform，并在部署后保留。参见 references/asset-storage.md。
• 在 CI 操作中加入 composer install / npm run build。 Servd 会在构建步骤中运行这两条命令。请改用 servd.yaml 或控制面板配置 Node 构建。参见 references/deploy-and-environments.md。
• 假设支持任意 cron。 Servd 没有记录可由用户配置的 cron。请将周期性任务移至队列作业和 Dedicated Queue Runner。请根据套餐确认。参见 references/database-and-queue.md。
• 选择了错误的数据库使用方式。 Servd 支持 MariaDB 和 MySQL 8；请通过 SSH 隧道连接数据库，而不是使用直接公开的端口。参见 references/database-and-queue.md。

参考文件

请阅读与任务相关的参考文件。通常需要参考多个文件。

任务示例：

• “将 Craft 站点部署到 Servd” → deploy-and-environments.md
• “配置 Node 构建步骤 / servd.yaml” → deploy-and-environments.md
• “设置环境并在环境之间同步” → deploy-and-environments.md + local-dev.md
• “安装 Servd 资源存储” → asset-storage.md
• “为什么上传的资源会消失？” → asset-storage.md + limitations.md
• “在 Servd 上设置图像转换” → asset-storage.md
• “启用静态缓存” → caching.md
• “在 Servd 上运行 Blitz” → caching.md（Blitz 反向代理模式）
• “向缓存页面添加动态岛” → caching.md（{% dynamicInclude %}）
• “连接到 Servd 数据库” → database-and-queue.md
• “设置队列 / 运行定期任务” → database-and-queue.md
• “备份 / 恢复 / 同步数据库” → database-and-queue.md + local-dev.md
• “为 Servd 项目设置本地开发环境” → local-dev.md
• “将生产环境资源 / 数据库拉取到本地” → local-dev.md
• “为什么我的插件在 Servd 上无法写入文件？” → limitations.md
• “哪些插件可在 Servd 上使用？” → limitations.md
• “我应该使用 Servd 还是 Craft Cloud？” → limitations.md（Servd 与 Cloud）+ 本文件中的表格

仅加载任务所需的参考文件。

参考文件	范围	约行数
references/deploy-and-environments.md	Git 推送部署、构建步骤（Composer + Node、servd.yaml 键、Node 版本）、环境（本地 → 暂存 → 生产，单向）、项目配置 + allowAdminChanges、环境变量和密钥、部署 / 克隆工作流	~150
references/asset-storage.md	servd/craft-asset-storage 插件（Composer 包、句柄、安装）、SERVD_PROJECT_SLUG/SERVD_SECURITY_KEY、位于 *.files.svdcdn.com 的 Servd 文件系统、各环境目录、服务器外图像转换、Imager-X（transformer: 'servd'）和 ImageOptimize 集成	~140
references/caching.md	Servd 静态缓存（启用 + TTL、完整清除与基于标签的清除、排除前缀、{% dynamicInclude %} 标签、CSRF 注入、保存时自动清除缓存、clear-caches/servd-static-cache + servd-edge-caches），以及以反向代理模式运行 Blitz	~140
references/database-and-queue.md	MariaDB / MySQL 8、SSH 隧道访问、自动 + 手动备份（保留 30 天、已删除资源保留 90 天）、专用队列运行器、cron 注意事项、控制台同步命令	~130
references/local-dev.md	基于 DDEV 的本地开发（Servd 没有官方本地环境）、本地环境的 SERVD_* 变量、servd-asset-storage/local/pull-assets·push-assets·pull-database·push-database、servd-asset-storage/clone、单向同步规范	~120
references/limitations.md	临时且负载均衡的文件系统（运行时文件需使用 Redis + 远程卷）、插件 / 功能限制、文档说明与未知事项（cron）、Servd 与 Craft Cloud 的完整比较，以及仓库检测信号（servd/craft-asset-storage、servd.yaml、SERVD_* 环境变量）	~140