OpenSquilla OpenSquilla
文档导航
文档 / Docker 部署

Docker 部署

在一台常开的机器上——家庭服务器、NAS 或小型 VPS——以容器方式运行 OpenSquilla gateway。本页以 Debian 12 作为示例，但任何装有 Docker Engine 的主机的操作方式都相同，amd64 和 arm64 均可。

以下情况适合选择 Docker 安装路径：

  • 主机上没有 Python 3.12+ 工具链（或你不想装一个），
  • 你希望 gateway 在重启后继续存活，并通过拉取新镜像来升级，
  • 你部署在 NAS 或无显示器的服务器上，并从其他设备使用 Web UI。

对于桌面机器，快速开始中的安装方式更简单。

环境要求

安装带有 Compose 插件的 Docker Engine。在 Debian 12 上，按照 Docker 官方说明操作，然后验证：

docker --version
docker compose version

对于预构建镜像路径，主机上不需要其他任何东西——不需要 Python、Git 或构建工具。

使用预构建镜像快速开始

预构建的多架构镜像会针对每个发版 tag 发布到 ghcr.io/opensquilla/opensquilla。不可变的 v0.5.0rc4 tag 对应 Preview 4，而 latest 跟随最近推送的发版 tag，包括预览版和 backport。如果某个 backport 移动了 latest，最新的发版 workflow 会被重新运行以恢复预期的顺序。如果你需要的发版早于镜像发布机制，请改用自行构建镜像。如果拉取失败并报 denied 或 manifest unknown，说明该 tag 的镜像尚未发布（或 package 尚未公开）——请到 package 页面查看可用 tag，或从源码构建。

为部署创建一个目录，并写入以下 compose.yaml：

services:
  gateway:
    # Pin v0.5.0rc4 for reproducibility; latest follows the most recent tag push.
    image: ghcr.io/opensquilla/opensquilla:latest
    environment:
      # In-container bind. Keep it 0.0.0.0 — what the network can reach is
      # decided by `ports` below, not by this value.
      OPENSQUILLA_LISTEN: "0.0.0.0"
      # Token auth is required to administer a containerized gateway through
      # the Web UI, even from the same host. Generate a token with:
      #   openssl rand -hex 32
      OPENSQUILLA_AUTH_MODE: token
      OPENSQUILLA_AUTH_TOKEN: ${OPENSQUILLA_AUTH_TOKEN:?generate one with openssl rand -hex 32}
      OPENROUTER_API_KEY: ${OPENROUTER_API_KEY:-}
      TZ: ${TZ:-UTC}
    volumes:
      # All state — config, session DBs, memory, logs, workspace — lives under
      # /var/lib/opensquilla. The named volume makes it survive recreates.
      - opensquilla-state:/var/lib/opensquilla
    ports:
      # Loopback-only: reachable from this host, invisible to the network.
      # For NAS/LAN access see "Reach the Web UI from Your LAN" below.
      - "127.0.0.1:18791:18791"
    restart: unless-stopped

volumes:
  opensquilla-state:

把这两个密钥放到 compose.yaml 旁边的 .env 文件中（Compose 会自动读取它；请勿纳入版本控制并保持私密：chmod 600 .env）：

OPENSQUILLA_AUTH_TOKEN=<output of: openssl rand -hex 32>
OPENROUTER_API_KEY=<your provider key>

启动：

docker compose up -d
docker compose logs -f gateway

然后在 URL 中带上 token 打开 Web UI：

http://127.0.0.1:18791/control/?token=<your OPENSQUILLA_AUTH_TOKEN>

该 token 会被消费一次并为浏览器 session 存储。首次请求还会把 token 写入 gateway 访问日志，因此请把 docker compose logs 的输出当作敏感信息——或者不带查询参数直接打开 /control/，改为把 token 粘贴到连接面板中。之后在 Web UI 中完成 provider onboarding 与配置——provider 变更会立即生效并持久化到状态 volume 中。

为什么这里的 token 认证不是可选项：容器绑定的是通配地址，因此 gateway 会把每个浏览器——包括同一主机上的浏览器——都视为远程操作者。没有 token 的远程操作者可以聊天，但无法管理配置或 onboarding（只有一小部分安全的运行时开关允许写入）。使用 OPENSQUILLA_AUTH_MODE=token 时，token 会授予 Web UI 管理所需的操作者 scope。请专门使用 token 模式；password 和 trusted-proxy 模式不支持 Web UI 连接。

从局域网访问 Web UI

在无显示器的 NAS 上，你会从其他设备使用 Web UI。两条规则：

  1. 通过修改 ports 条目把端口发布到所有网络接口——不要修改 OPENSQUILLA_LISTEN：

    ports:
  - "18791:18791"

  2. 保持 token 认证已配置（如果你按照快速开始操作，这已经满足）。当 gateway 可从网络访问时，它会发出警告但不会拒绝——是否暴露由你决定，认证则不容商量。

