部署全栈 SSR 应用

Deploying a Full-Stack SSR App

可以将 Leptos 全栈 SSR 应用部署到任意数量的服务器或容器托管服务中。将 Leptos SSR 应用投入生产最简单的方法可能是使用 VPS 服务，并在虚拟机中原生运行 Leptos（点击此处查看更多详情）。或者，你可以将 Leptos 应用容器化，并在任何托管或云服务器上的 Podman 或 Docker 中运行。

It's possible to deploy Leptos fullstack, SSR apps to any number of server or container hosting services. The most simple way to get a Leptos SSR app into production might be to use a VPS service and either run Leptos natively in a VM (see here for more details). Alternatively, you could containerize your Leptos app and run it in Podman or Docker on any colocated or cloud server.

目前存在多种不同的部署设置和托管服务，总的来说，Leptos 本身与你使用的部署设置无关。考虑到部署目标的多样性，本页将介绍：

There are a multitude of different deployment setups and hosting services, and in general, Leptos itself is agnostic to the deployment setup you use. With this diversity of deployment targets in mind, on this page we will go over:

创建用于 Leptos SSR 应用的 Containerfile (或 Dockerfile)
使用 Dockerfile 部署到云服务 —— 例如 Fly.io
将 Leptos 部署到无服务器运行时 (serverless runtimes) —— 例如 AWS Lambda 以及像 Deno 和 Cloudflare 这样托管 JS 的 WASM 运行时
尚未获得 Leptos SSR 支持的平台
creating a Containerfile (or Dockerfile) for use with Leptos SSR apps
Using a Dockerfile to deploy to a cloud service - for example, Fly.io
Deploying Leptos to serverless runtimes - for example, AWS Lambda and JS-hosted WASM runtimes like Deno & Cloudflare
Platforms that have not yet gained Leptos SSR support

注意：Leptos 不认可使用任何特定的部署方法或托管服务。

Note: Leptos does not endorse the use of any particular method of deployment or hosting service.

创建 Containerfile

Creating a Containerfile

人们部署使用 cargo-leptos 构建的全栈应用最流行的方式是使用支持通过 Podman 或 Docker 构建部署的云托管服务。这是一个示例 Containerfile / Dockerfile，它基于我们用于部署 Leptos 网站的文件。

The most popular way for people to deploy full-stack apps built with cargo-leptos is to use a cloud hosting service that supports deployment via a Podman or Docker build. Here’s a sample Containerfile / Dockerfile, which is based on the one we use to deploy the Leptos website.

Debian

# 使用 Rust nightly 构建环境开始
# Get started with a build env with Rust nightly
FROM rustlang/rust:nightly-trixie as builder

# 如果你使用的是 stable，请改用这个
# If you’re using stable, use this instead
# FROM rust:1.92.0-trixie as builder # 在此处查看当前的官方 Rust 标签：https://hub.docker.com/_/rust
# FROM rust:1.92.0-trixie as builder # See current official Rust tags here: https://hub.docker.com/_/rust

# 安装 cargo-binstall，它可以更轻松地安装其他 cargo 扩展，如 cargo-leptos
# Install cargo-binstall, which makes it easier to install other
# cargo extensions like cargo-leptos
RUN wget https://github.com/cargo-bins/cargo-binstall/releases/latest/download/cargo-binstall-x86_64-unknown-linux-musl.tgz
RUN tar -xvf cargo-binstall-x86_64-unknown-linux-musl.tgz
RUN cp cargo-binstall /usr/local/cargo/bin

# 安装所需工具
# Install required tools
RUN apt-get update -y \
  && apt-get install -y --no-install-recommends clang

# 安装 cargo-leptos
# Install cargo-leptos
RUN cargo binstall cargo-leptos -y

# 添加 WASM 目标
# Add the WASM target
RUN rustup target add wasm32-unknown-unknown

# 创建 /app 目录，所有内容最终都将存放在这里
# Make an /app dir, which everything will eventually live in
RUN mkdir -p /app
WORKDIR /app
COPY . .

# 构建应用
# Build the app
RUN cargo leptos build --release -vv

