feat: 添加 AI 索引重建功能，优化相关 API 和工作流，增强内存管理配置

deploy/docker/.env.example

@@ -3,6 +3,17 @@ BACKEND_PORT=5150
 FRONTEND_PORT=4321
 ADMIN_PORT=4322
 
+# 建议在小内存主机上给每个服务设置明确上限，避免 backend 在 AI 重建索引时
+# 把整台主机拖进 swap 抖动。默认值与 compose.package.yml 保持一致。
+BACKEND_MEMORY_LIMIT=768m
+BACKEND_MEMORY_SWAP_LIMIT=768m
+BACKEND_WORKER_MEMORY_LIMIT=512m
+BACKEND_WORKER_MEMORY_SWAP_LIMIT=512m
+FRONTEND_MEMORY_LIMIT=256m
+FRONTEND_MEMORY_SWAP_LIMIT=256m
+ADMIN_MEMORY_LIMIT=128m
+ADMIN_MEMORY_SWAP_LIMIT=128m
+
 # frontend SSR 服务端访问 backend 用这个内部地址（compose 默认可直接使用）
 INTERNAL_API_BASE_URL=http://backend:5150/api
 

deploy/docker/README.md

@@ -43,6 +43,10 @@ python deploy/scripts/render_compose_env.py \
 
 建议在 `config.yaml -> compose_env` 下同时检查这些运行时变量：
 
+- `BACKEND_MEMORY_LIMIT / BACKEND_MEMORY_SWAP_LIMIT`：backend 容器内存 / swap 上限；对小内存主机建议显式设置
+- `BACKEND_WORKER_MEMORY_LIMIT / BACKEND_WORKER_MEMORY_SWAP_LIMIT`：worker 容器内存 / swap 上限
+- `FRONTEND_MEMORY_LIMIT / FRONTEND_MEMORY_SWAP_LIMIT`：frontend 容器内存 / swap 上限
+- `ADMIN_MEMORY_LIMIT / ADMIN_MEMORY_SWAP_LIMIT`：admin 容器内存 / swap 上限
 - `INTERNAL_API_BASE_URL`：frontend SSR 容器访问 backend 用，compose 默认推荐 `http://backend:5150/api`
 - `PUBLIC_API_BASE_URL`：浏览器访问 backend API 用；留空时前台会回退到“当前主机 + `:5150/api`”
 - `PUBLIC_COMMENT_TURNSTILE_SITE_KEY`：前台评论 / 订阅表单使用的 Cloudflare Turnstile site key
