feat: switch article publishing to SSR

8ca07403 · tao355667 · 6a8442a9 · 8ca07403 · 8ca07403 · 8ca07403
Commit 8ca07403 authored Aug 14, 2026 by tao355667
28 changed files
--- a/.env.example
+++ b/.env.example
@@ -6,4 +6,9 @@ CMS_SECRET=replace-with-openssl-rand-hex-32
 CMS_API_KEY=replace-with-openssl-rand-hex-32
 # 本地默认放入已忽略的 .runtime；生产环境请改为 /root/qiyouxue/shared/ 下的绝对路径。
 CMS_DATA_DIR=.runtime/cms-data
+# 仅供代码部署或人工构建原子替换 dist 使用，CMS 内容操作不会获取此锁。
 CMS_BUILD_LOCK=.runtime/site-build.lock
+# CMS 内容写入专用的跨进程非阻塞锁，不要与 CMS_BUILD_LOCK 共用。
+CMS_CONTENT_LOCK=.runtime/cms-data/.content-write.lock
+# 写进程异常退出后的陈旧锁恢复阈值，单位毫秒，默认 15 分钟。
+CMS_CONTENT_LOCK_STALE_MS=900000
--- a/CMS_README.md
+++ b/CMS_README.md
 # 启优学学习资讯后台
-项目采用与官网同端口的 Astro 内容后台：Markdown 文件负责存储，Astro 同时提供管理 API 与静态页面生成。文章列表、分类页和详情页均预渲染为 HTML，便于 SEO 与 AI 搜索发现。
+项目采用与官网同端口的 Astro 内容后台：Markdown 文件负责存储，Astro 同时提供管理 API 与文章 SSR。稳定官网页面继续预渲染，文章列表、分类、分页和详情在请求时直接生成完整 HTML，便于 SEO 与 AI 搜索发现，也让发布内容无需重新构建整站即可上线。
 ## 本地使用
@@ -24,7 +24,9 @@ npm start
 - `CMS_SECRET`：会话签名密钥
 - `CMS_API_KEY`：Bearer API 密钥
 - `CMS_DATA_DIR`：文章、分类与上传文件的持久化目录
- `CMS_BUILD_LOCK`：发布重建共享锁
+- `CMS_BUILD_LOCK`：仅用于代码部署或人工执行构建时原子替换 `dist/`
+- `CMS_CONTENT_LOCK`：CMS 内容写入的跨进程非阻塞锁，默认 `${CMS_DATA_DIR}/.content-write.lock`
+- `CMS_CONTENT_LOCK_STALE_MS`：异常退出后的陈旧内容锁恢复阈值，默认 `900000` 毫秒
 生产示例：
@@ -32,6 +34,8 @@ npm start
 CMS_PORT=8793
 CMS_DATA_DIR=/root/qiyouxue/shared/cms-data
 CMS_BUILD_LOCK=/root/qiyouxue/shared/site-build.lock
+CMS_CONTENT_LOCK=/root/qiyouxue/shared/cms-data/.content-write.lock
+CMS_CONTENT_LOCK_STALE_MS=900000
 ```
 ## 内容工作流
@@ -44,7 +48,11 @@ CMS_BUILD_LOCK=/root/qiyouxue/shared/site-build.lock
 - 支持 Markdown、Word `.docx` 导入和内嵌图片提取
 - 支持图片上传、Markdown 预览和后台密码修改
-生产环境配置 `CMS_DATA_DIR` 后，内容持久化到仓库外，不随单目录部署被覆盖。发布、下架、删除与分类变更会触发共享锁保护的原子站点重建。
+生产环境配置 `CMS_DATA_DIR` 后，内容持久化到仓库外，不随单目录部署被覆盖。发布、下架、删除与分类变更在 `CMS_CONTENT_LOCK` 临界区内通过同目录临时文件和原子 rename 写入；已有写操作进行中时接口立即返回 HTTP 409，不等待整站构建。锁文件记录 PID、创建时间与操作名称，支持异常进程和超时锁恢复。
+文章公开入口采用 SSR：下一次请求会读取已发布目录并立即反映新内容。`llms.txt`、`llms-full.txt` 和 `/article-sitemap.xml` 同样动态生成并支持 ETag。进程内缓存使用文件的 `mtimeMs` 与大小校验，多进程也能发现文件替换或删除。
+`CMS_BUILD_LOCK` 和 `CMS_CONTENT_LOCK` 职责必须分离：前者只允许部署脚本或人工 `npm run build` 使用，后者只允许 CMS 内容变更使用，不要配置成同一路径。
 ## API
@@ -74,4 +82,4 @@ Word 导入示例字段：
 - Nginx 配置：`/etc/nginx/conf.d/qiyouxue.conf`
 - 公网域名：`qiyouxueedu.com`
-Runner 需具备安装固定 Nginx 配置、执行 `nginx -t` 与 reload 的最小 sudo 权限。生产密钥、上传文件、CMS 数据与构建锁必须位于 `shared/`。
+Runner 需具备安装固定 Nginx 配置、执行 `nginx -t` 与 reload 的最小 sudo 权限。生产密钥、上传文件、CMS 数据、构建锁与内容写锁必须位于 `shared/`。建议内容写锁放在 `CMS_DATA_DIR` 内，确保所有 Node 进程看到同一锁文件。
--- a/README.md
+++ b/README.md
 # 启优学企业官网
-启优学一对一品牌官网。项目基于 Astro 5 + Node standalone adapter，包含品牌首页、学科辅导详情、教学服务、常见问题、联系页面、学习资讯 CMS、SEO/AI 可发现性、响应式适配、原子构建与 GitLab/Nginx 部署配置。
+启优学一对一品牌官网。项目基于 Astro 5 + Node standalone adapter，稳定官网页面采用 SSG，学习资讯采用运行时 SSR；同时包含内容 CMS、SEO/AI 可发现性、响应式适配、原子构建与 GitLab/Nginx 部署配置。
 ## 本地运行（Node 20）
@@ -42,9 +42,9 @@ npm start
 - 页面级标题、描述、关键词、canonical、Open Graph 与 Twitter Card
 - EducationalOrganization、WebSite、WebPage、Service、FAQ、Article 和 Breadcrumb 结构化数据
- sitemap、robots.txt、语义化页面、分类分页、`llms.txt` 与 `llms-full.txt`
+- 非文章静态 sitemap、动态文章 sitemap、robots.txt、语义化页面、SSR 分类分页、动态 `llms.txt` 与 `llms-full.txt`
 - Astro 图片优化、响应式图片、移动端适配、减少动态效果偏好
- Astro standalone、原子构建、共享锁与 Nginx 反向代理
+- Astro standalone、部署构建锁、CMS 内容写锁与 Nginx 反向代理
 ## 部署
@@ -53,4 +53,4 @@ npm start
 - 站点域名：`qiyouxueedu.com`
 - 服务器目录：`/root/qiyouxue/current` 与 `/root/qiyouxue/shared`
-生产部署前需在 `/root/qiyouxue/shared/.env` 配置独立的 `CMS_PASSWORD`、`CMS_SECRET`、`CMS_API_KEY`、`CMS_DATA_DIR` 和 `CMS_BUILD_LOCK`。
+生产部署前需在 `/root/qiyouxue/shared/.env` 配置独立的 `CMS_PASSWORD`、`CMS_SECRET`、`CMS_API_KEY`、`CMS_DATA_DIR`、`CMS_BUILD_LOCK` 和 `CMS_CONTENT_LOCK`。构建锁只保护部署时的 `dist/` 替换；内容锁只保护 CMS 的 Markdown 与分类写入，两者不要共用路径。
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -12,6 +12,9 @@ export default defineConfig({
      const pathname = new URL(page).pathname;
      return pathname !== "/404/"
        && pathname !== "/admin/"
+        && pathname !== "/articles"
+        && !pathname.startsWith("/articles/")
+        && pathname !== "/article-sitemap.xml"
        && !pathname.startsWith("/api/")
        && !pathname.startsWith("/uploads/")
        && !pathname.endsWith(".txt");

--- a/public/admin/app.js
+++ b/public/admin/app.js
@@ -439,7 +439,6 @@ function syncStaffRoleFields() {
  $("#teacher-modal-description").textContent = customerService ? "客服负责查看并处理分配给自己的用户咨询" : "运营负责学习资讯的创建、编辑与发布";
 }
 $("#teacher-role").addEventListener("change", syncStaffRoleFields);
-$("#close-teacher-modal").addEventListener("click", closeTeacherModal);
 $("#cancel-teacher").addEventListener("click", closeTeacherModal);
 $("#teacher-qr-button").addEventListener("click", () => $("#teacher-qr-file").click());
 async function uploadTeacherQr(file) {
@@ -474,7 +473,7 @@ $("#teacher-form").addEventListener("submit", async (event) => {
  event.preventDefault();
  const id = $("#teacher-id").value;
  const body = { role: $("#teacher-role").value, name: $("#teacher-name").value, username: $("#teacher-username").value, wechat: $("#teacher-wechat").value, sort: Number($("#teacher-sort").value || 1), password: $("#teacher-password").value, qrCodeUrl: $("#teacher-qr-url").value, enabled: $("#teacher-enabled").checked };
-  const submit = event.submitter;
+  const submit = event.submitter || $("#save-teacher");
  submit.disabled = true;
  $("#teacher-error").textContent = "";
  try {
@@ -609,7 +608,7 @@ function listMoreActions(article) {
 async function publishFromList(article) {
  try {
-    await triggerBuild(`/articles/${article.slug}/publish`);
+    await runContentAction(`/articles/${article.slug}/publish`);
    await loadArticles();
  } catch {}
 }
@@ -626,7 +625,7 @@ async function unpublishFromList(article) {
  const detail = article.publishStatus === "edited-draft" ? "未发布的修改会继续保留为草稿。" : "文章内容会继续保留为草稿。";
  if (!confirm(`确定将《${article.title}》从官网下架吗？${detail}`)) return;
  try {
-    await triggerBuild(`/articles/${article.slug}/unpublish`, { action: "下架" });
+    await runContentAction(`/articles/${article.slug}/unpublish`);
    await loadArticles();
  } catch {}
 }
@@ -637,7 +636,7 @@ async function deleteFromList(article) {
    : `确定彻底删除《${article.title}》吗？线上版本和草稿都会删除，且无法恢复。`;
  if (!confirm(prompt)) return;
  try {
-    await triggerBuild(`/articles/${article.slug}`, { action: "删除", method: "DELETE" });
+    await runContentAction(`/articles/${article.slug}`, { method: "DELETE" });
    await loadArticles();
  } catch {}
 }
@@ -703,7 +702,7 @@ async function createCategory() {
  const name = input.value.trim();
  $("#category-error").textContent = "";
  try {
-    await triggerBuild("/categories", { action: "添加分类", body: { name } });
+    await runContentAction("/categories", { body: { name } });
    await loadCategories();
    input.value = "";
    fillCategories(name);
@@ -747,10 +746,10 @@ function categoryPanel(row, text) {
  return panel;
 }
-async function runCategoryBuild(action, method, body) {
+async function runCategoryAction(method, body) {
  $("#manager-category-error").textContent = "";
  try {
-    await triggerBuild("/categories", { action, method, body });
+    await runContentAction("/categories", { method, body });
    await loadCategoryManager();
    await loadArticles();
  } catch (error) {
@@ -778,7 +777,7 @@ function showRenameCategory(row, stat) {
  save.onclick = () => {
    const name = input.value.trim();
    if (!name || name === stat.name) return clearCategoryPanels();
-    runCategoryBuild("更新分类", "PATCH", { current: stat.name, name });
+    runCategoryAction("PATCH", { current: stat.name, name });
  };
  cancel.onclick = clearCategoryPanels;
  input.addEventListener("keydown", (event) => {
@@ -804,7 +803,7 @@ function showDeleteCategory(row, stat) {
    button.type = "button";
    button.className = stat.count ? "" : "confirm-danger";
    button.textContent = stat.count ? `迁移到“${replacement}”并删除` : "确认删除分类";
-    button.onclick = () => runCategoryBuild("删除分类", "DELETE", { name: stat.name, replacement });
+    button.onclick = () => runCategoryAction("DELETE", { name: stat.name, replacement });
    actions.append(button);
  });
  const cancel = document.createElement("button");
@@ -866,7 +865,7 @@ $("#manager-add-category").addEventListener("click", async () => {
  const name = input.value.trim();
  $("#manager-category-error").textContent = "";
  try {
-    await triggerBuild("/categories", { action: "添加分类", body: { name } });
+    await runContentAction("/categories", { body: { name } });
    input.value = "";
    await loadCategoryManager();
  } catch (error) { $("#manager-category-error").textContent = error.message; }
@@ -1007,9 +1006,9 @@ $("#publish").addEventListener("click", async () => {
  $("#message").textContent = "正在保存草稿…";
  try {
    const slug = await save();
-    await triggerBuild(`/articles/${slug}/publish`);
+    await runContentAction(`/articles/${slug}/publish`);
    setEditorStatus("live");
-    $("#message").textContent = "发布成功，官网已更新。";
+    $("#message").textContent = "发布成功，文章已上线。";
  } catch (error) { $("#message").textContent = error.message; }
 });
@@ -1031,7 +1030,7 @@ $("#unpublish").addEventListener("click", async () => {
  $("#more-actions").open = false;
  $("#message").textContent = "正在下架文章…";
  try {
-    await triggerBuild(`/articles/${editingSlug}/unpublish`, { action: "下架" });
+    await runContentAction(`/articles/${editingSlug}/unpublish`);
    setEditorStatus("new-draft");
    $("#message").textContent = "文章已下架，内容已保留为草稿。";
  } catch (error) { $("#message").textContent = error.message; }
@@ -1046,7 +1045,7 @@ $("#delete-article").addEventListener("click", async () => {
  $("#more-actions").open = false;
  $("#message").textContent = "正在删除文章…";
  try {
-    await triggerBuild(`/articles/${editingSlug}`, { action: "删除", method: "DELETE" });
+    await runContentAction(`/articles/${editingSlug}`, { method: "DELETE" });
    dirty = false;
    editingSlug = null;
    setView(false);
@@ -1101,31 +1100,8 @@ $("#file").addEventListener("change", async (event) => {
  } catch (error) { $("#upload-status").textContent = error.message; }
 });
-async function triggerBuild(endpoint, { action = "发布", method = "POST", body } = {}) {
+async function runContentAction(endpoint, { method = "POST", body } = {}) {
-  show("#build-modal");
+  return api(endpoint, { method, body });
-  hide("#close-modal");
-  $("#build-title").textContent = `正在${action}…`;
-  $("#build-log").textContent = "系统正在更新官网，请稍候。";
-  try {
-    await api(endpoint, { method, body });
-  } catch (error) {
-    $("#build-title").textContent = `${action}失败`;
-    $("#build-log").textContent = error.message;
-    show("#close-modal");
-    throw error;
-  }
-  while (true) {
-    await new Promise((resolve) => setTimeout(resolve, 1000));
-    const state = await api("/build");
-    if (state.status === "building") continue;
-    if (state.ok) { hide("#build-modal"); return; }
-    $("#build-title").textContent = `${action}失败`;
-    $("#build-log").textContent = state.log || `${action}失败，请联系技术人员。`;
-    show("#close-modal");
-    throw new Error(`${action}失败，原文章已恢复，请检查操作日志。`);
-  }
 }
-$("#close-modal").addEventListener("click", () => hide("#build-modal"));
 boot();
--- a/public/admin/style.css
+++ b/public/admin/style.css
@@ -155,8 +155,6 @@ input:focus, textarea:focus, select:focus { outline: 2px solid rgba(20,115,230,.
 .confirm-danger { color: white; background: var(--danger); }
 .replacement-options button { color: var(--primary-dark); background: white; border: 1px solid var(--border); }
 .replacement-options button:hover { border-color: var(--primary); background: #eaf3ff; }
-.build-card { width: min(780px, 100%); }
-#build-log { max-height: 62vh; margin: 0; padding: 18px; overflow: auto; color: var(--muted); background: #f5f9fd; white-space: pre-wrap; font-size: 12px; }
 .admin-shell { min-height: 100vh; padding-left: 238px; }
 .sidebar { width: 238px; position: fixed; inset: 0 auto 0 0; z-index: 20; display: flex; flex-direction: column; color: #dbeaff; background: #102f55; box-shadow: 8px 0 28px rgba(10,40,75,.12); }
 .sidebar-brand { height: 86px; padding: 20px 24px; display: grid; align-content: center; border-bottom: 1px solid rgba(255,255,255,.1); }
@@ -239,11 +237,12 @@ input:focus, textarea:focus, select:focus { outline: 2px solid rgba(20,115,230,.
 .teacher-card { width: min(760px, 100%); }
 .consultation-user-card { width: min(760px, 100%); }
 .teacher-card > .modal-head,.consultation-user-card > .modal-head { flex: 0 0 auto; }
+.teacher-card > .teacher-modal-head { align-items: flex-start; justify-content: flex-start; flex-direction: column; gap: 13px; }
+.teacher-modal-head > .teacher-modal-heading { display: grid; gap: 4px; }
 .teacher-form { min-height: 0; padding: 20px; display: grid; gap: 18px; overflow-y: auto; overscroll-behavior: contain; scrollbar-gutter: stable; }
 .teacher-form::-webkit-scrollbar { width: 8px; }
 .teacher-form::-webkit-scrollbar-track { background: #f3f6f9; }
 .teacher-form::-webkit-scrollbar-thumb { background: #bdc9d6; border: 2px solid #f3f6f9; border-radius: 999px; }
-.teacher-form > .password-actions { margin-top: 2px; }
 .consultation-edit-section { padding: 17px; display: grid; gap: 15px; border: 1px solid var(--border); border-radius: 12px; background: #fbfcfe; }
 .consultation-edit-heading { display: flex; align-items: baseline; justify-content: space-between; gap: 16px; }
 .consultation-edit-heading strong { color: #203a57; font-size: 14px; }

--- a/public/robots.txt
+++ b/public/robots.txt
@@ -4,3 +4,4 @@ Disallow: /admin/
 Disallow: /api/
 Sitemap: https://qiyouxueedu.com/sitemap-index.xml
+Sitemap: https://qiyouxueedu.com/article-sitemap.xml
--- a/src/components/ArticleDetailView.astro
+++ b/src/components/ArticleDetailView.astro
+---
+import Base from "../layouts/Base.astro";
+import Header from "./Header.astro";
+import Footer from "./Footer.astro";
+import { site } from "../data/site";
+import { fmtDate } from "../lib/articles";
+import type { PublishedArticleDetail } from "../lib/article-store";
+const { entry } = Astro.props as { entry: PublishedArticleDetail };
+const article = entry.data;
+const date = fmtDate(article.date);
+const modified = fmtDate(article.updated || article.date);
+const title = `${article.title}｜学习资讯｜${site.brand.name}`;
+const pageUrl = new URL(`/articles/${entry.id}/`, Astro.site).href;
+const keywords = [article.category, article.title, "学习方法", "在线一对一", site.brand.name];
+const jsonLd = [
+  { "@context": "https://schema.org", "@type": "Article", headline: article.title, description: article.excerpt, datePublished: date, dateModified: modified, articleSection: article.category, inLanguage: "zh-CN", author: { "@type": "Organization", name: article.author }, publisher: { "@id": new URL("/#organization", Astro.site).href }, mainEntityOfPage: { "@type": "WebPage", "@id": `${pageUrl}#webpage` }, url: pageUrl },
+  { "@context": "https://schema.org", "@type": "BreadcrumbList", itemListElement: [{ "@type": "ListItem", position: 1, name: "首页", item: Astro.site?.href }, { "@type": "ListItem", position: 2, name: "学习资讯", item: new URL("/articles/", Astro.site).href }, { "@type": "ListItem", position: 3, name: article.title, item: pageUrl }] },
+];
+---
+<Base {title} description={article.excerpt} {keywords} ogType="article" publishedTime={date} modifiedTime={modified} articleSection={article.category} articleAuthor={article.author} {jsonLd}>
+  <Header />
+  <main id="main-content" class="article-detail-page"><article><header class="article-detail-head"><div class="container article-detail-head__inner"><div class="breadcrumb"><a href="/">首页</a> / <a href="/articles/">学习资讯</a> / {article.category}</div><span class="article-detail-category">{article.category}</span><h1>{article.title}</h1><p>{article.excerpt}</p><div class="article-detail-meta"><time datetime={date}>{date}</time><span>{article.author}</span></div></div></header><div class="container article-detail-layout"><aside><a href="/articles/">← 返回学习资讯</a><p>分享学情判断、学习方法、阶段复习与在线一对一服务说明。</p></aside><div class="article-prose" set:html={entry.html}></div></div></article></main>
+  <Footer />
+</Base>
--- a/src/components/ArticlesView.astro
+++ b/src/components/ArticlesView.astro
 ---
 import Base from "../layouts/Base.astro"; import Header from "./Header.astro"; import Footer from "./Footer.astro"; import ArticleListing from "./ArticleListing.astro"; import { site } from "../data/site"; import { PAGE_SIZE, type Article, type CategoryInfo } from "../lib/articles";
 interface Props { items: Article[]; categories: CategoryInfo[]; totalCount: number; activeSlug: string | null; activeName: string | null; currentPage: number; lastPage: number; basePath: string; }
