Tutoriales de VPS
Harbor en VPS: instalador verificado, Trivy y recuperación
Instale Harbor 2.15.5 con verificación Sigstore y HTTPS. Limite robots CI, pruebe análisis y retención, programe GC y ensaye recuperación de copias externas cifradas.

Cuando un equipo empieza con docker build, el almacenamiento de imágenes se convierte en dependencia operativa. Una cuenta personal Docker Hub complica permisos, límites y traspasos; registry:2 resulta más ligero, pero no aporta los roles, robots, análisis, auditoría, retención y replicación de Harbor.
La guía utiliza Ubuntu 24.04, Compose, HTTPS confiable y Trivy. El ejemplo del 3 de septiembre de 2026 fijaba v2.15.2. La versión oficial consultada el 16 de noviembre es v2.15.5, publicada el 12 de noviembre. Sus instaladores usan bundles Sigstore: los comandos históricos .asc/GPG no verifican ese paquete actual. Use la descarga fijada y la verificación nueva antes de instalar.
- Separar imágenes privadas por equipos/proyectos.
- Dar push limitado a CI y solo pull a producción.
- Analizar CVE conocidos tras subir imágenes.
- Conservar
release-*y caducar builds de desarrollo. - Auditar cargas, borrados y acceso.
- Replicar artefactos a otro registro o ubicación.
| Opción | Recursos | Acceso/auditoría | Análisis | Uso |
|---|---|---|---|---|
| Registry simple | Bajos | Configurar aparte | Sin scanner integrado | Uso individual/cachés |
| Harbor | Medios/altos | Proyectos, roles, robots | Trivy | Equipos y CI propio |
| Registry GitLab | Parte de GitLab | Permisos del proyecto | Según edición | GitLab existente |
| Registry administrado | Sin host que mantener | Controles del proveedor | Según plan | Costes de proveedor/tráfico aceptables |
Un registry/runner de GitLab CE ya instalado puede simplificar. Harbor permite servir distintos sistemas Git/CI.
El mínimo oficial original es 2 núcleos, 4GB RAM y 40GB; la recomendación es 4 núcleos/8GB/160GB. Trivy añade bases de vulnerabilidades, CPU, RAM e I/O.
| Uso | Recursos iniciales | Condición |
|---|---|---|
| Laboratorio/personal | 2 vCPU, 4GB, 80GB SSD | Limitar scans y tags históricos |
| Equipo de 3–10 | 4 vCPU, 8GB, 160GB SSD | Trivy y retención explícita |
| CI frecuente/múltiples proyectos | 8 vCPU, 16GB, disco separado | Espacio para copia/actualización completa |
| Producción distribuida | Base/almacenamiento independientes | Fuera de esta guía de un host |
Las capas se comparten, pero arquitecturas, tags, scanner, PostgreSQL, jobs y copias también crecen. Con 100GB de imágenes, un disco de 160GB deja poco margen para copia local.
Use /data como volumen dedicado, ampliable y respaldable. En un host compartido elija directorio aislado y actualice todas las rutas; no archive otras aplicaciones. Compruebe si snapshots del proveedor incluyen el disco de datos.
Apunte harbor.example.com a la VPS y publique AAAA solo con IPv6 operativo.
| Puerto | Función | Acceso |
|---|---|---|
22/TCP | Administración | Claves y orígenes restringidos |
80/TCP | HTTP-01/redirección | Público para este método |
443/TCP | Portal/API/push/pull | Clientes autorizados |
Mantenga PostgreSQL, Redis, Registry y Jobservice internos. Diagnostique timeouts con DNS, escucha y cortafuegos.
Instale Engine y Compose v2 desde el repositorio oficial Ubuntu. Use docker compose y distinga el ejecutable antiguo docker-compose:
sudo apt update
sudo apt full-upgrade -y
sudo apt install -y ca-certificates curl gnupg jq certbot dnsutils
docker version
docker compose version
openssl version
Los requisitos originales piden Engine superior a 20.10 y Compose superior a 2.3; revise también requisitos actuales. Evalúe actualizaciones/reinicios y la lista Compose de producción.
Compare DNS y dirección pública:
dig +short harbor.example.com A
curl -4 ifconfig.me
Con NAT o varias IP, confirme la dirección de entrada; la de salida no siempre la identifica. Certbot standalone necesita 80 libre:
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo certbot certonly --standalone \
-d harbor.example.com \
--agree-tos \
-m [email protected] \
--no-eff-email
Cambie dominio/email. Las rutas son:
/etc/letsencrypt/live/harbor.example.com/fullchain.pem
/etc/letsencrypt/live/harbor.example.com/privkey.pem
Use CA confiable entre redes. insecure-registries no arregla una cadena TLS pública incorrecta.
Estos comandos conservan el ejemplo v2.15.2 y su petición .asc. Para v2.15.5 consultado, continúe con Sigstore:
cd /tmp
HARBOR_VERSION=v2.15.2
curl -fLO \
"https://github.com/goharbor/harbor/releases/download/${HARBOR_VERSION}/harbor-online-installer-${HARBOR_VERSION}.tgz"
curl -fLO \
"https://github.com/goharbor/harbor/releases/download/${HARBOR_VERSION}/harbor-online-installer-${HARBOR_VERSION}.tgz.asc"
Solo sirve para un paquete acompañado realmente de su firma GPG auténtica y una huella completa de clave comprobada independientemente:
gpg --keyserver hkps://keyserver.ubuntu.com \
--receive-keys 644FF454C0B4115C
gpg --verify \
"harbor-online-installer-${HARBOR_VERSION}.tgz.asc" \
"harbor-online-installer-${HARBOR_VERSION}.tgz"
Si falta .asc, no omita verificación ni intente validar un bundle Sigstore con este identificador corto antiguo.
Instale cosign compatible siguiendo Sigstore oficial. Conserve el paquete en un directorio persistente:
sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/harbor-installers/v2.15.5
cd /opt/harbor-installers/v2.15.5
HARBOR_VERSION=v2.15.5
curl -fLO "https://github.com/goharbor/harbor/releases/download/${HARBOR_VERSION}/harbor-online-installer-${HARBOR_VERSION}.tgz"
curl -fLO "https://github.com/goharbor/harbor/releases/download/${HARBOR_VERSION}/harbor-online-installer-${HARBOR_VERSION}.tgz.sigstore.json"
printf '%s\n' '6b3aa89c868d975549be7dad7238bf1f674fc248711a0913b42d65832f589b7d harbor-online-installer-v2.15.5.tgz' | sha256sum -c -
cosign verify-blob \
--bundle "harbor-online-installer-${HARBOR_VERSION}.tgz.sigstore.json" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
--certificate-identity "https://github.com/goharbor/harbor/.github/workflows/publish_release.yml@refs/tags/${HARBOR_VERSION}" \
"harbor-online-installer-${HARBOR_VERSION}.tgz"
Digest e identidad proceden de los assets/bundle consultados. Para versiones posteriores obtenga digest, bundle e identidad esperados propios, sin reutilizar hash ni relajar comprobaciones. Online descarga componentes al instalar; offline los incluye.
Confirme que /opt/harbor no contiene otra instalación. Tras validar el paquete:
sudo tar -xzf "harbor-online-installer-${HARBOR_VERSION}.tgz" -C /opt
sudo chown -R root:root /opt/harbor
cd /opt/harbor
ls -la
Conserve descarga versionada y configuración para recuperación/actualización.
Copie certificados a rutas estables:
sudo install -d -m 700 /data/cert
sudo cp \
/etc/letsencrypt/live/harbor.example.com/fullchain.pem \
/data/cert/harbor.crt
sudo cp \
/etc/letsencrypt/live/harbor.example.com/privkey.pem \
/data/cert/harbor.key
sudo chmod 600 /data/cert/harbor.crt /data/cert/harbor.key
Genere secretos distintos para administrador y base:
openssl rand -base64 32
openssl rand -base64 32
Uno es para admin; otro para PostgreSQL. Sustituya Harbor12345 y guárdelos restringidos.
Use la plantilla de la versión elegida:
cd /opt/harbor
sudo cp harbor.yml.tmpl harbor.yml
sudo chmod 600 harbor.yml
sudoedit harbor.yml
Cambie valores necesarios en harbor.yml. Los dos marcadores de contraseña del ejemplo representan el primer/segundo secreto y deben sustituirse completamente:
hostname: harbor.example.com
http:
port: 80
https:
port: 443
certificate: /data/cert/harbor.crt
private_key: /data/cert/harbor.key
harbor_admin_password: 替换为第一段随机密码
database:
password: 替换为第二段随机密码
data_volume: /data
trivy:
ignore_unfixed: false
skip_update: false
offline_scan: false
insecure: false
log:
level: info
local:
rotate_count: 10
rotate_size: 200M
location: /var/log/harbor
hostnamees dominio sinhttps://.certificate/private_keyson rutas absolutas del host.data_volumeguarda datos de registry, base, Redis y scanner.skip_update: falsepermite actualizar vulnerabilidades.- Cite contraseñas especiales según YAML/plantilla actual.
Busque valores predeterminados:
sudo grep -nE 'Harbor12345|root123' /opt/harbor/harbor.yml
No debe haber coincidencias. harbor.yml contiene credenciales y no pertenece a repositorios públicos.
Compruebe puertos 80/443 libres:
sudo ss -lntp | grep -E ':(80|443)\b' || true
Otro servidor web requiere IP/host aparte o proxy compartido planificado con external_url correcto. Instale explícitamente scanner:
cd /opt/harbor
sudo ./install.sh --with-trivy
--with-trivy activa Trivy; install.sh solo no lo hace. Revise servicios:
cd /opt/harbor
sudo docker compose ps
curl -fsS https://harbor.example.com/api/v2.0/health | jq
curl -sSI https://harbor.example.com/v2/ | head
Salud debe indicar healthy. /v2/ sin login responde normalmente 401 Unauthorized: prueba desafío de autenticación, no acceso autenticado. Revise fallos:
cd /opt/harbor
sudo docker compose logs --tail=200
sudo find /var/log/harbor -maxdepth 1 -type f -printf '%f\n' | sort
Abra https://harbor.example.com con admin y secreto inicial de harbor.yml:
- Guarde administrador en el gestor del equipo.
- Desactive registro abierto salvo decisión explícita.
- Limite desarrolladores al proyecto necesario.
- Cree proyectos privados sin concentrar todo en
library. - Configure cuotas.
- Compruebe Trivy y antigüedad de su base.
- Configure retención de auditoría y alertas.
Proyectos privados requieren miembros/robots autorizados; públicos permiten pull anónimo y no protegen imágenes internas.
Cree antes el proyecto privado demo. Autentíquese:
docker login harbor.example.com
Pruebe recorrido completo:
docker pull alpine:3.22
docker tag alpine:3.22 harbor.example.com/demo/alpine:3.22
docker push harbor.example.com/demo/alpine:3.22
docker pull harbor.example.com/demo/alpine:3.22
Incluya proyecto en la ruta:
harbor.example.com/<project>/<repository>:<tag>
docker login puede guardar credenciales en ~/.docker/config.json. Use credential helper y permisos apropiados en equipos compartidos.
En Configuration del proyecto:
- Active escaneo automático al hacer push.
- Decida bloqueo de pulls vulnerables.
- Pruebe umbral como
Critical. - Use excepciones temporales para CVE revisados.
Harbor bloquea solicitudes al registry; no detiene imágenes ejecutadas ni sustituye admisión del clúster. Pruebe Critical antes de producción para no impedir pulls tras reiniciar. Reanalice periódicamente con nuevas bases y supervise actualizaciones. Limite concurrencia en 4GB.
Créelo en:
Projects → demo → Robot Accounts → New Robot Account
Conceda a ci-push solo permisos necesarios de demo:
- Repository Pull.
- Repository Push.
- Artifact Read.
- Scan únicamente si CI lo activa explícitamente.
Configure caducidad, por ejemplo 90 días según política. Guarde nombre generado y secreto mostrado una vez; no adivine prefijos ni conceda acceso global innecesario.
printf '%s' "$HARBOR_ROBOT_SECRET" | \
docker login harbor.example.com \
--username "$HARBOR_ROBOT_USER" \
--password-stdin
docker logout harbor.example.com
Guarde robot como credencial Username with password y use Jenkinsfile:
pipeline {
agent { label 'linux' }
environment {
REGISTRY = 'harbor.example.com'
IMAGE = 'harbor.example.com/demo/webapp'
}
stages {
stage('Build') {
steps {
sh 'docker build -t "$IMAGE:$BUILD_NUMBER" .'
}
}
stage('Push') {
steps {
withCredentials([usernamePassword(
credentialsId: 'harbor-demo-robot',
usernameVariable: 'HARBOR_USER',
passwordVariable: 'HARBOR_SECRET'
)]) {
sh '''
set +x
printf '%s' "$HARBOR_SECRET" | \
docker login "$REGISTRY" \
--username "$HARBOR_USER" \
--password-stdin
docker push "$IMAGE:$BUILD_NUMBER"
docker logout "$REGISTRY"
'''
}
}
}
}
}
Construya en agent aislado; consulte Jenkins. Haga logout/limpieza del directorio temporal de credenciales en un post siempre ejecutado, incluso con push fallido. Separe:
ci-pushpara construir/subir.staging-pullpara pull de pruebas.prod-pullpara pull de producción.- Secretos, expiraciones y responsables distintos.
Producción no debe reutilizar ci-push.
Diseñe reglas y ejecute dry-run:
- Conserve releases
release-*necesarios. - Guarde, por ejemplo, 20 builds
main-*recientes. - Guarde cinco builds por rama de desarrollo.
- No deje
latestmutable como único rollback.
Registre digest desplegado y proteja artefactos activos:
docker inspect \
--format='{{index .RepoDigests 0}}' \
harbor.example.com/demo/webapp:42
Retención selecciona artefactos; no libera todas las capas inmediatamente ni reemplaza copias/replicación.
En Administration → Clean Up → Garbage Collection:
- Ejecute DRY RUN.
- Revise blobs/espacio candidatos.
- Compruebe push, retención y replicación.
- Ejecute GC o prográmelo.
- Revise historial y logs.
La ventana histórica documentada protege capas recientes dos horas; confirme comportamiento de su versión. Actúe antes de agotar disco y alerte al 70%/85%:
df -h
sudo du -xhd1 /data | sort -h
sudo du -xhd2 /data/registry | sort -h | tail -30
cd /opt/harbor && sudo docker compose ps
data_volume es /data; configuración reside en /opt/harbor. Solo /opt/harbor/docker-compose.yml no contiene blobs ni base. Active Read Only, espere jobs activos y detenga:
cd /opt/harbor
sudo docker compose ps
sudo docker compose down
Archive datos detenidos:
sudo install -d -m 700 /backup/harbor
sudo tar --xattrs --acls \
-C / \
-czf "/backup/harbor/harbor-$(date +%F-%H%M%S).tar.gz" \
data \
opt/harbor
sudo sha256sum /backup/harbor/harbor-*.tar.gz
Un /data grande necesita espacio adicional. Snapshot coherente o restic cifrado de /data//opt/harbor hacia almacenamiento independiente puede encajar mejor; vea copias/recuperación. Reinicie y quite Read Only después de comprobar éxito:
cd /opt/harbor
sudo docker compose up -d
curl -fsS https://harbor.example.com/api/v2.0/health | jq
Conserve:
/datacompleto./opt/harbor/harbor.yml, instalador y descarga versionada.- Compose/configuración generados.
- TLS o procedimiento probado de reemisión.
- Versión y parámetros
--with-trivy. - Reemisión de robots y actualización CI.
- Lista read-only/recuperación.
Cifre archivos fuera del dominio de fallo del registry.
Use VPS aislada con frecuencia acorde al objetivo de recuperación, al menos trimestral en el ejemplo:
- Iguale versiones Docker/Harbor copiadas.
- Detenga destino vacío.
- Restaure
/data//opt/harbor, propietarios, ACL y atributos. - Compruebe dominio/rutas/secretos en
harbor.yml. - Ejecute
sudo ./prepare --with-trivy. - Ejecute
sudo docker compose up -d. - Revise Portal,
/api/v2.0/health//v2/. - Autentíquese, haga pull privado y compruebe digest.
- Revise proyectos, robots, scans, políticas y auditoría.
- Registre tiempo y carencias.
Recupere versión original antes de actualizar mayor.
Harbor ocupa 80/443; standalone requiere liberar 80 durante mantenimiento:
cd /opt/harbor
sudo docker compose down
sudo certbot renew --standalone
sudo cp \
/etc/letsencrypt/live/harbor.example.com/fullchain.pem \
/data/cert/harbor.crt
sudo cp \
/etc/letsencrypt/live/harbor.example.com/privkey.pem \
/data/cert/harbor.key
sudo chmod 600 /data/cert/harbor.crt /data/cert/harbor.key
sudo ./prepare --with-trivy
sudo docker compose up -d
Compruebe fechas:
echo | openssl s_client \
-connect harbor.example.com:443 \
-servername harbor.example.com 2>/dev/null | \
openssl x509 -noout -issuer -dates
Automatice reinicio de Harbor aunque falle renovación y pruebe el procedimiento. DNS-01 o certificados gestionados por proxy independiente pueden evitar parada con configuración real del proveedor DNS.
Cambian harbor.yml y schema:
- Lea notas, compatibilidad y migración.
- Compruebe saltos admitidos.
- Copie
/data, base e instalación. - Ensaye migración/rollback en copia.
- Registre scanner, almacenamiento, identidad y replicación.
- Programe mantenimiento.
El prepare destino goharbor/prepare:<tag> migra harbor.yml; Core migra la base según procedimiento después de copiar /data/database. Cambiar tag no garantiza downgrade; conserve base y /data anteriores.
Para docker login/x509: certificate signed by unknown authority:
echo | openssl s_client \
-connect harbor.example.com:443 \
-servername harbor.example.com \
-showcerts
Revise cert.pem/fullchain.pem, CA cliente y DNS; no oculte con insecure-registries.
Con 413 Request Entity Too Large, revise CDN/WAF/proxy de 443, límites y timeouts. Los cambios generados desaparecen tras prepare.
df -h
sudo du -sh /data/registry /data/database /data/trivy-adapter 2>/dev/null
cd /opt/harbor
sudo docker compose ps
sudo docker compose logs --tail=200 proxy core registry jobservice
Revise disco, inodos, rutas, pérdidas, timeout y escritura en /data/registry.
cd /opt/harbor
sudo docker compose logs --tail=200 trivy-adapter
date -Is
curl -I https://github.com
Revise DNS saliente, reloj, proxy y límites de las fuentes. Use proceso offline admitido; skip_update: true con datos caducados no demuestra seguridad.
Revise retención/manifests compartidos y GC dry-run. Nunca borre manualmente /data/registry/docker/registry/v2/blobs.
Revise caducidad, desactivación, rotación y nombre exacto. Cambiar robot no actualiza secretos Jenkins/GitHub automáticamente.
cd /opt/harbor
sudo docker compose ps
sudo docker compose logs --tail=200
sudo journalctl -u docker --since '30 minutes ago' --no-pager
free -h
df -h
Confirme OOM/exit antes de reducir scans o ampliar RAM.
prepare/prepare regeneran desde harbor.yml. Guarde ajustes admitidos en harbor.yml; mantenga proxy adicional por separado.
- Fije parche de instalador revisado.
- Verifique firma real y paquete.
- Cumpla CPU/RAM/disco con margen para copia.
- Use
/dataampliable y respaldable. - Valide A/AAAA.
- Configure HTTPS confiable.
- Quite defaults en
harbor.yml, modo600. - Mantenga internos los puertos auxiliares.
- Instale
--with-trivyy verifique scanner. - Use proyectos privados/cuotas.
- Pruebe escaneo tras push.
- Pruebe umbrales en proyecto seguro.
- CI usa robots de proyecto, no
admin. - Separe push y pull producción.
- Vigile rotación/caducidad.
- Dry-run de retención.
- Programe/revise GC.
- Active alertas 70%/85%.
- Cifre copias externas
/data//opt/harbor. - Ensaye pull privado/digest recuperados.
- Pruebe renovación TLS.
- Actualice con copia/migración admitida.
2 núcleos/4GB/40GB es el mínimo histórico; 4 núcleos/8GB/160GB y disco independiente suele servir mejor a un equipo pequeño, medido por scans y crecimiento.
Registry almacena artefactos; Harbor añade RBAC, robots, scanner, auditoría, replicación, retención y GC con mayor mantenimiento.
Úselo entre redes. insecure-registries debilita confianza; HTTP corresponde a experimentos aislados deliberados.
Capas compartidas siguen referenciadas; GC elimina blobs elegibles tras revisar retención y despliegues.
Robot de proyecto con expiración, no admin; robot pull-only separado para producción.
/data/registry omite metadatos/permisos. Restaure /data//opt/harbor coherentes con TLS/procedimientos. Compruebe recuperación de /data mediante build, push, scan, pull y rollback en demo.