docs(deploy): document pipeline and static assets

deploy/single-node/docker-compose.yml

@@ -8,8 +8,8 @@ services:
       - |
         set -eu
         rm -rf /assets/_next /assets/public
-        mkdir -p /assets/_next /assets/public
-        cp -R /app/dashboard/static /assets/_next/static
+        mkdir -p /assets/_next/static /assets/public
+        cp -R /app/dashboard/static/. /assets/_next/static
         cp -R /app/dashboard/public/. /assets/public
     volumes:
       - frontend_static:/assets

docs/en/deployment.md

@@ -13,13 +13,19 @@
 
 The frontend is built in GitHub Actions and shipped as a prebuilt `linux/amd64` image. The host only pulls the image and starts containers; it does not build locally.
 
+`yarn prebuild` bundles the docs, blog, and static content needed by the console. During that phase the CI container runs `scripts/sync-doc-content.sh` (pulling docs from this repo plus `accounts.svc.plus`, `rag-server.svc.plus`, and `postgresql.svc.plus`) and `scripts/sync-blog-content.sh` (cloning `https://github.com/cloud-neutral-workshop/knowledge.git`), so the `knowledge/` directory and all documentation assets already live inside the image before the runtime stage begins.
+
 The stack is static-first:
 
-- Caddy serves `/_next/static/*` and public assets from a shared volume.
-- The Next.js standalone container serves dynamic HTML, auth endpoints, and API proxy routes.
-- `knowledge/` is cloned in CI and packed into the image during the Docker build.
+- Caddy serves `/_next/static/*` and public assets from a shared read-only volume.
+- The Next.js standalone container serves dynamic HTML, auth endpoints, and API proxy routes. Static assets and hashed CSS/JS files are extracted by the `frontend-assets` helper task, so the runtime no longer needs to compile anything on the single-node host.
+- `knowledge/` and the synced docs/blog assets are copied into the image during the Docker build via the GitHub Actions workflow.
 
-This baseline is intentional for the current weak-IO single-node host. If `docs.svc.plus` becomes an API-backed service later, update this page and the runbook to remove docs payload from the frontend image.
+Releases are orchestrated through `.github/workflows/service_release_frontend-deploy.yml`. That workflow clones the knowledge repository, runs the Docker build/push sequence, renders `.env.runtime`, and ships `docker-compose.yml`, `Caddyfile`, and the runtime env file to the host. The control-plane workflow `.github/workflows/service_release_apiserver-deploy.yml` then updates Cloudflare DNS for the release domain (via `scripts/github-actions/update-release-dns.sh`) so `cn.svc.plus` and the redirected alias `cn.onwalk.net` point at the new environment.
+
+This baseline is intentional for the weak-IO single-node host (47.120.61.35). No images are built on the target machine, keeping the deployment lightweight: the host only logs into GHCR, pulls the `dashboard` image, extracts assets into `frontend_static`, and starts `dashboard` plus `caddy` containers via `docker compose`.
+
+If `docs.svc.plus` is later refactored into a dedicated API service, revisit this writeup (and the runbook) so the GitHub Actions pipeline only bundles the API payloads that belong to that new service.
 
 ## Related Docs
 

docs/usage/deployment.md

@@ -17,11 +17,19 @@ The production frontend is deployed as a prebuilt container image from GitHub Ac
 - The target host does not build images locally.
 - The workflow builds an `linux/amd64` image and pushes it to `ghcr.io/<owner>/dashboard:<sha>`.
 - The host only performs `docker login`, `docker compose pull`, static asset extraction, and `docker compose up`.
-- `knowledge/` is cloned during CI build and packed into the image.
+- `knowledge/` is cloned during CI build (via `scripts/sync-blog-content.sh`) and synced with other docs (via `scripts/sync-doc-content.sh`) before being packed into the image.
 - Static assets are extracted from the image into a shared Docker volume so Caddy can serve `/_next/static/*` and checked-in public files directly.
 
 This is intentionally static-first for the current weak-IO single-node host. Dynamic HTML, auth routes, and API proxy routes still run through the Next.js container. When `docs.svc.plus` is later split into an API/service, revisit this runbook and remove docs content from the frontend image.
 
