本文档介绍如何在麒麟V10系统中挂载ISO镜像文件，并配置本地YUM源。

1. 挂载ISO文件

假设ISO文件存放在 /opt/iso/ 目录，目标挂载路径为 /mnt/media/iso。

1.1 临时挂载

1

mount -t iso9660 /opt/iso/Kylin-Server-V10-SP3-2403-Release-20240426-x86_64.iso /mnt/media/iso

1.2 永久挂载

编辑 /etc/fstab 文件，在末尾添加以下行：

1

/opt/iso/Kylin-Server-V10-SP3-2403-Release-20240426-x86_64.iso    /mnt/media/iso    iso9660    loop,ro,auto    0 0

2. 配置YUM源

在 /etc/yum.repos.d/ 目录下创建新的源配置文件 Kylin_Local.repo。

1
2
3
4
5
6

[Kylin-Local]
name=Kylin V10 Local Repository
baseurl=file:///mnt/media/iso
enabled=1
gpgcheck=1
gpgkey=file:///mnt/media/iso/RPM-GPG-KEY-Kylin

配置项说明：

• baseurl: 指定本地ISO的挂载路径。
• enabled: 设为 1 以启用此仓库。
• gpgcheck: 设为 1 以启用GPG签名验证，确保软件包安全。
• gpgkey: 指定用于验证的GPG公钥文件位置。

3. 测试源配置

配置完成后，执行以下命令测试源是否正常工作：

1
2
3
4
5
6
7
8
9

# 清理旧的YUM缓存并生成新缓存
dnf clean all
dnf makecache

# 列出已启用的仓库，检查本地源是否在列
dnf repolist

# 尝试搜索一个软件包，测试源功能
dnf search openssh-server

4. 扩展：搭建局域网共享源

若需在多台机器上使用，可在局域网内搭建一个共享源服务器。

4.1 在源服务器上操作

1
2
3
4
5
6
7
8
9
10

# 1. 安装Nginx Web服务器
dnf install -y nginx
systemctl enable --now nginx

# 2. 将ISO挂载到Nginx的Web目录
mount -t iso9660 -o loop /opt/iso/Kylin-Server-V10-SP3-2403-Release-20240426-x86_64.iso /usr/share/nginx/html/kylin-local/

# 3. 配置防火墙，允许HTTP访问
firewall-cmd --permanent --add-service=http
firewall-cmd --reload

4.2 在客户端机器上配置

将客户端YUM源配置文件中的 baseurl 修改为：

1

baseurl=http://<源服务器IP地址>/kylin-local

5. 常见问题与解决方案

问题1：挂载点不存在或权限不足

1
2
3

# 创建挂载目录并设置权限
mkdir -p /mnt/media/iso
chmod 755 /mnt/media/iso

问题2：GPG密钥验证失败

• 临时解决方案（不推荐用于生产环境）：
  在 Kylin_Local.repo 文件中将 gpgcheck=1 改为 gpgcheck=0。
• 正确解决方案：
  检查GPG密钥文件路径和名称是否正确。

  1	ls -l /mnt/media/iso/RPM-GPG-KEY-Kylin

问题3：软件包依赖缺失

1
2
3
4

# 查看详细的安装错误信息
dnf --verbose install <软件包名>

# 如果确认本地源缺少某些依赖，可以考虑配置多个YUM源（如结合官方网络源）

麒麟V10配置EPEL源指南

概述

在麒麟V10系统上配置EPEL（Extra Packages for Enterprise Linux）源，可以方便安装大量额外的开源软件包。由于麒麟V10基于CentOS系（内核版本介于CentOS 8与9之间），大部分 EPEL 8 的软件包都能直接使用。

方法一：直接安装官方EPEL RPM包

操作步骤

1. 下载并安装EPEL源RPM包

1
2

wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
rpm -ivh epel-release-latest-8.noarch.rpm --nodeps --force

2. 清理缓存并生成新缓存

1
2

yum clean all
yum makecache

3. 测试安装软件

1

yum install htop -y

方法二：使用国内镜像（推荐）

操作步骤

1. 创建EPEL仓库配置文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

cat > /etc/yum.repos.d/epel.repo <<EOF
[epel]
name=Extra Packages for Enterprise Linux 8 - \$basearch
baseurl=https://mirrors.tuna.tsinghua.edu.cn/epel/8/Everything/\$basearch/
enabled=1
gpgcheck=0
countme=1

[epel-debuginfo]
name=Extra Packages for Enterprise Linux 8 - \$basearch - Debug
baseurl=https://mirrors.tuna.tsinghua.edu.cn/epel/8/Everything/\$basearch/debug/
enabled=0
gpgcheck=0

[epel-source]
name=Extra Packages for Enterprise Linux 8 - \$basearch - Source
baseurl=https://mirrors.tuna.tsinghua.edu.cn/epel/8/Everything/source/tree/
enabled=0
gpgcheck=0
EOF

2. 更新缓存并测试

1
2

yum makecache
yum install vnstat -y

验证方式

执行 yum repolist 确认 epel 仓库已启用，并能正常安装来自EPEL的软件包。

配置建议

1. 版本选择：麒麟V10建议使用 EPEL 8 源
2. 架构适配：对于ARM架构，$basearch 会自动匹配 aarch64，无需手动修改
3. 网络优化：若需长期稳定运行，建议优先选择国内镜像以减少网络延迟

1. Chrony简介

Chrony是一个开源自由的网络时间协议（NTP）客户端和服务器软件。它能让计算机保持系统时钟与时钟服务器（NTP）同步，确保计算机保持精确的时间。Chrony也可以作为服务端软件为其他计算机提供时间同步服务。

Chrony由两个程序组成：

• chronyd：后台运行的守护进程，用于调整内核中运行的系统时钟和时钟服务器同步
• chronyc：用户界面程序，用于监控性能并进行多样化的配置

2. 时间同步相关概念

2.1 硬件时间

硬件时间，也被称为实时时钟（RTC），是指计算机主板上的一个独立于操作系统的设备，它在电源关闭甚至断电情况下也能保持运行。

相关命令：

1
2
3
4
5
6
7
8

# 查询硬件时间
hwclock --show

# 将系统时间设置为硬件时间
hwclock --systohc

# 将硬件时间设置为系统时间
hwclock --hctosys

2.2 时间标准

• UTC：协调世界时，基于原子时钟的时间标准
• Local time：本地时间，系统时间经过时区转换后的时间

2.3 时间同步目的

1. 对外同步：保证本地时间和国际通用时间保持同步（通过NTP）
2. 对内同步：保证系统时间和硬件时间同步（通过rtcsync）

