SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

如何在 VPS 上自托管 KiroCrew 并保持代理常驻

使用 Docker 和 systemd 在 VPS 上运行 KiroCrew gateway,持久化记忆与计划任务,支持 SSH 访问、备份及升级失败后的回滚。

为什么应在 VPS 上自行托管 KiroCrew,而不是在笔记本电脑上

只有永不休眠的机器才能充分发挥自行托管 KiroCrew 的价值,因此 VPS 是合适的运行环境,笔记本电脑则不是。KiroCrew 会将会话历史、语义记忆、计划任务和审批队列保存到磁盘,并在进程重启后重新加载这些数据。如果计划任务在 03:00 到期时进程没有运行,这些数据都无法发挥作用;而合上的笔记本电脑不会运行该进程。

KiroCrew 是 Kiro 团队推出的开源代理工作区,采用 Apache 2.0 许可证,0.1.0 于 2026 年 7 月 22 日发布。一个称为 gateway 的进程负责保存状态,并在 5476 端口提供 Web 控制面板。您可以通过控制面板、kirocrew CLI,或 Slack 等聊天渠道访问 gateway。您自行托管的只有 gateway,因此本指南重点介绍如何让它持续运行、避免将其暴露到公网,以及在升级失败后如何恢复。

开始前需要了解两点。自 0.11.0 起,没有保存 harness 选择的新 KiroCrew 安装默认使用 KAS,无需 kiro-cli;已有的显式 Kiro CLI 选择会保留。Kiro 后端上的推理使用您的 Kiro 计划,因此截至 2026 年 11 月 1 日,此默认配置并非离线运行。该项目也较新,迭代速度很快:稳定版本从 2026 年 8 月 5 日的 0.1.3 发展到 2026 年 10 月 25 日的 0.10.0;期间还发布了 10 月 9 日的 0.8.0 和 10 月 16 日的 0.9.0,而 0.11.0 候选版本已于 10 月 25 日作为预发布版本提供。请假设您迟早需要回滚,并采用支持回滚的安装方式。如果您以前没有在服务器上运行过代理,在 VPS 上运行编码代理介绍了本指南所依赖的基本原则。如果您对代理侧的了解少于服务器侧,建议先了解代理循环、工具和记忆的实际含义,这样下面的选择会更容易理解为配置决策,而不是照搬命令。

KiroCrew 的依赖项及其状态数据位置

原生安装需要 Python 3.12 或更高版本。如果从源代码构建仪表板,还需要 Node.js 22.12.0 或更高版本(项目推荐使用 Node 24 LTS)。Kiro CLI 后端需要 kiro-cli,并使用 kiro-cli login 完成身份验证;自动化使用时,也可以使用 API 密钥。自 0.10.0 起,内置 KAS 引擎无需安装 kiro-cli 即可运行;0.11.0 将其设为新安装的默认引擎,前提是没有保存的 harness 选择。容器安装不要求主机具备上述依赖,只需要 Docker。这是优先选择容器安装的主要原因。

状态数据位于 ~/.kiro/crew,KIROCREW_HOME 环境变量可将其迁移到其他位置。该目录包含:

  • config.json:网关设置和聊天渠道凭据。
  • .env:机密信息。
  • workspace/memory/:偏好设置、项目笔记和聊天历史记录。
  • memory.db 和 memory_index.db:语义索引和全文索引。
  • models/:首次运行时下载的嵌入模型。
  • security_events.jsonl:安全事件日志。

该目录就是整个安装。将其复制到新的 VPS,即可迁移代理。因此,下面的备份部分比安装部分更重要。

应优先规划磁盘空间,而不是 RAM。网关是一个 Python 进程;真正占用主机资源的是代理运行的任务、构建过程或测试套件。状态目录会随着聊天历史记录增长,嵌入模型也会在首次启动时下载。因此,运行数周后,使用 du -sh ~/.kiro/crew 在自己的主机上测量实际占用量,不要依赖项目早期发布的任何容量数据。相比之下,另一类运行时会为每个工作进程分配独立的容器和浏览器。在这种情况下,自行托管 OpenBot 的 AI 协作者 时,首先需要考虑的是 RAM,而不是磁盘空间。