-const {items,categories,totalCount,activeSlug,activeName,currentPage,lastPage,basePath}=Astro.props as Props; const heading=activeName??"学习资讯"; const pageSuffix=currentPage>1?`｜第${currentPage}页`:""; const title=`${heading}${pageSuffix}｜${site.brand.name}`; const description=activeName?`启优学${activeName}分类文章，分享学情判断、学科方法与家庭学习规划。`:"启优学学习资讯：关于小初高学情判断、学习方法、阶段复习和在线一对一服务的公开说明。"; const keywords=[heading,"学习方法","学情诊断","在线一对一",site.brand.name]; const pageUrl=new URL(`${basePath}${currentPage>1?`/page/${currentPage}`:""}/`,Astro.site).href; const jsonLd={"@context":"https://schema.org","@type":"CollectionPage",name:heading,description,url:pageUrl,inLanguage:"zh-CN",mainEntity:{"@type":"ItemList",itemListElement:items.map((item,index)=>({"@type":"ListItem",position:(currentPage-1)*PAGE_SIZE+index+1,name:item.data.title,url:new URL(`/articles/${item.id}/`,Astro.site).href}))}};
+const {items,categories,totalCount,activeSlug,activeName,currentPage,lastPage,basePath}=Astro.props as Props; const heading=activeName??"学习资讯"; const pageSuffix=currentPage>1?`｜第${currentPage}页`:""; const title=`${heading}${pageSuffix}｜${site.brand.name}`; const description=activeName?`启优学${activeName}分类文章，分享学情判断、学科方法与家庭学习规划。`:"启优学学习资讯：关于小初高学情判断、学习方法、阶段复习和在线一对一服务的公开说明。"; const keywords=[heading,"学习方法","学情诊断","在线一对一",site.brand.name]; const pagePath=(page:number)=>`${basePath}${page>1?`/page/${page}`:""}/`; const pageUrl=new URL(pagePath(currentPage),Astro.site).href; const prevUrl=currentPage>1?new URL(pagePath(currentPage-1),Astro.site).href:undefined; const nextUrl=currentPage<lastPage?new URL(pagePath(currentPage+1),Astro.site).href:undefined; const jsonLd={"@context":"https://schema.org","@type":"CollectionPage",name:heading,description,url:pageUrl,inLanguage:"zh-CN",mainEntity:{"@type":"ItemList",itemListElement:items.map((item,index)=>({"@type":"ListItem",position:(currentPage-1)*PAGE_SIZE+index+1,name:item.data.title,url:new URL(`/articles/${item.id}/`,Astro.site).href}))}};
 ---
-<Base {title} {description} {keywords} {jsonLd}><Header /><main id="main-content"><section class="page-hero"><div class="container page-hero__inner" data-reveal><div class="breadcrumb"><a href="/">首页</a> / <a href="/articles/">学习资讯</a>{activeName&&` / ${activeName}`}</div><h1>{heading}</h1><p>{description}</p></div></section><section class="section-pad section-blue"><div class="container"><ArticleListing {items} {categories} {totalCount} {activeSlug} {currentPage} {lastPage} {basePath} /></div></section></main><Footer /></Base>
+<Base {title} {description} {keywords} {prevUrl} {nextUrl} {jsonLd}><Header /><main id="main-content"><section class="page-hero"><div class="container page-hero__inner" data-reveal><div class="breadcrumb"><a href="/">首页</a> / <a href="/articles/">学习资讯</a>{activeName&&` / ${activeName}`}</div><h1>{heading}</h1><p>{description}</p></div></section><section class="section-pad section-blue"><div class="container"><ArticleListing {items} {categories} {totalCount} {activeSlug} {currentPage} {lastPage} {basePath} /></div></section></main><Footer /></Base>
--- a/src/components/NotFoundPage.astro
+++ b/src/components/NotFoundPage.astro
+---
+import Base from "../layouts/Base.astro";
+import Header from "./Header.astro";
+import Footer from "./Footer.astro";
+---
+<Base title="页面未找到｜启优学" description="你访问的页面不存在。" noindex>
+  <Header />
+  <main id="main-content">
+    <section class="not-found"><div class="container" data-reveal><span>404</span><h1>这一页暂时找不到了</h1><p>可以返回首页，继续了解启优学在线一对一课程与教学服务。</p><a class="button" href="/">返回首页</a></div></section>
+  </main>
+  <Footer />
+</Base>
--- a/src/content.config.ts
+++ b/src/content.config.ts
@@ -9,6 +9,8 @@ const articleSchema = z.object({
  category: z.string(),
  author: z.string(),
  excerpt: z.string(),
+  readingMinutes: z.number().int().positive().optional(),
+  featured: z.boolean().optional(),
  status: z.enum(["draft", "published"]),
 });

--- a/src/layouts/Base.astro
+++ b/src/layouts/Base.astro
@@ -5,8 +5,8 @@ import logo from "../../pic/启优学LOGO-透明.png";
 import { getImage } from "astro:assets";
 import { site } from "../data/site";
 import ContactDialog from "../components/ContactDialog.astro";