3. 安装与配置

3.1 服务端配置

安装Chrony：

1
2
3

yum -y install chrony
systemctl enable chronyd
systemctl start chronyd

修改配置文件 /etc/chrony.conf：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 记录时间补偿调整
driftfile /var/lib/chrony/drift

# 允许系统时钟在前三次更新中步进
makestep 1.0 3

# 启用RTC内核同步
rtcsync

# 允许所有客户端连接
allow all

# 本地时间作为标准时间授时
local stratum 10

配置说明：

• local指令允许将本地时间作为标准时间授时给其他客户端
• stratum 10表示距离真实时间源较远，防止机器本身的时间与真实时间混淆

3.2 客户端配置

修改配置文件 /etc/chrony.conf：

1

server 10.0.0.1 iburst

重启服务：

1

systemctl restart chronyd

4. 常用命令与监控

4.1 查看同步状态

1

chronyc sources -v

状态标识说明：

4.2 时间同步状态检查

1

chronyc tracking

关键参数说明：

• Reference ID：正在同步的NTP服务器地址
• Stratum：系统在NTP层次中的级别
• System time：系统时间相对于NTP服务器时间的差异
• Last offset：上一次时间同步时的偏移量
• Frequency：本地系统时钟的速度（ppm）

4.3 系统时间管理

1
2
3
4
5

# 查看时间状态
timedatectl

# 设置NTP服务状态（慎用）
timedatectl set-ntp yes/no

5. 常见问题与解决方案

5.1 迁移VM后时间差异较大

问题：需要快速同步时间

解决方案：

1
2
3
4
5

# 逐步校正（较慢）
chronyc makestep 0.1 3

# 立即同步时钟
chronyc -m 'burst 3/3' 'makestep 0.1 3'

5.2 外网时间源不可用

问题：启用本地模式后，客户端无法同步时间

解决方案：local模式只能有一个服务器配置该参数

5.3 Chronyd服务正常但未同步

问题：NetworkManager调度程序脚本BUG（3.2-2版本）

解决方案：

• 临时：重启chronyd服务
• 永久：升级到3.4以上版本

6. 常用时钟源推荐

6.1 公共NTP服务器

• pool.ntp.org：cn.pool.ntp.org，0-3.cn.pool.ntp.org
• 阿里云：ntp.aliyun.com，ntp1-7.aliyun.com
• 大学NTP服务：
  • s1a.time.edu.cn（北京邮电大学）
  • s1b.time.edu.cn（清华大学）
  • s1c.time.edu.cn（北京大学）
• 国家授时中心：210.72.145.44

6.2 配置示例

1
2
3
4

# 使用阿里云NTP服务器
server ntp.aliyun.com iburst
server ntp1.aliyun.com iburst
server ntp2.aliyun.com iburst

在使用Docker过程中，镜像拉取超时、构建镜像时依赖下载失败是开发者常遇到的问题，其核心原因在于网络环境限制。为Docker配置代理是解决该问题最直接、高效的方案。本文将详细介绍三种常用的Docker代理配置方式，分别适配守护进程（Systemd、daemon.json）和客户端（config.json）场景，配套完整操作步骤、验证方法及关键注意事项，助力开发者快速完成配置、规避常见坑。

一、配置前提说明

在启动配置前，请确认以下两个核心前提，避免因前提缺失导致配置失败：

1. 已完成Docker安装（未安装用户可参考Docker官方文档，根据自身操作系统执行对应安装命令，确保安装版本与系统兼容）；

2. 已拥有可用的代理服务（如Clash、V2Ray等），并准确获取代理地址及端口（常规格式为http://127.0.0.1:端口号，常见端口包括7890、1080等，需与本地代理工具监听端口一致）。

本文涵盖三种配置场景，开发者可根据自身需求灵活选择：守护进程代理（Systemd、daemon.json，优先推荐，核心解决镜像拉取超时）、客户端代理（config.json，补充配置，解决容器内网络访问需求）。

二、方式一：守护进程代理（Systemd，推荐）

该方式直接作用于Docker守护进程（dockerd），是Docker官方推荐的生产级配置方案，稳定性强，核心解决docker pull镜像拉取超时问题，配置后所有Docker服务相关的网络请求均会通过代理转发（适配基于Systemd管理服务的操作系统，如CentOS、Ubuntu等主流Linux发行版）。

步骤1：创建Systemd配置目录

在基于Systemd的系统中，Docker服务通过Systemd管理，需先创建专属配置目录（用于存放代理配置文件），若目录已存在，可直接跳过此步骤：

1

sudo mkdir -p /etc/systemd/system/docker.service.d

步骤2：新建代理配置文件

在上述创建的目录中，新建http-proxy.conf配置文件，用于定义Docker守护进程的代理环境变量：

1

sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf

步骤3：写入代理配置信息

打开配置文件后，输入以下内容，将<proxy-addr>替换为实际代理地址（示例：http://127.0.0.1:7890），保存并退出（nano编辑器操作：Ctrl+O保存，Ctrl+X退出）：

1
2
3
4

[Service]
Environment="HTTP_PROXY=http://<proxy-addr>"
Environment="HTTPS_PROXY=http://<proxy-addr>"
Environment="NO_PROXY=localhost,127.0.0.1,::1"

关键说明：

• HTTP_PROXY/HTTPS_PROXY：分别指定HTTP、HTTPS协议请求的代理地址，确保所有Docker网络请求均走代理；

• NO_PROXY：指定无需走代理的地址，必须包含本地回环地址（localhost、127.0.0.1、::1），避免本地通讯走代理导致性能损耗，可根据实际需求添加内网地址。

步骤4：重载配置并重启Docker服务

配置文件修改后，需重载Systemd配置，重启Docker服务，确保代理配置生效：

1
2

sudo systemctl daemon-reload
sudo systemctl restart docker

步骤5：验证代理是否生效

通过以下命令查看Docker服务的环境变量，若输出中包含配置的代理信息，即说明守护进程代理配置成功：

1

sudo systemctl show --property=Environment docker

预期输出示例：Environment=HTTP_PROXY=http://127.0.0.1:7890 HTTPS_PROXY=http://127.0.0.1:7890 NO_PROXY=localhost,127.0.0.1,::1

三、方式二：守护进程代理（daemon.json，通用）

除Systemd方式外，通过Docker守护进程配置文件daemon.json配置代理，是更通用的方案，适配所有支持Docker的操作系统（Linux、Windows、Mac），配置逻辑简洁，直接通过JSON格式定义代理参数，同样作用于dockerd守护进程，可有效解决镜像拉取超时问题，适合跨系统使用场景。

步骤1：定位并编辑daemon.json文件

