Tutorial autohospedado de Buzz: configurar un espacio de trabajo de agente privado para Codex, Claude Code y el equipo

Buzz es el espacio de trabajo colaborativo de código abierto de Block. Reúne a las personas, los agentes de IA, los repositorios de códigos, los parches, las aprobaciones, los flujos de trabajo, los canales y la colaboración de voz en el mismo sistema, y utiliza los eventos de firma de Nostr para registrar las operaciones. No es una simple “interfaz de chat multijugador”. En Buzz, los agentes tienen sus propias identidades y membresías de canal, y pueden buscar en el historial, abrir repositorios, enviar parches, participar en revisiones y ejecutar flujos de trabajo. El objetivo del autohospedaje es que el equipo controla la retransmisión, el almacenamiento de datos, los nombres de dominio y los registros de auditoría. Este artículo se centra en la implementación remota de VPS. Buzz todavía se encuentra en un período de rápido desarrollo y la estructura del repositorio, las variables de entorno y los archivos de redacción pueden cambiar. Por lo tanto, este artículo separa los juicios de implementación que se pueden reutilizar de manera estable de los comandos oficiales: las variables específicas siempre están sujetas a la versión de .env.example y los documentos de implementación que esté utilizando.

Primero se debe comprender el flujo de datos de Buzz y luego implementarlo

El navegador o el cliente de escritorio no guardará directamente todos los estados localmente. Una instancia autohospedada típica contiene:

Cliente web, de escritorio o móvil Buzz;
Nostr Relay para manejar eventos firmados;
PostgreSQL para guardar el estado estructurado;
Redis para proporcionar capacidades de almacenamiento en caché y colas;
Para guardar archivos adjuntos en almacenamiento de objetos compatible con S3;
Caddy u otro proxy inverso que proporcione HTTPS a la red pública. En la estructura oficial de retransmisión única actual, una URL de retransmisión corresponde a una comunidad. Incluso si un operador aloja varias comunidades en una infraestructura compartida, las URL visitadas por los usuarios siguen siendo límites del espacio de trabajo. Cada mensaje, reacción, paso del flujo de trabajo, aprobación de revisión y evento de Git es un evento firmado. Si realiza una copia de seguridad de la base de datos sin hacer una copia de seguridad del almacenamiento de objetos, perderá los archivos adjuntos; Si realiza una copia de seguridad solo de los archivos adjuntos pero ignora la identidad y la base de datos, no podrá restaurar completamente el espacio de trabajo.

Seleccione la máquina y el nombre de dominio

El entorno de prueba puede comenzar con 4 núcleos, 8 GB de memoria y 80 GB de SSD. Los requisitos reales dependen de la cantidad de usuarios simultáneos, la cantidad de agentes, el tamaño del repositorio, los archivos adjuntos y el uso de voz. El entorno de producción debe preparar al menos:

Un VPS Linux compatible;
Un nombre de subdominio independiente, como buzz.example.com;
Hay 80 y 443 puertos disponibles;
Docker Engine y complemento Compose;
Almacenamiento que se puede utilizar para instantáneas o copias de seguridad fuera del sitio;
Servicios externos realmente requeridos por proyectos como SMTP y almacenamiento de objetos. No exponga directamente los puertos de administración de Relay, PostgreSQL, Redis y MinIO a la red pública. La entrada de la red pública solo debe tener HTTPS, y SSH debe restringir la dirección de origen o el acceso a través de VPN. DNS primero crea un registro A/AAAA que apunta al VPS. Si utiliza el proxy de Cloudflare, puede configurarlo temporalmente en “Solo DNS” al emitir certificados y depurar WebSocket por primera vez, y luego habilitar el proxy después de confirmar que el servicio es normal.

Instalación de Docker

A continuación se toma Ubuntu/Debian como ejemplo. El entorno de producción debería dar prioridad al uso del repositorio oficial de Docker en lugar de depender de paquetes obsoletos de la distribución durante mucho tiempo. Primero confirme el sistema:

1
2


