tauri-deployment-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tauri Deployment Setup — Development Guide

Tauri部署搭建——开发指南

You are an expert on Tauri deployment pipelines. Use this knowledge when setting up CI/CD, configuring code signing, or integrating with the Oasis update server.

您是Tauri部署流水线方面的专家。在搭建CI/CD、配置代码签名或集成Oasis更新服务器时，请运用这些知识。

What It Is

系统介绍

A comprehensive deployment system for Tauri desktop applications that handles multi-platform builds, code signing, artifact storage, and automatic updates.

Reusable workflow:

porkytheblack/oasis/.github/workflows/tauri-release.yml@main

This project's workflow:

.github/workflows/release.yaml

这是一套针对Tauri桌面应用的完整部署系统，可处理多平台构建、代码签名、制品存储和自动更新。

可复用工作流：

porkytheblack/oasis/.github/workflows/tauri-release.yml@main

本项目工作流：

.github/workflows/release.yaml

Architecture at a Glance

架构概览

Developer pushes tag → GitHub Actions triggers
                              ↓
        ┌─────────────────────┴─────────────────────┐
        ↓                     ↓                     ↓
   macOS Build           Windows Build         Linux Build
   (Apple signed)        (optional sign)       (AppImage)
        ↓                     ↓                     ↓
        └─────────────────────┬─────────────────────┘
                              ↓
                    Tauri Update Signing
                              ↓
        ┌─────────────────────┼─────────────────────┐
        ↓                     ↓                     ↓
   Upload to R2         Register with Oasis    GitHub Release
   (CDN storage)        (update manifest)      (user downloads)

Developer pushes tag → GitHub Actions triggers
                              ↓
        ┌─────────────────────┴─────────────────────┐
        ↓                     ↓                     ↓
   macOS Build           Windows Build         Linux Build
   (Apple signed)        (optional sign)       (AppImage)
        ↓                     ↓                     ↓
        └─────────────────────┬─────────────────────┘
                              ↓
                    Tauri Update Signing
                              ↓
        ┌─────────────────────┼─────────────────────┐
        ↓                     ↓                     ↓
   Upload to R2         Register with Oasis    GitHub Release
   (CDN storage)        (update manifest)      (user downloads)

Quick Start

快速开始

1. Install dependencies

1. 安装依赖

bash

pnpm add -D @tauri-apps/cli

bash

pnpm add -D @tauri-apps/cli

2. Generate signing keys

2. 生成签名密钥

bash

npx @tauri-apps/cli signer generate -w ~/.tauri/keys/your-app.key

bash

npx @tauri-apps/cli signer generate -w ~/.tauri/keys/your-app.key

Save the public key for tauri.conf.json

Save the private key as TAURI_SIGNING_PRIVATE_KEY secret

undefined

undefined

3. Create release workflow

3. 创建发布工作流

yaml

undefined

yaml

undefined

.github/workflows/release.yaml

name: Release

on: push: tags: ["v*"]

permissions: contents: write

jobs: release: uses: porkytheblack/oasis/.github/workflows/tauri-release.yml@main with: app_slug: your-app app_name: Your App artifact_prefix: YourApp app_dir: app distribute_to: r2,oasis,github secrets: APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }} APPLE_CERTIFICATE_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }} APPLE_SIGNING_IDENTITY: ${{ secrets.APPLE_SIGNING_IDENTITY }} APPLE_ID: ${{ secrets.APPLE_ID }} APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }} APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }} TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }} TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }} CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }} CLOUDFLARE_R2_ACCESS_KEY_ID: ${{ secrets.CLOUDFLARE_R2_ACCESS_KEY_ID }} CLOUDFLARE_R2_SECRET_ACCESS_KEY: ${{ secrets.CLOUDFLARE_R2_SECRET_ACCESS_KEY }} R2_BUCKET_NAME: ${{ secrets.R2_BUCKET_NAME }} OASIS_SERVER_URL: ${{ secrets.OASIS_SERVER_URL }} OASIS_CI_KEY: ${{ secrets.OASIS_CI_KEY }}

undefined

name: Release

on: push: tags: ["v*"]

permissions: contents: write

undefined

4. Configure updater in tauri.conf.json

4. 在tauri.conf.json中配置更新器

json

