---
title: "Windows"
description: "在 Windows 上安装与使用 Kiri（WSL2、安装流程与更新）。"
---

> 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.

# Windows

# Kiri on Windows

在 Windows 上，Kiri 通过 **WSL2** 运行其 Linux 引擎。Windows 侧程序 `kiri-win.exe` 负责 Docker API 命名管道、图形窗口与托盘图标，并与 WSL 内的引擎通信。

> **Beta**：Windows 版本处于 Beta 阶段。安装包在部分版本中可能未签名，系统可能提示确认；如遇问题可通过窗口内反馈渠道提交。

## 系统要求与安装包

- 支持 Windows 10/11，提供 x64 与 ARM64 安装包（如 `Kiri-<version>-x86_64.msi`、`Kiri-<version>-arm64.msi`）。
- 安装包与引擎、CLI 工具需与 CPU 架构匹配；在错误架构上安装会提示更换正确安装包。
- 每用户安装（无需管理员权限安装本体），默认路径通常为 `%LOCALAPPDATA%\Kiri`，并可添加开始菜单项与“已安装应用”条目。

## 首次运行与设置向导

首次打开 Kiri 会进入分步设置（进度保存在本地，可在重启后继续）：

1. **语言选择**（较新版本）：默认跟随 Windows 语言，可选择界面语言。
2. **WSL2**：如未安装，Kiri 可下载并安装所需组件，可能需要管理员批准与系统重启。
3. **选择 Linux 发行版**：
   - **Kiri Linux**：安装包内置的轻量发行版（注册为 `kiri` WSL 发行版），下载/占用更小。
   - **Ubuntu 26.04** 或已有 Ubuntu：可从微软渠道下载或复用已安装发行版。
4. **启动引擎**：在所选 WSL 发行版中启动引擎并通过运行测试容器验证。
5. **Docker 工具**：安装/校验 `docker` CLI、Compose、buildx，配置 `kiri-build` 构建器与默认 context（若选择）。
6. **完成**：可选“登录时启动（托盘）”并打开 Kiri。

Kiri 的 `bin` 目录通常追加到用户 PATH 末尾，避免覆盖已有 `docker`。未设为默认时可使用 `docker --context kiri`。

## 代理与网络

- 若 Windows 代理监听在 `127.0.0.1`（如 `http://127.0.0.1:7892`），Kiri 可将 WSL 内的代理连接转发到 Windows 侧代理，使镜像拉取等操作可用。
- 安装/拉取失败时，向导或日志会尽量给出具体原因（代理拒绝、注册表不可达、限流或需认证等）。

## USB 设备

Windows 上通过 **usbipd-win** 将 USB 设备共享到 WSL 供容器使用。若未安装，USB 视图可提供安装入口；首次附加设备需管理员批准。详见 [USB 设备](https://kiri.ndjp.net/features/usb/)。

## 工作原理概览

- WSL 内：引擎在 Unix socket（如 `/var/lib/kiri-daemon/.kiri/run/docker.sock`）提供 Docker API。
- Windows 内：`kiri-win.exe` 在 `\\.\pipe\kiri` 提供 Docker API（对应 docker context 的 `npipe:////./pipe/kiri`）。
- 两者通过 `wsl.exe -u root -- kiri bridge` 进程以帧协议中继连接，避免 WSL TCP localhost 转发对半关闭的兼容性问题，保证 `docker run`/`attach` 等场景正常。

## 托盘与命令行

- 关闭窗口通常使 Kiri 最小化到托盘并继续运行；托盘菜单可打开窗口、查看状态、检查更新与退出。
- `kiri` 命令位于安装目录的 `bin` 中：`kiri run/ps` 等通过 Kiri context 执行 Docker 命令，`kiri share`、`kiri k8s`、`kiri machine`、`kiri diag` 等按支持情况转发到引擎。

## 更新

- Kiri 按架构检查对应更新源，后台下载安装包并校验完整性与元数据。
- 可选择立即重启或稍后安装；更新可能停止容器（有重启策略的容器可恢复）。引擎组件可能需要按提示重启以完成切换。详见 [更新](https://kiri.ndjp.net/guide/updates/)。

## 卸载

- 从“已安装应用”卸载会清理 context、构建器配置、PATH 与自启动项等。
- 若使用 Kiri 创建的专用 WSL 发行版，卸载可能注销该发行版并删除其中数据；使用自有发行版时通常仅移除 Kiri 引擎组件，数据保留在 `/var/lib/kiri` 等位置（以实际卸载行为与提示为准）。
- 建议从原安装用户账户执行卸载，以正确清理用户级设置。

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