跳转至正文
ColliePWA

01/Documentation

安装 Collie

系统要求、两种安装方式（全新安装或通过 Herdr 安装）、首次运行以及在手机上打开

主机要求、两种接入方式与首次运行配置。请先阅读 安全性：Collie 按设计会向外暴露机器的远程 shell 访问权限。

环境要求

支持的主机环境：Linux 和 macOS。Windows 处于实验阶段；请参阅 Windows。

工具适用场景用途
curl、tar、sha256 工具（sha256sum/shasum）二进制安装脚本与更新下载并校验发布归档包。
Bun源码构建运行 bridge 并构建 Web UI。
git源码构建与 Herdr 路由克隆并更新代码仓库。
多路复用器：Herdr、tmux 或 zellij所有安装方式镜像后端通过 COLLIE_MUX 设置。tmux 和 zellij 在 1.0 中为实验性功能；请参阅 将 Collie 指向多路复用器 和 MUX_CONTRACT.md。
Herdr ≥ 0.7.0仅限 Herdr 后端当 COLLIE_MUX=herdr 时必需。使用 herdr --version 检查。
Tailscale默认访问方式tailscale serve 将 Collie 代理到你的 tailnet。如果使用 变体 C 则为可选。
注意。 未强制要求 tmux 或 zellij 的最低版本。适配器已在 tmux 3.4、tmux 3.6b 和 zellij 0.44.2 上进行过测试。处理了一个 tmux 极端情况：在使用 window-size manual 的服务器上，低于 3.7 版本的 tmux 在创建窗口时会崩溃，因此 Collie 会拦截该请求并提示你运行 tmux set -g window-size latest。

软依赖项，仅旁注的功能需要：

工具适用场景
Node.js在日志中格式化 MagicDNS 名称。
systemd / launchd服务监管；回退到 nohup。
web-push可选，参见 Web Push。

安装

三种接入方式：

Herdr 是 Collie 可以镜像的三种多路复用器之一，不是程序的依赖项。镜像哪一个是此步骤之后的环节。

全新安装

安装脚本将最新版本下载到 ~/.local/share/collie（COLLIE_DIR）并将二进制文件链接到 ~/.local/bin/collie：

curl -fsSL https://colliepwa.dev/install.sh | sh

它会获取最新的稳定版本，且不会改动已存在的安装，改动已有安装请使用 collie update。规范来源是仓库中的 scripts/install.sh：一页 POSIX sh 脚本，且绝不需要 sudo。

curl -fsSL https://raw.githubusercontent.com/AltanS/collie/main/scripts/install.sh | less
curl -fsSL https://raw.githubusercontent.com/AltanS/collie/main/scripts/install.sh | sh

如果 ~/.local/bin 不在 PATH 中，直接运行二进制文件：

~/.local/share/collie/current/bin/collie version

固定版本或修复现有安装（参见 当 collie 无法运行时）：

curl -fsSL https://colliepwa.dev/install.sh | COLLIE_TAG=v1.0.0 sh

对于预发布版本，传入 --beta：它会采用最新的预发布版本，然后安装会跟踪该主版本的预发布版本，直到最终版本发布（预发布版本）。

从源码构建的相同结果

# 1. Clone and checkout latest stable tag
git clone https://github.com/AltanS/collie.git ~/.local/share/collie
cd ~/.local/share/collie
git checkout --detach "$(git tag --list 'v*' | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -1)"

# 2. Build runtime and UI
bash scripts/collie-ctl.sh build

# 3. Verify
bin/collie version

# 4. Optional: link to PATH
bin/collie link

然后启动它。start 会创建 ~/.config/collie/ 并将你的多路复用器选择写入其 .env，因此无需预先手动配置：

bin/collie start

通过 Herdr

先启动 Herdr 服务端（herdr 或 herdr server &）。

从 GitHub：

herdr plugin install AltanS/collie
herdr plugin action invoke start --plugin herdr.collie

从本地源码：

git clone https://github.com/AltanS/collie.git && cd collie
herdr plugin link "$(pwd)"
herdr plugin action invoke start --plugin herdr.collie

通过 Herdr 操作 管理。对于预发布版本，使用 herdr plugin install AltanS/collie --ref <tag> --yes 安装该标签，这就是全部的加入操作（预发布版本）。

通过包管理器安装

如果 Collie 已为你所用的系统打包，按平时的安装方式安装即可。该软件包包含发布版本已提供的编译二进制文件，因此你的机器上不会构建任何内容：无需 Bun，无需 git，无需编译。整个发布版本目录落在一个前缀路径下，并通过 PATH 上的 collie 软链接指向该目录。

