# ComfyUI — Manual de Referência para Agente
Este documento é a referência completa do setup ComfyUI nesta máquina.
Usa-o como contexto quando precisares de operar, diagnosticar ou modificar qualquer parte do sistema.
---
## 1. Arquitectura Geral
```
Internet
│
▼
Cloudflare Tunnel (serviço Windows "cloudflared", sempre ligado)
│ domínio: comfyui.stratia.app.br
│
▼
Controlador (porta 8189) ─── D:\Ai\comfyui\comfyui_controller.py
│
├─ /ctrl/* → endpoints de controlo (start/stop/status/web UI)
│
└─ /* → proxy transparente para ComfyUI
│
▼
ComfyUI (porta 8188) ─── D:\Ai\comfyui\main.py
```
O fluxo é:
1. O tunnel Cloudflare redireciona `comfyui.stratia.app.br` para `127.0.0.1:8189`
2. O controlador na 8189 trata `/ctrl/*` (ligar/desligar) e faz proxy de tudo o resto para o ComfyUI na 8188
3. O ComfyUI corre como subprocesso do controlador (quando iniciado via `/ctrl/start`)
---
## 2. Caminhos e Ficheiros Importantes
### Directório principal
```
D:\Ai\comfyui\ ← raiz do ComfyUI
├── main.py ← entrypoint do ComfyUI
├── comfyui_controller.py ← controlador remoto (porta 8189)
├── .controller_key ← API key do controlador
├── comfyui_controller.log ← log do controlador
├── venv\ ← virtualenv Python 3.12.7
│ └── Scripts\
│ ├── python.exe ← Python do venv
│ ├── pythonw.exe ← Python sem consola (para background)
│ ├── pip.exe ← pip do venv
│ └── activate.bat ← activar venv em cmd
├── custom_nodes\ ← 45 custom nodes instalados
├── models\ ← modelos (checkpoints, loras, etc.)
├── input\ ← imagens de input
├── output\ ← imagens geradas
├── temp\ ← ficheiros temporários
├── user\default\ComfyUI-Manager\config.ini ← config do Manager
├── extra_model_paths.yaml ← paths extra para modelos
├── requirements.txt ← dependências core do ComfyUI
├── NODES_DISPONIVEIS.md ← catálogo de todos os nodes
└── MANUAL_AGENTE.md ← este ficheiro
```
### Cloudflare Tunnel
```
C:\Users\henri\.cloudflared\config.yml ← config do tunnel
C:\Users\henri\.cloudflared\88f29dbe-*.json ← credenciais do tunnel
```
### Scripts no Desktop
```
C:\Users\henri\OneDrive\Área de Trabalho\
├── ComfyUI - LIGAR.bat ← inicia ComfyUI local (venv + --lowvram)
├── ComfyUI - DESLIGAR.bat ← mata processo ComfyUI
├── ComfyUI - Tunnel LIGAR.bat ← inicia serviço cloudflared (requer admin)
├── ComfyUI - Tunnel DESLIGAR.bat ← para serviço cloudflared (requer admin)
└── ComfyUI - Controlador.bat ← inicia controlador na porta 8189
```
### Arranque automático
```
C:\Users\henri\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\
└── ComfyUI_Controller.bat ← inicia controlador ao login do Windows
```
---
## 3. Python e Virtualenv
| Item | Valor |
|------|-------|
| Python do sistema | `C:\Program Files\Python312\python.exe` (3.12.7) — **NÃO USAR para ComfyUI** |
| Python do venv | `D:\Ai\comfyui\venv\Scripts\python.exe` (3.12.7) |
| pip do venv | `D:\Ai\comfyui\venv\Scripts\pip.exe` |
| Activar venv (cmd) | `call D:\Ai\comfyui\venv\Scripts\activate.bat` |
| Activar venv (bash) | `source D:/Ai/comfyui/venv/Scripts/activate` |
### Pacotes críticos no venv
| Pacote | Versão | Nota |
|--------|--------|------|
| torch | 2.6.0+cu124 | PyTorch com CUDA 12.4 |
| numpy | 2.4.2 | Compatível com numba 0.64 |
| numba | 0.64.0 | Necessário para MelBandRoFormer e was-node-suite |
| transformers | 5.2.0 | Quebra LayerStyle_Advance (AutoModelForVision2Seq removido) |
### Instalar novas dependências
```bash
# SEMPRE usar o pip do venv, nunca o do sistema
"D:\Ai\comfyui\venv\Scripts\pip.exe" install <pacote>
# Verificar dependências quebradas
"D:\Ai\comfyui\venv\Scripts\pip.exe" check
```
---
## 4. Controlador Remoto
### Ficheiro
`D:\Ai\comfyui\comfyui_controller.py`
### Portas
| Serviço | Porta | Bind |
|---------|-------|------|
| Controlador | 8189 | 127.0.0.1 |
| ComfyUI | 8188 | 127.0.0.1 |
### API Key
Guardada em `D:\Ai\comfyui\.controller_key`.
Conteúdo actual: `YK-Dg2hC1mt-Xhpqs3v7XVHZRk7mIOMpJsgSdBlOi_U`
### Endpoints
| Método | Endpoint | Auth | Descrição |
|--------|----------|------|-----------|
| GET | `/ctrl/` | Não | Página web com botões Start/Stop/Status |
| GET | `/ctrl/status` | Sim | JSON: `{"running": true/false, "pid": 1234}` |
| POST | `/ctrl/start` | Sim | Inicia ComfyUI com `--lowvram --listen 127.0.0.1 --port 8188` |
| POST | `/ctrl/stop` | Sim | Para ComfyUI gracefully (SIGTERM, depois SIGKILL após 15s) |
| `*` | `/*` | Não | Proxy transparente para ComfyUI porta 8188 |
### Autenticação
A API key é enviada de duas formas:
1. **Header**: `X-API-Key: <chave>` (preferido)
2. **Query param**: `?key=<chave>` (para browser)
### Exemplos curl
```bash
# Ver status
curl -H "X-API-Key: YK-Dg2hC1mt-Xhpqs3v7XVHZRk7mIOMpJsgSdBlOi_U" http://127.0.0.1:8189/ctrl/status
# Ligar ComfyUI
curl -X POST -H "X-API-Key: YK-Dg2hC1mt-Xhpqs3v7XVHZRk7mIOMpJsgSdBlOi_U" http://127.0.0.1:8189/ctrl/start
# Desligar ComfyUI
curl -X POST -H "X-API-Key: YK-Dg2hC1mt-Xhpqs3v7XVHZRk7mIOMpJsgSdBlOi_U" http://127.0.0.1:8189/ctrl/stop
# Via tunnel (remoto)
curl -H "X-API-Key: YK-Dg2hC1mt-Xhpqs3v7XVHZRk7mIOMpJsgSdBlOi_U" https://comfyui.stratia.app.br/ctrl/status
```
### Log
O controlador escreve log em `D:\Ai\comfyui\comfyui_controller.log`.
### Iniciar manualmente
```bash
# Com consola (debug)
cd D:\Ai\comfyui
venv\Scripts\python.exe comfyui_controller.py
# Sem consola (background)
start /min "" "D:\Ai\comfyui\venv\Scripts\pythonw.exe" "D:\Ai\comfyui\comfyui_controller.py"
```
---
## 5. Cloudflare Tunnel
### Serviço Windows
| Item | Valor |
|------|-------|
| Nome do serviço | `cloudflared` |
| Estado | Sempre a correr (auto-start) |
| Domínio | `comfyui.stratia.app.br` |
| Aponta para | `http://127.0.0.1:8189` (controlador) |
| Tunnel ID | `88f29dbe-f62f-4fdc-9478-9d5b401f412e` |
### Config (`C:\Users\henri\.cloudflared\config.yml`)
```yaml
tunnel: comfyui
credentials-file: C:\Users\henri\.cloudflared\88f29dbe-f62f-4fdc-9478-9d5b401f412e.json
protocol: http2
ingress:
- hostname: comfyui.stratia.app.br
service: http://127.0.0.1:8189 # controlador (faz proxy ao ComfyUI)
- service: http_status:404
```
### Comandos (requerem admin)
```cmd
:: Ver estado
sc query cloudflared
:: Parar
net stop cloudflared
:: Iniciar
net start cloudflared
:: Reiniciar (para aplicar mudanças no config.yml)
net stop cloudflared && net start cloudflared
```
---
## 6. ComfyUI-Manager (Segurança)
### Ficheiro
`D:\Ai\comfyui\user\default\ComfyUI-Manager\config.ini`
### Configuração actual
```ini
[default]
security_level = normal # era "weak" — bloqueia installs remotos de nodes
network_mode = normal # era "public"
preview_method = none
use_uv = False
channel_url = https://raw.githubusercontent.com/ltdrdata/ComfyUI-Manager/main
share_option = all
bypass_ssl = False
file_logging = True
component_policy = workflow
update_policy = stable-comfyui
windows_selector_event_loop_policy = False
model_download_by_agent = False
always_lazy_install = False
db_mode = cache
```
### Níveis de segurança
| Nível | Descrição |
|-------|-----------|
| `weak` | Permite tudo remotamente (perigoso com tunnel) |
| `normal` | Bloqueia instalação de nodes via rede, permite o resto |
| `strong` | Bloqueia quase tudo via rede |
---
## 7. Custom Nodes — Estado Actual
### Funcionais (43/45)
**Audio/TTS (7):**
- ComfyUI-F5-TTS
- ComfyUI-FishSpeech
- benjiyaya_ComfyUI-KokoroTTS
- ComfyUI-VoxCPM
- comfyui-elevenlabs-integrtion
- ComfyUI-audio-nodes
- ComfyUI-MelBandRoFormer
**Vídeo (3):**
- ComfyUI-WanVideoWrapper
- comfyui-videohelpersuite
- comfyui-jakeupgrade
**Geração/IP-Adapter (7):**
- ComfyUI-IPAdapter-Flux
- comfyui-instantx-ipadapter-sd3
- comfyui_ipadapter_plus
- comfyui_ipadapter_plus_v2
- image_control
- flux-prompt-generator
- x-flux-comfyui
**Upscaling (1):**
- comfyui_ultimatesdupscale
**Análise de Imagem (4):**
- ComfyUI-Florence-2
- comfyui-florence2
- comfyui-wd14-tagger
- comfyui-ranbooru
**Processamento (4):**
- comfyui-post-processing-nodes
- ComfyUI-Vextra-Nodes
- comfyui_layerstyle
- (ComfyUI_LayerStyle_Advance — quebrado, ver abaixo)
**AI/Utilidades (17):**
- ComfyUI-Manager
- ComfyUI-Copilot
- comfyui-impact-pack
- comfyui-impact-subpack
- comfyui-advancedliveportrait
- comfyui-easy-use
- comfyui-kjnodes
- rgthree-comfy
- comfyui_essentials
- comfyui_essentials_mb
- comfyui_tinyterranodes
- comfyui_stringessentials
- ComfyUI_Comfyroll_CustomNodes
- aegisflow_utility_nodes
- cg-use-everywhere
- comfyui-various
- was-node-suite-comfyui
- websocket_image_save.py
### Quebrados (2/45)
| Node | Motivo | Resolução |
|------|--------|-----------|
| `__OFF__MaskGCT-ComfyUI` | Desactivado intencionalmente (prefixo `__OFF__`) | Manter assim. Para activar, renomear tirando `__OFF__` |
| `ComfyUI_LayerStyle_Advance` | `AutoModelForVision2Seq` removido em transformers 5.x | Aguardar update do autor. Downgrade de transformers quebraria outros nodes |
---
## 8. Modelos
### Directórios de modelos
```
D:\Ai\comfyui\models\
├── checkpoints\ ← modelos base (SD, SDXL, Flux, etc.)
├── clip\ ← modelos CLIP
├── clip_vision\ ← modelos CLIP Vision
├── controlnet\ ← ControlNet
├── diffusion_models\ ← modelos de difusão standalone
├── embeddings\ ← textual inversions
├── loras\ ← LoRA / LyCORIS
├── upscale_models\ ← modelos de upscaling (ESRGAN, etc.)
├── vae\ ← VAE
├── ipadapter\ ← modelos IP-Adapter
├── ipadapter_flux\ ← IP-Adapter para Flux
├── LLM\ ← modelos de linguagem
├── tts\ ← modelos text-to-speech
├── florence2\ ← modelos Florence-2
├── ultralytics\ ← modelos YOLO/detection
├── sams\ ← modelos SAM
├── text_encoders\ ← text encoders
├── unet\ ← UNet models
├── xlabs\ ← XLabs models
└── ...
```
### Config de paths extra (`extra_model_paths.yaml`)
O ficheiro `D:\Ai\comfyui\extra_model_paths.yaml` define paths adicionais.
O `base_path` aponta para `D:\AI\ComfyUI` (atenção: case diferente do directório real `D:\Ai\comfyui`).
---
## 9. Arranque do ComfyUI
### Flags importantes
| Flag | Descrição |
|------|-----------|
| `--lowvram` | Reduz uso de VRAM (essencial nesta máquina) |
| `--listen 127.0.0.1` | Só aceita conexões locais |
| `--port 8188` | Porta do servidor web |
| `--cpu` | Força uso de CPU (para testes sem GPU) |
### Comando completo para iniciar
```cmd
cd /d D:\Ai\comfyui
call venv\Scripts\activate.bat
python main.py --lowvram --listen 127.0.0.1 --port 8188
```
### Via controlador
O controlador inicia o ComfyUI com:
```
D:\Ai\comfyui\venv\Scripts\python.exe main.py --lowvram --listen 127.0.0.1 --port 8188
```
---
## 10. Troubleshooting
### ComfyUI não arranca
1. Verificar se o venv existe: `dir D:\Ai\comfyui\venv\Scripts\python.exe`
2. Testar imports: `D:\Ai\comfyui\venv\Scripts\python.exe -c "import torch; print(torch.cuda.is_available())"`
3. Verificar dependências: `D:\Ai\comfyui\venv\Scripts\pip.exe check`
4. Ver log do ComfyUI: `D:\Ai\comfyui\user\comfyui.log`
### Custom node falha ao carregar
1. Verificar se tem requirements.txt: `dir D:\Ai\comfyui\custom_nodes\<node>\requirements.txt`
2. Instalar deps: `D:\Ai\comfyui\venv\Scripts\pip.exe install -r D:\Ai\comfyui\custom_nodes\<node>\requirements.txt`
3. Re-testar: `pushd D:\Ai\comfyui && venv\Scripts\python.exe main.py --cpu --quick-test-for-ci 2>&1 | grep <node>`
### Controlador não responde
1. Verificar se está a correr: `tasklist | findstr python`
2. Ver log: `type D:\Ai\comfyui\comfyui_controller.log`
3. Verificar porta: `netstat -an | findstr 8189`
4. Reiniciar: matar processo e executar `ComfyUI - Controlador.bat`
### Tunnel não funciona
1. Verificar serviço: `sc query cloudflared`
2. Verificar config: `type C:\Users\henri\.cloudflared\config.yml`
3. A porta no config deve ser 8189 (controlador)
4. Reiniciar: `net stop cloudflared && net start cloudflared` (admin)
### numpy/numba incompatíveis
O numpy actual é 2.4.2 com numba 0.64.0 — funcionam juntos.
Se após update o numpy ficar incompatível:
```bash
# Ver versões
D:\Ai\comfyui\venv\Scripts\python.exe -c "import numpy; import numba; print(numpy.__version__, numba.__version__)"
# Fixar numpy se necessário
D:\Ai\comfyui\venv\Scripts\pip.exe install "numpy==2.1.0"
```
### Reinstalar venv do zero
```cmd
cd /d D:\Ai\comfyui
rmdir /s /q venv
"C:\Program Files\Python312\python.exe" -m venv venv
venv\Scripts\pip.exe install --upgrade pip
venv\Scripts\pip.exe install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
venv\Scripts\pip.exe install -r requirements.txt
:: Depois instalar deps de cada custom node (ver secção 7)
```
---
## 11. Operações Comuns
### Instalar novo custom node
```cmd
cd /d D:\Ai\comfyui\custom_nodes
git clone <url-do-node>
:: Se tiver requirements.txt:
D:\Ai\comfyui\venv\Scripts\pip.exe install -r <node>\requirements.txt
:: Reiniciar ComfyUI
```
### Actualizar ComfyUI
```cmd
cd /d D:\Ai\comfyui
git pull
D:\Ai\comfyui\venv\Scripts\pip.exe install -r requirements.txt
:: Reiniciar ComfyUI
```
### Actualizar custom node
```cmd
cd /d D:\Ai\comfyui\custom_nodes\<node>
git pull
:: Se tiver requirements.txt:
D:\Ai\comfyui\venv\Scripts\pip.exe install -r requirements.txt
:: Reiniciar ComfyUI
```
### Desactivar node (sem apagar)
Renomear a pasta adicionando `__OFF__` no início:
```cmd
ren "D:\Ai\comfyui\custom_nodes\<node>" "__OFF__<node>"
```
### Regenerar API key do controlador
```cmd
D:\Ai\comfyui\venv\Scripts\python.exe -c "import secrets; print(secrets.token_urlsafe(32))" > D:\Ai\comfyui\.controller_key
:: Reiniciar controlador
```
### Alterar segurança do Manager
Editar `D:\Ai\comfyui\user\default\ComfyUI-Manager\config.ini`:
- `security_level = normal` (actual) ou `strong` (mais restritivo)
- `network_mode = normal` (actual)
---
## 12. Resumo de Portas e Serviços
| Serviço | Porta | Bind | Estado |
|---------|-------|------|--------|
| ComfyUI | 8188 | 127.0.0.1 | Sob demanda (via controlador ou bat) |
| Controlador | 8189 | 127.0.0.1 | Auto-start com Windows |
| Cloudflare Tunnel | — | — | Serviço Windows, sempre ligado |
### Ordem de startup do sistema
1. Windows inicia → serviço `cloudflared` arranca automaticamente
2. Login do utilizador → `ComfyUI_Controller.bat` na Startup folder arranca o controlador na 8189
3. O utilizador (ou agente remoto) acede a `comfyui.stratia.app.br/ctrl/` e clica Start
4. O controlador inicia ComfyUI na 8188 como subprocesso
---
## 13. Segurança
- O ComfyUI **nunca** está exposto directamente à internet
- Todo o tráfego passa pelo controlador (8189) que depois faz proxy
- Os endpoints `/ctrl/*` requerem API key
- O Manager está em modo `security_level = normal` (bloqueia installs remotos)
- O tunnel Cloudflare fornece HTTPS/TLS automaticamente
- Ambas as portas (8188, 8189) fazem bind apenas a `127.0.0.1`
---
*Última actualização: 2026-03-02*