PythonPubblicato il 15 dicembre 2025Lettura di 13 min

Pubblicare un'API Flask o FastAPI con dominio e HTTPS

Questa guida ti mostra come pubblicare un'API Flask o FastAPI su un server Python di OuiHeberg gestito in OuiPanel. Poi ti mostra come collegarla al tuo dominio in HTTPS con il Proxy Manager. Ti servono il codice della tua API (app.py, main.py…) e, se vuoi un indirizzo personalizzato, un nome di dominio.


Preparare i file dell'API

Scegliere tra Flask e FastAPI

CriterioFlaskFastAPI
DifficoltàPrincipianteIntermedio
InstallazioneSemplice, senza compilazionePiù pesante, pydantic-core può dover essere compilato con Rust
Spazio su disco per l'installazioneCirca 100 MBFino a 5 GB se pydantic-core viene compilato
PrestazioniBuoneEccellenti (async)
Documentazione automaticaNo (estensione)Sì (Swagger, OpenAPI)
Validazione dei datiManualeAutomatica (Pydantic)
Ideale perAPI semplici, server piccoliAPI moderne, server grandi

Il tuo server ha meno di 5 GB di storage? Scegli Flask.

Struttura dei file

La tua API deve avere questa struttura.

MonAPI/
├── app.py             ← File principale (o main.py)
├── requirements.txt   ← Dipendenze Python
├── .env               ← Variabili d'ambiente (creato sul server)
└── routes/            ← (Opzionale) Cartella delle route

Opzione A: API con Flask

Ecco il file requirements.txt.

flask==2.3.3
python-dotenv==1.0.0
werkzeug==2.3.7
PacchettoRuolo
flaskFramework web minimalista
python-dotenvCarica le variabili da .env
werkzeugUtility WSGI (incluse con Flask)

Mantieni esattamente queste versioni per evitare problemi di compatibilità. Ecco il file principale, app.py.

import os
from dotenv import load_dotenv

# Caricare le variabili d'ambiente da .env
load_dotenv()

from flask import Flask, jsonify, request

# Creare l'applicazione Flask
app = Flask(__name__)

# ============================================
# ROUTE DELL'API
# ============================================

# Route principale
@app.route('/')
def home():
    return jsonify({
        'status': 'online',
        'message': 'Benvenuto nella mia API Flask!',
        'version': '1.0.0'
    })

# Route di salute (health check)
@app.route('/health')
def health():
    return jsonify({
        'status': 'healthy',
        'service': 'La mia API Flask'
    })

# Esempio di dati (simulando un database)
items = [
    {'id': 1, 'name': 'Item 1', 'price': 10.99},
    {'id': 2, 'name': 'Item 2', 'price': 24.99},
    {'id': 3, 'name': 'Item 3', 'price': 5.49}
]

# GET tutti gli elementi
@app.route('/api/items', methods=['GET'])
def get_items():
    return jsonify({
        'success': True,
        'data': items,
        'count': len(items)
    })

# GET un elemento per ID
@app.route('/api/items/<int:item_id>', methods=['GET'])
def get_item(item_id):
    for item in items:
        if item['id'] == item_id:
            return jsonify({
                'success': True,
                'data': item
            })
    return jsonify({
        'success': False,
        'error': 'Elemento non trovato'
    }), 404

# POST creare un elemento
@app.route('/api/items', methods=['POST'])
def create_item():
    data = request.get_json()
    
    if not data or 'name' not in data:
        return jsonify({
            'success': False,
            'error': 'Il campo "name" è obbligatorio'
        }), 400
    
    new_id = max(item['id'] for item in items) + 1 if items else 1
    new_item = {
        'id': new_id,
        'name': data['name'],
        'price': data.get('price', 0)
    }
    items.append(new_item)
    
    return jsonify({
        'success': True,
        'message': 'Elemento creato con successo',
        'data': new_item
    }), 201