-interface Props { title: string; description?: string; keywords?: string | readonly string[]; image?: string; imageAlt?: string; ogType?: "website" | "article"; noindex?: boolean; publishedTime?: string; modifiedTime?: string; articleSection?: string; articleAuthor?: string; jsonLd?: Record<string, unknown> | Record<string, unknown>[]; }
+interface Props { title: string; description?: string; keywords?: string | readonly string[]; image?: string; imageAlt?: string; ogType?: "website" | "article"; noindex?: boolean; publishedTime?: string; modifiedTime?: string; articleSection?: string; articleAuthor?: string; prevUrl?: string; nextUrl?: string; jsonLd?: Record<string, unknown> | Record<string, unknown>[]; }
-const { title, description = site.seo.description, keywords = site.seo.keywords, image = "/og-cover.svg", imageAlt = site.seo.imageAlt, ogType = "website", noindex = false, publishedTime, modifiedTime, articleSection, articleAuthor, jsonLd = [] } = Astro.props;
+const { title, description = site.seo.description, keywords = site.seo.keywords, image = "/og-cover.svg", imageAlt = site.seo.imageAlt, ogType = "website", noindex = false, publishedTime, modifiedTime, articleSection, articleAuthor, prevUrl, nextUrl, jsonLd = [] } = Astro.props;
 const cleanMeta = (value: string) => value.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
 const metaTitle = cleanMeta(title); const metaDescription = cleanMeta(description);
 const metaKeywords = (typeof keywords === "string" ? keywords.split(",") : keywords).map((keyword) => cleanMeta(keyword)).filter(Boolean).join(",");
@@ -17,6 +17,6 @@ const websiteLd = { "@context": "https://schema.org", "@type": "WebSite", "@id":
 const webPageLd = { "@context": "https://schema.org", "@type": "WebPage", "@id": `${canonical}#webpage`, url: canonical, name: metaTitle, description: metaDescription, inLanguage: "zh-CN", isPartOf: { "@id": new URL("/#website", Astro.site).href }, about: { "@id": new URL("/#organization", Astro.site).href }, primaryImageOfPage: { "@type": "ImageObject", url: ogImage, caption: imageAlt } };
 const pageLd = Array.isArray(jsonLd) ? jsonLd : [jsonLd]; const serializedLd = JSON.stringify([organizationLd, websiteLd, webPageLd, ...pageLd.filter((item) => Object.keys(item).length > 0)]).replace(/</g, "\\u003c");
 ---
-<!doctype html><html lang="zh-CN"><head><meta charset="UTF-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><meta name="theme-color" content="#1473E6" /><meta name="color-scheme" content="light" /><title>{metaTitle}</title><meta name="description" content={metaDescription} /><meta name="keywords" content={metaKeywords} /><meta name="robots" content={noindex ? "noindex,nofollow" : "index,follow,max-image-preview:large,max-snippet:-1,max-video-preview:-1"} /><link rel="canonical" href={canonical} /><link rel="icon" href="/favicon.png" type="image/png" sizes="512x512" /><link rel="apple-touch-icon" href="/favicon.png" /><link rel="manifest" href="/site.webmanifest" /><link rel="alternate" hreflang="zh-CN" href={canonical} /><link rel="alternate" hreflang="x-default" href={canonical} /><meta property="og:type" content={ogType} /><meta property="og:title" content={metaTitle} /><meta property="og:description" content={metaDescription} /><meta property="og:url" content={canonical} /><meta property="og:image" content={ogImage} /><meta property="og:image:alt" content={imageAlt} /><meta property="og:site_name" content={site.brand.name} /><meta property="og:locale" content="zh_CN" />{publishedTime && <meta property="article:published_time" content={publishedTime} />}{modifiedTime && <meta property="article:modified_time" content={modifiedTime} />}{articleSection && <meta property="article:section" content={articleSection} />}{articleAuthor && <meta property="article:author" content={articleAuthor} />}<meta name="twitter:card" content="summary_large_image" /><meta name="twitter:title" content={metaTitle} /><meta name="twitter:description" content={metaDescription} /><meta name="twitter:image" content={ogImage} /><script type="application/ld+json" set:html={serializedLd} is:inline></script></head><body><a class="skip-link" href="#main-content">跳到主要内容</a><slot /><ContactDialog /><script is:inline>
+<!doctype html><html lang="zh-CN"><head><meta charset="UTF-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><meta name="theme-color" content="#1473E6" /><meta name="color-scheme" content="light" /><title>{metaTitle}</title><meta name="description" content={metaDescription} /><meta name="keywords" content={metaKeywords} /><meta name="robots" content={noindex ? "noindex,nofollow" : "index,follow,max-image-preview:large,max-snippet:-1,max-video-preview:-1"} /><link rel="canonical" href={canonical} />{prevUrl && <link rel="prev" href={prevUrl} />}{nextUrl && <link rel="next" href={nextUrl} />}<link rel="icon" href="/favicon.png" type="image/png" sizes="512x512" /><link rel="apple-touch-icon" href="/favicon.png" /><link rel="manifest" href="/site.webmanifest" /><link rel="alternate" hreflang="zh-CN" href={canonical} /><link rel="alternate" hreflang="x-default" href={canonical} /><meta property="og:type" content={ogType} /><meta property="og:title" content={metaTitle} /><meta property="og:description" content={metaDescription} /><meta property="og:url" content={canonical} /><meta property="og:image" content={ogImage} /><meta property="og:image:alt" content={imageAlt} /><meta property="og:site_name" content={site.brand.name} /><meta property="og:locale" content="zh_CN" />{publishedTime && <meta property="article:published_time" content={publishedTime} />}{modifiedTime && <meta property="article:modified_time" content={modifiedTime} />}{articleSection && <meta property="article:section" content={articleSection} />}{articleAuthor && <meta property="article:author" content={articleAuthor} />}<meta name="twitter:card" content="summary_large_image" /><meta name="twitter:title" content={metaTitle} /><meta name="twitter:description" content={metaDescription} /><meta name="twitter:image" content={ogImage} /><script type="application/ld+json" set:html={serializedLd} is:inline></script></head><body><a class="skip-link" href="#main-content">跳到主要内容</a><slot /><ContactDialog /><script is:inline>
 const header=document.querySelector('[data-header]');const syncHeader=()=>header?.classList.toggle('is-scrolled',scrollY>12);addEventListener('scroll',syncHeader,{passive:true});syncHeader();const observer='IntersectionObserver'in window?new IntersectionObserver(entries=>entries.forEach(entry=>{if(entry.isIntersecting){entry.target.classList.add('is-visible');observer.unobserve(entry.target)}}),{threshold:.08}):null;document.querySelectorAll('[data-reveal]').forEach(el=>observer?observer.observe(el):el.classList.add('is-visible'));document.querySelectorAll('[data-mobile-nav] a').forEach(link=>link.addEventListener('click',()=>link.closest('details')?.removeAttribute('open')));const dialog=document.querySelector('[data-contact-dialog]');const teacherDialog=document.querySelector('[data-teacher-dialog]');const form=dialog?.querySelector('[data-consultation-form]');const copyWechat=teacherDialog?.querySelector('[data-copy-teacher-wechat]');const resetConsultation=()=>{form?.reset();const error=dialog?.querySelector('[data-consultation-error]');if(error)error.textContent=''};document.addEventListener('click',event=>{const trigger=event.target.closest('[data-open-contact]');if(!dialog||!trigger)return;event.preventDefault();resetConsultation();dialog.showModal();dialog.querySelector('#consultation-phone')?.focus()});dialog?.querySelector('[data-contact-dialog-close]')?.addEventListener('click',()=>dialog.close());teacherDialog?.querySelector('[data-teacher-dialog-close]')?.addEventListener('click',()=>teacherDialog.close());[dialog,teacherDialog].forEach(item=>item?.addEventListener('click',event=>{if(event.target===item)item.close()}));copyWechat?.addEventListener('click',async()=>{const value=teacherDialog.querySelector('[data-teacher-wechat]').textContent.trim();if(!value)return;try{await navigator.clipboard.writeText(value);copyWechat.textContent='已复制';setTimeout(()=>{copyWechat.textContent='复制'},1600)}catch{copyWechat.textContent='复制失败';setTimeout(()=>{copyWechat.textContent='复制'},1600)}});form?.addEventListener('submit',async event=>{event.preventDefault();const phone=String(new FormData(form).get('phone')||'').replace(/\s+/g,'');const error=dialog.querySelector('[data-consultation-error]');const submit=form.querySelector('button[type="submit"]');error.textContent='';if(!/^1[3-9]\d{9}$/.test(phone)){error.textContent='请输入正确的 11 位手机号';return}submit.disabled=true;submit.textContent='正在领取…';try{const response=await fetch('/api/cms/consultations/claim',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({phone,source:'免费领取学情分析',page:location.href})});const result=await response.json();if(!response.ok)throw new Error(result.error||'提交失败，请稍后重试');teacherDialog.querySelector('[data-teacher-name]').textContent=result.teacher.name;teacherDialog.querySelector('[data-teacher-title]').textContent=result.teacher.title;teacherDialog.querySelector('[data-teacher-qr]').src=result.teacher.qrCodeUrl;teacherDialog.querySelector('[data-teacher-wechat]').textContent=result.teacher.wechat||'';teacherDialog.querySelector('[data-teacher-wechat-wrap]').classList.toggle('hidden',!result.teacher.wechat);copyWechat.textContent='复制';dialog.close();teacherDialog.showModal()}catch(requestError){error.textContent=requestError.message}finally{submit.disabled=false;submit.textContent='立即领取'}});
  </script></body></html>
--- a/src/lib/article-store.ts
+++ b/src/lib/article-store.ts
@@ -12,6 +12,7 @@ export const ARTICLES_DIR = DATA_ROOT ? path.join(DATA_ROOT, "articles") : path.
 export const PUBLISHED_DIR = DATA_ROOT ? path.join(DATA_ROOT, "published") : path.join(ROOT, "src", "content", "published");
 export const CATEGORIES_FILE = DATA_ROOT ? path.join(DATA_ROOT, "categories.json") : path.join(ROOT, "src", "content", "categories.json");
 export const UPLOADS_DIR = DATA_ROOT ? path.join(DATA_ROOT, "uploads") : path.join(ROOT, "public", "uploads");
+const DATA_SEED_MARKER = DATA_ROOT ? path.join(DATA_ROOT, ".content-initialized") : null;
 const DEFAULT_CATEGORIES = ["学情指南", "学习方法", "家长课堂", "服务说明"];
 const DEFAULT_AUTHOR = "启优学教研中心";
@@ -33,11 +34,14 @@ export interface StoredArticle {
  category: string;
  author: string;
  excerpt: string;
+  readingMinutes: number;
+  featured: boolean;
  status: "draft" | "published";
  body: string;
 }
