From 5c9b5d2ed0a4c995fd178536c6ba0cfbe574427f Mon Sep 17 00:00:00 2001
From: Haitao Pan <haitaopanhq@gmail.com>
Date: Thu, 18 Jun 2026 12:55:51 +0000
Subject: [PATCH] fix(macos): postgres brew install via command (clone-path
 patch) + docs

Add patch_playbook_postgres_macos() to rewrite the postgres macos.yml install
from the community.general.homebrew module (which can select a crashing stale
Intel Homebrew) to a brew command using the PATH brew, matching the playbooks
repo fix. Documents TC-MAC-018.
---
 docs/case/macos_compatibility_tests.md   | 10 +++++++
 docs/report/TC-MAC-012-26-06-18-19.md    | 18 +++++++++++
 scripts/setup-ai-workspace-all-in-one.sh | 38 ++++++++++++++++++++++++
 3 files changed, 66 insertions(+)

diff --git a/docs/case/macos_compatibility_tests.md b/docs/case/macos_compatibility_tests.md
index be20169..c108936 100644
--- a/docs/case/macos_compatibility_tests.md
+++ b/docs/case/macos_compatibility_tests.md
@@ -157,6 +157,16 @@
 | **目录/模式策略** | macOS 部署 `postgresql_deploy_mode=native`（→ `macos.yml`，brew 安装）；Linux 部署保持默认 `compose` |
 | **修复方案** | 在 `setup-ai-workspace-all-in-one.sh` 的 Darwin 分支注入 `-e postgresql_deploy_mode=native`，并以 `append_secret_var postgresql_admin_password=$UNIFIED_AUTH_TOKEN` 直接提供密码（extra-vars 优先级最高，彻底绕过 `/root` 的 password lookup）。Linux 分支不变 |
 
+## TC-MAC-018: postgres native 安装误用过期 Intel Homebrew 崩溃
+
+| 项目 | 内容 |
+|------|------|
+| **触发文件** | `roles/vhosts/postgres/tasks/macos.yml` |
+| **触发报错** | `Ensure PostgreSQL 16 is installed via Homebrew` → `/usr/local/Homebrew/.../macos_version.rb: unknown or unsupported macOS version: "27.0" (MacOSVersion::Error)` |
+| **根因** | 该任务用 `community.general.homebrew` 模块，模块自行探测 brew 前缀，命中了机器上**过期的 Intel Homebrew**（`/usr/local/Homebrew`），其内置 macOS 版本表不认识 `27.0`，brew 启动即崩溃。而 vault/openclaw 用 `command: brew`（走 PATH 上可用的 brew，如 Apple Silicon 的 `/opt/homebrew`）则正常——这是模块选错 brew，而非 brew 整体不可用 |
+| **修复方案** | 与 vault/openclaw 对齐：改用 `ansible.builtin.command: brew install postgresql@16`，并在 `environment.PATH` 前置 `/opt/homebrew/bin:/usr/local/bin`（优先选可用的 brew），加 `HOMEBREW_NO_AUTO_UPDATE=1`；`register`+`changed_when`/`failed_when` 维持幂等。真实仓库 `macos.yml` 已改；clone 路径由 `patch_playbook_postgres_macos()` 同步补丁 |
+| **备注** | 若该机仅有一个且过期的 brew（纯 Intel），根因为环境，需 `brew update`/重装 Homebrew；本修复在“存在可用 brew”时即可绕过（vault 步骤已证明存在可用 brew） |
+
 ---
 
 ## 修复维度总结
diff --git a/docs/report/TC-MAC-012-26-06-18-19.md b/docs/report/TC-MAC-012-26-06-18-19.md
index 94e3ffb..d3a5c74 100644
--- a/docs/report/TC-MAC-012-26-06-18-19.md
+++ b/docs/report/TC-MAC-012-26-06-18-19.md
@@ -187,3 +187,21 @@ PUT /v1/identity/mfa/method/totp/admin-generate
 **修复**：脚本 Darwin 分支注入 `-e postgresql_deploy_mode=native` + `append_secret_var postgresql_admin_password=$UNIFIED_AUTH_TOKEN`（直接给密码，绕过 `/root` lookup）。纯脚本改动，Linux 不变。`bash -n` 通过，`append_secret_var` 在用前已定义。
 
 **后续观察**：native 路径 `macos.yml` 使用 `community.general.homebrew` 模块，若该 collection 未安装可能是下一个点；先验证本步。
