LocalAI 在 macOS 上的安装实战从 DMG 下载到菜单栏 Launcher 完整使用与验签指南【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAILocalAI 官方为 macOS 用户提供了一条零命令行的安装路径——通过 DMG 应用分发一个驻留在**菜单栏Menu Bar**的桌面 Launcher由它自动下载、校验并托管local-ai服务器进程。本文以仓库中的 macos 安装文档 为核心骨架结合 cmd/launcher 目录下的源码与 Makefile 中的打包逻辑讲解从下载安装、首次启动、菜单栏日常操作到 Apple 签名与公证验证的完整流程并剖析 Launcher 后台真实执行的配置与行为让你既会点也能懂。为什么 macOS 上用 Launcher 最省事macOS 版本的 LocalAI 默认采用LocalAI.dmg安装包方式分发。DMG 内是一个独立 App基于 Go Fyne 框架构建入口见 cmd/launcher/main.go它本身不包含模型推理后端而是扮演服务器管家角色负责发现最新版本、下载local-ai服务端二进制、校验完整性、拉起进程、看护日志并提供菜单栏图形界面。相比直接跑二进制这种方式的优势在于首次启动免配置自动完成服务器安装与启动立刻获得可用服务图形化管理启动/停止服务器、打开 WebUI、检查更新都在菜单栏完成数据隔离服务器所有可写路径都被锚定到用户数据目录避免多用户共享/tmp时的权限冲突。下载与安装步骤从项目仓库的Releases 页面获取最新构建的LocalAI.dmg按原文档说明即Download the latest DMG from GitHub releases入口。安装是标准的 macOS 三步操作下载LocalAI.dmg文件双击打开 DMG 镜像将 LocalAI 应用拖入 Applications 文件夹从应用程序文件夹启动 LocalAI。关于第 3 步从 Makefile 的 DMG 打包目标 可以看到 DMG 内部结构正是这样组织的镜像内同时放置LocalAI.app和一个指向/Applications的软链接方便用户拖放安装dmg-launcher-darwin: build-launcher-darwin rm -rf dist/dmg dist/LocalAI.dmg mkdir -p dist/dmg cp -R dist/LocalAI.app dist/dmg/LocalAI.app ln -s /Applications dist/dmg/Applications hdiutil create -volname LocalAI -srcfolder dist/dmg -ov -format UDZO dist/LocalAI.dmgApp 本身由 Fyne 工具打包go run fyne.io/tools/cmd/fynelatest package -os darwin ...应用元数据来自 cmd/launcher/FyneApp.toml程序内以固定应用 IDcom.localai.launcher创建应用实例见 cmd/launcher/main.go。首次启动Launcher 到底做了什么原文档指出首次启动时 App 会提示下载并安装最新的服务器 release装好后服务器自动启动此后每次打开 App 也会自动带起服务器。把这句话翻译成源码行为对应三条关键链路1. 版本发现优先走重定向规避 API 限流release_manager.go 中的GetLatestRelease()先跟随github.com/{owner}/{repo}/releases/latest的 302 重定向从最终 URL 中解析出最新 tag。源码注释解释了原因该重定向不受 api.github.com 未认证每小时 60 次的限流约束在 NAT / CGNAT / 云主机共享 IP 环境下尤其重要GitHub JSON API 仅作为兜底回退方案并在设置了GITHUB_TOKEN时自动附带 Authorization 头提升配额。2. 下载安装断点续传 SHA256 校验DownloadRelease()见 release_manager.go把服务端二进制下载到~/.localai/bin/local-ai同时下载配套的LocalAI-{version}-checksums.txt。下载过程有多个加固点数据流先写入dest.part临时文件成功后改名落盘失败自动重试最多 3 次退避间隔递增重试时携带 HTTPRange: bytesN-头从断点续传不会从头再来下载完成后对二进制做 SHA256 校验校验失败会丢弃损坏文件并报错重来校验通过后把 checksums 持久化到~/.localai/checksums/并把版本元数据写入~/.localai/metadata/installed-version.json。需要说明的是若 checksums 下载失败Launcher 会继续安装但输出警告并提示可手动放置校验文件到~/.localai/checksums/checksums-{version}.txt以保证后续安全校验。3. 自动启动服务器launcher.go 的Initialize()在检测到二进制已就绪且符合自动启动条件时会直接autoStartServer()拉起进程。源码注释针对 issue #11673特别强调Launcher 是纯菜单栏应用如果不自动启动用户打开后会看不见窗口也等不到服务因此自动启动默认开启——对应文档中 Settings 里的 Start LocalAI when the launcher opens 开关。菜单栏使用指南Launcher不打开独立主窗口常驻屏幕右上角菜单栏。点击菜单栏图标可看到 systray_manager.go 中recreateMenu()动态构建的菜单其状态随安装与运行情况实时变化场景菜单呈现未安装状态项 Install Latest Version 安装入口已安装未运行状态项 版本号 ▶️ Start LocalAI运行中状态项 版本号 Stop LocalAI Open WebUI此外菜单固定包含Check for Updates手动检查更新、Settings打开设置窗口含关闭随启动自动运行服务器等选项、Show Welcome Window、Open Data Folder在访达中打开~/.localai、Documentation与Quit。当检测到新版本时顶部会出现 New version available (版本号) 的升级入口。服务器运行状态下点击菜单栏图标上的状态项会弹出状态详情窗口展示当前状态、已安装版本、运行状态、WebUI 地址以及最近日志约最近 50 行由 launcher.go 中GetRecentLogs()提供。点击Open WebUI会用默认浏览器打开http://localhost:8080。技术细节进程启停由 StartLocalAI / StopLocalAI 实现——启动前会先做一次二进制完整性校验VerifyInstalledBinary比对已保存 checksums发现损坏则删除并提示重装停止时先发os.Interrupt优雅退出失败再强制 Kill。Launcher 还常驻一个每小时触发一次的后台更新检查器periodicUpdateCheck发现新版本即通过菜单栏气泡通知。数据目录与服务器运行参数源码级说明Launcher 会把配置写入~/.localai/launcher.jsonJSON 格式首次运行自动生成。从 Config 结构体 可见全部可配置项及其默认值配置键含义默认值models_path模型存放目录~/.localai/modelsbackends_path后端运行时目录~/.localai/backendsaddress监听地址127.0.0.1:8080auto_start_server打开 Launcher 时是否自动启动服务器true未设置即视为开启start_on_boot开机自启强制启动falselog_level日志级别infoenvironment_vars追加到服务进程的环境变量{}show_welcome是否显示欢迎窗口true启动服务时 Launcher 实际拼装的命令行等价于见 BuildRunArgslocal-ai run \ --models-path ~/.localai/models \ --backends-path ~/.localai/backends \ --address 127.0.0.1:8080 \ --log-level info \ --data-path ~/.localai/data \ --localai-config-dir ~/.localai/configuration \ --generated-content-path ~/.localai/generated \ --upload-path ~/.localai/uploads把数据、配置、生成内容与上传目录全部锚定到~/.localai下是有意为之源码注释指出服务器默认把部分路径解析到进程 CWD 或共享/tmpmacOS 上/tmp对所有用户都映射到/private/tmp首个用户创建出的/tmp/generated若权限为 0750其他账户再启动就会因mkdir ... permission denied失败。统一收敛到用户目录既避免路径错位也规避了跨用户冲突。服务器进程的 stdout/stderr 会被实时记录到带时间戳的日志文件~/.localai/logs/localai_时间戳.log日志中出现API server listening时 Launcher 会判定启动成功并把状态更新为 LocalAI is running。访问与验证服务服务就绪后打开浏览器访问WebUI 控制台http://localhost:8080API 健康检查http://localhost:8080/readyz命令行快速验证方式与 故障排查文档 中 Quick Diagnostics 一致# 检查 LocalAI 是否就绪 curl http://localhost:8080/readyz # 列出已加载模型 curl http://localhost:8080/v1/models若服务器未随 Launcher 自动启动可通过菜单栏手动点 Start LocalAI仍失败时状态详情窗口会给出最近日志用于定位。签名与公证验证原文档明确LocalAI.dmg及其内的 App与local-ai服务端二进制均使用Apple Developer ID 签名并经 Apple 公证notarized因此不会触发隔离警告quarantine prompt也无需任何绕过操作。这一承诺在仓库的 CI 链路中有完整实现。如需自行核对签名执行文档给出的两条命令spctl --assess --type open --context context:primary-signature -v /Applications/LocalAI.app codesign --verify --deep --strict --verbose2 /Applications/LocalAI.app仓库侧对应的发布流水线可从 contrib/macos/sign-and-notarize.sh 与 Makefile 目标还原代码签名App 使用codesign --deep --force --options runtime --timestamp并启用Hardened Runtime且附带 Launcher.entitlements 中声明的权限network.client下载/API 访问、network.server本地监听 8080、allow-jit与allow-unsigned-executable-memory支撑服务端/后端的本地代码执行公证与装订脚本对 App 先打包 zip 再xcrun notarytool submit通过后xcrun stapler staple把票据装订进App 本体而非仅 DMG。脚本注释解释了原因只装订 DMG 时被拷贝出镜像的 App 本地没有公证票据Gatekeeper 会退回在线核验——离线或防火墙环境下启动就会失败把票据打进 App bundle 才能离线验证无密钥时自动跳过脚本的每个子命令在对应密钥环境变量如MACOS_CERTIFICATE、MACOS_SIGN_IDENTITY、MACOS_NOTARY_KEY未设置时直接返回成功保证 fork、本地开发与 PR 的无签名构建不受阻塞。对应 Makefile 发布目标链为build-launcher-darwin打 App→dmg-launcher-darwinhdiutil生成 UDZO 格式 DMG 并签名→notarize-launcher-darwin提交公证→release-launcher-darwin产出dist/LocalAI.dmg可见 Makefile。常见问题与排查建议应用已损坏无法打开或隔离提示官方发布物已公证正常不应出现若仍遇到 quarantine 类提示说明你拿到的是第三方/未签名构建例如从源码自行打包的本地产物此时需自行评估安全风险后处理参见 troubleshooting 文档 中 macOS: Application Is Quarantined 一节的说明。服务迟迟不 Running在菜单栏状态详情中查看 Recent Logs若提示二进制损坏Launcher 会自动删除损坏文件并引导重新安装源码中VerifyInstalledBinary失败即走该路径。想改监听端口/模型目录直接编辑~/.localai/launcher.json后重启 Launcher或通过 Settings 界面的环境变量配置注入。下一步安装完成后即可基于http://localhost:8080开始使用通过 模型安装入门 了解如何挑选与安装模型GGUF 格式配合 llama.cpp 系列后端等参考 快速开始文档 体验第一个推理请求深入学习 模型自定义配置 与 故障排查手册若你偏好命令行或无 GUI 环境可改用 Linux / Docker 部署方式 中的二进制或容器安装路径。如果希望自己动手复现这套桌面应用源码入口在 cmd/launchermake build-launcher可构建跨平台二进制make release-launcher-darwin在配置好签名密钥后产出完整的公证 DMG。【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
