文档 · 服务器

在 Docker 里运行 magpie

在没有桌面的服务器或 NAS 上运行 magpie：它的网关为其他电脑上的 Agent 提供模型，供应商的添加和订阅登录都在浏览器页面里完成。

镜像里是 magpie 的纯终端版本，基于 distroless，并带了 bash 和 busybox，方便在容器里开终端。不指定命令时运行 magpie serve（只有网关）。容器里找不到需要配置的 Agent，所以这里的 magpie 是一个网关：用它的 Agent 运行在别的机器上。

运行

带 Web 界面运行，给页面一个重启后不变的 key，两个端口都只发布在宿主机的回环地址上：

docker run -d --name magpie --restart unless-stopped \
  -p 127.0.0.1:3425:3425 -p 127.0.0.1:3430:3430 \
  -e MAGPIE_WEB_KEY=$(openssl rand -hex 16) \
  -v magpie-config:/config \
  ghcr.io/yetone/magpie:latest web --addr 0.0.0.0:3430 --no-open

docker logs magpie

日志里给出带 key 的页面地址：

● magpie web on http://127.0.0.1:3430/?k=0f3c9a1e…
  on the network http://172.17.0.2:3430/?k=0f3c9a1e…
  these are the container's own addresses: other machines use the host's, and MAGPIE_PUBLIC_URL=http://<host>:<port> puts it here
! anyone with the link can change magpie and see its keys, and the network carries it unencrypted
  the link carries MAGPIE_WEB_KEY · gateway http://127.0.0.1:3425 · Ctrl-C to stop

不加 web --addr 0.0.0.0:3430 --no-open 时容器只跑网关，需要在容器终端里配置（docker exec -it magpie magpie provider add …）。也可以把一个目录绑定挂载到 /config 来代替命名卷，前提是 uid 65532 能写它：sudo chown -R 65532:65532 /volume1/docker/magpie/config。

Web 界面

打开日志里的链接。链接里的 key 会换成一个 cookie，并从地址栏里去掉；不带 key 打开会被拒绝（401）。设置了 MAGPIE_WEB_KEY（16 个以上的字母、数字或 - . _ ~；openssl rand -hex 16 可以生成一个）时，重启后 key 不变，浏览器保持登录 400 天。不设置时每次启动都会生成新 key，cookie 只在本次浏览器会话里有效。

这个页面处于网关模式：只有 供应商、网关、路由、用量、插件和 设置，没有 Agent、会话和资源库，因为容器里没有 Agent。设置 → 常规 → 网关模式 可以关掉它。

NAS 或通过 SSH 访问的服务器上，用隧道打开页面，不要发布 3430：ssh -L 3430:127.0.0.1:3430 you@nas，然后在自己电脑上打开日志里的链接。

登录订阅

在 供应商 里添加 API key，和桌面版一样。订阅登录（ChatGPT、Claude……）会在你的浏览器里打开厂商页面，完成后厂商把浏览器跳回 localhost，ChatGPT 是 http://localhost:1455/auth/callback?code=…。那是你自己的电脑，不是容器，所以页面打不开。把地址栏里的完整地址复制下来，粘贴到登录的 回调 URL 一栏。

在终端里也可以：

docker exec -it magpie magpie accounts add codex

打开它打印的链接并登录，再把浏览器最后停在的地址粘贴回去。Web 界面也能从文件导入登录。

保存了什么

magpie 写的所有东西都在 /config 下，所以重启、或者在同一个数据卷上新建容器，供应商、密钥、登录和插件都还在。

旧镜像创建的数据卷照样能用：magpie 启动时会补上缺的目录。只有用旧镜像做的登录（当时存在数据卷之外）需要重新登录。

环境变量

网关密钥与其他机器

1. 给每个客户端生成一个密钥网关 → 网关密钥，或在终端里 docker exec magpie magpie gateway-key add "Laptop"，它会打印新的 sk-magpie-key-…。容器外的每个请求（包括宿主机自己的）都必须带一个启用的网关密钥，不带的返回 401。每个密钥可以有自己的每日、每周或每月上限和可用模型（magpie gateway-key limit、magpie gateway-key models）。
2. 发布端口用 -p 3425:3425（或绑定到 NAS 的局域网或 VPN 地址，-p 192.168.1.20:3425:3425）并加上 -e MAGPIE_PUBLIC_URL=http://192.168.1.20:3425 重新创建容器。

在其他电脑上，把 Agent 指向这个网关，用其中一个密钥作为 API key：OpenAI 客户端用 http://192.168.1.20:3425/v1，Anthropic 或 Gemini 客户端用 http://192.168.1.20:3425。模型 id 是 provider/model 或路由组的名字，GET /v1/models 会列出它们。如果那台电脑自己也运行 magpie，就把容器添加为远程 magpie，由 magpie 替你配置 Agent。

容器里不需要打开 设置 → 局域网共享：打开它会另外生成一个名为 Magpie 的网关密钥，而不论开关如何，网关都会向容器外的请求要密钥。

从旧镜像升级。容器外发送 magpie 或其他非启用网关密钥的 Agent，现在会收到 401（“the API key sent is not an enabled magpie gateway key”）。按上面的步骤给它生成一个密钥，填进 Agent 的设置。已经发送网关密钥的 Agent，以及用网关密钥添加的远程 magpie，照常工作。

在 NAS 上用 Docker Compose

services:
  magpie:
    image: ghcr.io/yetone/magpie:latest
    restart: unless-stopped
    ports:
      # 127.0.0.1：只在宿主机上；容器外的每个调用方都需要网关密钥
      - "127.0.0.1:3425:3425"
      - "127.0.0.1:3430:3430"
    environment:
      MAGPIE_PUBLIC_URL: http://<nas-address>:3425
      MAGPIE_WEB_KEY: <random-key>
    volumes:
      - ./config:/config
    command: [web, --addr, 0.0.0.0:3430, --no-open]

然后：sudo chown -R 65532:65532 ./config，docker compose up -d，通过 SSH 隧道打开 http://127.0.0.1:3430/?k=<random-key>，添加供应商，给每台机器生成一个网关密钥。要让其他机器访问网关，把它那一行改成 "3425:3425"（或 NAS 的局域网、VPN 地址），重新 docker compose up -d。

健康检查、终端与更新

• 健康检查。镜像带 HEALTHCHECK：网关能应答时 magpie healthcheck 返回 0，serve 和 web 都一样，所以 docker ps 会显示 healthy，Compose 可以用 depends_on: condition: service_healthy 等它。
• 终端。docker exec -it magpie bash 或 NAS 面板里的终端会打开一个 shell，magpie 在 PATH 里：magpie providers、magpie models、magpie usage、magpie quota 以及其他 CLI 命令。
• 更新。拉取新镜像，在同一个数据卷上重新创建容器：docker pull ghcr.io/yetone/magpie:latest，然后 docker rm -f magpie 再执行同样的 docker run；或 docker compose pull && docker compose up -d。
• 自己构建。在仓库的检出目录里 docker build -t magpie . 得到同样的镜像。

遇到问题，或者有值得分享的配置？来 Discord 聊。细节见参考文档（英文）。