Docker守护进程配置文件daemon.json的默认路径因操作系统而异，开发者可根据自身系统查找，若文件不存在，直接创建即可：

• Linux系统：/etc/docker/daemon.json

• Windows系统（Docker Desktop）：通过界面进入「设置」→「Docker Engine」，直接编辑JSON内容

• Mac系统（Docker Desktop）：通过界面进入「设置」→「Docker Engine」，直接编辑JSON内容

Linux系统编辑命令（若文件不存在，执行命令后会自动创建）：

1

sudo nano /etc/docker/daemon.json

步骤2：写入代理配置信息

在daemon.json文件中输入以下JSON格式内容，将<proxy-addr>替换为实际代理地址（示例：http://127.0.0.1:7890），注意严格遵循JSON格式规范（逗号分隔、无多余空格），保存并退出：

1
2
3
4
5
6
7

{
  "proxies": {
    "http-proxy": "http://<proxy-addr>",
    "https-proxy": "http://<proxy-addr>",
    "no-proxy": "localhost,127.0.0.1,::1"
  }
}

关键说明：

• 与Systemd方式区分：daemon.json中代理参数均为小写（http-proxy、https-proxy、no-proxy），切勿与Systemd方式的大写参数混淆，否则会导致配置失效；

• 若daemon.json中已存在其他配置（如镜像源），无需新建文件，只需在原有JSON对象中添加proxies节点即可，示例如下：

1
2
3
4
5
6
7
8

{
  "registry-mirrors": ["https://docker.mirrors.aliyun.com"],
  "proxies": {
    "http-proxy": "http://127.0.0.1:7890",
    "https-proxy": "http://127.0.0.1:7890",
    "no-proxy": "localhost,127.0.0.1,::1"
  }
}

步骤3：重启Docker服务，使配置生效

配置完成后，需重启Docker服务，不同操作系统的重启方式如下，按需选择：

• Linux系统（Systemd）：sudo systemctl restart docker

• Windows/Mac系统（Docker Desktop）：直接在界面点击「重启」按钮，或关闭Docker后重新启动即可。

步骤4：验证代理是否生效

提供两种验证方式，开发者可任选其一，操作简单高效：

1. 拉取测试镜像：执行docker pull hello-world，若能成功拉取镜像，说明代理配置生效；

2. 查看守护进程配置：Linux系统执行sudo docker info，在输出结果中找到「HTTP Proxy」「HTTPS Proxy」字段，若显示配置的代理地址，即配置成功。

四、方式三：客户端代理（config.json，可选）

该方式作用于Docker CLI（客户端），适配所有Docker支持的操作系统，核心影响docker build镜像构建、容器内网络访问等场景，与守护进程代理形成互补。若仅需解决镜像拉取问题，配置方式一或方式二即可；若需容器内访问外部网络（如构建时下载依赖包），需补充配置此方式。

步骤1：创建/编辑客户端配置文件

Docker客户端配置文件位于用户目录下的.docker文件夹中，若文件夹或配置文件不存在，执行命令后会自动创建，不同操作系统路径如下：

• Windows系统：C:\Users\用户名\.docker\config.json

• Linux/Mac系统：~/.docker/config.json

Linux/Mac系统编辑命令：

1
2

mkdir -p ~/.docker
nano ~/.docker/config.json

步骤2：添加客户端代理配置

在config.json文件中输入以下JSON格式内容，将<proxy-addr>替换为实际代理地址，保存并退出：

1
2
3
4
5
6
7
8
9

{
  "proxies": {
    "default": {
      "httpProxy": "http://<proxy-addr>",
      "httpsProxy": "http://<proxy-addr>",
      "noProxy": "localhost,127.0.0.1,::1"
    }
  }
}

关键说明：该配置仅对当前用户生效，若需对所有用户生效，可将配置文件复制到系统级Docker配置目录（Linux系统为/etc/docker/config.json，Windows系统可参考官方文档配置系统级路径）。

五、全局测试：验证代理是否正常工作

无论采用哪种配置方式，均可通过拉取官方测试镜像hello-world验证代理有效性，操作简单且直观：

1

docker pull hello-world

若镜像拉取成功，会提示“Hello from Docker!”相关信息；若仍出现超时，需优先检查代理地址是否正确、本地代理服务是否正常运行。

六、关键注意事项与常见问题

1. 代理地址填写规范

代理地址需与本地代理工具的监听设置完全一致，避免因地址或端口错误导致配置失效。示例：Clash默认HTTP代理地址为http://127.0.0.1:7890，V2Ray默认地址通常为http://127.0.0.1:10809，配置前需确认代理工具的监听参数。

2. NO_PROXY列表不可遗漏

本地回环地址（localhost、127.0.0.1、::1）必须加入NO_PROXY列表，否则会导致Docker容器无法访问本地服务，或本地服务与Docker容器通讯异常，影响使用体验。

3. 配置不生效的排查方法

• 检查代理服务状态：通过访问代理地址（如curl http://127.0.0.1:7890）测试，确认代理服务正常运行；

• 核对配置路径：基于Systemd的系统，守护进程配置路径为/etc/systemd/system/docker.service.d/http-proxy.conf；daemon.json路径为/etc/docker/daemon.json，确保路径和文件名无误；

• 重启服务重试：配置修改后需重启Docker服务，若仍不生效，可通过对应系统的日志查看命令（如Linux系统sudo journalctl -u docker）排查错误原因；

• 检查JSON格式：daemon.json配置不生效时，需重点检查JSON格式（可通过在线JSON校验工具验证），避免逗号遗漏、引号不匹配等语法错误。

4. 代理关闭后的清理

若后续无需使用代理，可按以下步骤清理配置（适配基于Systemd的Linux系统，其他系统可参考对应路径调整）：

1. 删除Systemd守护进程代理配置：sudo rm /etc/systemd/system/docker.service.d/http-proxy.conf；

2. 删除daemon.json守护进程代理配置：编辑/etc/docker/daemon.json，删除proxies节点（若文件中无其他配置，可直接删除该文件）；

3. 删除客户端代理配置：rm ~/.docker/config.json；

4. 重载并重启Docker服务：sudo systemctl daemon-reload && sudo systemctl restart docker。

七、总结

Docker代理配置的核心原则是“守护进程代理为主，客户端代理为辅”：优先选择守护进程代理（Systemd方式适配Linux Systemd系统，稳定性强；daemon.json方式适配所有系统，通用性更高），可高效解决镜像拉取超时问题；若需容器内访问外部网络，补充配置客户端代理（config.json）即可。本文提供的三种配置方式均经过实际场景验证，步骤清晰、重点突出，适配Docker支持的各类操作系统，开发者可根据自身网络环境和实际需求，灵活选择合适的配置方式，快速解决Docker网络访问难题。

