Lokus 跨平台构建与部署:从源码编译 macOS/Windows/Linux 到 Docker 构建完整指南

原创2026-10-25 21:39:142,337 阅读

Lokus 跨平台构建与部署:从源码编译 macOS/Windows/Linux 到 Docker 构建完整指南

Lokus 是一款基于 React + Rust(Tauri 2)构建的本地优先 Markdown 笔记应用。本文将带你完整走通 Lokus 跨平台构建与部署流程:环境检查、启动开发服务器、从源码编译 macOS/Windows/Linux 生产安装包、用 Docker 构建 Linux 版本,以及用 Docker Compose 一键部署自托管 AI 推理代理。

一、动手之前:了解 Lokus 的构建架构

Lokus 采用典型的 Tauri 双端架构:前端是 React 19 + Vite 7 的 Web 界面,后端是 Rust 编写的系统能力层。理解这个结构,才能选对构建命令:

层 技术 主要代码位置
前端 React 19、Tailwind CSS、Vite 7 src/
后端 Rust、Tauri 2、Tokio src-tauri/
编辑器 ProseMirror、KaTeX、Shiki src/editor/
构建脚本 Node 脚本 + Shell scripts/
Linux 构建镜像 Ubuntu 22.04 + GTK/WebKit docker/
AI 推理代理 Bun + Caddy + Redis proxy/

Lokus 跨平台构建产物界面:本地优先的 Markdown 笔记编辑器

前端构建由 Vite 完成(配置见 vite.config.js),Rust 侧的依赖声明在 src-tauri/Cargo.toml,而 Tauri 的全局配置(打包目标、图标、更新端点等)集中在 src-tauri/tauri.conf.json。其中 beforeBuildCommand 会自动先执行 npm run build,再打包桌面应用——所以你只需一条命令就能完成"前端 + 后端"的完整构建。

二、环境准备:macOS/Windows/Linux 依赖一键检查

开始编译前,先确认三类基础依赖:

  1. Node.js 18+(推荐 22)+ npm
  2. Rust 工具链(通过 rustup 安装,含 cargo)
  3. 平台专属系统库(Tauri 桌面窗口依赖):
平台 必需依赖
macOS Xcode Command Line Tools(xcode-select --install)
Windows Visual Studio Build Tools(含 C++ 工作负载)、WebView2
Linux libgtk-3-dev、libwebkit2gtk-4.0-dev、librsvg2-dev、patchelf、build-essential、pkg-config

装完后无需逐个手动验证,项目内置了平台检测脚本,一条命令即可核对 Node、Rust、Tauri CLI 和各平台库是否齐全:

npm run check-platform
# 或加 --verbose 查看更详细的版本与建议

该逻辑位于 scripts/check-platform.js,它还会自动尝试补装缺失的 Tauri CLI。各平台的完整依赖清单与常见报错对照,可参考 CONTRIBUTING.md 的 "Platform-Specific Dependencies" 一节。

三、最快启动方法:3 条命令进入 Lokus 开发模式

开发模式适合验证代码改动,也适合首次"冒烟测试"环境是否可用:

# 1. 克隆仓库
git clone https://gitcode.com/gh_mirrors/lo/lokus
cd lokus

# 2. 安装前端依赖(同时会安装 Tauri CLI)
npm install

# 3. 启动开发服务器(自动编译 Rust 并打开应用窗口)
npm run tauri dev

⚠️ 首次构建需要编译数百个 Rust 依赖,耗时约 5–10 分钟,属正常现象;之后的热更新会快很多。

项目还封装了带平台校验的开发脚本(定义在 package.json),会先跑 check-platform.js 确认环境再启动:

npm run dev:windows   # Windows 开发模式
npm run dev:macos     # macOS 开发模式
npm run dev:linux     # Linux 开发模式

启动成功后,除了编辑器,你还能在应用内直接看到看板任务视图等完整功能:

Lokus 开发模式运行效果:Kanban 看板任务视图

四、编译 macOS/Windows/Linux 三大桌面安装包

开发验证通过后,用下面这些脚本即可产出正式安装包(脚本入口分别为 scripts/build-macos.js、scripts/build-windows.js、scripts/build-linux.js):

目标平台 命令 安装包格式 使用的配置文件
macOS npm run build:macos .dmg / .app tauri.macos.conf.json
Windows npm run build:windows .exe 安装器 tauri.windows.conf.json
Linux npm run build:linux .deb / .rpm / .AppImage tauri.conf.json
全部平台 npm run build:all 以上全部 自动切换