+## Control Plane & DNS Stage
+
+The control repo (`github-org-cloud-neutral-toolkit`) tracks `console.svc.plus` through `console.svc.plus.code-workspace` and keeps the `subrepos/accounts.svc.plus` pointer in sync via `skills/cross-repo-upstream-submodule-sync`. Releases resolve metadata with that workspace and the `config/single-node-release` manifests. After `.github/workflows/service_release_frontend-deploy.yml` finishes pushing the new image, the control-plane workflow `.github/workflows/service_release_apiserver-deploy.yml` calls `scripts/github-actions/update-release-dns.sh` to update Cloudflare DNS so the new endpoint is reachable under `cn.svc.plus` and `cn.onwalk.net`.
+
+## Future Docs Strategy
+
+Because the frontend currently ships docs content directly (knowledge/blog + rendered markdown), any future split where `docs.svc.plus` becomes an API-backed service should include a repo-level migration plan: stop syncing docs into the frontend image, move documentation storage/serving into the dedicated API, and adjust the runbook/workflow notes above accordingly.
+
 ## Runtime Layout
 
 Remote directory:

docs/zh/deployment.md

@@ -13,13 +13,19 @@
 
 前端镜像在 GitHub Actions 中完成构建并推送到镜像仓库，目标主机只负责拉取镜像和启动容器，不在机器上本地构建。
 
+`yarn prebuild` 会同步 docs、博客和其它静态内容。CI 在该阶段执行 `scripts/sync-doc-content.sh`（从 `console.svc.plus`、`accounts.svc.plus`、`rag-server.svc.plus` 和 `postgresql.svc.plus` 拉取文档）以及 `scripts/sync-blog-content.sh`（克隆 `https://github.com/cloud-neutral-workshop/knowledge.git`），因此 `knowledge/` 目录和所有文档/博客资产在构建镜像时就已存在。
+
 当前方案尽量以静态模式运行：
 
-- Caddy 直接服务 `/_next/static/*` 与 `public/` 里的静态资源。
-- Next.js standalone 容器只承接动态页面、认证接口和代理接口。
-- `knowledge/` 在 CI 阶段拉取，并在 Docker 打包时直接写入镜像。
+- Caddy 直接服务 `/_next/static/*` 与 `public/` 里的静态资源，并配合 `frontend_static` 共享卷。
+- Next.js standalone 容器只承接动态页面、认证接口和代理接口，`frontend-assets` 任务会把所有静态文件（包括哈希后的 CSS/JS）拷贝到 `frontend_static`。
+- `knowledge/` 与同步的文档/博客内容在 GitHub Actions 的 Docker 构建阶段就被写入镜像。
 
-这是针对当前单机弱 IO 环境的权衡。后续如果 `docs.svc.plus` 被拆成独立 API 服务，需要同步调整这里和 `docs/usage/deployment.md` 的镜像内容与路由职责。
+发布由 `.github/workflows/service_release_frontend-deploy.yml` 驱动，CI 构建/推送镜像、渲染 `.env.runtime`，然后将 `docker-compose.yml`、`Caddyfile` 与运行时环境文件发送到主机。随后控制平面工作流 `.github/workflows/service_release_apiserver-deploy.yml` 通过 `scripts/github-actions/update-release-dns.sh` 更新 Cloudflare DNS，使 `cn.svc.plus` 与别名 `cn.onwalk.net` 指向更新后的环境。
+
+这是针对弱 IO 单机主机 `47.120.61.35` 的部署权衡：主机不会在本地构建镜像，只需登录 GHCR、拉取 `dashboard` 镜像、解包静态资源到 `frontend_static`，再通过 `docker compose` 启动 `dashboard` 与 `caddy`。
+
+未来如果 `docs.svc.plus` 被拆分成独立的 API 服务，必须同步更新这份说明（以及运行手册），让 GitHub Actions 只打包属于新服务的内容。
 
 ## 相关文档