RomanNum3ral
/
MicroFish
mirror of https://github.com/666ghj/MiroFish.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
MicroFish/INSTALL.md

7.4 KiB
Raw Blame History

MiroFish — Guia d'instal·lació i desplegament

Aquesta guia cobreix les dues modalitats d'execució:

1. Desenvolupament local

Prerequisits

Eina Versió Comprovació
Node.js ≥ 18 node -v
Python ≥ 3.11, ≤ 3.12 python --version
uv última uv --version

Instal·lació

# 1. Clonar el repositori
git clone https://github.com/jaumemir/MiroFish.git
cd MiroFish

# 2. Configurar variables d'entorn
cp .env.example .env
# Edita .env i omple els valors (vegeu la secció de variables)

# 3. Instal·lar totes les dependències (Node + Python)
npm run setup:all

Variables d'entorn (.env)

# ── LLM principal (OpenAI-compatible) ─────────────────────────────
LLM_API_KEY=la-teva-clau
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL_NAME=qwen-plus

# ── Zep Cloud (graf de memòria) ───────────────────────────────────
ZEP_API_KEY=la-teva-clau-zep

# ── LLM accelerador (opcional) ────────────────────────────────────
LLM_BOOST_API_KEY=
LLM_BOOST_BASE_URL=
LLM_BOOST_MODEL_NAME=

# ── Autenticació ──────────────────────────────────────────────────
# Contrasenya de l'usuari "demo" per accedir a l'app
DEMO_PASSWORD=una-contrasenya-segura

# Clau per signar tokens JWT
# Genera-la amb: python -c "import secrets; print(secrets.token_hex(32))"
SECRET_KEY=una-clau-secreta-llarga

Execució

npm run dev

Obre el navegador a http://localhost:3000.
Fes login amb usuari demo i la DEMO_PASSWORD que has configurat.

El frontend (port 3000) i el backend (port 5001) s'inicien simultàniament.
Vite proxia automàticament les peticions /api/* al backend.

2. Desplegament a Azure Container Apps

Prerequisits

Eina Versió Instal·lació
Azure CLI ≥ 2.60 docs.microsoft.com/cli/azure/install-azure-cli
Docker ≥ 24 docs.docker.com/get-docker
Python 3 ≥ 3.8 (per processar outputs JSON dels scripts)

Estructura dels fitxers de desplegament

azure/
├── config.sh.example   # plantilla de configuració (commited al repo)
├── config.sh           # valors reals amb secrets  (NO comitejar mai — gitignored)
├── infra.bicep         # infraestructura base: ACR + Container Apps Env
├── container-app.bicep # Container App: es re-desplega a cada nova versió
├── 1-infra.sh          # script pas 1: crea la infraestructura (una sola vegada)
└── 2-build-deploy.sh   # script pas 2: build Docker + push + deploy (cada versió)

Pas 0 — Login a Azure

az login

Pas 1 — Configuració

cp azure/config.sh.example azure/config.sh

Edita azure/config.sh i omple tots els valors:

Variables obligatòries

Variable Descripció On obtenir-la
AZURE_SUBSCRIPTION_ID ID de la subscripció Azure az account show --query id -o tsv
AZURE_LOCATION Regió Azure (ex: westeurope) Llista de regions
DEMO_PASSWORD Contrasenya de l'usuari demo Escull una contrasenya segura
SECRET_KEY Clau Flask per signar JWT python -c "import secrets; print(secrets.token_hex(32))"
LLM_API_KEY Clau de l'API LLM Alibaba Bailian o OpenAI
LLM_BASE_URL URL base de l'API LLM Default: Alibaba Qwen
LLM_MODEL_NAME Nom del model Default: qwen-plus
ZEP_API_KEY Clau de Zep Cloud app.getzep.com

Variables opcionals

Variable Descripció Default
LLM_BOOST_API_KEY Clau LLM accelerador (buit = desactivat)
LLM_BOOST_BASE_URL URL LLM accelerador (buit)
LLM_BOOST_MODEL_NAME Model LLM accelerador (buit)
OASIS_DEFAULT_MAX_ROUNDS Rondes màximes simulació 10
REPORT_AGENT_MAX_TOOL_CALLS Crides màximes a eines 5
REPORT_AGENT_MAX_REFLECTION_ROUNDS Rondes de reflexió 2
REPORT_AGENT_TEMPERATURE Temperatura del Report Agent 0.5

Seguretat: azure/config.sh està al .gitignore. Mai el comiteges al repositori.

Pas 2 — Crear infraestructura (una sola vegada)

bash azure/1-infra.sh

Aquest script crea al resource group rg_mirofish:

Recurs Nom Descripció
Resource Group rg_mirofish Contenidor de tots els recursos
Container Registry mirofsihacr Registre privat Docker (SKU Basic)
Container Apps Environment mirofish-env Plataforma d'execució de contenidors

Al final imprimeix l'ACR Login Server i l'ID de l'entorn. Guarda'ls si els necessites.

Idempotent: pots executar-lo múltiples vegades sense errors.

Pas 3 — Build i deploy (a cada nova versió)

bash azure/2-build-deploy.sh

El script fa automàticament:

  1. Obté les dades de la infraestructura existent (ACR, Container Apps Env)
  2. Genera un tag de versió amb format <git-sha>-<timestamp>
  3. docker build de la imatge multi-stage (Vue build + Flask + gunicorn)
  4. docker push a l'ACR privat
  5. Desplega la Container App via Bicep amb tots els secrets configurats

Al final imprimeix la URL de l'aplicació:

URL de l'aplicació: https://mirofish.<hash>.westeurope.azurecontainerapps.io

Gestió de versions i re-deploys

Cada execució de 2-build-deploy.sh genera una nova revisió de la Container App amb tag únic. La versió latest sempre apunta a la darrera imatge.

Per veure l'historial de revisions:

az containerapp revision list \
  --name mirofish \
  --resource-group rg_mirofish \
  --output table

Per consultar els logs en temps real:

az containerapp logs show \
  --name mirofish \
  --resource-group rg_mirofish \
  --follow

Arquitectura de producció

Internet
    │  HTTPS
    ▼
Container Apps Ingress (port 5001)
    │
    ▼
Flask + gunicorn (1 worker, 4 threads)
    ├── GET /              → serveix Vue SPA (frontend/dist/)
    ├── POST /api/auth/login  → autenticació JWT (pública)
    └── /api/*             → protegit per JWT Bearer token

Escalat automàtic: de 1 a 10 rèpliques per nombre de peticions concurrents (llindar: 20).

Solució de problemes habituals

Problema Causa probable Solució
ERROR: No s'ha trobat azure/config.sh Fitxer no creat cp azure/config.sh.example azure/config.sh
Cannot login to ACR Docker no està en execució docker info i arrenca Docker
Login retorna 401 sempre DEMO_PASSWORD buida o incorrecta Verifica el valor a config.sh / secret Azure
Container App no arrenca Imatge no trobada a l'ACR Verifica que 2-build-deploy.sh hagi finalitzat sense errors
Token expirat al cap de 24h Comportament esperat Torna a fer login a /login