几个实用细节:

  • 产物位置:所有安装包统一输出在 src-tauri/target/release/bundle/ 下(dmg/、deb/、rpm/、appimage/ 等子目录);
  • App Store 版本:macOS 上架构建走独立命令 npm run build:appstore,会额外关闭更新检查并使用 tauri.appstore.conf.json;
  • 清理构建:npm run clean 可清空 dist/、src-tauri/target/ 及各平台缓存,环境异常时优先执行它重来;
  • 移动端:仓库同样支持 npm run dev:ios / npm run build:ios 进行 iOS 构建。

编译成功后,桌面端即拥有完整的知识图谱等全部功能:

编译后的 Lokus 桌面版:笔记知识图谱视图

五、Docker 构建 Linux 版:环境可复现的交叉编译

在非 Linux 机器上(比如 macOS)打包 Linux 安装包,直接装 GTK/WebKit 依赖很折腾。Lokus 的解决方案是把整套 Linux 构建环境做成 Docker 镜像:

一条命令即可完成(对应 package.json 中的 build:linux:docker):

npm run build:linux:docker

脚本内部做了三件事:

  1. 若本机没有 lokus-linux-builder 镜像,先自动 docker build;
  2. 挂载项目目录到容器内,依次执行 npm ci → npm run build(Vite 前端打包)→ cargo tauri build;
  3. 打印产物路径:src-tauri/target/release/bundle/ 下的 DEB、RPM、AppImage。

📦 在 macOS 上准备"全平台构建"环境,可以运行 npm run install:build:deps,它会一次性安装 Docker Desktop、cargo-xwin(Windows 交叉编译工具)和 Windows Rust target,并构建 Linux 构建镜像,见 scripts/install-build-deps.sh。

六、Docker Compose 部署自托管 AI 推理代理

Lokus 的云端 AI 能力由一个独立的推理代理服务(proxy/)提供:它负责 JWT 鉴权、按用户限流、额度扣减,并以 SSE 流式转发推理结果。整个服务栈只有 3 个容器,部署非常轻量:

Caddy (80/443, 自动 TLS)  →  proxy (Bun, 仅内网 :3000)  →  Redis (限流/幂等)

关键文件:

部署只需 3 步:

# 1. 进入代理目录,准备环境变量(切勿把真实密钥提交进仓库)
cd proxy
cp env.sample .env
# 编辑 .env:填写 SUPABASE_URL、SUPABASE_SERVICE_ROLE_KEY、
# ANTHROPIC_API_KEY、OPENAI_API_KEY、LOKUS_DEEPGRAM_KEY 等必填项

# 2. 修改 Caddyfile 中的站点域名为你自己的域名(默认 localhost)

# 3. 一键构建并启动全部服务
docker compose up --build

启动后验证服务健康:

curl -s localhost:3000/health
# 预期返回 {"status":"ok",...}

Redis 带健康检查(redis-cli ping),proxy 会等它就绪后再启动;Caddy 会自动申请 TLS 证书,无需额外配置。

七、常见问题速查表

现象 原因与解决
webkit2gtk not found(Linux) 缺少 WebKit 开发库,安装 libwebkit2gtk-4.0-dev(22.04+ 可换 4.1)
linker cc not found(Linux) 缺少编译工具链,安装 build-essential
cargo: command not found 将 ~/.cargo/bin 加入 PATH 并重启终端
首次编译极慢 / 内存不足 设置 export CARGO_BUILD_JOBS=2 限制并行任务数
构建结果异常、行为怪异 npm run clean 清空产物后重新 npm install 再构建

更多疑难杂症(如 Apple Silicon、WebView2、端口冲突)的完整排查清单,见 CONTRIBUTING.md 的 "Common Installation Issues & Solutions"。

八、总结

Lokus 的跨平台构建可以归纳为 4 条路径,按需选择即可:

场景 推荐方式
改代码、看效果 npm run tauri dev
本机产出当前平台安装包 npm run build:macos / build:windows / build:linux
在非 Linux 机器打包 Linux 版 npm run build:linux:docker
部署自托管 AI 代理 cd proxy && docker compose up --build

从一条 npm install 到 docker compose up,你现在已经掌握了 Lokus 从源码编译到生产部署的完整链路。

登录后查看全文
lokus