Instalación — AiHummer Documentos

AiHummer instala anfitrión-nativo. La instalación comienza en su cuenta personal en my.aihummer.ru: te registras, obtienes un enlace de instalación personal y ejecuta un solo comando en tu servidor. El script de instalación descarga un paquete firmado para tu arquitectura, y establece una raíz de instalación única bajo ~/.aihummer (en el directorio principal del usuario que ejecutó el instalador), registra las unidades de systemd y, opcionalmente, provisiona sidecars. No hay contenedores en ningún momento de este proceso.

[!NOTE] Esta es una instalación nativa del host: un paquete tar de lanzamiento que se ejecuta bajo systemd, no Docker. La puerta de enlace, los sidecars y los plugins se ejecutan cada uno como su propio systemd servicio.

[!NOTE] Lo que necesitarás antes de empezar:

un Linux servidor (x86_64 o arm64) al que puedes acceder por SSH;

sudo derechos (o una disposición a instalar sin privilegios de root — ver más abajo);

PostgreSQL con el pgcrypto extensión — o dejar que el instalador proporcione un clúster en modo usuario (en modo sin raíz lo hace él mismo);

una cuenta en my.aihummer.ru para obtener tu personal enlace de instalación.

La lista completa de requisitos está en la Requisitos página.

Paso 1: obtén tu enlace personal de instalación

No hay un script de instalación público: el enlace de instalación es personal y emitido en el portal de tu cuenta:

Registrar en my.aihummer.ru (número de teléfono + contraseña; también se necesita el correo electrónico).
Abrir el Instalación pantalla y haga clic en “Obtener enlace de instalación personal”.
El portal muestra un comando listo para ejecutar con tu enlace personal.

Más sobre el portal en sí (detalles de facturación, documentos, planes) está en el Cuenta personal página.

Paso 2: instalación con un solo comando

Copia el comando de la pantalla de “Instalación” y ejecútalo en tu servidor (Linux x86_64/arm64):

curl -fsSL -o install.sh "<your personal install link>" && sudo bash install.sh

El enlace personal tiene la forma https://my.aihummer.ru/dl/<token>/install.sh y está vinculado a tu cuenta.

[!IMPORTANT] El enlace es de un solo uso: sirve exactamente para una instalación. En cuanto el instalador ha descargado install.sh con él, el enlace queda consumido. Repetir la misma orden devuelve el error «el enlace ya se ha utilizado»: no es un fallo, sino una protección. Qué hacer: abre la pantalla «Instalación» de tu portal y genera un enlace nuevo; es gratuito e inmediato.

Los 30 días se refieren a la descarga de artefactos, no a repetir la instalación: una instancia ya instalada sigue actualizándose mediante su enlace mucho después de que este se haya gastado en la instalación.

El script detecta la arquitectura de tu CPU, descarga el paquete correspondiente junto con su .sha256 suma de verificación y co-firmar .sig firma, verifica ambos, descomprime la raíz de instalación y registra el servicio de puerta de enlace. Consulte el Registro de cambios para la versión actual.

El enlace personal también vincula la instancia a su cuenta del portal de clientes: el instalador almacena el token del enlace, la instancia lo envía en su primer registro con el proveedor, y el portal vincula automáticamente la instancia a su cuenta. Su correo electrónico se convierte inmediatamente en el de la instancia contacto verificado — no hay un paso separado de “adjuntar y verificar un correo electrónico” en la interfaz web, y la licencia se entrega sin pasos manuales.

[!WARNING] Tu enlace personal es tu clave para la distribución. No lo publiques: cualquiera mantener el enlace puede descargar compilaciones en tu nombre hasta que el token expire.

Instalar diseño raíz

Todo reside bajo un único directorio. Cuál exactamente depende de cómo hayas ejecutado el instalador:

Modo de instalación	Raíz de instalación	Configuración	Usuario del servicio
Instalación normal (con `sudo`)	`/home/.aihummer`	`/etc/aihummer/gateway.env`	Una cuenta de servicio `aihummer` dedicada
Sin root (rootless)	`~/.aihummer`	`~/.aihummer/etc/gateway.env`	Tu propio usuario

Una instalación normal no coloca archivos en tu directorio personal y no ejecuta el servicio con tu identidad: crea un usuario aihummer dedicado y sin privilegios. Es algo deliberado — comprometer el servicio no entrega a un atacante tus archivos personales.

La disposición dentro de la raíz es idéntica en ambos modos (se muestra la de una instalación normal):