{
  "plugins": {
    "updater": {
      "pubkey": "YOUR_PUBLIC_KEY_HERE",
      "endpoints": [
        "https://oasis.yourdomain.com/{app_slug}/update/{{target}}-{{arch}}/{{current_version}}"
      ]
    }
  }
}

json

{
  "plugins": {
    "updater": {
      "pubkey": "YOUR_PUBLIC_KEY_HERE",
      "endpoints": [
        "https://oasis.yourdomain.com/{app_slug}/update/{{target}}-{{arch}}/{{current_version}}"
      ]
    }
  }
}

5. Trigger release

5. 触发发布

bash

./app/scripts/bump-version.sh patch
git push && git push --tags

bash

./app/scripts/bump-version.sh patch
git push && git push --tags

Version Files to Sync

需要同步的版本文件

File	Format	Location
`package.json`	`"version": "X.Y.Z"`	App root
`tauri.conf.json`	`"version": "X.Y.Z"`	src-tauri/
`Cargo.toml`	`version = "X.Y.Z"`	src-tauri/
Status bar	`vX.Y.Z` display	UI component

Use

./app/scripts/bump-version.sh

to update all files automatically.

文件	格式	位置
`package.json`	`"version": "X.Y.Z"`	应用根目录
`tauri.conf.json`	`"version": "X.Y.Z"`	src-tauri/
`Cargo.toml`	`version = "X.Y.Z"`	src-tauri/
状态栏	`vX.Y.Z` 显示	UI组件

使用

./app/scripts/bump-version.sh

自动更新所有文件。

Distribution Targets

分发目标

Target	Purpose	When to Use
`github`	GitHub Releases page	User downloads, changelog
`r2`	Cloudflare R2 CDN	Fast artifact delivery
`oasis`	Update server	Auto-update manifests

Combine with comma:

distribute_to: r2,oasis,github

目标	用途	使用场景
`github`	GitHub Releases页面	用户下载、变更日志
`r2`	Cloudflare R2 CDN	快速制品分发
`oasis`	更新服务器	自动更新清单

使用逗号分隔组合：

distribute_to: r2,oasis,github

Required Secrets

所需密钥

Apple Code Signing (macOS)

Apple代码签名（macOS）

Secret	Description
`APPLE_CERTIFICATE`	Base64-encoded .p12 certificate
`APPLE_CERTIFICATE_PASSWORD`	Certificate password
`APPLE_SIGNING_IDENTITY`	e.g., "Developer ID Application: Your Name"
`APPLE_ID`	Apple ID email
`APPLE_PASSWORD`	App-specific password (not Apple ID password)
`APPLE_TEAM_ID`	10-character Team ID

密钥	说明
`APPLE_CERTIFICATE`	Base64编码的.p12证书
`APPLE_CERTIFICATE_PASSWORD`	证书密码
`APPLE_SIGNING_IDENTITY`	例如："Developer ID Application: Your Name"
`APPLE_ID`	Apple ID邮箱
`APPLE_PASSWORD`	应用专用密码（非Apple ID密码）
`APPLE_TEAM_ID`	10位团队ID

Tauri Update Signing

Tauri更新签名

Secret	Description
`TAURI_SIGNING_PRIVATE_KEY`	Private key from signer generate
`TAURI_SIGNING_PRIVATE_KEY_PASSWORD`	Password used during generation

密钥	说明
`TAURI_SIGNING_PRIVATE_KEY`	签名工具生成的私钥
`TAURI_SIGNING_PRIVATE_KEY_PASSWORD`	生成时设置的密码

Cloudflare R2

Secret	Description
`CLOUDFLARE_ACCOUNT_ID`	Account ID from dashboard
`CLOUDFLARE_R2_ACCESS_KEY_ID`	R2 API token ID
`CLOUDFLARE_R2_SECRET_ACCESS_KEY`	R2 API token secret
`R2_BUCKET_NAME`	Bucket name

密钥	说明
`CLOUDFLARE_ACCOUNT_ID`	控制台中的账户ID
`CLOUDFLARE_R2_ACCESS_KEY_ID`	R2 API令牌ID
`CLOUDFLARE_R2_SECRET_ACCESS_KEY`	R2 API令牌密钥
`R2_BUCKET_NAME`	存储桶名称

Oasis Server

Oasis服务器

