> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 如何托管 FastAPI 应用

> 了解如何在 Square Cloud 上创建并托管 FastAPI 应用。

export const PortNote = ({lang}) => {
  const t = {
    'en': {
      q: 'What port should I use for my server?',
      a1: <>You should use port <b>80</b> for your server. Port 80 is the default port for HTTP traffic, which is handled by Square Cloud to route it to 443, HTTPS, for a secure connection.</>,
      a2: 'Make sure to configure it before compressing and uploading your project.'
    },
    'pt-br': {
      q: 'Qual porta devo usar para o meu servidor?',
      a1: <>Você deve usar a porta <b>80</b> para o seu servidor. A porta 80 é a porta padrão para tráfego HTTP; a Square Cloud a encaminha para 443 (HTTPS) para estabelecer uma conexão segura.</>,
      a2: 'Certifique-se de configurá-la antes de compactar e enviar seu projeto.'
    },
    'es': {
      q: '¿Qué puerto debo usar para mi servidor?',
      a1: <>Debes usar el puerto <b>80</b> para tu servidor. El puerto 80 es el puerto predeterminado para el tráfico HTTP; Square Cloud lo redirige al 443 (HTTPS) para establecer una conexión segura.</>,
      a2: 'Asegúrate de configurarlo antes de comprimir y subir tu proyecto.'
    },
    'fr': {
      q: 'Quel port dois-je utiliser pour mon serveur ?',
      a1: <>Vous devez utiliser le port <b>80</b> pour votre serveur. Le port 80 est le port par défaut du trafic HTTP ; Square Cloud le redirige vers le port 443 (HTTPS) pour établir une connexion sécurisée.</>,
      a2: "Assurez-vous de le configurer avant de compresser et d'envoyer votre projet."
    },
    'de': {
      q: 'Welchen Port sollte ich für meinen Server verwenden?',
      a1: <>Verwenden Sie Port <b>80</b> für Ihren Server. Port 80 ist der Standardport für HTTP-Traffic; Square Cloud leitet ihn für eine sichere Verbindung an Port 443 (HTTPS) weiter.</>,
      a2: 'Stellen Sie sicher, dass Sie ihn konfigurieren, bevor Sie Ihr Projekt komprimieren und hochladen.'
    },
    'it': {
      q: 'Quale porta devo usare per il mio server?',
      a1: <>Devi usare la porta <b>80</b> per il tuo server. La porta 80 è la porta predefinita per il traffico HTTP; Square Cloud la instrada verso la 443 (HTTPS) per stabilire una connessione sicura.</>,
      a2: 'Assicurati di configurarla prima di comprimere e caricare il tuo progetto.'
    },
    'ja': {
      q: 'サーバーにはどのポートを使えばよいですか？',
      a1: <>サーバーにはポート<b>80</b>を使用してください。ポート80はHTTPトラフィックのデフォルトポートで、Square Cloudが安全な接続のために443（HTTPS）へルーティングします。</>,
      a2: 'プロジェクトを圧縮してアップロードする前に、必ず設定してください。'
    },
    'zh': {
      q: '我的服务器应该使用哪个端口？',
      a1: <>您的服务器应使用端口 <b>80</b>。端口 80 是 HTTP 流量的默认端口，Square Cloud 会将其路由到 443（HTTPS）以建立安全连接。</>,
      a2: '请务必在压缩并上传项目之前完成配置。'
    }
  };
  const c = t[lang] || t['en'];
  return <Note>
            <b>{c.q}</b><br />
            {c.a1}<br />
            {c.a2}
        </Note>;
};

