核心功能与特性

• 🌐 超强跨平台支持：全面覆盖 Windows、macOS、Linux、Android、iOS 和 Web 网页端。由于系统限制，iOS 设备仅支持投屏，无法作为被控端。
• 🔒 安全与自托管：提供免费的中继服务器程序，用户可在自己的 VPS 或本地 NAS（支持 Docker）上自建 RustDesk 中继服务器，彻底摆脱第三方 SaaS 平台的稳定性和隐私限制。
• 🚀 高效编解码：支持 H.264/H.265 硬件加速以及 VP8/VP9/AV1 软件编解码，即使在低带宽下也能通过调整画质和帧率来保证流畅度。
• 🛠️ 免安装与高级功能：在 Windows 系统上支持免管理员权限

为什么自建 RustDesk 服务端

工作原理

两个核心组件：

• hbbs（ID 服务器）：端口 21114-21116。负责设备注册、发现，提供 Web 后台和 API 服务
• hbbr（中继服务器）：端口 21117-21119。P2P 直连失败时盲转发加密数据包

连接流程：

1. 被控端启动 → 向 hbbs 注册（提交设备 ID 和网络信息）
2. 控制端向 hbbs 查询目标设备 → 尝试 P2P 直连（低延迟）
3. 直连失败（NAT 穿透失败）→ 双方通过 hbbr 中继转发，端到端加密，hbbr 无法解密

步骤 1：准备服务器

需一台有公网 IP 的 Linux 服务器：

2 核 2G

带宽建议 ≥ 5Mbps

步骤 2：安装 Docker

1

ssh root@你的服务器IP

访问 https://getdocker.quickso.cn

一键安装Docker

步骤 3：部署服务端

创建项目目录

1

mkdir -p /opt/rustdesk-server && cd /opt/rustdesk-server

编写 docker-compose.yaml

1

nano docker-compose.yaml

写入（将 <IP> 替换为服务器公网 IP或者你的域名）：

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

services:
  rustdesk:
    image: lejianwen/rustdesk-server-s6:latest
    ports:
      - 21114:21114
      - 21115:21115
      - 21116:21116
      - 21116:21116/udp
      - 21117:21117
      - 21118:21118
      - 21119:21119
    environment:
      - RELAY=<IP>:21117
      - ENCRYPTED_ONLY=1
      - MUST_LOGIN=N
      - TZ=Asia/Shanghai
      - RUSTDESK_API_RUSTDESK_ID_SERVER=<IP>:21116
      - RUSTDESK_API_RUSTDESK_RELAY_SERVER=<IP>:21117
      - RUSTDESK_API_RUSTDESK_API_SERVER=http://<IP>:21114
      - RUSTDESK_API_KEY_FILE=/data/id_ed25519.pub
      - RUSTDESK_API_JWT_KEY=
    volumes:
      - ./data/server:/data
      - ./data/api:/app/data
    networks:
      - rustdesk-net
    restart: unless-stopped

networks:
  rustdesk-net:
    external: false

📝 关键变量说明：

变量	说明
ENCRYPTED_ONLY=1	仅允许加密连接（强烈推荐保留）
MUST_LOGIN=N	N = 允许匿名连接；Y = 必须登录账户才能用

启动服务

1

docker compose up -d

开放防火墙

云控制台：安全组 → 入方向 → 添加 TCP 21114-21119 + UDP 21116，来源 0.0.0.0/0。

服务器本地：

1
2
3
4
5
6
7

# Ubuntu/Debian
ufw allow 21114:21119/tcp && ufw allow 21116/udp

# CentOS/RHEL
firewall-cmd --add-port=21114-21119/tcp --permanent
firewall-cmd --add-port=21116/udp --permanent
firewall-cmd --reload

步骤 4：获取 Key 和密码

Key（公钥）

所有客户端连接服务端的凭证，必须妥善保存：

1

cat /opt/rustdesk-server/data/server/id_ed25519.pub

输出类似 OQd8dJxxxxxxxxxxxxxxxxxxxxxxx=，复制到安全位置备用。

管理员密码

1

docker compose logs | grep Password

输出类似 Initial admin password: AbCd1234。此密码仅首次启动生成，建议立即登录后台修改。

步骤 5：后台管理

浏览器访问 http://你的服务器IP:21114。

• 用户名：admin
• 密码：上一步获取的随机密码

💡 登录后立即修改默认密码，并为家人/同事创建独立子账户。

步骤 6：客户端配置（Windows\MacOS\Linux\安卓\iOS）

① 下载 RustDesk

https://github.com/rustdesk/rustdesk/releases/latest

选择 你的客户端版本。

② 网络设置（两端都需要）

1. 打开 RustDesk → 左侧「网络」→ 右上角「解锁」
2. 填写：

1. 点击「应用」

右上角可复制/粘贴配置，多设备快速部署。

③ 被控端设置

「安全」→ 解锁 → 密码 → 选择「使用固定密码」→ 设置强密码。

④ 账户登录（两端）

点击底部用户图标 → 用 admin 或子账户登录。登录后可在设备列表直接看到在线设备，双击连接。

⑤ 仅控制他人时

「常规」→ 服务 → 点击「停止」，避免自身成为被控端。

步骤 7：安全加固与维护

强制账户登录

编辑 docker-compose.yaml：

1

- MUST_LOGIN=Y

重启：

1

docker compose down && docker compose up -d

之后未登录用户无法使用，防止未授权接入。

定期备份

1

tar -czf rustdesk-backup-$(date +%Y%m%d).tar.gz /opt/rustdesk-server/data/

更新服务端

1
2
3

cd /opt/rustdesk-server
docker compose pull
docker compose down && docker compose up -d

安全速查

在 RemoteDesk 中使用

配置自建服务器

在 RemoteDesk 的 RustDesk 设置中填写：

添加主机

常见问题排查

Q: 客户端显示「未连接到服务器」？

→ ① 确认云安全组已开放全部 7 个端口（TCP 21114-21119 + UDP 21116）
→ ② 确认 Key 完整粘贴，无多余空格换行
→ ③ 确认 ID 服务器格式为 IP:21116（不带 http://）
→ ④ docker compose ps 确认容器状态为 Up

Q: 连接上了但非常卡？

→ P2P 直连失败，走了中继转发。优化：确保安全组开放 UDP 21116（打洞依赖），临时关闭 Windows 防火墙测试，升级服务器带宽。

Q: Web 后台 502 / 无法访问？

→ docker compose ps 确认运行中 → 安全组确认 TCP 21114 开放 → 浏览器用 http:// 而非 https://

Q: 如何查看当前连接状态？

→ docker compose logs --tail=50 查看实时日志。

参考文档

https://lijiong.online/2026/06/22/RustDesk%E8%87%AA%E5%BB%BA%E6%9C%8D%E5%8A%A1%E5%99%A8%E6%95%99%E7%A8%8B/

https://www.liups.net/2026/05/docker-%E8%87%AA%E5%BB%BA-rustdesk-%E8%BF%9C%E7%A8%8B%E5%92%8C-api-%E6%9C%8D%E5%8A%A1/

https://hoshiroko.com/posts/course/rustdesk

llama.cpp 是一个高性能的 C/C++ 本地推理引擎，支持在各种硬件上高效运行 LLM 模型。本文将详细介绍如何在国内和通用环境下正确部署 llama.cpp。

为什么选择 llama.cpp

• ⚡ 高性能：极致优化的推理引擎，支持多种硬件加速
• 🔧 纯 C/C++ 实现：无 Python 依赖，编译后即可运行
• 📱 多平台支持：支持 x86、ARM、Apple Silicon 等
• 🧠 量化支持：支持 4-bit、5-bit、8-bit 等量化格式
• 🔌 多种前端：支持命令行、服务器模式、嵌入式设备

官方链接

一、国内部署方式

前置条件

在开始之前，需要安装编译环境：

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

# Windows 用户推荐使用 MSYS2 或 WSL2
# 安装 MSYS2 后执行：
pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-make cmake

# Linux (Ubuntu/Debian)
sudo apt update
sudo apt install build-essential cmake git

# Linux (CentOS/RHEL)
sudo yum groupinstall "Development Tools"
sudo yum install cmake git

# macOS
# 只需安装 Xcode Command Line Tools
xcode-select --install

方式一：获取源码

方法 1：使用 Gitee 镜像克隆（推荐）

1
2
3

# 使用 Gitee 国内镜像克隆
git clone https://gitee.com/mirrors/llama-cpp.git
cd llama-cpp

方法 2：GitHub 加速访问

1
2
3
4
5
6

# 使用 GitHub 代理加速克隆
git clone https://gh-proxy.com/https://github.com/ggml-org/llama.cpp.git
cd llama.cpp

# 或者直接下载 ZIP 压缩包
# https://gh-proxy.com/https://github.com/ggml-org/llama.cpp/archive/master.zip

方法 3：从国内平台下载

1
2
3
4
5

# Gitee 镜像下载
# https://gitee.com/mirrors/llama-cpp

# 华为云代码托管
# https://repo.huaweicloud.com/

方式二：国内编译方法

1. 编译 llama.cpp

使用 CMake 编译（推荐）：

1
2
3
4
5
6
7
8
9
10

# 创建构建目录
mkdir build && cd build

# 配置编译选项
cmake .. -DCMAKE_BUILD_TYPE=Release

# 编译（-j 后面跟 CPU 核心数）
make -j$(nproc)

# 可执行文件在 build/bin/ 目录下

Makefile 方式：

1
2
3
4
5

# 简单编译
make

# 指定优化级别编译
make LLAMA_NATIVE=1

