在 Docker 中运行 DisPatch 及我的 AI 工具：一个文件，一条命令

我为自己家运行一个名为 DisPatch 的 AI 聊天应用。直到本月，安装它还需要 Python、虚拟环境以及服务文件。现在它以 Docker 镜像的形式提供，整个设置只需一个文件、一条命令即可在自己的服务器上完成。本页面将一步步指导你从空文件夹开始，最终搭建起可正常使用的聊天系统；其中还包含一个能在本地处理器上运行的小型 AI 模型，让你无需注册任何服务即可试用。

本页面中的所有命令均为我在 2026 年 10 月 19 日实际执行过的操作。我的电脑上并未安装 Docker Desktop，因此我是在 Linux 环境下使用 Podman 5.8 以及 Docker Compose 5.6 来完成操作的。命令本身并无差异；若 Podman 需要额外设置，我会在文末的技术说明部分予以说明。

最终成果展示

Atlas 是新创建的 DisPatch 账号的默认角色。它能回答各类问题；若所使用的模型支持工具调用，它还能执行网页搜索、页面抓取、天气查询、维基百科检索、汇率查询、时间获取以及简单计算等操作。同样的聊天界面也能在手机上打开：

关于 DisPatch 的其他功能（如为家中每位成员创建独立账号、儿童专用界面以及数据备份等），请参阅 DisPatch 3.0 相关介绍。本页面仅侧重于如何成功运行该应用。

第一步：安装 Docker

• Windows 或 Mac： 下载并安装 Docker Desktop，随后启动一次即可。
• Linux： 根据你所用的发行版安装 Docker Engine 及 Compose 插件，亦可参照 Docker 官方说明完成安装。

打开终端（Windows 下为 PowerShell），输入 docker compose version 以验证安装效果。只要显示出版本号，即表明一切准备就绪。

第二步：创建文件夹及配置文件

新建一个名为 dispatch 的文件夹，随后在其中创建名为 docker-compose.yml 的文件，内容如下：

services:
  dispatch:
    image: ghcr.io/laserlloyd/dispatch_chat:main
    ports:
      - "8765:8765"
    volumes:
      - dispatch-data:/data
    restart: unless-stopped
    init: true
    stop_grace_period: 30s

  # 可选：一个能在本地处理器上运行的小型 AI 模型，无需注册任何账号。
  # 若你打算改用 Ollama、LM Studio 或云端服务，可删除此块内容。
  model:
    image: ghcr.io/ggml-org/llama.cpp:server-b11723
    command: ["-hf", "unsloth/Qwen3-4B-Instruct-2507-GGUF:Q4_K_M", "--jinja",
              "--host", "0.0.0.0", "--port", "8080", "--ctx-size", "8192"]
    environment:
      LLAMA_CACHE: /models
    volumes:
      - model-files:/models
    restart: unless-stopped

volumes:
  dispatch-data:
  model-files:

此配置包含两个服务。dispatch 即聊天应用本身。model 则是 llama.cpp 提供的服务器程序；它在首次启动时会自动下载 Qwen3 4B Instruct 模型（大小约 2.5 GB）并保存于本地。dispatch-data 是一个专门用于存储聊天数据的卷，即便后续更新或重启也不会丢失任何内容。

"8765:8765" 这一配置允许局域网内的其他设备访问 DisPatch，非常适合家庭内部使用。若你仅希望本机能够访问，可将其改为 "127.0.0.1:8765:8765"。

第三步：启动服务

进入 dispatch 文件夹后，在终端中依次执行以下命令：

docker compose up -d
docker compose ps

首次启动时会下载所需的镜像及模型文件，因此请耐心等待几分钟。在我的电脑上，DisPatch 在镜像下载完成后约 5 秒即开始响应请求；而模型服务器则在约 20 秒内完成模型的下载与加载。docker compose ps 的输出结果中应能看到两个服务均显示为 Up 状态。

第四步：创建账号

在浏览器中打开 http://localhost:8765。刚创建的 DisPatch 实例在拥有所有者之前处于锁定状态；由于它运行于容器中，系统会要求输入一次性设置令牌。该令牌可从日志中获取：

docker compose logs dispatch | grep "SETUP TOKEN"

若你的系统不支持 grep（如 Windows 环境），可执行 docker compose logs dispatch 并查找以 SETUP TOKEN: 开头的那一行。该令牌在每次 DisPatch 启动时都会发生变化，一旦成功创建所有者账号，此令牌即刻失效。