应使用四种安装方式中的哪一种

该项目提供四种方式:桌面应用、单行安装程序、源码和 Docker。单行安装程序会下载一个 wheel,并创建 kirocrew 启动器;如果其目录不在 PATH 中,安装程序会输出将该目录加入 PATH 的说明:

curl -fsSL https://download.crew.kiro.dev/cli.sh | sh

它接受 channel 标志和 version 标志:

curl -fsSL https://download.crew.kiro.dev/cli.sh | sh -s -- --channel insider
curl -fsSL https://download.crew.kiro.dev/cli.sh | sh -s -- --version 0.8.0

容器镜像发布在 ghcr.io/kirodotdev/kirocrew,每个标签都包含 linux/amd64 和 linux/arm64。源码构建需要 git clone 和 make build,适用于修改代码的人员,不适用于运行程序的人员。

请使用容器。原生源码安装会将 Python 软件包和 Node 安装到运行其他服务的同一台主机上;使用 Kiro CLI 后端时还会安装 kiro-cli。因此,升级失败后,你需要手动清理这些变更。容器将运行时集中在一个镜像中,将状态集中在一个卷中。这样,回滚只需更换标签并重启即可。

将镜像固定到发布标签,而不是固定到 stable

项目自身的示例使用 stable 标签:

docker run -d --name kirocrew \
  -p 127.0.0.1:5476:5476 \
  -v kirocrew-home:/home/kirocrew \
  ghcr.io/kirodotdev/kirocrew:stable

stable 是一个会移动的标签,latest 也是如此,它们指向同一版本。该标签始终指向当前最新的稳定版本,因此下一次拉取可能在未经过您选择的情况下更改正在运行的版本,而且标签本身无法记录实际使用的是哪个版本。版本标签不可变,因此应固定到版本标签。截至 2026 年 11 月 1 日,最新的稳定版本是 0.11.1。该版本于 2026 年 10 月 31 日发布,用于修复 0.11.0 中的内存完整性和 KAS 问题。下面的 0.8.0 示例使用 Kiro CLI。此外还有 insider 和 nightly 标签;nightly 跟随来自 main 的构建。

写入 /opt/kirocrew/compose.yaml:

services:
  kirocrew:
    image: ghcr.io/kirodotdev/kirocrew:0.8.0
    container_name: kirocrew
    restart: unless-stopped
    ports:
      - "127.0.0.1:5476:5476"
    volumes:
      - kirocrew-home:/home/kirocrew

volumes:
  kirocrew-home:

启动后,检查镜像自身用于 HEALTHCHECK 的健康检查端点:

cd /opt/kirocrew
docker compose up -d
docker compose ps
curl -s http://127.0.0.1:5476/api/health

docker compose ps 应在大约 1 分钟内将容器报告为健康,/api/health 无需令牌即可响应(/api/live 和 /api/ready 也是如此,这使它们可以用作探针)。如果状态保持为 starting,请先读取 docker logs kirocrew,再进行任何更改。首次运行时会在后台下载嵌入模型;模型下载完成前,内存搜索使用关键字匹配。

使用 systemd 保持服务运行

restart: unless-stopped 会在容器崩溃或系统重启后恢复容器,前提是 Docker 本身会在启动时运行。单元文件可以明确声明这一依赖,并提供一条命令,在备份前停止整个服务栈。在启动时运行 Docker Compose 服务栈介绍了一般模式。下面是 KiroCrew 在 /etc/systemd/system/kirocrew.service 中的配置方式:

[Unit]
Description=KiroCrew gateway
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/kirocrew
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now kirocrew
systemctl status kirocrew