# PUT modificare un elemento
@app.route('/api/items/<int:item_id>', methods=['PUT'])
def update_item(item_id):
    data = request.get_json()
    
    for item in items:
        if item['id'] == item_id:
            item['name'] = data.get('name', item['name'])
            item['price'] = data.get('price', item['price'])
            return jsonify({
                'success': True,
                'message': 'Elemento modificato con successo',
                'data': item
            })
    
    return jsonify({
        'success': False,
        'error': 'Elemento non trovato'
    }), 404

# DELETE eliminare un elemento
@app.route('/api/items/<int:item_id>', methods=['DELETE'])
def delete_item(item_id):
    for index, item in enumerate(items):
        if item['id'] == item_id:
            items.pop(index)
            return jsonify({
                'success': True,
                'message': f'Elemento {item_id} eliminato con successo'
            })
    
    return jsonify({
        'success': False,
        'error': 'Elemento non trovato'
    }), 404

# ============================================
# GESTIONE DEGLI ERRORI
# ============================================

@app.errorhandler(404)
def not_found(error):
    return jsonify({
        'success': False,
        'error': 'Risorsa non trovata'
    }), 404

@app.errorhandler(500)
def internal_error(error):
    return jsonify({
        'success': False,
        'error': 'Errore interno del server'
    }), 500

# ============================================
# AVVIO DEL SERVER
# ============================================

if __name__ == '__main__':
    # Porta : utilizza SERVER_PORT (OuiPanel) o 5000 per impostazione predefinita
    port = int(os.getenv('SERVER_PORT', 5000))
    
    # IMPORTANTE : Ascoltare su 0.0.0.0 per OuiPanel
    app.run(host='0.0.0.0', port=port)

L'API deve ascoltare su 0.0.0.0, e non su localhost o 127.0.0.1, per essere raggiungibile dall'esterno.

Opzione B: API con FastAPI

FastAPI dipende da pydantic-core. Quando pip deve compilarlo, l'installazione richiede diversi GB di spazio su disco. In caso di errore No space left on device, passa a Flask o aumenta lo storage del server.

Ecco il file requirements.txt.

fastapi==0.104.1
uvicorn==0.24.0
python-dotenv==1.0.0
PacchettoRuolo
fastapiFramework web moderno e veloce
uvicornServer ASGI per FastAPI
python-dotenvCarica le variabili da .env

Prevedi almeno 5 GB di storage libero per installare FastAPI. Ecco il file principale, app.py.

import os
from dotenv import load_dotenv

# Caricare le variabili d'ambiente da .env
load_dotenv()

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Optional, List

# Creare l'applicazione FastAPI
app = FastAPI(
    title="La mia API FastAPI",
    description="Un'API REST moderna con FastAPI",
    version="1.0.0",
    docs_url="/docs",      # Documentazione Swagger
    redoc_url="/redoc"     # Documentazione ReDoc
)

# ============================================
# MODELLI PYDANTIC (validazione dei dati)
# ============================================

class ItemCreate(BaseModel):
    name: str
    price: float = 0
    description: Optional[str] = None

class Item(BaseModel):
    id: int
    name: str
    price: float
    description: Optional[str] = None

# ============================================
# DATI ESEMPIO (simulando un database)
# ============================================

items_db = [
    {"id": 1, "name": "Item 1", "price": 10.99, "description": "Primo elemento"},
    {"id": 2, "name": "Item 2", "price": 24.99, "description": "Secondo elemento"},
    {"id": 3, "name": "Item 3", "price": 5.49, "description": "Terzo elemento"},
]

# ============================================
# ROUTE DELL'API
# ============================================

# Route principale
@app.get("/", tags=["Generale"])
async def home():
    return {
        "status": "online",
        "message": "Benvenuto nella mia API FastAPI!",
        "version": "1.0.0",
        "docs": "/docs"
    }

# Route di salute (health check)
@app.get("/health", tags=["Generale"])
async def health():
    return {
        "status": "healthy",
        "service": "La mia API FastAPI"
    }

