fix(发布): push-all.sh 补上 git tag，并补打 v1.2.0 ~ v1.4.0 历史标签

问题：脚本里只有 docker tag / docker push，**没有 git tag**，所以远程仓库一直只有软件包、没有版本 tag —— 「某个版本对应哪个提交」只能靠翻 CHANGELOG 猜。镜像 tag 只说明「注册表里有这个包」，回答不了「这个包是哪份代码构建的」。 tools/push-all.sh： - 新增**版本预检**（传了版本号时）：从 workbuddy_portal/__init__.py 读 __version__ 与传入值比对，不一致立刻退出 —— 放在最前面，免得代码和镜像都推完了才发现「代码写着 1.4.0、却当 1.5.0 发」 - 新增 git tag -a vX.Y.Z + 推送该 tag，**放在代码与镜像都推成功之后**： tag 一旦出现在远端就是「这个版本发过了」的公开声明，不该先于产物出现 - 已存在的 tag 只提示、不改写（指向哪个提交由历史决定）补打历史标签：v1.2.0 / v1.3.0 / v1.4.0，各指向引入该版本号的那个提交（1.1.0 在仓库里没有对应提交，故未补）。文档： - DEPLOYMENT 7.1 补上「为什么必须有 git tag」与版本预检说明 - DEPLOYMENT 7.4 补上「镜像与 tag 要分别核验」的命令（git ls-remote --tags） —— 此前 7.4 只验镜像，正是这个盲区让「没有 tag」一直没被发现验证：python tools/check_docs.py → 0 处问题；python tools/smoke.py → ok=264 fail=0
2026-09-18 14:54:48 +08:00
@@ -8,6 +8,30 @@

 ---

+## [未发布]
+
+### 发布流程修复：脚本从来没打过 git tag
+
+- **问题**：`tools/push-all.sh` 里只有 `docker tag` + `docker push`，**没有 `git tag`**。
+  结果是远程仓库里**只有软件包、没有版本 tag** —— 「1.5.0 对应哪个提交」只能靠翻本文件猜，
+  想 checkout 某个已发布版本的代码没有可靠入口。镜像 tag 只说明「注册表里有这个包」，
+  它回答不了「这个包是哪份代码构建的」。
+- **现在脚本会做三件事**：
+  1. **版本预检**（传了版本号时）：从 `workbuddy_portal/__init__.py` 读 `__version__`
+     与传入值比对，不一致**立刻退出**。放在最前面，免得代码和镜像都推完了才发现
+     「代码里写着 1.4.0、却当 1.5.0 发」——那种错误只能靠改 tag 补救。
+  2. 代码与镜像都推成功后，打 `git tag -a vX.Y.Z` 并推送该 tag。放在最后是有意的：
+     tag 一旦出现在远端就是「这个版本发过了」的公开声明，不该先于产物出现。
+  3. 已存在的 tag **只提示、不改写** —— 指向哪个提交由历史决定，不该被脚本偷偷换掉。
+- **补齐历史 tag**：`v1.2.0` / `v1.3.0` / `v1.4.0` 三个注解 tag 已按各自提交的
+  `__version__` 补打并推送（每个都指向引入该版本号的那个提交，可用
+  `git for-each-ref refs/tags` 复核）。1.1.0 在仓库里没有对应提交，故未补。
+- **文档**：`docs/DEPLOYMENT.md` 第 7.1 节补上「为什么必须有 git tag」与版本预检说明；
+  第 7.4 节补上「镜像与 tag 要分别核验」的命令（`git ls-remote --tags origin`）——
+  此前 7.4 只验镜像，正是这个盲区让「没有 tag」一直没被发现。
+
+---
+
 ## [1.5.0] — 2026-09-18

 **主题：按「将会被公网访问」重新审一遍界面与暴露面**
@@ -675,17 +675,30 @@ WB_TRUST_PROXY=1

 ```bash
 export GITEA_TOKEN=<你的令牌>
-tools/push-all.sh                 # 推 main 分支 + 镜像 latest
-tools/push-all.sh 1.5.0           # 同时打一个版本 tag 并推送
+tools/push-all.sh                 # 推 main 分支 + 镜像 latest（不打版本 tag）
+tools/push-all.sh 1.5.0           # 另外打 git tag v1.5.0 与镜像 tag 1.5.0
 ```

 脚本做的事：

-1. `git push origin main` —— 用 `http.extraHeader` 传 Basic 认证，Token **只在环境变量里**，
+1. **版本预检**（只有传了版本号时才做）：从 `workbuddy_portal/__init__.py` 读
+   `__version__`，与传入的版本号比对，不一致**立刻退出**。放在最前面，免得代码和镜像
+   都推完了才发现「代码里写着 1.4.0，却当 1.5.0 发」——那种错误只能靠改 tag 补救。
+2. `git push origin main` —— 用 `http.extraHeader` 传 Basic 认证，Token **只在环境变量里**，
   不会写进 `.git/config`、URL 或 reflog；同时用 `-c credential.helper=` 屏蔽凭据助手
   （否则在非交互 / 无桌面会话里 Git Credential Manager 会挂住等弹窗）。
-2. `docker compose build` —— 镜像名本身就是注册表地址。
-3. `docker login` + `docker push`（`--password-stdin`，Token 不进命令行历史）。
+3. `docker compose build` —— 镜像名本身就是注册表地址。
+4. `docker login` + `docker push`（`--password-stdin`，Token 不进命令行历史）。
+5. **`git tag -a vX.Y.Z` + 推送该 tag** —— 放在最后，**只有代码与镜像都推成功才落 tag**。
+   tag 一旦出现在远端就是「这个版本发过了」的公开声明，不该先于产物出现。
+   已存在的 tag 只提示、不改写：指向哪个提交由历史决定，脚本不去偷偷换掉
+   「v1.5.0 到底是哪份代码」这个答案。
+
+> **为什么必须有 git tag**：镜像 tag 只说明「注册表里有这个包」，不能回答
+> 「这个包对应哪个提交」。只推镜像的话，远程仓库里永远是**只有软件包、没有版本 tag**，
+> 事后想 checkout 某个版本的代码只能靠翻 CHANGELOG 猜。
+> v1.5.0 之前的三个版本（1.2.0 / 1.3.0 / 1.4.0）已按各自提交的 `__version__` 补打了
+> `v1.2.0` / `v1.3.0` / `v1.4.0` 注解 tag；1.1.0 没有对应的提交，故未补。

 > 不用脚本、手工推也行：`git push origin main` 弹出凭据窗口时，用户名填 `wangchuanli`，
 > **密码处填 Access Token**（不是网页登录密码）。
@@ -728,6 +741,19 @@ curl -s -u wangchuanli:TOKEN \
  https://git.iwali.top/api/v1/packages/wangchuanli?type=container
 ```

+镜像与 **git tag 要分别核验** —— 两者是两套东西，只推镜像时 git 侧会静默地什么都没有：
+
+```bash
+# 远端有哪些版本 tag（读权限即可，不需要 Token）
+git ls-remote --tags origin
+
+# 标签指向哪个提交（^(commit) 前缀可看到标签解引用后的提交）
+git ls-remote --tags origin 'refs/tags/*^{}'
+
+# 本地核对「版本号 ↔ 提交」是否对得上
+git for-each-ref refs/tags --format="%(refname:short)  ->  %(*objectname:short)  %(*subject)"
+```
+
 ---

 ## 八、备份与恢复