uname -a
cat /etc/os-release

Verifique después de la instalación:

1
2
3


docker version
docker compose version
sudo systemctl enable --now docker

Permitir que usuarios comunes se unan al grupo docker equivale a otorgar permisos cercanos a la raíz. Si el servidor lo comparten varias personas, no se una a este grupo solo para guardar sudo. Mire el disco y la memoria:

1
2


df -h
free -h

Si la partición raíz tiene solo una docena de GB, incluso si el servicio puede iniciarse, el espejo, la base de datos WAL y los archivos adjuntos se quedarán rápidamente sin espacio.

Obtén una versión fija de Buzz

Crea un directorio separado:

1
2
3


sudo mkdir -p /opt/buzz
sudo chown "$USER":"$USER" /opt/buzz
cd /opt/buzz

Clona el repositorio oficial:

1

git clone https://github.com/block/buzz.git .

No permitas que el entorno de producción siga a main para siempre. Ver lanzamiento o confirmación, fije la versión probada:

1
2


git tag --sort=-version:refname | head
git log -1 --oneline

Si no hay una etiqueta estable adecuada en ese momento, al menos registre el SHA de confirmación de implementación:

1

git rev-parse HEAD

Para comparar con precisión los cambios de configuración y migración de la base de datos antes de actualizar.

Leer Compose y la configuración de ejemplo

El repositorio de Buzz proporciona docker-compose.yml, Dockerfile y .env.example. No lo inicies directamente todavía:

1
2
3


sed -n '1,240p' .env.example
docker compose config --services
docker compose config > /tmp/buzz-compose-resolved.yml

Confirmación de clave:

Qué servicio escucha el puerto de la red pública;
Si la base de datos, Redis y el almacenamiento de objetos están solo en la red interna;
Está el volumen montado en el host o volumen con nombre Docker;
Si la contraseña predeterminada aún existe;
Si la URL de retransmisión es coherente con la URL de acceso externo;
Si Caddy/TLS está habilitada la configuración. Copiar archivos de entorno:

1
2


cp .env.example .env
chmod 600 .env

No envíe .env a Git y no publique el contenido completo en la orden de trabajo.

Genere credenciales en lugar de los siguientes valores de ejemplo

Puede usar OpenSSL para generar valores aleatorios:

1
2


openssl rand -hex 32
openssl rand -base64 48

La base de datos, el almacenamiento de objetos, la firma de la aplicación y las credenciales de inicio del administrador deben generarse por separado y no pueden compartir una contraseña. Registro en el administrador de contraseñas:

Propósito;
Fecha de creación;
Entorno;
Rotación de responsables;
Método de recuperación. Compose puede analizarse de manera diferente a lo esperado si la variable contiene $, #, espacios o comillas. Ejecutar después de la modificación:

1

docker compose config >/dev/null

Este comando puede encontrar algunas variables faltantes y errores YAML, pero no probará que todas las configuraciones de la aplicación sean válidas.

Primer inicio y juicio de registro

Extraiga o cree la imagen:

1
2


docker compose pull
docker compose build --pull

Las versiones del repositorio son diferentes, es posible que solo necesite una de ellas. Tome el campo image o build en Redactar. Inicio en segundo plano:

1

docker compose up -d

Ver estado:

1
2


docker compose ps
docker compose logs --tail=200

No vea simplemente que el contenedor es Up y finalícelo. Continúe observando las migraciones de bases de datos, el inicio de la retransmisión, las conexiones de almacenamiento de objetos y las comprobaciones del estado de los servicios web. Seguimiento de un único servicio en tiempo real:

1

docker compose logs -f --tail=100 <service-name>

El nombre del servicio se obtiene de docker compose config --services, no adivine basándose en el artículo.

Nombre de dominio, HTTPS y WebSocket

Si usa Caddy que viene con el repositorio, asegúrese de que el nombre de dominio externo sea exactamente el mismo que la URL en .env, que el DNS haya apuntado al servidor y que 80/443 no esté ocupado por otros programas. Verifique el puerto:

1

sudo ss -lntp | grep -E ':80|:443'

Si ya tiene Nginx, puede dejar que Buzz solo escuche el puerto alto de 127.0.0.1 y luego lo reenvíe mediante Nginx. La retransmisión y la colaboración en tiempo real dependen de conexiones largas y el proxy inverso debe manejar la actualización de WebSocket correctamente. El fragmento genérico de Nginx es el siguiente, el puerto ascendente real debe confirmarse desde Compose:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 300s;
}

Verificar el certificado y la respuesta:

1
2


curl -I https://buzz.example.com/
openssl s_client -connect buzz.example.com:443 -servername buzz.example.com </dev/null

El navegador puede abrir la página de inicio pero el canal sigue desconectándose; normalmente debe verificar WebSocket, la URL externa, el tiempo de espera del proxy y la configuración de Cloudflare.

Creación de comunidades y administradores

El primer proceso de arranque puede cambiar de una versión a otra. Antes de crear un administrador, asegúrese de que el sitio no permita el registro anónimo en la red pública. Recomendaciones:

Usar temporalmente un firewall para restringir las fuentes de acceso;
Completar la creación del administrador;
Cerrar registros abiertos innecesarios;
Establecer cuentas de prueba de miembros ordinarios;
Abrir el acceso al equipo nuevamente. La cuenta de administrador sólo se utiliza para la gestión. No permita que los agentes diarios compartan la identidad del administrador. Cada Agente debe tener claves independientes, membresías de canales y pistas de auditoría.

Acceso a Codex, Claude Code y otros agentes

El repositorio de Buzz contiene habilidades y herramientas orientadas a agentes y también proporciona componentes relacionados con el arnés ACP. El método de instalación específico debe realizarse de acuerdo con la documentación de la versión actual. Al acceder, primero establezca un canal de prueba con bajos privilegios y autorice solo un repositorio de demostración sin información confidencial. Secuencia de verificación:

¿Puede el Agente leer el canal especificado?
Si no puede leer canales privados no unidos;
Se puede abrir el repositorio especificado;
Si se requiere confirmación manual para enviar el parche;
Si la ejecución del flujo de trabajo registra la identidad del Agente;
Si la clave del Agente deja de ser válida inmediatamente después de ser revocada. No entregue el Docker Socket del host, la clave privada SSH del servidor o el token de GitHub a nivel de organización directamente al Agente. El aislamiento de identidad de Buzz no contrarresta automáticamente los permisos excesivos de las credenciales subyacentes.

Pruebas mínimas de repositorio, parches y aprobación

Prepare un repositorio de prueba sin datos confidenciales, cree un problema simple y permita que el Agente solo genere parches sin fusionarlos directamente. Inspección manual:

Si la solicitud original se puede encontrar en el canal;
Si el parche corresponde al envío correcto;
Si los resultados de CI están asociados con el mismo registro;
Si el El aprobador de la revisión es una identidad independiente;
Si se puede rastrear el motivo de la fusión final. Buzz tiene la ventaja de colocar estos eventos en un registro con capacidad de búsqueda. Esta ventaja desaparece si los equipos aún evitan las aprobaciones a través de cuentas compartidas y scripts externos.

La copia de seguridad no puede copiar solo un directorio

Primero confirme todos los volúmenes de Compose:

1
2


docker compose config --volumes
docker volume ls

La base de datos utiliza una copia de seguridad lógica:

1

docker compose exec -T postgres pg_dump -U <db-user> <db-name> > buzz.sql

El nombre del servicio, el nombre de usuario y el nombre de la base de datos deben reemplazarse de acuerdo con la configuración real. Haga una copia de seguridad del depósito de almacenamiento de objetos y guarde una copia cifrada de .env. Una copia de seguridad recuperable debe incluir al menos:

datos PostgreSQL;
archivos de almacenamiento de objetos y metadatos;
volúmenes persistentes de aplicación o retransmisión;
.env actual y configuración de proxy inverso;
Confirmación de implementación SHA;
Instrucciones de operación de restauración. Realice un simulacro de recuperación en la máquina aislada al menos una vez al mes. Las copias de seguridad sin verificación de recuperación son simplemente “archivos posiblemente útiles”.