2. 国内下载模型

由于 HuggingFace 在国内访问较慢，可以使用以下方式下载模型：

方法一：使用 ModelScope（魔搭社区）

1
2
3
4

# 访问 ModelScope
# https://www.modelscope.cn/

# 搜索 GGUF 格式模型下载

方法二：使用国内 HuggingFace 镜像

1
2
3
4
5

# 设置 HuggingFace 镜像源
export HF_ENDPOINT=https://hf-mirror.com

# 使用 huggingface-cli 下载
hf download ggml-org/models llama2-7b.Q4_0.gguf

方法三：手动下载

1. 访问 ModelScope 或其他国内模型站点
2. 搜索 llama.cpp 支持的 GGUF 格式模型
3. 下载后放入指定目录

方式三：Docker 部署（国内镜像）

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

# 使用国内 Docker 镜像源
# 修改 /etc/docker/daemon.json，添加：
{
  "registry-mirrors": [
    "https://docker.1ms.run",
  ]
}

# 拉取 llama.cpp Docker 镜像
docker pull registry.cn-hangzhou.aliyuncs.com/library/llama-cpp:latest

# 或者使用 NVIDIA 官方镜像（如有 GPU）
docker pull registry.cn-hangzhou.aliyuncs.com/nvidia/llama-cpp:latest

国内常见问题

下载源码慢怎么办？

使用国内 Gitee 镜像或 GitHub 加速代理：

• Gitee 镜像: https://gitee.com/mirrors/llama-cpp
• GitHub 加速: https://gh-proxy.com/

模型下载慢怎么办？

使用 ModelScope 国内平台：

• https://www.modelscope.cn/

编译依赖下载失败？

可以提前下载依赖源码，或使用国内 npm/maven 镜像源。

二、通用部署方式

前置条件

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

# Windows
# 安装 Visual Studio Build Tools 或 MSYS2
# 下载地址：https://visualstudio.microsoft.com/downloads/

# Linux (Ubuntu/Debian)
sudo apt update
sudo apt install build-essential cmake git

# Linux (Fedora)
sudo dnf groupinstall "Development Tools"
sudo dnf install cmake git

# macOS
xcode-select --install

方式一：从源码编译（推荐）

1. 克隆仓库

1
2
3

# 克隆 llama.cpp 仓库
git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp

2. 编译

基础编译：

1
2
3
4

# 使用 CMake（推荐）
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

带 GPU 加速编译（NVIDIA CUDA）：

1
2
3
4
5

mkdir build && cd build
cmake .. \
  -DCMAKE_BUILD_TYPE=Release \
  -DGGML_CUDA=ON
make -j$(nproc)

带 Metal 加速编译（Apple Silicon）：

1
2
3
4

# macOS 默认支持 Metal，直接编译即可
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(sysctl -n hw.ncpu)

带 OpenCL 加速编译：

1
2
3
4
5

mkdir build && cd build
cmake .. \
  -DCMAKE_BUILD_TYPE=Release \
  -DGGML_OPENCL=ON
make -j$(nproc)

编译选项说明：

3. 下载模型

从 HuggingFace 下载：

1
2
3
4
5
6
7
8
9

# 安装 huggingface-hub
pip install huggingface-hub

# 下载 GGUF 格式模型
hf download ggml-org/models llama2-7b.Q4_0.gguf

# 或者指定下载目录
hf download ggml-org/models llama2-7b.Q4_0.gguf \
  --local-dir ./models

从modelscope下载：

1
2

pip install modelscope
modelscope download --model unsloth/Qwen3.5-4B-GGUF Qwen3.5-4B-Q4_K_M.gguf --local_dir ./models

常用 GGUF 模型地址：

• https://huggingface.co/ggml-org/models
• https://huggingface.co/TheBloke（量化模型集合）

方式二：Docker 部署

使用官方 Docker 镜像

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

# 拉取官方镜像
docker pull ghcr.io/ggml-org/llama.cpp:latest

# 运行容器
docker run -d \
  --name llama-cpp \
  -v $(pwd)/models:/models \
  -p 8080:8080 \
  ghcr.io/ggml-org/llama.cpp:latest \
  --model /models/llama2-7b.Q4_0.gguf \
  --host 0.0.0.0 \
  --port 8080

# 查看日志
docker logs -f llama-cpp

使用 NVIDIA GPU 加速

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

# 确保已安装 NVIDIA Container Toolkit
# https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html

# 运行带 GPU 的容器
docker run -d \
  --name llama-cpp-gpu \
  --gpus all \
  -v $(pwd)/models:/models \
  -p 8080:8080 \
  ghcr.io/ggml-org/llama.cpp:latest \
  --model /models/llama2-7b.Q4_0.gguf \
  --host 0.0.0.0 \
  --port 8080 \
  --cuda

三、使用方法

命令行运行

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

# 运行模型（交互式）
./build/bin/llama-cli -m ./models/llama2-7b.Q4_0.gguf

# 指定参数运行
./build/bin/llama-cli \
  -m ./models/llama2-7b.Q4_0.gguf \
  -t 8 \                    # 使用 8 个线程
  -n 256 \                  # 最大生成 token 数
  -c 4096 \                 # 上下文窗口大小
  -p "你好，请介绍一下自己"  # 提示词

# 批量处理
echo "你好" | ./build/bin/llama-cli -m ./models/llama2-7b.Q4_0.gguf

服务器模式

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

# 启动 HTTP 服务器
./build/bin/llama-server \
  -m ./models/llama2-7b.Q4_0.gguf \
  --host 0.0.0.0 \
  --port 8080

# 使用 API 调用
curl http://localhost:8080/completion -d '{
  "prompt": "你好",
  "n_predict": 128,
  "temperature": 0.7
}'

模型量化

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

# 安装量化工具依赖
pip install -r requirements.txt

# 下载原始模型（HuggingFace 格式）
# 从 huggingface.co 下载原始 HuggingFace 模型

# 转换为 F16 格式
python convert-hf-to-gguf.py /path/to/model \
  --output-dir ./models \
  --outtype f16

# 量化为 Q4_K_M 格式（推荐）
./build/bin/llama-quantize \
  ./models/model-f16.gguf \
  ./models/model-q4_k_m.gguf \
  Q4_K_M

# 量化格式说明：
# Q2_K, Q3_K_S, Q3_K_M, Q3_K_L, Q4_0, Q4_K_S, Q4_K_M, Q5_0, Q5_K_S, Q5_K_M, Q8_0

Python API 调用

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

import requests

# llama.cpp 服务器 API
BASE_URL = "http://localhost:8080"

# 发送请求
response = requests.post(f"{BASE_URL}/completion", json={
    "prompt": "Hello, introduce yourself",
    "n_predict": 128,
    "temperature": 0.7,
    "top_p": 0.9,
    "stop": ["\n"]
})

# 处理响应
result = response.json()
print(result["content"])

使用 llama-cpp-python

1
2
3
4
5

# 安装 Python 绑定
pip install llama-cpp-python

# 如果需要从源码编译
CMAKE_ARGS="-DGGML_CUDA=ON" pip install llama-cpp-python

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

from llama_cpp import Llama

# 加载模型
llm = Llama(
    model_path="./models/llama2-7b.Q4_0.gguf",
    n_ctx=4096,
    n_gpu_layers=-1  # -1 表示使用所有 GPU 层
)

# 生成文本
output = llm(
    "Q: 你好，请介绍一下自己\nA: ",
    max_tokens=128,
    stop=["\n"]
)

print(output["choices"][0]["text"])

# 聊天模式
output = llm.create_chat_completion(
    messages=[
        {"role": "user", "content": "你好"}
    ],
    max_tokens=128
)

print(output["choices"][0]["message"]["content"])

四、常见问题

编译错误怎么办？

1
2
3
4
5
6
7
8
9

# 确保编译环境完整
# Ubuntu/Debian
sudo apt install build-essential cmake git python3

# 清理后重新编译
rm -rf build
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j$(nproc)

显存/内存不足？

1
2
3
4
5
6
7
8

# 使用更小的模型
# Q2_K < Q3_K < Q4_K < Q5_K < Q8_0 < F16

# 减小上下文窗口
./build/bin/llama-cli -m model.gguf -c 2048

# 使用更少的线程
./build/bin/llama-cli -m model.gguf -t 4

如何选择量化级别？

模型不支持怎么办？

1. 检查模型格式是否为 GGUF
2. 参考 llama.cpp 的 README.md 查看支持的模型列表
3. 某些新模型可能需要最新版本的 llama.cpp

性能优化建议

1
2
3
4
5
6
7
8
9
10

# 使用 GPU 加速（如有）
# NVIDIA CUDA: 编译时加 -DGGML_CUDA=ON
# Apple Silicon: 默认启用 Metal
# AMD: 编译时加 -DGGML_VULKAN=ON

# 使用适当的线程数
./build/bin/llama-cli -m model.gguf -t $(nproc)

# 启用 KV Cache（默认开启）
# 可以提升长文本处理速度

五、进阶配置

环境变量

配置开机自启（Linux 服务器）

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

# 创建 systemd 服务
sudo nano /etc/systemd/system/llama-cpp.service

# 添加以下内容
[Unit]
Description=llama.cpp Server
After=network.target

[Service]
ExecStart=/path/to/llama-server \
  -m /path/to/model.gguf \
  --host 0.0.0.0 \
  --port 8080
User=your_username
Restart=always
RestartSec=5

[Install]
WantedBy=default.target

# 启用服务
sudo systemctl daemon-reload
sudo systemctl enable llama-cpp
sudo systemctl start llama-cpp

多模型服务

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