/home/.aihummer/
├── bin/        gateway binary and the aihummer CLI
├── etc/        configuration (gateway.env)
├── share/      static assets for the administration interface
├── sidecars/   optional STT/TTS/etc services
├── plugins/    installed marketplace plugins
├── systemd/    unit files (symlinked into /etc/systemd/system)
├── state/      runtime state
├── data/       blob/media storage
└── logs/       service logs

Los archivos de unidad systemd generados en systemd/ son vinculado simbólicamente en /etc/systemd/system/, por lo que se gestionan de manera regular systemctl comandos.

Instalación sin raíz

sudoNo se requieren privilegios de root. Si ejecuta el comando de instalación sin sudo, el instalador cambia al modo sin root: las unidades se registran en la systemd --user alcance (archivos en ~/.config/systemd/user), el aihummer CLI y cosign aterrizan en ~/.aihummer/bin, y si AIHUMMER_DATABASE_URL no está configurado, el instalador proporciona un clúster de PostgreSQL en modo usuario dentro de la raíz de instalación. Los servicios se gestionan con systemctl --user .... Para que los servicios se inicien al arrancar el host (no solo al iniciar sesión del usuario), habilite la persistencia:

loginctl enable-linger $USER

Selección de sidecar

Los sidecars de medios ligeros — STT (faster-whisper), TTS (edge-tts) y video: instalar listo para usar, sin preguntas ni alertas: la voz de ida y vuelta funciona de inmediato. Cualquiera de ellas puede ser desactivada con las variables de entorno AIHUMMER_SKIP_STT=1, AIHUMMER_SKIP_TTS=1, AIHUMMER_SKIP_VIDEO=1.

La búsqueda web (SearXNG) y el navegador (CloakBrowser) están integrados en el paquete firmado y se instalan sin conexión de forma predeterminada: el instalador ya no pregunta por ellos. Las opciones cambian ese comportamiento — esta es la lista completa:

Bandera	Efecto
`--no-search` / `--no-browser`	Saltar este sidecar
`--external-search=URL` / `--external-browser=URL`	Usa un servicio existente en esta URL en lugar de instalar
`--browser-engine=cloak\|chrome`	Motor del navegador (por defecto `cloak`)
`--with-search` / `--with-browser`	Redundantes desde v1.0.14: ya es el comportamiento predeterminado
`--with-embedder`	Instalar el incrustador semántico (optar por participar: descarga PyTorch — cientos de MB)

La búsqueda y el navegador también se instalan sin un tty: su contenido proviene del paquete, por lo que no hace falta acceso a internet. Ambas instalaciones no son bloqueantes: si falta el contenido o la versión de Python no es compatible, el servicio simplemente queda sin configurar y la instalación nunca se interrumpe. El embeedor también se puede habilitar con AIHUMMER_WITH_EMBEDDER=1; sin él, la memoria funciona mediante una búsqueda de respaldo léxico. El idioma de la interfaz de usuario está configurado por AIHUMMER_LANG=ru|en (de lo contrario, el instalador pregunta en un tty). La conexión a PostgreSQL se solicita en un tty; para instalaciones no interactivas, configure AIHUMMER_DATABASE_URL con anticipación. En un tty, el instalador también ofrece restaurar desde una copia de seguridad.

# Instalar el gateway con el incrustador, sin el navegador (la búsqueda se instala por defecto)
curl -fsSL -o install.sh "<your personal install link>" && sudo bash install.sh \
  --with-embedder --no-browser

Debido a que los sidecars se acceden por URL, puedes mezclar libremente los nativos y los externos y apuntar varios gateways a un sidecar compartido.

Cómo se comprueba la autenticidad de la compilación

El enlace personal de tu portal instala siempre el lanzamiento vigente: es la vía estándar y la única. No hay ninguna «versión más reciente» que elegir — recibes la compilación que el proveedor ha publicado para su explotación.

Cada artefacto, tanto en la primera instalación como en cada actualización, llega como un paquete tar para tu arquitectura, acompañado de una suma de verificación .sha256 y una firma .sig (cosign). El instalador verifica ambas antes de descomprimir nada. Nunca tienes que comprobarlas a mano.

Resultado esperado: las comprobaciones pasan en silencio y la instalación continúa. Si alguna de ellas falla, el instalador se detiene con un error y deja intacta la versión en ejecución — un archivo dañado o sustituido nunca llega a tu servidor.

Si el proveedor te ha invitado a un programa de pruebas tempranas, la pantalla «Instalación» de tu portal muestra un selector y emite un enlace distinto para la opción que elijas; consulta Instancia.