密码长度至少需为 8 个字符。PIN码为可选设置，用于快速解锁账号。若设置了 PIN码，DisPatch 会生成一条恢复码并将其保存于数据中，此时你务必将该代码妥善记录下来：

docker compose exec dispatch cat /data/RECOVERY-CODE.txt

第五步：连接 AI 模型

设置向导的第二步旨在寻找本地运行的模型服务器。由于 Docker 容器内部无法直接识别 model 服务，因此需手动输入相关信息：

配置项	应填入的内容
类型	OpenAI-compatible
地址	http://model:8080/v1
API 密钥	留空即可
默认模型	unsloth/Qwen3-4B-Instruct-2507-GGUF:Q4_K_M

若想改用云端的模型呢？ 只需在类型栏中选取对应选项并填入相应密钥即可。我曾使用一家兼容 OpenAI 接口的云端服务商进行测试：“Test and save”成功识别出了该服务提供的模型，Atlas 也能正常调用它返回结果。需注意的是，相关密钥信息仅存储于 DisPatch 自身的数据目录中，无需写入 compose 配置文件。

第六步：完成设置并开始使用

后续步骤均较为简单。语音功能属于独立插件，可暂时跳过；“Family”环节则用于添加其他家庭成员（此操作亦可稍后执行）。“Network”环节要求你指定哪些设备能够访问 DisPatch，此处答案应与第二步中所选的端口配置保持一致。

点击 Finish。若刷新页面后依然出现“创建所有者账号”的表单，请再次刷新——这是当前版本的一个显示漏洞（实际上账号早已创建成功，只是旧表单仍停留在屏幕上）。随后在左侧选择 Atlas，点击 + 新建对话并向其提问即可。

若想在同一 Wi-Fi 网络下的手机上使用 DisPatch，只需打开 http://<your computer's address>:8765。至于添加至主屏幕、通知推送以及麦克风功能则需使用 HTTPS 协议，具体实现方式详见文末的技术说明部分。

至此整个设置流程便圆满结束。下文内容仅供你进一步了解系统运作机制、保障数据安全或集成其他相关工具时参考。

各组件如何协同工作

DisPatch镜像以普通用户身份（uid 1000）运行，而非root权限。它产生的所有数据均保存在/data目录下，该目录即对应的dispatch-data卷：其中包括SQLite数据库、上传的文件、头像、设置信息以及每隔六小时自动生成的快照。若仅删除容器则数据不会丢失；唯有删除该卷后所有数据才会消失。

镜像标签main对应DisPatch代码库的main分支。DisPatch代码库中的发布内容包含2026年10月19日的main标签以及每个构建版本对应的sha-<commit>标签；目前尚无以版本号命名的标签。若希望镜像版本保持稳定直至您主动更新，可从包页面选取对应的sha-标签。该镜像同时提供适用于64位Intel/AMD及ARM架构的版本；笔者测试时使用的是Intel/AMD版。

数据安全：备份、恢复与安全更新

首先需停止DisPatch进程以确保数据库数据完整写入，随后将对应卷的内容打包为文件：

docker compose stop dispatch
docker run --rm -v dispatch_dispatch-data:/data:ro -v "$PWD":/backup alpine \
  tar czf /backup/dispatch-backup.tgz -C /data .
docker compose start dispatch

Docker Compose会以文件夹名作为卷的名称，例如名为dispatch的文件夹生成的卷名为dispatch_dispatch-data；通过docker volume ls可查看卷的真实名称。笔者在测试时仅录入少量聊天记录，最终生成的备份文件大小仅为3.7 MB。

若需将数据恢复至新的卷中（笔者曾将备份数据导入新建的DisPatch实例中，该实例同样拥有相同的用户身份且保留了8条聊天记录）：

docker volume create dispatch_dispatch-data
docker run --rm -v dispatch_dispatch-data:/data -v "$PWD":/backup:ro alpine \
  sh -c 'tar xzf /backup/dispatch-backup.tgz -C /data && chown -R 1000:1000 /data'
docker compose up -d

切勿直接从正在运行的容器中复制chats.db文件：在DisPatch进程未终止前，新生成的聊天记录会暂存于同目录下的chats.db-wal文件中。

版本更新操作仅需两条命令即可完成。笔者曾在存有大量数据的实例上依次执行了docker compose down、pull及up -d指令；结果显示用户身份信息及所有聊天记录均完好无损，且系统未生成新的设置令牌。

docker compose pull
docker compose up -d

跨大版本更新前务必先备份数据：DisPatch会在启动时执行数据库迁移操作，旧版镜像可能无法正确读取已完成迁移的数据库。

安全默认设置及需留意的配置项