+
+---
+
+## 13. 续：postgres native 安装 Homebrew 崩溃（TC-MAC-018，20:50）
+
+**进展**：native 模式生效（postgres 进入 `macos.yml`）。新报错：
+
+```
+/usr/local/Homebrew/.../macos_version.rb: unknown or unsupported macOS version: "27.0"
+```
+
+**根因（非 brew 整体不可用）**：`community.general.homebrew` 模块自探测到过期的 **Intel Homebrew**（`/usr/local/Homebrew`），其不认识 macOS 27.0 而启动崩溃；vault/openclaw 用 `command: brew`（走 PATH 上可用的 brew）均正常——是模块选错了 brew。
+
+**修复**：postgres `macos.yml` 安装改为 `command: brew install postgresql@16` + `environment.PATH` 前置 `/opt/homebrew/bin:/usr/local/bin` + `HOMEBREW_NO_AUTO_UPDATE=1`，与 vault/openclaw 一致。真实仓库已改；clone 路径新增 `patch_playbook_postgres_macos()` 同步补丁。
+
+**验证**：脚本 `bash -n` 通过；用 git HEAD pristine `macos.yml` 跑补丁，模块被替换为 command:brew、YAML 合法、二次执行幂等。
+
+**注意**：若该机仅有单一过期 brew（纯 Intel），属环境问题，需 `brew update` 或重装 Homebrew。
diff --git a/scripts/setup-ai-workspace-all-in-one.sh b/scripts/setup-ai-workspace-all-in-one.sh
index 256125b..f6160ea 100755
--- a/scripts/setup-ai-workspace-all-in-one.sh
+++ b/scripts/setup-ai-workspace-all-in-one.sh
@@ -1322,6 +1322,43 @@ path.write_text(text)
 PY
 }
 
+# The postgres native (macOS) path installs postgresql@16 via the
+# community.general.homebrew module, which auto-detects a brew prefix and can
+# pick a stale Intel Homebrew at /usr/local that crashes on newer macOS versions
+# ("unknown or unsupported macOS version"). Replace it with a brew command that
+# runs the brew on PATH (Apple Silicon prefix first), matching vault/openclaw.
+patch_playbook_postgres_macos() {
+    local macos_file="roles/vhosts/postgres/tasks/macos.yml"
+    [ -f "$macos_file" ] || return 0
+    python3 - <<'PY'
+from pathlib import Path
+
+path = Path("roles/vhosts/postgres/tasks/macos.yml")
+text = path.read_text()
+old = (
+    "- name: Ensure PostgreSQL 16 is installed via Homebrew\n"
+    "  community.general.homebrew:\n"
+    "    name: postgresql@16\n"
+    "    state: present\n"
+)
+new = (
+    "- name: Ensure PostgreSQL 16 is installed via Homebrew\n"
+    "  ansible.builtin.command: brew install postgresql@16\n"
+    "  environment:\n"
+    "    PATH: \"/opt/homebrew/bin:/usr/local/bin:{{ ansible_env.PATH }}\"\n"
+    "    HOMEBREW_NO_AUTO_UPDATE: \"1\"\n"
+    "  register: postgresql_brew_install\n"
+    "  changed_when: >-\n"
+    "    'already installed' not in (postgresql_brew_install.stderr | default(''))\n"
+    "    and 'already installed' not in (postgresql_brew_install.stdout | default(''))\n"
+    "  failed_when: postgresql_brew_install.rc != 0\n"
+)
+if old in text:
+    text = text.replace(old, new, 1)
+    path.write_text(text)
+PY
+}
+
 ensure_core_skills_source() {
     if [ "${AI_WORKSPACE_PREFETCH_COMPLETED:-false}" = "true" ] &&
        [ -d "$XWORKSPACE_CORE_SKILLS_DIR/skills" ]; then
@@ -2104,6 +2141,7 @@ patch_playbook_user_systemd
 if [ "$(detect_os)" = "darwin" ]; then
     patch_playbook_vault_macos
     patch_playbook_common_macos
+    patch_playbook_postgres_macos
 fi
 prefetch_independent_sources
 ensure_core_skills_source