systemctl status kirocrew 应显示为 active (exited),这表示该单元运行正常。这里使用 Type=oneshot 和 RemainAfterExit=yes 是正确的,因为 docker compose up -d 会在容器启动后立即返回:systemd 跟踪的是服务栈已启动这一状态,而不是前台进程。如果改用 Type=simple,systemd 会看到命令立即退出,将服务标记为已停止,然后根据 Restart= 设置选择放弃重启或进入重启循环。对于原生安装,项目提供了自己的等效单元 kirocrew service install;该单元会写入 /etc/systemd/system/kirocrew.service,并以当前用户身份运行网关。不要同时运行这两个单元。VPS 上的 systemd 服务和计时器详细介绍了这一主题。单元如果无法恢复运行,默认不会主动通知;因此应添加 OnFailure= 处理程序,将告警推送到您自己的 ntfy 服务器。这样,您可以通过手机得知网关已停止,而不是等到某个从未运行的计划任务才发现问题。

首次运行:登录并获取仪表板令牌

容器会启动网关,但固定的 0.8.0 镜像中默认的 Kiro CLI 运行时仍需要身份验证。请在容器内登录,或通过容器环境传入 KIRO_API_KEY,以便自动化使用:

docker exec -it kirocrew kiro-cli login

该命令会输出设备代码和 URL。请在您自己的浏览器中打开该 URL。然后生成仪表板令牌:

docker exec kirocrew kirocrew token --ttl 2h

仪表板 URL 为 http://localhost:5476/?token=<the token>。令牌会过期:生成令牌后,必须在五分钟内打开输出的链接。此命令会请求一个有效期为两小时的访问 Cookie,文档规定的最长有效期为二十小时。浏览器还会收到一个刷新 Cookie,其滑动空闲窗口为 30 天,因此活动会话无需再次打开链接即可续期。仪表板加载为空白,或直接将您重定向回登录页,通常表示令牌已过期。请重新生成令牌,并立即打开链接。切勿将令牌粘贴到工单或聊天消息中,因为持有令牌的人即可控制您的代理。

通过 SSH 访问仪表板,绝不要发布端口 5476

再次查看项目示例中的绑定地址:-p 127.0.0.1:5476:5476。容器内的网关监听 0.0.0.0,因为它必须能够通过端口映射访问;但该映射只将端口发布到主机的回环地址。删除 127.0.0.1: 前缀后,网关就会暴露在公网,任何扫描该端口的人都能访问。ufw 规则也无法保护它:Docker 通过写入 DNAT 规则发布端口,在 ufw 规则生效前就已转发流量,因此 ufw deny 5476 对已发布的端口不起作用。使用 Docker 默认的 iptables 后端时,Docker 的做法是将过滤规则写入其 DOCKER-USER 链。这种方式可行,但除非使用 conntrack 扩展进行匹配,否则这些规则看到的是容器的内部地址和端口。因此,绑定到回环地址仍然是更简单、也更不容易配置错误的控制方式。Docker 的 nftables 后端则使用独立的 nftables 表和基础链来实现自定义过滤。绕过 ufw 的 Docker 端口详细介绍了这一机制。

从笔记本电脑通过 SSH 转发端口:

ssh -N -L 5476:127.0.0.1:5476 you@your-server.example.com

保持该连接运行,然后在本地打开 http://localhost:5476/?token=<the token>。要让每次连接都自动建立转发,将其写入 ~/.ssh/config:

Host your-server.example.com
    LocalForward 5476 127.0.0.1:5476

如果笔记本电脑上的端口 5476 已被占用,只修改左侧的端口号:ssh -N -L 45476:127.0.0.1:5476 you@your-server.example.com,然后访问 http://localhost:45476/?token=...。不需要额外设置回环端口,也不需要重新创建容器:回环 Origin 与请求自身的 Host 匹配,因此 CSRF 检查会接受该请求。只要第二个代理也使用这台主机,你就会开始叠加这样的转发,因为自行托管 open-kritt 进行安全扫描会在同一台服务器上再运行一个仅绑定回环地址的仪表板,端口为 5173。