FROM debian:trixie-slim as runtime
WORKDIR /app
RUN apt-get update -y \
  && apt-get install -y --no-install-recommends openssl ca-certificates \
  && apt-get autoremove -y \
  && apt-get clean -y \
  && rm -rf /var/lib/apt/lists/*

# -- 注意：将二进制文件名从 "leptos_start" 更新为 Cargo.toml 中的应用名称 --
# -- NB: update binary name from "leptos_start" to match your app name in Cargo.toml --
# 将服务端二进制文件复制到 /app 目录
# Copy the server binary to the /app directory
COPY --from=builder /app/target/release/leptos_start /app/

# /target/site 包含我们的 JS/WASM/CSS 等文件
# /target/site contains our JS/WASM/CSS, etc.
COPY --from=builder /app/target/site /app/site

# 如果运行时需要，复制 Cargo.toml
# Copy Cargo.toml if it’s needed at runtime
COPY --from=builder /app/Cargo.toml /app/

# 设置任何所需的环境变量
# Set any required env variables and
ENV RUST_LOG="info"
ENV LEPTOS_SITE_ADDR="0.0.0.0:8080"
ENV LEPTOS_SITE_ROOT="site"
EXPOSE 8080

# -- 注意：将二进制文件名从 "leptos_start" 更新为 Cargo.toml 中的应用名称 --
# -- NB: update binary name from "leptos_start" to match your app name in Cargo.toml --
# 运行服务器
# Run the server
CMD ["/app/leptos_start"]

Alpine

# 使用 Rust nightly 构建环境开始
# Get started with a build env with Rust nightly
FROM rustlang/rust:nightly-alpine as builder

RUN apk update && \
    apk add --no-cache bash curl npm libc-dev binaryen

RUN npm install -g sass

RUN curl --proto '=https' --tlsv1.3 -LsSf https://github.com/leptos-rs/cargo-leptos/releases/latest/download/cargo-leptos-installer.sh | sh

# 添加 WASM 目标
# Add the WASM target
RUN rustup target add wasm32-unknown-unknown

WORKDIR /work
COPY . .

RUN cargo leptos build --release -vv

FROM rustlang/rust:nightly-alpine as runner

WORKDIR /app

COPY --from=builder /work/target/release/leptos_start /app/
COPY --from=builder /work/target/site /app/site
COPY --from=builder /work/Cargo.toml /app/

ENV RUST_LOG="info"
ENV LEPTOS_SITE_ADDR="0.0.0.0:8080"
ENV LEPTOS_SITE_ROOT=./site
EXPOSE 8080

CMD ["/app/leptos_start"]

延伸阅读：针对 Leptos 应用的 gnu 和 musl 构建文件。

Read more: gnu and musl build files for Leptos apps.

关于反向代理的说明

A Note on Reverse Proxies

虽然你可以直接暴露你的 Leptos 应用，但通常最好将其放在反向代理之后。这允许你在专用层处理 SSL/TLS、压缩和安全标头，而不是在 Rust 二进制文件中处理。

While you can expose your Leptos app directly, it's usually better to put it behind a reverse proxy. This allows you to handle SSL/TLS, compression, and security headers in a dedicated layer rather than in your Rust binary.

有几种流行的反向代理选项。Caddy 常因其自动 HTTPS 证书管理而被选中，而 Nginx、Traefik 或 Apache 也被广泛使用，具体取决于你的需求和熟悉程度。

There are several popular reverse proxy options. Caddy is often chosen for its automatic HTTPS certificate management, while Nginx, Traefik, or Apache are also widely used depending on your requirements and familiarity.

如果你使用 Caddy，你的配置可以简单到将域名指向你的容器名称或 IP：

If you are using Caddy, your configuration can be as simple as pointing a domain to your container name or IP:

# 简单配置
# Simple setup
example.com {
    reverse_proxy leptos-app:8080
}

# 进阶：基础认证和 HSTS 标头
# Advanced: Basic auth and HSTS headers
app.example.com {
    # 使用基础认证保护预发布站点
    # Protect a staging site with basic auth
    basic_auth {
        admin $2a$14$CIW9S... 
    }
    
    header {
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
    }

    reverse_proxy leptos-app:8080
}

有关更多详细信息，请参阅 Caddy 反向代理快速入门和 Caddyfile 概念文档等资源。

For more details, see the Caddy Reverse Proxy Quick-start and the Caddyfile concept documentation, among other resources.

云端部署

Cloud Deployments

部署到 Fly.io

Deploy to Fly.io

部署 Leptos SSR 应用的一个选择是使用 Fly.io 这样的服务，它采用 Leptos 应用的 Dockerfile 定义，并将其运行在快速启动的微型虚拟机（micro-VM）中；Fly 还提供多种存储选项和托管数据库供你的项目使用。以下示例将展示如何部署一个简单的 Leptos 入门应用，仅供你上手使用；如果需要，请点击此处查看有关在 Fly.io 上使用存储选项的更多信息。

One option for deploying your Leptos SSR app is to use a service like Fly.io, which takes a Dockerfile definition of your Leptos app and runs it in a quick-starting micro-VM; Fly also offers a variety of storage options and managed DBs to use with your projects. The following example will show how to deploy a simple Leptos starter app, just to get you up and going; see here for more about working with storage options on Fly.io if and when required.

首先，在应用的根目录中创建一个 Dockerfile 并填入建议的内容（见上文）；确保将 Dockerfile 示例中的二进制文件名更新为你自己应用的文件名，并根据需要进行其他调整。

First, create a Dockerfile in the root of your application and fill it in with the suggested contents (above); make sure to update the binary names in the Dockerfile example to the name of your own application, and make other adjustments as necessary.

此外，请确保你已经安装了 flyctl 命令行工具，并已在 Fly.io 上注册了账户。要在 MacOS、Linux 或 Windows WSL 上安装 flyctl，请运行：

Also, ensure you have the flyctl CLI tool installed, and have an account set up at Fly.io. To install flyctl on MacOS, Linux, or Windows WSL, run:

curl -L https://fly.io/install.sh | sh

如果你遇到问题，或者要在其他平台上安装，请参阅此处的完整说明。

If you have issues, or for installing to other platforms see the full instructions here

然后登录 Fly.io：

Then login to Fly.io

fly auth login

并使用以下命令手动启动你的应用：

and manually launch your app using the command

fly launch

flyctl 命令行工具将引导你完成将应用部署到 Fly.io 的过程。

The flyctl CLI tool will walk you through the process of deploying your app to Fly.io.

:::admonish note title="注意" 默认情况下，Fly.io 会自动停止在一段时间内没有流量的机器。虽然 Fly.io 的轻量级虚拟机启动很快，但如果你想最大限度地减少 Leptos 应用的延迟并确保其始终响应迅速，请进入生成的 fly.toml 文件，将 min_machines_running 从默认的 0 更改为 1。

有关更多详细信息，请参阅 Fly.io 文档中的此页面。

:::

Note

By default, Fly.io will auto-stop machines that don't have traffic coming to them after a certain period of time. Although Fly.io's lightweight VM's start up quickly, if you want to minimize the latency of your Leptos app and ensure it's always swift to respond, go into the generated fly.toml file and change the min_machines_running to 1 from the default of 0.

See this page in the Fly.io docs for more details.

如果你更喜欢使用 Github Actions 来管理部署，你需要通过 Fly.io Web 界面创建一个新的访问令牌。

If you prefer to use Github Actions to manage your deployments, you will need to create a new access token via the Fly.io web UI.

转到 "Account" > "Access Tokens" 并创建一个名为 "github_actions" 之类的令牌，然后通过进入你项目的 Github 仓库，点击 "Settings" > "Secrets and Variables" > "Actions" 并创建一个名为 "FLY_API_TOKEN" 的 "New repository secret"，将该令牌添加到仓库的机密信息中。

Go to "Account" > "Access Tokens" and create a token named something like "github_actions", then add the token to your Github repo's secrets by going into your project's Github repo, then clicking "Settings" > "Secrets and Variables" > "Actions" and creating a "New repository secret" with the name "FLY_API_TOKEN".

要生成用于部署到 Fly.io 的 fly.toml 配置文件，你必须首先在项目源目录中运行以下命令：

To generate a fly.toml config file for deployment to Fly.io, you must first run the following from within the project source directory

fly launch --no-deploy

以此创建一个新的 Fly 应用并将其注册到服务中。Git 提交你新生成的 fly.toml 文件。

to create a new Fly app and register it with the service. Git commit your new fly.toml file.

要设置 Github Actions 部署工作流，请将以下内容复制到 .github/workflows/fly_deploy.yml 文件中：

To set up the Github Actions deployment workflow, copy the following into a .github/workflows/fly_deploy.yml file:

示例

# 更多详情请参阅：https://fly.io/docs/app-guides/continuous-deployment-with-github-actions/
# For more details, see: https://fly.io/docs/app-guides/continuous-deployment-with-github-actions/

name: Deploy to Fly.io
on:
push:
	branches:
	- main
jobs:
deploy:
	name: Deploy app
	runs-on: ubuntu-latest
	steps:
	- uses: actions/checkout@v4
	- uses: superfly/flyctl-actions/setup-flyctl@master
	- name: Deploy to fly
		id: deployment
		run: |
		  flyctl deploy --remote-only | tail -n 1 >> $GITHUB_STEP_SUMMARY
		env:
		  FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

下次提交到 Github 的 main 分支时，你的项目将自动部署到 Fly.io。

On the next commit to your Github main branch, your project will automatically deploy to Fly.io.

查看此处的示例仓库。

See the example repo here.

Railway

云端部署的另一个提供商是 Railway。Railway 与 GitHub 集成以自动部署你的代码。

Another provider for cloud deployments is Railway. Railway integrates with GitHub to automatically deploy your code.

有一个预配置好的社区模板可以帮助你快速开始：

There is an opinionated community template that gets you started quickly:

该模板配置了 renovate 以保持依赖项最新，并支持 GitHub Actions 以在部署发生之前测试你的代码。

The template has renovate setup to keep dependencies up to date and supports GitHub Actions to test your code before a deploy happens.

Railway 提供不需要信用卡的免费层级，考虑到 Leptos 所需资源非常少，该免费层级应该可以持续很长时间。

Railway has a free tier that does not require a credit card, and with how little resources Leptos needs that free tier should last a long time.

查看此处的示例仓库。

See the example repo here.

部署到无服务器运行时

Deploy to Serverless Runtimes

Leptos 支持部署到 FaaS（函数即服务）或“无服务器（serverless）”运行时，如 AWS Lambda，以及兼容 WinterCG 的 JS 运行时，如 Deno 和 Cloudflare。请注意，与虚拟机或容器类型部署相比，无服务器环境确实会对 SSR 应用的可用功能施加一些限制（见下文说明）。

Leptos supports deploying to FaaS (Function as a Service) or 'serverless' runtimes such as AWS Lambda as well as WinterCG-compatible JS runtimes such as Deno and Cloudflare. Just be aware that serverless environments do place some restrictions on the functionality available to your SSR app when compared with VM or container type deployments (see notes, below).

AWS Lambda

在 Cargo Lambda 工具的帮助下，Leptos SSR 应用可以部署到 AWS Lambda。在 leptos-rs/start-aws 提供了一个使用 Axum 作为服务器的入门模板仓库；那里的说明也可以调整为你使用 Leptos+Actix-web 服务器。入门仓库包括用于 CI/CD 的 Github Actions 脚本，以及设置 Lambda 函数和获取云部署所需凭据的说明。

With a little help from the Cargo Lambda tool, Leptos SSR apps can be deployed to AWS Lambda. A starter template repo using Axum as the server is available at leptos-rs/start-aws; the instructions there can be adapted for you to use a Leptos+Actix-web server as well. The starter repo includes a Github Actions script for CI/CD, as well as instructions for setting up your Lambda functions and getting the necessary credentials for cloud deployment.

然而，请记住，一些原生服务器功能在 Lambda 等 FaaS 服务中无法使用，因为环境在不同请求之间不一定是一致的。特别是，'start-aws' 文档指出，“由于 AWS Lambda 是一个无服务器平台，你需要更加小心地管理长期存在的状态。写入磁盘或使用状态提取器在跨请求时无法可靠工作。相反，你需要一个数据库或其他微服务，你可以从 Lambda 函数中查询。”

However, please keep in mind that some native server functionality does not work with FaaS services like Lambda because the environment is not necessarily consistent from one request to the next. In particular, the 'start-aws' docs state that "since AWS Lambda is a serverless platform, you'll need to be more careful about how you manage long-lived state. Writing to disk or using a state extractor will not work reliably across requests. Instead, you'll need a database or other microservices that you can query from the Lambda function."

另一个需要牢记的因素是函数即服务的“冷启动”时间 —— 取决于你的用例和你使用的 FaaS 平台，这可能满足也可能无法满足你的延迟要求；你可能需要让一个函数始终运行，以优化请求速度。

The other factor to bear in mind is the 'cold-start' time for functions as a service - depending on your use case and the FaaS platform you use, this may or may not meet your latency requirements; you may need to keep one function running at all times to optimize the speed of your requests.

Deno & Cloudflare Workers

目前，Leptos-Axum 支持在托管 Javascript 的 WebAssembly 运行时（如 Deno、Cloudflare Workers 等）中运行。此选项需要对源代码设置进行一些更改（例如，在 Cargo.toml 中，你必须使用 crate-type = ["cdylib"] 定义应用，并且必须为 leptos_axum 启用 "wasm" 特性）。Leptos HackerNews JS-fetch 示例演示了所需的修改，并展示了如何在 Deno 运行时运行应用。此外，在为托管 JS 的 WASM 运行时设置自己的 Cargo.toml 文件时，leptos_axum crate 文档也是一个很有帮助的参考。

Currently, Leptos-Axum supports running in Javascript-hosted WebAssembly runtimes such as Deno, Cloudflare Workers, etc. This option requires some changes to the setup of your source code (for example, in Cargo.toml you must define your app using crate-type = ["cdylib"] and the "wasm" feature must be enabled for leptos_axum). The Leptos HackerNews JS-fetch example demonstrates the required modifications and shows how to run an app in the Deno runtime. Additionally, the leptos_axum crate docs are a helpful reference when setting up your own Cargo.toml file for JS-hosted WASM runtimes.

虽然托管 JS 的 WASM 运行时的初始设置并不繁重，但需要牢记的更重要的限制是，由于你的应用在服务端和客户端都将被编译为 WebAssembly (wasm32-unknown-unknown)，你必须确保你在应用中使用的 crate 都是兼容 WASM 的；根据你应用的需求，这可能是也可能不是一个决定性因素，因为 Rust 生态系统中的所有 crate 并不都支持 WASM。

While the initial setup for JS-hosted WASM runtimes is not onerous, the more important restriction to keep in mind is that since your app will be compiled to WebAssembly (wasm32-unknown-unknown) on the server as well as the client, you must ensure that the crates you use in your app are all WASM-compatible; this may or may not be a deal-breaker depending on your app's requirements, as not all crates in the Rust ecosystem have WASM support.

如果你愿意接受 WASM 在服务端的局限性，目前开始的最佳地点是查看官方 Leptos Github 仓库中在 Deno 中运行 Leptos 的示例。

If you're willing to live with the limitations of WASM server-side, the best place to get started right now is by checking out the example of running Leptos with Deno in the official Leptos Github repo.

正在适配 Leptos 的平台

Platforms Working on Leptos Support

部署到 Spin Serverless WASI (带有 Leptos SSR)

Deploy to Spin Serverless WASI (with Leptos SSR)

服务端的 WebAssembly 最近势头强劲，开源无服务器 WebAssembly 框架 Spin 的开发人员正在努力原生支持 Leptos。虽然 Leptos-Spin SSR 集成仍处于早期阶段，但有一个你可以尝试的运行示例。

WebAssembly on the server has been gaining steam lately, and the developers of the open source serverless WebAssembly framework Spin are working on natively supporting Leptos. While the Leptos-Spin SSR integration is still in its early stages, there is a working example you may wish to try out.

在 Fermyon 博客上的一篇文章中提供了让 Leptos SSR 和 Spin 协同工作的完整说明，或者如果你想跳过文章直接开始尝试一个运行正常的入门仓库，请点击此处。

The full set of instructions to get Leptos SSR & Spin working together are available as a post on the Fermyon blog, or if you want to skip the article and just start playing around with a working starter repo, see here.

部署到 Shuttle.rs

Deploy to Shuttle.rs

几位 Leptos 用户询问了使用对 Rust 友好的 Shuttle.rs 服务部署 Leptos 应用的可能性。不幸的是，目前 Shuttle.rs 服务尚未正式支持 Leptos。

Several Leptos users have asked about the possibility of using the Rust-friendly Shuttle.rs service to deploy Leptos apps. Unfortunately, Leptos is not officially supported by the Shuttle.rs service at the moment.

然而，Shuttle.rs 的团队致力于在未来提供 Leptos 支持；如果你想了解该工作的最新进展，请关注这个 Github issue。

However, the folks at Shuttle.rs are committed to getting Leptos support in the future; if you would like to keep up-to-date on the status of that work, keep an eye on this Github issue.

此外，虽然有人在尝试让 Shuttle 与 Leptos 配合工作，但到目前为止，向 Shuttle 云的部署仍未按预期工作。如果你想亲自调查或贡献修复，该工作可以从此处获得：针对 Shuttle.rs 的 Leptos Axum 入门模板。

Additionally, some effort has been made to get Shuttle working with Leptos, but to date, deploys to the Shuttle cloud are still not working as expected. That work is available here, if you would like to investigate for yourself or contribute fixes: Leptos Axum Starter Template for Shuttle.rs.

Keyboard shortcuts