Lokus 跨平台构建与部署:从源码编译 macOS/Windows/Linux 到 Docker 构建完整指南
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/ |
前端构建由 Vite 完成(配置见 vite.config.js),Rust 侧的依赖声明在 src-tauri/Cargo.toml,而 Tauri 的全局配置(打包目标、图标、更新端点等)集中在 src-tauri/tauri.conf.json。其中 beforeBuildCommand 会自动先执行 npm run build,再打包桌面应用——所以你只需一条命令就能完成"前端 + 后端"的完整构建。
二、环境准备:macOS/Windows/Linux 依赖一键检查
开始编译前,先确认三类基础依赖:
- Node.js 18+(推荐 22)+ npm
- Rust 工具链(通过 rustup 安装,含 cargo)
- 平台专属系统库(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 开发模式
启动成功后,除了编辑器,你还能在应用内直接看到看板任务视图等完整功能:
四、编译 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 构建。
编译成功后,桌面端即拥有完整的知识图谱等全部功能:
五、Docker 构建 Linux 版:环境可复现的交叉编译
在非 Linux 机器上(比如 macOS)打包 Linux 安装包,直接装 GTK/WebKit 依赖很折腾。Lokus 的解决方案是把整套 Linux 构建环境做成 Docker 镜像:
- 镜像定义:docker/Dockerfile.linux-builder
基于 Ubuntu 22.04,预装
libgtk-3-dev、libwebkit2gtk-4.0/4.1-dev、Node.js 20、Rust 及 Tauri CLI; - 构建脚本:scripts/docker-build-linux.sh
一条命令即可完成(对应 package.json 中的 build:linux:docker):
npm run build:linux:docker
脚本内部做了三件事:
- 若本机没有
lokus-linux-builder镜像,先自动docker build; - 挂载项目目录到容器内,依次执行
npm ci→npm run build(Vite 前端打包)→cargo tauri build; - 打印产物路径:
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 (限流/幂等)
关键文件:
- proxy/Dockerfile:Bun 运行时镜像,多阶段构建,以非特权用户运行
- proxy/docker-compose.yml:编排 proxy + redis + caddy,proxy 仅暴露到内部桥接网络
- proxy/Caddyfile:反向代理配置,
flush_interval -1保证 SSE 流实时送达 - proxy/env.sample:环境变量模板
部署只需 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 从源码编译到生产部署的完整链路。