在 Windows 开发环境中，WSL 2（Windows Subsystem for Linux 2）与 Docker Desktop 的组合已成为开发者的主流选择——既可以享受 Linux 终端的便捷性，又能依托宿主机 Docker 服务实现容器化开发。但在实际使用中，当需要访问私有镜像仓库或启用宿主机 Docker TLS 验证时，常出现 tls: failed to verify certificate: x509: certificate signed by unknown authority 证书信任错误。本文将详细讲解如何在 WSL 2 中配置私有证书，让 WSL 客户端顺利信任宿主机 Docker 服务端或私有镜像仓库，彻底解决证书验证问题。

一、前置条件：确保 WSL 2 与宿主机 Docker 正常连通

在配置私有证书前，需先确认 WSL 2 能正常调用宿主机 Docker 服务，这是后续证书配置的基础，步骤如下：

1. 验证 WSL 版本：在 Windows 终端执行 wsl -l -v，确保目标 Linux 发行版（如 Ubuntu）的 VERSION 为 2；若为 1，需执行 wsl --set-version <发行版名称> 2 升级。

2. 启用 Docker Desktop WSL 集成：打开宿主机 Docker Desktop，进入 Settings → General，勾选 Use the WSL 2 based engine；再进入 Settings → Resources → WSL Integration，启用目标 WSL 发行版的集成功能，点击 Apply & Restart 重启 Docker。

3. WSL 端安装 Docker 客户端：进入 WSL 终端，执行 sudo apt update && sudo apt install docker.io -y，无需单独启动 Docker 守护进程（daemon），因为 WSL 会复用宿主机 Docker 服务。

4. 测试连通性：在 WSL 终端执行 docker -H tcp://localhost:2375 ps，若能正常返回宿主机 Docker 容器列表，说明 WSL 与宿主机 Docker 已连通；若提示连接失败，需检查 Docker Desktop 集成配置或 Windows 防火墙是否放行 2375 端口。

注意：WSL 2 访问宿主机文件系统时，推荐使用路径 /run/desktop/mnt/host/c/（替代传统 /mnt/c/），可避免路径访问权限或同步问题，这也是后续证书拷贝的关键路径格式。

二、核心场景：WSL 配置私有证书的两种常用场景

WSL 中调用宿主机 Docker 时，证书信任需求主要分为两种场景：一是信任宿主机 Docker 服务端的 TLS 证书（双向认证场景），二是信任私有镜像仓库（如 Harbor、GitLab Registry）的私有 CA 证书。以下分别给出详细配置步骤，覆盖大多数开发场景。

场景一：WSL 信任宿主机 Docker 服务端证书（mTLS 双向认证）

若宿主机 Docker 启用了 TLS 验证（即通过 --tlsverify 参数启动），WSL 客户端需配置对应的 CA 证书、客户端证书及密钥，才能通过双向认证（mTLS）与宿主机 Docker 服务端通信。

步骤 1：获取宿主机 Docker TLS 证书

宿主机 Docker 的 TLS 证书默认存储在 C:\Users\<你的 Windows 用户名>\.docker\ 目录下，核心文件包括：

• ca.pem：根 CA 证书（用于验证服务端证书合法性）；

• cert.pem、key.pem：宿主机 Docker 服务端证书及密钥；

• client-cert.pem、client-key.pem：客户端证书及密钥（双向认证必需）。

若该目录下无相关证书，需先在宿主机配置 Docker TLS 验证，生成对应证书文件（可参考 Docker 官方文档或联系运维人员获取）。

步骤 2：在 WSL 中创建证书目录

WSL 中 Docker 客户端会从 ~/.docker/certs.d/<宿主机 Docker 地址>:<端口>/ 目录读取证书，需先创建该目录，格式如下：

1
2

# 示例：宿主机 Docker 地址为 192.168.1.100，TLS 端口为 2376（默认 TLS 端口）
mkdir -p ~/.docker/certs.d/192.168.1.100:2376

说明：宿主机 Docker 启用 TLS 后，默认端口为 2376，而非非 TLS 模式的 2375，需确认端口对应正确。

步骤 3：拷贝宿主机证书到 WSL 目录

通过 WSL 访问宿主机证书目录，将所需证书拷贝到上述创建的 WSL 证书目录中，命令如下：

1
2
3
4
5
6

# 拷贝根 CA 证书（必选）
cp /run/desktop/mnt/host/c/Users/<Windows用户名>/.docker/ca.pem ~/.docker/certs.d/192.168.1.100:2376/ca.crt

# 拷贝客户端证书与密钥（双向认证必选）
cp /run/desktop/mnt/host/c/Users/<Windows用户名>/.docker/client-cert.pem ~/.docker/certs.d/192.168.1.100:2376/client.crt
cp /run/desktop/mnt/host/c/Users/<Windows用户名>/.docker/client-key.pem ~/.docker/certs.d/192.168.1.100:2376/client.key

注意：将命令中的 <Windows用户名> 和宿主机 Docker 地址、端口替换为实际信息，若路径错误会导致证书无法被识别。

步骤 4：配置 WSL 环境变量（永久生效）

需在 WSL 中配置环境变量，指定宿主机 Docker 地址、启用 TLS 验证，并指向证书目录，确保每次启动 WSL 终端都能生效。

1. 编辑环境变量配置文件（根据所使用的 Shell 选择，如 bash 对应 ~/.bashrc，zsh 对应 ~/.zshrc）：
   vim ~/.bashrc

2. 在文件末尾添加以下配置：
   `# 指向宿主机 Docker 服务地址（TLS 端口 2376）

export DOCKER_HOST=tcp://192.168.1.100:2376

启用 TLS 验证

export DOCKER_TLS_VERIFY=1

指向 WSL 本地证书目录

export DOCKER_CERT_PATH=~/.docker/certs.d/192.168.1.100:2376`

3. 使配置生效：
   source ~/.bashrc

步骤 5：验证配置

在 WSL 终端执行 docker ps，若能正常返回宿主机 Docker 容器列表，无证书验证错误，说明配置成功；若仍报错，需检查证书路径、环境变量或宿主机 Docker TLS 配置是否正确。

场景二：WSL 信任私有镜像仓库证书

若仅需在 WSL 中通过宿主机 Docker 访问私有镜像仓库（如公司内网 Harbor、自建 GitLab Registry），无需配置宿主机 Docker TLS 验证，只需让 WSL Docker 客户端信任私有仓库的 CA 证书即可，该场景更常见于日常开发。

