Thunderbolt部署避坑全记录

thunderbolt是Mozilla邮件客户端团队出的开源AI控制面板，2026年4月已有4341个GitHub stars。它支持所有主流平台（Web/iOS/Android/Mac/Linux/Windows），可以连接Ollama、llama.cpp或任何OpenAI兼容API。听起来很美好，但我花了整整两天才把它跑起来——过程中踩了5个真实的坑。

这篇文章不是入门教程，而是踩坑复盘。我假设你已经读过了官方文档，重点讲官方文档没写清楚的地方。每个坑都附上了真实的错误信息和排查方法。

坑1：用了Node.js而不是Bun

**症状**：npm install报错，或者bun tauri:dev直接失败

原因：thunderbolt的frontend和backend都要求Bun 1.2+，不支持Node.js。

这是最容易被忽略的坑。官方的quick-start.md开头就写了需要Bun，但很多开发者（包括我自己）习惯性地执行npm install，然后收获一堆奇奇怪怪的依赖错误。

# 错误做法：使用Node.js包管理器
npm install
# 或
yarn install

# 报错示例（取决于你的Node版本）：
# Error: @tauri-apps/cli@2.x requires Bun >= 1.2.0

# 正确做法：先确认安装了Bun
bun --version
# 如果版本低于1.2：
curl -fsSL https://bun.sh/install | bash
# 重新加载shell后：
bun --version  # 确认是1.2+
bun install

快速验证方法：

# 检查是否在正确的目录并且Bun可用
bun --version && ls package.json
# 输出应该类似：1.2.3 和 package.json存在

验证完Bun可用后，正常流程是：

git clone https://github.com/thunderbird/thunderbolt.git
cd thunderbolt
bun install
cd backend && bun install && cd ..
cp .env.example .env
cp backend/.env.example backend/.env

坑2：PostgreSQL容器端口5433而非默认的5432

**症状**：docker compose up显示postgres容器启动后立即退出；或者应用连不上数据库

原因：thunderbolt的docker-compose.yml里，PostgreSQL容器映射到了宿主机端口5433（内部仍然是5432），用于避免和本地可能存在的PostgreSQL冲突。

这是官方仓库deploy/docker-compose.yml中的实际配置：

postgres:
  image: postgres:18-alpine
  environment:
    POSTGRES_PASSWORD: postgres
    POSTGRES_DB: postgres
  ports:
    - "${POSTGRES_PORT:-5433}:5432"  # 注意这里是5433，不是5432

如果你有本地PostgreSQL运行在5432，这个设计很合理。但问题是：文档和配置文件里大量地方直接写的是5432，只有docker-compose.yml偷偷改成了5433。

排查方法：

# 1. 检查postgres容器状态
docker compose ps

# 如果看到 postgres exited (1)，查看日志：
docker compose logs postgres

# 2. 常见错误：端口已被占用
# docker-compose logs postgres 会显示：
# FATAL: could not create lock file "/var/run/postgresql/.s.PGSQL.5432.lock" : No such file or directory

# 3. 解决方法：修改.env中的端口配置
# 在 thunderbolt/deploy/.env 中添加：
POSTGRES_PORT=5433

# 4. 同时确认backend连接字符串也使用了正确端口
# backend/.env 中应该是：
DATABASE_URL=postgresql://postgres:postgres@localhost:5433/postgres
# 而不是：
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres

生产环境推荐：如果你已经有其他服务在用PostgreSQL，修改.env中的POSTGRES_PORT到一个不冲突的端口，然后同步更新DATABASE_URL。

坑3：忘记设置BETTER_AUTH_SECRET

症状：应用启动后注册/登录失败，或者所有用户共享同一个账户

**原因**：.env.example里有默认值BETTER_AUTH_SECRET=better-auth-secret-change-in-production-12345678901234567890。这个默认值在本地开发可以工作，但**多人访问或部署到服务器上时，如果SECRET相同，会有严重的安全问题**。

这个问题在GitHub Issue #771中有记录：Kubernetes部署时漏掉了BETTER_AUTH_SECRET环境变量，导致后端无法正常工作。

# 生成一个随机的SECRET（macOS/Linux）：
openssl rand -base64 32
# 输出类似：W9K3xL2pVN8mQrTlE5fH1sD6aJcM7nR4BvC8wGxT3kY=

# 生成后，在 backend/.env 中设置：
BETTER_AUTH_SECRET=W9K3xL2pVN8mQrTlE5fH1sD6aJcM7nR4BvC8wGxT3kY=

判断方法：应用日志中如果出现Error: Better Auth secret is not set or is too short，说明BETTER_AUTH_SECRET未设置或长度不足32字符。

另外，如果你在一台服务器上为多个团队成员部署thunderbolt，每人需要不同的BETTER_AUTH_SECRET值（或者使用OIDC模式做SSO认证）。默认SECRET会导致所有用户被识别为同一个会话。

坑4：PowerSync服务未启动导致多设备同步失效

症状：在手机和电脑上登录同一个账户，但数据不同步；或者每次打开应用都像全新安装

**原因**：thunderbolt的多设备同步依赖PowerSync服务（第3个docker容器），但快速入门指南里只写了make up命令，很多用户不知道还需要单独启动PowerSync。

正确的完整启动流程：

# 1. 先启动依赖服务（PostgreSQL + PowerSync）
make up
# 这实际上执行的是：
# docker compose -f powersync-service/docker-compose.yml up -d

