Mac 开发环境预发布（Staging）配置

当你希望一台 Mac 表现为可重复构建的本地开发或预发布服务器时，请使用本技能。

该技能围绕现代 Apple Silicon Mac 实际具备的软件栈构建：

• 系统自带的 macOS Apache（/usr/sbin/httpd）
• 通过 Homebrew 安装的 PHP 8.5
• 通过 Homebrew 安装的 MariaDB
• macOS 内置的 SSH/SFTP
• 由 npm 管理的 JavaScript 工具链，用于本地构建/测试工作流
• 一个与主 OpenClaw 网关共存的、仅限开发使用的网关接入面（gateway surface）
• 可选的 Homebrew nginx

它不假设采用 Linux 风格的包布局，也不假装 Mac 应当完全模拟你的 Ubuntu 网关行为。

适用场景

• 在 Mac 上进行本地 PHP 预发布环境搭建
• Joomla、WordPress、CodeIgniter、Laravel 等 PHP 应用
• 在系统默认的 macOS Apache 中启用 PHP 8.5
• 添加 MariaDB 并建立可预测的本地数据库环境
• 自动生成虚拟主机（vhost）配置文件和 Apache 片段，避免凭记忆手动编辑
• 通过 SFTP 暴露项目，用于部署、编辑及预发布环境同步
• 以可复现的方式安装 browser-sync 等 JS 工具链
• 在不干扰主网关的前提下，测试轻量级 Mac 本地网关/控制器
• 可选的 nginx 前端代理或旁路（sidecar）本地测试

不适用场景

• 面向公网的生产环境托管
• 替代你的主 Linux 网关
• 明确倾向容器化方案时（如 Docker 优先的本地开发栈）
• 误以为本技能可绕过 sudo 权限直接修改 /etc/apache2 目录下的配置

现实考量

在 macOS 上，难点不在于安装 PHP 或 MariaDB，而在于使 Apache 配置具备可复现性，且不破坏系统稳定性。

因此，本技能遵循分阶段执行模式：

1. 检测当前系统状态
2. 安装或验证 Homebrew 托管的服务
3. 生成安全的 Apache 配置片段
4. 明确告知操作者哪些步骤需使用 sudo
5. 变更后验证整套技术栈运行状态
6. 若文件部署是工作流的一部分，则验证 SFTP 可用性
7. 保留操作凭证（receipts）与日志，便于自动化与预发布流程审计

工作流

1. 检测当前技术栈

运行：

scripts/detect-stack.sh
scripts/detect-ports.sh

检查内容包括：

• 系统自带 Apache 的版本
• 是否已启用虚拟主机（vhosts）
• 是否通过 Homebrew 安装了 PHP
• 是否已安装 MariaDB
• 是否已安装 nginx
• 当前 brew services 状态
• 是否存在与主网关或本地 JS 工具链的端口冲突

2. 安装核心软件包

运行：

scripts/bootstrap-brew.sh
scripts/bootstrap-npm-tooling.sh

安装以下组件：

• php
• mariadb
• nginx
• 本地 npm 工具链（例如 browser-sync）

该步骤不会静默修改 /etc/apache2 下的任何文件。

3. 渲染 Apache + PHP 配置

生成推荐的 Apache PHP 启用配置片段：

scripts/render-apache-php-snippet.sh

生成本地虚拟主机配置：

scripts/render-vhost.sh 
  --server-name mysite.test 
  --docroot /Users/you/Sites/mysite/public

这些脚本会输出应写入以下路径的配置内容：

• /etc/apache2/httpd.conf
• /etc/apache2/extra/httpd-vhosts.conf

将配置实际写入上述路径仍需使用 sudo 权限。

4. 启用服务

对于 Homebrew 托管的服务：

brew services start php
brew services start mariadb
brew services start nginx

对于系统自带的 Apache：

sudo apachectl restart

若需部署一个与主 Ryzen 网关共存的 Mac 本地开发网关，请先渲染推荐的环境配置：

scripts/render-local-gateway-env.sh

默认规则如下：

• 主 Ryzen 网关保持绑定于 192.168.88.11:18789
• Mac 本地开发网关仅绑定回环地址（loopback）
• Mac 本地开发网关使用非冲突的测试端口（如 28789）

5. 验证技术栈

运行：

scripts/verify-stack.sh

验证内容包括：

• Apache 是否响应请求
• PHP CLI 是否可用
• PHP 模块路径是否正确加载
• MariaDB 的 Unix socket 或 TCP 端口是否就绪
• 如预期启用，nginx 是否正在运行
• 预期的本地端口是否空闲或已被有意占用
• 本地开发网关测试端口是否与生产网关端口发生冲突

6. 启用并验证 SFTP

对预发布环境而言，SFTP 通常是部署最简路径。

检查当前状态：

scripts/detect-sftp.sh

若“远程登录”（Remote Login）未启用，可通过 macOS 系统设置或以下命令开启：

sudo systemsetup -setremotelogin on

推荐实践：

