HQbird 2027 en Docker: guía del administrador
Esta guía es para el administrador que ejecuta HQbird 2027 en Docker. Un contenedor es una instancia de Firebird con todos los componentes de HQbird:
- Firebird (la compilación de HQbird de una línea: 5.0, 4.0, 3.0 o 2.5);
- agente de HQbird (
fbagent): copias de seguridad, monitorización, tareas de mantenimiento, actualizaciones, la conexión con HQCenter; - HQ Monitor: la consola web de la instancia;
- nodo de clúster (
hqclusternode) y RCM (hqbirdrcm): los instala el agente cuando HQCenter añade esta instancia a un clúster, o cuando usted asigna al contenedor un rol de clúster (sección 7). Sin un rol y sin HQCenter, el contenedor no ejecuta ningún componente de clúster.
El contenedor instala HQbird con el mismo instalador sin conexión que un servidor (guía de instalación en Linux). El agente actualiza después Firebird, HQ Monitor, los componentes del clúster y a sí mismo desde HQCenter, como en un servidor. Sus datos, la configuración, la licencia, los certificados de HQCenter y los programas actualizados están en volúmenes: permanecen cuando vuelve a crear el contenedor o cambia la imagen.
Versión actual: 2027.2.33 (2026-11-16): Firebird 2.5.9, 3.0.15, 4.0.8 y 5.0.5, agente 3.4.0, HQ Monitor 1.57.0, RCM y nodo 2027.5.12.
Probado el 2026-11-16 en Ubuntu 22.04.5 (2 vCPU / 4 GB), Docker 29.10.0,
Compose 5.7.1, imagen hqbird2027-fb40:2027.2.33 (primera prueba: 2026-11-11,
imagen 2027.2.27). Una instalación paso a paso
para Ubuntu 22.04: hqbird2027-docker-install-fb40.ru.md
(ruso), hqbird2027-docker-install-fb40.pt.md
(portugués).
El rol de clúster (sección 7.1) y el switchover (sección 7.3) se probaron
el 2026-11-16 en las imágenes 5.0, 4.0, 3.0 y 2.5, con los dos «hosts»
como dos direcciones de una VM, y en dos hosts Docker separados (dos droplets, la
imagen 4.0 2027.2.33). El 2026-11-17 se probó el resto en dos hosts Docker
con la imagen 5.0 2027.2.33: un clúster hecho a mano en contenedores 2027.2.32
y trasladado a la imagen nueva (ambos contenedores healthy en 35
segundos), HQBIRD_RCM_ALLOW, las páginas Services de la consola de RCM y
el failover automático. Los routers (HAProxy) no arrancan en las imágenes hasta
2027.2.33 (sección 9); la imagen siguiente incluye la corrección.
1. Imágenes
| Imagen | Firebird | Puerto predeterminado |
|---|---|---|
ghcr.io/ibsurgeon/hqbird2027-fb50:<version> |
5.0 | 3050 |
ghcr.io/ibsurgeon/hqbird2027-fb40:<version> |
4.0 | 3050 |
ghcr.io/ibsurgeon/hqbird2027-fb30:<version> |
3.0 | 3050 |
ghcr.io/ibsurgeon/hqbird2027-fb25:<version> |
2.5 | 3050 |
Las imágenes están en el GitHub Container Registry de IBSurgeon
(https://github.com/orgs/IBSurgeon/packages). Son públicas: no hace
falta iniciar sesión. <version> es la versión de setup de HQbird, por ejemplo
2027.2.33. La etiqueta 2027.2 es la imagen 2027.2.x más reciente.
docker pull ghcr.io/ibsurgeon/hqbird2027-fb50:2027.2.33Las imágenes están firmadas con cosign. La clave pública hqbird-cosign.pub aún
no está publicada (2026-11-16). Las imágenes 2027.2.33 están firmadas. Cuando tenga la clave, compruebe una imagen
antes de usarla:
cosign verify --key hqbird-cosign.pub ghcr.io/ibsurgeon/hqbird2027-fb50:2027.2.332. Primer arranque
-
Copie
compose.yaml(deops/docker/de la versión) a una carpeta del host Docker. -
Ponga la contraseña de SYSDBA en un archivo, legible solo por usted:
mkdir -p secrets && openssl rand -hex 12 > secrets/sysdba_password && chmod 600 secrets/sysdba_password -
En
compose.yaml, definaimage:,hostname:y quite el#de las líneassecrets:que use. -
Arranque el contenedor:
docker compose up -d -
Observe la instalación (unos minutos en el primer arranque):
docker compose logs -fEn 2 vCPU la instalación tarda unos 20 segundos. Ha terminado cuando el registro muestra
[hqbird-boot] ready: firebird.service=active ...ydocker compose psmuestrahealthy.
Después:
- Firebird:
<docker host>:3050. - HQ Monitor:
http://<docker host>:23050/, usuarioadmin. El instalador crea la contraseña; léala condocker compose exec hqbird cat /opt/hqbird/conf/access.properties. - El id del agente en HQCenter: el nombre de host + la fecha de instalación (YYMMDD) +
-fbNN, por ejemplohqbird-fb40-3051261111-fb40.
Conserve el nombre de host. La identidad de licencia de la instancia es el
machine-id del volumen state y el id del agente. Un volumen state nuevo es
una instalación nueva.
3. Ajustes
Los ajustes se leen solo en el primer arranque (la instalación).
| Ajuste | Qué hace |
|---|---|
HQBIRD_FB_PORT |
Puerto de Firebird dentro del contenedor (predeterminado 3050). HQ Monitor usa 20000 + este puerto |
HQBIRD_HQM_PORT |
otro puerto de HQ Monitor |
HQBIRD_AGENT_ID |
el id del agente (predeterminado: se forma con el nombre del host, la fecha y el puerto) |
HQBIRD_HQM_LOGIN + secreto hqmonitor_password |
el usuario de HQ Monitor |
HQBIRD_TRIAL_EMAIL, HQBIRD_TRIAL_ZONE |
solicitar una licencia de prueba (usted acepta la política de privacidad) |
HQBIRD_DEBUG=1 |
instalar los archivos de depuración de Firebird |
secreto sysdba_password |
la contraseña SYSDBA de un Firebird nuevo |
secreto license |
un archivo de licencia |
secreto attach |
attach.json de HQCenter: conectar el agente a su HQCenter |
HQBIRD_CLUSTER_ROLE |
master o replica: un clúster sin HQCenter (sección 7). Vacío: sin clúster |
HQBIRD_CLUSTER_ADDRESS |
master, obligatorio: la dirección o el nombre DNS del host Docker, tal como los alcanzan el replica y el navegador. Una lista con comas; el primero entra en la RCM URL |
HQBIRD_CLUSTER_ID |
master: el id del clúster (predeterminado: el nombre del host) |
secreto rcm_password |
master: la contraseña del usuario RCM rcmadmin (predeterminado: una generada) |
HQBIRD_RCM_ALLOW |
replica: solo estos RCM pueden invitar al contenedor (IP, CIDR, nombre de host; predeterminado: cualquiera). Escriba la dirección del host Docker del master: el replica ve esa dirección. En un solo host Docker el replica ve la puerta de enlace de su red Docker |
HQBIRD_PAIRING_PORT, HQBIRD_NODE_PORT |
el slot del clúster: puerto de emparejamiento 7450-7459 y puerto de nodo = puerto de emparejamiento - 399 (predeterminado 7450 y 7051) |
4. Volúmenes
| Volumen | Ruta | Contenido |
|---|---|---|
opt |
/opt |
Firebird, el agente, HQ Monitor, nodo de clúster, RCM |
state |
/var/lib/hqbird-container |
units, sudoers, datos de HQ Monitor, registros del agente, machine-id, estado del setup, las cuentas del sistema operativo creadas en tiempo de ejecución (el usuario de servicio de RCM) |
trust |
/usr/libexec/hqbird-fbagent |
el lanzador de actualizaciones del agente y la confianza |
rootwork |
/var/lib/hqbird-fbagent |
la carpeta de trabajo del lanzador de actualizaciones |
db |
/db |
bases de datos (ponga aquí sus bases de datos) |
backup |
/backup |
copias de seguridad |
No monte carpetas del host en opt, state, trust y rootwork. Puede
usar carpetas del host para db y backup; déselas al uid 84 (el usuario firebird
de la imagen):
chown 84:84 /srv/hqbird/db /srv/hqbird/backupHaga una copia de seguridad de los seis volúmenes juntos.
5. Trabajo diario
| Tarea | Comando |
|---|---|
| Estado de los servicios | docker compose exec hqbird systemctl list-units --type=service |
| Reiniciar Firebird | docker compose exec hqbird systemctl restart firebird (Firebird 3.0: firebird-superserver) |
| isql | docker compose exec hqbird /opt/firebird/bin/isql -user SYSDBA localhost/<port>:/db/my.fdb |
| Registros | docker compose logs --since 1h |
| Detener (Firebird cierra las bases de datos) | docker compose stop |
Dentro del contenedor, systemctl controla los servicios de HQbird. No es
systemd: admite los comandos que usan los programas de HQbird (start, stop,
restart, status, is-active, enable, disable, show,
list-units, daemon-reload).
6. Actualizaciones
Hay dos formas de actualizar. Ambas conservan los datos.
-
Desde HQCenter (como en un servidor): HQCenter actualiza el agente, HQ Monitor, Firebird, el nodo de clúster y RCM dentro del contenedor.
-
Imagen nueva: cambie
image:a la versión nueva y después:docker compose pull && docker compose up -dEn el arranque, el contenedor ejecuta el instalador de la imagen nueva en modo de actualización. Si HQCenter ya actualizó el agente a una versión más reciente que la de la imagen, el instalador no se ejecuta (no hay bajada de versión); el registro lo indica.
Un contenedor nuevo (una imagen nueva, o docker compose down y up -d sin
-v) conserva el clúster: el rol, el id del clúster, RCM, los nodos y el
enlace con el otro host están en los volúmenes. Los ajustes de clúster del
archivo compose no se vuelven a leer. Las imágenes hasta 2027.2.32 tienen dos defectos
aquí: véase la sección 9.
7. Clúster
Hay dos formas de crear un clúster. No las mezcle en un mismo contenedor.
7.1. Sin HQCenter: dos contenedores con un rol
Un contenedor es el master y ejecuta el gestor del clúster (RCM) con su
consola. El otro es un replica. El rol es un ajuste del primer
arranque: HQBIRD_CLUSTER_ROLE. Sin él, el contenedor no ejecuta RCM, ni
nodo de clúster, y no abre ningún puerto de emparejamiento. El rol necesita la imagen 2027.2.33 o
posterior.
Dos hosts Docker. Dé a los dos contenedores nombres de host distintos
(HQBIRD_HOSTNAME en .env, o hostname:): con el mismo nombre de host
los dos agentes tienen el mismo id, y RCM rechaza el replica
(duplicate). Copie compose.master.yaml al host master y
compose.replica.yaml al host replica, junto a compose.yaml
(ops/docker/ de la versión).
-
En el host master, ponga la dirección de ese host Docker en
.env, tal como la alcanzan el host replica y el navegador (nolocalhost, no la dirección del contenedor):echo 'HQBIRD_CLUSTER_ADDRESS=203.0.113.10' >> .env docker compose -f compose.yaml -f compose.master.yaml up -d -
En el host replica:
docker compose -f compose.yaml -f compose.replica.yaml up -d -
Lea las líneas de clúster de cada contenedor:
docker compose logs | grep -E 'cluster:|CA hash|Password'El master muestra la dirección de la consola y el
CA hash:[hqbird-boot] cluster: role=master id=... console=https://203.0.113.10:7444 login=rcmadmin. El replica muestra su puerto de emparejamiento y la huella:[hqbird-boot] cluster: role=replica pairing port 7450: open until ..., fingerprint sha256:.... -
Abra la consola
https://<master host>:7444. El usuario esrcmadmin. Sin el secretorcm_passwordla contraseña está en un archivo; RCM pide una nueva en el primer inicio de sesión:docker compose exec hqbird sh -c 'cat /opt/hqbird/fbagent-*/clusterca/*/rcm-initial-password' -
En Settings → Link hosts escriba dos líneas: la dirección que indicó en
HQBIRD_CLUSTER_ADDRESS(el master) y la dirección del host Docker del replica. No escriba un puerto: RCM lee los puertos de emparejamiento 7450-7459. El puerto de emparejamiento responde unos 30 segundos después de que el contenedor estáhealthy. La ventana Initialize propone la carpeta/databases/replica/..., que está fuera de los volúmenes: cámbiela. Esa ventana mide unos 1000 px de alto y no se desplaza: reduzca el zoom de la página si no ve los botones. Probado en el navegador el 2026-11-16. Compare la huella del replica con la de su registro. Deje RCM URL vacío. Después continúe con el paso 4 de la guía del clúster en Linux (carpeta de bases de datos, registrar, inicializar el replica). Para la carpeta de bases de datos del replica, use una carpeta del volumendb, por ejemplo/db/replica. Probado: una fila escrita en el master estaba en el replica en 30 segundos.
Para omitir las opciones -f, ponga
COMPOSE_FILE=compose.yaml:compose.master.yaml (o ...replica.yaml) en
.env.
Un host Docker. compose.cluster-one-host.yaml es un archivo completo
con ambos contenedores:
docker compose -f compose.cluster-one-host.yaml up -dLos contenedores se alcanzan entre sí por nombre en la red del proyecto, así que
los puertos del clúster no se publican. En Link hosts escriba
hqbird-master y hqbird-replica. El Firebird del master está en el puerto
3050, el del replica en 3051; la consola es https://<docker host>:7444.
Reglas:
- El rol y sus ajustes se leen solo en el primer arranque. Después, un
HQBIRD_CLUSTER_ROLEdistinto escribe una advertencia en el registro y no cambia nada. Para cambiar el clúster más adelante, use HQ Monitor (Clusters) o los comandosfbagent --cluster-inityfbagent --cluster-pairingdentro del contenedor. - Un ajuste incorrecto (un rol desconocido, un master sin
HQBIRD_CLUSTER_ADDRESS, un ajuste del otro rol) detiene el arranque antes de instalar nada. El registro dice qué hay que escribir ([hqbird-boot] error: ...); Docker vuelve a arrancar el contenedor y el registro repite la línea hasta que corrija el ajuste. - La ventana de emparejamiento de un replica permanece abierta 24 horas. Un reinicio de un
contenedor que aún no está en ningún clúster la abre de nuevo. Para cerrar el
puerto de emparejamiento hacia otras redes, use
HQBIRD_RCM_ALLOWo su cortafuegos; después del enlace puede quitar el puerto deports:. - Para un switchover (un servicio de RCM), cada host necesita un segundo nodo y su puerto publicado: véase la sección 7.3.
7.2. Con HQCenter
HQCenter añade la instancia a un clúster como añade un servidor. No defina
HQBIRD_CLUSTER_ROLE. En HQCenter, indique la dirección del host Docker
como dirección del miembro. En compose.yaml, publique los puertos de los
componentes del clúster:
| Componente | Puerto | Publicar cuando |
|---|---|---|
| nodo de clúster | el listen_port del nodo (por ejemplo 7051) |
la instancia es miembro del clúster |
| RCM | 7443 | HQCenter hace de este agente el RCM |
| consola de operador de RCM | 7444 | como arriba; defina operator_addr como 0.0.0.0:7444 en los ajustes de RCM |
El agente instala el nodo (y RCM) unos minutos después de guardar el clúster.
Hasta entonces el puerto del nodo no responde.
En HQCenter, defina el listen_port del nodo como el puerto publicado. Un replica espera hasta que el agente RCM sube la CA del clúster.
Probado el 2026-11-16 sin un rol: los agentes instalaron los nodos y RCM,
y todos los miembros volvieron a estar running después de docker compose down y
up -d.
7.3. Switchover entre los dos contenedores
Un servicio de RCM mueve el rol master de una base de datos de un host al otro. Para un servicio, cada host necesita dos nodos: un nodo master y un nodo replica. Link hosts da a cada host un nodo, así que usted añade los segundos nodos. Probado el 2026-11-16 en el par de la sección 7.1: el switchover tardó 25 segundos, el master antiguo pasó a ser un replica de solo lectura, y una fila escrita en el master nuevo estaba en él 15 segundos después.
Los pasos usan la API de operador de RCM en el puerto de la consola. curl pide
la contraseña de rcmadmin; -k omite la comprobación del certificado propio
del clúster:
RCM=https://203.0.113.10:7444
api() { curl -sk --digest -u rcmadmin -H 'Content-Type: application/json' "$@"; }-
Publique el puerto del segundo nodo en ambos hosts: puerto de nodo + 10. En
compose.master.yamlycompose.replica.yaml, quite el#de la línea"7061:7061"y ejecutedocker compose up -dcon las mismas opciones-f. Hágalo antes del primer arranque cuando pueda. -
Dé a cada nodo la dirección de su host Docker. RCM da esta dirección y el puerto de Firebird a las aplicaciones; sin ella obtienen la dirección del contenedor:
api -X PUT $RCM/v1/nodes/<master node id>/config -d '{"advertise_addr":"203.0.113.10"}' api -X PUT $RCM/v1/nodes/<replica node id>/config -d '{"advertise_addr":"203.0.113.20"}'api $RCM/v1/nodesmuestra los id de nodo (<host name>-master,<host name>-replica). -
Añada los segundos nodos al documento del clúster: un nodo master en el host replica y su nodo replica en el host master, ambos con
listen_port7061. Lea el documento, añada dos miembros y un enlace, y envíelo de vuelta con su revisión:api $RCM/v1/admin/clusters/<cluster id> > cluster.json # note "revision" # add to "members": # {"member_id":"<host B>-master","agent_id":"<agent id of host B>","role":"master","addresses":["203.0.113.20"],"listen_port":7061} # {"member_id":"<host A>-replica","agent_id":"<agent id of host A>","role":"replica","addresses":["203.0.113.10"],"listen_port":7061} # add to "links": {"from":"<host B>-master","to":"<host A>-replica"} api -X POST $RCM/v1/admin/clusters/<cluster id>/validate --data-binary @cluster.json api -X PUT -H 'If-Match: <revision>' $RCM/v1/admin/clusters/<cluster id> --data-binary @cluster.jsonLos agentes instalan entonces los dos servicios de nodo (30 segundos en la prueba en dos hosts; puede tardar unos minutos).
docker compose exec hqbird systemctl list-units --type=servicemuestra entonces dos servicioshqclusternodeen cada contenedor.Después dé a ambos nodos replica una carpeta de bases de datos en el volumen
db. Sin ella, un switchover de vuelta o un failover se detiene después del punto de no retorno, y el servicio pasa afailed:for n in <host A>-replica <host B>-replica; do api -X POST $RCM/v1/nodes/$n/databases/root/prepare -d '{"root":"/db/replica"}' api -X PUT $RCM/v1/nodes/$n/config -d '{"databases":{"root":"/db/replica"}}' done -
Defina el servicio.
hostes el id de agente del host. La ruta en el segundo host es la ruta del archivo del replica:<database folder of the replica>/<master member id>/<file>:cat > service.json <<'J' {"alias":"shop","router_port":3051,"members":[ {"host":"<agent id of host A>","master_node":"<host A>-master","replica_node":"<host A>-replica","path":"/db/shop.fdb","priority":100}, {"host":"<agent id of host B>","master_node":"<host B>-master","replica_node":"<host B>-replica","path":"/db/replica/<host A>-master/shop.fdb","priority":50}]} J api -X PUT "$RCM/v1/services/shop?check=1" --data-binary @service.json # a check, nothing is stored api -X PUT $RCM/v1/services/shop --data-binary @service.json -
Compruebe y después cambie:
api $RCM/v1/services/shop/master # the master now, the replicas, problems api -X POST $RCM/v1/services/shop/switchover/check -d '{}' api -X POST $RCM/v1/services/shop/switchover -d '{}' # gives "operation_id" api $RCM/v1/operations/<operation id>
Después del switchover, .../services/shop/master da la dirección del
otro host Docker y su puerto de Firebird. Las aplicaciones deben conectarse a
esa dirección. Un switchover necesita un replica que esté IN_SYNC: lo está, después
de la primera escritura en el master (35 segundos en la prueba).
Routers y failover automático. Un router (HAProxy) da a las aplicaciones una dirección que sigue al master. En las imágenes hasta 2027.2.33 el router no arranca (sección 9); la imagen siguiente incluye la corrección. El failover automático necesita un router como testigo. Probado el 2026-11-17 en el laboratorio, en 2027.2.33 con una solución provisional y en una imagen de prueba con la corrección:
-
Un router es un miembro del clúster con el rol
router. El agente instala el paquetehaproxydel repositorio Debian, también en cada contenedor nuevo: el contenedor necesita acceso al repositorio. Publique el puerto del router (3051 en el ejemplo). -
Con un router solo en el host de RCM, RCM movió el master por sí solo 84 segundos después de que se detuviera el contenedor del otro host; la operación tardó 10 segundos. Cuando ese host volvió,
rejoinlo convirtió de nuevo en el replica. -
Con un router en cada host el failover automático no se inicia: más de la mitad de los routers deben informar, y uno de los dos está en el host perdido.
-
RCM se ejecuta en el contenedor master. Cuando se pierde ese host, también se pierde RCM, y nada mueve el master por sí solo.
8. Puertos, cortafuegos, segunda instancia
Publique cada puerto con el mismo número fuera y dentro del contenedor
(3051:3051, no 3051:3050). El agente y el clúster informan del puerto
que ven dentro del contenedor.
| Puerto | Qué | Necesario |
|---|---|---|
HQBIRD_FB_PORT (3050) |
Firebird | siempre |
| 20000 + puerto de Firebird (23050) | HQ Monitor | siempre |
listen_port del nodo (7051) |
nodo de clúster | miembro del clúster |
| puerto de nodo + 10 (7061) | el segundo nodo del host | un servicio con switchover (sección 7.3) |
| 7443, 7444 | RCM, consola de operador de RCM | este agente es el RCM (uno por host) |
| puerto de emparejamiento (7450) | el puerto de emparejamiento del agente | un replica con un rol, hasta que queda enlazado |
El agente se conecta a HQCenter por sí mismo (saliente); no necesita ningún puerto de entrada.
Docker publica puertos al margen de ufw. Probado: con ufw permitiendo solo el puerto 22,
los puertos de Firebird y de HQ Monitor estaban abiertos desde internet. Use un
cortafuegos externo, publique en una dirección de host ("10.0.0.5:23050:23050"),
o añada reglas a la cadena de iptables DOCKER-USER.
Una segunda instancia en un host necesita su propia carpeta, el name: del proyecto,
hostname, HQBIRD_FB_PORT y los puertos. El nombre del proyecto forma los nombres de los
volúmenes (<name>_opt, …): con el mismo nombre, el segundo arranque toma los
volúmenes y el contenedor del primero.
| Instancia 1 | Instancia 2 | |
|---|---|---|
name:, hostname: |
hqbird-fb40-3051 |
hqbird-fb40-3052 |
HQBIRD_FB_PORT |
3051 | 3052 |
ports: |
3051, 23051, 7052 | 3052, 23052, 7053 |
Reglas para N instancias en una IP externa:
- Firebird
3050 + N, HQ Monitor20000 +el puerto de Firebird, nodo de clúster7051 + N(defina el mismolisten_porten HQCenter). Omita 3050, 23050 y 7051 cuando el host ya ejecuta un Firebird o HQbird fuera de Docker. - Solo una instancia por host puede ser el RCM (7443, 7444).
- Con un rol de clúster (sección 7.1), cada instancia de un host necesita su propio
slot:
HQBIRD_PAIRING_PORT=7451yHQBIRD_NODE_PORT=7052para la segunda,7452y7053para la tercera. - Una instancia usa unos 200-250 MB de memoria sin carga. Probado: tres instancias FB 4.0 en 2 vCPU / 4 GB, una con carga.
- Otras líneas de Firebird en el mismo host siguen las mismas reglas con su
propia imagen (
hqbird2027-fb50, …) y nombres (hqbird-fb50-3054).
Añada una instancia (aquí la tercera: 3053, 23053, 7054) a partir del
compose.yaml de la primera. Sustituir 3051 también cambia name:, hostname:,
HQBIRD_FB_PORT y el puerto de HQ Monitor:
sudo ss -ltnp | grep -E ':(3053|23053|7054)\b' # must print nothing
sudo mkdir -p /srv/hqbird-fb40-3053/secrets
cd /srv/hqbird-fb40-3053
sudo sh -c 'openssl rand -hex 12 > secrets/sysdba_password && chmod 600 secrets/sysdba_password'
sudo sed -e 's/3051/3053/g' -e 's/7052/7054/g' /srv/hqbird-fb40-3051/compose.yaml | sudo tee compose.yaml >/dev/null
sudo docker compose config | grep -E '^name:|hostname:|HQBIRD_FB_PORT|published:'
sudo docker compose up -d
sudo docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'9. Problemas conocidos
- Después de conectar el agente a HQCenter con
fbagent --enrolla mano, ejecutefbagent --refresh-apply-launchercomo root, o la autoactualización del agente falla con “no goafts CA is pinned”. - En los scripts, ejecute
docker compose execcon-Ty</dev/null. Sin ellos lee la entrada estándar y se lleva el resto de un script que envíe conssh ... bash -s. - Antes de que el agente esté conectado a HQCenter, su registro muestra las advertencias
goafts mTLS settings are incompleteybootstrap CA not found. Esto es normal. - El contenedor asigna
/opt/hqbirda root después de cada instalación (la autoactualización del agente lo necesita). El agente escribe una advertencia de que no puede actualizar/opt/hqbird/version.json; puede ignorarla. - Imágenes hasta 2027.2.32: carpetas abiertas a la escritura. En estas imágenes
/etc,/usry/usr/libtienen el modo 0777, y algunos archivos del contenedor son escribibles por todas las cuentas. Cualquier cuenta del contenedor puede cambiar lo que arranca root. El agente también rechaza una carpeta así (root trust directory: /usr is writable by group or others): el instalador en modo de actualización falla entonces en un contenedor nuevo, y el contenedor arranca una y otra vez. Use la imagen 2027.2.33 o posterior. No dé acceso de shell en el contenedor de una imagen más antigua a usuarios en los que no confíe. - Imágenes hasta 2027.2.32: un RCM hecho a mano no arranca en un contenedor
nuevo. Cuando crea RCM con
fbagent --cluster-initdentro del contenedor, el agente crea la cuenta del sistema operativohqbirdrcm. Un contenedor nuevo no la tiene (User=hqbirdrcm: invalid userid, el contenedor estáunhealthy). Las imágenes más recientes conservan las cuentas en el volumenstate. Un clúster creado por HQCenter no se ve afectado. - Imágenes hasta 2027.2.33: un router (HAProxy) no arranca. Para un
miembro del clúster con el rol
routerel agente instala el paquetehaproxyy el servicio del router, perohaproxy.servicefalla. El sustituto de systemd de la imagen no pone los valores de$CONFIG,$PIDFILEy$EXTRAOPTSen la línea de comandos y no lee ningún archivo drop-in, y nada crea la carpeta/run/haproxy. La imagen siguiente incluye la corrección. Hasta entonces, dé a las aplicaciones la dirección de.../services/<alias>/mastery no añada un miembrorouter. - Imagen 2027.2.33: un contenedor nuevo no arranca después de añadir un router. El registro tiene
chown: invalid user: 'haproxy', y Docker arranca el contenedor una y otra vez. Para arrancarlo, elimine el archivousr/lib/tmpfiles.d/haproxy.confdel volumenstate. La imagen siguiente incluye la corrección.
10. Construir las imágenes
Para el equipo de la versión. En un host Windows con los archivos de la versión en
dist\releases, inicie sesión en GHCR con un token que tenga write:packages,
y después construya, suba y firme:
Get-Content token.txt | docker login ghcr.io -u <GitHub user> --password-stdin
.\ops\docker\Build-HqbirdImage.ps1 -Line 50 -SetupVersion 2027.2.33 -Registry ghcr.io/ibsurgeon -Tag 2027.2 -Push -CosignKey cosign.keyUn paquete nuevo (el primer envío de una línea) es privado. En los ajustes del paquete de la organización IBSurgeon, ponga su visibilidad en pública.
-ContextOnly prepara solo la carpeta de construcción
(dist\hqbird2027-docker\fbNN-<version>) e imprime el comando docker build
para ejecutarlo en un host Docker Linux.
La construcción se detiene cuando una carpeta o un archivo de la imagen bajo /etc o /usr
es escribible por todas las cuentas (la carpeta de construcción viene de Windows, donde se
pierden los modos). Las pruebas de los scripts del contenedor, los ajustes del clúster
y los archivos compose: go test ./ops/docker/.