• 无管理员账户时系统处于锁定状态。在设置向导的第一步完成前，外部网络仅能访问登录页面；创建管理员账户时需使用日志中提供的令牌。
• 未登录访客只能查看受限内容。测试时笔者发现：从未登录过的浏览器也能打开Atlas界面并获取回复。这是DisPatch 3.0的设计机制（访客被视为拥有受限权限的儿童账户，每日仅可接收200条回复），但这些回复实际上仍是通过您的AI服务生成的。若您将DisPatch部署在配有付费云密钥的网络环境中，建议前往“设置→全局设置→用户与资料”页面，将“未登录设备”的访问权限调整为仅显示登录页面。
• 端口访问范围由端口配置决定。"8765:8765"表示整个网络均可访问；"127.0.0.1:8765:8765"则仅限本机访问。容器本身始终会在其所属网络的任意地址上监听请求。
• HTTPS配置由用户自行决定。代码库中的docker-compose.yml文件提供了可选的Caddy代理模块（需启用--profile proxy参数），可借助真实域名与SSL证书实现安全访问；本次测试未涉及该功能。若您自行配置nginx作为反向代理，切记加入proxy_set_header Host $host;指令，否则聊天界面虽能加载但后续内容将无法更新（DisPatch会校验浏览器来源地址是否与Host头信息一致）。
• 模型服务器无需密钥。如前所述，其端口并未对外公开，因此仅DisPatch可与其通信。除非同时为llama.cpp指定了--api-key参数，否则切勿在model配置中添加ports:字段。

关于DisPatch的Docker部署完整指南——包括绑定挂载、用户权限设置以及容器环境下无法正常运作的代理集成方法——请参阅代码库中的docs/deploy-docker.md文档。

其他工具的整合使用

笔者开发的其他工具各自在代码库中配有deploy/compose/compose.yml配置文件。由于这些镜像尚未上传至公共仓库，用户需先克隆对应代码库并添加--build参数方可编译生成镜像。因基础镜像已预先下载完毕，各工具的编译耗时均在一分钟以内。2026年10月19日笔者从GitHub重新克隆代码后，逐一编译并启动了以下工具：

工具名称	功能简介	镜像大小	开放端口	验证情况
DisPatch	聊天应用	已发布版，599 MB	8765	前文所述各项功能均正常运作
MailForge	具备自主发送功能的邮件助手	需编译生成，420 MB	8090	管理界面可正常打开，但尚未绑定任何邮箱账户
InfoForge + kiwix	基于离线维基百科数据的AI问答工具	需编译生成，128 MB；另需下载66 MB的Kiwix数据包	无（Kiwix占用8090端口）	成功运行doctor及search指令，处理对象为大小为23 MB的维基百科数据文件
ThemeForge	主题预览工具	需编译生成，13.8 MB	8185	预览页面可顺利打开
StudioForge	GPU加速模型服务器	需编译生成，568 MB（含Vulkan相关组件）	1234、8080、1235	成功在AMD集成显卡上运行模型服务，详情见后文说明
CrucibleForge	模型性能基准测试工具	需编译生成，129 MB	8777	程序可启动并进入操作界面，但本次未执行实际测试流程
TransForge	静态网站翻译工具	需编译生成	无	本次测试未涉及该工具

上述体积数值为Podman检测到的磁盘占用大小。各工具的compose配置默认仅向127.0.0.1地址开放端口，您可自行修改相关设置以改变此限制。

MailForge

MailForge 使用您设定的密钥环密码来对邮箱密码进行加密；该密码无法恢复，因此请将其保存在密码管理器中。另外，请将 LLM_BASE_URL 指向您自己的模型服务器（下方的 192.0.2.10 即为其地址）。默认情况下，请求会被发送到 Docker 主机上的 1234 端口，任何返回的内容都会被用于响应 MailForge 的请求。

git clone https://github.com/LaserLloyd/MailForge.git
cd MailForge
read -rsp 'MailForge 密钥环密码: ' MAILFORGE_KEYRING_PASSWORD; export MAILFORGE_KEYRING_PASSWORD
LLM_BASE_URL=http://192.0.2.10:1234/v1 \
  docker compose -f deploy/compose/compose.yml up -d --build
docker compose -f deploy/compose/compose.yml logs app | grep "MailForge UI"

日志中会显示类似 http://127.0.0.1:8090/?token=… 的地址，请在浏览器中打开它。

InfoForge与离线版维基百科