两个已记录的行为决定了你可以从仪表板修改哪些设置。第一,网关会将任何带有转发标头(Forwarded、X-Forwarded-* 或 X-Real-IP)的请求视为远程请求,并拒绝这些请求访问配置写入和机密信息显示端点。反向代理会添加这些标头;普通的 ssh -L 转发不会添加任何标头,因此从这一点看它属于本地请求,不会被拒绝。第二,在容器镜像中,对于并非直接本地访问的浏览器,通道凭据页面和显示机密信息的视图均为只读,而且镜像不提供文本编辑器。如果通道凭据无法从仪表板保存,原因就在这里,而不是程序错误。请改为在主机上编辑配置:

docker cp kirocrew:/home/kirocrew/.kiro/crew/config.json .
# edit config.json here
docker cp config.json kirocrew:/home/kirocrew/.kiro/crew/config.json
docker exec -u 0 kirocrew chown kirocrew:kirocrew /home/kirocrew/.kiro/crew/config.json
docker restart kirocrew

若要通过手机访问,项目建议使用 Tailscale 的 tailscale serve,这样仪表板只位于你自己的 tailnet 内,而不会暴露在公共主机名下。优先采用这种方式,不要使用公共反向代理。令牌会出现在 URL 中,而 URL 会被写入沿途每一层的访问日志。这条规则关注的是端口后面的服务,而不是端口本身:例如将 Jellyfin 媒体库重建为可浏览的 90 年代视频商店的 Halcyon就是供其他人访问的服务,适合使用反向代理;而能够在服务器上执行命令的网关则不适合。

尽可能缩小代理的影响范围

容器首次启动时会探测是否支持沙箱,探测结果决定代理能否执行任何操作。如果支持命名空间隔离,代理子进程会在隔离环境中运行。如果不支持,且未设置 KIROCREW_ALLOW_UNSANDBOXED=1,则拒绝执行,而不是在无隔离环境中运行。因此,网关看似正常,但所有任务都停滞时,通常就是这个原因。该决定会写入首次运行生成的 docker logs kirocrew。项目还提供了可应用的 seccomp(安全计算模式)配置文件:

curl -fsSL https://raw.githubusercontent.com/kirodotdev/KiroCrew/main/docker/seccomp/kirocrew-seccomp.json \
  -o /opt/kirocrew/kirocrew-seccomp.json
    security_opt:
      - seccomp:./kirocrew-seccomp.json

在启用 AppArmor 的主机上,项目的 Docker 指南指出,仅应用 seccomp 配置文件还不够,因为 Docker 还会附加其 docker-default AppArmor 配置文件,并将该配置文件与 apparmor=unconfined 配合使用。该选项只会解除 AppArmor 针对单个容器的规则;seccomp 配置文件、已删除的 capabilities 以及非 root 用户仍然生效。

如果确实设置了 KIROCREW_ALLOW_UNSANDBOXED=1,必须明确发生了什么变化:此时,容器成为代理与服务器之间唯一的隔离边界。项目的警告值得完整重申。不要挂载你不愿直接交给代理使用的主机路径。实际操作中,这意味着不能挂载 Docker socket、/ 的任何 bind mount,也不能挂载存放其他服务数据的目录。

其余措施适用于所有获准执行命令的代理。将凭据权限限制在它需要的一个代码仓库或一个存储桶内,绝不要使用具有账户级权限的个人令牌。使用专用用户运行代理,并确保该用户的 home 目录中没有其他内容;这正是 VPS 上的最小权限用户 的用途。代理编写代码后还会运行这些代码,因此应为它提供一台允许被破坏的机器:用于代码代理的一次性 VM 比此 compose 文件中的任何选项都提供更强的隔离边界,因为你可以直接删除它,而不必清理环境。同样的思路也适用于 在 VPS 上安全运行 OpenClaw 和 在 VPS 上自行托管 Hermes 代理。工具同样会扩大影响范围:允许代理进行 Web 搜索后,它获取的每个页面都可能成为不可信输入,因此 将代理指向你自己的 SearXNG 实例 不仅是网络配置决策,也是提示注入防护决策。计划任务还会在你休息时持续产生费用,因为 Kiro 后端的推理会消耗你的 Kiro 套餐额度;在添加夜间任务前,请先按照 控制 AI 代理在 VPS 上的费用 中的说明设置限制。