Verificar la instalación

Después de que el instalador termine, verifica el servicio y el punto final de preparación:

systemctl status aihummer-gateway
curl -fsS http://localhost:8780/healthz
curl -fsS http://localhost:8780/readyz

/healthz informa sobre actividad y versión; /readyz verifica PostgreSQL y devuelve 503 mientras la base de datos no sea accesible. El incluido aihummer La CLI también proporciona aihummer status y aihummer doctor para una visión rápida de la salud.

Lo que verás después de una instalación exitosa: la aihummer-gateway servicio en active (running), a 200 de /healthz y /readyz, y la contraseña de administrador inicial en /home/.aihummer/etc/initial-admin-password.txt (en una instalación rootless, ~/.aihummer/etc/initial-admin-password.txt) para primer inicio de sesión.

Lista de verificación de producción

Un solo comando de instalación pone en marcha la puerta de enlace, pero está todavía no listo para producción. Antes de exponerlo, completa:

TLS — terminar HTTPS frente a la puerta de enlace (proxy inverso / propio) certificado); nunca exponga el puerto simple en una red no confiable.
🔴 Active la compatibilidad con WebSocket en el proxy inverso. La aplicación móvil y de escritorio se conecta a la pasarela por wss://, por lo que el proxy debe reenviar las cabeceras Upgrade y Connection. Sin ese ajuste, el proxy responde con una página normal y estado 200 en lugar de 101 Switching Protocols: la aplicación lo interpreta como «el servicio no responde», aunque la pasarela funciona y en su registro no hay ni un solo error. En Nginx Proxy Manager es el interruptor Websockets Support del Proxy Host correspondiente; en nginx normal — proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; más proxy_http_version 1.1 en el bloque location.

Comprobación con un solo comando (se espera 101, no 200):
```
curl -s -o /dev/null -w '%{http_code}\n' \
  -H 'Connection: Upgrade' -H 'Upgrade: websocket' \
  -H 'Sec-WebSocket-Version: 13' -H 'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==' \
  https://su-dominio/
```
Cambiar la contraseña de administrador y eliminar initial-admin-password.txt; establecer un emisor de autenticación (AIHUMMER_OIDC_ISSUER / LDAP / SAML) antes de exponer /admin/*.
Respaldar la llave maestra y la base de datos — registro AIHUMMER_MASTER_KEY (secretos son irrecuperables sin él) y configurar copias de seguridad regulares de PostgreSQL.
Cablear un modelo real — conjunto AIHUMMER_LLM_* (o BYOK); sin él las respuestas vienen del simulacro determinista.
Conecta al menos un canal (Telegrama para empezar) y vincular un agente a él.

Ver Primer inicio de sesión, Configuración y Copias de seguridad y recuperación ante desastres para los detalles.

Si no funcionó

«el enlace ya se ha utilizado» / la instalación no arranca por segunda vez — el enlace es de un solo uso y un intento anterior ya lo gastó. Genera uno nuevo en la pantalla «Instalación» del portal y vuelve a ejecutar la orden.
curl: (22) … 404 o «enlace inválido» — el enlace se copió de manera incompleta o su plazo ha vencido. El remedio es el mismo: un enlace nuevo.
arquitectura no soportada — la instalación es compatible con Linux x86_64 y arm64; no hay paquete para otras plataformas.
/readyz devuelve 503 — la puerta de enlace no puede ver PostgreSQL. Verifique AIHUMMER_DATABASE_URL, la accesibilidad de la base de datos, y que la pgcrypto extensión se crea (CREATE EXTENSION IF NOT EXISTS pgcrypto;).
El servicio no se inició — inspeccionar systemctl status aihummer-gateway y journalctl -u aihummer-gateway; para una ejecución de diagnóstico rápido aihummer doctor.
Instalado sin sudo, los servicios se detienen después de cerrar sesión — habilitar la persistencia: loginctl enable-linger $USER (ver sin raíces).
La verificación de la firma falló — no continúe con la instalación; intente de nuevo más tarde o conseguir un enlace nuevo. El artefacto siempre se verifica contra su .sha256 y aval .sig.

¿A dónde vamos ahora?

Primera carrera: ver Primer inicio de sesión recuperar la contraseña de administrador inicial de /home/.aihummer/etc/initial-admin-password.txt (en una instalación rootless, ~/.aihummer/etc/initial-admin-password.txt).
Ajusta la implementación: leer Configuración.
¿Quieres una primera carrera guiada? Usa el Inicio rápido.