Tutoriais de VPS
Harbor na VPS: instalador verificado, Trivy e recuperação
Instale Harbor 2.15.5 com Sigstore e HTTPS. Limite robots CI, teste análise e retenção, agende GC e ensaie recuperação de backups externos criptografados.

Depois que a equipe começa a usar docker build, armazenar imagens vira uma dependência operacional. Uma conta pessoal no Docker Hub dificulta permissões, limites e transferência de responsabilidade; registry:2 é mais leve, mas não oferece os papéis, robots, análise, auditoria, retenção e replicação do Harbor.
O guia usa Ubuntu 24.04, Compose, HTTPS confiável e Trivy. O exemplo de 3 de setembro de 2026 fixava v2.15.2. A versão oficial consultada em 16 de novembro é v2.15.5, lançada em 12 de novembro. Seus instaladores usam bundles Sigstore: os comandos históricos .asc/GPG não verificam esse pacote atual. Use a descarga e a verificação atualizadas antes de instalar.
- Separar imagens privadas por equipes/projetos.
- Dar push restrito ao CI e somente pull à produção.
- Analisar CVEs conhecidos após enviar imagens.
- Preservar
release-*e expirar builds de desenvolvimento. - Auditar envios, exclusões e acesso.
- Replicar artefatos para outro registro ou local.
| Opção | Recursos | Acesso/auditoria | Análise | Uso |
|---|---|---|---|---|
| Registry simples | Baixos | Configurar separadamente | Sem scanner integrado | Uso individual/cache |
| Harbor | Médios/altos | Projetos, papéis, robots | Trivy | Equipes e CI próprio |
| Registry GitLab | Parte da operação GitLab | Permissões do projeto | Conforme edição | GitLab existente |
| Registry gerenciado | Sem host a manter | Controles do provedor | Conforme plano | Custos de provedor/tráfego aceitáveis |
Um registry/runner GitLab CE existente pode simplificar. Harbor permite atender diferentes plataformas Git/CI.
O mínimo oficial original é 2 núcleos, 4GB RAM e 40GB; a recomendação é 4 núcleos/8GB/160GB. Trivy acrescenta bancos de vulnerabilidades, CPU, RAM e I/O.
| Uso | Recursos iniciais | Condição |
|---|---|---|
| Laboratório/pessoal | 2 vCPU, 4GB, SSD de 80GB | Limitar scans e tags antigas |
| Equipe de 3–10 | 4 vCPU, 8GB, SSD de 160GB | Trivy e retenção explícita |
| CI frequente/muitos projetos | 8 vCPU, 16GB, disco separado | Espaço para backup/atualização completos |
| Produção distribuída | Banco/armazenamento independentes | Fora deste guia de um host |
Camadas são compartilhadas, mas arquiteturas, tags, scanner, PostgreSQL, jobs e backups crescem. Com 100GB de imagens, um disco de 160GB deixa pouca folga para backup local.
Use /data como volume dedicado, expansível e protegido por snapshots. Em host compartilhado, escolha diretório isolado e ajuste todas as rotas; não arquive outros aplicativos. Confira se snapshots do provedor incluem o disco de dados.
Aponte harbor.example.com à VPS e publique AAAA somente com IPv6 funcionando.
| Porta | Função | Acesso |
|---|---|---|
22/TCP | Administração | Chaves e origens restritas |
80/TCP | HTTP-01/redirecionamento | Pública nesse método |
443/TCP | Portal/API/push/pull | Clientes autorizados |
Mantenha PostgreSQL, Redis, Registry e Jobservice internos. Diagnostique timeouts por DNS, escuta e firewall.
Instale Engine e Compose v2 pelo repositório oficial Ubuntu. Use docker compose e diferencie o executável antigo 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
Os requisitos originais pedem Engine acima de 20.10 e Compose acima de 2.3; confira também a versão atual. Avalie atualização/reinicialização e a lista Compose de produção.
Compare DNS e endereço público:
dig +short harbor.example.com A
curl -4 ifconfig.me
Com NAT ou múltiplas IPs, confirme o endereço de entrada; o de saída nem sempre o identifica. Certbot standalone exige 80 livre:
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
Troque domínio/email. As rotas são:
/etc/letsencrypt/live/harbor.example.com/fullchain.pem
/etc/letsencrypt/live/harbor.example.com/privkey.pem
Use CA confiável entre redes. insecure-registries não corrige uma cadeia TLS pública incorreta.
Estes comandos preservam o exemplo v2.15.2 e sua requisição .asc. Para v2.15.5 consultado, siga o procedimento 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"
Só se aplica a um pacote acompanhado da assinatura GPG autêntica correspondente e de uma impressão digital completa da chave verificada de forma independente:
gpg --keyserver hkps://keyserver.ubuntu.com \
--receive-keys 644FF454C0B4115C
gpg --verify \
"harbor-online-installer-${HARBOR_VERSION}.tgz.asc" \
"harbor-online-installer-${HARBOR_VERSION}.tgz"
Se faltar .asc, não pule verificação nem tente validar bundle Sigstore com esse identificador curto antigo.
Instale cosign compatível seguindo Sigstore oficial. Guarde o pacote em diretório 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 identidade vieram dos assets/bundle consultados. Em versões futuras, obtenha digest, bundle e identidade esperados daquela versão; não reutilize hash nem flexibilize verificações. Online baixa componentes ao instalar; offline os inclui.
Confira que /opt/harbor não contém outra instalação. Após verificar o pacote:
sudo tar -xzf "harbor-online-installer-${HARBOR_VERSION}.tgz" -C /opt
sudo chown -R root:root /opt/harbor
cd /opt/harbor
ls -la
Preserve download versionado e configuração para recuperação/atualização.
Copie certificados para rotas estáveis:
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
Gere segredos distintos para administrador e banco:
openssl rand -base64 32
openssl rand -base64 32
Um é para admin; outro para PostgreSQL. Troque Harbor12345 e guarde ambos com acesso restrito.
Use a nova versão da própria configuração:
cd /opt/harbor
sudo cp harbor.yml.tmpl harbor.yml
sudo chmod 600 harbor.yml
sudoedit harbor.yml
Altere valores necessários em harbor.yml. Os dois marcadores de senha abaixo representam o primeiro/segundo segredo e precisam ser totalmente substituídos:
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
hostnamecontém domínio semhttps://.certificate/private_keysão caminhos absolutos do host.data_volumeguarda registry, banco, Redis e scanner.skip_update: falsepermite atualizar vulnerabilidades.- Coloque senhas especiais entre aspas conforme YAML/configuração atual.
Procure senhas padrão:
sudo grep -nE 'Harbor12345|root123' /opt/harbor/harbor.yml
Não deve haver correspondência. harbor.yml contém credenciais e não pertence a repositório público.
Confira portas 80/443 livres:
sudo ss -lntp | grep -E ':(80|443)\b' || true
Outro servidor web exige IP/host separado ou proxy compartilhado planejado com external_url correto. Instale explicitamente scanner:
cd /opt/harbor
sudo ./install.sh --with-trivy
--with-trivy ativa Trivy; install.sh sozinho não. Confira serviços:
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
Saúde deve indicar healthy. /v2/ sem login normalmente responde 401 Unauthorized: prova desafio de autenticação, não acesso autenticado. Confira falhas:
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 com admin e segredo inicial de harbor.yml:
- Guarde administrador no gerenciador da equipe.
- Desative cadastro aberto salvo decisão explícita.
- Restrinja desenvolvedores aos projetos necessários.
- Crie projetos privados sem juntar tudo em
library. - Defina cotas.
- Confira Trivy e atualização do banco.
- Configure retenção de auditoria e alertas.
Projetos privados exigem membros/robots autorizados; públicos permitem pull anônimo e não protegem imagens internas.
Crie primeiro o projeto privado demo. Autentique:
docker login harbor.example.com
Teste o caminho 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
Inclua projeto na rota:
harbor.example.com/<project>/<repository>:<tag>
docker login pode guardar credenciais em ~/.docker/config.json. Use credential helper e permissões adequadas em computadores compartilhados.
Em Configuration do projeto:
- Ative análise automática após push.
- Decida bloqueio de pulls vulneráveis.
- Teste limiar como
Critical. - Use exceções temporárias para CVEs revisados.
Harbor bloqueia solicitações ao registry; não encerra imagens em execução nem substitui admissão do cluster. Teste Critical antes de produção para não impedir pull após reiniciar. Reanalise com novas bases e monitore atualizações. Limite concorrência em 4GB.
Crie em:
Projects → demo → Robot Accounts → New Robot Account
Dê a ci-push só permissões necessárias de demo:
- Repository Pull.
- Repository Push.
- Artifact Read.
- Scan apenas se CI o aciona explicitamente.
Defina validade, por exemplo 90 dias conforme política. Guarde nome gerado e segredo exibido uma vez; não adivinhe prefixos nem conceda acesso global desnecessário.
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 e 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"
'''
}
}
}
}
}
Construa em agent isolado; veja Jenkins. Faça logout/limpeza do diretório temporário de credenciais em post sempre executado, mesmo após falhar push. Separe:
ci-pushpara construir/enviar.staging-pullpara pull de teste.prod-pullpara pull de produção.- Segredos, validade e responsáveis distintos.
Produção não deve reutilizar ci-push.
Planeje regras e faça dry-run:
- Preserve releases
release-*necessários. - Guarde, por exemplo, os 20 builds
main-*recentes. - Guarde cinco builds por branch de desenvolvimento.
- Não dependa apenas de
latestmutável para rollback.
Registre digest implantado e proteja artefatos ativos:
docker inspect \
--format='{{index .RepoDigests 0}}' \
harbor.example.com/demo/webapp:42
Retenção seleciona artefatos; não libera todas as camadas imediatamente nem substitui backup/replicação.
Em Administration → Clean Up → Garbage Collection:
- Execute DRY RUN.
- Confira blobs/espaço candidatos.
- Confira push, retenção e replicação.
- Execute ou agende GC.
- Veja histórico e logs.
A janela histórica documentada protege camadas recentes por duas horas; confira a versão usada. Aja antes do disco acabar e alerte em 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 é /data; configuração fica em /opt/harbor. Só /opt/harbor/docker-compose.yml não contém blobs nem banco. Ative Read Only, aguarde jobs ativos e pare:
cd /opt/harbor
sudo docker compose ps
sudo docker compose down
Arquive dados parados:
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
Um /data grande exige espaço extra. Snapshot consistente ou restic criptografado de /data//opt/harbor para armazenamento independente pode ser melhor; veja backup/recuperação. Reinicie e retire Read Only após confirmar sucesso:
cd /opt/harbor
sudo docker compose up -d
curl -fsS https://harbor.example.com/api/v2.0/health | jq
Preserve:
/datacompleto./opt/harbor/harbor.yml, instalador e download versionado.- Compose/configuração gerados.
- TLS ou procedimento testado de reemissão.
- Versão e parâmetros
--with-trivy. - Reemissão de robots e atualização CI.
- Lista read-only/recuperação.
Criptografe arquivos fora do domínio de falha do registry.
Use VPS isolada conforme objetivo de recuperação, trimestralmente no exemplo:
- Iguale versões Docker/Harbor copiadas.
- Pare destino vazio.
- Restaure
/data//opt/harbor, proprietários, ACLs e atributos. - Confira domínio/rotas/segredos em
harbor.yml. - Execute
sudo ./prepare --with-trivy. - Execute
sudo docker compose up -d. - Confira Portal,
/api/v2.0/health//v2/. - Autentique, faça pull privado e confira digest.
- Confira projetos, robots, scans, políticas e auditoria.
- Registre duração e lacunas.
Recupere a versão original antes de atualizar major.
Harbor ocupa 80/443; standalone exige liberar 80 em manutenção:
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
Confira datas:
echo | openssl s_client \
-connect harbor.example.com:443 \
-servername harbor.example.com 2>/dev/null | \
openssl x509 -noout -issuer -dates
Automatize retorno do Harbor mesmo se renovação falhar e ensaie o procedimento. DNS-01 ou certificados em proxy independente podem evitar parada, com configuração real do provedor DNS.
Podem mudar harbor.yml e schema:
- Leia notas, compatibilidade e migração.
- Confira etapas de atualização suportadas.
- Copie
/data, banco e instalação. - Ensaie migração/rollback em cópia.
- Registre scanner, armazenamento, identidade e replicação.
- Agende manutenção.
O prepare destino goharbor/prepare:<tag> migra harbor.yml; Core migra banco pelo procedimento após backup de /data/database. Alterar tag não garante downgrade; mantenha banco e /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
Confira cert.pem/fullchain.pem, CA cliente e DNS. Não esconda com insecure-registries.
Com 413 Request Entity Too Large, confira CDN/WAF/proxy em 443, limites e timeouts. Mudanças geradas somem após 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
Confira disco, inodes, rotas, perdas, timeout e escrita em /data/registry.
cd /opt/harbor
sudo docker compose logs --tail=200 trivy-adapter
date -Is
curl -I https://github.com
Confira DNS de saída, relógio, proxy e limites das fontes. Use procedimento offline suportado; skip_update: true com dados antigos não comprova segurança.
Confira retenção/manifests compartilhados e GC dry-run. Nunca apague manualmente /data/registry/docker/registry/v2/blobs.
Confira validade, desativação, rotação e nome exato. Alterar robot não atualiza segredos Jenkins/GitHub automaticamente.
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 reduzir scans ou aumentar RAM.
prepare/prepare geram novamente a partir de harbor.yml. Guarde ajustes suportados em harbor.yml; mantenha proxy adicional separadamente.
- Fixe patch revisado do instalador.
- Verifique assinatura real e pacote.
- Atenda CPU/RAM/disco com folga para backup.
- Use
/dataexpansível e com snapshots. - Valide A/AAAA.
- Configure HTTPS confiável.
- Remova padrões de
harbor.yml, modo600. - Mantenha portas auxiliares internas.
- Instale
--with-trivye confira scanner. - Use projetos privados/cotas.
- Teste análise após push.
- Teste limites em projeto seguro.
- CI usa robots de projeto, não
admin. - Separe push e pull produção.
- Monitore rotação/validade.
- Faça dry-run de retenção.
- Agende/revise GC.
- Ative alertas 70%/85%.
- Criptografe backups externos
/data//opt/harbor. - Ensaie pull privado/digest recuperados.
- Teste renovação TLS.
- Atualize com backup/migração suportados.
2 núcleos/4GB/40GB é o mínimo histórico; 4 núcleos/8GB/160GB e disco independente costuma atender melhor uma equipe pequena, medido por scans e crescimento.
Registry armazena artefatos; Harbor adiciona RBAC, robots, scanner, auditoria, replicação, retenção e GC, com mais manutenção.
Use entre redes. insecure-registries reduz confiança; HTTP cabe em experimentos isolados deliberados.
Camadas compartilhadas seguem referenciadas; GC remove blobs elegíveis após revisar retenção e implantações.
Robot de projeto com validade, nunca admin; use robot pull-only separado na produção.
/data/registry omite metadados/permissões. Restaure /data//opt/harbor consistentes com TLS/procedimentos. Comprove recuperação de /data por build, push, scan, pull e rollback no demo.