步骤 1：获取私有仓库 CA 证书

私有仓库的 CA 证书（通常为 ca.crt 或 ca.pem）可从宿主机获取——宿主机 Docker 若已配置信任该私有仓库，证书通常存储在 C:\Users\<Windows用户名>\.docker\certs.d\<仓库域名>:<端口>/ 目录下；若未配置，需联系运维人员获取私有仓库的 CA 证书。

步骤 2：在 WSL 中创建仓库证书目录

与场景一类似，WSL Docker 客户端会根据私有仓库的域名和端口查找证书，需创建对应目录：

1
2

# 示例：私有仓库地址为 registry.example.com，端口为 443（默认 HTTPS 端口）
mkdir -p ~/.docker/certs.d/registry.example.com:443

步骤 3：拷贝 CA 证书到 WSL 目录

将宿主机的私有仓库 CA 证书拷贝到 WSL 对应的证书目录中，命令如下：

1

cp /run/desktop/mnt/host/c/Users/<Windows用户名>/.docker/certs.d/registry.example.com:443/ca.crt ~/.docker/certs.d/registry.example.com:443/

补充：若私有仓库使用自签名证书，且宿主机未配置，可直接将自签名证书拷贝到上述目录，无需额外配置。

步骤 4：验证配置

在 WSL 终端执行 docker login registry.example.com，输入私有仓库的账号密码，若能成功登录，说明证书配置生效；登录成功后，即可正常拉取、推送私有镜像，不再出现 x509 证书错误。

三、常见问题与快速修复方案

配置过程中，可能会遇到证书识别失败、连接超时等问题，以下是高频问题及解决方案，覆盖大部分异常场景：

问题 1：配置后仍报 x509: certificate signed by unknown authority

核心原因：证书路径错误、证书文件损坏，或 WSL 系统未信任该 CA 证书。

解决方案：

• 检查证书路径是否正确，确保 ca.crt 位于 ~/.docker/certs.d/<地址:端口>/ 目录下，且文件名正确（必须为 ca.crt）；

• 重启 WSL 终端，或执行 wsl --shutdown 关闭 WSL 后重新进入，刷新证书缓存；

• 手动更新 WSL 系统证书（可选）：
  sudo cp ~/.docker/certs.d/**/ca.crt /usr/local/share/ca-certificates/ sudo update-ca-certificates
  执行后会提示证书更新信息，忽略“ca-certificates.crt does not contain exactly one certificate”警告，不影响生效。

问题 2：WSL 无法访问宿主机证书路径（权限不足或路径错误）

核心原因：使用了错误的宿主机路径，或 WSL 对宿主机文件系统访问权限不足。

解决方案：

• 优先使用 /run/desktop/mnt/host/c/ 路径访问 Windows C 盘，替代 /mnt/c/，避免 WSL 2 路径挂载异常；

• 若提示权限不足，执行 sudo chmod 755 ~/.docker/certs.d/，赋予证书目录可读权限；

• 确认宿主机证书文件未被隐藏，且 Windows 文件夹共享权限已开启。

问题 3：Docker Desktop 证书自动同步后仍无法生效

核心原因：Docker Desktop 会自动将 Windows ~/.docker/certs.d 同步到 WSL 的 /etc/docker/certs.d，但可能存在同步延迟或权限问题。

解决方案：手动拷贝证书到 WSL 的 ~/.docker/certs.d 目录（按本文场景步骤操作），而非依赖自动同步；同步后重启 Docker Desktop 和 WSL，确保证书生效。

问题 4：WSL 执行 docker 命令提示 connection refused

核心原因：宿主机 Docker 未启动、WSL 集成未启用，或环境变量配置错误。

解决方案：

• 确认宿主机 Docker Desktop 已启动，且 WSL 集成功能已启用；

• 检查DOCKER_HOST 环境变量，确保地址和端口与宿主机 Docker 一致；

• 执行 unset DOCKER_HOST 清除错误环境变量，重新配置后生效。

四、总结与最佳实践

WSL 2 调用宿主机 Docker 配置私有证书，核心是让 WSL Docker 客户端能够识别并信任 CA 证书，不同场景对应不同的配置逻辑，可总结如下：

最佳实践建议

1. 开发环境优先使用“场景二”配置：若无需宿主机 Docker TLS 验证，仅配置私有仓库证书即可，操作更简洁，避免不必要的复杂配置；

2. 生产环境推荐“场景一”配置：启用 TLS 双向认证，提升宿主机 Docker 服务的安全性，防止未授权访问；

3. 证书管理：将私有证书统一存储在宿主机固定目录，WSL 按需拷贝，避免重复创建证书，便于后续维护和更新；

4. 异常排查：遇到证书问题时，优先检查证书路径、文件名和环境变量，再尝试重启 WSL 和 Docker Desktop，大部分问题可快速解决。

通过本文的配置步骤，可彻底解决 WSL 2 调用宿主机 Docker 时的私有证书信任问题，实现 WSL 与宿主机 Docker 的无缝协同，提升容器化开发效率。若遇到特殊场景（如多仓库证书配置、代理环境下的证书问题），可根据实际需求调整证书目录和配置参数。

使用MSYS2替代原生MinGW-w64搭建Qt 4.8.7 ARM32交叉编译环境，优势是MSYS2的包管理更便捷、依赖兼容性更强，且能完美兼容POSIX命令行环境（适配Qt 4.8.7的Unix风格编译脚本）。以下是基于MSYS2的完整实操指南，核心步骤与原生MinGW一致，但环境搭建环节适配MSYS2生态：

一、前置准备：下载清单（替换原生MinGW为MSYS2）

说明：MSYS2内置Python 2.7/Perl/CMake，无需单独安装，通过包管理器一键部署即可。

二、步骤1：安装并配置MSYS2

1.1 安装MSYS2

• 运行MSYS2安装包，默认安装到C:\msys64（禁止修改路径含中文/空格）；

• 安装完成后自动打开MSYS2终端，执行更新命令（首次更新需耐心等待）：

1

pacman -Syu

若终端提示“关闭后重启”，则关闭终端，重新打开MSYS2 MSYS终端，再次执行：

1

pacman -Su

1.2 安装MSYS2编译依赖（替代原生MinGW/Perl/Python/CMake）

打开MSYS2 MinGW64终端（关键：必须选MinGW64环境，而非MSYS环境），执行以下命令安装依赖：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 安装MinGW64 GCC（核心编译工具）
pacman -S --needed mingw-w64-x86_64-gcc

