Arquitetura e Fundamentos

O painel aaPanel não oferece uma solução nativa de "clique único" para aplicativos Python complexos. Para garantir estabilidade e desempenho em produção, é essencial configurar manualmente uma pilha de serviço robusta. O fluxo de dados recomendado segue a ordem: Usuário → Nginx (Proxy Reverso) → Servidor WSGI (Gunicorn) → Aplicação (Flask/Django).

É um erro comum tentar rodar aplicações diretamente com comandos como python app.py ou python manage.py runserver em servidores de produção. Esses métodos não possuem gerenciamento de processos adequado e apresentam baixo desempenho sob carga. A utilização de um servidor WSGI como o Gunicorn é obrigatória.

Configuração do Ambiente

Instalação do Interpretador Python

1. Acesse o painel aaPanel e navegue até a Loja de Aplicativos (App Store).
2. Procure por "Gerenciador de Projetos Python" e realize a instalação do plugin.
3. Após a instalação, abra o plugin, vá para a seção de gerenciamento de versões e instale a versão do Python compatível com o seu projeto (recomenda-se 3.9 ou superior).

Preparação do Código

Certifique-se de que seu repositório contenha os arquivos essenciais: o arquivo de dependências (ex: requirements.txt), o ponto de entrada da aplicação (ex: wsgi.py ou main.py) e todos os módulos do código fonte.

Procedimento de Implantação

Transferência de Arquivos

Você pode utilizar o "Gerenciador de Arquivos" do aaPanel para fazer o upload do compactado do seu projeto para o diretório /www/wwwroot/ ou usar uma conexão SFTP via ferramentas como FileZilla.

Configuração do Ambiente Virtual

Através do terminal do aaPanel ou via SSH, execute os seguintes comandos para isolar as dependências do projeto:

cd /www/wwwroot/nome-do-projeto
python3.9 -m venv venv
source venv/bin/activate
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

Instalação do Servidor de Aplicação

Dentro do ambiente virtual ativado, instale o Gunicorn:

pip install gunicorn

Configuração do Nginx

No menu "Sites", crie um novo site. Defina o domínio (ou IP do servidor) e configuer o ambiente como "Estático". Em seguida, acesse as configurações do site criado:

1. Na aba "Proxy Reverso", adicione uma nova apontando para http://127.0.0.1:5000.
2. Edite o arquivo de configuração do Nginx diretamente para incluir o tratamento de arquivos estáticos e mídia:

location /static/ {
    alias /www/wwwroot/nome-do-projeto/static/;
}
location /media/ {
    alias /www/wwwroot/nome-do-projeto/media/;
}

Após salvar, valide e recarregue o Nginx:

nginx -t && nginx -s reload

Execução da Aplicação

Inicializando o Gunicorn

Para iniciar o servidor, utilize o comando adaptado ao seu framework.

Para Flask:

gunicorn --workers 4 --bind 127.0.0.1:5000 --chdir /www/wwwroot/nome-do-projeto modulo_principal:app

Para Django:

gunicorn --workers 4 --bind 127.0.0.1:5000 --chdir /www/wwwroot/nome-do-projeto config_projeto.wsgi:application

Persistência de Processos com Supervisor

Para garantir que o serviço reinicie automaticamente em caso de falha ou reinicialização do servidor, utilize o Supervisor.

Instale o Supervisor via pip ou gerenciador de pacotes do sistema. Crie um arquivo de configuração em /etc/supervisor/conf.d/projeto.conf:

[program:app_python]
command=/www/wwwroot/nome-do-projeto/venv/bin/gunicorn --workers 4 --bind 127.0.0.1:5000 --chdir /www/wwwroot/nome-do-projeto config_projeto.wsgi:application
directory=/www/wwwroot/nome-do-projeto
user=www
autostart=true
autorestart=true
redirect_stderr=true
stdout_logfile=/www/wwwlogs/app_python.log

Atualize e inicie os serviços do Supervisor:

supervisorctl update
supervisorctl start app_python

Tratamento de Arquivos Estáticos (Django)

No arquivo settings.py, certifique-se de que as variáveis estão corretas:

STATIC_URL = '/static/'
STATIC_ROOT = '/www/wwwroot/nome-do-projeto/staticfiles'

Execute o comando de coleta no terminal:

python manage.py collectstatic --noinput

Ajuste a configuração do Nginx para apontar para STATIC_ROOT no bloco location /static/.

Domínio e Segurança SSL

1. Configure o registor DNS do seu domínio apontando o registro A para o IP do servidor.
2. Na área de gerenciamento do site no aaPanel, adicione o domínio.
3. Na aba SSL, utilize a opção "Let's Encrypt" para emitir um certificado gratuito.

Importante: Adicione o domínio à variável ALLOWED_HOSTS no Django:

ALLOWED_HOSTS = ['meudominio.com', 'www.meudominio.com']

Solução de Problemas

• Erro 502 Bad Gateway: Indica que o Nginx não consegue se comunicar com o Gunicorn. Verifique se o processo está rodando com ps aux | grep gunicorn.
• Erro 500 Internal Server Error: Problema na lógica da aplicação. Consulte os logs definidos no stdout_logfile do Supervisor.
• Recursos estáticos não carregam: Verifique as permissões de leitura das pastas e o caminho no alias do Nginx.
• ModuleNotFoundError: Garanta que todas as dependências foram instaladas no ambiente virtual correto.

Lista de Verificação Final

• Firewall do sistema e security group do provedor de nuvem permitem tráfego nas portas 80 e 443.
• A versão correta do Python está instalada no aaPanel.
• O ambiente virtual (venv) foi criado e as dependências instaladas.
• O Gunicorn está instalado e configurado para rodar na porta definida no proxy do Nginx.
• O Supervisor está ativo e gerenciando o processo do Gunicorn.
• Arquivos estááticos foram coletados e servidos corretamente pelo Nginx.
• SSL está configurado e o acesso HTTPS está funcional.