在每次升级前备份状态卷

先查找实际的卷名称。Compose 会使用项目名称为命名卷添加前缀。项目名称默认为目录名称,因此,/opt/kirocrew/compose.yaml 中声明为 kirocrew-home 的卷会创建为 kirocrew_kirocrew-home:

docker volume ls

复制任何内容前,先停止网关。memory.db 和 memory_index.db 是 SQLite 数据库。在数据库写入期间复制,可能会捕获未完成的事务;恢复后,该文件会损坏。项目自身的迁移说明也提出了相同要求:只有在网关停止后,才能迁移 memory。先停止服务再复制并非 KiroCrew 特有的规则。如果同一台主机上还运行 photo server,PhotoPrism 和 Immich 对比给出了这两个服务各自需要使用的确切备份命令。

sudo systemctl stop kirocrew
docker run --rm -v kirocrew_kirocrew-home:/data:ro -v "$PWD":/backup \
  alpine tar czf /backup/kirocrew-2026-08-06.tgz -C /data .
sudo systemctl start kirocrew

将归档复制到主机之外的位置。恢复时使用相同的命令,但要先停止容器,并用 tar xzf 替换 tar czf:

sudo systemctl stop kirocrew
docker run --rm -v kirocrew_kirocrew-home:/data -v "$PWD":/backup \
  alpine tar xzf /backup/kirocrew-2026-08-06.tgz -C /data
sudo systemctl start kirocrew

迁移到新主机与在原主机上恢复是两项不同的工作,项目对此有明确说明。workspace/memory/ 下的聊天记录和项目备注会保留,两个数据库文件以及 config.json 也会保留。PID 文件、安全事件日志和 .env 与旧主机绑定,因此不要迁移它们,并在新主机上重新输入密钥。

如何回滚失败的升级

升级过程很短,而且只有在固定版本的前提下才安全。先创建备份,再修改标签:

sudo systemctl stop kirocrew
# take the backup here, as above
sudo nano /opt/kirocrew/compose.yaml   # set the new image tag
sudo systemctl start kirocrew
docker compose -f /opt/kirocrew/compose.yaml ps
curl -s http://127.0.0.1:5476/api/health

如果本机尚未存在该镜像,docker compose up -d 会先拉取镜像,因此修改标签就是完整的升级过程。回滚时使用相同的步骤,但改回旧版本号。这样可以获得升级前使用的确切镜像,因为版本标签不可变。

二进制文件可以正常回滚。状态数据则不一定。较新的网关可能会重写 config.json,或将内存数据库迁移为旧版网关无法读取的格式。截至 12 October 2026,尚未记录状态数据的降级路径。安装指南明确说明了一种情况:从旧版 ~/.kirocrew 主目录迁出的数据无法回滚,而早于 ~/.kiro/crew 的版本启动后会显示为空。因此,如果旧镜像能够启动但行为异常,不要继续排查。停止服务,恢复升级前创建的备份,然后重新启动。这正是必须先创建备份的原因,也是为什么“先升级、之后再备份”的做法不适用于这样一个仍处于早期阶段的项目。

本指南未验证的内容

请客观评估该软件的成熟度。版本 0.1.3 于 2026 年 8 月 5 日发布,截至 2026 年 10 月 12 日,稳定版分支已更新至 0.8.0。大多数发布说明仍为自动生成的变更日志;0.8.0 的说明虽为手动编写,但并未包含迁移章节,且公开的发布历史仅约三个月。本指南中的内容均非长期运行的验证结果,因此请自行在本地服务器上监测内存占用增长、数据库规模及调度程序的可靠性,切勿直接预设其表现。