# GET tutti gli elementi
@app.get("/api/items", tags=["Elementi"])
async def get_items():
    return {
        "success": True,
        "data": items_db,
        "count": len(items_db)
    }

# GET un elemento per ID
@app.get("/api/items/{item_id}", tags=["Elementi"])
async def get_item(item_id: int):
    for item in items_db:
        if item["id"] == item_id:
            return {"success": True, "data": item}
    raise HTTPException(status_code=404, detail="Elemento non trovato")

# POST creare un elemento
@app.post("/api/items", status_code=201, tags=["Elementi"])
async def create_item(item: ItemCreate):
    new_id = max(i["id"] for i in items_db) + 1 if items_db else 1
    new_item = {
        "id": new_id,
        "name": item.name,
        "price": item.price,
        "description": item.description
    }
    items_db.append(new_item)
    return {
        "success": True,
        "message": "Elemento creato con successo",
        "data": new_item
    }

# PUT modificare un elemento
@app.put("/api/items/{item_id}", tags=["Elementi"])
async def update_item(item_id: int, item: ItemCreate):
    for index, existing_item in enumerate(items_db):
        if existing_item["id"] == item_id:
            updated_item = {
                "id": item_id,
                "name": item.name,
                "price": item.price,
                "description": item.description
            }
            items_db[index] = updated_item
            return {
                "success": True,
                "message": "Elemento modificato con successo",
                "data": updated_item
            }
    raise HTTPException(status_code=404, detail="Elemento non trovato")

# DELETE eliminare un elemento
@app.delete("/api/items/{item_id}", tags=["Elementi"])
async def delete_item(item_id: int):
    for index, item in enumerate(items_db):
        if item["id"] == item_id:
            items_db.pop(index)
            return {"success": True, "message": f"Elemento {item_id} eliminato"}
    raise HTTPException(status_code=404, detail="Elemento non trovato")

# ============================================
# AVVIO DEL SERVER
# ============================================

if __name__ == "__main__":
    import uvicorn
    
    # Porta : utilizza SERVER_PORT (OuiPanel) o 8000 per impostazione predefinita
    port = int(os.getenv('SERVER_PORT', 8000))
    
    # IMPORTANTE : Ascoltare su 0.0.0.0 per OuiPanel
    uvicorn.run(app, host="0.0.0.0", port=port)

FastAPI genera da solo una documentazione interattiva: Swagger UI su http://tuo-ip:porta/docs e ReDoc su http://tuo-ip:porta/redoc.


Caricare i file su OuiPanel

La Gestione file non ha un pulsante di caricamento. I file si inviano trascinandoli nella pagina.

  1. Accedi a OuiPanel su dash.ouipanel.com e apri il tuo server Python.

  2. Nel menu laterale, clicca su Gestione file.

  3. Elimina i file predefiniti, se ce ne sono.

  4. Dal tuo computer, trascina nella pagina app.py, requirements.txt e le tue cartelle (routes/, models/…).

  5. Quando compare il riquadro «Trascina i tuoi file qui», rilascia.

Ogni file inviato così è limitato a 100 MB.

Riquadro Trascina i tuoi file qui mostrato durante il trascinamento nella Gestione file

Non caricare il tuo file .env. Crealo direttamente sul server, è più sicuro.

Via SFTP

Per molti file, o file oltre i 100 MB, usa l'SFTP. Collegati con FileZilla, trascina tutto il contenuto della cartella dell'API, poi verifica che sia arrivato tutto. La guida Come connettersi in SFTP con FileZilla spiega la connessione.


Creare il file .env

  1. Nella Gestione file, nella Radice, clicca su Crea un file.

  2. Nella finestra «Crea un nuovo file», scrivi .env in Nome del file, con il punto davanti, poi clicca su Crea il file.

  3. Clicca su .env per aprirlo nell'editor, aggiungi le tue variabili, poi clicca su Salva.

# Configurazione dell'API
DEBUG=false
PORT=8000