Secret	Description
`OASIS_SERVER_URL`	e.g., `https://oasis.yourdomain.com`
`OASIS_CI_KEY`	CI authentication key

密钥	说明
`OASIS_SERVER_URL`	例如： `https://oasis.yourdomain.com`
`OASIS_CI_KEY`	CI认证密钥

Tauri Capabilities

Tauri权限

Add to

capabilities/default.json

json

{
  "permissions": [
    "core:default",
    "core:window:default",
    "core:window:allow-start-dragging",
    "shell:default",
    "shell:allow-open",
    "dialog:default",
    "fs:default",
    "http:default",
    "updater:default",
    "updater:allow-check",
    "updater:allow-download-and-install",
    "process:default",
    "process:allow-restart"
  ]
}

添加到

capabilities/default.json

：

json

{
  "permissions": [
    "core:default",
    "core:window:default",
    "core:window:allow-start-dragging",
    "shell:default",
    "shell:allow-open",
    "dialog:default",
    "fs:default",
    "http:default",
    "updater:default",
    "updater:allow-check",
    "updater:allow-download-and-install",
    "process:default",
    "process:allow-restart"
  ]
}

Release Commands (This Project)

发布命令（本项目）

Action	Command
Bump patch	`./app/scripts/bump-version.sh patch`
Bump minor	`./app/scripts/bump-version.sh minor`
Bump major	`./app/scripts/bump-version.sh major`
Set version	`./app/scripts/bump-version.sh --set 2.0.0`
Preview	`./app/scripts/bump-version.sh patch --dry-run`
Push release	`git push && git push --tags`
Redeploy	`./app/scripts/redeploy.sh`

操作	命令
升级补丁版本	`./app/scripts/bump-version.sh patch`
升级次版本	`./app/scripts/bump-version.sh minor`
升级主版本	`./app/scripts/bump-version.sh major`
设置版本	`./app/scripts/bump-version.sh --set 2.0.0`
预览	`./app/scripts/bump-version.sh patch --dry-run`
推送发布	`git push && git push --tags`
重新部署	`./app/scripts/redeploy.sh`

Common Gotchas

常见问题

Apple signing identity must match exactly — Copy the full name from Keychain Access, including "Developer ID Application:" prefix.
App-specific password, not Apple ID password — Generate at appleid.apple.com under Security → App-Specific Passwords.
Public key mismatch — If updates fail signature verification, regenerate keys and update both
```
tauri.conf.json
```
and the GitHub secret.
R2 public URL required — Set
```
R2_PUBLIC_URL
```
as a repository variable (not secret) for the CDN base URL.
Version mismatch breaks updates — All version files must match. Use the bump script, not manual edits.
Tag format matters — Workflow triggers on
```
v*
```
tags. Use
```
v0.1.0
```
, not
```
0.1.0
```
.
Workflow permissions — Ensure
```
contents: write
```
permission for creating GitHub releases.
macOS notarization takes time — Apple notarization can take 5-15 minutes. Don't cancel the workflow early.
Secrets are case-sensitive — Double-check secret names match exactly.
Dry run first — Use
```
workflow_dispatch
```
with
```
dry_run: true
```
to test without uploading.

Apple签名身份必须完全匹配 — 从钥匙串访问中复制完整名称，包括"Developer ID Application:"前缀。
使用应用专用密码，而非Apple ID密码 — 在appleid.apple.com的“安全”→“应用专用密码”中生成。
公钥不匹配 — 如果更新签名验证失败，请重新生成密钥并同时更新
```
tauri.conf.json
```
和GitHub密钥。
需要R2公开URL — 将
```
R2_PUBLIC_URL
```
设置为仓库变量（非密钥），作为CDN基础URL。
版本不匹配会导致更新失败 — 所有版本文件必须一致。使用升级脚本，不要手动编辑。
标签格式很重要 — 工作流在
```
v*
```
标签时触发。使用
```
v0.1.0
```
，而非
```
0.1.0
```
。
工作流权限 — 确保拥有
```
contents: write
```
权限以创建GitHub发布。
macOS公证需要时间 — Apple公证可能需要5-15分钟。不要提前取消工作流。
密钥区分大小写 — 仔细检查密钥名称是否完全匹配。
先进行试运行 — 使用
```
workflow_dispatch
```
并设置
```
dry_run: true
```
来测试，无需上传。