从 Kiwix 图书馆中获取一个 .zim 文件，将其放入 deploy/compose/zims/ 目录下。然后在 infoforge.config.yaml 文件中为其命名（该文件可从 infoforge.config.example.yaml 复制而来）。我测试时使用的是一个仅 23 MB 大小的“维基百科化学知识”迷你版 ZIM 文件。

git clone https://github.com/LaserLloyd/InfoForge.git
cd InfoForge/deploy/compose
docker compose up -d kiwix
docker compose --profile cli build infoforge
docker compose --profile cli run --rm infoforge doctor
docker compose --profile cli run --rm infoforge search "稀有气体"

即使完全没有使用任何AI模型，搜索功能也能正常工作：

[1] 惰性气体（评分：19.0，字符数：4222）
[2] 气体（评分：16.0，字符数：1586）
[3] 惰性气体化合物（评分：10.5，字符数：2045）

infoforge ask需要在 base_url 中指定一个模型服务器；使用这个占位地址时，doctor 能通过除“llm primary”之外的所有检查，这也是正确的。

ThemeForge

git clone https://github.com/LaserLloyd/ThemeForge.git
cd ThemeForge
docker compose -f deploy/compose/compose.yml up -d --build

然后打开 http://localhost:8185。

一款GPU模型服务器：StudioForge

StudioForge是我自己开发的模型服务器。它能在显卡上运行各种模型，同时支持多个模型及多个客户端。从2.0版本开始，每个客户端都需要提供拥有者账户和API密钥才能使用。目前该服务器的镜像尚未上传到镜像仓库，因此这一步就是用来构建镜像的。

我原本打算在这里写上“仅支持 NVIDIA”。不过我测试用的迷你主机并没有安装 NVIDIA 显卡，只有搭载在 Ryzen AI 9 365 处理器上的 AMD Radeon 集成显卡。即便如此，我还是构建了 Vulkan 镜像并传入了 GPU 参数，结果一切正常：StudioForge 在首次启动时便从 GitHub 下载了与之匹配的预编译版 llama.cpp 引擎，经过测试后成功以每秒 23 到 28 个词的速度在 GPU 上运行 Qwen3 4B 模型。作为对比，上面提到的仅使用 CPU 的 model 服务在处理同一模型时的速度仅为每秒 22 个词。由此可见，在这款芯片上，GPU 的作用更多在于释放 CPU 资源，而非单纯提升响应速度。

git clone https://github.com/LaserLloyd/StudioForge.git
cd StudioForge/deploy/compose
cp env.example .env
# 在 .env 文件中设置：SF_BACKEND=vulkan，SF_MODELS=/path/to/your/gguf/files，
#          SF_OWNER_PASSWORD（长度至少为10个字符的密码），
#          SF_VIDEO_GID 和 SF_RENDER_GID 的值分别为命令“getent group video render”的输出结果
docker compose -f compose.yml -f compose.vulkan.yml build
docker compose -f compose.yml -f compose.vulkan.yml up -d
docker compose -f compose.yml -f compose.vulkan.yml exec studioforge \
  studioforge keys create --name dispatch --scope inference

最后一个命令会输出一个密钥。控制面板位于 http://localhost:8080（用户名：owner，密码为你自己设置的）。对于 NVIDIA 显卡而言，对应的配置文件是 compose.cuda.yml，同时需要设置 SF_BACKEND=cuda；不过我并未在此处测试该配置路径，而且使用 CUDA 的镜像文件体积要大得多。

DisPatch 与 StudioForge 的配合使用

DisPatch 的代码库中包含 deploy/compose/stack.yml 文件，该文件可让两者在同一网络中启动，并自动完成 DisPatch 对 StudioForge 的连接配置。默认情况下它会尝试拉取尚未公开发布的 StudioForge 镜像，因此你需要将其指向自己刚刚构建的镜像。以下是我添加到 stack.env 中的设置：

git clone https://github.com/LaserLloyd/DisPatch_Chat.git
cd DisPatch_Chat
cp deploy/compose/stack.env.example deploy/compose/stack.env
# 在 deploy/compose/stack.env 中添加以下内容：
#   DISPATCH_IMAGE=ghcr.io/laserlloyd/dispatch_chat:main
#   STUDIOFORGE_IMAGE=ghcr.io/laserlloyd/studioforge:2.0.1-vulkan
#   STUDIOFORGE_MODELS=/path/to/your/gguf/files
#   STACK_MODEL=<StudioForge 列出的模型 ID>
#   SF_OWNER_PASSWORD（即那个长度在10个字符以上的管理员密码）