重新创建容器（docker compose up -d），然后在你的设备上打开 http://<server-address>:18791/control/?token=<token>。如果主机运行了防火墙，请仅允许来自局域网的入站 TCP 18791。发往 gateway 的局域网流量是明文 HTTP，因此任何能观测该网络的人都能看到 token——如果你的局域网并非完全可信，请把 gateway 置于 TLS 反向代理之后，或使用下方的 VPN 方案。

不要把 gateway 端口转发到互联网。在家庭之外进行远程访问时，请使用 VPN（WireGuard、Tailscale），或在前面加一层带 TLS 和自身认证的反向代理。安全默认配置参见 gateway.md。

把状态保存在自己的存储上（Bind Mount）

命名 volume 是最安全的默认选择。如果你更喜欢一个由自己管理的目录（RAID 存储、备份工具），可以使用 bind mount——但容器以非 root 的 UID 10001 运行，所以要先把所有权交给它，否则 gateway 会在启动时失败：

sudo mkdir -p /srv/opensquilla
sudo chown -R 10001:10001 /srv/opensquilla
volumes:
  - /srv/opensquilla:/var/lib/opensquilla

所有值得备份的内容都在这一个目录下：config.toml、state/（session 和调度器数据库）、logs/、workspace/、media/，以及可选的 .env。

配置 provider 与密钥

有三种方式，按优先推荐顺序排列：

  1. Web UI——在 /control/ 进行的 provider onboarding 与大多数配置变更会热生效，并持久化到状态 volume 中的 config.toml。Channel、记忆 embedding 与 sandbox 姿态的变更需要重启——Web UI 会标出这些项，运行 docker compose restart gateway 即可应用。
  2. Compose 的 environment——像快速开始那样，按环境变量名传入 provider key。环境值总是优先于 .env 文件。
  3. 状态 volume 内的 .env——gateway 在启动时加载 /var/lib/opensquilla/.env，因此 key 可以在镜像升级后保留，而不出现在 compose.yaml 中。在 bind mount 上，请让它归容器用户所有并保持私密：chown 10001:10001 .env && chmod 600 .env。注意事项：在 compose.yaml 的 environment: 中列出的 key 会遮蔽状态 volume 中的 .env，即使主机变量未设置也是如此（Compose 会把空值传进去）——如果你在状态 volume 中管理它，请把它从 environment: 中移除。

关于认证有一个优先级注意事项：保存到 config.toml 的值——例如通过 Web UI 保存的——在启动时优先于环境变量。如果在通过 Web UI 配置之后 OPENSQUILLA_AUTH_* 变量不再生效，说明 config.toml 现在拥有 [auth] 设置的所有权；请在那里（或在 Web UI 中）轮换 token 并重启。

对 /var/lib/opensquilla/config.toml 的手工编辑只在启动时读取——重启以应用：

docker compose restart gateway

更改发布端口

修改映射的主机侧，容器侧保持 18791 不变：

ports:
  - "127.0.0.1:8080:18791"

设置 OPENSQUILLA_GATEWAY_PORT 不会改变容器入口点的监听端口——端口由上面的映射决定。

健康检查与 CLI 访问

/healthz 无需认证即可回应存活探测，/readyz 在 gateway 完全就绪之前返回 503。镜像自带 healthcheck；可以这样查看：

docker inspect --format '{{.State.Health.Status}}' $(docker compose ps -q gateway)

完整的 CLI 在容器内可用：

docker compose exec gateway opensquilla doctor
docker compose exec gateway opensquilla gateway status

升级与回滚

状态保存在 volume 中，因此容器是可随时丢弃的：

docker compose pull
docker compose up -d

要回滚，请在 image: 中固定上一个发版 tag，然后再次执行 docker compose up -d。固定 tag 加上状态备份，可以让升级和回滚双向都变成日常操作。

自行构建镜像

源码检出中附带相同的 Dockerfile 和一个默认使用自构建 opensquilla:local 镜像的 compose.yaml（可通过 OPENSQUILLA_GATEWAY_IMAGE 覆盖以改用 GHCR 镜像）。构建需要 git、git-lfs 以及 Git LFS 中的 router 资产：

sudo apt install -y git git-lfs
git clone https://github.com/opensquilla/opensquilla.git
cd opensquilla
git lfs pull --include="src/opensquilla/squilla_router/models/**"
docker build -t opensquilla:local .
docker compose up -d

在低功耗或 arm64 的 NAS 上，这个构建会很慢；请优先使用预构建镜像，把源码构建留给开发机器。

如果出现故障

  • docker compose logs gateway 会显示启动错误，包括状态目录不可写（按上文修复所有权）。
  • docker compose exec gateway opensquilla doctor 会报告就绪状态和恢复步骤。
  • troubleshooting.md 中的 Docker 章节涵盖了常见故障：Web UI 无法访问、配置变更被拒绝、bind mount 权限问题，以及与 LFS 相关的构建错误。

文档索引 · 产品指南 · 改进此页面 · 报告文档问题

在 GitHub 上编辑此页(英文原稿) OpenSquilla 文档 · 中文社区翻译