diff --git a/web/resources/email/cloud/maintenance-notice.tpl b/web/resources/email/cloud/maintenance-notice.tpl
new file mode 100644
index 00000000..b5baf0d9
--- /dev/null
+++ b/web/resources/email/cloud/maintenance-notice.tpl
@@ -0,0 +1,30 @@
+{extends file='layout.tpl'}
+
+{block name='email_title'}{$notice_subject|escape:"html"} | {$config["appName"]|escape:"html"}{/block}
+{block name='preheader'}{$scope_label|escape:"html"} 将进行维护,请查看受影响实例和 UTC 时间窗口。{/block}
+
+{block name='content'}
+
MAINTENANCE NOTICE
+ {$notice_subject|escape:"html"}
+ {$message_text|escape:"html"|nl2br}
+
+
+
+ | 维护范围{$scope_label|escape:"html"} |
+ 预计影响{$impact_label|escape:"html"} |
+
+
+ | 开始时间(UTC){$maintenance_starts_utc|escape:"html"} |
+ 结束时间(UTC){$maintenance_ends_utc|escape:"html"} |
+
+
+
+ 受影响的实例
+ {foreach $instances as $instance}
+
+ | {$instance.name|escape:"html"}IPv4:{$instance.ipv4|default:'—'|escape:"html"}IPv6:{$instance.ipv6|default:'—'|escape:"html"} |
+
+ {/foreach}
+
+ | 维护时间统一使用 UTC。实际开始和结束时间可能因现场进度略有变化,请提前保存未完成的工作。 |
+{/block}
diff --git a/web/tests/MailNotificationContractTest.php b/web/tests/MailNotificationContractTest.php
index 9f65348d..2f8c8255 100644
--- a/web/tests/MailNotificationContractTest.php
+++ b/web/tests/MailNotificationContractTest.php
@@ -16,6 +16,7 @@ $verify = file_get_contents($root . '/resources/email/auth/verify.tpl');
$reset = file_get_contents($root . '/resources/email/password/reset.tpl');
$renewal = file_get_contents($root . '/resources/email/cloud/invoice.tpl');
$provisioned = file_get_contents($root . '/resources/email/cloud/provision-success.tpl');
+$maintenance = file_get_contents($root . '/resources/email/cloud/maintenance-notice.tpl');
$contentTemplates = [];
$templateFiles = new RecursiveIteratorIterator(new RecursiveDirectoryIterator(
$root . '/resources/email', FilesystemIterator::SKIP_DOTS
@@ -42,8 +43,8 @@ foreach ($contentTemplates as $path => $template) {
$assert(str_contains($template, "{extends file='layout.tpl'}"),
'An email template does not use the shared panel theme: ' . $path);
}
-$assert(count($contentTemplates) === 13,
- 'Expected every one of the 13 content email templates to be covered.');
+$assert(count($contentTemplates) === 14,
+ 'Expected every one of the 14 content email templates to be covered.');
foreach (['#edf3f8', '#102235', '#159da9', '#15243a', '#f5f8fb'] as $color) {
$assert(str_contains(strtolower($layout), $color),
'Shared email layout is missing a user-panel theme color: ' . $color);
@@ -90,6 +91,18 @@ foreach (['root_password', 'private_key', 'sealed_credential', 'generated_passwo
$assert(!str_contains($provisioned, $secret),
'Provision success email references a forbidden secret: ' . $secret);
}
+foreach (['notice_subject', 'message_text', 'scope_label', 'impact_label',
+ 'maintenance_starts_utc', 'maintenance_ends_utc'] as $field) {
+ $assert(str_contains($maintenance, '{$' . $field . '|escape:"html"'),
+ 'Maintenance email is missing escaped field: ' . $field);
+}
+$assert(str_contains($maintenance, '{foreach $instances as $instance}')
+ && str_contains($maintenance, '{$instance.name|escape:"html"}')
+ && str_contains($maintenance, '{$instance.ipv4|default:\'—\'|escape:"html"}')
+ && str_contains($maintenance, '{$instance.ipv6|default:\'—\'|escape:"html"}')
+ && str_contains($maintenance, '开始时间(UTC)')
+ && str_contains($maintenance, '结束时间(UTC)'),
+ 'Maintenance email lost its escaped instance list or UTC window.');
$assert(str_contains($worker,
'CloudInvoiceService::queueProvisionSucceeded(')
diff --git a/web/tests/MailTemplateRenderTest.php b/web/tests/MailTemplateRenderTest.php
index 315e485f..3f09c099 100644
--- a/web/tests/MailTemplateRenderTest.php
+++ b/web/tests/MailTemplateRenderTest.php
@@ -71,6 +71,19 @@ try {
'expires_at' => '2026-10-28 18:00:00',
'instance_url' => 'https://cloud.example.test/user/cloud/instances/43?x=1&y=2',
]);
+ $maintenance = $render('cloud/maintenance-notice.tpl', [
+ 'notice_subject' => '网络 <维护>',
+ 'message_text' => "请保存 \n第二行",
+ 'scope_label' => 'HKG-A & IPv4 pool',
+ 'impact_label' => '网络可能短时中断',
+ 'maintenance_starts_utc' => '2026-11-06 03:00:00 UTC',
+ 'maintenance_ends_utc' => '2026-11-06 04:00:00 UTC',
+ 'instances' => [
+ ['name' => 'vm-', 'ipv4' => '203.0.113.10',
+ 'ipv6' => '2001:db8::10'],
+ ['name' => 'vm-two', 'ipv4' => '', 'ipv6' => ''],
+ ],
+ ]);
$user = (object) [
'user_name' => '云端 <用户>',
@@ -115,7 +128,7 @@ try {
]);
$renderedEmails = [$registration, $login, $emailChange, $reset, $renewal,
- $provisioned, $ticketCreated, $ticketReplied, $backup, $monitor,
+ $provisioned, $maintenance, $ticketCreated, $ticketReplied, $backup, $monitor,
$warning, $finance, $addressNotice, $newYear, $testMail];
foreach ($renderedEmails as $html) {
$assert(str_contains(strtolower($html), '')
@@ -148,6 +161,15 @@ try {
&& str_contains($provisioned, '203.0.113.43')
&& !str_contains($provisioned, 'not-for-email'),
'Provision-success email did not render safe instance details.');
+ $assert(str_contains($maintenance, '网络 <维护>')
+ && str_contains($maintenance,
+ '<script>alert('x')</script>')
+ && !str_contains($maintenance, '