docs(polaris): 同步设计与部署文档现状

对齐深色玻璃样式、响应式布局、数据规模与配置生效范围。
明确仅由 polaris-v* 标签触发发布，并保留历史规格说明。

ts/web/nextjs/polaris/deploy/README.md

@@ -2,10 +2,12 @@
 
 本目录提供在服务器上以**独立 Compose 项目**运行 Polaris 的最小配置。
 
-第一阶段流程：CI（Gitea Actions）在校验（lint / typecheck / test / build / standalone
-冒烟）通过后，**自动构建并推送**镜像 `git.labmem.icu/<repo-owner>/polaris:<full-commit-sha>`
-到 Gitea registry；宿主机（服务器）首次部署时用**只读**凭据 `docker login`，在 `.env`
-中固定该镜像的 digest，再 `pull + up` 单服务运行。
+第一阶段流程：仅当推送 `polaris-v*` 标签时才运行 CI（Gitea Actions）整条验证+发布
+工作流——`verify` job 通过校验（lint / typecheck / test / build / standalone 冒烟）后，
+`publish` job 构建镜像 `git.labmem.icu/<repo-owner>/polaris:<full-commit-sha>`（完整
+commit SHA 作 tag）并**自动推送**到 Gitea registry，从 push 日志解析输出 digest；
+分支/路径推送不触发 CI。宿主机（服务器）首次部署时用**只读**凭据 `docker login`，
+在 `.env` 中以 digest 固定该镜像，再 `pull + up` 单服务运行。
 
 ## 文件说明
 
@@ -16,8 +18,9 @@
 
 设计约束：
 
-- 镜像来源：CI 按 commit sha tag 推送；部署侧用 `image: ${POLARIS_IMAGE:?...}`
-  必填 + `sha256:<digest>` 固定，杜绝 latest 漂移
+- 镜像来源：CI 仅在 `polaris-v*` 标签触发的发布中，以完整 commit SHA 为 tag 推送；
+  部署侧约定在 `.env` 写 `...@sha256:<digest>` 固定镜像，杜绝 latest 漂移；
+  `compose.yaml` 的 `image: ${POLARIS_IMAGE:?...}` 只校验变量非空，不校验 digest 格式
 - 只加入外部网络 `net-public`（与 nginx 同网）；**不连** `net-db`
 - 不映射宿主机端口（无 `ports:`），仅通过 nginx 反代访问
 - 无 DB/Redis、无 secrets、无源码/数据卷挂载
@@ -41,8 +44,9 @@
 
 ## 待现场验证（不要假设，逐项落实）
 
-- workflow 中 build/push 步骤的实际行为，以及 **digest 在 CI 运行日志中的输出形式**
-  （workflow 正在另行更新，本 lane 不改它；下文涉及处均以实际运行日志为准）
+- workflow 的 build/push 与 digest 输出逻辑已定稿：推送步骤从 push 日志解析
+  `digest: sha256:<64 位十六进制>`，回显「镜像摘要」与手动部署引用，解析失败即 job 失败；
+  **待现场验证**的是真实 Gitea registry / runner 下 push 输出能否匹配该解析
 - registry / runner 实际行为：登录、推送、按 digest 拉取
 - 生产 Nginx 行为（见「Nginx 反代」）
 - 服务器上 `net-public` 网络名、既有 Compose 项目与目录布局
@@ -51,16 +55,19 @@
 
 ## 首次发布步骤
 
-### 1) 触发并等待 CI，记录镜像与 digest
+### 1) 推送标签触发 CI，记录镜像与 digest
 
 ```bash
-# 推送到触发分支/路径后，在 Gitea 网页打开 Actions 运行页，等待 job 全绿
+# 推送 polaris-v* 标签触发整条工作流（分支/路径推送不触发 CI），例如：
+git tag polaris-v0.1.0 && git push origin polaris-v0.1.0
+# 在 Gitea 网页打开 Actions 运行页，等待 verify 与 publish job 全绿
 ```
 
-- 确认校验/构建/冒烟全部通过后，从该次运行日志的**推送步骤**记录：
+- 确认全部 job 通过后，从该次运行日志的**推送步骤**记录：
   - 镜像：`git.labmem.icu/<repo-owner>/polaris:<full-commit-sha>`
-  - digest：`sha256:<digest>`（日志中的具体展示形式**待现场验证**；
-    若日志未直接给出，用下文「如何确认真实 digest」的方法在部署前核对）
+  - digest：推送步骤解析成功时直接回显「镜像摘要：sha256:<digest>」与
+    `docker pull ...@sha256:<digest>` 手动部署引用；实际输出以日志为准，
+    若未给出，用下文「如何确认真实 digest」的方法在部署前核对
 - 记下对应 commit sha 与 run 编号，便于追溯。
 
 ### 2) 拷贝示例到服务器，并确认现状与项目路径
@@ -142,8 +149,9 @@ docker exec <nginx容器名> wget -qO- http://polaris:3000/ >/dev/null && echo o
 
 ## 升级与回退
 
-升级（**无零停机承诺**）：新 commit 的 CI 运行**全绿**并取得新 digest 后，
-把新 digest 写入 `.env` 的 `POLARIS_IMAGE`，旧值保留为注释行，然后：
+升级（**无零停机承诺**）：为要发布的新 commit 打新的 `polaris-v*` 标签触发 CI，
+运行**全绿**并取得新 digest 后，把新 digest 写入 `.env` 的 `POLARIS_IMAGE`，
+旧值保留为注释行，然后：
 
 ```bash
 docker compose pull polaris && docker compose up -d polaris
@@ -162,7 +170,8 @@ docker compose pull polaris && docker compose up -d polaris
 
 按可靠程度排序，最终以「按 digest 拉取成功」为准：
 
-- **CI 运行日志**：推送步骤的输出通常包含 digest；具体展示形式取决于 workflow 写法，
+- **CI 运行日志**：workflow 已实现 digest 输出——推送步骤解析 push 日志后回显
+  「镜像摘要」与 `docker pull` 手动部署引用；真实 registry / runner 下输出是否符合预期
   **待现场验证**，以实际日志为准。
 - **部署前交叉核对**（任一已登录该 registry、装有 buildx 的机器）：
   `docker buildx imagetools inspect git.labmem.icu/<repo-owner>/polaris:<full-commit-sha>`
@@ -173,8 +182,8 @@ docker compose pull polaris && docker compose up -d polaris
 - 已拉取过 tag 的机器可查本地记录的远端摘要：
   `docker image inspect --format '{{index .RepoDigests 0}}' git.labmem.icu/<repo-owner>/polaris:<full-commit-sha>`。
 - 注意：`.env` 固定的是 manifest（列表）digest；多架构镜像按 digest 拉取时由运行时
-  选择本平台对应的 manifest。CI 采用单平台还是多平台构建取决于 workflow
-  （**待现场验证**），构建平台需覆盖服务器架构。
+  选择本平台对应的 manifest。workflow 用单条 `docker build` 构建单平台镜像
+  （平台取决于 runner 架构），是否覆盖服务器架构**待现场验证**。
 - commit sha tag 正常不应被重复推送；若发现同名 tag 的 digest 变化，
   先排查 CI 再部署，不要直接沿用旧记录。