软件包不是 Herdr 插件，无论哪种方式，PATH 上的每个 collie 动词都以相同方式工作。要在 Herdr 中获取 Collie 的按钮，请将安装目录树链接一次：

herdr plugin link /opt/collie

Herdr 不会扫描 /opt，因此它绝不会自行找到该软件包。插件的 update 和 update-major 操作随后会拒绝执行并改为提示你的包管理器名称。这是正常的，并非错误：该目录树应由你的包管理器负责更新。

Arch

collie-bin 尚未进入 AUR。AUR 暂停了新账号注册，待注册重新开放后，我们将通过自己的账号发布该软件包。在此之前，请通过克隆此仓库进行构建：

git clone https://github.com/AltanS/collie.git && cd collie/packaging/aur
makepkg -si
collie start

makepkg 会下载适用于你架构的发布版本 tarball，根据发布的完整性清单校验其 sha256，并解压。无需 Bun，无需克隆任何其他 git，无需编译。

进入 AUR 后，AUR 助手会安装相同的 PKGBUILD：

paru -S collie-bin     # or: yay -S collie-bin
collie start

后续更新使用 paru -S collie-bin 或 yay -S collie-bin，即你安装时使用的相同命令。sudo pacman -Syu collie-bin 仅在有仓库收录该软件包时有效，例如 Omarchy 的仓库。

该软件包将发布目录树安装到 /opt/collie，并将 /usr/bin/collie 作为符号链接指向其中。README.md、CHANGELOG.md 和 docs/ 放入 /usr/share/doc/collie-bin/，许可证放入 /usr/share/licenses/collie-bin/。它提供并冲突于 collie，因此它与未来的源码包无法同时安装。它不会启用任何 systemd unit：collie start 会像在任何安装后一样写入你自己的 --user unit。

注意。 每次升级后请运行 collie restart。pacman 会替换文件但不会重启任何服务，因此服务会继续基于已删除的二进制文件运行旧构建，直到你将其重启。collie doctor 将其报告为 restart-pending，手机端会显示 "Collie was replaced on disk. Restart it." 以及需要运行的命令。

通过以下三个步骤卸载：

collie uninstall
herdr plugin unlink herdr.collie   # only if you linked it
sudo pacman -Rns collie-bin

collie uninstall 会停止服务、删除 systemd --user unit 并卸载 Collie 自身的 tailscale serve 映射；pacman 随后仅删除 /opt/collie 和 /usr/bin/collie，不删除其他内容。你自己的两个目录会保留，想要清除时可手动删除：~/.local/state/collie/（或 $COLLIE_STATE_DIR）下的状态目录，以及存放 .env 的配置目录（在装有 Herdr 的主机上为 ~/.config/herdr/plugins/config/herdr.collie/）。

Omarchy

sudo pacman -S collie-bin
COLLIE_MUX=herdr collie start

Omarchy 同时内置了 tmux 和 Herdr，而 Collie 每次安装仅镜像一个复用器，因此首次启动必须指定要驱动的那一个——它拒绝在看到的两个复用器之间进行猜测。start 将该名称写入 Collie 的 .env（在装有 Herdr 的主机上为 ~/.config/herdr/plugins/config/herdr.collie/.env），后续启动只需执行 collie start。

当 collie-bin 进入 Omarchy 自己的软件包仓库后即可这样操作，目前添加它的 pull request 尚未合并。在此之前，请像上面针对任何 Arch 主机那样，在 packaging/aur 中使用 makepkg -si 构建相同的软件包。

后续更新直接使用 sudo pacman -Syu（即你平时用来更新机器的命令）完成——无需 AUR 助手，因为 pkgs.omarchy.org 是一个真正的 pacman 仓库。无论哪种方式，其 PKGBUILD 和 /opt/collie 布局都完全相同。

注意。 更新来自你的包管理器，Collie 在此环境下不会自行更新。collie update 会拒绝执行。手机端的更新横条会显示 "Collie x.y.z available via pacman."，Updates 页面会显示可复制的命令来替代更新按钮，因为该目录归包管理器所有。Collie 会提示 sudo pacman -Syu collie-bin 形式（即仓库命名写法）；在 AUR 安装中请改用你的 helper。升级后请运行 collie restart，原因如上所述：pacman 不会重启任何服务。

在 pack 中，此机器绝不会通过手机接收更新：pack 会将其列为“等待包管理器”，只有当你在该机器上运行 helper 时它才会同步到最新版本。

按照上面针对 Arch 的相同三个步骤进行卸载。

Nix

nix profile install github:AltanS/collie#collie
collie start

