macOS 安装与服务
管理 macOS 上的 launchd 服务、Docker Desktop 接入与文件权限。
安装目录允许当前用户写入时，可直接运行安装脚本；安装到受保护的目录时需要 sudo。不带 --service 的 sudo 安装会以经过验证的原用户身份初始化配置并同步订阅，而不是以 root 身份操作用户文件。无法验证用户身份时，安装器会跳过自动同步并给出警告。
系统服务
sudo sh ./install.sh --service此命令安装 launchd LaunchDaemon，无需用户登录即可随系统启动。它是以 root 身份运行的系统服务，不是用户级 LaunchAgent。
| 项目 | 位置 |
|---|---|
| 服务标签 | com.runui.oci-mirror-proxy |
| 服务定义 | /Library/LaunchDaemons/com.runui.oci-mirror-proxy.plist |
| 配置文件 | /etc/oci-mirror-proxy/config.yaml |
| 默认管理套接字 | /var/run/oci-mirror-proxy/admin.sock |
| 日志 | /var/log/oci-mirror-proxy/stdout.log、/var/log/oci-mirror-proxy/stderr.log |
已有配置会保留，包括自定义管理套接字路径。服务每次启动时会重新创建套接字目录。旧配置未显式指定套接字时，通过服务运行环境使用 /var/run/oci-mirror-proxy/admin.sock。
标准系统管理套接字允许所有本地用户访问，无需 sudo。目录由 root 所有，权限为 0711；套接字权限为 0666，每次启动时都会恢复这些权限。本地用户既能查询状态，也能通过管理 API 修改代理配置。如果主机上存在不可信的本地账号，请勿使用此系统服务模式。私有实例和自定义套接字路径仍仅允许所有者访问。
sudo launchctl print system/com.runui.oci-mirror-proxy
oci-mirror-proxy status
sudo launchctl kickstart -k system/com.runui.oci-mirror-proxy使用 update --service 更新并重启由安装器管理的服务。不带 --service 的更新不会重启已有服务。自定义或修改过的服务定义不会被覆盖。如果 launchd 配置失败，安装器会尝试恢复原来的可执行文件和服务定义，但不会回滚配置文件。请查看恢复警告和日志。
Docker Desktop
Shell 安装器使用 --service 时还会尝试接入 Docker Desktop，除非指定 --skip-docker。安装器不会自动重启 Docker，请按输出提示完成激活。使用 Homebrew 服务、手动安装的服务，或需要手动恢复时，以登录 Docker Desktop 的用户执行以下命令，不要使用 sudo：
oci-mirror-proxy dockerd plan
oci-mirror-proxy dockerd apply --restart
oci-mirror-proxy doctor
docker pull hello-world:latest--restart 会重启 Docker Desktop 并中断运行中的容器。不使用此参数时，配置会保存，但可能仍需重启才能生效。使用 dockerd revert --restart 可移除工具管理的代理设置并使变更生效。
即使文件已经正确，显式指定 --restart 仍可让尚未加载该配置的 Docker Engine 重启并应用设置。
与 Linux 的 containerd 接入不同，Docker Desktop 通过 registry-mirrors 配置 Docker Hub，不会自动配置其他仓库的路由。CLI 会对跳过的仓库给出警告。
Engine 设置正确且镜像拉取成功，并不能证明流量经过了代理。应针对已安装的 Docker Desktop/containerd 版本验证：在拉取未缓存的镜像前后比较代理请求计数，或抓取代理流量。doctor 检查配置和连通性，不验证实际拉取路径。即使全部检查通过，请求计数没有变化时也不能认定加速已生效。
非交互式 SSH 会话的 PATH 可能不包含 /usr/local/bin，即使普通终端中可以找到程序。使用 CLI 或执行 Docker 接入前，可显式设置：
export PATH="/usr/local/bin:$PATH"客户端命令直接发现运行中的服务，不读取服务配置文件。如果同时运行用户实例和系统服务，可使用 --admin-socket /var/run/oci-mirror-proxy/admin.sock 选择系统服务。
移除服务
如果 Docker 正在使用该代理，请在服务仍运行时先执行 oci-mirror-proxy dockerd revert --restart，并确认恢复后的设置已生效。重启会中断运行中的容器。然后停止并注销服务，保留配置和可执行文件：
sudo launchctl bootout system/com.runui.oci-mirror-proxy
sudo rm /Library/LaunchDaemons/com.runui.oci-mirror-proxy.plist用户配置提示权限不足
旧版提权安装或手动运行 sudo oci-mirror-proxy serve，可能在用户配置或缓存目录中留下 root 所有的文件。普通用户无法打开仅所有者可访问、但由 root 所有的 config.yaml.lock。
修复权限前，请停止所有使用该配置的代理进程，并先检查文件所有者：
ls -ld "$HOME/Library/Application Support/oci-mirror-proxy"
ls -la "$HOME/Library/Application Support/oci-mirror-proxy"
ls -ld "$HOME/Library/Caches/oci-mirror-proxy"仅当这些目录确实是你自己的应用目录、不是共享目录或符号链接时，才恢复所有权。缓存目录存在时才执行对应命令：
sudo chown -R "$(id -un):$(id -gn)" "$HOME/Library/Application Support/oci-mirror-proxy"
sudo chown -R "$(id -un):$(id -gn)" "$HOME/Library/Caches/oci-mirror-proxy"
oci-mirror-proxy serve不要将这些命令用于系统服务配置或整个 Library 目录。不要使用 chmod 777，也不要删除锁文件：配置可能包含敏感信息，而固定的锁文件用于协调并发进程。安装器不会自动修改已有用户数据的所有者。