平台支持
pgcli 各组件与功能在 Linux、macOS 上的支持情况
pgcli 在 Linux 和 macOS 上都是驱动 Podman 容器运行的。 两者的根本区别在于容器如何获得网络：
- Linux 原生运行 Podman，容器共享宿主网络栈（
--network host），彼此通过127.0.0.1互访。这是零开销路径，也是唯一支持跨主机拓扑的路径。 - macOS 把 Podman 跑在
podman machine虚拟机里。此处的 host 网络绑定的是 虚拟机的回环，Mac 看不到；于是 pgcli 改为加入共享 bridge 网络 （pgcli-net）并发布各端口 —— Mac 通过 gvproxy 用127.0.0.1:<port>访问，容器之间则通过 bridge 上的容器名互访。这适用于单主机 （开发/测试），不是跨主机 HA 路径。
下表是当前支持矩阵。“macOS（单主机）“表示单机完全可用；那些必须向其它机器 广播可路由地址、或依赖 Linux 专属容器内部机制的功能，仍是 仅 Linux。
支持矩阵
| 组件 / 功能 | Linux | macOS |
|---|---|---|
实例生命周期 —— pg create / start / stop / restart / destroy / status |
✅ | ✅ 单主机 |
pg psql / pg exec |
✅ | ✅ |
SQL 命令参考（pg exec、管理查询） |
✅ | ✅ |
日志 —— pg logs |
✅ | ✅ |
命名空间隔离（pg.yaml 的 namespace） |
✅ | ✅ |
数据导入 / 导出 —— pg import / pg export |
✅ | ✅ |
克隆 —— pg clone（流式 pg_dump | pg_restore） |
✅ | ✅ |
扩展 —— pg extension install / list |
✅ | ✅ |
备份 / 恢复 —— pg backup / pg restore（pgBackRest） |
✅ | ✅ 单主机 |
物理副本 —— pg replica |
✅ | ✅ 单主机 |
故障切换 —— pg failover（副本提升） |
✅ | ✅ 单主机 |
开机自启 —— pg autostart |
✅ systemd user unit | ✅ launchd（登录后） |
| 插件 —— PgBouncer | ✅ 含跨主机连接池 | ✅ 单主机 dev/test |
| 插件 —— PgDog | ✅ | ✅ 单主机 dev/test |
| 插件 —— etcd | ✅ 含跨主机集群 | ❌ 仅 Linux |
| 插件 —— HAProxy | ✅ | ❌ 仅 Linux |
| 插件 —— MinIO | ✅ host 网络 | ✅ bridge，发布端口 |
| 插件 —— silo | ✅ host 网络 | ✅ bridge，发布端口 |
| 插件 —— rustfs | ✅ host 网络 | ⚠️ bridge 路径已实现但未实测 —— 暂按仅 Linux 对待 |
客户端 —— pg mc（MinIO 客户端） |
✅ host 网络 | ✅ bridge（见下） |
高可用 —— Patroni（pg ha） |
✅ 含跨主机 | ❌ 仅 Linux |
图例：✅ 支持 · ✅ 备注 支持但有所述限制 · ⚠️ 该平台上已实现但未实测 · ❌ 不支持。
实例类功能
所有构建在受管 PostgreSQL 实例之上的功能在两个平台都可用 —— 生命周期命令、
pg psql / pg exec、日志、命名空间、导入/导出、克隆、扩展、备份/恢复
（pgBackRest）、物理副本、故障切换。macOS 的 bridge 路径（发布端口 + 容器名
DNS）最早由实例、副本/备份路径验证；代理插件复用的正是这一套。
macOS 上这些都是单主机：跨主机副本、跨多机的连接池属于 Linux 的
--network host + LAN 地址能力。
开机自启
两个平台都支持，但机制不同：
- Linux —— systemd 的 user unit。
- macOS —— launchd 的 LaunchAgent。LaunchAgent 在用户登录时运行，而 非系统启动时 —— 因为 rootless podman 无法在有人登录前启动。请预期容器在你 登录后才拉起。见开机自启。
插件
各组件的网络模型不同：
- PgBouncer 与 PgDog ——
纯代理，macOS 上支持单主机 dev/test。macOS 下它们加入
pgcli-net并发布端 口；客户端连接仍是127.0.0.1:<port>。后端地址的注意事项（remote/后端主机 必须是从 Mac 可达的地址，而不是127.0.0.1）见各自页面的"平台支持"一 节。 - etcd —— 仅 Linux。成员以 host 网络运行，并把 client/peer URL 作为永久的集群状态写进 raft 成员列表；要移植 macOS 的 bridge + 容器名模型就得重写这份状态，在完成该设计之前保持仅 Linux。
- Patroni（
pg ha）—— 仅 Linux。成员依赖 podman 的 host 网络；root 和 rootless podman 均可使用。podman machine虚拟机的 uid 映射与 host 网络模型不吻合。这些命令在 macOS 上会快速失 败并给出清晰提示。见 Patroni 高可用。 - HAProxy —— 仅 Linux。它通过主机网络代理 Patroni 成员，而 podman machine 虚拟机不提供该能力；manager 在 macOS 上快速 失败。
- MinIO —— 两个平台都支持。对象存储，单机或跨
主机分布式纠删码集群皆可。Linux 上经主机网络提供服务；macOS 上加入
pgcli-net并发布 API 与控制台端 口，Mac 通过127.0.0.1:<port>即可访问（与代理插件同一条路径）。公开镜像 为双架构（amd64 + arm64）。 - silo —— 两个平台都支持。Pigsty 的 MinIO 分支，
网络模型与 MinIO 完全一致：Linux 走 host 网络，macOS 加入
pgcli-net并发布 端口。公开镜像为双架构（amd64 + arm64）。 - rustfs —— 实际上仅 Linux。pgcli 运行一个定制
wrapper 镜像（
ghcr.io/mars-base/pgcli/pgcli-rustfs），其 entrypoint 在容器 内部先把 bind 挂载的数据/证书目录 chown 成 rustfs 固定的 uid 10001，再降权到 非特权用户。wrapper 镜像为双架构构建，Go manager 也有与 MinIO/silo 相同的 macOS bridge 路径（发布端口），故 macOS 预期可用 —— 但本插件的 e2e 覆盖只在 Linux 上跑过，在 Mac 上实测之前请按仅 Linux 对待。 pg mc（MinIO 客户端）—— 两个平台都支持。它在一次性容器里运行mc：宿主的~/.mc/config.json按其原生默认路径挂载，cp/mirror/diff的本地文件参数也会按真实路径动态 挂载 —— macOS 上要求位于家目录之下（podman machine 只共享家目录）。Linux 上走 host 网络，127.0.0.1别名可直达本机 addon 实例；macOS 上容器在 bridge 网络里，127.0.0.1是容器自己的回环 —— 本机 addon 请用host.containers.internal:<port>，远端存储用可路由地址。
确认当前平台
pg start 会在横幅里打印检测到的平台，便于确认当前走的是哪条路径：