# 创建 systemd 服务
sudo nano /etc/systemd/system/llama-cpp.service

# 添加以下内容
[Unit]
Description=llama.cpp Server
After=network.target

[Service]
ExecStart=/root/llama.cpp/build/bin/llama-server \
  --models-dir /root/llama.cpp/models \
  --host 0.0.0.0 \
  --port 8080
User=root
Restart=always
RestartSec=5

[Install]
WantedBy=default.target

# 启用服务
sudo systemctl daemon-reload
sudo systemctl enable llama-cpp
sudo systemctl start llama-cpp

适用场景

• 💻 高性能本地推理
• 📱 嵌入式设备 AI
• 🔧 模型转换与量化
• 🏢 私有化部署
• 🎓 AI 研究与教学
• ⚙️ 定制化 AI 应用

随着 Qwen、Llama、DeepSeek 等开源大模型越来越成熟，本地部署已经成为很多开发者的选择。

目前最轻量、最流行的推理框架之一就是 llama.cpp。

https://llama.app/

https://github.com/ggml-org/llama.cpp

它具有以下特点：

• 支持 Windows、Linux、macOS
• 支持 CPU 推理
• 支持 NVIDIA CUDA
• 支持 AMD ROCm
• 支持 Apple Metal
• 支持 OpenAI API
• 支持 GGUF 模型
• 部署简单，占用资源少

本文介绍如何使用 llama.cpp 完整部署本地大模型。

一、什么是 GGUF

GGUF 是 llama.cpp 官方推荐的模型格式。

优点：

• 加载速度快
• 支持量化
• 节省内存
• CPU/GPU 都支持

例如：

1

Qwen3-4B-Q4_K_M.gguf

其中：

一般推荐：

1

Q4_K_M

二、安装依赖

Debian / Ubuntu：

1
2
3
4
5
6
7
8

sudo apt update

sudo apt install -y \
git \
cmake \
build-essential \
libopenblas-dev \
numactl

三、下载 llama.cpp

1
2
3

git clone https://github.com/ggml-org/llama.cpp.git

cd llama.cpp

四、编译

CPU 版本

使用

1

lscpu

查看CPU是否支持 AVX2/AVX512
如果 CPU 支持 AVX2/AVX512 使用下面编译

1
2
3

cmake -B build -DCMAKE_BUILD_TYPE=Release

cmake --build build -j$(nproc)

如果你的 CPU 不支持 AVX2/AVX512，不用强行开启相关优化，直接使用：

1
2
3

cmake -B build -DCMAKE_BUILD_TYPE=Release

cmake --build build -j40

编译完成：

1
2

build/bin/llama-cli
build/bin/llama-server

为了缩短时间，你还可以根据你的CPU核心数开启并行编译，例如：

1

cmake --build build --config Release -j 8

这将以8个并行编译任务来构建程序。

NVIDIA GPU（CUDA）

如果安装好了 CUDA：

1
2
3
4
5

cmake -B build \
-DGGML_CUDA=ON \
-DCMAKE_BUILD_TYPE=Release

cmake --build build -j$(nproc)

即可启用 GPU 推理。

AMD 显卡（ROCm）

1
2

cmake -B build \
-DGGML_HIPBLAS=ON

Apple Silicon

1
2

cmake -B build \
-DGGML_METAL=ON

五、下载模型

必须下载 GGUF。

推荐来源：

1、ModelScope（国内推荐）

https://modelscope.cn

搜索：

1

Qwen GGUF

在下载前，请先通过如下命令安装ModelScope

1
2

apt install python3 python3-pip
pip install modelscope

下载：

1

modelscope download --model unsloth/Qwen3-4B-GGUF Qwen3-4B-Q4_K_M.gguf --local_dir /root/llama.cpp/models

2、Hugging Face

https://huggingface.co

国内镜像站:https://hf-mirror.com/

搜索：

1

Qwen GGUF

1

huggingface-cli download <model_repo> <gguf_file> --local-dir <local_dir>

下载完成后放入：

1
2
3

llama.cpp/
    models/
        Qwen3-4B-Q4_K_M.gguf

六、CPU推理

例如：

1

./build/bin/llama-cli -m ./models/Qwen3-4B-Q4_K_M.gguf -t 20 -c 8192 --color auto --chat-template chatml --temp 0.7 --top-p 0.9

参数说明：

七、GPU 推理

如果使用 CUDA：

1
2
3

./build/bin/llama-cli \
-m models/Qwen3-4B-Q4_K_M.gguf \
-ngl 999

说明：

1

-ngl 999

表示尽可能把模型放到 GPU。

如果显存不足：

1

-ngl 20

只加载部分层。

八、启动 API 服务

推荐：

1
2
3
4
5
6
7

./build/bin/llama-server \
-m models/Qwen3-4B-Q4_K_M.gguf \
-t 20 \
-c 4096 \
-b 256 \
--host 0.0.0.0 \
--port 8000

启动成功：

1

http://服务器IP:8000

OpenAI API：

1

POST /v1/chat/completions

九、测试 API

1
2
3
4
5
6
7
8

curl http://127.0.0.1:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model":"Qwen",
"messages":[
{"role":"user","content":"你好"}
]
}'

十、开机启动（systemd）

创建：

1

sudo nano /etc/systemd/system/llama.service

内容：

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

[Unit]
Description=llama.cpp API Server
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/llama.cpp

ExecStart=/opt/llama.cpp/build/bin/llama-server \
-m /opt/llama.cpp/models/Qwen3-4B-Q4_K_M.gguf \
-t 20 \
-c 4096 \
-b 256 \
--host 0.0.0.0 \
--port 8000

Restart=always

[Install]
WantedBy=multi-user.target

启动：

1
2
3
4
5

sudo systemctl daemon-reload

sudo systemctl enable llama

sudo systemctl start llama

查看日志：

1

journalctl -u llama -f

十一、CPU 参数建议

推荐：

1

-t = 物理核心数

例如：

一般不要直接使用超线程数量。

十二、GPU 参数建议

RTX4060：

1
2

Qwen3-4B
Qwen3-8B

RTX3090：

1
2

Qwen3-14B
Qwen3-32B

RTX4090：

1
2
3

DeepSeek-R1 Distill
Qwen3-32B
Llama3-70B（量化）

十三、模型推荐

推荐量化：

1

Q4_K_M

十四、性能优化

安装 OpenBLAS：

1

sudo apt install libopenblas-dev

NUMA：

1
2

numactl --interleave=all \
./build/bin/llama-server ...

CPU 性能模式：

1

sudo cpupower frequency-set -g performance

大内存服务器可以考虑：

1

--mlock

减少模型被交换到磁盘。

十五、常见问题

找不到模型

确认：

1

-m models/Qwen3-4B-Q4_K_M.gguf

路径正确。

CPU 很慢

• 使用 Q4_K_M 量化。
• 线程数设置为物理核心数。
• 安装 OpenBLAS。
• 使用 numactl 优化双路服务器。

GPU 未生效

确认编译时启用了 CUDA：

1

cmake -B build -DGGML_CUDA=ON

启动时：

1

-ngl 999

并通过 nvidia-smi 检查显存占用。

总结

llama.cpp 是目前本地部署大模型最轻量、兼容性最好的推理框架之一，无论是仅有 CPU 的服务器还是配备 NVIDIA GPU 的工作站，都可以快速部署 GGUF 模型，并提供 OpenAI 兼容 API，方便与 Cherry Studio、Open WebUI、LangChain 等工具集成。

对于生产环境，建议：

• CPU 环境：选择 Q4_K_M 量化模型，线程数设置为物理核心数，配合 OpenBLAS 与 numactl 优化。
• GPU 环境：启用 CUDA 编译，并使用 -ngl 999 尽可能将模型加载到显卡。
• 服务部署：通过 llama-server 提供 OpenAI API，并结合 systemd 实现开机自启动，便于长期稳定运行。

这套方案适合个人开发、企业内部知识库、AI 助手和本地推理服务等多种场景。

https://www.fedoraproject.org/zh-Hans/

Ubuntu

https://cn.ubuntu.com/desktop

这里我们使用Gnome桌面版本，体验比较像MacOS

安装

安装系统

将 https://ventoy.net/ 写入U盘，下载iso镜像丢进去，U盘启动即可。详细步骤略

配置系统

1.修改root密码

1

sudo passwd root

2.升级(root)

1

dnf update

1

apt update && apt upgrade

3.修改flatpak 国内源

1
2

flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepo
flatpak remote-modify flathub --url=https://mirrors.ustc.edu.cn/flathub

zsh 安装与配置

参考 https://www.haoyep.com/posts/zsh-config-oh-my-zsh/

Gnome相关

GNOME Tweaks 是一款用于个性化桌面体验的工具，它允许用户自定义默认字体、窗口管理、工作区等多个方面。

1

sudo dnf install gnome-tweaks

1

sudo apt install gnome-tweaks

安装官方的拓展管理应用

1

dnf install gnome-extensions-app

1

apt install gnome-extensions-app

安装完成后，你可以在应用程序菜单中找到 “扩展” (Extensions) 图标。它是管理已安装插件的“开关”，支持开启、关闭以及进入插件的详细设置。

如何获取与安装新扩展

除了通过 DNF 安装部分系统级扩展外，最灵活的方式是使用浏览器插件：

访问官网：

https://extensions.gnome.org

安装集成组件：浏览器会提示安装“GNOME Shell integration”扩展，点击允许并安装。

开启插件：在网页中找到心仪的扩展，直接点击右上角的 ON/OFF 开关即可自动下载并启用。

必装扩展推荐