该 flake 为 x86_64-linux、aarch64-linux 和 aarch64-darwin 导出了 packages.<system>.collie。它根据发布版本自身完整性清单中的 sha256 获取对应平台的发布版本 tarball，在 Linux 上为二进制文件的解释器打补丁，并将发布版本目录树安装到 <store-path>/lib/collie，同时创建指向它的软链接 bin/collie。无需安装，直接运行一次：nix run github:AltanS/collie#collie -- doctor。

这里特意没有提供源码构建：安装依赖需要网络，而 Nix derivation 无法访问网络，因此该软件包直接封装了发布版本已经发布并附带校验和的二进制文件。

目前还没有 NixOS 模块，只有 flake 软件包，因此途径是 nix profile：按上述方式将其安装到你的 profile 中，或者自行将 flake output 添加到 home-manager 或 environment.systemPackages 列表中。

注意。 更新来自 nix，Collie 在这里不会自行更新。collie update 会拒绝并提示 nix profile upgrade collie，手机端会在原本显示更新按钮的位置展示新版本以及该命令。

在 pack 中，此机器绝不会通过手机接收更新：pack 会将其列为“等待包管理器”，只有当你在该机器上运行 nix 时它才会同步到最新版本。

先使用 collie stop 移除它，然后：

nix profile remove collie

这只会从你的 profile 中移除 store 路径，不会删除其他任何内容。你自己的文件会保留：位于 ~/.local/state/collie（或 $COLLIE_STATE_DIR）的状态、位于 ~/.config/collie 的配置，以及由 collie start 写入位于 ~/.config/systemd/user/collie.service 的 systemd --user 服务单元。在移除软件包之前运行 collie uninstall 可以清除该服务单元和端口映射。

mise

mise use -g github:AltanS/collie@1.5.6
collie start

mise use -g 会将工具写入 ~/.config/mise/config.toml，并将发布版本的 bin/ 放入你的 PATH。github 后端会拉取该平台的发布版本 tarball，因此这在 Linux 和 macOS 上均可运行，无需 Bun，无需编译。整个目录树均置于 ~/.local/share/mise/installs/github-altan-s-collie/<version>/ 下，包含 web/dist 和 herdr-plugin.toml，collie 从该位置解析其自身的根目录。

使用相同的 mise use 行配合更新的 tag 获取新版本，或者让 mise 选择最新版本：

mise upgrade --bump github:AltanS/collie
collie restart

--bump 是关键的 flag。固定的 1.5.6 是一个单值范围，因此直接执行 mise upgrade 会报告工具已是最新且不会移动任何内容。

重启是必须的。每个版本都有自己的目录，并且 collie start 会将运行它的目录固定写入服务定义中，因此服务会继续从旧目录运行旧版本，直到你将其重启。collie restart 会使用新路径重写该定义：Linux 上为 systemd --user unit，macOS 上为 ~/Library/LaunchAgents plist。两端均为同一命令。

注意。 仅通过 SSH 管理的 Mac 没有用于加载 agent 的 gui/<uid> 域。在此情况下 collie start 会给出提示并改为运行不受监管的后台桥接，故障时不重启，登录时不自启。collie restart 仍会将其迁移到新目录。
注意。 collie update 在此会被拒绝，并且不会提示包管理器名称：它会显示 cannot tell how this Collie was installed。mise 目录树位于你的 home 目录下，自身不带 .git，上方也没有 versions/ 布局，因此 Collie 既不将其视作代码检出，也不视作软件包。在此安装中，mise 负责更新，通过上述两条命令完成版本迁移。

先使用 collie uninstall 移除它，然后：

mise uninstall github:AltanS/collie@1.5.6
mise unuse github:AltanS/collie

uninstall 会删除该版本的目录，unuse 会从配置中移除该行。两处均需使用工具的完整 github: 名称；简短的 collie 仅适用于 upgrade，不适用于 uninstall。你自己的文件会保留：~/.local/state/collie（或 $COLLIE_STATE_DIR）中的状态，以及 ~/.config/collie 中的配置。

PKGBUILD、Nix 表达式及其说明位于此仓库的 packaging/ 中。macOS 目前没有专门的软件包；aarch64-darwin flake output 是最接近的替代方案。

指定你的多路复用器

Collie 镜像一个后端：COLLIE_MUX=herdr（默认）、tmux 或 zellij。

注意。 你无需预先设置它。

首次 start 会查找活动的 Herdr 套接字、运行中的 tmux 服务和 zellij 会话，输出找到的内容，并将你的选择写入配置 .env（若不存在则创建）。在没有终端可供询问时，它会采用唯一找到的后端并显示其名称；若未找到或找到多个，它会拒绝启动并指明 COLLIE_MUX。

