Tutoriais de VPS
Gateway de API de IA auto-hospedado em VPS (2026): One-API / New-API, modelos unificados, gestão de chaves, limitação de taxa e cobrança
Quer unificar OpenAI, Claude, Gemini, DeepSeek, Qwen, Doubao e outros modelos atrás de um único ponto de entrada de API? Este artigo explica quando um gateway de API de IA auto-hospedado em VPS faz sentido, como escolher entre One-API e New-API, implantação com Docker Compose, configuração de canais, gestão de chaves, limitação de taxa, logs e uma lista de verificação de segurança.
A maioria das pessoas começa a integrar APIs de IA escrevendo diretamente no código o endereço da OpenAI, Claude ou Gemini. Com poucos projetos não há problema, mas quando você tem três ou quatro provedores de modelos, dois ou três projetos e uma dúzia de chaves de API, tudo começa a ficar bagunçado:
- Um projeto usa o formato da OpenAI, outro usa o da Claude;
- Um colega ficou com a chave mestra e, no fim do mês, ninguém sabe quem gastou o quê;
- O DeepSeek é barato, mas às vezes você quer fallback automático para outro modelo;
- Você quer distribuir chaves para clientes ou ferramentas internas sem expor as chaves reais do provedor;
- O orçamento é limitado e você quer cotas, limites de taxa e logs por chave.
É aí que entra o gateway de API de IA. Em resumo, você monta seu próprio "ponto de entrada de modelos": o backend se conecta a vários provedores e o frontend expõe apenas um endereço de API unificado. A partir daí, o lado da aplicação só precisa alterar base_url em vez de editar código em todo lugar.
Em 2026, as duas opções mais comuns para auto-hospedar um gateway de API de IA na comunidade de língua chinesa continuam sendo One-API e New-API. O One-API é o projeto veterano: leve e fácil de entender. O New-API é um fork ativo derivado do One-API, com mais recursos, suporte à conversão de protocolos entre OpenAI, Claude, Gemini e outros, e melhor encaixe para cenários multiusuário, multicanal e multimodelo.
Vamos começar pela conclusão: não todo mundo precisa auto-hospedar.
Se você só usa o ChatGPT pessoalmente, ou chama o DeepSeek de vez em quando em um script, a API oficial já basta. Auto-hospedar um gateway só adiciona uma camada de manutenção.
Mas as situações a seguir se encaixam muito bem:
| Cenário | Valor de um gateway auto-hospedado |
|---|---|
| Vários provedores de modelos | Gerenciar OpenAI, Claude, Gemini, DeepSeek, Qwen, Doubao e outros canais a partir de um único ponto de entrada |
| Uso compartilhado entre vários projetos | Emitir uma chave separada por projeto e desativá-la individualmente se algo der errado |
| Uso interno da equipe | Ver consumo, cotas e de onde vem o gasto |
| Redistribuição para clientes | Não expor as chaves de API reais do provedor |
| Controle de custos | Definir cotas, limites de taxa e permissões de modelos por chave |
| Camada de compatibilidade | Permitir que ferramentas que só suportam o formato OpenAI acessem mais modelos |
O uso mais típico que já vi: o New-API roda em um VPS e o Dify, o LobeChat, as tarefas de script e os bots de atendimento da empresa passam todos por esse ponto de entrada unificado. No painel você vê de relance quantos tokens cada um usa. Se um canal falhar, você reduz o peso dele ou o desativa temporariamente, e o código da aplicação não precisa mudar.
Os dois projetos têm nomes muito parecidos, mas o posicionamento já não é exatamente o mesmo.
| Comparação | One-API | New-API |
|---|---|---|
| Público-alvo | Quem quer algo leve, simples e estável | Quem quer mais modelos, painel mais completo e manutenção mais ativa |
| Maturidade do projeto | Projeto veterano com lógica clara | Comunidade mais ativa, iteração de recursos mais rápida |
| Implantação | Docker / binário único | Docker / Docker Compose / painel / cluster |
| Suporte a protocolos | Principalmente compatível com OpenAI | Conversão multiprotocolo mais forte para OpenAI, Claude, Gemini e mais |
| Complexidade de recursos | Menor | Maior |
| Licença | MIT | AGPL-3.0 |
Minha recomendação é direta:
- Uso pessoal, só unificar alguns endpoints compatíveis com OpenAI: o One-API basta;
- Uso em equipe com vários modelos, várias chaves, estatísticas de consumo e conversão de protocolos: prefira o New-API;
- Desenvolvimento secundário comercial ou distribuição de código fechado: leia bem a licença; o New-API é AGPL-3.0, não ignore essa pegadinha.
O repositório oficial do One-API é songquanpeng/one-api, e o do New-API mais ativo atualmente é QuantumNous/new-api. Antes de implantar, vale a pena ler o README e a documentação oficial, porque variáveis de ambiente, nomes de imagem e suporte a bancos de dados mudam conforme a versão.
O gateway de API de IA em si não executa modelos, apenas encaminha requisições e registra consumo, então não exige muito do VPS. O que realmente custa dinheiro são os modelos do provedor, não o gateway.
Sugiro escolher assim:
| Uso | Configuração recomendada |
|---|---|
| Uso pessoal | 1 núcleo e 1 GB roda; 2 GB é mais estável |
| Equipe interna pequena | Começar com 2 núcleos e 2 GB |
| Distribuição multiusuário + MySQL | 2 núcleos e 4 GB é mais confortável |
| Alta concorrência ou serviço comercial | Banco de dados separado + proxy reverso + monitoramento; não economize e aguente no limite |
Com 20 GB de disco já basta para começar. Não guarde os logs indefinidamente, ou em alguns meses você vai ver que o banco de dados é muito maior que o programa.
Recomendo Ubuntu 22.04/24.04 ou Debian 12. A implantação com contêineres é a mais prática e facilita a migração posterior.
A seguir uso o New-API como exemplo. O One-API funciona de forma semelhante, apenas com imagens e variáveis de ambiente ligeiramente diferentes.
Primeiro prepare o diretório:
mkdir -p /opt/new-api
cd /opt/new-api
Escreva um docker-compose.yml mínimo que funcione:
services:
new-api:
image: calciumion/new-api:latest
container_name: new-api
restart: unless-stopped
ports:
- "3000:3000"
environment:
- SQL_DSN=root:change_this_password@tcp(mysql:3306)/new-api
- TZ=Asia/Shanghai
depends_on:
- mysql
mysql:
image: mysql:8
container_name: new-api-mysql
restart: unless-stopped
environment:
- MYSQL_ROOT_PASSWORD=change_this_password
- MYSQL_DATABASE=new-api
- TZ=Asia/Shanghai
volumes:
- ./mysql:/var/lib/mysql
Inicie:
docker compose up -d
docker compose logs -f new-api
Depois acesse:
http://你的服务器IP:3000
Após o primeiro login, faça três coisas imediatamente:
- Alterar a senha de administrador padrão;
- Desativar o registro público que você não precisa;
- Configurar proxy reverso e HTTPS; não deixe a porta 3000 exposta a longo prazo.
Se você usa Nginx, pode fazer o proxy reverso assim:
server {
listen 80;
server_name api.example.com;
location / {
proxy_pass http://127.0.0.1:3000;
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;
}
}
Depois obtenha um certificado com Certbot ou acme.sh. Não rode produção apenas em HTTP.
Implantar o gateway é só o primeiro passo; o tempo de verdade vai para a configuração dos canais.
Os canais comuns podem ser agrupados assim:
| Tipo de canal | Exemplos | Pontos de atenção |
|---|---|---|
| OpenAI oficial | GPT-4o, GPT-4.1, etc. | Caro, mas estável; atenção aos limites de cobrança |
| Compatível com OpenAI | DeepSeek, Moonshot, OpenRouter, etc. | A URL base é diferente; os nomes dos modelos precisam coincidir |
| Claude | Anthropic Claude | O protocolo não é idêntico ao da OpenAI; o New-API facilita |
| Gemini | Google Gemini | Alguns modelos têm contexto longo, mas confira bem os limites de taxa |
| Modelos nacionais | Qwen, Doubao, Zhipu, Wenxin, etc. | Autenticação e nomes de modelos costumam ser diferentes; não copie os parâmetros da OpenAI às cegas |
Ao configurar, agrupe por "finalidade" em vez de jogar todos os canais de uma vez:
- Chat de baixo custo: DeepSeek / Qwen / Doubao;
- Escrita de alta qualidade: Claude / GPT;
- Processamento de contexto longo: Gemini / modelos de contexto longo da Claude;
- Ambiente de testes: modelos baratos com cota limitada;
- Ambiente de produção: canais estáveis com chaves separadas.
Assim a resolução de problemas fica muito mais fácil depois.
O maior benefício de auto-hospedar um gateway para muita gente não é economizar dinheiro, mas "recuperar o controle das permissões".
A forma correta é:
- As chaves de API reais do provedor ficam só no painel do gateway;
- Emitir uma chave independente por projeto, usuário e ambiente;
- Definir nas chaves cotas, datas de expiração e permissões de modelos;
- Registrar o consumo separadamente por finalidade, por exemplo
dify-prod,lobechat-home,crawler-test; - Se algo der errado, desativar uma única chave sem afetar outros projetos.
Não use uma chave só para tudo. Principalmente se você colocar chaves em projetos frontend, repositórios públicos do GitHub ou plugins de terceiros, o vazamento é só questão de tempo.
Se só você usa, os limites de taxa podem ser frouxos. Mas assim que outras pessoas usarem, a limitação precisa estar ativada.
Sugiro controlar por estas dimensões:
| Controle | Sugestão |
|---|---|
| Requisições por minuto | Evitar que scripts em loop esgotem as cotas |
| Cota diária | Evitar que um único usuário consuma todo o orçamento |
| Permissões de modelos | Usuários comuns só usam modelos baratos; os caros são autorizados à parte |
| Peso dos canais | Priorizar canais baratos e usar os caros como reserva |
| Repetições em falhas | Não repetir sem fim; os 429 do provedor só pioram |
Uma pegadinha real: um script tinha a lógica de repetição em exceções escrita errada e, após um 500 do endpoint do modelo, repetia dezenas de vezes por segundo. Sem limitação de taxa no gateway, a fatura do provedor ficaria assustadora. Com gateway, no máximo essa chave é limitada e o sistema inteiro não é arrastado junto.
A maioria das ferramentas compatíveis com OpenAI só precisa de duas mudanças:
API Key: 你在网关里生成的 Key
Base URL: https://api.example.com/v1
Por exemplo, em Python:
from openai import OpenAI
client = OpenAI(
api_key="sk-your-gateway-key",
base_url="https://api.example.com/v1"
)
response = client.chat.completions.create(
model="deepseek-chat",
messages=[{"role": "user", "content": "写一段 VPS 备份脚本说明"}]
)
print(response.choices[0].message.content)
Ferramentas como Dify, LobeChat, Cherry Studio e LibreChat também costumam permitir configurar um endereço compatível com OpenAI. Preencha o endereço do seu gateway e você poderá unificar vários modelos atrás dele.
Um gateway de API de IA exposto à internet não tem menos risco que um site comum. No mínimo, faça isto:
- Senha forte no painel de administração e ative 2FA se possível;
- Não exponha o painel no caminho padrão, ou adicione outra camada com Cloudflare Access / Basic Auth;
- Adicione limitação de taxa básica na camada do Nginx;
- Abra apenas 80/443, não exponha a 3000 diretamente;
- Não use o
change_this_passworddo exemplo como senha do banco de dados; - Faça backup periódico do MySQL;
- Registre consumo anômalo, por exemplo um pico repentino em uma chave específica;
- Configure também alertas de orçamento nas plataformas do provedor; não confie só no gateway.
Exemplo simples de limitação de taxa no Nginx:
limit_req_zone $binary_remote_addr zone=aiapi:10m rate=10r/s;
server {
listen 443 ssl http2;
server_name api.example.com;
location / {
limit_req zone=aiapi burst=20 nodelay;
proxy_pass http://127.0.0.1:3000;
}
}
Não é uma defesa universal, mas bloqueia parte do uso indevido de scripts e varreduras de baixo custo.
O gateway em si pode ser reconstruído; o mais importante é o banco de dados.
Sugiro fazer backup uma vez por dia:
mkdir -p /opt/backups/new-api
docker exec new-api-mysql mysqldump \
-uroot \
-p'change_this_password' \
new-api > /opt/backups/new-api/new-api-$(date +%F).sql
Depois sincronize fora do servidor com rclone ou armazenamento de objetos. Não guarde os backups só no mesmo VPS; se o disco morrer, é como se você não tivesse backup.
A migração geralmente tem três passos:
- Instalar o Docker no servidor novo;
- Copiar o
docker-compose.ymle os dados/backup do MySQL; - Trocar o DNS para o servidor novo.
Se o negócio for importante, restaure primeiro na máquina nova e confirme que o painel, as chaves, os canais e os logs funcionam, e só então troque o domínio.
O provedor chama de deepseek-chat e sua aplicação escreve gpt-4, então é claro que dá erro. Confirme primeiro o mapeamento de modelos no gateway e depois altere a configuração da aplicação.
Alguns proxies reversos ou CDNs fazem buffer da resposta, transformando a saída em streaming em uma descarga de uma vez. No Nginx você pode desativar o buffering do proxy:
proxy_buffering off;
Os 429 geralmente são limites de taxa ou problemas de saldo do provedor. Veja primeiro os logs do canal e depois os logs da aplicação; não reinicie o contêiner de imediato.
Verifique estes três pontos:
docker compose ps
ss -lntp | grep 3000
ufw status
Um contêiner saudável não significa que a porta esteja acessível; verifique também o firewall e o grupo de segurança do provedor de nuvem.
Se você só quer unificar rapidamente várias APIs de IA, sugiro ir direto para o New-API. Ele tem recursos mais completos e uma comunidade mais ativa, o que combina com o ambiente de uso misto de vários modelos em 2026.
Se você se importa muito com simplicidade, leveza e licença permissiva, o One-API ainda é utilizável. Só que mais adiante você pode esbarrar em recursos insuficientes e conversão de protocolos não tão prática.
A forma mais sólida de implantar é:
- Começar com um VPS de 2 núcleos e 2 GB;
- Implantar New-API + MySQL com Docker Compose;
- Proxy reverso Nginx + HTTPS;
- Emitir uma chave separada por projeto;
- Ativar cotas, limitação de taxa e logs;
- Backup diário do banco de dados;
- Configurar também alertas de orçamento nas plataformas do provedor.
Um gateway de API de IA não é para exibir. O que ele realmente resolve é o problema de "cada vez mais modelos, chaves cada vez mais bagunçadas e faturas cada vez mais feias". Se você já integra APIs de IA em vários projetos, gastar meia hora agora montando uma camada de gateway vai economizar muito tempo de diagnóstico e gestão depois.