# Deploy de FastAPI em produção: do uvicorn --reload a um contêiner no ar

Faça o deploy de FastAPI em produção com Uvicorn, sem fastapi dev. Escute em 0.0.0.0 e na PORT, e deixe os segredos em variáveis. O Dockerfile exige Pro.

Canonical URL: https://unbroker.cloud/pt/blog/fastapi-in-production
Published: 2026-11-10
Reviewed: 2026-11-16
Author: Timoteo Borgobello

## A resposta curta

O deploy FastAPI em produção não usa `fastapi dev` nem `uvicorn --reload`. Esses comandos são de desenvolvimento. O processo de produção roda o Uvicorn num contêiner, em `0.0.0.0` e na porta do comando de início, com as dependências travadas na imagem, a configuração em variáveis de ambiente e um único processo de servidor nesse contêiner.

Se a busca é hospedagem FastAPI, na Unbroker esse caminho é um serviço com Dockerfile e exige Pro. Builds de Dockerfile não estão no Free. A página do produto é [Deploy de FastAPI](https://unbroker.cloud/deploy/fastapi). Os passos estão em [Deploy a FastAPI application](https://docs.unbroker.cloud/guides/deploy-fastapi).

## Servidor de desenvolvimento e servidor de produção

`fastapi dev` sobe o modo de desenvolvimento. O reload fica ligado e o servidor escuta em `127.0.0.1`, o endereço que a máquina usa para falar com ela mesma. A [CLI do FastAPI](https://fastapi.tiangolo.com/fastapi-cli/) manda usar `fastapi run` em produção. `fastapi run` desliga o reload e escuta em `0.0.0.0`, então o processo fica alcançável de fora da máquina. Num contêiner, esse é o endereço que importa.

A [página de deploy do Uvicorn](https://www.uvicorn.dev/deployment/) diz para rodar `uvicorn --reload` no desenvolvimento local. A [página de settings](https://www.uvicorn.dev/settings/) diz que `--host` começa em `127.0.0.1`, e que `--host 0.0.0.0` é como a aplicação fica disponível na rede. `--reload` e `--workers` não andam juntos.

| | Desenvolvimento (`fastapi dev`, `uvicorn --reload`) | Servidor de produção |
| --- | --- | --- |
| Processo | Modo de desenvolvimento. Recarrega quando o código muda. Não é o comando do release. | Uvicorn sem reload, num contêiner. `fastapi run` é o comando de produção da CLI e também desliga o reload. |
| Endereço | `127.0.0.1`. Outras máquinas não alcançam. `fastapi dev` usa a porta 8000. | `0.0.0.0` e a porta do comando. O exemplo da Unbroker é `${PORT:-8000}`. |
| Dependências | O que o ambiente local tiver instalado. | Um `requirements.txt` commitado com versões resolvidas, instalado na imagem. |
| Configuração | Muitas vezes um `.env` local. | Variáveis de ambiente de runtime. Não ficam no repositório e não são copiadas para a imagem. |
| Trabalho longo | É fácil deixar no processo do request. | Um worker com uma fila durável, quando o job precisa sobreviver a um restart. |

## Um Dockerfile de produção

O Dockerfile do guia da Unbroker é o arquivo que vai para produção. A página de contêineres do FastAPI usa a imagem base de Python dela e `fastapi run` numa porta fixa. O guia usa `python:3.12-slim`, instala os requirements commitados, desce para um usuário que não é root e sobe o Uvicorn para o shell expandir `PORT`.

```dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt
COPY main.py ./
RUN useradd --uid 10001 --create-home appuser
USER appuser
ENV PORT=8000
CMD ["sh", "-c", "exec uvicorn main:app --host 0.0.0.0 --port ${PORT:-8000}"]
```

Anote as versões resolvidas em `requirements.txt` e faça commit desse arquivo, para a imagem instalar um conjunto conhecido. O guia pede para manter a imagem base e essas dependências atualizadas na revisão de sempre. Copie o arquivo de requirements antes do arquivo da aplicação. A página de contêineres do FastAPI coloca o arquivo de dependências primeiro pelo mesmo motivo: a camada de instalação pode ser reaproveitada quando só o código muda.

A linha `CMD` está na forma exec do Docker, o array JSON. A [página de contêineres](https://fastapi.tiangolo.com/deployment/docker/) do FastAPI manda usar essa forma para o processo desligar com graça e os eventos de lifespan rodarem. A forma shell, um `CMD uvicorn ...` solto, não faz isso. Este comando ainda sobe um shell, porque o shell é quem expande `PORT`. `exec` troca esse shell pelo Uvicorn. O guia diz as duas partes: o shell expande `PORT`, e `exec` deixa a aplicação receber os sinais de desligamento. Sem `exec`, o sinal para no `sh` e o servidor não é o processo que o recebe.

`${PORT:-8000}` escuta em `PORT` quando ela existe, e em 8000 só quando `PORT` está vazia. `ENV PORT=8000` é o padrão dentro da imagem. Escute em `0.0.0.0`, não em `127.0.0.1`. O processo roda como `appuser`, não como root.

Um deploy FastAPI com Docker começa nesse arquivo na raiz do repositório. O check local do guia constrói a imagem e pede `/health` antes de conectar o repositório. A mesma forma está em [Deploy a Docker container](https://docs.unbroker.cloud/guides/deploy-docker). Um arquivo compose que sobe a API, um banco e um worker como uma pilha só é outro desenho: [Docker Compose em produção](https://unbroker.cloud/pt/blog/docker-compose-to-production).

A página de contêineres do FastAPI também diz que a imagem antiga `tiangolo/uvicorn-gunicorn-fastapi` está obsoleta. Construa a partir de uma imagem base de Python, não dessa imagem.

## Workers, processos e réplicas

O exemplo do guia tem um processo de servidor por contêiner. É o caso que o FastAPI documenta quando a replicação mora fora do contêiner.

A página de contêineres diz que, se um cluster ou uma plataforma replica contêineres, o que você quer é um único processo Uvicorn em cada um, não `--workers`. `--workers` sobe vários processos worker dentro de um contêiner, com um manager na frente. O FastAPI diz que esse manager a mais é complexidade que você já cobriu se a plataforma cria as cópias. O Uvicorn documenta `--workers` na [página de deploy](https://www.uvicorn.dev/deployment/). O número padrão é 1, ou `$WEB_CONCURRENCY` se essa variável existe. Não defina `WEB_CONCURRENCY` a menos que queira que o padrão a siga. O comando do guia não passa `--workers`.

Existe outro caso. O FastAPI diz que `--workers` pode fazer sentido numa app simples de um único servidor, ou com Docker Compose numa máquina, quando não há outro jeito de rodar vários contêineres e distribuir os requests. Esse não é o exemplo da Unbroker. Workers do Uvicorn em produção são essa escolha: vários processos num contêiner, ou um processo e mais contêineres. Este texto não escolhe um número de workers.

Na Unbroker, o Free roda uma réplica. O Pro pode configurar réplicas, até o limite da célula compartilhada da [tabela de planos](https://docs.unbroker.cloud/billing/plans). Autoscaling de réplicas não está no Free. Como as cópias entram e saem está em [Autoscaling de réplicas](https://unbroker.cloud/pt/blog/replica-autoscaling). Um serviço worker é outra coisa: o guia de workers diz que eles rodam uma réplica.

## Settings e segredos

A [página de settings](https://fastapi.tiangolo.com/advanced/settings/) do FastAPI diz que chaves secretas, credenciais de banco e o resto da configuração costumam vir de variáveis de ambiente, porque mudam e porque muitas são sensíveis. Uma variável de ambiente é uma string fora do código Python. O que não é string, inclusive um número, a aplicação precisa converter.

`pydantic-settings` é opcional. `BaseSettings` lê essas variáveis sem diferenciar maiúsculas e valida nos tipos que você declara. Um `.env` é a forma local da mesma ideia. Em produção, defina os mesmos nomes como variáveis de runtime. Não faça commit do arquivo e não o copie para a imagem.

Um segredo copiado para uma camada da imagem continua no artefato mesmo se uma camada posterior apaga o arquivo. O guia de Docker manda incluir `.env`, credenciais locais e outros arquivos locais no `.dockerignore` quando o `COPY` é amplo, e mandar os segredos da aplicação por variáveis de runtime. Esse guia é [Deploy a Docker container](https://docs.unbroker.cloud/guides/deploy-docker).

Na Unbroker, abra as variáveis do serviço e defina o valor para o ambiente que deve recebê-lo: Production, Preview ou All. Uma credencial de banco de produção não fica em All, a menos que os ambientes de preview devam recebê-la. Use uma variável de serviço para a configuração de uma única aplicação. Variáveis compartilhadas do projeto servem para um valor que vários serviços usam, e exigem Pro. Uma variável de serviço cobre uma compartilhada com a mesma chave. Faça deploy de novo para a revisão no ar usar o valor novo. Não imprima o ambiente inteiro enquanto depura. O escopo está em [Variáveis de ambiente e segredos](https://unbroker.cloud/pt/blog/environment-variables-and-secrets), e os passos em [Configure environment variables and secrets](https://docs.unbroker.cloud/guides/environment-variables).

## Banco, pools e migrações

O exemplo do guia de FastAPI não tem banco. Quando você adiciona um, ele pede uma variável de conexão de runtime, um pool de conexões e um passo deliberado de migração de schema. Não rode migrações durante o build da imagem.

Na Unbroker há dois caminhos de PostgreSQL. Um nó de Apps é um serviço de banco privado dentro do projeto. Um cluster gerenciado é um host de banco que o provedor opera. O schema e as migrações continuam seus. O guia de conexão parte da Unbroker Pro e de um recurso PostgreSQL que já existe. Bancos gerenciados não estão no Free. Guarde as credenciais nas variáveis de runtime do serviço. Um comando que revela uma connection string pode imprimir um segredo, então essa saída não vai para o repositório, para o chat nem para os logs. Não desligue a verificação do certificado para contornar um erro de conexão, e não exponha o banco na internet para diagnosticar uma conexão privada. Os passos estão em [Connect your application to PostgreSQL](https://docs.unbroker.cloud/guides/connect-postgres). Operar o banco está em [Postgres em produção](https://unbroker.cloud/pt/blog/postgres-in-production).

Limite o pool e defina timeouts. A linha de "conexões demais" do guia é o tamanho do pool multiplicado por processos e por réplicas. Um processo por contêiner não mantém o total pequeno se cada réplica abre um pool grande.

Rode a migração uma vez, com as credenciais de runtime, antes de a versão nova receber tráfego. Os [conceitos de deploy](https://fastapi.tiangolo.com/deployment/concepts/) do FastAPI dizem que um passo anterior, como uma migração de banco, deve rodar uma única vez. Se cada processo roda, esses processos trabalham em paralelo e a migração pode conflitar com ela mesma. Se o projeto já usa Alembic, esse comando é este passo. Este texto não acrescenta flags. Na Unbroker, comandos de migração exigem Pro. O que um rollback de código deixa para trás está em [Migrações de banco de dados no deploy](https://unbroker.cloud/pt/blog/database-migrations-on-deploy).

## Trabalho em segundo plano

`BackgroundTasks` roda depois da resposta, no mesmo processo. A [página de background tasks](https://fastapi.tiangolo.com/tutorial/background-tasks/) do FastAPI usa isso quando o cliente não precisa esperar, por exemplo um aviso por e-mail ou um arquivo que o request já aceitou. A função pode ser `async def` ou um `def` comum.

A mesma página faz uma ressalva. Se o trabalho é pesado e não precisa da memória daquele processo, use uma ferramenta de fila. A página cita o Celery como exemplo. Essas ferramentas precisam de uma fila de mensagens e podem rodar em outros processos e em outras máquinas. O guia de workers da Unbroker não cita uma biblioteca. Ele diz que o worker e a fila durável são peças separadas, e que um loop sobre um array em memória não é entrega durável.

Se o job precisa sobreviver a um restart, `BackgroundTasks` não é o lugar. Elas vivem no processo do servidor. Quando esse processo para, a tarefa para com ele. Coloque o consumidor num serviço worker próprio. O comando de início deve lançar o consumidor e permanecer no ar enquanto espera. Um script que processa um item e sai é um job agendado ou um comando avulso, não um worker. Workers exigem Pro e rodam uma réplica. Não têm URL pública. O corte está em [Workers em segundo plano e cron](https://unbroker.cloud/pt/blog/background-workers-cron-jobs), e os passos em [Deploy a background worker](https://docs.unbroker.cloud/guides/background-worker).

## Health checks e falhas de subida

O health check de FastAPI no guia é `GET /health`. O exemplo devolve `{"ok": True}`. Depois do deploy, abra `/health` na URL do serviço. O exemplo também tem `/api/message`.

Duas falhas aparecem antes de você precisar de uma máquina maior. Um erro de import em geral significa que o caminho `main:app` não bate com o repositório, ou que uma dependência não entrou na imagem. Um contêiner que responde no local e fica inalcançável depois do deploy costuma precisar do host ou da porta: `0.0.0.0`, e a porta em que o comando realmente escutou. Leia os logs de runtime antes de aumentar recursos. Por onde começar quando um release falha está em [Depurar um deploy que falhou](https://unbroker.cloud/pt/blog/debug-failed-deployment). O guia aponta o mesmo diagnóstico em [Diagnose a failed deployment](https://docs.unbroker.cloud/guides/debug-failed-deployment).

## Como funciona na Unbroker

No Cloud, adicione um serviço de repositório, escolha o método de build Dockerfile e use o Dockerfile da raiz. Configure as variáveis de runtime antes do deploy. Abra `/health` na URL do serviço.

Uma API Express no preset de Node.js é outro caminho. O caminho público de Node.js gerenciado pode se qualificar para o Free, e builds de Dockerfile não estão no Free. O que muda depois do nodemon está em [Express em produção](https://unbroker.cloud/pt/blog/express-in-production).

O guia parte de um repositório Python, um check local com Docker e Unbroker Pro. Builds de Dockerfile são uma capacidade do plano pago. Não estão no Free. A [tabela de planos](https://docs.unbroker.cloud/billing/plans) lista builds de Dockerfile, workers, comandos de migração e bancos gerenciados como indisponíveis no Free e disponíveis no Pro. A página de preços também lista Dockerfiles com o Pro. Este texto não descreve um caminho Free para FastAPI. O que o plano de $0 consegue rodar, com Node.js gerenciado e sites estáticos, está em [hospedagem backend grátis sem Dockerfile](https://unbroker.cloud/pt/blog/free-backend-hosting).

O Pro custa $25 por mês com $25 de crédito de uso. O crédito reinicia a cada ciclo de cobrança e não acumula. Se o uso elegível fica abaixo do crédito, a cobrança mensal continua o preço do plano. Se o uso elegível passa do crédito, só a diferença é somada. As linhas estão em [preços](https://unbroker.cloud/pt/precos) e em [Plans](https://docs.unbroker.cloud/billing/plans). Separe no orçamento a API no ar, o build e qualquer banco. O guia diz o mesmo.

## Como faço o deploy de uma app FastAPI com Docker Compose?

Um arquivo Docker Compose é um inventário de processos, não algo que a Unbroker roda como um projeto Compose. Para fazer o deploy de uma app FastAPI que você hoje sobe com Compose, trate cada serviço do arquivo como um serviço próprio da Unbroker.

Quando você cria um projeto, pode colar um arquivo Compose. A Unbroker cria um serviço por entrada. Esse caminho aceita imagens, builds de repositório, environment, depends_on, portas, comandos e um volume persistente por serviço. Ele não decide o que é público, onde os dados ficam nem se um banco deve ser um cluster gerenciado. Você também pode adicionar esses serviços à mão.

O serviço FastAPI continua o Dockerfile deste texto: Uvicorn, sem reload, escutando em 0.0.0.0 e na PORT. Builds de Dockerfile exigem Pro. Um serviço de Postgres ou Redis no mesmo arquivo Compose vira um nó de banco do Apps ou um banco gerenciado, não um processo empacotado na imagem da API. O mapa campo a campo está em [Docker Compose em produção](https://unbroker.cloud/pt/blog/docker-compose-to-production). Os passos do contêiner estão em [Deploy a FastAPI application](https://docs.unbroker.cloud/guides/deploy-fastapi).

## Checklist

1. Deixe `fastapi dev` e `uvicorn --reload` fora do comando de produção.
2. Escute em `0.0.0.0`. Use a forma `${PORT:-8000}` do guia, e coloque `exec` na frente do Uvicorn para os sinais de desligamento chegarem ao servidor.
3. Instale um `requirements.txt` commitado com versões resolvidas. Rode com o usuário que não é root no Dockerfile do guia.
4. Mantenha um processo de servidor no contêiner. Não passe `--workers` quando as réplicas ficam fora, e não defina `WEB_CONCURRENCY` sem querer isso.
5. Leia a configuração de variáveis de ambiente. Deixe os segredos fora do repositório e fora da imagem.
6. Aponte o Postgres para uma variável de runtime. Limite o pool. Lembre do tamanho do pool vezes processos vezes réplicas.
7. Rode as migrações uma vez, como passo próprio, não durante o build da imagem e não em cada processo.
8. Coloque o trabalho que precisa sobreviver a um restart num worker com fila durável. Deixe `BackgroundTasks` para um trabalho curto do processo web.
9. Abra `/health` depois do deploy. Leia os logs de runtime antes de aumentar recursos.
10. Faça deploy do serviço Dockerfile no Pro. Builds de Dockerfile não estão no Free.

## Perguntas frequentes

### Posso usar uvicorn --reload ou fastapi dev em produção?

Não. A página de deploy do Uvicorn diz para rodar uvicorn --reload no desenvolvimento local. fastapi dev é o modo de desenvolvimento: o reload fica ligado e ele escuta em 127.0.0.1. A CLI do FastAPI manda usar fastapi run em produção. O reload observa a árvore de trabalho e não é o processo de um release. O guia da Unbroker sobe o Uvicorn sem reload, em 0.0.0.0, e toma a porta de PORT.

### Devo rodar o Uvicorn com --workers ou um processo por contêiner?

Um processo por contêiner, quando as cópias nascem fora dele. A página de contêineres do FastAPI diz isso, e diz para não passar --workers nesse caso. --workers sobe vários processos dentro de um único contêiner. Não pode ser usado junto com --reload. O padrão do Uvicorn é 1, ou o valor de WEB_CONCURRENCY quando essa variável existe. O exemplo da Unbroker não passa --workers. Ele tem um processo de servidor. Como as cópias entram na Unbroker está em [Autoscaling de réplicas](https://unbroker.cloud/pt/blog/replica-autoscaling).

### Por que o contêiner responde localmente e fica inalcançável depois do deploy?

Olhe o host e a porta. O guia de FastAPI diz que um contêiner saudável no local e inalcançável de fora costuma precisar dessa correção. O host padrão do Uvicorn é 127.0.0.1, e outras máquinas não alcançam esse endereço. Escute em 0.0.0.0. O comando do guia usa ${PORT:-8000}: se PORT está vazia, cai para 8000. A imagem também define ENV PORT=8000. Leia os logs de runtime antes de aumentar CPU ou memória. Um erro de import em geral significa que o caminho main:app não bate com o módulo, ou que uma dependência ficou de fora da imagem.

### Onde ficam os segredos e as settings do FastAPI em produção?

Em variáveis de ambiente, fora do repositório e fora da imagem. A página de settings do FastAPI diz que chaves secretas e credenciais de banco são lidas do ambiente. pydantic-settings é opcional: BaseSettings lê essas variáveis e valida. Um arquivo .env é a forma local da mesma ideia, nessa página. Não faça commit dele e não copie para uma camada da imagem. Na Unbroker os valores são variáveis de runtime. Como elas se dividem está em [Variáveis de ambiente e segredos](https://unbroker.cloud/pt/blog/environment-variables-and-secrets).

### Quando as migrações do Alembic devem rodar?

Uma vez, como passo próprio, com as credenciais de runtime. Não enquanto a imagem é construída e não a partir de cada processo do servidor. O guia de FastAPI pede um passo deliberado de migração de schema e diz para não rodar migrações durante o build. Os conceitos de deploy do FastAPI dizem que um passo anterior, como uma migração, deve rodar uma única vez: execuções em paralelo podem entrar em conflito. Se o projeto já usa Alembic, esse comando é o passo. Na Unbroker, comandos de migração exigem Pro. O que um rollback de código não desfaz está em [Migrações de banco de dados no deploy](https://unbroker.cloud/pt/blog/database-migrations-on-deploy).

### BackgroundTasks do FastAPI bastam para um job longo?

Para uma tarefa pequena que pode rodar no mesmo processo depois da resposta, sim. A página de background tasks do FastAPI usa isso quando o cliente não precisa esperar, por exemplo um aviso por e-mail. A mesma página diz que um trabalho pesado que não precisa desse processo cabe numa ferramenta de fila, que pode rodar em outros processos e em outras máquinas. BackgroundTasks não sobrevivem ao processo. Se o job precisa sobreviver a um restart, use um worker e uma fila durável. O corte está em [Workers em segundo plano e cron](https://unbroker.cloud/pt/blog/background-workers-cron-jobs).

### Posso fazer deploy de FastAPI no plano Free da Unbroker?

Não. O caminho documentado é um build de Dockerfile, e builds de Dockerfile não estão no Free. A tabela de planos marca isso como indisponível no Free e disponível no Pro. A página de preços lista Dockerfiles junto com o Pro. Este texto não descreve outro jeito de rodar FastAPI no Free. O Pro custa $25 por mês com $25 de crédito de uso. Os passos estão em [Deploy de FastAPI](https://unbroker.cloud/deploy/fastapi) e no [guia de FastAPI](https://docs.unbroker.cloud/guides/deploy-fastapi).

### Como faço o deploy de uma app FastAPI com Docker Compose?

Trate o arquivo Compose como um inventário, não como uma unidade que a Unbroker roda. Quando você cria um projeto, pode colar um arquivo Compose, e a Unbroker cria um serviço por entrada. Esse caminho aceita imagens, builds de repositório, environment, depends_on, portas, comandos e um volume persistente por serviço. Ele não escolhe o que é público, onde os dados ficam nem se um banco deve ser um cluster gerenciado. O serviço FastAPI continua um Dockerfile que sobe o Uvicorn em 0.0.0.0 e na PORT, e builds de Dockerfile exigem Pro.

## Related reading

- [Deploy de FastAPI](https://unbroker.cloud/deploy/fastapi)
- [Variáveis de ambiente e segredos](https://unbroker.cloud/pt/blog/environment-variables-and-secrets)
- [Postgres em produção](https://unbroker.cloud/pt/blog/postgres-in-production)
- [Migrações de banco de dados no deploy](https://unbroker.cloud/pt/blog/database-migrations-on-deploy)
- [Workers em segundo plano e cron](https://unbroker.cloud/pt/blog/background-workers-cron-jobs)
- [Depurar um deploy que falhou](https://unbroker.cloud/pt/blog/debug-failed-deployment)
- [Docker Compose em produção](https://unbroker.cloud/pt/blog/docker-compose-to-production)
- [Autoscaling de réplicas](https://unbroker.cloud/pt/blog/replica-autoscaling)
- [Express em produção](https://unbroker.cloud/pt/blog/express-in-production)
- [Hospedagem grátis sem Docker](https://unbroker.cloud/pt/blog/free-backend-hosting)
- [Preços](https://unbroker.cloud/pt/precos)