针对追求高效、美观与系统监控的用户，以下扩展值得尝试：

1. 桌面布局与效率类

• Dash to Dock：将顶部的收藏栏（Dash）转换为类似 macOS 的固定 Dock 栏，支持自动隐藏。

• Dash to Panel：将顶栏与 Dock 合二为一，模仿 Windows 任务栏布局，非常适合习惯单底栏操作的用户。

• Just Perfection：GNOME 界的“瑞士军刀”。它可以让你隐藏几乎任何不需要的 UI 元素（如搜索框、顶栏时钟、辅助功能图标等），实现极致纯净的桌面。

2. 美化与 UI 增强类

• Blur my Shell：为 GNOME 的活动概览界面、面板和 Dash 添加精美的毛玻璃（高斯模糊）效果，瞬间提升桌面高级感。

• User Themes：允许从用户目录下加载自定义的 Shell 主题，是深度定制皮肤的必备前提。

• AppIndicator and KStatusNotifierItem Support：让托盘图标（如 Discord、网易云音乐、Telegram）重新出现在顶栏右侧，解决 GNOME 默认不显示第三方应用图标的问题。

• Coverflow Alt-Tab: 改进 Alt+Tab 切换窗口的视觉效果，采用类似macOS的Coverflow立体翻转样式。

• compiz-alike-magic-lamp-effect: 为窗口最小化添加类似Compiz的“魔灯”缩放动画效果。

3. 功能增强类

• Clipboard Indicator：在顶栏添加剪贴板历史记录。对于开发者和文字工作者来说，这是大幅提升生产力的工具。

• Vitals：在顶栏实时监控 CPU 温度、频率、内存使用率、风扇转速以及网络速度。它的 UI 设计非常简洁，不会显得杂乱。

• Caffeine ：关闭屏幕保护程序和自动挂起

安装rime中文输入法

1

dnf install ibus-table ibus-rime

1

apt install ibus-table ibus-rime

Tips：

1.修改文字排列为横列

1
2
3

nano ~/.config/ibus/rime/build/ibus_rime.yaml
修改
horizontal: true

2.将候选词从默认的繁体改为简体
中文输入法前提下，按F4键或者ctrl+~选择“朙月・简化字”

3.将候选词从默认的5个改为9个
打开配置文件

1

nano ~/.config/ibus/rime/build/luna_pinyin_simp.schema.yaml

中“menu: page_size: 5”一行中5改为9或其它小于10的数字。

4.美化拓展 https://extensions.gnome.org/extension/2820/ibus-tweaker/

可以调整 IBus 字体、输入模式、剪贴板历史记录等设置

5.ctrl+； 输入emoji符号

安装软件

命令行安装软件

1

dnf install curl git btop vim vlc gimp fastfetch 

1

apt install curl git btop vim vlc gimp fastfetch 

• curl: 命令行数据传输工具。支持 HTTP、FTP 等多种协议，常用于下载文件、调用 API 接口或排查网络连通性。

• git: 目前最流行的分布式版本控制系统。无论是管理自己的代码脚本，还是从 GitHub 克隆项目，它都是核心工具。

• btop: 一个颜值极高的终端资源监视器。它比传统的 top 或 htop 更直观，能以图表形式实时展示 CPU、内存、网络和磁盘的使用情况。

• vim: 极其强大的终端文本编辑器。虽然有一定学习曲线，但在服务器环境或快速修改配置文件时，它的效率极高。

• vlc: 全能的多媒体播放器。几乎能解码所有格式的视频和音频。在命令行安装后，它也提供 cvlc 这种无界面运行模式。

• gimp: 开源的图像处理程序（类似 Photoshop）。它是一个功能齐全的 GUI 软件，适合进行照片编辑、绘图或图标制作。

• fastfetch: 系统信息展示工具（neofetch 的现代化替代品）。运行它会用漂亮的 ASCII 字符展示你的操作系统图标以及硬件配置信息。

krita：专业绘画软件，也可以当ps使用

1

dnf install krita

darktable ：Lightroom替代

1

dnf install darktable

flatpak 安装软件

https://flathub.org/zh-Hans

1. Remmina (org.remmina.Remmina)
   功能：远程桌面客户端

用途：如果你需要从 Linux 电脑远程连接到 Windows 桌面（使用 RDP 协议）或者其他 Linux 服务器（使用 VNC 或 SSH），Remmina 是首选工具。

特点：支持多窗口管理、文件传输和剪贴板共享。对于系统管理员来说，它是管理远程服务器集群的利器。

1

flatpak install flathub org.remmina.Remmina

2. Kdenlive (org.kde.kdenlive)
   功能：专业级非线性视频编辑器

用途：它是 Linux 生态中最强大的开源视频剪辑软件之一，类似于 Adobe Premiere 或剪映。

特点：支持多轨道编辑、丰富的转场效果、关键帧动画以及 4K 视频导出。它基于 KDE 框架，非常稳定且功能全面。

1

flatpak install flathub org.kde.kdenlive

3. Steam (com.valvesoftware.Steam)
   功能：游戏分发平台

用途：全球最大的数字游戏发行平台。

特点：通过内置的 Proton (WINE) 技术，Steam 使得成千上万的原生 Windows 游戏可以完美运行在 Linux 系统上。如果你想在 Linux 上玩 3A 大作，这是必装软件。

1

flatpak install flathub com.valvesoftware.Steam

4. OBS Studio (com.obsproject.Studio)
   功能：视频录制与直播推流软件

用途：屏幕录制、网课制作或在 Bilibili/YouTube 等平台进行直播。

特点：支持多源输入（窗口捕获、摄像头、麦克风等），可以进行实时混音和场景切换。它是目前全球主播和录屏用户的行业标准工具。

1

flatpak install flathub com.obsproject.Studio

LocalSend局域网互传

此应用程序允许您通过本地局域网发送文件和消息。

与大多数替代方案不同，它不需要外部服务器。所有操作都在本地 Wi-Fi 网络中完成。

1

flatpak install flathub org.localsend.localsend_app

安装包安装

📦 安装 .rpm 软件包 (RHEL/CentOS/Fedora/SUSE等)

基础命令安装 (不处理依赖)

使用 rpm (Red Hat Package Manager) 的 -ivh 参数（i=install，v=verbose，h=显示进度）。

1

sudo rpm -ivh /path/to/package.rpm

同样，它不会自动处理依赖，若失败则需手动安装所有依赖包。来源: [3†L5-L6], [12†L6-L7], [14†L4]

推荐命令 (自动处理依赖)

推荐使用更高级的包管理器，它们会自动处理依赖，免去很多麻烦。

对于 CentOS 7/RHEL 7 等老版本:
使用 yum localinstall 命令。

1

sudo yum localinstall /path/to/package.rpm

对于 Fedora/CentOS 8+/RHEL 8+ 等新版本 (使用 dnf):

1

sudo dnf install /path/to/package.rpm

对于 OpenSUSE/SUSE Linux (使用 zypper):

1

sudo zypper install /path/to/package.rpm

📦 安装 .deb 软件包 (Debian/Ubuntu/Mint等)

基础命令安装 (不处理依赖)

使用 dpkg (Debian Package) 的 -i (install) 参数。

1

sudo dpkg -i /path/to/package.deb

注意：dpkg 不会自动处理依赖问题，如果遇到依赖错误，需要手动修复：

修复依赖关系

1

sudo apt-get install -f

1

sudo apt --fix-broken install

推荐命令 (自动处理依赖)

使用 apt 命令并指定本地包路径（注意路径前的 ./，用于防止与仓库中的包名混淆）：

1

sudo apt install ./package.deb

常用软件

Chrome 浏览器 https://www.google.cn/chrome/

QQ https://im.qq.com/linuxqq/index.shtml

微信 https://linux.weixin.qq.com/

WPS https://www.wps.cn/product/wpslinux

Vscode https://code.visualstudio.com/

安装 达芬奇视频剪辑软件

参考 https://github.com/H3rz3n/How-install-DaVinci-Resolve-in-Fedora-Linux/tree/main

未完待续…

Dokploy 是一款开源的自托管 PaaS（平台即服务），可以在自己的服务器上搭建类似 Vercel/Heroku 的部署平台。支持 Git 自动部署、Docker 应用、数据库管理，是个人开发者和小团队的理想选择。

https://github.com/dokploy/dokploy

功能概览

• 应用程序部署：支持 Node.js、PHP、Python、Go、Ruby 等多种语言。
• 数据库管理：支持 MySQL、PostgreSQL、MongoDB、MariaDB、Redis 等数据库。
• Docker 管理：轻松部署和管理 Docker 容器。
• Traefik 集成：自动与 Traefik 集成，实现路由和负载均衡。
• 实时监控：监控 CPU、内存、存储和网络使用情况。
• 数据库备份：支持多种存储目标，实现自动备份。

为什么选择 Dokploy

部署指南

服务器要求

• 内存：至少 2GB
• 磁盘：至少 30GB

这是为了保证 Docker 在构建和运行容器时不会消耗过多资源，防止系统崩溃。

Docker 配置

确保 Docker 已安装，并修改 /etc/docker/daemon.json，以优化日志和启用实验功能：

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

{

    "log-driver": "json-file",

    "log-opts": {

        "max-size": "20m",

        "max-file": "3"

    },

    "experimental": true,

    "data-root": "/root/docker_data"

}

安装 Dokploy

官方提供一键安装脚本：

Terminal window

1

curl -sSL https://dokploy.com/install.sh | sh

完成后，访问 http://your-vps-ip:3000 进行初始设置。

初始设置