export const PyDepFiles = ({lang}) => {
  const desc = {
    "en": {
      requirements: "Standard file used in Python projects to list all the external libraries and dependencies that your project needs. Each line in this file specifies a package to be installed using pip, the Python package manager.",
      pyproject: "A modern configuration file for Python projects that can specify build system requirements and project metadata. It is used by tools like Poetry to manage dependencies and packaging."
    },
    "pt-br": {
      requirements: "Arquivo padrão usado em projetos Python para listar todas as bibliotecas externas e dependências necessárias para o seu projeto. Cada linha neste arquivo especifica um pacote a ser instalado usando o pip, o gerenciador de pacotes do Python",
      pyproject: "Um arquivo de configuração moderno para projetos Python que permite especificar requisitos do sistema de compilação e metadados do projeto. É utilizado por ferramentas como o Poetry para gerenciar dependências e empacotamento."
    },
    "es": {
      requirements: "Archivo estándar usado en proyectos Python para listar todas las bibliotecas externas y dependencias que tu proyecto necesita. Cada línea de este archivo especifica un paquete que se instalará usando pip, el gestor de paquetes de Python.",
      pyproject: "Un archivo de configuración moderno para proyectos Python que permite especificar los requisitos del sistema de compilación y los metadatos del proyecto. Lo utilizan herramientas como Poetry para gestionar dependencias y empaquetado."
    },
    "fr": {
      requirements: "Fichier standard utilisé dans les projets Python pour lister toutes les bibliothèques externes et dépendances nécessaires à votre projet. Chaque ligne de ce fichier spécifie un paquet à installer avec pip, le gestionnaire de paquets de Python.",
      pyproject: "Un fichier de configuration moderne pour les projets Python qui permet de spécifier les exigences du système de build et les métadonnées du projet. Il est utilisé par des outils comme Poetry pour gérer les dépendances et le packaging."
    },
    "de": {
      requirements: "Standarddatei in Python-Projekten, die alle externen Bibliotheken und Abhängigkeiten Ihres Projekts auflistet. Jede Zeile dieser Datei gibt ein Paket an, das mit pip, dem Paketmanager von Python, installiert wird.",
      pyproject: "Eine moderne Konfigurationsdatei für Python-Projekte, die Build-System-Anforderungen und Projektmetadaten festlegen kann. Sie wird von Tools wie Poetry zur Verwaltung von Abhängigkeiten und Packaging verwendet."
    },
    "it": {
      requirements: "File standard usato nei progetti Python per elencare tutte le librerie esterne e le dipendenze necessarie al tuo progetto. Ogni riga di questo file specifica un pacchetto da installare con pip, il gestore di pacchetti di Python.",
      pyproject: "Un file di configurazione moderno per i progetti Python che consente di specificare i requisiti del sistema di build e i metadati del progetto. È utilizzato da strumenti come Poetry per gestire dipendenze e packaging."
    },
    "ja": {
      requirements: "Python プロジェクトで、必要な外部ライブラリと依存関係をすべて列挙するための標準ファイルです。このファイルの各行は、Python のパッケージマネージャーである pip でインストールするパッケージを指定します。",
      pyproject: "ビルドシステムの要件やプロジェクトのメタデータを指定できる、Python プロジェクト向けのモダンな設定ファイルです。Poetry などのツールが依存関係とパッケージングの管理に使用します。"
    },
    "zh": {
      requirements: "Python 项目中用于列出项目所需的所有外部库和依赖项的标准文件。文件中的每一行指定一个通过 pip（Python 的包管理器）安装的包。",
      pyproject: "Python 项目的现代配置文件，可指定构建系统要求和项目元数据。Poetry 等工具使用它来管理依赖项和打包。"
    }
  };
  const d = desc[lang] || desc.en;
  return <CardGroup cols={2}>
            <Card title="requirements.txt" icon="file-lines" href="../../articles/how-to-create-your-requirements">
            {d.requirements}
            </Card>
            <Card title="pyproject.toml" icon="file" href="../../articles/how-to-create-your-pyproject">
            {d.pyproject}
            </Card>
        </CardGroup>;
};