# 安装Python 2.7（Qt 4.8.7编译必需）
# pacman -S --needed mingw-w64-x86_64-python2
pacman -U https://repo.msys2.org/mingw/mingw64/mingw-w64-x86_64-python2-2.7.18-8-any.pkg.tar.zst

# 安装Perl（Qt编译脚本依赖）
pacman -S --needed mingw-w64-x86_64-perl

# 安装CMake（辅助编译）
pacman -S --needed mingw-w64-x86_64-cmake

# 安装make工具（mingw32-make）
pacman -S --needed mingw-w64-x86_64-make

# 安装依赖库（如zlib、libpng，Qt编译需）
pacman -S --needed mingw-w64-x86_64-zlib mingw-w64-x86_64-libpng mingw-w64-x86_64-libjpeg-turbo

1.3 验证MSYS2环境

在MinGW64终端执行以下命令，验证依赖安装成功：

1
2
3
4
5
6
7
8

# 验证GCC
gcc -v
# 验证Python 2.7
python2 --version
# 验证Perl
perl -v
# 验证make
mingw32-make -v

三、步骤2：配置ARM32交叉编译工具链（适配MSYS2）

2.1 解压Linaro工具链到MSYS2路径

• 下载Linaro工具链（如gcc-linaro-7.5.0-2019.12-i686-mingw32_arm-linux-gnueabihf.tar.xz）；

• 用7-Zip解压到MSYS2的目录下（建议路径：C:\msys64\opt\arm-linux-gnueabihf-7.5.0），避免路径含空格/中文。

2.2 配置MSYS2环境变量（永久生效）

• 打开MSYS2 MinGW64终端，编辑环境变量配置文件：

1

vi ~/.bashrc

• 在文件末尾添加以下内容（指定交叉工具链路径）：

1
2
3
4

# ARM交叉工具链路径
export PATH=/opt/arm-linux-gnueabihf-7.5.0/bin:$PATH
# 别名（可选，简化命令）
alias arm-gcc='arm-linux-gnueabihf-gcc'

• 生效配置：

1

source ~/.bashrc

2.3 验证交叉工具链

在MinGW64终端执行：

1

arm-linux-gnueabihf-gcc -v

输出Linaro 7.5.0版本信息则成功（若提示“找不到命令”，检查工具链解压路径是否正确）。

四、步骤3：修改Qt 4.8.7源码（与原生MinGW一致，适配MSYS2路径）

4.1 解压Qt源码到MSYS2路径

将Qt 4.8.7源码解压到MSYS2可识别的路径（如C:\msys64\home\你的用户名\qt-4.8.7-arm），MSYS2中路径表示为/home/你的用户名/qt-4.8.7-arm（避免Windows风格路径导致编译报错）。

4.2 修改交叉编译配置文件

复制并修改mkspecs配置文件（与原生MinGW步骤一致，仅路径适配MSYS2）：

1. 进入Qt源码目录：

1

cd /home/你的用户名/qt-4.8.7-arm

2. 复制并修改配置文件：

1
2
3
4

# 复制ARM配置模板
cp -r mkspecs/qws/linux-arm-gnueabi-g++ mkspecs/qws/linux-arm-gnueabihf-g++
# 编辑qmake.conf
vi mkspecs/qws/linux-arm-gnueabihf-g++/qmake.conf

3. 替换qmake.conf内容（与原生MinGW的配置一致，工具链前缀不变）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

MAKEFILE_GENERATOR      = UNIX
TEMPLATE                = app
CONFIG                  += qt warn_on release incremental link_prl gdb_dwarf_index
QT                      += core gui
QMAKE_INCREMENTAL_STYLE = sublib

# 交叉编译工具链前缀（匹配Linaro）
CROSS_COMPILE = arm-linux-gnueabihf-
CC              = $$CROSS_COMPILE gcc
CXX             = $$CROSS_COMPILE g++
LINK            = $$CROSS_COMPILE g++
AR              = $$CROSS_COMPILE ar cqs
RANLIB          = $$CROSS_COMPILE ranlib
STRIP           = $$CROSS_COMPILE strip
RC              = $$CROSS_COMPILE windres

# ARM架构参数（适配ARMv7）
QMAKE_CFLAGS            = -march=armv7-a -mtune=cortex-a9 -mfpu=neon -mfloat-abi=hard -O2
QMAKE_CXXFLAGS          = $$QMAKE_CFLAGS
QMAKE_LFLAGS            = -march=armv7-a -mtune=cortex-a9 -mfpu=neon -mfloat-abi=hard

# 系统库与路径（适配MSYS2）
QMAKE_INCDIR            = 
QMAKE_LIBDIR            = 
QMAKE_INCDIR_QT         = $$[QT_INSTALL_HEADERS]
QMAKE_LIBDIR_QT         = $$[QT_INSTALL_LIBS]
QMAKE_LIBS              = -lrt -ldl -lpthread
QMAKE_LIBS_QT_ENTRY     = -lQtCore -lQtGui
QMAKE_LIBS_GUI          = -lX11 -lXext -lXt -lm -lSM -lICE -lfontconfig -lfreetype
QMAKE_LIBS_CORE         = -lz -lm -ldl -lpthread

# 输出目录
DESTDIR                 = ../bin

五、步骤4：配置并编译Qt 4.8.7 ARM版本（MSYS2终端执行）

5.1 清理旧配置（首次编译可跳过）

1
2

cd /home/你的用户名/qt-4.8.7-arm
mingw32-make distclean

5.2 执行configure（核心：适配MSYS2路径）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

./configure -prefix /home/你的用户名/qt-4.8.7-arm-build \
            -opensource \
            -confirm-license \
            -release \
            -shared \
            -embedded arm \
            -xplatform qws/linux-arm-gnueabihf-g++ \
            -no-webkit \
            -no-phonon \
            -no-phonon-backend \
            -no-qt3support \
            -no-multimedia \
            -no-ltcg \
            -no-dbus \
            -no-opengl \
            -no-openvg \
            -no-svg \
            -no-javascript-jit \
            -no-script \
            -no-scripttools \
            -no-declarative \
            -no-declarative-debug \
            -nomake demos \
            -nomake examples \
            -nomake docs \
            -qt-libpng \
            -qt-libjpeg \
            -qt-zlib \
            -little-endian \
            -host-little-endian \
            -verbose

关键差异：-prefix使用MSYS2的Unix风格路径（/home/...），而非Windows路径（D:...），避免Qt配置解析路径出错。

5.3 编译Qt源码

1
2

# 多核编译（-j后接CPU核心数，如8核则-j8）
mingw32-make -j8

5.4 安装编译结果

1

mingw32-make install

安装完成后，/home/你的用户名/qt-4.8.7-arm-build（对应Windows路径C:\msys64\home\你的用户名\qt-4.8.7-arm-build）即为ARM交叉编译环境。