+type StoredArticleMetadata = Omit<StoredArticle, "body">;
-export interface Article {
+export interface ArticleMetadata {
  id: string;
  data: {
    title: string;
@@ -47,11 +51,16 @@ export interface Article {
    category: string;
    author: string;
    excerpt: string;
+    readingMinutes: number;
+    featured: boolean;
    status: "published";
  };
-  body: string;
 }
+export type Article = ArticleMetadata;
+export interface PublishedArticleSource extends ArticleMetadata { body: string; }
+export interface PublishedArticleDetail extends PublishedArticleSource { html: string; }
 export interface CategoryStat {
  name: string;
  count: number;
@@ -102,6 +111,8 @@ function serialize(data: StoredArticle, body: string): string {
    `category: ${quote(data.category)}`,
    `author: ${quote(data.author || DEFAULT_AUTHOR)}`,
    `excerpt: ${quote(data.excerpt)}`,
+    `readingMinutes: ${Math.max(1, Math.round(Number(data.readingMinutes) || 1))}`,
+    `featured: ${Boolean(data.featured)}`,
    `status: ${quote(data.status || "draft")}`,
    "---",
    "",
@@ -132,18 +143,23 @@ async function ensureStore(): Promise<void> {
    fs.mkdir(PUBLISHED_DIR, { recursive: true }),
    fs.mkdir(UPLOADS_DIR, { recursive: true }),
  ]);
-  if (DATA_ROOT) {
+  if (DATA_ROOT && DATA_SEED_MARKER && !await fileExists(DATA_SEED_MARKER)) {
    const seedDirectory = async (source: string, target: string) => {
-      const current = await fs.readdir(target);
-      if (current.some((file) => file.endsWith(".md"))) return;
      const seeds = await fs.readdir(source).catch(() => [] as string[]);
-      await Promise.all(seeds.filter((file) => file.endsWith(".md")).map((file) => fs.copyFile(path.join(source, file), path.join(target, file))));
+      await Promise.all(seeds.filter((file) => file.endsWith(".md")).map(async (file) => {
+        await writeAtomic(path.join(target, file), await fs.readFile(path.join(source, file)));
+      }));
    };
+    const [workingFiles, publishedFiles] = await Promise.all([fs.readdir(ARTICLES_DIR), fs.readdir(PUBLISHED_DIR)]);
+    const hasExistingContent = [...workingFiles, ...publishedFiles].some((file) => file.endsWith(".md"));
+    if (!hasExistingContent) {
      await Promise.all([
        seedDirectory(SOURCE_ARTICLES_DIR, ARTICLES_DIR),
        seedDirectory(SOURCE_PUBLISHED_DIR, PUBLISHED_DIR),
      ]);
    }
+    await writeAtomic(DATA_SEED_MARKER, `${new Date().toISOString()}\n`);
+  }
  if (!await fileExists(CATEGORIES_FILE)) {
    await writeAtomic(CATEGORIES_FILE, `${JSON.stringify(DEFAULT_CATEGORIES, null, 2)}\n`);
  }
@@ -193,11 +209,56 @@ export async function readArticleFrom(directory: string, slug: string): Promise<
    category: String(data.category || ""),
    author: String(data.author || DEFAULT_AUTHOR),
    excerpt: String(data.excerpt || ""),
-    status: data.status === "draft" ? "draft" : "published",
+    readingMinutes: Math.max(1, Math.round(Number(data.readingMinutes) || 1)),
+    featured: data.featured === true,
+    status: data.status === "published" ? "published" : "draft",
    body: content.trim(),
  };
 }
+async function readFrontmatter(file: string): Promise<string | null> {
+  const handle = await fs.open(file, "r");
+  const chunkSize = 4096;
+  const maxFrontmatterBytes = 64 * 1024;
+  const chunks: Buffer[] = [];
+  let raw = "";
+  let position = 0;
+  try {
+    while (position < maxFrontmatterBytes) {
+      const buffer = Buffer.alloc(Math.min(chunkSize, maxFrontmatterBytes - position));
+      const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
+      if (!bytesRead) break;
+      chunks.push(buffer.subarray(0, bytesRead));
+      raw = Buffer.concat(chunks).toString("utf8");
+      const closing = raw.indexOf("\n---", 4);
+      if (raw.startsWith("---") && closing >= 0) return `${raw.slice(0, closing + 4)}\n`;
+      position += bytesRead;
+    }
+    return null;
+  } finally {
+    await handle.close();
+  }
+}
+async function readArticleMetadataFrom(directory: string, slug: string): Promise<StoredArticleMetadata | null> {
+  const frontmatter = await readFrontmatter(path.join(directory, `${slug}.md`));
+  if (!frontmatter) return null;
+  const { data } = matter(frontmatter);
+  if (data.status !== "published") return null;
+  return {
+    slug,
+    title: String(data.title || ""),
+    date: fmtDate(data.date),
+    updated: fmtDate(data.updated || data.date),
+    category: String(data.category || ""),
+    author: String(data.author || DEFAULT_AUTHOR),
+    excerpt: String(data.excerpt || ""),
+    readingMinutes: Math.max(1, Math.round(Number(data.readingMinutes) || 1)),
+    featured: data.featured === true,
+    status: "published",
+  };
+}
 export const readWorkingArticle = (slug: string) => readArticleFrom(ARTICLES_DIR, slug);
 async function markdownFiles(directory: string): Promise<string[]> {
@@ -235,7 +296,7 @@ export async function createContentSnapshot(): Promise<ContentSnapshot> {
 }
 const sameArticleContent = (left: StoredArticle, right: StoredArticle): boolean =>
-  ["slug", "title", "date", "category", "author", "excerpt", "body"]
+  ["slug", "title", "date", "category", "author", "excerpt", "readingMinutes", "featured", "body"]
    .every((key) => String(left[key as keyof StoredArticle] ?? "") === String(right[key as keyof StoredArticle] ?? ""));
 export async function getPublishStatus(article: StoredArticle): Promise<PublishStatus> {
@@ -269,6 +330,8 @@ export async function writeArticle(slug: string, input: Record<string, unknown>,
    category: categories.includes(String(input.category)) ? String(input.category) : categories[0],
    author: DEFAULT_AUTHOR,
    excerpt: autoExcerpt(body, String(input.title || "")),
+    readingMinutes: Math.max(1, Math.ceil(body.replace(/\s+/g, "").length / 400)),
+    featured: input.featured === true || existing?.featured === true,
    status: "draft",
    body,
  };
@@ -310,11 +373,13 @@ export async function publishArticle(slug: string): Promise<void> {
  const previousDraft = await fs.readFile(draftFile, "utf8");
  const previousLive = await fileExists(liveFile) ? await fs.readFile(liveFile, "utf8") : null;
  try {
-    await writeAtomic(liveFile, text);
    await writeAtomic(draftFile, text);
+    await writeAtomic(liveFile, text);
+    clearPublicArticleCaches(slug);
  } catch (error) {
    await restoreFile(draftFile, previousDraft);
    await restoreFile(liveFile, previousLive);
+    clearPublicArticleCaches(slug);
    throw error;
  }
 }
@@ -328,9 +393,11 @@ export async function unpublishArticle(slug: string): Promise<void> {
  try {
    await writeAtomic(draftFile, serialize({ ...article, status: "draft" }, article.body));
    await fs.unlink(liveFile);
+    clearPublicArticleCaches(slug);
  } catch (error) {
    await restoreFile(draftFile, previousDraft);
    await restoreFile(liveFile, previousLive);
+    clearPublicArticleCaches(slug);
    throw error;
  }
 }
@@ -342,8 +409,10 @@ export async function deleteArticle(slug: string): Promise<void> {
  if (!backups.length) throw new StoreError("文章不存在", 404);
  try {
    for (const { file } of backups) await fs.unlink(file);
+    clearPublicArticleCaches(slug);
  } catch (error) {
    for (const { file, content } of backups) await writeAtomic(file, content);
+    clearPublicArticleCaches(slug);
    throw error;
  }
 }
@@ -352,7 +421,7 @@ export async function discardDraft(slug: string): Promise<{ removed: boolean; pu
  const liveFile = path.join(PUBLISHED_DIR, `${slug}.md`);
  const draftFile = path.join(ARTICLES_DIR, `${slug}.md`);
  if (await fileExists(liveFile)) {
-    await fs.copyFile(liveFile, draftFile);
+    await writeAtomic(draftFile, await fs.readFile(liveFile));
    return { removed: false, publishStatus: "live" };
  }
  await fs.unlink(draftFile);
@@ -397,9 +466,11 @@ async function updateCategoryArticles(current: string, replacement: string, next
      await writeAtomic(item.file, serialize(updated, updated.body));
    }
    await saveCategories(nextCategories);
+    clearPublicArticleCaches();
  } catch (error) {
    for (const item of affected) await writeAtomic(item.file, item.raw);
    await writeAtomic(CATEGORIES_FILE, previousCategories);
+    clearPublicArticleCaches();
    throw error;
  }
 }
@@ -432,9 +503,22 @@ export async function removeCategory(value: unknown, replacementValue: unknown):
  return next;
 }
-export async function getPublishedArticles(): Promise<Article[]> {
+interface FileSignature { mtimeMs: number; size: number; }
-  const items = await Promise.all((await markdownFiles(PUBLISHED_DIR)).map(async (file) => {
+interface CacheEntry<T> { signature: FileSignature; value: T; }
-    const article = await readArticleFrom(PUBLISHED_DIR, file.replace(/\.md$/, ""));
+const MAX_PUBLIC_CACHE_ENTRIES = 256;
+const metadataCache = new Map<string, CacheEntry<ArticleMetadata>>();
+const sourceCache = new Map<string, CacheEntry<PublishedArticleSource>>();
+const detailCache = new Map<string, CacheEntry<PublishedArticleDetail>>();
+let markdownRenderCount = 0;
+const sameSignature = (left: FileSignature, right: FileSignature) => left.mtimeMs === right.mtimeMs && left.size === right.size;
+function setLimitedCache<T>(cache: Map<string, CacheEntry<T>>, key: string, value: CacheEntry<T>): void {
+  cache.delete(key);
+  cache.set(key, value);
+  while (cache.size > MAX_PUBLIC_CACHE_ENTRIES) cache.delete(cache.keys().next().value as string);
+}
+function publicMetadata(article: StoredArticleMetadata): ArticleMetadata {
  return {
    id: article.slug,
    data: {
@@ -445,39 +529,89 @@ export async function getPublishedArticles(): Promise<Article[]> {
      category: article.category,
      author: article.author,
      excerpt: article.excerpt,
-        status: "published" as const,
+      readingMinutes: article.readingMinutes,
+      featured: article.featured,
+      status: "published",
    },
-      body: article.body,
  };
-  }));
-  return items.sort((a, b) => b.data.date.valueOf() - a.data.date.valueOf());
 }
-export async function getPublishedArticle(slug: string): Promise<(Article & { html: string }) | null> {
+async function publishedFileState(slug: string): Promise<{ file: string; signature: FileSignature } | null> {
  if (!safeSlug(slug)) return null;
+  const file = path.join(PUBLISHED_DIR, `${slug}.md`);
  try {
-    const article = await readArticleFrom(PUBLISHED_DIR, slug);
+    const stat = await fs.stat(file);
-    return {
+    return { file, signature: { mtimeMs: stat.mtimeMs, size: stat.size } };
-      id: article.slug,
-      data: {
-        title: article.title,
-        slug: article.slug,
-        date: new Date(article.date),
-        updated: new Date(article.updated),
-        category: article.category,
-        author: article.author,
-        excerpt: article.excerpt,
-        status: "published",
-      },
-      body: article.body,
-      html: await marked.parse(article.body),
-    };
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
    throw error;
  }
 }
+export async function getPublishedArticleMetadata(slug: string): Promise<ArticleMetadata | null> {
+  const state = await publishedFileState(slug);
+  if (!state) return null;
+  const cached = metadataCache.get(slug);
+  if (cached && sameSignature(cached.signature, state.signature)) return cached.value;
+  const article = await readArticleMetadataFrom(PUBLISHED_DIR, slug);
+  if (!article) return null;
+  const value = publicMetadata(article);
+  setLimitedCache(metadataCache, slug, { signature: state.signature, value });
+  return value;
+}
+export async function getPublishedArticles(): Promise<ArticleMetadata[]> {
+  const files = await markdownFiles(PUBLISHED_DIR);
+  const items = (await Promise.all(files.map((file) => getPublishedArticleMetadata(file.replace(/\.md$/, "")))))
+    .filter((item): item is ArticleMetadata => item !== null);
+  return items.sort((a, b) => b.data.date.valueOf() - a.data.date.valueOf());
+}
+export async function getPublishedArticleSource(slug: string): Promise<PublishedArticleSource | null> {
+  const state = await publishedFileState(slug);
+  if (!state) return null;
+  const cached = sourceCache.get(slug);
+  if (cached && sameSignature(cached.signature, state.signature)) return cached.value;
+  const article = await readArticleFrom(PUBLISHED_DIR, slug);
+  if (article.status !== "published") return null;
+  const value = { ...publicMetadata(article), body: article.body };
+  setLimitedCache(sourceCache, slug, { signature: state.signature, value });
+  return value;
+}
+export async function getPublishedArticle(slug: string): Promise<PublishedArticleDetail | null> {
+  const state = await publishedFileState(slug);
+  if (!state) return null;
+  const cached = detailCache.get(slug);
+  if (cached && sameSignature(cached.signature, state.signature)) return cached.value;
+  const source = await getPublishedArticleSource(slug);
+  if (!source) return null;
+  markdownRenderCount += 1;
+  const value = { ...source, html: await marked.parse(source.body) };
+  setLimitedCache(detailCache, slug, { signature: state.signature, value });
+  return value;
+}
+export function clearPublicArticleCaches(slug?: string): void {
+  if (slug) {
+    metadataCache.delete(slug);
+    sourceCache.delete(slug);
+    detailCache.delete(slug);
+  } else {
+    metadataCache.clear();
+    sourceCache.clear();
+    detailCache.clear();
+  }
+}
+export function getArticleStoreDiagnostics(): { markdownRenderCount: number; metadataCacheSize: number; sourceCacheSize: number; detailCacheSize: number } {
+  return { markdownRenderCount, metadataCacheSize: metadataCache.size, sourceCacheSize: sourceCache.size, detailCacheSize: detailCache.size };
+}
+export function resetArticleStoreDiagnostics(): void {
+  markdownRenderCount = 0;
+}
 export async function saveUpload(dataUrl: unknown): Promise<string> {
  await ensureStore();
  const extensions: Record<string, string> = { "image/png": "png", "image/jpeg": "jpg", "image/webp": "webp", "image/gif": "gif" };

--- a/src/lib/cms-api.ts
+++ b/src/lib/cms-api.ts
@@ -3,7 +3,6 @@ import { marked } from "marked";
 import {
  StoreError,
  addCategory,
-  createContentSnapshot,
  deleteArticle,
  discardDraft,
  generateSlug,
@@ -36,7 +35,7 @@ import {
  updateConsultationTeacher,
  verifyTeacherCredentials,
 } from "./consultation-store";
-import { buildSiteAtomic, tryAcquireSiteBuildLock, withSiteBuildLock } from "../../scripts/site-build.mjs";
+import { ContentWriteLockBusyError, withContentWriteLock } from "./content-lock";
 const SECRET = process.env.CMS_SECRET || crypto.randomBytes(32).toString("hex");
 const API_KEY = process.env.CMS_API_KEY || "";
@@ -49,15 +48,6 @@ const loginAttempts = new Map<string, { count: number; first: number; blockedUnt
 type AuthContext =
  | { role: "admin"; id: "admin"; name: "管理员" }
  | { role: "customer_service" | "operator"; id: string; name: string };
-type BuildState = {
-  status: "idle" | "building" | "success" | "error";
-  ok: boolean | null;
-  log: string;
-  startedAt: string | null;
-  finishedAt: string | null;
-};
-let buildState: BuildState = { status: "idle", ok: null, log: "", startedAt: null, finishedAt: null };
 const json = (data: unknown, status = 200, headers?: HeadersInit) => Response.json(data, { status, headers });
 const safeEqual = (leftValue: unknown, rightValue: unknown): boolean => {
@@ -188,51 +178,6 @@ function requireSlug(value: string | undefined): string {
  return slug;
 }
-async function startContentBuild(change: () => Promise<void>): Promise<boolean> {
-  if (buildState.status === "building") return false;
-  const releaseLock = await tryAcquireSiteBuildLock();
-  if (!releaseLock) return false;
-  buildState = { status: "building", ok: null, log: "", startedAt: new Date().toISOString(), finishedAt: null };
-  void (async () => {
-    const snapshot = await createContentSnapshot();
-    try {
-      await change();
-      const log = await buildSiteAtomic();
-      buildState = { status: "success", ok: true, log, startedAt: buildState.startedAt, finishedAt: new Date().toISOString() };
-    } catch (error) {
-      let rollbackMessage = "";
-      try { await snapshot.restore(); } catch (rollbackError) {
-        rollbackMessage = `\n内容回滚失败：${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`;
-      }
-      const message = error instanceof Error ? error.message : String(error);
-      const log = typeof error === "object" && error && "log" in error ? String(error.log || "") : "";
-      buildState = {
-        status: "error",
-        ok: false,
-        log: `${log}${log ? "\n" : ""}${message}${rollbackMessage}`,
-        startedAt: buildState.startedAt,
-        finishedAt: new Date().toISOString(),
-      };
-    }
-  })().finally(releaseLock).catch((error) => {
-    buildState = {
-      status: "error",
-      ok: false,
-      log: error instanceof Error ? error.message : String(error),
-      startedAt: buildState.startedAt,
-      finishedAt: new Date().toISOString(),
-    };
-  });
-  return true;
-}
-async function startOrConflict(change: () => Promise<void>): Promise<Response> {
-  if (!await startContentBuild(change)) {
-    return json({ error: "网站正在部署或生成静态页面，本次操作未受理，请稍后重试" }, 409, { "Retry-After": "5" });
-  }
-  return json({ ok: true, status: "building" });
-}
 export async function handleCmsApi(request: Request, routeValue: string, clientAddress = "unknown"): Promise<Response> {
  const route = routeValue.replace(/^\/+|\/+$/g, "");
  const parts = route.split("/").filter(Boolean);
@@ -358,26 +303,26 @@ export async function handleCmsApi(request: Request, routeValue: string, clientA
      if (method === "GET") return json({ categories: await getCategoryNames(), stats: await getCategoryStats() });
      const body = await bodyOf(request);
      if (method === "POST") {
-        return startOrConflict(async () => { await addCategory(body.name); });
+        return json({ ok: true, categories: await withContentWriteLock("添加文章分类", () => addCategory(body.name)) }, 201);
      }
      if (method === "PATCH") {
-        return startOrConflict(async () => { await renameCategory(body.current, body.name); });
+        return json({ ok: true, categories: await withContentWriteLock("重命名文章分类", () => renameCategory(body.current, body.name)) });
      }
      if (method === "DELETE") {
-        return startOrConflict(async () => { await removeCategory(body.name, body.replacement); });
+        return json({ ok: true, categories: await withContentWriteLock("删除文章分类", () => removeCategory(body.name, body.replacement)) });
      }
    }
-    if (route === "build" && method === "GET") return json(buildState);
    if (route === "articles") {
      if (method === "GET") return json(await listWorkingArticles());
      if (method === "POST") {
        const body = await bodyOf(request);
        if (!String(body.title || "").trim()) throw new StoreError("请填写文章标题");
        if (!String(body.body || "").trim()) throw new StoreError("请填写文章正文");
+        const { slug, article } = await withContentWriteLock("新建文章草稿", async () => {
          const slug = await generateSlug(body.category);
-        const article = await withSiteBuildLock(() => writeArticle(slug, body, true));
+          return { slug, article: await writeArticle(slug, body, true) };
+        });
        return json({ ok: true, slug, publishStatus: await getPublishStatus(article) }, 201);
      }
    }
@@ -395,7 +340,7 @@ export async function handleCmsApi(request: Request, routeValue: string, clientA
          return url;
        });
        const title = String(body.title || "").trim() || converted.suggestedTitle;
-        const imported = await withSiteBuildLock(async () => {
+        const imported = await withContentWriteLock("导入文章草稿", async () => {
          const slug = await generateSlug(body.category);
          createdSlug = slug;
          const article = await writeArticle(slug, { title, category: body.category, body: converted.body }, true);
@@ -411,7 +356,7 @@ export async function handleCmsApi(request: Request, routeValue: string, clientA
        }, 201);
      } catch (error) {
        if (createdSlug) {
-          await withSiteBuildLock(() => discardDraft(createdSlug as string)).catch(() => {});
+          await withContentWriteLock("清理导入失败的文章草稿", () => discardDraft(createdSlug as string)).catch(() => {});
        }
        await Promise.allSettled(uploadedUrls.map((url) => removeUpload(url)));
        throw error;
@@ -421,13 +366,15 @@ export async function handleCmsApi(request: Request, routeValue: string, clientA
    if (parts[0] === "articles" && parts[1]) {
      const slug = requireSlug(parts[1]);
      if (parts.length === 3 && parts[2] === "draft" && method === "DELETE") {
-        return json({ ok: true, ...await withSiteBuildLock(() => discardDraft(slug)) });
+        return json({ ok: true, ...await withContentWriteLock("放弃文章草稿修改", () => discardDraft(slug)) });
      }
      if (parts.length === 3 && parts[2] === "publish" && method === "POST") {
-        return startOrConflict(async () => { await publishArticle(slug); });
+        await withContentWriteLock("发布文章", () => publishArticle(slug));
+        return json({ ok: true, publishStatus: "live", message: "发布成功，文章已上线" });
      }
      if (parts.length === 3 && parts[2] === "unpublish" && method === "POST") {
-        return startOrConflict(async () => { await unpublishArticle(slug); });
+        await withContentWriteLock("下架文章", () => unpublishArticle(slug));
+        return json({ ok: true, publishStatus: "new-draft", message: "文章已下架" });
      }
      if (parts.length === 2 && method === "GET") {
        const article = await readWorkingArticle(slug);
@@ -437,11 +384,12 @@ export async function handleCmsApi(request: Request, routeValue: string, clientA
        const body = await bodyOf(request);
        if (!String(body.title || "").trim()) throw new StoreError("请填写文章标题");
        if (!String(body.body || "").trim()) throw new StoreError("请填写文章正文");
-        const article = await withSiteBuildLock(() => writeArticle(slug, body));
+        const article = await withContentWriteLock("保存文章草稿", () => writeArticle(slug, body));
        return json({ ok: true, slug, publishStatus: await getPublishStatus(article) });
      }
      if (parts.length === 2 && method === "DELETE") {
-        return startOrConflict(async () => { await deleteArticle(slug); });
+        await withContentWriteLock("删除文章", () => deleteArticle(slug));
+        return json({ ok: true, message: "文章已删除" });
      }
    }
@@ -457,6 +405,7 @@ export async function handleCmsApi(request: Request, routeValue: string, clientA
    return json({ error: "接口不存在" }, 404);
  } catch (error) {
+    if (error instanceof ContentWriteLockBusyError) return json({ error: error.message, ...error.details }, 409, { "Retry-After": "1" });
    if (error instanceof StoreError) return json({ error: error.message, ...error.details }, error.status);
    if ((error as NodeJS.ErrnoException).code === "ENOENT") return json({ error: "文章不存在" }, 404);
    console.error(error);

--- a/src/lib/content-lock.ts
+++ b/src/lib/content-lock.ts
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+const ROOT = process.cwd();
+const DATA_ROOT = path.resolve(process.env.CMS_DATA_DIR || path.join(ROOT, ".runtime", "cms-data"));
+export const CONTENT_LOCK_FILE = path.resolve(process.env.CMS_CONTENT_LOCK || path.join(DATA_ROOT, ".content-write.lock"));
+const RECOVERY_LOCK_FILE = `${CONTENT_LOCK_FILE}.recovery`;
+const parsedStaleMs = Number(process.env.CMS_CONTENT_LOCK_STALE_MS || 15 * 60 * 1000);
+const STALE_MS = Number.isFinite(parsedStaleMs) && parsedStaleMs >= 30_000 ? parsedStaleMs : 15 * 60 * 1000;
+interface LockRecord {
+  token: string;
+  pid: number;
+  hostname: string;
+  createdAt: string;
+  operation: string;
+}
+export class ContentWriteLockBusyError extends Error {
+  status = 409;
+  details = { retryAfter: 1 };
+  constructor(operation?: string) {
+    super(operation ? `另一项内容操作正在进行（${operation}），请稍后重试` : "另一项内容操作正在进行，请稍后重试");
+    this.name = "ContentWriteLockBusyError";
+  }
+}
+function processIsAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+async function readLock(): Promise<LockRecord | null> {
+  try {
+    const parsed = JSON.parse(await fs.readFile(CONTENT_LOCK_FILE, "utf8")) as Partial<LockRecord>;
+    if (!parsed.token || !parsed.createdAt) return null;
+    return parsed as LockRecord;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    return null;
+  }
+}
+function isStale(lock: LockRecord | null): boolean {
+  if (!lock) return false;
+  const age = Date.now() - new Date(lock.createdAt).valueOf();
+  if (!Number.isFinite(age) || age > STALE_MS) return true;
+  return lock.hostname === os.hostname() && !processIsAlive(Number(lock.pid));
+}
+async function unreadableLockIsStale(): Promise<boolean> {
+  try {
+    const stat = await fs.stat(CONTENT_LOCK_FILE);
+    return Date.now() - stat.mtimeMs > STALE_MS;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "ENOENT";
+  }
+}
+async function recoverStaleLock(): Promise<boolean> {
+  let recoveryHandle: fs.FileHandle | null = null;
+  try {
+    recoveryHandle = await fs.open(RECOVERY_LOCK_FILE, "wx");
+    const before = await readLock();
+    if (before ? !isStale(before) : !await unreadableLockIsStale()) return false;
+    const current = await readLock();
+    const currentIsStale = current ? isStale(current) : await unreadableLockIsStale();
+    if ((before?.token || null) !== (current?.token || null) || !currentIsStale) return false;
+    await fs.unlink(CONTENT_LOCK_FILE).catch((error: NodeJS.ErrnoException) => {
+      if (error.code !== "ENOENT") throw error;
+    });
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") return false;
+    throw error;
+  } finally {
+    if (recoveryHandle) {
+      await recoveryHandle.close().catch(() => {});
+      await fs.unlink(RECOVERY_LOCK_FILE).catch(() => {});
+    }
+  }
+}
+async function acquireContentWriteLock(operation: string): Promise<() => Promise<void>> {
+  await fs.mkdir(path.dirname(CONTENT_LOCK_FILE), { recursive: true });
+  const record: LockRecord = {
+    token: crypto.randomBytes(16).toString("hex"),
+    pid: process.pid,
+    hostname: os.hostname(),
+    createdAt: new Date().toISOString(),
+    operation,
+  };
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const handle = await fs.open(CONTENT_LOCK_FILE, "wx");
+      await handle.writeFile(`${JSON.stringify(record)}\n`);
+      await handle.close();
+      return async () => {
+        const current = await readLock();
+        if (current?.token === record.token) {
+          await fs.unlink(CONTENT_LOCK_FILE).catch((error: NodeJS.ErrnoException) => {
+            if (error.code !== "ENOENT") throw error;
+          });
+        }
+      };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      if (attempt === 0 && await recoverStaleLock()) continue;
+      const current = await readLock();
+      throw new ContentWriteLockBusyError(current?.operation);
+    }
+  }
+  throw new ContentWriteLockBusyError();
+}
+export async function withContentWriteLock<T>(operation: string, task: () => Promise<T>): Promise<T> {
+  const release = await acquireContentWriteLock(operation);
+  try {
+    return await task();
+  } finally {
+    await release();
+  }
+}
--- a/src/lib/http-cache.ts
+++ b/src/lib/http-cache.ts
+import crypto from "node:crypto";
+export function etagOf(content: string): string {
+  return `"${crypto.createHash("sha256").update(content).digest("base64url")}"`;
+}
+export function conditionalTextResponse(request: Request, content: string, contentType: string): Response {
+  const etag = etagOf(content);
+  const headers = {
+    "Cache-Control": "public, max-age=60, must-revalidate",
+    "Content-Type": contentType,
+    ETag: etag,
+  };
+  if (request.headers.get("if-none-match")?.split(",").map((value) => value.trim()).includes(etag)) {
+    return new Response(null, { status: 304, headers });
+  }
+  return new Response(content, { headers });
+}
--- a/src/pages/404.astro
+++ b/src/pages/404.astro
 ---
-import Base from "../layouts/Base.astro"; import Header from "../components/Header.astro"; import Footer from "../components/Footer.astro";
+import NotFoundPage from "../components/NotFoundPage.astro";
 ---
-<Base title="页面未找到｜启优学" description="你访问的页面不存在。" noindex><Header /><main id="main-content"><section class="not-found"><div class="container" data-reveal><span>404</span><h1>这一页暂时找不到了</h1><p>可以返回首页，继续了解启优学在线一对一课程与教学服务。</p><a class="button" href="/">返回首页</a></div></section></main><Footer /></Base>
+<NotFoundPage />
--- a/src/pages/admin/index.astro
+++ b/src/pages/admin/index.astro
@@ -132,7 +132,10 @@
  <div id="teacher-modal" class="modal hidden">
    <div class="modal-card teacher-card">
-      <div class="modal-head"><div><strong id="teacher-modal-title">添加后台账号</strong><small id="teacher-modal-description">按职责分配客服或运营权限</small></div><button id="close-teacher-modal" class="ghost small" type="button">关闭</button></div>
+      <div class="modal-head teacher-modal-head">
+        <div class="teacher-modal-heading"><strong id="teacher-modal-title">添加后台账号</strong><small id="teacher-modal-description">按职责分配客服或运营权限</small></div>
+        <div class="modal-head-actions"><button id="cancel-teacher" class="ghost small" type="button">取消</button><button id="save-teacher" class="primary small" type="submit" form="teacher-form">保存账号</button></div>
+      </div>
      <form id="teacher-form" class="teacher-form">
        <input id="teacher-id" type="hidden" />
        <div class="form-grid">
@@ -150,7 +153,6 @@
        </label>
        <label class="switch-row"><input id="teacher-enabled" type="checkbox" checked /><span id="teacher-enabled-label">启用并参与轮询分配</span></label>
        <p id="teacher-error" class="error"></p>
-        <div class="password-actions"><button id="cancel-teacher" class="ghost" type="button">取消</button><button class="primary" type="submit">保存账号</button></div>
      </form>
    </div>
  </div>
@@ -206,12 +208,6 @@
      </form>
    </div>
  </div>
-  <div id="build-modal" class="modal hidden">
-    <div class="modal-card build-card">
-      <div><strong id="build-title">正在处理</strong><button id="close-modal" class="ghost small hidden" type="button">关闭</button></div>
-      <pre id="build-log">系统正在更新官网，请稍候。</pre>
-    </div>
-  </div>
  <script is:inline src="/admin/app.js"></script>
 </body>
 </html>
--- a/src/pages/article-sitemap.xml.ts
+++ b/src/pages/article-sitemap.xml.ts
+import type { APIRoute } from "astro";
+import { getCategoryNames, getCategories, getPublishedArticles, lastPageOf } from "../lib/articles";
+import { conditionalTextResponse } from "../lib/http-cache";
+export const prerender = false;
+const escapeXml = (value: string) => value
+  .replaceAll("&", "&amp;")
+  .replaceAll("<", "&lt;")
+  .replaceAll(">", "&gt;")
+  .replaceAll('"', "&quot;")
+  .replaceAll("'", "&apos;");
+export const GET: APIRoute = async ({ request, site }) => {
+  const origin = site ?? new URL("https://qiyouxueedu.com");
+  const articles = await getPublishedArticles();
+  const categories = getCategories(articles, await getCategoryNames());
+  const paths = new Set<string>(["/articles/"]);
+  for (let page = 2; page <= lastPageOf(articles.length); page += 1) paths.add(`/articles/page/${page}/`);
+  for (const article of articles) paths.add(`/articles/${article.id}/`);
+  for (const category of categories) {
+    paths.add(`/articles/topic/${category.slug}/`);
+    for (let page = 2; page <= lastPageOf(category.count); page += 1) paths.add(`/articles/topic/${category.slug}/page/${page}/`);
+  }
+  const rows = [...paths].map((pathname) => `  <url><loc>${escapeXml(new URL(pathname, origin).href)}</loc></url>`);
+  const xml = [`<?xml version="1.0" encoding="UTF-8"?>`, `<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">`, ...rows, `</urlset>`, ""].join("\n");
+  return conditionalTextResponse(request, xml, "application/xml; charset=utf-8");
+};
--- a/src/pages/articles/[slug].astro
+++ b/src/pages/articles/[slug].astro
 ---
-import Base from "../../layouts/Base.astro"; import Header from "../../components/Header.astro"; import Footer from "../../components/Footer.astro"; import { site } from "../../data/site"; import { getPublishedArticle, getPublishedArticles } from "../../lib/article-store"; import { fmtDate } from "../../lib/articles";
+import ArticleDetailView from "../../components/ArticleDetailView.astro";
-type ArticleDetail = NonNullable<Awaited<ReturnType<typeof getPublishedArticle>>>;
+import NotFoundPage from "../../components/NotFoundPage.astro";
-export async function getStaticPaths() { const articles = await getPublishedArticles(); return Promise.all(articles.map(async (article) => ({ params: { slug: article.id }, props: { entry: await getPublishedArticle(article.id) } }))); }
+import { getPublishedArticle, safeSlug } from "../../lib/article-store";
-const { entry } = Astro.props as { entry: ArticleDetail }; const article = entry.data; const date = fmtDate(article.date); const title = `${article.title}｜学习资讯｜${site.brand.name}`; const pageUrl = new URL(`/articles/${entry.id}/`, Astro.site).href;
-const modified = fmtDate(article.updated || article.date);
+export const prerender = false;
-const keywords = [article.category, article.title, "学习方法", "在线一对一", site.brand.name];
-const jsonLd = [{ "@context": "https://schema.org", "@type": "Article", headline: article.title, description: article.excerpt, datePublished: date, dateModified: modified, articleSection: article.category, inLanguage: "zh-CN", author: { "@type": "Organization", name: article.author }, publisher: { "@id": new URL("/#organization", Astro.site).href }, mainEntityOfPage: { "@type": "WebPage", "@id": `${pageUrl}#webpage` }, url: pageUrl }, { "@context": "https://schema.org", "@type": "BreadcrumbList", itemListElement: [{ "@type": "ListItem", position: 1, name: "首页", item: Astro.site?.href }, { "@type": "ListItem", position: 2, name: "学习资讯", item: new URL("/articles/", Astro.site).href }, { "@type": "ListItem", position: 3, name: article.title, item: pageUrl }] }];
+const slug = safeSlug(Astro.params.slug);
+const entry = slug ? await getPublishedArticle(slug) : null;
+if (!entry) Astro.response.status = 404;
+else Astro.response.headers.set("Cache-Control", "public, max-age=0, must-revalidate");
 ---
-<Base {title} description={article.excerpt} {keywords} ogType="article" publishedTime={date} modifiedTime={modified} articleSection={article.category} articleAuthor={article.author} {jsonLd}><Header /><main id="main-content" class="article-detail-page"><article><header class="article-detail-head"><div class="container article-detail-head__inner"><div class="breadcrumb"><a href="/">首页</a> / <a href="/articles/">学习资讯</a> / {article.category}</div><span class="article-detail-category">{article.category}</span><h1>{article.title}</h1><p>{article.excerpt}</p><div class="article-detail-meta"><time datetime={date}>{date}</time><span>{article.author}</span></div></div></header><div class="container article-detail-layout"><aside><a href="/articles/">← 返回学习资讯</a><p>分享学情判断、学习方法、阶段复习与在线一对一服务说明。</p></aside><div class="article-prose" set:html={entry.html}></div></div></article></main><Footer /></Base>
+{entry ? <ArticleDetailView {entry} /> : <NotFoundPage />}
--- a/src/pages/articles/index.astro
+++ b/src/pages/articles/index.astro
@@ -2,8 +2,11 @@
 import ArticlesView from "../../components/ArticlesView.astro";
 import { getPublishedArticles, getCategoryNames, getCategories, pageSlice, lastPageOf } from "../../lib/articles";
+export const prerender = false;
 const all = await getPublishedArticles();
 const categories = getCategories(all, await getCategoryNames());
 const items = pageSlice(all, 1);
+Astro.response.headers.set("Cache-Control", "public, max-age=0, must-revalidate");
 ---
 <ArticlesView items={items} categories={categories} totalCount={all.length} activeSlug={null} activeName={null} currentPage={1} lastPage={lastPageOf(all.length)} basePath="/articles" />
--- a/src/pages/articles/page/[page].astro
+++ b/src/pages/articles/page/[page].astro
 ---
 import ArticlesView from "../../../components/ArticlesView.astro";
+import NotFoundPage from "../../../components/NotFoundPage.astro";
 import { getPublishedArticles, getCategoryNames, getCategories, pageSlice, lastPageOf } from "../../../lib/articles";
-export async function getStaticPaths() {
+export const prerender = false;
-  const articles = await getPublishedArticles();
-  return Array.from({ length: Math.max(0, lastPageOf(articles.length) - 1) }, (_, index) => ({
-    params: { page: String(index + 2) },
-  }));
-}
 const all = await getPublishedArticles();
-const page = Number(Astro.params.page);
+const pageValue = String(Astro.params.page || "");
+const page = /^\d+$/.test(pageValue) ? Number(pageValue) : 0;
+const lastPage = lastPageOf(all.length);
+const valid = Number.isSafeInteger(page) && page >= 2 && page <= lastPage;
+if (!valid) Astro.response.status = 404;
+else Astro.response.headers.set("Cache-Control", "public, max-age=0, must-revalidate");
+const categories = valid ? getCategories(all, await getCategoryNames()) : [];
 ---
-<ArticlesView items={pageSlice(all, page)} categories={getCategories(all, await getCategoryNames())} totalCount={all.length} activeSlug={null} activeName={null} currentPage={page} lastPage={lastPageOf(all.length)} basePath="/articles" />
+{valid
+  ? <ArticlesView items={pageSlice(all, page)} {categories} totalCount={all.length} activeSlug={null} activeName={null} currentPage={page} {lastPage} basePath="/articles" />
+  : <NotFoundPage />}
--- a/src/pages/articles/topic/[slug]/index.astro
+++ b/src/pages/articles/topic/[slug]/index.astro
 ---
 import ArticlesView from "../../../../components/ArticlesView.astro";
-import { categoryToSlug, getPublishedArticles, getCategoryNames, getCategories, slugToCategory, pageSlice, lastPageOf } from "../../../../lib/articles";
+import NotFoundPage from "../../../../components/NotFoundPage.astro";
+import { getPublishedArticles, getCategoryNames, getCategories, slugToCategory, pageSlice, lastPageOf } from "../../../../lib/articles";
-export async function getStaticPaths() {
+export const prerender = false;
-  return (await getCategoryNames()).map((categoryName) => ({
-    params: { slug: categoryToSlug(categoryName) },
-    props: { categoryName },
-  }));
-}
 const all = await getPublishedArticles();
-const categories = getCategories(all, await getCategoryNames());
+const categoryNames = await getCategoryNames();
-const categoryName = String(Astro.props.categoryName || slugToCategory(Astro.params.slug!, categories.map((item) => item.name)) || "");
+const categories = getCategories(all, categoryNames);
-const filtered = all.filter((item) => item.data.category === categoryName);
+const routeSlug = String(Astro.params.slug || "");
+const categoryName = slugToCategory(routeSlug, categoryNames);
+const valid = Boolean(categoryName);
+const filtered = valid ? all.filter((item) => item.data.category === categoryName) : [];
+if (!valid) Astro.response.status = 404;
+else Astro.response.headers.set("Cache-Control", "public, max-age=0, must-revalidate");
 ---
-<ArticlesView items={pageSlice(filtered, 1)} categories={categories} totalCount={all.length} activeSlug={Astro.params.slug!} activeName={categoryName} currentPage={1} lastPage={lastPageOf(filtered.length)} basePath={`/articles/topic/${Astro.params.slug}`} />
+{valid
+  ? <ArticlesView items={pageSlice(filtered, 1)} {categories} totalCount={all.length} activeSlug={routeSlug} activeName={categoryName!} currentPage={1} lastPage={lastPageOf(filtered.length)} basePath={`/articles/topic/${routeSlug}`} />
+  : <NotFoundPage />}
--- a/src/pages/articles/topic/[slug]/page/[page].astro
+++ b/src/pages/articles/topic/[slug]/page/[page].astro
 ---
 import ArticlesView from "../../../../../components/ArticlesView.astro";
+import NotFoundPage from "../../../../../components/NotFoundPage.astro";
 import { getPublishedArticles, getCategoryNames, getCategories, slugToCategory, pageSlice, lastPageOf } from "../../../../../lib/articles";
-export async function getStaticPaths() {
+export const prerender = false;
-  const articles = await getPublishedArticles();
-  const categories = getCategories(articles, await getCategoryNames());
-  const paths: Array<{ params: { slug: string; page: string }; props: { categoryName: string } }> = [];
-  for (const category of categories) {
-    for (let page = 2; page <= lastPageOf(category.count); page += 1) {
-      paths.push({ params: { slug: category.slug, page: String(page) }, props: { categoryName: category.name } });
-    }
-  }
-  return paths;
-}
 const all = await getPublishedArticles();
-const categories = getCategories(all, await getCategoryNames());
+const categoryNames = await getCategoryNames();
-const categoryName = String(Astro.props.categoryName || slugToCategory(Astro.params.slug!, categories.map((item) => item.name)) || "");
+const categories = getCategories(all, categoryNames);
-const filtered = all.filter((item) => item.data.category === categoryName);
+const routeSlug = String(Astro.params.slug || "");
-const page = Number(Astro.params.page);
+const categoryName = slugToCategory(routeSlug, categoryNames);
+const filtered = categoryName ? all.filter((item) => item.data.category === categoryName) : [];
+const pageValue = String(Astro.params.page || "");
+const page = /^\d+$/.test(pageValue) ? Number(pageValue) : 0;
+const lastPage = lastPageOf(filtered.length);
+const valid = Boolean(categoryName) && Number.isSafeInteger(page) && page >= 2 && page <= lastPage;
+if (!valid) Astro.response.status = 404;
+else Astro.response.headers.set("Cache-Control", "public, max-age=0, must-revalidate");
 ---
-<ArticlesView items={pageSlice(filtered, page)} categories={categories} totalCount={all.length} activeSlug={Astro.params.slug!} activeName={categoryName} currentPage={page} lastPage={lastPageOf(filtered.length)} basePath={`/articles/topic/${Astro.params.slug}`} />
+{valid
+  ? <ArticlesView items={pageSlice(filtered, page)} {categories} totalCount={all.length} activeSlug={routeSlug} activeName={categoryName!} currentPage={page} {lastPage} basePath={`/articles/topic/${routeSlug}`} />
+  : <NotFoundPage />}
--- a/src/pages/llms-full.txt.ts
+++ b/src/pages/llms-full.txt.ts
 import type { APIRoute } from "astro";
 import { site } from "../data/site";
 import { getPublishedArticles } from "../lib/articles";
+import { getPublishedArticleSource } from "../lib/article-store";
+import { conditionalTextResponse } from "../lib/http-cache";
-export const prerender = true;
+export const prerender = false;
-export const GET: APIRoute = async ({ site: configuredSite }) => {
+export const GET: APIRoute = async ({ request, site: configuredSite }) => {
  const articles = await getPublishedArticles();
+  const details = (await Promise.all(articles.map((article) => getPublishedArticleSource(article.id))))
+    .filter((article): article is NonNullable<Awaited<ReturnType<typeof getPublishedArticleSource>>> => article !== null);
  const origin = configuredSite ?? new URL("https://qiyouxueedu.com");
  const url = (pathname: string) => new URL(pathname, origin).href;
  const lines = [
@@ -20,8 +24,8 @@ export const GET: APIRoute = async ({ site: configuredSite }) => {
    "## 教学服务能力", "", ...site.about.technologies.map((technology) => `- ${technology}`), "",
    "## 学习服务流程", "", ...site.workflow.map((step) => `- ${step.title}：${step.desc}`), "",
    "## 常见问题", "", `常见问题页面：${url("/faq/")}`, "", ...site.faq.flatMap((item) => [`### ${item.q}`, "", item.a, ""]),
-    "## 学习资讯全文", "", ...articles.flatMap((article) => [`### ${article.data.title}`, "", `页面：${url(`/articles/${article.id}/`)}`, `分类：${article.data.category}`, `作者：${article.data.author}`, `发布日期：${article.data.date.toISOString().slice(0, 10)}`, `更新时间：${article.data.updated.toISOString().slice(0, 10)}`, "", article.data.excerpt, "", article.body, ""]),
+    "## 学习资讯全文", "", ...details.flatMap((article) => [`### ${article.data.title}`, "", `页面：${url(`/articles/${article.id}/`)}`, `分类：${article.data.category}`, `作者：${article.data.author}`, `发布日期：${article.data.date.toISOString().slice(0, 10)}`, `更新时间：${article.data.updated.toISOString().slice(0, 10)}`, "", article.data.excerpt, "", article.body, ""]),
    "## 联系方式", "", `联系页面：${url("/contact/")}`, `咨询电话：${site.contact.phone}`, `联系邮箱：${site.contact.email}`, `公司地址：${site.contact.address}`, `内容矩阵：${site.contact.socials.join("、")}`, "",
  ];
-  return new Response(lines.join("\n"), { headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "public, max-age=3600" } });
+  return conditionalTextResponse(request, lines.join("\n"), "text/plain; charset=utf-8");
 };
--- a/src/pages/llms.txt.ts
+++ b/src/pages/llms.txt.ts
 import type { APIRoute } from "astro";
 import { site } from "../data/site";
 import { getPublishedArticles } from "../lib/articles";
+import { conditionalTextResponse } from "../lib/http-cache";
-export const prerender = true;
+export const prerender = false;
-export const GET: APIRoute = async ({ site: configuredSite }) => {
+export const GET: APIRoute = async ({ request, site: configuredSite }) => {
  const articles = await getPublishedArticles();
  const origin = configuredSite ?? new URL("https://qiyouxueedu.com");
  const url = (pathname: string) => new URL(pathname, origin).href;
@@ -31,5 +32,5 @@ export const GET: APIRoute = async ({ site: configuredSite }) => {
    `- [完整站点内容](${url("/llms-full.txt")})`,
    "", `咨询电话：${site.contact.phone}`, `联系邮箱：${site.contact.email}`, `公司地址：${site.contact.address}`,
  ];
-  return new Response(lines.join("\n"), { headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "public, max-age=3600" } });
+  return conditionalTextResponse(request, lines.join("\n"), "text/plain; charset=utf-8");
 };
--- a/src/styles/global.css
+++ b/src/styles/global.css
 :root{--brand-blue:#1473e6;--brand-blue-dark:#1473e6;--brand-accent:#1473e6;--brand-accent-soft:#eaf3ff;--bg-page:#fff;--bg-card:#fff;--bg-blue-soft:#f1f7ff;--bg-accent-soft:#f4f8ff;--text-primary:#1f2937;--text-secondary:#526070;--text-muted:#8491a3;--border:#d8e5f4;--divider:#e6edf6;--primary-hover:#0e61c8;--accent-hover:#0e61c8;--shadow-card:0 6px 24px rgba(20,115,230,.06);--shadow-hover:0 10px 32px rgba(20,115,230,.1);--container:1220px}
 *{box-sizing:border-box}html{scroll-behavior:smooth}body{margin:0;color:var(--text-primary);background:var(--bg-page);font-family:"Noto Sans SC Variable","Noto Sans SC",sans-serif;font-size:16px;line-height:1.75;-webkit-font-smoothing:antialiased}button,input,textarea{font-family:inherit}a{color:inherit;text-decoration:none}img,svg{display:block;max-width:100%}button{color:inherit}address{font-style:normal}h1,h2,h3,p,ul,ol,blockquote{margin-top:0}h1,h2,h3,strong{line-height:1.25}h1,h2,h3{font-family:inherit}::selection{color:#fff;background:var(--brand-blue)}.container{width:min(calc(100% - 48px),var(--container));margin-inline:auto}.section-pad{padding:104px 0}.section-white{background:#fff}.section-blue,.section-muted{background:var(--bg-blue-soft)}.section-accent{background:var(--bg-accent-soft)}.skip-link{position:fixed;z-index:1000;top:12px;left:12px;padding:10px 16px;color:#fff;background:var(--brand-blue);transform:translateY(-150%)}.skip-link:focus{transform:none}[data-reveal]{opacity:0;transform:translateY(18px);transition:opacity .65s ease,transform .65s ease}[data-reveal].is-visible{opacity:1;transform:none}
 .eyebrow{display:flex;align-items:center;gap:10px;margin-bottom:16px;color:var(--brand-blue);font-size:11px;font-weight:700;letter-spacing:.16em}.eyebrow>span{width:28px;height:2px;background:var(--brand-accent)}.eyebrow--light,.section-heading--light .eyebrow{color:#d8eefb}.section-heading{max-width:700px}.section-heading--center{margin-inline:auto;text-align:center}.section-heading--center .eyebrow{justify-content:center}.section-heading h2{margin-bottom:20px;font-size:clamp(34px,4vw,54px);font-weight:600;letter-spacing:-.025em}.section-heading>p{margin:0;color:var(--text-secondary);font-size:17px}.section-heading--light h2{color:#fff}.section-heading--light>p{color:#c9deea}.section-intro-row{display:flex;align-items:end;justify-content:space-between;gap:50px;margin-bottom:48px}.text-link{color:var(--brand-blue);font-weight:600;white-space:nowrap}.text-link span{color:var(--brand-accent)}.text-link--light{color:#fff}
-.button{display:inline-flex;align-items:center;justify-content:center;gap:12px;min-height:52px;padding:0 25px;border:1px solid var(--brand-blue);border-radius:9px;color:#fff;background:var(--brand-blue);font-size:14px;font-weight:600;letter-spacing:.02em;transition:background .2s,border-color .2s,transform .2s}.button:hover{border-color:var(--primary-hover);background:var(--primary-hover);transform:translateY(-2px)}.button--small{min-height:42px;padding:0 18px;font-size:13px}.button--accent{border-color:var(--brand-accent);color:var(--text-primary);background:var(--brand-accent)}.button--accent:hover{border-color:var(--accent-hover);background:var(--accent-hover)}.button--outline{color:var(--brand-blue);background:#fff}.button--outline:hover{color:#fff}.button--ghost{border-color:rgba(255,255,255,.55);background:transparent}.button--white{border-color:#fff;color:var(--brand-blue-dark);background:#fff}.hero__actions{display:flex;flex-wrap:wrap;gap:12px}
+.button{display:inline-flex;align-items:center;justify-content:center;gap:12px;min-height:52px;padding:0 25px;border:1px solid var(--brand-blue);border-radius:9px;color:#fff;background:var(--brand-blue);font-size:14px;font-weight:600;letter-spacing:.02em;transition:background .2s,border-color .2s,box-shadow .2s,color .2s,transform .2s}.button:hover{border-color:var(--primary-hover);background:var(--primary-hover);transform:translateY(-2px)}.button--small{min-height:42px;padding:0 18px;font-size:13px}.button--accent{border-color:var(--brand-accent);color:var(--text-primary);background:var(--brand-accent)}.button--accent:hover{border-color:var(--accent-hover);background:var(--accent-hover)}.button--outline{color:var(--brand-blue);background:#fff}.button--outline:hover{color:#fff}.button--ghost{border-color:rgba(255,255,255,.55);background:transparent}.button--white{border-color:#fff;color:var(--brand-blue-dark);background:#fff}.button--white:hover{border-color:#fff;color:#0b5eba;background:#edf6ff;box-shadow:0 9px 22px rgba(6,52,105,.2)}.hero__actions{display:flex;flex-wrap:wrap;gap:12px}
 .site-header{position:sticky;z-index:100;top:0;height:76px;border-bottom:1px solid rgba(220,232,239,.8);background:rgba(252,253,252,.96);transition:box-shadow .25s}.site-header.is-scrolled{box-shadow:0 8px 24px rgba(7,59,131,.08)}.site-header__inner{display:flex;align-items:center;height:100%;gap:24px}.brand{width:132px;height:62px;overflow:hidden}.brand img{width:100%;height:100%;object-fit:cover;object-position:center}.desktop-nav{margin-left:auto}.desktop-nav>ul{display:flex;margin:0;padding:0;list-style:none}.nav-item{position:relative}.nav-link{position:relative;display:block;padding:27px 13px 24px;color:#304957;font-size:14px;font-weight:650}.nav-link::after{position:absolute;right:13px;bottom:16px;left:13px;height:2px;content:"";background:var(--brand-accent);transform:scaleX(0);transition:transform .25s}.nav-link:hover,.nav-link[aria-current=page]{color:var(--brand-blue)}.nav-link:hover::after,.nav-link[aria-current=page]::after{transform:scaleX(1)}.nav-dropdown{position:absolute;top:calc(100% - 4px);left:50%;visibility:hidden;width:220px;padding-top:10px;opacity:0;transform:translate(-50%,8px);transition:.2s}.nav-item:hover .nav-dropdown,.nav-item:focus-within .nav-dropdown{visibility:visible;opacity:1;transform:translate(-50%,0)}.nav-dropdown ul{margin:0;padding:8px;border:1px solid var(--border);border-radius:10px;background:#fff;box-shadow:var(--shadow-hover);list-style:none}.nav-dropdown a{display:flex;justify-content:space-between;padding:10px 12px;border-radius:7px;font-size:13px}.nav-dropdown a:hover{color:var(--brand-blue);background:var(--bg-blue-soft)}.mobile-nav{display:none;margin-left:auto}.mobile-nav summary{display:grid;width:40px;height:40px;padding:10px;cursor:pointer;list-style:none}.mobile-nav summary span{height:2px;background:var(--brand-blue-dark)}
 .home-hero{overflow:hidden;padding:56px 0 0;background:#fff}.home-hero__grid{display:grid;grid-template-columns:1.08fr .92fr;align-items:center;gap:20px}.hero-label{display:flex;align-items:center;margin-bottom:20px;color:var(--brand-blue);font-size:14px;font-weight:600}.home-hero h1{margin-bottom:25px;font-size:clamp(30px,2.65vw,40px);line-height:1.32;letter-spacing:-.03em}.home-hero h1 span,.home-hero h1 em{display:block;white-space:nowrap}.home-hero h1 em,.page-hero h1 em{color:var(--brand-blue);font-style:normal}.home-hero__copy{position:relative;z-index:2}.home-hero__copy>p{max-width:600px;margin-bottom:32px;color:var(--text-secondary);font-size:18px}.hero__proof{display:flex;flex-wrap:wrap;gap:16px;margin-top:30px}.hero__proof span{display:flex;align-items:center;gap:8px;color:var(--text-secondary);font-size:13px}.hero__proof span::before{width:6px;height:6px;border-radius:50%;content:"";background:var(--brand-accent)}.home-hero__visual{position:relative;margin-left:-36px}.image-frame{position:relative;overflow:hidden;background:#fff}.image-frame img{width:100%;aspect-ratio:1.22;object-fit:cover;mix-blend-mode:multiply;-webkit-mask-image:radial-gradient(ellipse 83% 86% at 55% 50%,#000 58%,rgba(0,0,0,.9) 72%,transparent 100%);mask-image:radial-gradient(ellipse 83% 86% at 55% 50%,#000 58%,rgba(0,0,0,.9) 72%,transparent 100%)}.stage-ruler{display:flex;align-items:center;justify-content:center;gap:25px;margin-top:32px;padding:20px 0;border-top:1px solid var(--divider);color:var(--brand-blue-dark);font-size:14px;font-weight:750}.stage-ruler i{width:5px;height:5px;border-radius:50%;background:var(--brand-accent)}
 .subject-overview{background:#fff}.subject-overview__head{max-width:920px;margin:0 auto 62px;text-align:center}.subject-overview__label{margin-bottom:14px;color:var(--brand-blue);font-size:14px;font-weight:600}.subject-overview__head h2{margin-bottom:22px;font-size:clamp(38px,4.8vw,64px);font-weight:600;line-height:1.18;letter-spacing:-.04em}.subject-overview__lead{max-width:760px;margin:0 auto 22px;color:var(--brand-blue);font-size:19px;font-weight:600}.subject-overview__intro{max-width:900px;margin:0 auto;color:var(--text-secondary);font-size:16px}.subject-overview__grid{display:grid;grid-template-columns:repeat(3,1fr);gap:16px}.subject-card{display:flex;min-height:190px;padding:30px;align-items:flex-start;gap:22px;border:1px solid transparent;border-radius:18px;background:var(--subject-bg);box-shadow:0 8px 28px rgba(20,115,230,.05);transition:transform .2s,box-shadow .2s,border-color .2s}.subject-card:hover{border-color:var(--subject-border);box-shadow:0 14px 34px rgba(20,115,230,.1);transform:translateY(-3px)}.subject-card__icon{display:grid;width:56px;height:56px;place-items:center;flex:0 0 auto;border-radius:15px;color:var(--subject-color);background:rgba(255,255,255,.76)}.subject-card__icon svg{width:32px;height:32px;fill:none;stroke:currentColor;stroke-width:2.2;stroke-linecap:round;stroke-linejoin:round}.subject-overview__grid h3{margin:3px 0 12px;color:var(--subject-title);font-size:27px;font-weight:600}.subject-overview__grid p{margin:0;color:var(--text-secondary);font-size:14px}.subject-card--blue{--subject-bg:#eef6ff;--subject-color:#1473e6;--subject-title:#145da8;--subject-border:#b9d8fb}.subject-card--rose{--subject-bg:#fff1f3;--subject-color:#c64d67;--subject-title:#9d3550;--subject-border:#f1c4ce}.subject-card--orange{--subject-bg:#fff5e9;--subject-color:#d87827;--subject-title:#a95718;--subject-border:#f2d1ad}.subject-card--indigo{--subject-bg:#edf3ff;--subject-color:#456fc2;--subject-title:#31569e;--subject-border:#c5d4f2}.subject-card--green{--subject-bg:#edf8ef;--subject-color:#3d9460;--subject-title:#287344;--subject-border:#bfdfc8}.subject-card--purple{--subject-bg:#f5f0fb;--subject-color:#8055aa;--subject-title:#643b8a;--subject-border:#d9c7e9}

--- a/tests/article-ssr.test.ts
+++ b/tests/article-ssr.test.ts
+import assert from "node:assert/strict";
+import { spawn, type ChildProcess } from "node:child_process";
+import fs from "node:fs/promises";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { after, test } from "node:test";
+const dataDirectory = await fs.mkdtemp(path.join(os.tmpdir(), "qiyouxue-article-ssr-"));
+const buildLock = path.join(dataDirectory, "site-build.lock");
+const contentLock = path.join(dataDirectory, ".content-write.lock");
+process.env.CMS_DATA_DIR = dataDirectory;
+process.env.CMS_BUILD_LOCK = buildLock;
+process.env.CMS_CONTENT_LOCK = contentLock;
+process.env.CMS_CONTENT_LOCK_STALE_MS = "30000";
+process.env.CMS_API_KEY = "article-ssr-test-key";
+process.env.CMS_SECRET = "article-ssr-test-secret";
+process.env.CMS_PASSWORD = "article-ssr-test-password";
+await fs.writeFile(buildLock, "deployment-build-lock-sentinel\n");
+const [{ handleCmsApi }, articleStore, { categoryToSlug }, { withContentWriteLock }] = await Promise.all([
+  import("../src/lib/cms-api.ts"),
+  import("../src/lib/article-store.ts"),
+  import("../src/lib/articles.ts"),
+  import("../src/lib/content-lock.ts"),
+]);
+function apiRequest(route: string, method = "GET", body?: Record<string, unknown>): Promise<Response> {
+  return handleCmsApi(new Request(`http://localhost/api/cms/${route}`, {
+    method,
+    headers: { Authorization: `Bearer ${process.env.CMS_API_KEY}`, ...(body ? { "Content-Type": "application/json" } : {}) },
+    body: body ? JSON.stringify(body) : undefined,
+  }), route);
+}
+async function availablePort(): Promise<number> {
+  const server = net.createServer();
+  await new Promise<void>((resolve, reject) => server.once("error", reject).listen(0, "127.0.0.1", resolve));
+  const address = server.address();
+  const port = typeof address === "object" && address ? address.port : 0;
+  await new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+  return port;
+}
+let devServer: ChildProcess | null = null;
+let serverOutput = "";
+const port = await availablePort();
+const origin = `http://127.0.0.1:${port}`;
+async function startDevServer(): Promise<void> {
+  const astro = path.join(process.cwd(), "node_modules", "astro", "astro.js");
+  devServer = spawn(process.execPath, [astro, "dev", "--host", "127.0.0.1", "--port", String(port)], {
+    cwd: process.cwd(),
+    env: { ...process.env },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  devServer.stdout?.on("data", (chunk) => { serverOutput += chunk.toString(); });
+  devServer.stderr?.on("data", (chunk) => { serverOutput += chunk.toString(); });
+  const deadline = Date.now() + 20_000;
+  while (Date.now() < deadline) {
+    if (devServer.exitCode !== null) throw new Error(`Astro dev server exited early:\n${serverOutput}`);
+    try {
+      const response = await fetch(`${origin}/articles/`);
+      if (response.ok) return;
+    } catch {}
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new Error(`Astro dev server did not start:\n${serverOutput}`);
+}
+await startDevServer();
+after(async () => {
+  if (devServer && devServer.exitCode === null) {
+    devServer.kill("SIGTERM");
+    await new Promise((resolve) => devServer?.once("exit", resolve));
+  }
+  await fs.rm(dataDirectory, { recursive: true, force: true });
+});
+test("article lists read metadata without rendering every Markdown body", async () => {
+  articleStore.resetArticleStoreDiagnostics();
+  const articles = await articleStore.getPublishedArticles();
+  assert.ok(articles.length > 0);
+  assert.equal(articleStore.getArticleStoreDiagnostics().markdownRenderCount, 0);
+  assert.equal("body" in articles[0], false);
+});
+test("drafts and invalid public article routes return real 404 responses", async () => {
+  const created = await apiRequest("articles", "POST", {
+    title: "SSR 即时发布验收文章",
+    category: "学习方法",
+    body: "# SSR 完整正文\n\n这是无需构建即可上线的唯一正文标记。",
+  });
+  assert.equal(created.status, 201);
+  const result = await created.json() as { slug: string };
+  assert.match(result.slug, /^[a-z0-9]+(?:-[a-z0-9]+)*$/);
+  process.env.TEST_ARTICLE_SLUG = result.slug;
+  for (const pathname of [
+    `/articles/${result.slug}/`,
+    "/articles/not_valid/",
+    "/articles/does-not-exist/",
+    "/articles/page/1/",
+    "/articles/page/9999/",
+    "/articles/topic/not-a-category/",
+  ]) {
+    const response = await fetch(`${origin}${pathname}`);
+    assert.equal(response.status, 404, pathname);
+  }
+});
+test("publishing is immediately visible in SSR HTML, lists, category, llms and sitemap without a build", async () => {
+  const slug = process.env.TEST_ARTICLE_SLUG!;
+  const published = await apiRequest(`articles/${slug}/publish`, "POST");
+  assert.equal(published.status, 200);
+  assert.deepEqual(await published.json(), { ok: true, publishStatus: "live", message: "发布成功，文章已上线" });
+  const detail = await fetch(`${origin}/articles/${slug}/`);
+  const detailHtml = await detail.text();
+  assert.equal(detail.status, 200);
+  assert.match(detail.headers.get("content-type") || "", /^text\/html/);
+  assert.match(detailHtml, /<div class="article-prose"[^>]*>[\s\S]*<h1>SSR 完整正文<\/h1>/);
+  assert.match(detailHtml, /<link rel="canonical" href="https:\/\/qiyouxueedu\.com\/articles\//);
+  assert.match(detailHtml, /"@type":"Article"/);
+  assert.match(detailHtml, /"@type":"BreadcrumbList"/);
+  const listHtml = await (await fetch(`${origin}/articles/`)).text();
+  assert.match(listHtml, /SSR 即时发布验收文章/);
+  const categorySlug = categoryToSlug("学习方法");
+  const category = await fetch(`${origin}/articles/topic/${categorySlug}/`);
+  assert.equal(category.status, 200);
+  assert.match(await category.text(), /SSR 即时发布验收文章/);
+  const llms = await fetch(`${origin}/llms.txt`);
+  assert.match(llms.headers.get("content-type") || "", /^text\/plain; charset=utf-8/);
+  assert.match(await llms.text(), /SSR 即时发布验收文章/);
+  const full = await fetch(`${origin}/llms-full.txt`);
+  const etag = full.headers.get("etag");
+  assert.ok(etag);
+  assert.match(await full.text(), /这是无需构建即可上线的唯一正文标记/);
+  const notModified = await fetch(`${origin}/llms-full.txt`, { headers: { "If-None-Match": etag! } });
+  assert.equal(notModified.status, 304);
+  const sitemap = await fetch(`${origin}/article-sitemap.xml`);
+  assert.equal(sitemap.headers.get("content-type"), "application/xml; charset=utf-8");
+  assert.match(await sitemap.text(), new RegExp(`/articles/${slug}/`));
+  assert.equal(await fs.readFile(buildLock, "utf8"), "deployment-build-lock-sentinel\n");
+  assert.equal((await apiRequest("build")).status, 404);
+});
+test("the content write lock returns 409 without changing the draft or acquiring the build lock", async () => {
+  const slug = process.env.TEST_ARTICLE_SLUG!;
+  const draftFile = path.join(dataDirectory, "articles", `${slug}.md`);
+  const before = await fs.readFile(draftFile, "utf8");
+  let releaseHold!: () => void;
+  const held = withContentWriteLock("并发锁验收", () => new Promise<void>((resolve) => { releaseHold = resolve; }));
+  const deadline = Date.now() + 3000;
+  while (Date.now() < deadline) {
+    try { await fs.access(contentLock); break; } catch { await new Promise((resolve) => setTimeout(resolve, 10)); }
+  }
+  const conflict = await apiRequest(`articles/${slug}`, "PUT", {
+    title: "不应写入的并发修改",
+    category: "学习方法",
+    body: "不应写入",
+  });
+  assert.equal(conflict.status, 409);
+  assert.match((await conflict.json() as { error: string }).error, /内容操作正在进行/);
+  releaseHold();
+  await held;
+  assert.equal(await fs.readFile(draftFile, "utf8"), before);
+  assert.equal(await fs.readFile(buildLock, "utf8"), "deployment-build-lock-sentinel\n");
+});
+test("a stale content lock is recovered without deleting a newer owner's lock", async () => {
+  await fs.writeFile(contentLock, JSON.stringify({
+    token: "stale-test-token",
+    pid: 99999999,
+    hostname: os.hostname(),
+    createdAt: new Date(Date.now() - 60_000).toISOString(),
+    operation: "已退出的写操作",
+  }));
+  let entered = false;
+  await withContentWriteLock("陈旧锁恢复验收", async () => { entered = true; });
+  assert.equal(entered, true);
+  await assert.rejects(fs.access(contentLock), { code: "ENOENT" });
+});
+test("unpublishing and deleting immediately removes an article from every public entry", async () => {
+  const slug = process.env.TEST_ARTICLE_SLUG!;
+  const unpublished = await apiRequest(`articles/${slug}/unpublish`, "POST");
+  assert.equal(unpublished.status, 200);
+  assert.equal((await fetch(`${origin}/articles/${slug}/`)).status, 404);
+  assert.doesNotMatch(await (await fetch(`${origin}/articles/`)).text(), /SSR 即时发布验收文章/);
+  assert.doesNotMatch(await (await fetch(`${origin}/articles/topic/${categoryToSlug("学习方法")}/`)).text(), /SSR 即时发布验收文章/);
+  assert.doesNotMatch(await (await fetch(`${origin}/llms.txt`)).text(), /SSR 即时发布验收文章/);
+  assert.doesNotMatch(await (await fetch(`${origin}/llms-full.txt`)).text(), /这是无需构建即可上线的唯一正文标记/);
+  assert.doesNotMatch(await (await fetch(`${origin}/article-sitemap.xml`)).text(), new RegExp(`/articles/${slug}/`));
+  const deleted = await apiRequest(`articles/${slug}`, "DELETE");
+  assert.equal(deleted.status, 200);
+  assert.equal((await apiRequest(`articles/${slug}`)).status, 404);
+  assert.equal(await fs.readFile(buildLock, "utf8"), "deployment-build-lock-sentinel\n");
+});