若要在启动前确定，请在首次启动 之前 预置该文件。独立运行时为 ~/.config/collie/.env，或为 herdr plugin config-dir herdr.collie 输出的路径：

mkdir -p ~/.config/collie
cp .env.example ~/.config/collie/.env

然后设置后端及其端点：

COLLIE_MUX=tmux                                           # or: zellij
# zellij instead: COLLIE_MUX_ENDPOINT_ZELLIJ=<session>
COLLIE_MUX_ENDPOINT_TMUX=/run/user/1000/collie-tmux.sock
注意。 启动后不要运行该 cp：它会把 .env.example 覆盖写入启动时刚生成的 COLLIE_MUX 上。

之后编辑该文件。参见 将 Collie 指向多路复用器。

启动它

herdr plugin action invoke start --plugin herdr.collie   # Herdr-managed
bin/collie start                                         # standalone

start 将会：

  1. 若缺失则构建 web/dist。
  2. 在 systemd --user（或 launchd/nohup）下启动 bridge。
  3. 运行 tailscale serve --bg 8787（HTTPS :443 → 127.0.0.1:8787）。你的 tailnet 需要为此启用 HTTPS（admin console → "Enable HTTPS"）；Collie 会给出提示，若未启用则会停止运行。
  4. 输出连接提示信息。

首次运行效果

bin/collie start 的输出（Herdr 运行会返回 JSON；使用 herdr plugin log list --plugin herdr.collie 查看日志）：

$ bin/collie start
building web UI (first run)…                    # linked clone only; a GitHub install already built
…bun install · typecheck · vite build output…
bridge started (systemd --user: collie)
tailscale serve (https) → tailnet :443 -> 127.0.0.1:8787

  ✓ Collie is running  ·  v1.0.0+b158755
    service   systemd --user (collie) · active
    local     http://127.0.0.1:8787
    tailnet   https://myhost.tail1234.ts.net

若健康检查失败（⚠ Collie isn't answering on :8787 yet），参见 问题排查。

stop 停止服务；uninstall 移除服务和代理。该 bridge 作为 systemd --user 服务运行（在 macOS 上为 launchd agent），登录时启动并在失败时重启（ARCHITECTURE.md §3）；在 Linux 上，loginctl enable-linger $USER 使其在重启后依然保留（在系统重启后保持运行）。

在 配置 中配置用户访问权限，并通过 配对 配置设备访问权限（bin/collie pair）。

在手机上打开

从横幅中打开 tailnet URL（可随时通过 bin/collie url 获取，或使用 bin/collie qr 生成二维码）。您的客户端必须处于同一个 tailnet 中。

  1. 配对该设备：在主机上运行 bin/collie pair。扫描输出的二维码以在客户端上打开“Settings → Paired devices”并自动填入配对码，或者在客户端上手动打开“Settings → Paired devices”并输入该配对码（配对设备）。
  2. 安装 PWA：在 Safari (iOS) 或 Chrome (Android) 中点击 添加到主屏幕。

安装 PWA 需要 HTTPS；COLLIE_SERVE_MODE=http 会禁用 service worker，因此在该模式下手机只能使用浏览器标签页。

它是否正常运行？

验证状态和日志：

$ bin/collie status

  ✓ Collie is running  ·  v1.0.0+b158755
    service   systemd --user (collie) · active
    local     http://127.0.0.1:8787
    tailnet   https://myhost.tail1234.ts.net

  serve config:
    https://myhost.tail1234.ts.net (tailnet only)
    |-- / proxy http://127.0.0.1:8787
$ bin/collie logs        # journal timestamps trimmed here
[push] disabled (no VAPID keys configured)
[bridge] listening on http://127.0.0.1:8787  (poll 1500ms)
[bridge] WARNING: COLLIE_TRUSTED_USER is empty — any tailnet device/user that reaches the bridge gets full write access. Set it to your tailnet login (see README → Variant A).

若要限制访问，请在 .env 中设置 COLLIE_TRUSTED_USER=you@example.com 并运行 bin/collie restart（配置）。若仪表盘内容缺失，请参阅 问题排查。

保持更新

单条命令即可更新当前主版本。

herdr plugin action invoke update --plugin herdr.collie   # Herdr-managed
bin/collie update                                         # standalone

更新适用于当前主版本；跨越主版本需要使用 collie update --major，或者在 Herdr 管理的安装上使用 update-major 操作。有关此内容、回滚和卸载，请参见 管理与更新。

在 GitHub 上编辑本页

The rest of the documentation