1. 访问管理界面
2. 创建管理员账号
3. 配置服务器信息

部署应用

模板部署

官方提供各种模板：https://templates.dokploy.com/

1. 选择合适模板
2. 检查 docker-compose.yml 或其他配置
3. 点击 Deploy 完成部署

域名设置通过 Traefik 自动反代，无需额外操作，只需解析到服务器即可。

Git 仓库部署

1. 项目 → 新建应用 → Git
2. 配置仓库地址和分支
3. 设置构建命令和启动命令
4. 部署

配置示例（Next.js）：

1
2
3
4
5

构建命令: npm install && npm run build

启动命令: npm start

端口: 3000

Dockerfile 部署

支持自定义 Dockerfile：

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

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./

RUN npm install

COPY . .

RUN npm run build

EXPOSE 3000

CMD ["npm", "start"]

Docker Compose 部署

对于复杂应用，支持 Docker Compose：

1
2

version: '3.8'services:  app:    build: .    ports:      - '3000:3000'    environment:      - DATABASE_URL=${DATABASE_URL}    depends_on:      - db  db:    image: postgres:15    environment:      - POSTGRES_PASSWORD=${DB_PASSWORD}    volumes:      - pgdata:/var/lib/postgresql/data
volumes:  pgdata:

预构建镜像

直接部署 Docker Hub 镜像：

1
2
3

镜像: nginx:latest

端口: 80

数据库服务

Dokploy 内置数据库管理：

PostgreSQL

1
2
3
4
5

1. 数据库 → 新建 → PostgreSQL

2. 设置用户名、密码、数据库名

3. 创建并获取连接信息

连接字符串：

1

postgres://user:password@localhost:5432/dbname

MySQL

1
2
3
4
5

1. 数据库 → 新建 → MySQL

2. 配置参数

3. 获取连接信息

Redis

1
2
3
4
5

1. 数据库 → 新建 → Redis

2. 设置密码

3. 获取连接信息

MongoDB

1
2
3
4
5

1. 数据库 → 新建 → MongoDB

2. 配置认证

3. 获取连接 URI

域名与 SSL

配置域名

1. 应用设置 → 域名
2. 添加自定义域名
3. 配置 DNS 指向服务器 IP

DNS 记录：

1
2
3
4
5

类型: A

名称: @

值: 服务器IP

自动 SSL

Dokploy 集成 Let’s Encrypt，自动申请和续期证书：

1

应用设置 → 域名 → 启用 HTTPS

通配符证书

支持申请 *.example.com 通配符证书，需要配置 DNS 验证。

安全设置

如果你不是内网，而是部署在公网vps上的。建议你设置自定义域名后关闭3000端口来保证安全. 你只需要打开80 443通过Traefik访问

1
2

docker service update --publish-rm "published=3000,target=3000,mode=host" dokploy
docker service inspect dokploy --format '{{.Spec.EndpointSpec}}'

环境变量

应用级变量

1
2
3
4
5
6

应用设置 → 环境变量
DATABASE_URL=postgres://...

API_KEY=sk-xxxxx

NODE_ENV=production

全局变量

可在多个应用间共享：

1

设置 → 全局变量

变量引用

支持引用数据库连接信息：

1
2
3

DATABASE_URL={{postgres.url}}

REDIS_URL={{redis.url}}

持续部署

Webhook 自动部署

每个应用提供 Webhook URL：

1

应用设置 → 部署 → Webhook URL

在 GitHub 仓库设置中添加 Webhook。

分支自动部署

可配置特定分支触发部署：

1
2
3

main → 生产环境

develop → 测试环境

监控与日志

应用日志

1

应用详情 → 日志

实时查看应用输出。

资源监控

1

应用详情 → 监控

查看 CPU、内存、网络使用。

部署历史

1

应用详情 → 部署记录

支持查看历史部署和回滚。

备份

数据库备份

1

数据库 → 备份 → 创建备份

支持定时自动备份。

导出配置

1

设置 → 导出配置

备份所有应用和数据库配置。

高级配置

资源限制

为每个应用设置资源限制：

1
2
3

CPU: 1 核

内存: 512 MB

健康检查

配置健康检查确保应用可用：

1
2
3
4
5

路径: /api/health

间隔: 30 秒

超时: 10 秒

自定义启动

使用 Procfile 定义启动方式：

1
2
3

web: npm start

worker: npm run worker

总结

Dokploy 通过简单的一键安装和图形化界面，极大降低了容器部署门槛，同时集成了 Git CI/CD、数据库管理、自动备份、监控等功能，是个人开发者和小型团队部署应用的理想选择。

参考:

https://catcat.blog/dokploy-deploy

https://dokploy.com/docs

https://www.wangshengliang.cn/blog/%E6%9D%82%E8%B0%88/dokploy/

内容大致如下：

“Guangzhou Baiyun, zero niner zero zero UTC. Wind zero eight zero degrees, zero five meters per second. Visibility niner kilometers. Scattered zero three zero. Temperature two six, Dewpoint two two. QNH one zero zero niner hectopascals. No significant change.”

对应的 METAR 报文格式： ZGGG 0900Z 08005MPS 9000 SCT030 26/22 Q1009 NOSIG

这是一种叫VOLMET的广播

航空气象资料（法语：vol météo，直译：“飞行气象”），简称VOLMET，是项全球性广播，利用无线电短波或甚高频频率发送机场天气预报（TAF）、向航机发出的显著危害天气（SIGMET）及机场天气报告（METAR）。航空气象资料会由自动声音系统，以上边带模式传送。

机师可透过航空气象资料避开雷暴及对流，及决定飞机升降及着陆的程序。

航空气象资料将世界分为特定区域及独立VOLMET站，在每个区域播报天气报告。为避免互相干扰，航空气象资料发射站会协调航空气象资料发射时间，有五分钟的时间间隔，每小时顺序播放。

播报内容通常包括：

• METAR（常规天气报告）： 包含风向风速、能见度、降水、云高、温度及气压（QNH）。
• TAF（机场预报）： 对未来一段时间内天气趋势的预测。
• SIGMET（重要气象情报）： 警告雷暴、湍流、积冰等严重影响航行安全的现象。

如何接收 VOLMET 消息？

硬件接收（无线电爱好者首选）

如果你希望体验亲手捕捉电波的快感，你需要以下设备：

• 接收设备：
  • 全波段收音机： 需支持 SSB（单边带） 模式（特别是高频接收）。
  • SDR（软件定义无线电）： 如 RTL-SDR 或更高阶的 Airspy/SDRplay。配合电脑或安卓设备使用，视觉化频谱能让你更轻松地找到信号。
• 天线：
  • VHF 波段： 普通的拉杆天线或 GP 天线即可，但需靠近机场。
  • HF 波段： 需要长线天线（Long Wire）或环形天线，才能接收到跨国甚至跨大洋的远距离信号。

接收技巧：

• 高频（HF）： 国际远程 VOLMET 通常使用 USB（上单边带） 模式。
• 甚高频（VHF）： 机场附近的局部播报通常使用 AM 模式。
• 时机： 高频传播受电离层影响，白天适合接收较高频率（如 13MHz），夜间适合较低频率（如 6MHz）。

常用频率

1. 广播基础参数

2. 播报时间与城市分布 (每小时循环)

广播以每小时的整点（H+00）开始，每 5 分钟为一个时段轮换播报不同城市的机场天气：

3. 城市区域逻辑划分

为了方便查阅，下表将广播中出现的城市按地理逻辑进行了归类：

其他地区参考
https://www.dxinfocentre.com/volmet-wx.htm

💡 补充说明

• 播报内容：通常包含风向、风速、能见度、云高、温度、露点以及修正海平面气压（QNH）。
• 频率选择：
  • 夜间：通常使用较低频率（如 3.458 MHz）。
  • 白天：通常使用较高频率（如 13.285 MHz）。
• 时间制式：表中的 H 代表协调世界时（UTC）的整点。

快去听听吧~

参考：

https://zh.wikipedia.org/wiki/%E8%88%AA%E7%A9%BA%E6%B0%A3%E8%B1%A1%E8%B3%87%E6%96%99

https://xiaohai.co/hf-volmet/

https://www.miyoushe.com/dby/article/29338079

HomeAssistant是一个成熟完整的基于 Python 的智能家居系统，设备支持度高，支持自动化（Automation）、群组化（Group）、UI 客制化（Theme）等等高度定制化设置，是构建智慧空间的神器。

基于HomeAssistant，可以方便地连接各种外部设备（智能设备、摄像头、邮件、短消息、云服务等，成熟的可连接组件有近千种），手动或按照自己的需求自动化地联动这些外部设备，构建随心所欲的智慧空间。HomeAssistant是开源的，它不属于任何商业公司，用户可以无偿使用。

HomeAssistant能识别和直接连接的外部设备有将近千项。其中有各种商业化的智能产品（如小米系列产品、Philips智能灯系列、亚马逊的音响、苹果的Siri、Google Assistant、博联的产品、特斯拉汽车等）、有互联网上的各种实时信息（股票、汇率、交通、天气等）、有开源或开放的各种智能软件（人脸识别、车牌识别、文字识别、文字转语音、语音转文字等）、有各种联动机制（短信、Email、IFTTT等）……

安装

关于Home Assistant的安装，一般都采用Docker部署的方法实现。

官方网站

安装Docker

关于Docker的安装，这里就不进行赘述了

通过以下指令验证Docker是否安装成功，安装成功则会返回Docker的版本号。

1

docker -v

Docker CLI

1
2
3
4
5
6
7
8
9