# Database (se necessario)
DATABASE_URL=mysql://user:password@host:3306/database

# Chiavi API (esempi)
API_KEY=la_tua_chiave_api_segreta
SECRET_KEY=la_tua_chiave_segreta_per_jwt
  • Nessuno spazio intorno al =.

  • Nessuna virgoletta intorno ai valori semplici.

  • Non condividere mai questo file.

Gestione file nella radice di un bot Python con bot.py, requirements.txt e la cartella cogs


Scegliere il file di avvio e la versione di Python

OuiPanel deve sapere quale file Python avviare all'accensione. Su un server Python, questa impostazione è una variabile del server.

  1. Apri Configurazione › Impostazioni del server.

  2. Nella scheda Avvio del server, scegli la Versione sistema. L'elenco propone Python 2.7 e tutte le versioni dalla 3.7 alla 3.13, con la 3.13 in versione candidata. È consigliata la 3.12.

  3. Nella scheda Variabili d'ambiente, scrivi il nome del tuo file in File Python di avvio (file di avvio; i nomi delle variabili sono in francese).

  4. Clicca sulla spunta a destra del campo (Salva).

Il tuo file principaleValore di File Python di avvio
app.pyapp.py
main.pymain.py
api.pyapi.py
src/app.pysrc/app.py

Il campo File delle dipendenze della stessa scheda indica il file delle dipendenze da installare, requirements.txt di default.

Variabili d'ambiente di un server Python con File Python di avvio e File delle dipendenze

Il nome deve corrispondere esattamente al tuo file, maiuscole comprese.


Avviare e provare l'API

Avviare il server

Nel menu laterale, clicca su Console, poi su Avvia. All'avvio il server installa i pacchetti di requirements.txt, poi esegue il tuo file.

Con Flask:

Installing requirements from requirements.txt...
Successfully installed flask-3.0.0 python-dotenv-1.0.0 gunicorn-21.2.0

Running app.py...
 * Running on http://0.0.0.0:25639

Con FastAPI:

Installing requirements from requirements.txt...
Successfully installed fastapi-0.109.0 uvicorn-0.27.0 python-dotenv-1.0.0

Running app.py...
INFO:     Uvicorn running on http://0.0.0.0:25639

Trovare l'indirizzo dell'API

  1. Annota la porta mostrata nella console, per esempio 25639.

  2. Leggi l'indirizzo IP del tuo server in Vista Globale, alla riga Indirizzo principale.

  3. L'indirizzo della tua API è http://IP:PORTA, per esempio http://203.0.113.10:25639.

Provare gli endpoint

In un browser:

  • http://203.0.113.10:25639/ mostra il JSON di benvenuto;

  • http://203.0.113.10:25639/health risponde al controllo di stato;

  • http://203.0.113.10:25639/docs apre la documentazione Swagger (FastAPI).

Con curl, ecco le chiamate di base.

# GET - Pagina principale
curl http://203.0.113.10:25639/

# GET - Lista degli elementi
curl http://203.0.113.10:25639/api/items

# GET - Un elemento specifico
curl http://203.0.113.10:25639/api/items/1

# POST - Creare un elemento
curl -X POST http://203.0.113.10:25639/api/items \
  -H "Content-Type: application/json" \
  -d '{"name": "Nuovo elemento", "price": 29.99}'

# PUT - Modificare un elemento
curl -X PUT http://203.0.113.10:25639/api/items/1 \
  -H "Content-Type: application/json" \
  -d '{"name": "Elemento modificato", "price": 39.99}'

# DELETE - Eliminare un elemento
curl -X DELETE http://203.0.113.10:25639/api/items/1

Con Postman o Insomnia, importa l'URL di base http://203.0.113.10:25639 e prova i tuoi endpoint.


Collegare un dominio con il Proxy Manager

Il Proxy Manager rende l'API raggiungibile a un indirizzo come https://api.miosito.com. Ti servono un dominio tuo e l'accesso alla sua zona DNS.