@@ -62,6 +66,14 @@ python deploy/scripts/render_compose_env.py \
 
 ```yaml
 compose_env:
+  BACKEND_MEMORY_LIMIT: 768m
+  BACKEND_MEMORY_SWAP_LIMIT: 768m
+  BACKEND_WORKER_MEMORY_LIMIT: 512m
+  BACKEND_WORKER_MEMORY_SWAP_LIMIT: 512m
+  FRONTEND_MEMORY_LIMIT: 256m
+  FRONTEND_MEMORY_SWAP_LIMIT: 256m
+  ADMIN_MEMORY_LIMIT: 128m
+  ADMIN_MEMORY_SWAP_LIMIT: 128m
   PUBLIC_API_BASE_URL: https://api.blog.init.cool
   PUBLIC_COMMENT_TURNSTILE_SITE_KEY: 1x00000000000000000000AA
   PUBLIC_WEB_PUSH_VAPID_PUBLIC_KEY: replace-with-web-push-vapid-public-key
@@ -178,6 +190,7 @@ A:
 A:
 - `backend` 镜像启动时会先执行 `db migrate`
 - `backend` 提供 `/healthz`
+- `backend-worker` 不提供 HTTP `/healthz`；compose 会覆盖镜像默认 healthcheck，改为检查主进程是否仍以 `--worker` 模式运行
 - `frontend` 提供 `/healthz`
 - `admin` 继续由 Nginx 提供 `/healthz`
 - compose 现在使用 `depends_on.condition: service_healthy`

deploy/docker/compose.package.yml

@@ -3,6 +3,10 @@ services:
     image: ${BACKEND_IMAGE:-git.init.cool/cool/termi-astro-backend:latest}
     pull_policy: always
     restart: unless-stopped
+    # 对 tohka 这类小内存主机，建议给服务设置明确上限，
+    # 避免 AI 重建索引时把整机拖进 swap 抖动 / OOM。
+    mem_limit: ${BACKEND_MEMORY_LIMIT:-768m}
+    memswap_limit: ${BACKEND_MEMORY_SWAP_LIMIT:-768m}
     environment:
       PORT: 5150
       APP_BASE_URL: ${APP_BASE_URL:-http://localhost:5150}
@@ -30,6 +34,8 @@ services:
     image: ${BACKEND_IMAGE:-git.init.cool/cool/termi-astro-backend:latest}
     pull_policy: always
     restart: unless-stopped
+    mem_limit: ${BACKEND_WORKER_MEMORY_LIMIT:-512m}
+    memswap_limit: ${BACKEND_WORKER_MEMORY_SWAP_LIMIT:-512m}
     depends_on:
       backend:
         condition: service_healthy
@@ -48,11 +54,22 @@ services:
       TERMI_WEB_PUSH_VAPID_SUBJECT: ${TERMI_WEB_PUSH_VAPID_SUBJECT:-}
       RUST_LOG: ${RUST_LOG:-info}
       TERMI_SKIP_MIGRATIONS: 'true'
+    # backend 镜像默认 healthcheck 会探测 HTTP /healthz，
+    # 但 worker 模式不监听 5150，所以这里改成“主进程仍然是 --worker”检查。
+    healthcheck:
+      test:
+        ['CMD-SHELL', "test -r /proc/1/cmdline && tr '\\000' ' ' </proc/1/cmdline | grep -q -- '--worker'"]
+      interval: 30s
+      timeout: 3s
+      start_period: 15s
+      retries: 5
 
   frontend:
     image: ${FRONTEND_IMAGE:-git.init.cool/cool/termi-astro-frontend:latest}
     pull_policy: always
     restart: unless-stopped
+    mem_limit: ${FRONTEND_MEMORY_LIMIT:-256m}
+    memswap_limit: ${FRONTEND_MEMORY_SWAP_LIMIT:-256m}
     depends_on:
       backend:
         condition: service_healthy
@@ -78,6 +95,8 @@ services:
     image: ${ADMIN_IMAGE:-git.init.cool/cool/termi-astro-admin:latest}
     pull_policy: always
     restart: unless-stopped
+    mem_limit: ${ADMIN_MEMORY_LIMIT:-128m}
+    memswap_limit: ${ADMIN_MEMORY_SWAP_LIMIT:-128m}
     depends_on:
       backend:
         condition: service_healthy

deploy/docker/config.yaml.example

@@ -25,6 +25,14 @@ compose_env:
   BACKEND_PORT: 5150
   FRONTEND_PORT: 4321
   ADMIN_PORT: 4322
+  BACKEND_MEMORY_LIMIT: 768m
+  BACKEND_MEMORY_SWAP_LIMIT: 768m
+  BACKEND_WORKER_MEMORY_LIMIT: 512m
+  BACKEND_WORKER_MEMORY_SWAP_LIMIT: 512m
+  FRONTEND_MEMORY_LIMIT: 256m
+  FRONTEND_MEMORY_SWAP_LIMIT: 256m
+  ADMIN_MEMORY_LIMIT: 128m
+  ADMIN_MEMORY_SWAP_LIMIT: 128m
 
   APP_BASE_URL: https://admin.blog.init.cool
   INTERNAL_API_BASE_URL: http://backend:5150/api