export const RecommendedPlan = ({lang, plan, tier, cpu, appType}) => {
  const siteLang = lang === 'pt-br' ? 'pt-br' : 'en';
  const url = `https://squarecloud.app/${siteLang}/pay?plan=${plan.toLowerCase()}&tier=${tier}`;
  const proUrl = `https://squarecloud.app/${siteLang}/pay?plan=pro`;
  const notes = {
    'en': <Note>
        <b>Wondering how much RAM and CPU your plan needs to host {appType}?</b><br />
        Don't worry, we're here to help.
        Our <a href={url}>{plan}</a> plan offers <b>{tier}GB</b> of RAM and <b>{cpu}vCPU</b>, which should be sufficient for most {appType}.
        However, if you are working on a larger project and seeking extra stability, we recommend considering our <b>Pro</b> plan. With additional resources, you can maintain stability even during demand spikes.
        To purchase, simply click <a href={proUrl}>here</a>.
      </Note>,
    'pt-br': <Note>
        <b>Está se perguntando quanta RAM e CPU seu plano precisa para hospedar {appType}?</b><br />
        Não se preocupe, estamos aqui para ajudar.
        Nosso plano <a href={url}>{plan}</a> oferece <b>{tier}GB</b> de RAM e <b>{cpu}vCPU</b>, o que deve ser suficiente para a maioria dos {appType}.
        No entanto, se você estiver trabalhando em um projeto maior e precisar de mais estabilidade, recomendamos considerar nosso plano <b>Pro</b>.
        Com recursos adicionais, você pode manter a estabilidade mesmo durante picos de demanda.
        Para comprar, basta clicar <a href={proUrl}>aqui</a>.
      </Note>,
    'es': <Note>
        <b>¿Te preguntas cuánta RAM y CPU necesita tu plan para alojar {appType}?</b><br />
        No te preocupes, estamos aquí para ayudarte.
        Nuestro plan <a href={url}>{plan}</a> ofrece <b>{tier}GB</b> de RAM y <b>{cpu}vCPU</b>, lo que debería ser suficiente para la mayoría de {appType}.
        Sin embargo, si estás trabajando en un proyecto más grande y buscas mayor estabilidad, te recomendamos considerar nuestro plan <b>Pro</b>.
        Con recursos adicionales, puedes mantener la estabilidad incluso durante picos de demanda.
        Para comprarlo, simplemente haz clic <a href={proUrl}>aquí</a>.
      </Note>,
    'fr': <Note>
        <b>Vous vous demandez combien de RAM et de CPU votre plan doit offrir pour héberger {appType} ?</b><br />
        Pas d'inquiétude, nous sommes là pour vous aider.
        Notre plan <a href={url}>{plan}</a> offre <b>{tier} Go</b> de RAM et <b>{cpu} vCPU</b>, ce qui devrait suffire pour la plupart des {appType}.
        Cependant, si vous travaillez sur un projet plus important et recherchez une stabilité accrue, nous vous recommandons notre plan <b>Pro</b>.
        Avec des ressources supplémentaires, vous conservez la stabilité même lors des pics de demande.
        Pour l'acheter, cliquez simplement <a href={proUrl}>ici</a>.
      </Note>,
    'de': <Note>
        <b>Sie fragen sich, wie viel RAM und CPU Ihr Plan zum Hosten von {appType} benötigt?</b><br />
        Keine Sorge, wir helfen Ihnen gerne.
        Unser <a href={url}>{plan}</a>-Plan bietet <b>{tier} GB</b> RAM und <b>{cpu} vCPU</b>, was für die meisten {appType} ausreichen sollte.
        Wenn Sie jedoch an einem größeren Projekt arbeiten und zusätzliche Stabilität benötigen, empfehlen wir unseren <b>Pro</b>-Plan.
        Mit zusätzlichen Ressourcen bleibt Ihre Anwendung auch bei Lastspitzen stabil.
        Zum Kauf klicken Sie einfach <a href={proUrl}>hier</a>.
      </Note>,
    'it': <Note>
        <b>Ti stai chiedendo quanta RAM e CPU serve al tuo piano per ospitare {appType}?</b><br />
        Non preoccuparti, siamo qui per aiutarti.
        Il nostro piano <a href={url}>{plan}</a> offre <b>{tier}GB</b> di RAM e <b>{cpu}vCPU</b>, che dovrebbero essere sufficienti per la maggior parte di {appType}.
        Tuttavia, se stai lavorando a un progetto più grande e cerchi maggiore stabilità, ti consigliamo il nostro piano <b>Pro</b>.
        Con risorse aggiuntive puoi mantenere la stabilità anche durante i picchi di richieste.
        Per acquistarlo, fai clic <a href={proUrl}>qui</a>.
      </Note>,
    'ja': <Note>
        <b>{appType}のホスティングに必要なRAMとCPUの容量が気になりますか？</b><br />
        ご安心ください。私たちがサポートします。
        <a href={url}>{plan}</a>プランは<b>{tier}GB</b>のRAMと<b>{cpu}vCPU</b>を提供しており、ほとんどの{appType}には十分です。
        より大規模なプロジェクトでさらなる安定性を求める場合は、<b>Pro</b>プランをおすすめします。追加リソースにより、需要のピーク時でも安定性を維持できます。
        ご購入は<a href={proUrl}>こちら</a>をクリックしてください。
      </Note>,
    'zh': <Note>
        <b>想知道托管{appType}需要多少 RAM 和 CPU 吗？</b><br />
        别担心，我们来帮您。
        我们的 <a href={url}>{plan}</a> 套餐提供 <b>{tier}GB</b> RAM 和 <b>{cpu}vCPU</b>，对大多数{appType}来说已经足够。
        如果您的项目规模更大、需要更高的稳定性，我们推荐 <b>Pro</b> 套餐。借助额外资源，即使在需求高峰期也能保持稳定。
        点击<a href={proUrl}>这里</a>即可购买。
      </Note>
  };
  return notes[lang] || notes['en'];
};