Creare il record DNS

  1. Nel menu laterale, clicca su Proxy Manager.

  2. La scheda La destinazione DNS di questo server indica l'indirizzo IP del proxy, come Valore.

  3. Presso il tuo registrar (OVH, Cloudflare, ecc.), crea un record di tipo A per il sottodominio dell'API.

TipoNomeValore
AapiL'indirizzo IP del proxy

Pagina Proxy Manager con la scheda La destinazione DNS di questo server

Su Cloudflare, lascia il proxy disattivato (icona grigia, DNS only). Altrimenti il certificato HTTPS non può essere emesso.

Collegare il dominio

  1. Nel Proxy Manager, clicca su Aggiungi un dominio. Si apre il modulo Nuovo collegamento.

  2. In Nome di dominio, scrivi api.miosito.com.

  3. In Porta, scegli dall'elenco la porta su cui ascolta la tua API.

  4. Lascia HTTPS su Certificato richiesto.

  5. Clicca su Verifica il DNS. Quando il pannello mostra «Il DNS punta qui», clicca su Crea il reindirizzamento.

Modulo Nuovo collegamento con il nome di dominio, la porta e HTTPS

Il dominio compare in Domini collegati. La tua API risponde su https://api.miosito.com, con un certificato Let's Encrypt rinnovato automaticamente.

curl https://api.miosito.com/api/items

La guida Collegare un dominio al tuo server con il Proxy Manager descrive ogni passaggio e i messaggi di errore.


Collegare un database MySQL

Crea prima il database in OuiPanel, da Database › Crea un database. Il pulsante Informazioni ti dà poi host, nome utente e password. La guida Creare un database MySQL su OuiPanel descrive queste schermate.

Con Flask e PyMySQL, aggiungi questa riga a requirements.txt.

pymysql==1.1.0

Ecco un esempio di connessione.

import pymysql
import os

# Connessione a MySQL
connection = pymysql.connect(
    host=os.getenv('DB_HOST', 'localhost'),
    user=os.getenv('DB_USER', 'root'),
    password=os.getenv('DB_PASSWORD', ''),
    database=os.getenv('DB_NAME', 'mydb'),
    charset='utf8mb4'
)

# Esempio di query
with connection.cursor() as cursor:
    cursor.execute("SELECT * FROM items")
    result = cursor.fetchall()

Aggiungi queste variabili al .env.

DB_HOST=mysql-host.ouiheberg.com
DB_USER=tuo_user
DB_PASSWORD=tuo_password
DB_NAME=tuo_database

Distribuire da un repository Git

Il tuo codice è su GitHub, GitLab, Bitbucket o Codeberg? La pagina Distribuzione scarica il repository e installa i pacchetti di requirements.txt al posto tuo, senza caricare i file a mano.

  1. Nel menu laterale, clicca su Distribuzione.

  2. Nel blocco Collegare un repository, compila Indirizzo del repository e Ramo.

  3. In Accesso al repository, scegli Repository pubblico oppure una delle due opzioni per repository privati (chiave di distribuzione o token di accesso).

  4. Spunta Distribuire a ogni push sul ramo se vuoi aggiornamenti automatici, poi clicca su Salva.

  5. Clicca su Distribuisci ora.

Ogni distribuzione riavvia il server, che resta fermo mentre vengono installate le dipendenze. Se l'installazione non riesce, riparte la versione precedente. I file non tracciati da Git, come il tuo .env, restano al loro posto. Prima della prima distribuzione, il pannello fa un backup del server.

Pagina Distribuzione Git con Collegare un repository, Indirizzo del repository, Ramo e Accesso al repository

Per un repository privato è consigliata la chiave di distribuzione. Il pannello genera una chiave propria del server, da aggiungere al repository in sola lettura.


Risolvere un problema

L'API non si avvia