六、步骤5：验证交叉编译环境（MSYS2终端）

6.1 新建测试工程

在MSYS2中新建测试目录：

1
2

mkdir /home/你的用户名/qt-arm-test
cd /home/你的用户名/qt-arm-test

新建test.pro：

1
2
3
4

QT += core gui
TARGET = test
TEMPLATE = app
SOURCES += main.cpp

新建main.cpp：

1
2
3
4
5
6
7
8
9
10

#include <QApplication>
#include <QLabel>

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
    QLabel lbl("Hello ARM32 Qt 4.8.7 (MSYS2)!");
    lbl.show();
    return a.exec();
}

6.2 生成Makefile并编译

1
2
3
4

# 使用ARM版本的qmake
/home/你的用户名/qt-4.8.7-arm-build/bin/qmake -spec qws/linux-arm-gnueabihf-g++ test.pro
# 编译
mingw32-make

6.3 验证ARM程序

• 安装file命令（MSYS2终端）：

1

pacman -S file

• 验证程序架构：

1

file test

输出类似test: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), dynamically linked，说明成功。

七、MSYS2专属问题与解决

1. configure提示“bash: ./configure: 权限不够”：

2. 执行chmod +x configure赋予执行权限。

3. 编译时提示“找不到python”：

4. MSYS2中Python 2.7命令为python2，Qt 4.8.7默认找python，需创建软链接：

1

ln -s /mingw64/bin/python2.exe /mingw64/bin/python.exe

5. 工具链路径识别失败：

6. MSYS2中/opt对应Windows路径C:\msys64\opt，确保工具链解压到该路径，且~/.bashrc中PATH配置正确。

7. mingw32-make报错“recipe for target failed”：

8. 降低编译核心数（如-j4），避免内存不足；检查Qt源码路径是否含中文/空格。

总结

用MSYS2替代原生MinGW的核心优势是：

1. 无需手动安装Python/Perl/CMake，包管理器一键部署，版本兼容性更高；

2. POSIX终端环境更适配Qt 4.8.7的Unix风格编译脚本，减少路径/命令兼容问题；

3. 环境变量配置永久生效，无需频繁修改系统PATH。

核心注意点：全程使用MSYS2 MinGW64终端（而非MSYS终端/系统CMD），路径统一使用MSYS2的Unix风格路径（/home/...），避免Windows路径解析错误。

常用Grafana模板

Alloy配置模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

// 基础设施指标收集组件一般都是prometheus.exporter.*的形式, 见官方文档https://grafana.com/docs/alloy/latest/reference/components/prometheus/
// 目标组件, 这里目标组件是Linux
prometheus.exporter.unix "node" {}
 
// 抓取目标组件指标
prometheus.scrape "node" {
  // 源
  targets         = prometheus.exporter.unix.node.targets
  // 指标转发
  forward_to      = [prometheus.relabel.node.receiver]
  // 10s抓取一次指标
  scrape_interval = "10s"
}

// 筛选指标
// prometheus.relabel 组件通常用于筛选 Prometheus 指标或标准化传递给一个或多个下游接收器的标签集
prometheus.relabel "node" {
  // 将address或者instance替换成host
  rule {
    action        = "replace"
    source_labels = ["__address__", "instance"]
    separator     = "/"
    target_label  = "host"
  }
  // 处理完后转发到组件
  forward_to = [prometheus.remote_write.metrics_service.receiver]
}


prometheus.exporter.redis "redis" {
    redis_addr = "redis:6379"
    redis_password = "123456"
}

prometheus.scrape "redis" {
  targets    = prometheus.exporter.redis.redis.targets
  forward_to = [prometheus.remote_write.metrics_service.receiver]
}


// 指标发送到prometheus中
prometheus.remote_write "metrics_service" {
    endpoint {
        url = "http://prometheus:9090/api/v1/write"
    }
}

Docker EMQX 5.4 最大包长度配置

一、最大包长度配置（Docker Compose 方式）

1
2
3
4
5
6
7
8
9
10
11
12

services:
  emqx:
    image: emqx/emqx:5.4
    container_name: emqx
    environment:
      - EMQX_MQTT__MAX_PACKET_SIZE=10485760
    ports:
      - 1883:1883
      - 8083:8083
      - 8084:8084
      - 18083:18083
    restart: unless-stopped

二、最大包长度配置（Docker Run 方式）

1
2
3
4
5
6
7

docker run -d --name emqx \
  -e "EMQX_MQTT__MAX_PACKET_SIZE=10485760" \
  -p 1883:1883 \
  -p 8083:8083 \
  -p 8084:8084 \
  -p 18083:18083 \
  emqx/emqx:5.4

三、配置验证命令

1

docker exec -it emqx emqx_ctl get mqtt.max_packet_size

正常输出：mqtt.max_packet_size = 10485760（对应10MB）

四、常见启动报错修复

1. 最大包长度配置格式错误

错误：配置带MB单位（如10MB），导致启动失败

修复：使用纯数字（字节）配置，参考一、二章节命令

2. 配置文件挂载权限错误

报错特征：permission denied / cannot read config / bad config

1
2
3
4
5
6
7
8
9
10

# 停止并删除旧容器
docker stop emqx
docker rm emqx

# 改用环境变量启动（规避权限问题）
docker run -d --name emqx \
  -e "EMQX_MQTT__MAX_PACKET_SIZE=10485760" \
  -p 1883:1883 \
  -p 18083:18083 \
  emqx/emqx:5.4

3. 端口被占用

报错特征：address already in use

1
2
3
4
5
6
7
8
9
10
11
12

# 清理旧容器
docker stop emqx
docker rm emqx

# 重新启动
docker run -d --name emqx \
  -e "EMQX_MQTT__MAX_PACKET_SIZE=10485760" \
  -p 1883:1883 \
  -p 8083:8083 \
  -p 8084:8084 \
  -p 18083:18083 \
  emqx/emqx:5.4

4. 报错日志查看（精准定位问题）

1

docker logs emqx

五、总结

EMQX 5.4 最大包长度需用纯数字（字节）配置，启动报错优先排查配置格式、权限、端口占用，所有命令可直接复制执行，配置后需重启容器生效。

Ollama 作为轻量级本地大语言模型（LLM）管理工具，能够便捷地实现本地模型的部署、调度与交互。本文将从环境变量配置、CLI 核心命令、安装部署优化等维度，全方位讲解 Ollama 的使用方法，同时涵盖 WebUI 部署、Python/Java 客户端 API 集成等实战场景，帮助开发者高效管理和使用本地大模型。