在依赖以下两种行为之前,建议自行测试。首先,降级版本是否能读取由较新版本写入的状态:请在不影响业务时对卷副本进行测试,而非在故障期间。其次,当 Kiro 登录过期且恰逢定时任务执行时,网关会有何表现。这些都是年轻项目在版本迭代中会逐步完善的细节,现在检查这些问题的成本很低。

FAQ

为什么通过服务器的公网 IP 无法打开 KiroCrew 控制面板?

因为示例配置将端口绑定到了回环地址。-p 127.0.0.1:5476:5476 只将容器端口映射到主机的回环地址,这是有意的设计。使用 ssh -N -L 5476:127.0.0.1:5476 you@your-server 通过 SSH 转发端口,然后在笔记本电脑上打开 http://localhost:5476/?token=<token>。移除 127.0.0.1: 前缀后,网关会暴露到公网;此时 ufw 无法限制它,因为 Docker 发布端口的 DNAT 规则会在 ufw 规则生效前路由流量。应使用 Docker 的 DOCKER-USER 链及其 iptables 后端,或使用 nftables 后端配置独立的 nftables 基础链,来过滤发布的端口;保留回环地址绑定更简单。

KiroCrew 将数据存储在哪里?应备份哪些内容?

所有内容都位于 ~/.kiro/crew 下,该路径在容器镜像中是 /home/kirocrew/.kiro/crew,并由 KIROCREW_HOME 重新定位。停止网关后,备份整个目录或整个 Docker 卷。memory.db 和 memory_index.db 是 SQLite 数据库,因此在网关写入期间复制可能导致数据不一致。迁移到新主机时,应迁移 workspace/memory/、两个数据库文件和 config.json;PID 文件、安全事件日志以及 .env 属于旧主机。

应使用 stable 标签还是版本标签?

使用版本标签。每次发布新版本时,stable 都会更新,因此下次拉取时,正在运行的版本可能发生变化,而标签本身无法说明当前运行的内容。0.8.0 等版本标签不可变,这正是回滚能够生效的原因:恢复旧版本号后即可获得完全相同的镜像。截至 1 November 2026,最新稳定版本是 0.11.1。

为什么我的代理拒绝执行任何命令?

容器首次启动时会检测沙箱支持。如果无法隔离代理子进程,且未设置 KIROCREW_ALLOW_UNSANDBOXED=1,容器会拒绝执行这些进程,而不是在无隔离状态下运行它们。因此网关看似正常,但每个任务都会停滞。docker logs kirocrew 会显示首次运行时的沙箱决策。设置该变量后,容器将成为代理与主机之间的唯一隔离边界。因此,如果设置该变量,不要挂载任何你不愿直接交给代理的内容。

自托管 KiroCrew 是否需要 Kiro 账户?

对于 Kiro 后端,截至 1 November 2026,需要。KiroCrew 是基于 Apache 2.0 许可的自由软件,但这些后端的推理功能使用你的 Kiro 方案。固定版本的 0.8.0 容器使用 Kiro CLI:运行 docker exec -it kirocrew kiro-cli login,然后在浏览器中批准设备代码;也可以通过容器环境传入 KIRO_API_KEY,以便自动使用。在完成身份验证前,网关会启动,控制面板也能加载,但其默认 harness 没有可连接的模型。自 0.10.0 起,系统还内置了无需安装 kiro-cli 的 KAS 引擎;0.11.0 将 KAS 设为没有保存 harness 选择的新安装的默认引擎,同时保留明确选择 Kiro CLI 的配置。KAS 使用 Crew 自己的登录方式,而不是 kiro-cli login。项目的自定义后端指南允许 claude harness 将主要模型交互发送到你选择的兼容 Anthropic 的端点,但 Kiro 的 kiro-cli 登录仍用于 Kiro 专属功能。

这篇文章对您有帮助吗?