Tutoriais de VPS
Go na VPS: compilação cruzada, systemd, Nginx e memória
Compile Go para Linux, implante arquivos, supervisione com systemd e configure Nginx HTTPS. Ajuste GOMEMLIMIT, confira CPU de contêineres, implemente encerramento gracioso e verifique o rollback de versões.

Uma aplicação em Go puro pode ser implantada como um binário sem instalar o compilador na VPS. Compile localmente ou em CI, transfira o artefato e supervisione o processo. Linkagem estática tem condições: CGO, arquivos externos, certificados e dados de fuso ainda exigem cuidado. Problemas comuns incluem Exec format error, loader ou recursos ausentes e pressão de memória.
Este guia para Ubuntu 24.04 cobre compilação cruzada, arquivos, systemd, memória, encerramento gracioso, Nginx e implantações recuperáveis. Reiniciar uma instância pode interromper a disponibilidade por um momento; continuidade exige outra estratégia testada.
Vantagens:
- A VPS de execução não precisa do compilador Go.
- Dependências compiladas não mudam com atualizações de pacotes externos; preserve artefato, lockfiles e identidade do build.
- Início e memória podem atender máquinas pequenas, conforme a aplicação.
- macOS e Windows podem gerar binários Linux quando as dependências suportam o destino.
Limites:
- Templates e frontend exigem inclusão ou implantação explícita.
- CGO pode introduzir dependências de loader e bibliotecas dinâmicas.
- Um orçamento de memória ajuda, mas não evita todo OOM.
- A aplicação precisa implementar encerramento gracioso; systemd não conclui requisições por ela.
Exemplo Linux:
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 \
go build \
-trimpath \
-ldflags="-s -w -X main.version=$(git rev-parse --short HEAD)" \
-o dist/myapp ./cmd/myapp
CGO_ENABLED=0 desativa CGO. Para dependências compatíveis de Go puro, evita depender do runtime C. Com CGO, pode haver dependência de glibc e seu loader; Ubuntu, Debian e Alpine com musl não são automaticamente intercambiáveis. Confira o artefato produzido.
GOOS=linux GOARCH=amd64 seleciona a plataforma:
| Arquitetura VPS | GOARCH |
|---|---|
| x86_64 / amd64 | amd64 |
| ARM64 | arm64 |
Na VPS, rode uname -m: x86_64 indica amd64 e aarch64 arm64. Veja escolha de ARM.
-trimpath remove caminhos locais e ajuda na reprodutibilidade. -s -w remove símbolos e seções de debug; a redução de 20–30% citada é ilustrativa e stack traces normais de panic geralmente continuam disponíveis. Mantenha build de debug quando necessário.
-X main.version=... define uma variável string com o commit:
var version = "dev"
func main() {
log.Printf("starting myapp version=%s", version)
// ...
}
Ajuste o caminho real do pacote e preserve fontes e dependências. Se precisar de CGO, compile em ambiente compatível ou configure uma toolchain C de compilação cruzada, incluindo musl quando buscar um estático compatível. CGO pode ser compilado para outro destino com as ferramentas certas; trocar apenas GOARCH não basta.
Um binário comum não inclui automaticamente templates, CSS, imagens e builds frontend.
import (
"embed"
"html/template"
"net/http"
)
//go:embed templates/*.html static/*
var assets embed.FS
func main() {
tpl := template.Must(template.ParseFS(assets, "templates/*.html"))
http.Handle("/static/", http.FileServer(http.FS(assets)))
_ = tpl
http.ListenAndServe("127.0.0.1:3000", nil)
}
Embeddings vinculam os arquivos ao binário, simplificando rollback. Com //go:embed:
../não pode sair da árvore permitida;- a travessia normalmente exclui nomes iniciados por
_ou.; use//go:embed all:staticquando quiser incluí-los deliberadamente.
Confira padrões e rotas. Não embuta credenciais ou arquivos de desenvolvimento por acidente.
Nginx pode entregar o frontend em vez de http.FileServer do Go. Desempenho depende de cache, disco e carga; não é uma garantia universal.
| Escolha | Arquivos embutidos | Arquivos externos com Nginx |
|---|---|---|
| Implantação | Um artefato conjunto | Coordenar binário e arquivos |
| Entrega | Processo Go | Proxy diretamente |
| Atualização frontend | Recompilar | Publicar arquivos versionados |
| Tamanho do binário | Inclui arquivos | Não aumenta pelos arquivos externos |
Uma opção prática usa go:embed para templates e frontend externo versionado. Preserve os arquivos exigidos pela versão de rollback.
Um programa em primeiro plano combina com Type=simple. Salve /etc/systemd/system/myapp.service:
[Unit]
Description=Go App
After=network.target
[Service]
Type=simple
User=appuser
Group=appuser
WorkingDirectory=/srv/app/current
EnvironmentFile=/srv/app/shared/.env
Environment=GOMEMLIMIT=400MiB
ExecStart=/srv/app/current/myapp
Restart=always
RestartSec=3
# 优雅退出:给 15 秒处理完在途请求
KillSignal=SIGTERM
TimeoutStopSec=15
StandardOutput=journal
StandardError=journal
SyslogIdentifier=myapp
# 资源与安全限制
MemoryMax=512M
LimitNOFILE=65535
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/srv/app/shared
[Install]
WantedBy=multi-user.target
Antes de habilitar, crie appuser, /srv/app/releases e /srv/app/shared, instale o executável com proprietário correto, prepare current e o arquivo protegido de ambiente. A conta de implantação precisa de permissões restritas para reiniciar o serviço.
WorkingDirectoryimporta para./config.yamle./templates; caminhos absolutos ougo:embedevitam confusão de diretórios.EnvironmentFileaponta parashared/.envpara preservar segredos. systemd lê o arquivo; Go ainda precisa consumir as variáveis previstas.ProtectSystem=stricttorna a maioria dos caminhos somente leitura. Declare diretórios de uploads/logs/cache emReadWritePathspara evitarRead-only file system. Proteja.envcontra escrita da aplicação.
sudo systemctl daemon-reload
sudo systemctl enable --now myapp
sudo systemctl status myapp
GOGC=100 define uma meta de crescimento do GC, não uma regra de coletar somente quando todo o RSS dobrar. GOMEMLIMIT, introduzido no Go 1.19, estabelece um limite flexível da memória gerenciada pelo runtime:
Environment=GOMEMLIMIT=400MiB
O original sugere margem de 20–30% abaixo do orçamento do processo/cgroup, como MemoryMax=512M com GOMEMLIMIT=400MiB. Meça essa margem: stacks e estruturas gerenciadas pelo Go já estão incluídas; memória de CGO, mmap direto e alguns recursos do sistema ficam fora. Um heap vivo grande pode superar o limite flexível, e um limite muito baixo pode causar trabalho excessivo de GC.
O teto rígido continua sendo MemoryMax do systemd ou --memory do Docker. Coordene ambos e monitore OOM.
O trecho pprof original:
import _ "net/http/pprof"
go func() {
log.Println(http.ListenAndServe("127.0.0.1:6060", nil))
}()
Use túnel SSH para http://localhost:6060/debug/pprof/heap, com o listener de debug somente em 127.0.0.1. Use um ServeMux de debug separado: importar pprof registra handlers em DefaultServeMux; usar o mesmo mux na aplicação pode expô-los pelo Nginx mesmo com 6060 privado. Profiles revelam informações sensíveis: proteja o acesso e remova exposição desnecessária.
Runtimes antigos podiam usar o número de CPUs do host apesar de uma quota menor, exigindo ajustes como GOMAXPROCS=1. Go 1.25 adicionou padrões Linux baseados em cgroups e atualização periódica de GOMAXPROCS.
Quota de uma CPU não garante padrão igual a um: o cálculo normalmente tem mínimo de dois, salvo limites menores de CPUs lógicas/afinidade, e arredonda quotas fracionárias para cima. Versão de linguagem e configurações explícitas também importam. Avalie se ainda precisa do antigo GOMAXPROCS. GODEBUG=containermaxprocs=0 desativa a consideração de quota; definir GOMAXPROCS manualmente altera o automatismo. Consulte Go 1.25.
Go mantém as duas famílias mais recentes. 1.27.1/1.26.8 e a retirada de 1.25 do artigo de setembro são referências históricas. A lista oficial consultada em 16 de novembro de 2026 mostra 1.27.4 e 1.26.11. Construa com toolchain suportada e atualizada, teste e reimplante: um binário pronto não recebe patches sozinho.
systemctl restart encerra o processo anterior com SIGTERM. Sem tratar sinais, requisições ativas podem ser interrompidas:
srv := &http.Server{
Addr: "127.0.0.1:3000",
Handler: mux,
ReadTimeout: 15 * time.Second,
WriteTimeout: 30 * time.Second,
IdleTimeout: 60 * time.Second,
}
go func() {
if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
log.Fatalf("listen: %v", err)
}
}()
quit := make(chan os.Signal, 1)
signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
<-quit
log.Println("shutting down...")
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if err := srv.Shutdown(ctx); err != nil {
log.Fatal("forced shutdown:", err)
}
log.Println("server exited")
srv.Shutdown(ctx)para de aceitar conexões e aguarda requisições HTTP normais em andamento.- O prazo da aplicação deve ser menor que
TimeoutStopSec; aqui 10 segundos cabem em 15, mas requisições longas exigem estratégia de drenagem. - Trate
SIGTERM, não apenasSIGINT. http.Servertem timeouts zero por padrão. ConfigureReadTimeout,WriteTimeoute limites de headers/inatividade; streaming exige prazos próprios.
Shutdown não fecha automaticamente WebSockets hijacked nem conclui todo trabalho de background. Controle esses casos separadamente. Encerrar com cuidado ajuda requisições ativas, mas reiniciar uma única instância ainda deixa uma janela sem listener.
Go escuta em 127.0.0.1:3000; Nginx publica HTTP/HTTPS:
upstream goapp {
server 127.0.0.1:3000;
keepalive 32;
}
server {
listen 80;
listen [::]:80;
server_name app.example.com;
client_max_body_size 20m;
access_log /var/log/nginx/app.access.log;
error_log /var/log/nginx/app.error.log warn;
location / {
proxy_pass http://goapp;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Connection "";
proxy_connect_timeout 5s;
proxy_read_timeout 60s;
}
# WebSocket / SSE(Go 里很常见)
location /ws/ {
proxy_pass http://goapp;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_read_timeout 3600s;
proxy_buffering off;
}
}
sudo nginx -t && sudo systemctl reload nginx
Adicione HTTPS com Certbot após conferir DNS e acesso público em 80/443, teste renovação ou veja Caddy. Salve a configuração em diretório carregado pelo Nginx e revise os firewalls do provedor/UFW.
Encaminhe X-Forwarded-For, mas r.RemoteAddr continua identificando o proxy conectado, geralmente 127.0.0.1. A aplicação deve interpretar headers somente de proxies confiáveis; encaminhá-los não altera RemoteAddr automaticamente. /ws/ também precisa de headers de cliente/protocolo correspondentes. SSE não exige Upgrade de WebSocket, mas exige buffering e timeouts adequados.
Script original:
#!/usr/bin/env bash
set -euo pipefail
HOST=deploy@your-vps
RELEASE=$(date +%Y%m%d-%H%M%S)
TARGET=/srv/app/releases/$RELEASE
# 1. 本地编译
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build \
-trimpath \
-ldflags="-s -w -X main.version=$(git rev-parse --short HEAD)" \
-o /tmp/myapp ./cmd/myapp
# 2. 传输
ssh "$HOST" "mkdir -p $TARGET"
scp /tmp/myapp "$HOST:$TARGET/myapp"
# 3. 切换并重启
ssh "$HOST" "chmod +x $TARGET/myapp && \
ln -sfn $TARGET /srv/app/current && \
sudo systemctl restart myapp"
# 4. 清理旧版本,保留最近 5 个
ssh "$HOST" "ls -1dt /srv/app/releases/* | tail -n +6 | xargs -r rm -rf"
Preserve set -euo pipefail para não trocar current por artefato antigo ou ausente depois de falha no build. Substitua host/caminhos, confira chaves SSH, registre commit e hash e garanta permissões do usuário de execução.
Guarde o destino anterior antes da troca. Depois do reinício, confira versão ativa e saúde local/pública. Se falhar, restaure o link e reinicie a versão anterior. Limpe apenas depois da verificação, retendo versões ativa e de rollback; conservar cinco não garante recuperação. Para continuidade, inicie outra instância em porta privada distinta, valide prontidão, troque o proxy e drene a anterior. Veja runner GitHub Actions para builds CI.
cannot execute binary file: Exec format error costuma indicar amd64 versus arm64. Confira uname -m e compile para o destino.
No such file or directory pode indicar loader dinâmico ou interpretador ausente. Inspecione:
file ./myapp # 看是 statically linked 还是 dynamically linked
ldd ./myapp # 动态链接的话,看依赖什么
Recompile com CGO_ENABLED=0 apenas se as dependências suportarem Go puro; caso contrário forneça ambiente compatível de bibliotecas/loader.
Para permission denied, confira proprietário/modo, chmod +x myapp, política noexec, diretórios e escrita bloqueada por ProtectSystem=strict. Veja journalctl -u myapp para identificar a operação.
Confira WorkingDirectory, caminhos absolutos e arquivos implantados. go:embed simplifica o vínculo quando adequado.
Configure GOMEMLIMIT e faça profiling de alocações/goroutines. Corpos de resposta sem Close() e time.Ticker sem Stop() podem reter recursos; confira os ciclos de vida reais. Swap/ZRAM pode aliviar pressão, mas não corrige vazamentos.
As oito horas do original representam Asia/Shanghai versus UTC, não o fuso esperado por todo leitor. Escolha UTC ou a zona IANA necessária e forneça os dados. Eles podem ser embutidos com -tags timetzdata:
go build -tags timetzdata -o dist/myapp ./cmd/myapp
Mantenha os outros flags de plataforma/linkagem estática; esse exemplo de fuso não os substitui.
Confira systemctl status myapp e se localhost resolve diferente de 127.0.0.1. Veja 502/504.
sudo ss -lntp 'sport = :3000' identifica o proprietário; não encerre serviços alheios. Consulte conflitos de portas e logs.
FROM scratch pode produzir uma imagem pequena de Go puro, mas menos de 20 MB é um exemplo condicionado ao projeto. Inclua certificados CA, dados de fuso e arquivos necessários. Um único serviço pode ser mais simples com systemd; Compose ajuda a coordenar vários.
| Escolha | systemd | Docker |
|---|---|---|
| Artefato | Binário e arquivos necessários | Imagem |
| Isolamento | Sandbox de serviço configurado | Isolamento configurado; privilégios/mounts podem enfraquecê-lo |
| Tamanho | Depende da aplicação | Um exemplo scratch pode ter menos de 20 MB |
| Vários serviços | Unidades e configuração separadas | Compose |
| Diagnóstico | Serviço do host | Camada adicional de contêiner/rede |
Escolha pelas necessidades operacionais, não por uma classificação universal de isolamento. Veja limites Compose. CPU depende da carga: GC e escalonamento podem usar vários núcleos, e pouca memória não é garantida. RackNerd anual e Vultr por hora são opções a conferir; CN2 GIA da DMIT atende especificamente à conectividade com a China continental. Veja dimensionamento.
- Node.js para um serviço complementar;
- Python para Django/FastAPI;
- Dimensionamento VPS para recursos medidos;
- Docker para contêineres;
- Ensaios de recuperação para banco, uploads e segredos: voltar o binário não restaura dados nem desfaz migrações.