VPS 与 Docker 部署 Magpie：搭建多设备共享的私有 AI 网关

准备

• 一台运行 Linux 的云服务器（VPS）或 NAS（支持 Docker 与 Docker Compose，内存建议 512MB 以上）。
• 已领取的任意平台 API Key（如百炼、硅基流动、Groq 等）或支持的厂商账号。
• 至少一台需要使用 AI 服务的客户端电脑（安装了 Claude Code、Codex、OpenCode 或 Cherry Studio 等）。

步骤

1. 01

   创建配置文件目录并设置容器权限

   登录你的 VPS 或服务器终端，创建存放 Magpie 配置和密钥的持久化目录。

   Magpie 官方 Docker 镜像以无 root 权限用户（UID 65532）运行。为了让容器能够正常读写配置与证书，必须把目录属主修改为 65532:65532。

   bash复制

   mkdir -p ~/magpie/config
   cd ~/magpie
   sudo chown -R 65532:65532 ./config

2. 02

   编写 docker-compose.yml 并启动容器

   在 ~/magpie 目录下创建 docker-compose.yml 文件。

   安全原则：
   - 3430 端口（Web 管理控制台）：包含所有平台密钥，强烈建议只绑定到本地回环 127.0.0.1:3430，不要直接暴露到公网；通过 SSH 隧道访问。
   - 3425 端口（AI 网关）：用于接收客户端请求，可映射到服务器网卡；外部请求必须携带 Gateway Key，未授权请求会被直接拦截（401）。
   - MAGPIE_WEB_KEY：设置随机生成的固定秘钥，保证容器重启后控制台登录态不丢失。

   yaml复制

   services:
     magpie:
       image: ghcr.io/yetone/magpie:latest
       container_name: magpie
       restart: unless-stopped
       ports:
         # 网关端口供客户端调用
         - "3425:3425"
         # Web 控制台仅限本机访问，后续通过 SSH 隧道打开
         - "127.0.0.1:3430:3430"
       environment:
         - MAGPIE_PUBLIC_URL=http://<你的VPS公网IP或内网IP>:3425
         - MAGPIE_WEB_KEY=CHANGE_THIS_TO_A_RANDOM_SECRET_KEY_16CHARS
       volumes:
         - ./config:/config
       command: [web, --addr, 0.0.0.0:3430, --no-open]

3. 03

   启动服务并通过 SSH 隧道打开 Web 面板

   在 VPS 上拉取镜像并后台运行容器：

   ```bash
   docker compose up -d
   ```

   检查运行状态 docker compose ps。因为 3430 端口绑定在 VPS 本地回环，在本地电脑上执行 SSH 端口转发即可安全打开管理面板：

   ```bash
   ssh -L 3430:127.0.0.1:3430 root@<你的VPS_IP>
   ```

   保持 SSH 连接，在本地电脑浏览器访问：http://127.0.0.1:3430/?k=<你的MAGPIE_WEB_KEY>。即可进入与桌面端完全一致的 Magpie 网页管理界面。

   bash复制

   # 本地电脑终端建立隧道（保持终端开启）
   ssh -L 3430:127.0.0.1:3430 root@<你的VPS_IP>

4. 04

   在面板中添加 API 供应商与账号

   在浏览器 Web 面板中点击 供应商（Providers）→ 添加供应商：

   • 添加免费 API：选择百炼、硅基流动、Groq、火山方舟等，填入 API Key 与 Base URL，点击 测试 确认连通。
   • 账号模型接入：如需使用 Qoder 或 WorkBuddy 国际版的免费模型，在设置中安装对应认证插件，并在浏览器中完成授权登录。
   • 配置路由组：在 路由（Routing） 中创建主备模型组（如按顺序 order 依次尝试百炼、硅基、Groq），实现单家限流或故障时自动切换。

   配置完成后数据会自动保存在挂载的 ./config 目录中，容器重启不丢失。

5. 05

   生成客户端专用 Gateway Key（强制鉴权）

   Magpie 运行在 Docker 外部调用时，必须凭有效的 Gateway Key 进行鉴权。不要把 VPS 裸开给所有人。

   可以通过 Web 面板的 网关（Gateway）→ Gateway keys 点击添加，也可以直接在 VPS 终端执行命令：

   • 为你的笔记本或特定客户端生成专属 Key：终端会打印出类似 sk-magpie-key-... 的密钥。
   • 可选配额与限制：支持为单把 Key 限制每日/每月消耗预算或限制可调用的模型列表，避免某台设备跑飞或被盗刷。

   bash复制

   # 在 VPS 上为客户端生成新 Key
   docker exec magpie magpie gateway-key add "MacBook-Air"
   
   # 可选：限制该 Key 每月最多调用额度（例如 1000 万 Tokens）
   docker exec magpie magpie gateway-key limit "MacBook-Air" month --tokens 10000000