ErroreSoluzione
ModuleNotFoundError: No module named 'flask'Controlla requirements.txt e riavvia.
ModuleNotFoundError: No module named 'fastapi'Controlla requirements.txt e riavvia.
ModuleNotFoundError: No module named 'dotenv'Aggiungi python-dotenv in requirements.txt.
SyntaxErrorErrore nel tuo codice Python.

Errore «No space left on device» (FastAPI)

Si verifica quando pydantic-core, una dipendenza di FastAPI, deve essere compilato con Rust.

error: No space left on device (os error 28)
ERROR: Failed building wheel for pydantic-core
  1. Usa Flask al suo posto, che non richiede compilazione.

  2. Aumenta lo storage del tuo server (consigliati 5 GB o più).

  3. Pulisci i file temporanei e riprova.

L'API si avvia ma non è raggiungibile

CausaSoluzione
Ascolta su localhostPassa a 0.0.0.0.
Porta sbagliataUsa os.getenv('SERVER_PORT').

Controlla il tuo codice:

# ERRATO - ascolta solo in locale
app.run(host='localhost', port=5000)
app.run(host='127.0.0.1', port=5000)

# CORRETTO - ascolta su tutte le interfacce
app.run(host='0.0.0.0', port=port)
uvicorn.run(app, host='0.0.0.0', port=port)

Errore 502 Bad Gateway (Proxy Manager)

CausaSoluzione
API non avviataAvvia il server in OuiPanel.
Porta sbagliata nel Proxy ManagerControlla la porta del dominio collegato.
API andata in crashConsulta la Console.

Il file .env non viene letto

CausaSoluzione
python-dotenv mancanteControlla requirements.txt.
load_dotenv() non chiamatoAggiungi load_dotenv() all'inizio del file.
Nome del file sbagliatoIl file deve chiamarsi esattamente .env.

Errore CORS

Compare quando un frontend (React, Vue, ecc.) chiama la tua API da un altro dominio.

ErroreSoluzione
Access-Control-Allow-OriginAggiungi Flask-CORS o CORSMiddleware (vedi più in basso).

Sicurezza e buone pratiche

Proteggere il file .env

Da fareDa evitare
Creare il .env sul serverCaricare il .env dal tuo computer
Aggiungere .env al .gitignorePubblicare il .env su GitHub
Passare i segreti tramite variabiliScrivere le chiavi API nel codice

Buone pratiche per un'API

  • Convalida sempre i dati inviati dagli utenti.

  • Servi l'API in HTTPS in produzione, con il Proxy Manager.

  • Non mostrare errori dettagliati in produzione.

  • Aggiungi un'autenticazione alle rotte sensibili.

Attivare CORS

Se un frontend ospitato su un altro dominio chiama la tua API, attiva CORS. Con Flask, aggiungi flask-cors.

# requirements.txt
flask-cors==4.0.0
from flask_cors import CORS
app = Flask(__name__)
CORS(app)

Con FastAPI, il middleware è già disponibile.

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)

Struttura avanzata

Per un'API più complessa, organizza il codice così. Questa struttura facilita la manutenzione delle API grandi.

LaMiaAPI/
├── app.py               ← Punto di ingresso
├── requirements.txt
├── .env
├── routes/
│   ├── __init__.py
│   ├── items.py         ← Rotte /api/items
│   └── users.py         ← Rotte /api/users
├── models/
│   └── item.py          ← Modello Item
└── utils/
    └── helpers.py       ← Funzioni utilitarie

Hai bisogno di aiuto?

Apri un ticket da Ticket › Aprire un ticket, oppure dal riquadro Contatta il supporto in fondo alla scheda del tuo server nell'area clienti. Puoi anche fare la tua domanda sul Discord di OuiHeberg.

Questo articolo ti è stato utile?

275 visualizzazioni
Condividi questo articolo
Python
Hai bisogno di un hosting Python?

Distribuisci le tue applicazioni Python con il nostro hosting ottimizzato e supporto dedicato.

Vedi le offerte →

Articoli correlati