• 创建或选用专用的预发布用户
• 将项目文件置于该用户的家目录下，或置于明确归属的共享路径中
• 当 SFTP 文件同步已满足需求时，避免授予广泛的 shell 访问权限

在将该 Mac 暴露给局域网内其他设备前，请先阅读 references/sftp-on-macos.md。

7. 凭证记录与控制器操作

本技能假定所有预发布操作均应留痕。

当你需要一个稳定入口点统一管理本地服务控制、构建步骤、验证、端口检查或网关连通性测试时，可使用轻量级控制器：

scripts/controller.sh status
scripts/controller.sh verify
scripts/controller.sh build /Users/you/Sites/mysite build
scripts/controller.sh gateway-ping http://127.0.0.1:28789/

记录操作凭证：

scripts/write-receipt.sh --action "bootstrap-brew" --status ok --detail "Installed php mariadb nginx"
scripts/write-receipt.sh --action "verify-stack" --status ok --detail "Apache php mariadb verified"

凭证记录用途包括：

• Markdown 格式查看器展示
• CRM 或内部仪表盘集成
• 故障回滚与排查

请参阅 references/controller-surface.md 了解该轻量级 Mac 控制平面的设计意图。

默认架构

推荐的本地预发布环境布局：

• 应用服务使用 Apache，监听 :80
• Apache 内嵌加载 PHP 8.5，或通过 PHP-FPM 运行
• MariaDB 仅绑定 localhost
• SFTP 用于部署/同步，监听 :22
• 可选：nginx 监听 :8080，用于替代反向代理方案测试
• npm 托管的测试服务使用显式端口（如 3000 或 5173）
• 可选：Mac 本地开发网关监听 127.0.0.1:28789

优先保持简洁；仅在确有需要时再引入 Proxy Manager。

本地网关兼容性

目标并非替代主 Ryzen 网关，而是让 Mac 能够运行一个轻量级本地开发控制面，同时不干扰生产级编排系统。

推荐规则：

• 主 OpenClaw 网关仍是唯一面向局域网的共享网关
• Mac 本地开发网关仅绑定 127.0.0.1
• Mac 本地开发网关使用非默认测试端口（如 28789）
• 测试控制器应连接本地 Mac 网关或控制器，而非直连生产网关——除非工作流明确要求
• 即使本地网关/控制器宕机，Mac 仍应作为普通节点及本地预发布环境正常运行

运行以下命令生成一份可复现的纯本地网关环境契约：

scripts/render-local-gateway-env.sh

可选的 nginx / NPM

nginx 可通过 Homebrew 直接便捷安装。

Nginx Proxy Manager 为可选组件，应视为独立层级，通常以容器方式部署。本技能不自动安装 NPM，因其引入的复杂度远超大多数 Mac 本地预发布环境所需。

在添加该层级前，请先阅读 references/nginx-and-npm.md。

安全规范

• 除非明确需要远程访问，否则始终将 MariaDB 绑定至 localhost
• 将 Mac 视为预发布环境，而非公开服务器
• 本地虚拟主机应使用明确的域名（如 mysite.test）
• 切勿将密钥（secrets）硬编码进生成的 Apache 配置中
• 推荐为 SFTP 创建专用预发布用户，而非广泛共享主登录账户
• 若 SFTP 已满足工作流需求，则不应额外授予 shell 访问权限
• 切勿将 Mac 的预发布技术栈直接暴露于公网互联网
• Mac 本地开发网关默认仅绑定回环地址（loopback）
• 为初始化（bootstrap）、服务变更及测试控制器操作保留完整凭证记录
• 在启动 BrowserSync、Vite、nginx 或本地网关前，优先执行显式端口检查
• 若控制器或本地网关失效，Apache/MariaDB 预发布栈仍应维持本地正常运行

相关文件

• scripts/detect-stack.sh：检查当前 Mac 技术栈状态
• scripts/bootstrap-brew.sh：安装核心 Homebrew 软件包
• scripts/bootstrap-npm-tooling.sh：安装本地预发布工作流所需的基线 npm 工具链
• scripts/controller.sh：轻量级 Mac 侧控制器，支持服务管理/构建/验证等操作
• scripts/detect-ports.sh：检查 Apache、nginx、JS 工具链及本地网关之间的端口冲突
• scripts/render-apache-php-snippet.sh：输出 Apache 启用 PHP 8.5 的配置片段
• scripts/render-local-gateway-env.sh：输出安全的纯本地网关环境契约
• scripts/render-vhost.sh：输出安全的虚拟主机（vhost）配置块
• scripts/verify-stack.sh：验证最终技术栈完整性
• scripts/detect-sftp.sh：检查 macOS 内置 SSH/SFTP 当前状态
• scripts/write-receipt.sh：为预发布/控制器操作追加可审计的操作凭证
• references/apache-layout.md：关于系统自带 macOS Apache 的说明
• references/sftp-on-macos.md：面向预发布场景的安全 SFTP 配置指南
• references/nginx-and-npm.md：判断何时值得引入 nginx 或 NPM
• references/controller-surface.md：轻量级 Mac 控制器设计模式
• references/gateway-coexistence.md：如何隔离本地网关测试与生产网关