6. 06

   客户端接入方式一：直接配置为 OpenAI / Anthropic 兼容端点

   在任意电脑上的 AI 客户端（如 Cherry Studio、NextChat、Cursor 或终端 Agent）中，直接将 API 地址指向 VPS 的 Magpie 网关：

   • OpenAI 兼容客户端（Cherry Studio、沉浸式翻译等）：
   • Base URL：http://<你的VPS_IP>:3425/v1
   • API Key：填入上一步生成的 sk-magpie-key-...
   • 模型名称：填入 Magpie 中的模型标识（如 bailian/qwen-plus）或路由组标识（如 group/my-coding-group）。
   • Anthropic / Claude 客户端：
   • Base URL：http://<你的VPS_IP>:3425（不带 /v1 后缀）
   • API Key：sk-magpie-key-...

   测试命令如下，返回 200 即说明公网网关鉴权正常：

   bash复制

   curl http://<你的VPS_IP>:3425/v1/models \
     -H "Authorization: Bearer sk-magpie-key-xxx"

7. 07

   客户端接入方式二：本机 Magpie 挂载为 Remote Magpie

   如果你的笔记本本地也安装了 Magpie 桌面端或 CLI，更推荐使用 Remote Magpie（远程挂载） 模式：

   1. 打开本地电脑 Magpie 的 供应商（Providers）→ 添加供应商。
   2. 选择 Remote magpie，输入 VPS 网关地址（如 http://<你的VPS_IP>:3425）和刚才生成的 sk-magpie-key-...，命名为 vps。
   3. 本地 Magpie 会自动拉取 VPS 上配置的所有模型，命名格式为 vps/供应商/模型名。
   4. 本地的 Claude Code、Codex 等工具在 Agent 页面直接选择 vps/... 模型即可，无需在每台电脑上重复配置 API Key。

8. 08

   网络与生产环境安全强化建议

   将网关部署在 VPS 公网环境时，安全是第一要务：

   • 推荐使用内网组网（Tailscale / WireGuard）：将 Docker 的端口仅绑定在 VPN 虚拟网卡 IP（如 100.x.x.x:3425:3425），彻底杜绝公网端口扫描。
   • 反向代理与 HTTPS：若需公网直连，建议在前端挂 Nginx 或 Caddy 配置 SSL 证书，并用 https://ai.yourdomain.com 访问。并在 Compose 中设置环境变量 MAGPIE_PUBLIC_URL=https://ai.yourdomain.com。
   • 严禁公网暴露 3430 端口：Web 管理页具备修改供应商与导出密钥的全部权限，切勿使用 0.0.0.0:3430 直接暴露到公网。

注意事项

• Magpie 镜像内部使用 nonroot（UID 65532），映射本地目录时注意 chown 属主。
• 外部机器或容器外访问必须携带 Gateway Key，未授权请求会直接返回 401。
• 公网环境务必注意端口防护，建议优先使用 Tailscale 等内网穿透工具或配合 HTTPS 反向代理。

常见问题

相关优惠

• 模型 · QoderQoder 国际版 Qwen3.8-Flash 免费：支持 Magpie 登录接入Qwen3.8-Flash 0 Credits；限免已延期，结束日期待公布
• 模型 · WorkBuddyWorkBuddy 国际版 DeepSeek V4.1 Flash 免费至10月31日，可接 Magpie内置DeepSeek V4.1 Flash 0积分，至2026年10月31日
• 模型 · 硅基流动硅基流动 SiliconFlow 免费 API：翻译、OCR、向量与生图模型价格页标注「免费」的模型调用费用为 0（无总量额度，限速以模型广场为准）
• 新人 · 火山引擎火山方舟新人额度：每模型 50 万 Tokens，支持豆包 API每个模型 50 万 Tokens 免费推理额度（以控制台「开通管理」显示为准）
• 新人 · 阿里云阿里云百炼新人额度：每模型通常 100 万 Tokens，90 天有效每个参与模型通常 100 万 Tokens（输入输出共用），90 天有效；仅北京地域
• 模型 · OpenRouterOpenRouter 免费模型 API：每天 50 次，充值后最高 1,000 次每分钟 20 次；累计充值不足 $10 每天 50 次，累计充值满 $10 每天 1,000 次（每天 00:00 UTC 重置）

信息来源

• Magpie 官方文档 · Docker 部署指南usemagpie.ai/docs/docker
• Magpie 官方文档 · 远程网关（Remote magpie）usemagpie.ai/docs/remote
• Magpie 官方参考手册 · 接口协议与网关秘钥usemagpie.ai/docs/integrate
• Magpie GitHub 官方仓库github.com/yetone/magpie

最后核实日期：2026-10-11 · 政策可能随时调整，请以官方页面为准