export const appType_0 = "a FastAPI application"

## 简介

要在 Square Cloud 上开发和托管 {appType_0}，遵循一套结构化的配置和前置条件流程至关重要。本技术指南将涵盖整个过程，从初始设置到生产环境部署。

### 前置条件

* **Square Cloud 账户**：通过[注册页面](https://squarecloud.app/zh/signup)使用你的邮箱进行注册。
* **有效的付费套餐**：为你的应用提供专属资源和优化的性能。查看我们[可用的套餐](https://squarecloud.app/zh/pricing)，选择最适合你需求的方案。

<RecommendedPlan appType="FastAPI 应用" plan="Standard" tier="4" cpu="4" lang="zh" />

## 创建项目

要创建 FastAPI 应用，在按照以下步骤操作之前，你的系统上需要安装 Python 和 pip。

### 安装库

安装好 Python 和 pip 后，创建你的 FastAPI 项目。首先，安装所需的依赖：

```bash Terminal theme={null}
pip install fastapi uvicorn
```

### 开发项目

创建一个 Python 文件（例如 `main.py`），并添加以下代码来实现一个基础的 FastAPI 应用：

```python main.py theme={null}
# Import the FastAPI class and the uvicorn ASGI server
from fastapi import FastAPI
import uvicorn

# Create an instance of the FastAPI class
app = FastAPI()

# Define a route for the root URL (/) that returns 'Hello, World!'
@app.get("/")
def hello_world():
  return {"message": "Hello, World!"}

# Check if this script is being run directly (not imported as a module)
if __name__ == "__main__":
  # Run the FastAPI application on host 0.0.0.0 (all available network interfaces) and port 80
  uvicorn.run(app, host="0.0.0.0", port=80)
```

在上面的代码中，我们实现了一个简单的路由，访问时会返回 "Hello, World!"。该应用被配置为在 80 端口上运行，这是默认的 HTTP 端口。

接下来，我们需要创建依赖文件。在 Python 中，我们可以使用 requirements.txt 或 pyproject.toml。

<PyDepFiles lang="zh" />

## 选择生产服务器

Uvicorn 本身就是一个适用于生产环境的 ASGI 服务器，因此不需要额外的 WSGI 服务器。在 Square Cloud 上，不要运行 `python main.py`，而是在你的配置文件中设置 `START` 字段来直接启动 Uvicorn：

```systemd squarecloud.config theme={null}
START=python -m uvicorn main:app --host 0.0.0.0 --port 80
```

<Note>对于流量较高的应用，你可以添加额外的 Uvicorn worker，例如 `START=python -m uvicorn main:app --host 0.0.0.0 --port 80 --workers 4`。</Note>

## 部署

准备好项目文件后，你现在可以将它们上传到 Square Cloud 并托管你的项目。
为此，请创建一个包含所有项目文件的 ZIP 文件。

<PortNote lang="zh" />

### 通过控制面板

<Steps>
  <Step title="访问上传页面">
    访问[上传页面](https://squarecloud.app/zh/dashboard/new)并上传你的项目 zip 文件。
  </Step>

  <Step title="配置你的环境">
    上传 zip 后，你需要为项目配置名称、主文件或运行时环境以及其他设置。\
    如果你上传的是 Web 项目，请务必选择 "Web Publication" 并为项目设置子域名。
  </Step>

  <Step title="部署你的项目">
    最后，点击 "Deploy" 按钮，即可将项目托管到 Square Cloud。\
    部署完成后，你可以在控制面板中监控项目的状态和日志。

    <Frame>
      <img src="https://cdn.squarecloud.app/docs/articles/dashboard/uploading.gif" alt="正在上传应用到 Square Cloud" style={{ borderRadius: "0.2rem" }} />
    </Frame>
  </Step>

  <Step title="确认你的应用已上线">
    首次部署通常在一分钟内完成。在[控制面板](https://squarecloud.app/zh/dashboard)中，等待你的应用状态显示为运行中，并检查日志中是否有启动错误。\
    如果你部署的是网站或 API，请在浏览器中打开 `https://<your-subdomain>.squareweb.app`，你应该能看到应用正常响应。如果你部署的是机器人，发送一条命令确认它已上线。
    <Tip>应用无法启动？请参见[故障排除指南](/zh/platform/troubleshooting/app-wont-start)，了解最常见的原因和解决方法。</Tip>
  </Step>
</Steps>

### 通过 CLI

要使用此方法，你需要在项目根目录中创建一个名为 `squarecloud.app` 的配置文件。该文件将包含项目所需的配置。

<Card title="配置文件指南" icon="link" href="/zh/getting-started/config-file">
  了解如何创建定义你应用环境的 `squarecloud.app` 配置文件。
</Card>

<Steps>
  <Step title="安装 CLI">
    首先，你的环境中需要已安装 CLI。如果尚未安装，请在终端中运行以下命令：

    ```
    npm install -g @squarecloud/cli
    ```

    如果你已经安装，我们建议对其进行更新。为此，请在终端中运行以下命令：

    <Tabs>
      <Tab title="Windows">
        ```bash theme={null}
        squarecloud update
        ```
      </Tab>

      <Tab title="Linux、macOS 和 WSL">
        ```bash theme={null}
        curl -fsSL https://cli.squarecloud.app/install | bash
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="进行身份验证">
    现在，要进行身份验证并使用其他 CLI 命令，你可以在[此处](https://squarecloud.app/zh/account/security)点击 "Request API Key" 找到你的授权密钥。获取授权密钥后，运行以下命令：

    ```bash theme={null}
    squarecloud auth login
    ```
  </Step>

  <Step title="上传你的项目">
    最后，要使用 CLI 将应用部署到 Square Cloud，你需要运行以下命令：

    ```bash theme={null}
    squarecloud upload 
    ```

    或者，如果你手动创建了 zip 文件，可以使用：

    ```bash theme={null}
    squarecloud upload --file <path/to/zip> 
    ```
  </Step>

  <Step title="确认你的应用已上线">
    首次部署通常在一分钟内完成。直接在终端中检查你的应用状态和日志：

    ```bash theme={null}
    squarecloud app status
    squarecloud app logs
    ```

    如果你部署的是网站或 API，请在浏览器中打开 `https://<your-subdomain>.squareweb.app`，你应该能看到应用正常响应。如果你部署的是机器人，发送一条命令确认它已上线。
    <Tip>应用无法启动？请参见[故障排除指南](/zh/platform/troubleshooting/app-wont-start)，了解最常见的原因和解决方法。</Tip>
  </Step>
</Steps>

## 故障排查

<CardGroup cols={1}>
  ### 自定义域名

  <Card horizontal>
    若要使用自定义域名（例如 `mysite.com`）来代替默认 URL `mysite.squareweb.app`，你需要 **Standard 计划或更高等级**。子域名由配置文件中的 **SUBDOMAIN** 字段定义。
  </Card>

  ### 最低内存要求

  <Card horizontal>
    简单网站/API 的**最低要求为 512MB RAM**。对于使用框架的站点（Next.JS、React、Vue、Angular 等），我们始终建议**至少 1GB RAM**。对于更大型的应用，请分配更多 RAM，以防止应用内存耗尽而崩溃。
  </Card>

  ### 找不到此站点。

  <Card horizontal>
    请检查**子域名/域名**是否与 **SUBDOMAIN** 字段或**自定义域名设置**中配置的内容一致。如果你刚上传站点，请等待最多 **60 秒**，让 Square 启用**首次访问**。
  </Card>

  ### 站点响应超时……

  <Card horizontal>
    请检查你是否在应用中正确配置了**端口 80** 和**主机 0.0.0.0**。我们建议使用 Square 强制注入的环境变量：来自 `.env` 文件的 **PORT** 和 **HOST**。
  </Card>
</CardGroup>

## 更多资源

有关 FastAPI 及其高级工具的更多详细信息，请访问 [FastAPI 官方文档](https://fastapi.tiangolo.com/)。
在那里，你将找到深入的技术指南、专门的教程和完整的 API 文档，帮助你充分利用 FastAPI 的各项功能。

## 联系我们

如果你仍然遇到**技术问题**，我们的**专业支持团队**可以为你提供帮助。[**联系我们**](https://squarecloud.app/zh/support)，我们很乐意协助你解决任何问题 —— 支持质量正是开发者给予 Square Cloud [**4.9/5 评分（共 402 条评价）**](https://www.trustpilot.com/review/squarecloud.app)（Google 与 Trustpilot）的重要原因之一。