一、核心环境变量配置

环境变量是定制 Ollama 运行行为的核心，通过合理配置可优化网络访问、模型管理、性能调度等关键环节，以下为高频实用的环境变量分类说明：

1. 网络配置：控制服务访问范围

2. 模型管理：优化存储与加载策略

3. 性能与调度：提升并发与资源利用率

4. 调试与日志：辅助问题排查

5. 特性开关：尝鲜实验性功能

6. 代理设置：适配网络访问场景

二、CLI 核心命令详解

Ollama 提供简洁的命令行工具（CLI）实现模型全生命周期管理，所有命令均可通过-h/--help查看详细用法，核心命令如下：

1. 基础命令速览

2. 高频命令实战

（1）启动服务：定制化启动参数

1
2
3
4
5

# 基础启动（默认配置）
ollama serve

# 带调试日志+自定义监听地址启动
OLLAMA_DEBUG=1 OLLAMA_HOST=0.0.0.0:8080 ollama serve

启动命令支持结合任意环境变量，实现服务的个性化配置。

（2）模型管理：从拉取到删除全流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 拉取模型（例如Llama 3 8B）
ollama pull llama3:8b

# 查看模型参数
ollama show llama3:8b --parameters

# 列出本地模型
ollama list

# 查看运行中的模型
ollama ps

# 停止运行中的模型
ollama stop llama3:8b

# 删除本地模型
ollama rm llama3:8b

（3）模型交互：终端高效验证

ollama run是终端验证模型的核心命令，支持直接传参或交互式对话：

1
2
3
4
5
6
7
8

# 基础运行模型
ollama run llama3:8b

# 带参数运行（指定响应格式为JSON+保持模型存活1小时）
ollama run llama3:8b --format json --keepalive 1h "请介绍Ollama的核心功能"

# 禁用自动换行+显示响应耗时
ollama run llama3:8b --nowordwrap --verbose

核心优势：

• 轻量化验证：无需依赖WebUI，终端直连模型快速验证响应效果；

• 可记录输出：通过>将响应写入文件（如ollama run llama3:8b "提问内容" > response.txt）；

• 自动化适配：可嵌入脚本实现定时交互、批量问答等自动化流程。

三、Ollama 安装与系统参数最佳实践

1. 快速安装

Ollama 支持全平台部署，可从官方官网下载对应系统安装包（Windows/MacOS/Linux），安装流程与常规软件一致，无额外依赖。

2. 必配系统环境变量（优化体验）

安装完成后，建议配置以下环境变量提升使用体验：

总结

Ollama 凭借轻量化、易配置、跨平台的特性，成为本地大模型管理的首选工具。通过合理配置环境变量，可精准控制服务的网络、性能、资源使用；借助 CLI 命令，可高效完成模型的全生命周期管理；结合 WebUI 或多语言 API，还能进一步扩展交互形式与应用场景。无论是本地验证模型效果，还是搭建私有化大模型服务，Ollama 都能通过灵活的配置和简洁的操作满足多样化需求。

Longhorn 单机部署指南

Longhorn 支持单机部署，它是一款基于 Kubernetes 的分布式块存储系统，同时也可以在单节点 Kubernetes 集群中完成部署和使用，适合开发测试、边缘计算等轻量场景。

一、单机部署的核心前提

1. 环境要求

   1. 单节点 Kubernetes 集群（如 Minikube、k3s、MicroK8s 或手动搭建的单节点集群）

   2. 节点满足 Longhorn 基础条件：

      • 操作系统：Linux（内核 4.14+）

      • 容器运行时：Docker、containerd 等

      • 磁盘：至少 1 块空闲磁盘或目录（用于存储数据）

      • 依赖工具：open-iscsi（必须安装并启动）

2. 网络要求

   1. 节点能访问互联网（用于拉取 Longhorn 镜像）

   2. Kubernetes 集群网络插件正常运行（如 Calico、Flannel）

二、单机部署的具体步骤（以 k3s 为例）

1. 部署单节点 k3s 集群

1
2
3
4

# 安装 k3s（禁用默认存储，避免冲突）
curl -sfL https://get.k3s.io | sh -s - --disable local-storage
# 配置 kubectl 环境变量
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

2. 安装依赖组件 open-iscsi

1
2
3
4
5
6
7

# Ubuntu/Debian
sudo apt update && sudo apt install -y open-iscsi
sudo systemctl enable --now iscsid

# CentOS/RHEL
sudo yum install -y iscsi-initiator-utils
sudo systemctl enable --now iscsid

3. 部署 Longhorn

推荐使用 Helm 部署（更易管理）：

1
2
3
4
5
6
7
8
9

# 安装 Helm 3
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# 添加 Longhorn Helm 仓库
helm repo add longhorn https://charts.longhorn.io
helm repo update

# 部署 Longhorn 到 longhorn-system 命名空间
helm install longhorn longhorn/longhorn --namespace longhorn-system --create-namespace

4. 验证部署状态

1
2
3
4
5
6

# 检查 Pod 是否全部 Running
kubectl -n longhorn-system get pods

# 检查 Longhorn 存储类是否创建
kubectl get sc
# 正常会看到 longhorn 存储类，且标注为 default

三、单机部署的注意事项

1. 高可用限制

   1. 单机部署下，Longhorn 无法提供数据冗余（默认副本数为 3，需手动调整为 1），节点故障会导致数据丢失，仅适合非生产环境。

   2. 修改副本数：在 Longhorn UI 中设置默认副本数为 1，或在 PVC 注解中指定 numberOfReplicas: 1。

2. 存储路径配置

   1. 如果节点没有空闲磁盘，可以指定目录作为存储后端：

      1 2 3 4 5 6

      # 创建本地目录 sudo mkdir -p /data/longhorn sudo chmod 777 /data/longhorn # 部署时通过 Helm 参数指定 helm install longhorn longhorn/longhorn --namespace longhorn-system --create-namespace \ --set defaultSettings.defaultDataPath=/data/longhorn

3. 访问 Longhorn UI

   1. 单机环境下可通过 NodePort 访问 UI：

      1 2	kubectl -n longhorn-system get svc longhorn-frontend # 访问 http://<节点IP>:<NodePort>

四、单机部署的适用场景

• 开发/测试环境：快速验证 Longhorn 功能、测试存储与应用的兼容性。

• 边缘节点：资源受限的边缘设备，仅需单节点提供块存储。

• 个人学习：熟悉 Kubernetes 存储编排和 Longhorn 运维操作。

是否需要我为你整理单机部署 Longhorn 后的测试用例，比如创建 PVC 并挂载到 Nginx 容器进行验证？