---
title: "Linux"
description: "在 Linux 上安装与使用 Kiri：包、服务、权限与升级。"
---

> Documentation Index
> Fetch the complete documentation index at: https://kiri.ndjp.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Linux

# Kiri on Linux

在 Linux 上，Kiri 无需虚拟机：守护进程与代理直接运行在宿主机内核上，通过 systemd 服务 `kiri.service` 管理。`docker` CLI、Compose 与 buildx 可照常使用。完整 `kiri` 包（x86-64）还包含图形窗口；`kiri-lite` 与部分架构包可能仅提供命令行。

## 无 VM，同一引擎

- macOS 上使用 VM + vsock；Linux 上代理作为普通 root 进程运行，通信改为私有目录中的 Unix socket。
- 容器隔离仍基于命名空间、cgroup、overlayfs、capabilities 与 seccomp；无 dockerd/containerd/shim/runc。
- 无 VM 内存气球与 VM 级空闲休眠。

## 软件包

提供 `.deb`（Debian/Ubuntu）与 `.rpm`（Fedora/RHEL/openSUSE），支持 x86-64 与 arm64。可从 [runkiri.com/download](https://runkiri.com/download/) 下载。

| 包 | 内容 |
| --- | --- |
| `kiri` | 引擎 + `docker` CLI、Compose、buildx（部分架构含窗口） |
| `kiri-lite` | 仅引擎，适合已安装 `docker` 的机器 |

两者互斥，只能安装其一。安装内容通常包括：
- `/usr/bin/kiri`、`/usr/bin/kiri-init`
- `kiri.service`（安装但可能不自动启动；按版本行为，需完成设置/授权后启动并可开机自启）
- `kiri` 用户组（拥有 `/run/kiri/docker.sock`，通常 `0660 root:kiri`）
- 数据目录 `/var/lib/kiri-daemon`、`/var/lib/kiri`
- `kiri` 包附带的 Docker CLI/插件路径（如 `/usr/libexec/kiri`、`/usr/lib/docker/cli-plugins`）

## 安装

### 安装脚本

```bash
curl -fsSL https://runkiri.com/install.sh | bash
# 安装 lite 版本
KIRI_LITE=1 curl -fsSL https://runkiri.com/install.sh | bash
```

脚本会选择匹配发行版与架构的包、校验摘要并使用包管理器安装（需要 systemd 与 sudo）。

### 手动安装

```bash
# Debian / Ubuntu
sudo apt install ./kiri_<version>_amd64.deb

# Fedora / RHEL
sudo dnf install ./kiri-<version>-1.x86_64.rpm

# openSUSE
sudo zypper install --allow-unsigned-rpm ./kiri-<version>-1.x86_64.rpm
```

安装后将当前用户加入 `kiri` 组并重新登录：

```bash
sudo usermod -aG kiri $USER
```

验证：

```bash
docker run --rm hello-world
```

使用 `kiri-lite` 时，可创建并切换 Docker context：

```bash
docker context create kiri --docker host=unix:///run/kiri/docker.sock
docker context use kiri
```

> **权限提示**：`kiri` 组成员可通过引擎以 root 权限运行容器并挂载任意路径，等同于 `docker` 组权限，请仅授予可信用户。

## Docker 如何找到 Kiri

- **`/usr/bin/docker`**：`kiri` 包可能通过 `update-alternatives` 提供 CLI（仅在路径空闲或已为 alternatives 链接时）；已有其他来源的 `docker` 不会被强行替换。
- **`/var/run/docker.sock`**：当该路径未被其他引擎占用时，`kiri.service` 可在启动时创建指向 `/run/kiri/docker.sock` 的链接，供忽略 docker context 的工具（如 Testcontainers、docker-py 等）使用；停止服务时移除 Kiri 创建的链接。
- `DOCKER_HOST`、`DOCKER_CONTEXT` 或 `docker context use` 可显式指定引擎。

## 命令与诊断

- `kiri run/ps/compose ...`：通过 PATH 中的 `docker` 面向 Kiri 执行。
- `kiri share`、`kiri k8s`：在 Linux 上可用（按版本支持）。
- `kiri diag logs`、`kiri diag report`：诊断信息；服务日志也可通过 `journalctl -u kiri` 查看（部分日志需 root 权限访问数据目录）。

macOS 专属命令（如菜单栏、`kiri setup`、`kiri update`、`kiri import` 等）在 Linux 上不可用或行为不同。

## 升级

- 当前可能需手动下载新包安装或重新运行安装脚本；官方计划提供签名 apt/dnf 仓库。
- 升级后引擎可能仍运行旧版本以避免中断容器，可在合适时执行：`sudo systemctl restart kiri`。

## 卸载

```bash
# Debian/Ubuntu
sudo apt remove kiri    # 保留数据
sudo apt purge kiri     # 同时删除数据与组（按包行为）

# Fedora/RHEL
sudo dnf remove kiri
```

移除包会停止服务并清理 Kiri 创建的 alternatives/链接；数据目录是否保留取决于 remove/purge 行为与发行版包管理器。RPM 系统移除后如需彻底清理，可手动删除 `/var/lib/kiri`、`/var/lib/kiri-daemon` 并删除 `kiri` 组。

## 无包安装（源码/手动）

可使用源码中的 systemd unit 与自行构建的静态二进制（`cargo xtask linux` 等）部署，需自行放置 `kiri`/`kiri-init`、配置 `kiri.service` 与 `kiri` 组。细节以仓库 `contrib/linux/kiri.service` 与构建脚本为准。

Source: https://kiri.ndjp.net/platforms/linux/index.mdx