docker run -d \
  --name homeassistant \
  --privileged \
  --restart=unless-stopped \
  -e TZ=Asia/Shanghai \
  -v /自定义路径:/config \
  -v /run/dbus:/run/dbus:ro \
  --network=host \
  home-assistant/home-assistant:latest

国内

1
2
3
4
5
6
7
8
9

docker run -d \
  --name homeassistant \
  --privileged \
  --restart=unless-stopped \
  -e TZ=Asia/Shanghai \
  -v /自定义路径:/config \
  -v /run/dbus:/run/dbus:ro \
  --network=host \
  swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/homeassistant/home-assistant:latest

Docker Compose

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

services:
  homeassistant:
    container_name: homeassistant
    image: "homeassistant/home-assistant:latest"
    volumes:
      - /自定义路径:/config
      - /etc/localtime:/etc/localtime:ro
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped
    privileged: true
    network_mode: host
    environment:
      TZ: Asia/Shanghai

1

docker compose up -d

浏览器输入 ip:8123 进入Home Assistant界面

安装HACS

HACS,全称Home Assistant Community Store，意思是 家庭助理社区商店。

HACS可以为您提供一个强大的Ul来处理所有自定义需求的下载，可以理解为 Home Assistant 上的一个第三方应用商店。

关于HACS的安装可以参考官网： https://hacs.xyz/docs/setup/download

我们在 homeasststant 目录（/root/docker/HA/）下创建一个名为 custom_components 的文件夹，再创建一个hacs文件夹

1

/root/docker/HA/custom_components/hacs

下载https://github.com/hacs/integration/releases/download/2.0.5/hacs.zip 并解压到/root/docker/HA/custom_components/hacs

重启 Home Assistant.

添加HACS商店

点击配置>设备与服务>添加集成>HACS

全部勾选后点击提交

在弹出的界面点击GitHub链接，将8位验证码输入GitHub链接进行绑定

如果提示could_not_register，请在容器内执行

1

echo 20.205.243.166  github.com >> /etc/hosts

刷新网页后就可以点击HACS 安装应用了

例如xiaomi_home 和xiaomi_miot

当然你也可以手动安装

例如下载https://ghp.quickso.cn/github.com/al-one/hass-xiaomi-miot/releases/download/v1.1.4/xiaomi_miot.zip 解压到

/root/docker/HA/custom_components/xiaomi_miot/

Home Assistant 米家集成

这里讲一下Home Assistant 米家集成的使用

米家集成是一个由小米官方提供支持的 Home Assistant 的集成组件，它可以让您在 Home Assistant 中使用小米 IoT 智能设备。

https://github.com/XiaoMi/ha_xiaomi_home

配置

登录

设置 > 设备与服务 > 添加集成 > 搜索“Xiaomi Home” > 下一步 > 请点击此处进行登录 > 使用小米账号登录

添加 MIoT 设备

登录成功后，会弹出会话框“选择家庭与设备”。您可以选择需要添加的米家家庭，该家庭内的所有设备将导入 Home Assistant 。

多账号登录

用一个小米账号登录并配置完成后，您可以在 Xiaomi Home Integration 页面中继续添加其他小米账号。

方法：设置 > 设备与服务 > 已配置 > Xiaomi Home > 添加中枢 > 下一步 > 请点击此处进行登录 > 使用小米账号登录

修改配置

在会话框“配置选项”中，可选择需要变更的配置项。您可以修改用户昵称或更新从米家 APP 导入的设备列表。

方法：设置 > 设备与服务 > 已配置 > Xiaomi Home > 配置 > 选择需要变更的配置项

其他具体使用可以参考官网文档https://www.home-assistant.io/docs/

或者第三方

https://wiki.wghaos.com/

https://ha-doc.hasscn.top/

https://bbs.hassbian.com/forum-38-1.html

Hexo-Admin 是一款为 Hexo 博客设计的后台管理插件，它能让你告枯燥的命令行，直接在浏览器里撰写文章、编辑草稿、管理标签，甚至直接发布。

这篇教程将带你从安装到进阶配置，全方位掌握这个插件。

1. 安装与启动

首先，确保你已经进入了 Hexo 博客的根目录。
执行安装命令：

1

npm install --save hexo-admin

启动 Hexo 服务器：

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

hexo server```
访问后台：
打开浏览器，输入 http://localhost:4000/admin/。
### 2. 功能解析
进入后台后，你会看到一个简洁的界面
- Posts (已发布): 管理你所有的正式文章。
- Pages (页面): 管理如“关于我”、“友链”等独立页面。
- Deplay(部署):部署你的博客
#### 撰写体验
Hexo-Admin 提供了侧边预览模式。你在左侧输入 Markdown 源码，右侧会实时渲染出效果。

- 插入图片： 直接将图片粘贴到编辑器，插件会自动帮你把图片存入 source/images 文件夹并生成路径，非常方便。
- 管理元数据： 在侧边栏可以轻松修改 Categories、Tags 和 Date。

### 3. 安全配置（必做）
默认情况下，任何人访问 localhost:4000/admin/ 都能修改你的博客。虽然在本地开发没问题，但如果你将博客部署到了云服务器，必须设置密码。

在后台点击 `Settings -> Setup authentication`。

输入你的 Username、Password 和 Secret。

插件会自动生成一段配置代码，如下所示：

```YAML
admin:
  username: my_username
  password_hash: $2a$10$xxxxxxxxxxxx
  secret: my_secret

将这段代码复制到你博客根目录的 _config.yml 文件末尾。

重启 Hexo 服务，再次访问后台就需要登录了。

4. 自动化部署 (Advanced)

Hexo-Admin 最强大的地方在于它支持一键部署。你可以配置一个脚本，让它在后台点击按钮后自动执行 hexo g -d。
在博客根目录下创建一个脚本文件
Linux / macOS 脚本 (deploy.sh)
在 Linux 环境下，我们通常使用 bash。为了确保脚本有执行权限，创建后请运行 chmod +x deploy.sh。

1
2
3
4
5
6
7
8
9
10
11

#!/bin/bash
echo "--- 开始自动部署 ---"
# 清理缓存并生成静态文件
hexo clean
hexo generate
# 部署到远程仓库（如 GitHub/云服务器）
hexo deploy