# 2. 验证服务状态
make status
# 应该看到：postgres running, powersync running

# 3. 如果PowerSync没启动，手动启动：
cd powersync-service
docker compose up -d
cd ..

# 4. 确认PowerSync监听在8080端口
curl http://localhost:8080/health
# 正常响应：{"status":"ok"}

# 5. 然后才启动应用
bun run dev        # frontend on :5173
# 或 bun run backend (如果你只需要API)

在backend/.env中确保设置了PowerSync相关变量：

DATABASE_DRIVER=postgres
DATABASE_URL=postgresql://postgres:postgres@localhost:5433/postgres
POWERSYNC_URL=http://localhost:8080
POWERSYNC_JWT_SECRET=powersync-dev-secret-change-in-production

如果你暂时不需要多设备同步功能（单机使用），可以在backend/.env中注释掉PowerSync相关变量，使用本地Pglite驱动：

DATABASE_DRIVER=pglite
DATABASE_URL=.pglite/data
# POWERSYNC_URL=   # 注释掉这行

坑5：VITE_THUNDERBOLT_CLOUD_URL配置错误导致API请求全部失败

症状：界面显示正常，但发送消息时报"网络错误"或"连接服务器失败"；Network标签里所有API请求都返回404

**原因**：thunderbolt前端需要知道后端服务的地址，这个配置通过VITE_THUNDERBOLT_CLOUD_URL环境变量设置。默认值是http://localhost:8000/v1，但如果你的backend运行在不同的端口或域名，这个值必须同步更新。

# 在 frontend/.env 或 .env (项目根目录) 中设置：
VITE_THUNDERBOLT_CLOUD_URL=http://localhost:8000/v1

# 如果你修改了backend端口（例如改成8080）：
VITE_THUNDERBOLT_CLOUD_URL=http://localhost:8080/v1

# 如果你是远程服务器部署（假设IP是 203.0.113.42，frontend端口3000）：
VITE_THUNDERBOLT_CLOUD_URL=http://203.0.113.42:8000/v1
# 同时需要更新backend/.env中的：
TRUSTED_ORIGINS=http://203.0.113.42:3000
CORS_ORIGINS=http://203.0.113.42:3000
APP_URL=http://203.0.113.42:3000
BETTER_AUTH_URL=http://203.0.113.42:8000

排查方法：

# 1. 打开浏览器DevTools -> Network
# 2. 找一个失败的API请求，查看Request URL
# 3. 如果请求地址是 http://localhost:8000/v1/chat 这样的URL：
#    - 确认backend确实在8000端口运行：curl http://localhost:8000/v1/health
# 4. 如果backend正常运行，检查CORS错误：
#    - DevTools Console里看到类似：
#    "Access to fetch at 'http://localhost:8000' from origin 'http://localhost:5173'
#     has been blocked by CORS policy"
#    - 解决方案：在 backend/.env 中添加/修改：
CORS_ORIGINS=http://localhost:5173,http://localhost:3000

注意：这个问题在Nginx反向代理场景下更复杂，因为官方deploy/config/Nginx 性能调优.conf中后端地址是硬编码的（Issue #777），需要同时修改nginx配置和VITE_THUNDERBOLT_CLOUD_URL。

---

完整的正确部署流程

基于以上所有踩坑经验，完整的本地开发环境搭建流程如下：

# 1. 安装Bun（必须，Node.js不行）
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc  # 或重新打开终端

# 2. 克隆并安装
git clone https://github.com/thunderbird/thunderbolt.git
cd thunderbolt
bun install
cd backend && bun install && cd ..

# 3. 配置环境变量
cp .env.example .env
cp backend/.env.example backend/.env

# 编辑 backend/.env，设置以下必填项：
# BETTER_AUTH_SECRET=$(openssl rand -base64 32)
# ANTHROPIC_API_KEY=sk-...  (或OLLAMA_URL+其他API Key)
# DATABASE_DRIVER=postgres
# DATABASE_URL=postgresql://postgres:postgres@localhost:5433/postgres
# POWERSYNC_URL=http://localhost:8080

# 4. 启动依赖服务（必须）
docker compose -f powersync-service/docker-compose.yml up -d

# 5. 验证依赖服务
curl http://localhost:8080/health   # PowerSync健康检查
docker compose -f powersync-service/docker-compose.yml ps  # PostgreSQL状态

# 6. 启动frontend + backend
bun run dev

# 7. 访问 http://localhost:5173

总结：thunderbolt值不值得折腾

踩完这5个坑之后，thunderbolt实际上是一个相当完整的AI客户端。它最大的优点是不绑定任何特定AI服务商，可以同时连接Ollama（本地模型）、OpenAI、Anthropic、Mistral、Fireworks等多个provider，跨provider对比回答质量非常方便。

如果你主要是用Ollama跑本地模型，thunderbolt的跨平台UI比直接用curl命令体验好很多。但部署确实有门槛——它不是一个"下载即用"的产品，需要理解Docker、Bun、环境变量等概念。

适合人群：已有Ollama或其他AI API经验，想用统一界面管理多个模型/provider的开发者。

不适合人群：完全不懂Docker和命令行的用户（建议等官方推出托管版本）。

👉 立即参与：https://platform.minimaxi.com/subscribe/token-plan?code=E5yur9NOub&source=link