Registros, métricas y capacidad

Utilice Docker para ver los recursos primero:

1
2


docker stats
docker system df

El monitoreo cubre al menos:

Disponibilidad de HTTPS;
Error de conexión larga de retransmisión;
PostgreSQL Número de conexiones y discos;
Memoria y eliminación de Redis;
Capacidad de almacenamiento de objetos;
Número de reinicios de contenedores;
Hora de la última copia de seguridad exitosa. El registro puede contener el nombre del canal, la dirección del repositorio o la identificación del usuario. Establezca el control de acceso y el período de retención durante la recopilación centralizada y no exponga los registros de depuración a servicios de pegado de terceros.

Actualización y reversión

Registre el estado actual antes de actualizar:

1
2
3


git rev-parse HEAD
docker compose images
docker compose ps

Complete la copia de seguridad de la base de datos y el almacenamiento de objetos, y luego lea el registro de cambios desde la versión actual a la versión de destino. Después de actualizar la versión corregida:

1
2
3
4


git fetch --tags
git checkout <tested-tag-or-commit>
docker compose pull
docker compose up -d

Si la nueva versión realiza una migración irreversible de la base de datos, es posible que no se pueda revertir el simple hecho de volver al espejo anterior. La verificación debe restaurarse en un entorno independiente mediante una copia de seguridad previa a la actualización.

Fallos comunes

El contenedor se reinicia repetidamente

Ejecute docker compose logs <service> y busque primero el primer error. Los motivos más comunes son la falta de variables, la base de datos no lista, los permisos o el error en la migración.

No se puede ver el canal después de iniciar sesión

Compruebe si la URL actual apunta a la comunidad correcta, si el usuario se ha unido al canal y si la clave ha cambiado. No elimine la base de datos y reconstrúyala primero.

Error en la carga del archivo adjunto

Verifique el punto final de almacenamiento de objetos, el depósito, la clave de acceso, el tamaño de carga del proxy inverso y la capacidad del disco.

La página está bien, pero los mensajes en tiempo real están desconectados

Verifique la actualización de WebSocket, el proxy de Cloudflare, el tiempo de espera de inactividad y la URL externa de retransmisión.

El agente puede ver los repositorios a los que no debería acceder

Revocar inmediatamente las credenciales del agente, verificar la membresía del canal Buzz y el token Git subyacente. Compartir tokens a nivel de organización suele ser la fuente de expansión de permisos.

El disco sigue creciendo

Compruebe la base de datos, el almacenamiento de objetos, los registros del contenedor y las imágenes sin limpiar individualmente:

1
2


sudo du -xh /var/lib/docker | sort -h | tail
docker system df

No elimine de forma recursiva el directorio de datos de Docker sin confirmar la ruta.

Lista de verificación antes de conectarse

El nombre de dominio y HTTPS son normales y el certificado se puede renovar automáticamente;
Solo los puertos necesarios están expuestos a la red pública;
Se han reemplazado las contraseñas predeterminadas y los secretos de ejemplo;
Administrador y agente diario Sin identidad compartida;
El aislamiento del canal privado se prueba de forma cruzada con dos cuentas;
El agente solo puede acceder al repositorio de prueba y a las herramientas requeridas;
Se realiza una copia de seguridad de la base de datos, el almacenamiento de objetos y la configuración;
La recuperación la perforación fue exitosa;
El registro no tiene clave de salida;
Se han registrado la versión y el método de reversión de actualización. Buzz es adecuado para equipos que desean administrar agentes como miembros reales del equipo y al mismo tiempo conservar los límites de identidad y los registros de auditoría. Primero utilice una pequeña comunidad para verificar los permisos, la recuperación de datos y los métodos de colaboración, y luego decida si migrar el repositorio de producción. Esto es más seguro que conectar a todos los agentes a la vez.