echo "--- 部署完成！ ---"```
**Windows 脚本 (deploy.bat)**
Windows 下使用批处理脚本。注意，如果你的 hexo 命令在某些环境下失效，可能需要使用 call hexo。

@echo off
echo — Starting Auto Deploy —

:: 清理并生成
call hexo clean
call hexo generate

:: 部署
call hexo deploy

echo — Deploy Finished! —
pause

#### 如何在 Hexo 中关联脚本脚本准备好后，你需要修改博客根目录下的 _config.yml，找到（或添加）admin 配置项：Linux 配置示例：```YAMLadmin:  deployCommand: './deploy.sh'```Windows 配置示例：```YAMLadmin:  deployCommand: 'deploy.bat'```这样，当你写完文章，直接在后台点一下 Deploy，文章就飞向服务器了。💡 常见小贴士图片路径问题： 如果你使用了资源文件夹（post_asset_folder），Hexo-Admin 的图片处理可能需要配合 hexo-asset-image 插件使用，以防路径失效。进程守护： 如果你在服务器上运行，建议配合 pm2 来守护 Hexo 进程，确保后台一直在线。避坑指南： Hexo-Admin 主要是为了本地或私有服务器协作设计的。如果你使用的是 GitHub Pages 静态托管，你还是需要在本地电脑上运行管理界面，生成后再推送到 GitHub。卸载执行命令并删除_config.yml里的相关配置:'''npm uninstall --save hexo-admin'''

RustFS是使用目前全球最流行的、内存安全的Rust语言开发的 高性能 ， 分布式对象存储软件。RustFS 同时具备简单、高效的特点，也是一种高效、开源、自由、可以进行本地私有云部署的对象存储解决方案。RustFS 100% 兼容 S3 协议，使用 Apache2 许可证发行的开源软件。RustFS 使用目前全世界最受欢迎的、内存安全的语言 Rust 语言编写。 它是由全世界优秀的工程师参与并贡献的一款对于商用友好的分布式对象存储产品，RustFS 可以平替非常多非友好开源协议的对象存储产品。

官方网站:

https://rustfs.com.cn/

官方文档:

https://docs.rustfs.com.cn/

一、前置准备

主机要求

• 已安装 Docker（≥ 20.10）并能正常拉取镜像与运行容器
• 本地路径 /mnt/rustfs/data（或自定义路径）用于挂载对象数据

网络与防火墙

• 确保宿主机 9000\9001 端口对外开放（或自定义端口一致）

运行 RustFS 容器

RustFS SNSD Docker 运行方式，结合上述镜像与配置，执行：

1
2
3
4
5
6
7
8
9

# 创建 data 和 logs 文件夹
mkdir -p /mnt/rustfs && cd /mnt/rustfs
mkdir -p data logs

 # 修改权限
 chown -R 10001:10001 data logs

 # Docker RUN
 docker run -d -p 9000:9000 -p 9001:9001 -v /mnt/rustfs/data:/data -v /mnt/rustfs/logs:/logs rustfs/rustfs:latest

各参数说明：

• -p 9000:9000：映射宿主机 9000 Endpoint端口到容器
• -p 9001:9001：映射宿主机 9001 Console端口到容器
• -v /mnt/rustfs/data:/data：挂载数据卷
• --name rustfs_local：容器自定义名称
• -d：后台运行

完整参数配置示例

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

docker run -d \
  --name rustfs_container \
  -p 9000:9000 \
  -p 9001:9001 \
  -v /mnt/rustfs/data:/data \
  -e RUSTFS_ACCESS_KEY=admin \
  -e RUSTFS_SECRET_KEY=修改成你的密码 \
  -e RUSTFS_CONSOLE_ENABLE=true \
  -e RUSTFS_SERVER_DOMAINS=s3.example.com \
  rustfs/rustfs:latest \
  --address :9000 \
  --console-enable \
  --server-domains s3.example.com \
  --access-key admin \
  --secret-key 修改成你的密码 \
  /data

Docker Compose 配置

创建 docker-compose.yml 文件：

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
48
49

version: "3.8"

services:
  rustfs:
    image: rustfs/rustfs:latest
    container_name: rustfs-server
    security_opt:
      - "no-new-privileges:true"
    ports:
      - "9000:9000"   # S3 API 对外端口
      - "9001:9001"   # 控制台对外端口
    environment:
      # 数据卷（多个路径用逗号分隔）
      - RUSTFS_VOLUMES=/data/rustfs0
      # API 和控制台监听地址
      - RUSTFS_ADDRESS=0.0.0.0:9000
      - RUSTFS_CONSOLE_ADDRESS=0.0.0.0:9001
      - RUSTFS_CONSOLE_ENABLE=true
      # CORS 设置，控制台与 S3 API 都放开来源
      - RUSTFS_CORS_ALLOWED_ORIGINS=*
      - RUSTFS_CONSOLE_CORS_ALLOWED_ORIGINS=*
      # 访问密钥（生产环境请修改为强密码）
      - RUSTFS_ACCESS_KEY=admin
      - RUSTFS_SECRET_KEY=改为你的密码
      # 日志级别
      - RUSTFS_OBS_LOGGER_LEVEL=info

    volumes:
      # 存储数据卷（请根据实际情况修改路径）
      - ./deploy/data/pro:/data
      # 日志目录
      - ./deploy/logs:/app/logs

    networks:
      - rustfs-network
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "sh", "-c", "curl -f http://localhost:9000/health && curl -f http://localhost:9001/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

networks:
  rustfs-network:
    driver: bridge
    ipam:
      config:
        - subnet: 172.20.0.0/16

启动服务：

1

docker compose up -d

通过 http://localhost:9000 访问，默认用户名和密码均为 rustfsadmin。

反向代理

• 访问方式：
  • S3 API 端：https://s3.example.com (端口 9000)
  • 控制台端：https://console.example.com (端口 9001)
• 特性：支持 HTTPS、CORS、健康检查

Nginx 反向代理配置

S3 API 端配置

为 S3 API 创建 Nginx 配置文件（如 /www/server/panel/vhost/nginx/s3.example.com.conf）：

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
48
49
50
51
52
53
54

# S3 API 负载均衡配置
upstream rustfs {
    least_conn;
    server 127.0.0.1:9000;  # S3 API 服务端口
}

# HTTP 重定向到 HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name s3.example.com;  # 替换为你的 S3 API 域名

    return 301 https://$host$request_uri;
}

# HTTPS 主配置
server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;
    server_name s3.example.com;  # 替换为你的 S3 API 域名

    # SSL 证书配置（请替换为实际证书路径）
    ssl_certificate     /www/server/panel/vhost/cert/s3.example.com/fullchain.pem;
    ssl_certificate_key /www/server/panel/vhost/cert/s3.example.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         EECDH+CHACHA20:EECDH+AES128:RSA+AES128:EECDH+AES256:RSA+AES256:EECDH+3DES:RSA+3DES:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_cache   shared:SSL:10m;
    ssl_session_timeout 10m;
    add_header Strict-Transport-Security "max-age=31536000";

    # 反向代理 RustFS S3 API
    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Port  $server_port;
        proxy_set_header X-Forwarded-Host  $host;

        # 关键配置：禁用 HEAD 请求转换，避免 S3 V4 签名失效
        proxy_cache_convert_head off;
        proxy_connect_timeout 300;
        proxy_http_version 1.1;
        proxy_set_header Connection "";

        proxy_pass http://rustfs;  # 代理到 S3 API
    }

    # 日志配置（请根据实际情况修改路径）
    access_log  /www/wwwlogs/s3.example.com.log;
    error_log   /www/wwwlogs/s3.example.com.error.log;
}

控制台端配置

为控制台创建 Nginx 配置文件（如 /www/server/panel/vhost/nginx/console.example.com.conf）：

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
48
49
50
51
52
53
54

# 控制台负载均衡配置
upstream rustfs-console {
    least_conn;
    server 127.0.0.1:9001;  # 控制台服务端口
}

# HTTP 重定向到 HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name console.example.com;  # 替换为你的控制台域名

    return 301 https://$host$request_uri;
}

# HTTPS 主配置
server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;
    server_name console.example.com;  # 替换为你的控制台域名

    # SSL 证书配置（请替换为实际证书路径）
    ssl_certificate     /www/server/panel/vhost/cert/console.example.com/fullchain.pem;
    ssl_certificate_key /www/server/panel/vhost/cert/console.example.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         EECDH+CHACHA20:EECDH+AES128:RSA+AES128:EECDH+AES256:RSA+AES256:EECDH+3DES:RSA+3DES:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_cache   shared:SSL:10m;
    ssl_session_timeout 10m;
    add_header Strict-Transport-Security "max-age=31536000";

    # 反向代理 RustFS 控制台
    location / {
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Port  $server_port;
        proxy_set_header X-Forwarded-Host  $host;

        # 禁用 HEAD 请求转换
        proxy_cache_convert_head off;
        proxy_connect_timeout 300;
        proxy_http_version 1.1;
        proxy_set_header Connection "";

        proxy_pass http://rustfs-console;  # 代理到控制台
    }

    # 日志配置（请根据实际情况修改路径）
    access_log  /www/wwwlogs/console.example.com.log;
    error_log   /www/wwwlogs/console.example.com.error.log;
}

重载 Nginx 配置：

1

nginx -t && nginx -s reload

测试S3

这里使用S3cmd

S3cmd 是一个用于操作 Amazon S3 和其他兼容 S3 的云存储服务的命令行工具。它提供了广泛的命令，允许用户上传、下载、同步和管理存储在 S3 上的文件。

使用包管理器安装

在大多数 Linux 发行版中，您可以使用包管理器来安装 S3cmd。以下是在几种常见 Linux 发行版上安装 S3cmd 的命令。

对于基于 Debian 的系统（如 Ubuntu），您可以使用 apt-get：

1
2

sudo apt-get update
sudo apt-get install s3cmd

对于基于 Red Hat 的系统（如 CentOS），您可以使用 yum：

1

sudo yum install s3cmd

对于基于 Arch Linux 的系统，您可以使用 pacman：

1

sudo pacman -S s3cmd

配置 S3cmd

在安装完 S3cmd 之后，您需要对其进行配置，以便连接到您的 S3 存储服务。配置 S3cmd 涉及设置您的 AWS 访问密钥 ID 和秘密访问密钥，这些是您在 AWS 账户中创建的访问权限凭证。

运行配置向导

最简单的方法是运行 S3cmd 的配置向导。在命令行中输入以下命令：

1

s3cmd --configure

该命令将启动一个交互式配置程序，提示您输入所需的配置信息，包括：

• S3 服务端点（写入s3.example.com）
• 访问密钥 ID
• 秘密访问密钥
• 默认存储桶名称
• 是否使用 HTTPS
• 是否启用服务端加密等

参考

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
48
49
50
51
52
53
54
55

root@iv-ydya2ilgcgqc6ilqbabf:~# s3cmd --configure

Enter new values or accept defaults in brackets with Enter.
Refer to user manual for detailed description of all options.

Access key and Secret key are your identifiers for Amazon S3. Leave them empty for using the env variables.
Access Key: admin
Secret Key: passwd
Default Region [US]:

Use "s3.amazonaws.com" for S3 Endpoint and not modify it to the target Amazon S3.
S3 Endpoint [s3.amazonaws.com]: s3.xxx.cn

Use "%(bucket)s.s3.amazonaws.com" to the target Amazon S3. "%(bucket)s" and "%(location)s" vars can be used
if the target S3 system supports dns based buckets.
DNS-style bucket+hostname:port template for accessing a bucket [%(bucket)s.s3.amazonaws.com]:

Encryption password is used to protect your files from reading
by unauthorized persons while in transfer to S3
Encryption password: passwd
Path to GPG program [/usr/bin/gpg]:

When using secure HTTPS protocol all communication with Amazon S3
servers is protected from 3rd party eavesdropping. This method is
slower than plain HTTP, and can only be proxied with Python 2.7 or newer
Use HTTPS protocol [Yes]:

On some networks all internet access must go through a HTTP proxy.
Try setting it here if you can't connect to S3 directly
HTTP Proxy server name:

New settings:
  Access Key: admin
  Secret Key: passwd
  Default Region: US
  S3 Endpoint: s3.quickso.cn
  DNS-style bucket+hostname:port template for accessing a bucket: %(bucket)s.s3.amazonaws.com
  Encryption password: passwd
  Path to GPG program: /usr/bin/gpg
  Use HTTPS protocol: True
  HTTP Proxy server name:
  HTTP Proxy server port: 0

Test access with supplied credentials? [Y/n] y
Please wait, attempting to list all buckets...
Success. Your access key and secret key worked fine :-)

Now verifying that encryption works...
Success. Encryption and decryption worked fine :-)

Save settings? [y/N] y
Configuration saved to '/root/.s3cfg'
root@iv-ydya2ilgcgqc6ilqbabf:~# s3cmd ls
2025-12-27 01:19  s3://test

出于安全考虑，您的配置文件应该只有您自己能够读写。设置适当的文件权限可以使用以下命令：

1

chmod 600 ~/.s3cfg

这样，您就完成了 S3cmd 的基本配置，可以开始使用它来管理您的 S3 存储桶了

基本命令与操作

S3cmd 提供了一系列命令，用于执行与 Amazon S3 存储桶相关的各种操作。以下是一些常用的 S3cmd 命令及其基本用法。

1 列出存储桶

要列出所有可用的存储桶，可以使用以下命令：

1

s3cmd ls

这将显示您有权访问的所有存储桶的列表。

2 上传文件

要将文件上传到存储桶，使用以下命令：

1

s3cmd put /path/to/your/file s3://bucket-name/file-name

请将 /path/to/your/file 替换为您要上传的文件的本地路径，将 bucket-name 替换为您的 S3 存储桶名称，将 file-name 替换为您希望文件在 S3 上保存的名称。

3 下载文件

要从存储桶下载文件，使用以下命令：

1

s3cmd get s3://bucket-name/file-name /path/to/your/local/directory

请将 bucket-name 和 file-name 替换为存储桶名称和文件名称，将 /path/to/your/local/directory 替换为您希望保存下载文件的本地路径。

4 删除文件

要删除存储桶中的文件，使用以下命令：

1

s3cmd rm s3://bucket-name/file-name

请确保在执行此操作之前正确地确认了文件名称，因为此操作是不可逆的。

5 同步文件

S3cmd 的同步功能允许您同步本地目录与 S3 存储桶中的内容。以下是如何使用该命令的示例：

1

s3cmd sync /path/to/your/local/directory s3://bucket-name/

这个命令会检查本地目录和 S3 存储桶中的文件，并根据需要上传或下载文件以保持同步。

6 查看文件信息

要查看存储在 S3 上的文件的元数据，可以使用以下命令：

1

s3cmd info s3://bucket-name/file-name

这将显示关于指定文件的信息，包括其大小、存储类、ETag 等。

通过掌握这些基本命令，您可以开始有效地管理您的 S3 存储桶中的文件。S3cmd 还有更多高级功能，如批量删除、复制对象、设置权限等，可以通过查阅官方文档来了解这些高级用法。

K3s 是一个完全兼容的 Kubernetes 发行版，具有以下增强功能：

• 打包为单个二进制文件。

• 使用基于 sqlite3 作为默认存储机制的轻量级存储后端。同时支持使用 etcd3、MySQL 和 Postgres。

• 封装在简单的启动程序中，可以处理很多复杂的 TLS 和选项。

• 默认情况下是安全的，对轻量级环境有合理的默认值。

• 添加了简单但强大的

  1	batteries-included

  功能，例如：

  • 本地存储提供程序
  • service load balancer
  • Helm controller
  • Traefik ingress controller

• 所有 Kubernetes control plane 组件的操作都封装在单个二进制文件和进程中。因此，K3s 支持自动化和管理复杂的集群操作（例如证书分发等）。

• 最大程度减轻了外部依赖性，K3s 仅需要现代内核和 cgroup 挂载。K3s 打包了所需的依赖，包括：

  • containerd
  • Flannel (CNI)
  • CoreDNS
  • Traefik (Ingress)
  • Klipper-lb (Service LB)
  • 嵌入式网络策略控制器
  • 嵌入式 local-path-provisioner
  • 主机实用程序（iptables、socat 等）

官方网站 ：https://k3s.io/

官方文档:

https://docs.k3s.io/zh/

https://docs.rancher.cn/docs/k3s/

环境说明

本文使用 Debian 部署一个 K3s 双节点 Kubernetes 集群。
节点规划

请根据自己的实际 IP 修改。
系统要求：

• Debian 12 x64
• CPU：1 Core+
• 内存：最低 512MB（建议 1GB+）
• 两台服务器网络互通,开放 6443 端口
• root 用户或 sudo 权限

1. 准备工作（两台主机均需执行）

在开始之前，确保两台机器可以互相通信，并且防火墙允许必要的流量。

• 更新系统：

  1	sudo apt update && sudo apt upgrade -y

• 安装基础工具

  1	apt install -y curl wget vim git net-tools iproute2 ca-certificates

• 停止并禁用防火墙

1
2
3
4
5
6
7

ufw disable

或者

ufw allow 6443/tcp #apiserver
ufw allow from 10.42.0.0/16 to any #pods
ufw allow from 10.43.0.0/16 to any #services

• 确认主机名： 建议分别设置主机名为 master 和 node0 方便识别。

  1 2	sudo hostnamectl set-hostname master # 在102上执行 sudo hostnamectl set-hostname node0 # 在103上执行

2. 部署 Master 节点 (192.168.10.102)

在 Master 节点上，我们将运行安装脚本并将其配置为集群的主控节点。

1. 执行安装命令：

   1 2 3 4 5

   curl -sfL https://get.k3s.io | sh - # 中国用户，可以使用以下方法加速安装： curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn sh -

2. 获取 Node Token： 安装完成后，你需要获取一个“令牌”，用于将 Node0 加入集群。

   1	sudo cat /var/lib/rancher/k3s/server/node-token

   复制保存这个字符串，稍后在 Node0 上会用到。

3. 检查状态：

   1	sudo kubectl get nodes

   此时你应该能看到 master 节点处于 Ready 状态。

3. 部署 Node 节点 (192.168.10.103)

现在切换到 Node0 主机，将其作为工作节点连接到 Master。

1. 执行安装命令： 请将下方命令中的 <MASTER_TOKEN> 替换为你刚才在 Master 上获取的字符串。

   1 2 3 4 5 6 7

   curl -sfL https://get.k3s.io | K3S_URL=https://192.168.10.102:6443 \ K3S_TOKEN=<MASTER_TOKEN> sh - # 中国用户，可以使用以下方法加速安装： curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | K3S_URL=https://192.168.10.102:6443 \ K3S_TOKEN=<MASTER_TOKEN> sh -

4. 验证集群状态

回到 Master 节点，运行以下命令验证 Node0 是否已成功加入：

1

sudo kubectl get nodes

预期输出：

1
2
3
4

sudo kubectl get nodes
NAME     STATUS   ROLES                  AGE   VERSION
master   Ready    control-plane,master   32m   v1.33.6+k3s1
node0    Ready    <none>                 30m   v1.33.6+k3s1

配置国内镜像

Master节点

创建或编辑配置文件：

1

sudo nano /etc/rancher/k3s/registries.yaml

填入

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

mirrors:
  docker.io:
    endpoint:
      - "https://docker.m.daocloud.io"
      - "https://docker.1panel.live"

  registry.k8s.io:
    endpoint:
      - "https://k8s.m.daocloud.io"

  quay.io:
    endpoint:
      - "https://quay.m.daocloud.io"

  ghcr.io:
    endpoint:
      - "https://ghcr.m.daocloud.io"

重启K3s

1

sudo systemctl restart k3s

Node节点

1
2

sudo mkdir -p /etc/rancher/k3s
sudo nano /etc/rancher/k3s/registries.yaml

配置完成

1

sudo systemctl restart k3s-agent

如何卸载K3s

如果需要重新开始：

• Master: sudo /usr/local/bin/k3s-uninstall.sh
• Node: sudo /usr/local/bin/k3s-agent-uninstall.sh

部署 Nginx 验证集群

我们创建一个简单的 Nginx 服务

1. 在 Master 节点上创建配置文件：

   1	nano nginx-demo.yaml

2. 粘贴以下内容：

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

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: nginx
spec:
  selector:
    app: nginx
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
  type: ClusterIP

注释

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

# 定义一个 Deployment 资源，用于管理应用的滚动更新和副本数
apiVersion: apps/v1          # 使用 apps/v1 API 版本（Kubernetes 稳定版）
kind: Deployment            # 资源类型为 Deployment
metadata:
  name: nginx               # Deployment 的名称，用于标识该资源
spec:
  replicas: 2               # 指定运行 2 个 Pod 副本，保证高可用
  selector:                 # 选择器，用于匹配该 Deployment 管理的 Pod
    matchLabels:            # 通过标签匹配
      app: nginx            # 标签键值对，要求 Pod 带有 app=nginx
  template:                 # Pod 模板，定义新 Pod 的规格
    metadata:
      labels:               # Pod 标签，必须与 selector 匹配
        app: nginx
    spec:
      containers:           # 容器列表
      - name: nginx         # 容器名称
        image: nginx:latest # 使用的镜像及版本（latest 表示最新版，生产环境建议固定版本）
        ports:              # 声明容器监听的端口
        - containerPort: 80 # 容器内 Nginx 服务监听 80 端口
---
# 定义一个 Service 资源，为 Deployment 中的 Pod 提供稳定的网络访问入口
apiVersion: v1              # 使用 v1 API 版本（Service 核心资源）
kind: Service               # 资源类型为 Service
metadata:
  name: nginx               # Service 名称，集群内可通过该名称访问
spec:
  selector:                 # 标签选择器，关联到带有 app=nginx 标签的 Pod
    app: nginx
  ports:                    # 端口映射配置
  - port: 80                # Service 暴露的端口（集群内其他服务访问的端口）
    targetPort: 80          # 目标 Pod 的容器端口（与 containerPort 对应）
    protocol: TCP           # 使用的协议（TCP）
  type: ClusterIP           # Service 类型为 ClusterIP（默认），仅在集群内部可访问，不对外暴露

3. 应用配置：

   1	sudo kubectl apply -f nginx-demo.yaml

4. 验证：

查看 Pod 和 Service：

1

kubectl get pods,svc

输出示例：