企业官网建设流程全解析

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/LocalAI

LocalAI 官方为 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 三步操作：

1. 下载LocalAI.dmg文件；
2. 双击打开 DMG 镜像；
3. 将 LocalAI 应用拖入 Applications 文件夹；
4. 从应用程序文件夹启动 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.dmg

App 本身由 Fyne 工具打包（go run fyne.io/tools/cmd/fyne@latest 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: bytes=N-头从断点续传，不会从头再来；
• 下载完成后对二进制做 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()动态构建的菜单，其状态随安装与运行情况实时变化：

此外菜单固定包含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.json（JSON 格式，首次运行自动生成）。从 Config 结构体 可见全部可配置项及其默认值：

启动服务时 Launcher 实际拼装的命令行等价于（见 BuildRunArgs）：

local-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 或共享/tmp（macOS 上/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:8080
• API 健康检查：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 --verbose=2 /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-darwin（hdiutil生成 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/launcher，make 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