该配置文件默认会分配一块 NVIDIA GPU 给 StudioForge 使用。若你使用的是 AMD 或 Intel 显卡且希望通过 Vulkan 运行，则需替换为一个小型的替代配置文件 stack-amd.yml：

services:
  studioforge:
    deploy: !reset {}
    devices: ["/dev/dri:/dev/dri"]
    group_add: ["39", "105"]   # 你的显卡与渲染相关用户组编号

docker compose -f deploy/compose/stack.yml -f stack-amd.yml \
  --env-file deploy/compose/stack.env up -d
docker compose -f deploy/compose/stack.yml -f stack-amd.yml \
  --env-file deploy/compose/stack.env exec studioforge \
  studioforge keys create --name dispatch --scope inference

随后按照常规流程完成 DisPatch 的设置向导，进入“设置 → 连接”页面，点击 StudioForge 连接的“编辑”按钮，粘贴刚才生成的密钥并点击“测试”。

所需的模型 ID 可通过 curl -H "Authorization: Bearer <key>" http://localhost:1234/v1/models 命令或 StudioForge 控制面板中的“模型”选项卡获取。如果你的模型文件保存在 Hugging Face 下载目录中，那么模型 ID 就是完整的文件夹路径——虽然较长但确实有效。

注意事项

• 完成设置后需刷新页面。 在我测试的版本中，向导关闭后“创建管理员账户”的表单仍会显示在屏幕上。实际上账户早已创建成功；此时只需刷新页面即可。
• 向导无法自动发现模型。 在 Docker 环境中，DisPatch 的搜索机制仅检查当前容器内容，而不会扫描其他服务。因此需手动输入 http://model:8080/v1。
• 小尺寸模型可能导致异常行为。 使用 Qwen2.5 1.5B 模型时，Atlas 偶尔会输出类似“正在进行网络搜索……”的虚假信息而非调用对应工具。不过使用上述配置中的 4B 版本时，每次天气查询均能正常执行——可见模型规模越大效果越好。
• 仅设置密码时不会生成恢复码。 若只设置了密码而未设定 PIN 码，则不会产生 RECOVERY-CODE.txt 文件；尽管向导中的检查列表提到了该文件的存在。
• 有两个工具默认使用端口 8090。 MailForge 与 InfoForge 自带的 kiwix 服务均默认占用此端口。若需同时运行两者，则需分别设置 HOST_PORT（针对 MailForge）或 KIWIX_PORT（针对 kiwix）。
• StudioForge 首次启动需要 GitHub 访问权限。 它会通过 GitHub API 下载 llama.cpp 引擎，而该服务对匿名请求的限制为每小时每 IP 60次。我第一次尝试时便触及了此限制；此时精简版 Vulkan 镜像转而尝试从源码编译引擎——但因其内部缺少 git 工具而导致失败，最终返回 can_serve: false 的状态。待访问限制重置后重启即可恢复正常。根据 StudioForge 自身的日志提示，在 .env 文件中设置 GITHUB_TOKEN 可提升此限额。
• docker compose down -v 会删除所有聊天记录。 仅使用 down 命令则不会造成此后果。
• Podman 用户注意事项： 在 Fedora 等启用了 SELinux 的系统中，需在备份文件夹挂载参数后添加 :z（例如 "$PWD":/backup:z）。此外 Podman 配合 Docker Compose 运行时，若 compose 文件中健康检查部分缺少 test: 字段则会报错（“必须定义健康检查命令”），此时需另外创建一个覆盖文件并补充相应指令。无 root 权限下运行 kiwix 服务时还需设置 KIWIX_USER=0。使用 Docker 的用户可忽略此条说明。

未进行测试的项目

• Windows 或 Mac 平台上的 Docker Desktop。我仅在 Linux x86-64 环境下通过 Podman 与 Docker Compose 完成了测试。
• 在同一台计算机上于 Docker 环境外运行的 Ollama 或 LM Studio。在 Docker Desktop 环境下，Ollama 的访问地址应为 http://host.docker.internal:11434/v1，且该服务器必须允许来自容器的连接；不过这一点我尚未验证。
• StudioForge 的 NVIDIA 与 ROCm 专用镜像、带语音功能的构建版本（需设置 VOICE=1）、Caddy HTTPS 配置以及 TransForge 工具。
• InfoForge 中借助模型执行 ask 操作的情况，以及 CrucibleForge 的基准测试流程。

GitHub 上的 DisPatch 项目 StudioForge MailForge InfoForge

相关链接：DisPatch 3.0：家庭配置档案与设置向导、DisPatch、StudioForge，以及如何让 LLM 自动适配各类项目需求。