Kevin's Notes

Windows 容器开发环境搭建指南

2026-05-21T02:00:00.000Z

容器技术本质上是 Linux-native 的，依赖 cgroups、namespaces、overlayfs 等内核特性，而 Windows 内核并不具备这些能力。因此所有在 Windows 上运行容器的方案，本质上都是在解决”如何在 Windows 上运行 Linux”这个问题。本文对比主流方案的优劣，并提供一套基于 WSL2 + Docker Engine 的稳定、免费、零授权风险的实践配置。

本文面向习惯命令行操作的 DevOps 工程师和开发者。如果你依赖 GUI 管理容器，Docker Desktop 或 Rancher Desktop 可能更适合你的使用习惯。

方案对比：Docker Desktop / Podman / Rancher Desktop

Docker Desktop —— 好用但有授权风险

Docker Desktop 内置 Linux VM、GUI、CLI、Compose，开箱即用，是过去几年的事实标准。但 2022 年 Docker 修改订阅条款后，员工数超过 250 人或年收入超过 1000 万美元的企业必须付费订阅。对于中大型公司，法务部门通常会直接封杀，存在合规风险。

收费的是 Docker Desktop 这个 GUI 应用，Docker Engine 本身仍是 Apache 2.0 开源免费，这个区别很重要。

Podman on Windows —— 理想丰满，现实骨感

Podman 的核心优势（Daemonless、Rootless、OCI 兼容、与 systemd 深度集成）在 Linux 上非常突出，但在 Windows 上需要通过 Podman Machine（QEMU/WSL2 VM）运行：

Windows 命令行
      ↓
Podman CLI (Windows)
      ↓
Podman Machine (QEMU/WSL2 VM)
      ↓
Linux 内核
      ↓
Container

这层 VM 抽象带来了一系列实际问题：Volume 挂载路径转换不稳定、Machine 启动偶尔卡死、rootless 在 VM 下端口绑定受限（<1024 失败）、Docker Compose 生态兼容性存在缺口。Podman 的主战场是 Linux，在 Windows 上使用需要接受这些 trade-off。

Rancher Desktop —— 看似全能，实则复杂

Rancher Desktop Apache 2.0 完全开源，SUSE 背书，支持 containerd/dockerd 切换。但实际使用中存在几个痛点：

默认 CLI 是 nerdctl，虽语法基本兼容，但细节有差异
镜像存储与 Docker 完全隔离，与其他工具链不互通
同样运行 Linux VM（Lima），资源占用与 Docker Desktop 相当
国内网络加速需要手动修改配置文件，没有简单 GUI 入口

对于习惯命令行的工程师，Rancher Desktop 的 GUI 价值有限，反而增加了一层复杂度。

推荐方案：WSL2 + Docker Engine

这是目前 Windows 上跑容器最干净、最稳定、零授权风险的方案。

架构原理

Windows Terminal / PowerShell
          ↓
    WSL2 (Linux 内核)
          ↓
   Docker Engine (dockerd)
          ↓
      Container

Docker Engine 直接运行在 WSL2 的 Linux 内核上，没有额外的 VM 抽象层，性能和稳定性接近原生 Linux。

方案对比总结

维度	Docker Desktop	Podman	Rancher Desktop	WSL2 + Docker Engine
授权风险	大公司需付费	免费	免费	零风险
Windows 稳定性	好	差	一般	好
Docker 生态兼容	完整	需配置	需切换	完整
Compose 支持	原生	兼容层	兼容层	原生
资源占用	高	高	高	低
配置复杂度	低	高	中	中（一次性）
适合人群	通用	Linux 用户	GUI 需求者	DevOps / 命令行

完整配置步骤

Step 1：启用 WSL2

以管理员身份打开 PowerShell：

# 启用 WSL 和虚拟机平台
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

# 重启电脑后，设置 WSL 默认版本为 2
wsl --set-default-version 2

# 安装 Ubuntu（或 Kali，按需选择）
wsl --install -d Ubuntu-22.04

验证安装：

wsl --list --verbose
# NAME            STATE           VERSION
# Ubuntu-22.04    Running         2      ← 确认是 VERSION 2

Step 2：WSL2 资源限制（可选但推荐）

默认 WSL2 会吃掉大量内存，在 C:\Users\<你的用户名>\.wslconfig 创建配置文件：

[wsl2]
memory=4GB          # 限制最大内存，根据你的机器调整
processors=4        # 限制 CPU 核心数
swap=2GB
localhostForwarding=true   # 允许 Windows 通过 localhost 访问 WSL2 端口

修改后重启 WSL2：

wsl --shutdown
wsl

Step 3：在 WSL2 里安装 Docker Engine

进入 WSL2 终端：

# 卸载旧版本（如果有）
sudo apt remove docker docker-engine docker.io containerd runc 2>/dev/null

# 删掉损坏的 key 和源
sudo rm -f /etc/apt/keyrings/docker.gpg
sudo rm -f /etc/apt/sources.list.d/docker.list

# 安装依赖
sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release

# 添加 Docker 官方 GPG 密钥
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 验证 key 是否正常
sudo gpg --dry-run --quiet --import --import-options import-show /etc/apt/keyrings/docker.gpg

# 添加 Docker 软件源
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# 把当前用户加入 docker 组（避免每次 sudo）
sudo usermod -aG docker $USER
newgrp docker

# 启动 Docker
sudo service docker start

# 验证
docker run hello-world

让 Docker 随 WSL2 自动启动，在 ~/.bashrc 或 ~/.zshrc 末尾添加：

# Auto-start Docker daemon in WSL2
if [ "$(service docker status 2>&1 | grep -c 'not running')" -eq 1 ]; then
    sudo service docker start > /dev/null 2>&1
fi

Step 4：配置代理（国内使用关键一步）

WSL2 有自己的网络栈，不会自动继承 Windows 的代理设置。

找到 Windows 宿主机的 IP（WSL2 网关）：

# 方法一
cat /etc/resolv.conf | grep nameserver | awk '{print $2}'

# 方法二
ip route | grep default | awk '{print $3}'

# 通常输出类似 172.x.x.1

在 ~/.bashrc 或 ~/.zshrc 里添加代理配置：

# WSL2 Proxy Configuration
WINDOWS_HOST=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')
PROXY_PORT=7890   # 替换成你的代理端口

export http_proxy="http://${WINDOWS_HOST}:${PROXY_PORT}"
export https_proxy="http://${WINDOWS_HOST}:${PROXY_PORT}"
export no_proxy="localhost,127.0.0.1,::1"

# Git 代理
git config --global http.proxy "http://${WINDOWS_HOST}:${PROXY_PORT}"
git config --global https.proxy "http://${WINDOWS_HOST}:${PROXY_PORT}"

给 Docker Daemon 单独配置代理（docker pull 走 daemon，不走 shell 环境变量）：

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

cat > /etc/systemd/system/docker.service.d/proxy.conf << 'EOF'
[Service]
Environment="HTTP_PROXY=http://:"
Environment="HTTPS_PROXY=http://:"
Environment="NO_PROXY=localhost,127.0.0.1"
EOF

# WSL2 里没有 systemd，用 service 重启
sudo service docker restart

将替换为上一步获取到的 WSL2 网关 IP，替换为你的代理工具实际端口。

WSL2 里三套代理互不相干，都要单独配：

作用域	配置方式	用途
Shell	`export http_proxy=...`	curl / wget / git
apt	`/etc/apt/apt.conf.d/proxy.conf`	apt install
Docker daemon	`/etc/systemd/system/docker.service.d/proxy.conf`	docker pull

apt 代理配置示例：

cat > /etc/apt/apt.conf.d/proxy.conf << 'EOF'
Acquire::http::Proxy "http://:";
Acquire::https::Proxy "http://:";
EOF

Git 精准代理（只代理 GitHub，国内仓库不受影响）：

git config --global http.https://github.com.proxy http://:

Step 5：配置镜像加速（代理 Fallback）

如果代理不稳定，配置镜像加速作为备用：

sudo tee /etc/docker/daemon.json > /dev/null <<EOF
{
  "registry-mirrors": [
    "https://docker.1panel.live",
    "https://hub.rat.dev",
    "https://dockerpull.com"
  ],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}
EOF

sudo service docker restart
docker info | grep -A5 "Registry Mirrors"

Step 6：配置 VSCode Remote WSL

安装 VSCode 插件：

ms-vscode-remote.remote-wsl
ms-vscode-remote.vscode-remote-extensionpack

使用方式：

# 在 WSL2 终端里直接打开项目
cd ~/projects/my-app
code .    # VSCode 自动以 Remote WSL 模式打开

VSCode 在 Remote WSL 模式下，终端、文件系统、Git、调试器全部运行在 Linux 环境里，体验和本地 Linux 开发一致。

可选：Portainer —— 需要 GUI 时的选择

如果偶尔需要可视化管理容器和镜像，可以部署 Portainer：

docker volume create portainer_data

docker run -d \
  --name portainer \
  --restart always \
  -p 9000:9000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

浏览器打开 http://localhost:9000，即可获得完整的容器、镜像、Volume、网络管理界面。

最终工作流

配置完成后，日常使用：

# 打开 Windows Terminal，切换到 WSL2
# 或直接在 VSCode Remote WSL 终端里操作

# 拉镜像
docker pull postgres:16-alpine

# 跑服务
docker compose up -d

# 看日志
docker compose logs -f app

# 清理
docker system prune -af

体验和纯 Linux 环境操作没有本质区别。

写在最后

Windows 上做容器开发，核心矛盾是 Windows 环境与 Linux-native 技术栈之间的阻抗失配。各种工具本质上都是在填这个坑：

Docker Desktop：填得最好，但要钱
Podman / Rancher Desktop：免费，但填得不够平整
WSL2 + Docker Engine：绕过这个坑，直接在 Linux 里跑

对于习惯命令行的工程师，GUI 是可选项而非必选项。这套方案一次配置，长期受益，没有授权风险，没有额外的抽象层，就是在 Windows 上搭了一个干净的 Linux 容器环境。

Nexus Repository Manager 启动失败排查全记录

2026-05-11T03:00:00.000Z

某天早上收到告警，Nexus 制品仓库无法访问。登录服务器检查，systemd 报告服务状态正常，实则 Java 进程根本不存在，端口未监听。本文记录完整的排查与修复过程。

背景

$ systemctl status nexus
Active: active (exited)   # 假正常

$ ps aux | grep java | grep nexus
# 空，Java 进程不存在

$ ss -tlnp | grep 8081
# 空，端口未监听

$ curl -s -o /dev/null -w "%{http_code}" http://localhost:8081
000  # 连接拒绝

active (exited) 是 init.d 风格的 SysV 脚本包装下的常见假象——启动脚本执行完就退出了，但它拉起的 Java 进程随后悄悄崩溃，systemd 毫无感知。

排查过程

第一步：定位真实安装路径

Nexus 并未安装在默认路径，需要先找到实际位置：

cat /etc/rc.d/init.d/nexus | grep -E 'NEXUS_HOME|data-dir|work'
find / -name "sonatype-work" -type d 2>/dev/null

确认路径：

程序目录：/opt/nexus/nexus-3.19.1-01
数据目录：/data/nexus/sonatype-work/nexus3

第二步：查看应用日志

tail -n 100 /data/nexus/sonatype-work/nexus3/log/nexus.log

日志只有 WARN 级别的 SSL 错误，全是 maven-osgeo 代理仓库的 SSLHandshakeException，没有 ERROR 或启动失败的痕迹。说明这次崩溃发生在日志系统初始化之后但写入之前，或者是更深层的问题。

第三步：前台运行，直接看报错

su - nexus -s /bin/bash -c "/opt/nexus/nexus-3.19.1-01/bin/nexus run" 2>&1 | head -50

终端立即出现关键错误：

ERROR - java.io.FileNotFoundException:
  /data/nexus/sonatype-work/nexus3/db/component/component.24003.wal
  (Permission denied)

ERROR - Cannot open local storage '/data/nexus/sonatype-work/nexus3/db/component' with mode=rw

根因找到：OrientDB 的 WAL（Write-Ahead Log）文件权限异常，nexus 用户无法写入。

第四步：验证权限问题

ls -la /data/nexus/sonatype-work/nexus3/db/component/*.wal
# -rw-r--r-- 1 nexus nexus ...   ← 644，nexus 用户只有读权限

ls -la /data/nexus/sonatype-work/nexus3/db/config/*.wal
# -rw-r--r-- 1 nexus nexus ...   ← 同样是 644

OrientDB 需要对 WAL 文件有写权限才能以 rw 模式打开存储。

根本原因分析

三个问题叠加导致服务无法启动：

#	问题	根因
1	WAL 文件 Permission Denied	某次 root 用户直接操作了 db 目录（备份、手动修复等），导致文件归属或权限被改写
2	lock / karaf.pid 残留	上次异常退出未正常清理锁文件，Nexus 启动时认为实例已运行，直接退出
3	systemd 无法追踪进程	使用 `Type=forking` + PIDFile，但 Nexus 写 PID 文件有延迟，systemd 判定启动失败并触发 Restart 循环

解决方案

修复一：恢复数据库文件权限

# 递归修复所有文件归属
chown -R nexus:nexus /data/nexus/sonatype-work/nexus3/

# 修复目录和文件权限
find /data/nexus/sonatype-work/nexus3/db -type d -exec chmod 755 {} \;
find /data/nexus/sonatype-work/nexus3/db -type f -exec chmod 664 {} \;

修复二：清理残留锁文件

rm -f /data/nexus/sonatype-work/nexus3/lock
rm -f /data/nexus/sonatype-work/nexus3/karaf.pid
rm -f /data/nexus/sonatype-work/nexus3/port

修复三：重写为原生 systemd 服务

原来的 init.d 包装脚本有两个核心缺陷：

systemd 无法感知实际的 Java 进程状态
Type=forking 依赖 PID 文件时序，不稳定

正确做法：使用 Type=simple + nexus run（前台模式），让 systemd 直接管理 Java 进程。

# 禁用旧的 init.d 服务
chkconfig nexus off

# 创建原生 systemd unit 文件
cat > /etc/systemd/system/nexus.service << 'EOF'
[Unit]
Description=Sonatype Nexus Repository Manager
After=network.target

[Service]
Type=simple
LimitNOFILE=65536
User=nexus
Group=nexus
Environment=JAVA_HOME=/opt/jdk1.8.0_74

# 每次启动前自动清理残留锁文件
ExecStartPre=/bin/bash -c "rm -f /data/nexus/sonatype-work/nexus3/lock \
  /data/nexus/sonatype-work/nexus3/karaf.pid \
  /data/nexus/sonatype-work/nexus3/port"

# 使用 run 以前台方式运行，systemd 可直接追踪进程
ExecStart=/opt/nexus/nexus-3.19.1-01/bin/nexus run
ExecStop=/opt/nexus/nexus-3.19.1-01/bin/nexus stop

# 异常退出后自动重启
Restart=on-failure
RestartSec=30
TimeoutStartSec=300
TimeoutStopSec=120

[Install]
WantedBy=multi-user.target
EOF

# 重载并启动
systemctl daemon-reload
systemctl enable nexus   # 开机自启
systemctl start nexus

验证结果

$ systemctl status nexus
● nexus.service - Sonatype Nexus Repository Manager
   Active: active (running) since Thu 2026-05-07 11:06:19 CST
   Main PID: 28549 (java)        # 真实 Java 进程
   Memory: 3.1G

$ ss -tlnp | grep 8081
LISTEN  0  50  *:8081  *:*  users:(("java",pid=28549,fd=953))

$ curl -s -o /dev/null -w "%{http_code}" http://localhost:8081
200

遗留优化：SSL 证书问题

服务恢复后，日志中仍持续出现 maven-osgeo 代理仓库的 SSL 错误：

SSLHandshakeException: PKIX path building failed
→ unable to find valid certification path to requested target

原因是 JDK 1.8.0_74（2016年构建）的信任链中没有 repo.osgeo.org 的新证书。

方案 A（推荐）：在 Web UI 中将 maven-osgeo 的 Remote URL 替换为可用镜像，或直接禁用该仓库。

方案 B：手动将证书导入 JDK 信任库：

openssl s_client -connect repo.osgeo.org:443 -showcerts /dev/null \
  | openssl x509 -outform PEM > /tmp/osgeo.crt

/opt/jdk1.8.0_74/bin/keytool -import \
  -alias osgeo-cert \
  -keystore /opt/jdk1.8.0_74/jre/lib/security/cacerts \
  -file /tmp/osgeo.crt \
  -storepass changeit -noprompt

systemctl restart nexus

经验总结

排查思路：

active (exited) ≠ 服务正常，必须验证实际进程和端口
应用日志没有新内容时，用前台运行模式（run）直接看终端输出
Permission Denied 类错误优先检查文件归属，而非权限位

防御措施：

任何对 Nexus 数据目录的运维操作，完成后必须执行 chown -R nexus:nexus
将 SysV init.d 服务迁移为原生 systemd unit，获得真实的进程生命周期管理
ExecStartPre 自动清理锁文件，消除异常重启后的残留问题
定期检查 systemctl status nexus 是否真的有 Main PID

排查日期：2026-05-07
环境：CentOS 7.6 / Nexus OSS 3.19.1-01 / JDK 1.8.0_74

Jenkins Slave 节点重建后 SSH 认证失败的排查与恢复

2026-05-11T02:00:00.000Z

生产服务器意外崩溃，重新申请了相同 IP 的机器并重做了免密登录，但 Jenkins slave 节点持续离线，日志显示 SSH 认证失败。本文记录完整的排查与恢复过程。

问题现象

打开 Jenkins → Nodes → slave-01 → Log，看到如下循环报错：

[05/07/26 17:11:54] [SSH] Opening SSH connection to 10.0.0.10:22.
Searching for 10.0.0.10 in /root/.ssh/known_hosts
Searching for 10.0.0.10:22 in /root/.ssh/known_hosts
[05/07/26 17:11:54] [SSH] SSH host key matches key in Known Hosts file.
ERROR: Failed to authenticate as root. Wrong password.
(credentialId:jenkins-slave-01/method:password)
[05/07/26 17:11:57] [SSH] Authentication failed.
Authentication failed.
[05/07/26 17:11:57] Launch failed – cleaning up connection
[05/07/26 17:11:57] [SSH] Connection closed.

节点状态显示为 offline，每隔几分钟自动重试，均以失败告终。

根因分析

很多人第一反应是”新机器缺少 Java 环境”，但仔细阅读日志，连接在认证阶段就已失败，根本没有到达 JVM 启动环节。

真正的问题链条如下：

旧机器崩溃
    ↓
新机器申请（相同 IP：10.0.0.10）
    ↓
重做了系统层面的 SSH 免密（authorized_keys）
    ↓
但 Jenkins 的 Credential 存储的是「密码」而非「SSH Key」
    ↓
新机器 root 密码 ≠ Jenkins 存储的旧密码
    ↓
认证失败，节点无法上线

关键日志特征：method:password —— 说明 Jenkins 走的是密码认证，不是 SSH Key 认证，所以手动配的免密对 Jenkins 完全没有生效。

完整恢复步骤

Step 1 — 验证网络和 SSH 基础连通性

先在 Jenkins Master 上确认能正常 SSH 登录新机器：

ssh root@10.0.0.10

如果提示 WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED，说明新机器的主机指纹和 known_hosts 里的旧记录冲突，需要先清理：

# 删除旧指纹
ssh-keygen -R 10.0.0.10

# 重新连接，接受新指纹
ssh root@10.0.0.10

这一步经常被忽略，但 Jenkins 的 KnownHostsFileKeyVerificationStrategy 依赖本机 known_hosts，指纹不匹配会导致连接直接被拒绝。

Step 2 — 切换为 SSH Key 认证（推荐，一劳永逸）

2.1 生成或复用 Jenkins Master 的密钥对

# 检查是否已有密钥
ls ~/.ssh/id_rsa

# 没有则生成
ssh-keygen -t rsa -b 4096 -C "jenkins-master" -f ~/.ssh/id_rsa -N ""

2.2 将公钥写入新 slave 机器

ssh-copy-id root@10.0.0.10

# 或手动方式
cat ~/.ssh/id_rsa.pub | ssh root@10.0.0.10 \
  "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

2.3 验证免密登录

ssh -o PasswordAuthentication=no root@10.0.0.10 "echo OK"
# 输出 OK 则成功

Step 3 — 更新 Jenkins Credential

进入 Jenkins Web UI：

Manage Jenkins → Credentials → System → Global credentials
→ 找到 jenkins-slave-01 → 点击修改

将凭据类型从 Username with password 修改为 SSH Username with private key：

字段	值
Kind	SSH Username with private key
Username	root
Private Key	选择 Enter directly，粘贴 `~/.ssh/id_rsa` 私钥内容
Passphrase	生成时设置了则填写，否则留空

私钥内容获取：

cat ~/.ssh/id_rsa
# 复制全部内容，包括 -----BEGIN/END----- 行

Step 4 — 确认 slave 节点的 Java 环境

认证问题解决后，Jenkins 会尝试通过 SSH 在 slave 上启动 agent。
查看 slave 节点的 Configure 页面，找到 JavaPath 配置项：

/opt/jdk-17/bin/java

在新机器上确认该路径存在：

ls /opt/jdk-17/bin/java
java -version

如果路径不存在，有两种处理方式：

方式 A：安装 Java 到相同路径

# 下载对应版本的 JDK（以 Eclipse Temurin 为例）
wget https://github.com/adoptium/temurin17-binaries/releases/download/jdk-17.0.15%2B6/OpenJDK17U-jdk_x64_linux_hotspot_17.0.15_6.tar.gz
mkdir -p /opt
 tar -xzf OpenJDK17U-jdk_x64_linux_hotspot_17.0.15_6.tar.gz -C /opt/

方式 B：安装系统 Java 并更新 Jenkins 配置

# Ubuntu/Debian
apt update && apt install -y openjdk-17-jdk

# CentOS/RHEL
yum install -y java-17-openjdk

# 获取实际路径
which java         # 或 update-alternatives --list java

然后在 Jenkins slave 节点 Configure → JavaPath 中填写新路径。

Step 5 — 重启 slave 节点连接

在 Jenkins slave 节点页面点击 Launch agent 或等待自动重试，观察 Log 输出：

[SSH] Opening SSH connection to 10.0.0.10:22.
[SSH] SSH host key matches key in Known Hosts file. Connection will be allowed.
[SSH] Authentication successful.
Remoting version: ...
Agent successfully connected and online

看到 Authentication successful 和 online 即恢复成功。

问题复盘

排查点	状态	说明
网络连通性	正常	SSH 端口 22 正常
known_hosts 指纹	需清理	新机器指纹变更，旧记录需删除
Jenkins Credential 类型	根本原因	password 方式，密码与新机器不符
slave 上的 Java 环境	需确认	新机器需重新安装并确认路径一致

经验总结

1. 优先使用 SSH Key 认证，而不是密码

密码认证在机器重建时必然失效；SSH Key 认证只要提前同步公钥，重建后无需修改 Jenkins 任何配置。

2. 机器重建后必须清理 known_hosts

ssh-keygen -R

这一步是 checklist 里必须有的一项，否则即使认证方式正确，指纹不匹配也会导致连接被拒绝。

3. 将 slave 初始化写成脚本

新机器上线时一键初始化，避免手工遗漏：

#!/bin/bash
# jenkins-slave-init.sh

set -e

JAVA_INSTALL_DIR="/opt"
JENKINS_MASTER_PUBKEY="ssh-rsa AAAA... jenkins-master"

echo "[1/4] Installing Java..."
apt update -qq && apt install -y openjdk-17-jdk

echo "[2/4] Setting up SSH authorized_keys..."
mkdir -p ~/.ssh && chmod 700 ~/.ssh
echo "$JENKINS_MASTER_PUBKEY" >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

echo "[3/4] Creating Jenkins workspace directory..."
mkdir -p /data/jenkins/workspace

echo "[4/4] Done. Java path: $(which java)"
java -version

4. 考虑使用 Jenkins Configuration as Code（JCasC）

将 slave 节点配置纳入版本控制，机器重建后配置自动恢复，彻底消除人工操作失误的可能。

参考资料

Jenkins SSH Build Agents Plugin
Eclipse Temurin JDK Downloads
Jenkins Configuration as Code Plugin

Podman CLI on Windows 安装与配置指南

2026-04-30T06:51:00.000Z

Podman 是 Docker 的开源替代方案，在 Windows 上通过 WSL2 虚拟机运行容器。本文档详细阐述 Podman on Windows 的完整部署流程，包括安装配置、代理设置、私有仓库信任、开机自启动及日常维护等关键环节，适用于需要在 Windows 环境下使用容器技术的开发与运维场景。

适用版本与环境说明：

Podman: 5.x（本文示例版本）
操作系统: Windows 10/11（需启用 WSL2）
代理软件: v2rayN（或其他支持局域网访问的代理）
私有仓库: Harbor（HTTP 或自签名证书）
更新日期: 2026-04-30（建议关注 Podman GitHub Releases）

Podman on Windows 通过 WSL2 虚拟机运行，与 Docker Desktop 的架构类似但无需付费许可。本文配置示例基于 Podman 5.x 版本，不同版本配置参数可能略有差异。

Podman 架构概述

核心概念

Podman on Windows 采用以下架构：

组件	功能	说明
Podman CLI	命令行客户端	与 Docker CLI 命令兼容
Podman Machine	WSL2 虚拟机	容器运行环境
containerd	容器运行时	管理容器生命周期
crun/runc	OCI 运行时	创建和运行容器

与 Docker 的差异

特性	Podman	Docker Desktop
运行模式	无守护进程（daemonless）	需要 dockerd 守护进程
Root 权限	支持 rootless 模式	默认需要 root
Pod 支持	原生支持 Kubernetes Pod	需要额外工具
许可费用	开源免费	企业版收费
架构	WSL2 轻量虚拟机	WSL2 + Hyper-V

安装 Podman

方式一：winget（推荐）

winget install RedHat.Podman

方式二：手动下载

前往 Podman Releases 下载最新 .exe 安装包。

安装完成后验证：

podman --version

初始化 Podman Machine

Podman on Windows 通过 WSL2 虚拟机运行，需要初始化一个 Machine 实例。

podman machine init

podman machine set --rootful

podman machine start

podman machine list

预期输出：

NAME                     VM TYPE     CREATED        LAST UP            CPUS   MEMORY   DISK SIZE
podman-machine-default*  wsl         X minutes ago  Currently running  8      2GiB     100GiB

参数说明：

参数	说明	推荐值
`--rootful`	以 root 用户运行容器	生产环境推荐，兼容性更好
`--cpus`	分配 CPU 核数	默认 8
`--memory`	分配内存大小	默认 2GiB
`--disk-size`	虚拟磁盘大小	默认 100GiB

清理系统代理环境变量

Windows 系统代理会被传入 VM，如果代理软件监听的是 127.0.0.1，在 VM 内会指向虚拟机本身而非宿主机，导致连接失败，必须清除。

Set-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet Settings" -Name ProxyEnable -Value 0
Set-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet Settings" -Name ProxyServer -Value ""

[System.Environment]::SetEnvironmentVariable("HTTP_PROXY", $null, "Machine")
[System.Environment]::SetEnvironmentVariable("HTTPS_PROXY", $null, "Machine")

[System.Environment]::SetEnvironmentVariable("HTTP_PROXY", $null, "User")
[System.Environment]::SetEnvironmentVariable("HTTPS_PROXY", $null, "User")

Remove-Item Env:HTTP_PROXY -ErrorAction SilentlyContinue
Remove-Item Env:HTTPS_PROXY -ErrorAction SilentlyContinue

echo $env:HTTP_PROXY
echo $env:HTTPS_PROXY

配置 VM 内部代理

Podman Machine 运行在 WSL2 中，需要在 VM 内部配置代理，且代理地址必须使用宿主机在 WSL 网卡上的 IP。

查找宿主机 WSL IP

在 Windows 侧执行：

ipconfig

找到 vEthernet (WSL) 对应的 IPv4 地址，通常为 172.20.128.1。

开启代理软件局域网访问

以 v2rayN 为例：

设置 → Core 基础设置 → 允许来自局域网的连接 → On → 确定 → 重启服务

写入 VM 代理配置

podman machine ssh

进入 VM 后执行（将 172.20.128.1 替换为你的实际 WSL IP，10808 替换为你的代理端口）：

tee /etc/profile.d/default-env.sh << 'EOF'
export http_proxy=http://172.20.128.1:10808
export https_proxy=http://172.20.128.1:10808
export HTTP_PROXY=http://172.20.128.1:10808
export HTTPS_PROXY=http://172.20.128.1:10808
export no_proxy=localhost,127.0.0.1,::1,
export NO_PROXY=localhost,127.0.0.1,::1,
EOF

cat /etc/profile.d/default-env.sh

exit

重启 Machine 使配置生效

podman machine stop
podman machine start

配置私有 Harbor 仓库信任

内网 Harbor 通常使用 HTTP 或自签名证书，需要添加 insecure 信任。

podman machine ssh

tee /etc/containers/registries.conf.d/harbor.conf << 'EOF'
[[registry]]
location = ""
insecure = true
EOF

cat /etc/containers/registries.conf.d/harbor.conf

exit

已在 NO_PROXY 中，访问私有仓库会自动绕过代理，直连内网。

配置开机自启动

Podman Machine 默认不随 Windows 启动，通过计划任务实现自动启动。

$action = New-ScheduledTaskAction -Execute "podman" -Argument "machine start"
$trigger = New-ScheduledTaskTrigger -AtLogOn
$settings = New-ScheduledTaskSettingsSet -ExecutionTimeLimit (New-TimeSpan -Minutes 2)

Register-ScheduledTask -TaskName "PodmanMachineStart" `
  -Action $action `
  -Trigger $trigger `
  -Settings $settings `
  -RunLevel Highest `
  -Force

验证注册成功：

Get-ScheduledTask -TaskName "PodmanMachineStart"

取消自启动：

Unregister-ScheduledTask -TaskName "PodmanMachineStart" -Confirm:$false

触发时机为用户登录时。若需要真正的开机启动（无需登录），将 -AtLogOn 改为 -AtStartup 并配置 Windows 自动登录。

验证完整环境

podman machine list

podman pull docker.io/library/nginx:latest

podman pull /-image>:

podman run --rm nginx:latest echo "Podman is working!"

日常维护命令

podman machine start
podman machine stop
podman machine stop && podman machine start

podman machine ssh

podman images

podman ps

podman ps -a

podman container prune

podman image prune

故障排查指南

常见问题与解决方案

错误信息	原因	解决方案
`proxyconnect tcp: connection refused`	代理软件未运行或端口错误	启动代理软件，确认端口一致
`proxyconnect tcp: 127.0.0.1:xxxx`	Windows 系统代理传入 VM	执行「清理系统代理环境变量」步骤
`Trying to pull...` 无响应	代理未开启局域网访问	v2rayN 开启「允许来自局域网的连接」
`permission denied /var/run/docker.sock`	非 rootful 模式	`podman machine set --rootful`
`VM already exists`	Machine 未完全清理	`podman machine rm --force podman-machine-default`

参考资源

官方文档

Podman 官方文档
Podman Windows 安装指南
Podman Machine 配置
containers/registries.conf 配置

Windows 小狼毫输入法（Rime）安装配置指南

2026-04-24T02:36:58.000Z

小狼毫（Weasel）是 Rime 输入法在 Windows 平台上的实现。Rime 是一款开源、高度可定制的输入法引擎，支持多种输入方案（拼音、双拼、五笔等），深受技术用户喜爱。本文将介绍小狼毫的安装、基础配置和进阶用法。

适用版本与环境说明：

操作系统: Windows 10/11
输入法版本: 小狼毫 (Weasel) 0.15+
更新日期: 2026-04-24

Rime 是跨平台的输入法引擎：

Windows: 小狼毫 (Weasel)
macOS: 鼠须管 (Squirrel)
Linux: 中州韵 (ibus-rime / fcitx5-rime)

安装步骤

方式一：官方下载

访问 Rime 官网下载安装包：

https://rime.im/download/

下载后双击安装程序，按提示完成安装。

方式二：包管理器安装（推荐）

使用 Windows 包管理器安装：

# 使用 winget
winget install RIME.Weasel

# 或使用 scoop
scoop install weasel

安装完成后需要重启系统或注销后重新登录，输入法才能正常加载。

基础配置

配置文件位置

小狼毫的用户配置文件位于：

%APPDATA%\Rime\

主要的配置文件：

文件名	说明
`default.custom.yaml`	全局配置（候选词数量、输入方案等）
`weasel.custom.yaml`	外观配置（配色、字体、布局）
`user.yaml`	用户信息

最小化配置

创建 `default.custom.yaml`

patch:
  # 候选词数量
  "menu/page_size": 5
  
  # 配色方案
  style/color_scheme: clean_white
  
  # 输入方案列表
  schema_list:
    - schema: luna_pinyin_simp  # 简体拼音

创建 `weasel.custom.yaml`

patch:
  # 配色方案
  "style/color_scheme": minimal_white
  "style/horizontal": true  # 横向候选栏
  "style/font_face": "Segoe UI, Microsoft YaHei"
  "style/font_point": 12
  "style/layout/border": 0
  "style/layout/margin_x": 12
  "style/layout/margin_y": 12
  "style/layout/spacing": 10
  
  # 自定义配色：简约白
  "preset_color_schemes/minimal_white":
    name: "简约白 / Minimal White"
    author: "Custom"
    back_color: 0xFFFFFF
    border_color: 0xE0E0E0
    text_color: 0x424242
    hilited_text_color: 0x000000
    hilited_back_color: 0xF5F5F5
    candidate_text_color: 0x606060
    hilited_candidate_text_color: 0x000000
    hilited_candidate_back_color: 0xEEEEEE

部署配置

修改配置文件后，需要重新部署才能生效：

右键点击任务栏小狼毫图标
选择 重新部署
等待部署完成（几秒钟）

快速上手

常用快捷键

快捷键	功能
`Ctrl + ~`	切换输入方案
`Ctrl + Shift + 1`	中英文切换
`Ctrl + Shift + F`	繁简转换
`Shift`	临时英文模式
`Ctrl + .`	切换中西文标点

切换输入方案

安装后默认使用明月拼音，可通过以下方式切换：

按 Ctrl + ~ 打开方案选单
输入方案编号选择
或右键托盘图标 → 输入方案设定

进阶配置

同步配置到 GitHub

使用 Git 管理配置文件，实现多设备同步：

cd $env:APPDATA\Rime

# 初始化 Git 仓库
git init
git add .
git commit -m "Init Rime config"

# 关联远程仓库
git remote add origin https://github.com/your-username/rime-config.git
git branch -M main
git push -u origin main

在其他设备上恢复配置：

cd $env:APPDATA\Rime
git clone https://github.com/your-username/rime-config.git .

词库扩展

使用雾凇拼音词库

雾凇拼音是一个高质量的简体拼音词库：

# 克隆词库
cd $env:TEMP
git clone https://github.com/iDvel/rime-ice.git

# 复制配置文件到 Rime 目录
Copy-Item -Recurse -Force "$env:TEMP\rime-ice\*" "$env:APPDATA\Rime\"

复制后重新部署即可生效。

自定义词库

在用户目录创建 custom_phrase.txt：

# 编码词组
rime    小狼毫
github  GitHub

在 luna_pinyin.custom.yaml 中引入：

patch:
  "translator/dictionary": luna_pinyin
  "translator/prism": luna_pinyin_simp
  "translator/custom_phrase": "custom_phrase.txt"

添加更多输入方案

内置输入方案：

方案	说明
`luna_pinyin`	明月拼音（繁体）
`luna_pinyin_simp`	明月拼音（简体）
`double_pinyin`	自然码双拼
`double_pinyin_flypy`	小鹤双拼
`wubi_pinyin`	五笔拼音混输
`terra_pinyin`	地球拼音

在 default.custom.yaml 中添加：

patch:
  schema_list:
    - schema: luna_pinyin_simp
    - schema: double_pinyin_flypy
    - schema: wubi_pinyin

常见问题

Q1: 输入法候选框不显示？

检查小狼毫服务是否运行：

# 重启服务
net stop WeaselService
net start WeaselService

或在任务管理器中重启 WeaselServer.exe。

Q2: 配置修改后无效？

确保文件编码为 UTF-8
检查 YAML 格式是否正确（注意缩进）
重新部署配置

Q3: 如何设置默认英文模式？

在 default.custom.yaml 中添加：

patch:
  "switches/@0/reset": 1  # 0 为中文，1 为英文

Q4: 如何关闭模糊音？

在 luna_pinyin.custom.yaml 中设置：

patch:
  "speller/algebra":
    - erase/^xx$/  # 移除模糊音配置

Q5: 如何备份用户词频？

用户词频存储在以下文件：

%APPDATA%\Rime\luna_pinyin.userdb\

使用 Git 同步或定期备份此目录。

配色方案参考

简约白

"preset_color_schemes/minimal_white":
  name: "简约白"
  back_color: 0xFFFFFF
  border_color: 0xE0E0E0
  text_color: 0x424242
  hilited_candidate_text_color: 0x000000
  hilited_candidate_back_color: 0xEEEEEE
  candidate_text_color: 0x606060

深色模式

"preset_color_schemes/minimal_dark":
  name: "简约黑"
  back_color: 0x2B2B2B
  border_color: 0x3C3C3C
  text_color: 0xD4D4D4
  hilited_candidate_text_color: 0xFFFFFF
  hilited_candidate_back_color: 0x3C3C3C
  candidate_text_color: 0x808080

跟随系统

在 weasel.custom.yaml 中设置：

patch:
  "style/color_scheme_dark": minimal_dark  # 深色模式配色
  "style/color_scheme": minimal_white        # 浅色模式配色

总结

小狼毫作为 Rime 在 Windows 平台的实现，提供了高度可定制的输入体验。通过配置文件可以精细控制候选词数量、外观样式、输入方案等。配合 Git 同步，可以轻松在多台设备间共享配置和词库。对于追求效率和个性化的用户来说，小狼毫是一个值得尝试的选择。

Windows Tiny10 恢复中文语言包与微软拼音输入法完整指南

2026-04-24T02:17:18.000Z

Tiny10 是 Windows 10 的精简版本，移除了大量预装组件以减小系统体积。然而，这也导致了中文语言包、输入法和字体等组件的缺失，使得中文显示乱码，影响日常使用。本文将详细介绍如何在 Tiny10 系统中恢复中文支持，包括语言包安装、输入法配置和字体修复。

适用版本与环境说明：

操作系统: Windows Tiny10（基于 Windows 10 LTSC 精简）
更新日期: 2026-04-24
需要管理员权限

Tiny10 移除了部分系统功能，某些 PowerShell 命令可能不可用。如果遇到命令执行失败，请尝试使用 DISM 替代方案。

问题背景

在 Tiny10 系统中，由于精简了语言包和输入法组件，会出现以下问题：

中文乱码：命令行、编辑器中的中文显示为乱码
无中文输入法：无法输入中文
系统区域设置缺失：无法切换到中文环境

方案一：命令行修复（推荐）

1. 安装中文语言包

方法一：使用 PowerShell（推荐）

以管理员身份运行 PowerShell：

# 添加中文语言到语言列表
$LanguageList = Get-WinUserLanguageList
$LanguageList.Add("zh-CN")
Set-WinUserLanguageList $LanguageList -Force

# 安装语言功能（字体、OCR等）
Install-Language -Language zh-CN

方法二：使用 DISM（备用）

如果上述命令不可用（Tiny10 可能移除了该功能），使用 DISM：

# 查看可用语言包
DISM /Online /Get-Capabilities

# 安装中文语言包和字体
DISM /Online /Add-Capability /CapabilityName:Language.Basic~~~zh-CN~0.0.1.0
DISM /Online /Add-Capability /CapabilityName:Language.Fonts.Hans~~~und-HANS~0.0.1.0
DISM /Online /Add-Capability /CapabilityName:Language.Handwriting~~~zh-CN~0.0.1.0
DISM /Online /Add-Capability /CapabilityName:Language.OCR~~~zh-CN~0.0.1.0
DISM /Online /Add-Capability /CapabilityName:Language.TextToSpeech~~~zh-CN~0.0.1.0

2. 恢复微软拼音输入法

# 确保语言包已安装
DISM /Online /Add-Capability /CapabilityName:Language.TextToSpeech~~~zh-CN~0.0.1.0

# 添加微软拼音输入法
$langList = Get-WinUserLanguageList
$langList[0].InputMethodTips.Clear()
$langList[0].InputMethodTips.Add('0804:00000804')  # 微软拼音
Set-WinUserLanguageList $langList -Force

3. 修复字体（解决乱码问题）

如果中文仍然显示乱码，可能是缺少中文字体。

方法一：从正常 Windows 系统复制字体

从正常的 Windows 10 系统复制以下字体文件到 Tiny10：

源路径: C:\Windows\Fonts\
目标路径: C:\Windows\Fonts\

需要复制的字体:
- msyh.ttc (微软雅黑)
- msyhbd.ttc (微软雅黑 Bold)
- simhei.ttf (黑体)
- simsun.ttc (宋体)

方法二：安装开源字体

# 下载 Noto Sans CJK SC 字体
Invoke-WebRequest -Uri "https://github.com/googlefonts/noto-cjk/raw/main/Sans/OTF/SimplifiedChinese/NotoSansCJKsc-Regular.otf" -OutFile "$env:TEMP\NotoSans.otf"

# 安装字体
Copy-Item "$env:TEMP\NotoSans.otf" "C:\Windows\Fonts\"
New-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Fonts" -Name "Noto Sans CJK SC (TrueType)" -Value "NotoSans.otf" -PropertyType String

4. 设置系统区域

# 设置系统区域为中文
Set-WinSystemLocale -SystemLocale zh-CN
Set-WinUILanguageOverride -Language zh-CN
Set-Culture -CultureInfo zh-CN

# 设置非 Unicode 程序的语言
Set-WinSystemLocale zh-CN

设置完成后需要重启系统才能生效。

方案二：离线包安装（无网络环境）

如果系统无法联网，可以使用离线安装方式。

1. 准备离线包

从正常 Windows 10 系统复制语言包文件：

源路径: C:\Windows\servicing\LCU\
或者从微软官方下载 Language Pack ISO

2. 使用 DISM 离线安装

# 假设语言包存放在 D:\LanguagePack 目录
DISM /Online /Add-Package /PackagePath:"D:\LanguagePack\Microsoft-Windows-LanguageFeatures-Basic-zh-cn-Package.cab"
DISM /Online /Add-Package /PackagePath:"D:\LanguagePack\Microsoft-Windows-LanguageFeatures-Fonts-Hans-Package.cab"

方案三：GUI 方式（备选）

如果命令行方式遇到问题，可以尝试图形界面操作：

打开 Settings → Time & Language → Language
点击 Add a language
选择 中文（简体，中国）
点击 Options → Download language pack
重启系统

验证安装

重启系统后，执行以下命令验证：

# 检查已安装的语言包
Get-WinUserLanguageList

# 检查系统语言
Get-WinSystemLocale

# 测试中文显示
echo 测试中文显示

# 设置命令行为 UTF-8 编码
chcp 65001

备选方案：便携版输入法

如果以上方法都无法恢复微软拼音输入法，可以考虑使用第三方便携版输入法：

小小输入法（绿色版）

官网: https://yong.dgod.net/
特点: 无需安装，不依赖系统组件
支持拼音、五笔等多种输入方式

使用方法

下载便携版压缩包
解压到任意目录
运行主程序即可使用

常见问题

Q1: DISM 命令执行失败？

检查 Windows Update 服务是否正常运行：

# 启动 Windows Update 服务
net start wuauserv

# 或者设置为自动启动
sc config wuauserv start= auto
net start wuauserv

Q2: 字体安装后仍然乱码？

检查控制面板 → 区域 → 管理 → 更改系统区域设置
勾选 “Beta 版: 使用 Unicode UTF-8 提供全球语言支持”
重启系统

Q3: 输入法切换快捷键无效？

# 检查输入法设置
Get-WinUserLanguageList | Select-Object InputMethodTips

# 手动添加输入法切换热键
# 设置 → 时间和语言 → 语言 → 拼写、键入和键盘设置 → 高级键盘设置 → 语言栏选项

总结

Tiny10 作为精简版系统，虽然体积小、运行快，但也牺牲了一些实用性组件。通过本文介绍的方法，可以恢复中文语言支持，解决中文乱码问题，并重新获得中文输入能力。建议优先使用命令行方式（方案一），如遇网络问题则使用离线安装（方案二），最后可考虑便携版输入法作为备选方案。

Docker 微服务架构安全实践指南

2026-04-17T03:00:00.000Z

在 Docker 容器化微服务架构中,安全是一个不可忽视的重要环节。本文将分享一套完整的 Docker 微服务环境安全加固方案,涵盖端口暴露最小化、网络隔离、敏感信息管理以及多层防御策略。通过本指南,你可以有效缩减 90%+ 的攻击面,提升整体系统安全性。

适用版本与环境说明：

Docker Engine: 20.10.x 及以上版本
Docker Compose: 2.x 及以上版本
操作系统: Ubuntu 20.04+/Debian 11+/CentOS 7.9+
内核版本: 建议 4.18+ 以支持完整的网络和安全特性
更新日期: 2026-04-17（建议每季度检查 Docker 安全公告）

核心安全原则

端口最小化暴露原则

在容器化环境中,端口暴露应遵循最小权限原则:

端口类型	是否映射到宿主机	说明
22/tcp (SSH)	✅ 是	系统管理必需
80/tcp (HTTP)	✅ 是	Web 业务入口
443/tcp (HTTPS)	✅ 是	安全 Web 入口(推荐)
数据库端口 (5432, 3306等)	❌ 否	仅容器内部访问
缓存端口 (6379, 11211等)	❌ 否	仅容器内部访问
注册中心端口 (8848, 8500等)	❌ 否	仅容器内部访问
后端服务端口	❌ 否	通过网关转发
管理后台端口	❌ 否	通过反向代理或VPN访问

网络分层架构

                 [ 用户/外部网络 ]
                        |
                        | HTTP/HTTPS (80/443)
                        v
               [ Nginx 容器 (唯一入口) ]
                        |
           ---( Docker 内部网络: apps、middleware等 )---
                        |
                        v
             [ gateway 容器 (网关) ]
                    /   |   \
                   /    |    \  (通过容器名称转发)
                  v     v     v
[ auth-service ]  [ user-service ]  [ business-service ]
     |             |                |
     |             |                |
     +-------------+----------------+
                   |
                   v
       [ 中间件层 ]
     为了安全，以上所有容器均无端口映射到外部

网络分层说明:

外部入口层: 仅开放 HTTP(80) 和 HTTPS(443) 端口,所有流量必须通过 Nginx
网关层: API Gateway 负责路由转发和权限验证
应用服务层: 各业务微服务,通过容器名称互相调用
中间件层: 数据库、缓存、注册中心等基础服务,严格内部访问

重要说明:
在 Docker Compose 环境中,服务间通信应使用容器名称(container_name)而非服务名称(service name)。容器名称是容器在网络中的唯一标识,确保服务间能够正确解析和访问。

安全策略:

所有内部服务容器均无端口映射到宿主机
外部请求只能到达 Nginx 容器
内部服务通过 Docker 网络隔离,无法直接从外部访问

宿主机防火墙配置

启用 UFW 防火墙

# 启用 UFW 防火墙
sudo ufw enable

# 设置默认策略:拒绝所有入站,允许所有出站
sudo ufw default deny incoming
sudo ufw default allow outgoing

# 仅开放必要端口
sudo ufw allow 22/tcp comment 'SSH Management'
sudo ufw allow 80/tcp comment 'HTTP Web Entry'
sudo ufw allow 443/tcp comment 'HTTPS Web Entry'

# 验证配置
sudo ufw status verbose

预期输出:

Status: active
Default: deny (incoming), allow (outgoing)

To                         Action      From
--                         ------      ----
22/tcp                     ALLOW IN    Anywhere
80/tcp                     ALLOW IN    Anywhere
443/tcp                    ALLOW IN    Anywhere

Docker 网络架构配置

创建隔离网络

# docker-compose.yml 顶层网络配置
networks:
  # 前端接入层网络
  frontend:
    driver: bridge
    internal: false  # 允许外部访问
  
  # 应用服务层网络
  apps:
    driver: bridge
    internal: true   # 仅内部通信(可选,根据需求)
  
  # 中间件层网络
  middleware:
    driver: bridge
    internal: true   # 严格内部访问
  
  # 模型服务层网络
  ai-services:
    driver: bridge
    internal: true

服务网络归属原则

服务类型	网络归属	端口映射
Nginx (反向代理)	frontend + apps	80:80, 443:443
API Gateway	apps + middleware	无
Java 微服务	apps + middleware	无
Python 后端	apps + ai-services	无
PostgreSQL	middleware + apps	无
Redis	middleware + apps	无
Nacos	middleware + apps	无
MinIO	middleware + apps	无
AI 模型服务	ai-services + apps	无

跨 Compose 文件的外部网络配置

当服务分布在不同 Docker Compose 文件中时,需要使用外部网络实现互联互通。关键步骤:

查看现有 Docker 网络:

# 查看所有 Docker 网络
docker network ls

# 输出示例:
# NETWORK ID     NAME                      DRIVER    SCOPE
# abc123def456   installapps_apps          bridge    local
# def789ghi012   middleware                bridge    local

在 Compose 文件中引用外部网络:

services:
  nginx:
    image: nginx:1.29.0-alpine
    container_name: nginx
    ports:
      - "80:80"
      - "443:443"
    environment:
      - TZ=Asia/Shanghai
    networks:
      - middleware
      - installapps_apps  # 引用外部网络(来自其他 compose 文件)
    healthcheck:
      test: ["CMD", "nginx", "-t"]
      interval: 30s
      timeout: 10s
      retries: 3
    volumes:
      - ./conf/mime.types:/etc/nginx/mime.types:ro
      - ./conf/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./conf/web.conf:/etc/nginx/conf.d/default.conf:ro
      - ./data/nginx/html:/usr/share/nginx/html
      - ./data/nginx/logs:/var/log/nginx:rw
    restart: always

networks:
  installapps_apps:
    external: true  # 声明为外部网络
  middleware:
    driver: bridge

外部网络的名称必须与 docker network ls 中显示的名称完全一致。

端口映射配置规范

正确示例:仅映射必要端口

services:
  # 唯一对外入口
  nginx:
    image: nginx:1.29-alpine
    container_name: nginx
    ports:
      - "80:80"
      - "443:443"
    networks:
      - frontend
      - apps

  # 后端服务:不映射端口
  gateway:
    image: /gateway:
    container_name: gateway
    # ports: 删除所有端口映射
    networks:
      - apps
      - middleware

  # 数据库:不映射端口
  postgres:
    image: /postgres:
    container_name: postgres
    # ports: 删除所有端口映射
    networks:
      - middleware

  # 缓存:不映射端口
  redis:
    image: /redis:
    container_name: redis
    # ports: 删除所有端口映射
    networks:
      - middleware

关键点:

ports 配置中的端口是容器自身服务端口,如 Nginx 默认 80、PostgreSQL 默认 5432
容器间通信使用 container_name 作为主机名,而非 service name

错误示例:过度暴露端口

# 危险!不要这样配置
services:
  postgres:
    image: postgres:17
    container_name: postgres
    ports:
      - "5432:5432"  # ⚠️ 数据库端口暴露在外
  
  redis:
    image: redis:8
    container_name: redis
    ports:
      - "6379:6379"  # ⚠️ 缓存端口暴露在外
  
  backend:
    image: backend:latest
    container_name: backend
    ports:
      - "8080:8080"  # ⚠️ 后端端口暴露在外

敏感信息安全处理

配置文件脱敏规范

镜像名称脱敏

# ❌ 原始配置(含敏感信息)
services:
  app:
    image: "mycompany/app-server:v1.2.3"
    image: "registry.internal.com/project/backend:abc123"

# ✅ 脱敏后配置
services:
  app:
    image: "/:"
    # 或使用环境变量
    image: "${REGISTRY}/${IMAGE_NAME}:${IMAGE_TAG}"

密码凭证脱敏

# ❌ 原始配置(硬编码密码)
services:
  postgres:
    container_name: postgres
    environment:
      POSTGRES_PASSWORD: "MyP@ssw0rd123"
  
  nacos:
    container_name: nacos
    environment:
      SPRING_CLOUD_NACOS_PASSWORD: "Nacos@123.com"

# ✅ 方案一:使用环境变量文件
services:
  postgres:
    container_name: postgres
    env_file:
      - .env.postgres  # 添加到 .gitignore
  
  nacos:
    container_name: nacos
    env_file:
      - .env.nacos

# ✅ 方案二:使用 Docker Secrets(Swarm模式)
services:
  postgres:
    container_name: postgres
    secrets:
      - postgres_password
secrets:
  postgres_password:
    external: true

# ✅ 方案三:使用变量引用
services:
  postgres:
    container_name: postgres
    environment:
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
# .env 文件(不提交到版本库)
# POSTGRES_PASSWORD=

IP 地址和域名脱敏

# ❌ 原始配置
services:
  app:
    container_name: app
    extra_hosts:
      - "server01.internal:192.168.1.100"
    environment:
      SPRING_CLOUD_NACOS_DISCOVERY_IP: "192.168.1.100"
      SERVER_URL: "https://api.example.com"

# ✅ 脱敏后配置
services:
  app:
    container_name: app
    extra_hosts:
      - ":"
    environment:
      SPRING_CLOUD_NACOS_DISCOVERY_IP: "${SERVER_IP}"
      SERVER_URL: "${API_BASE_URL}"

.gitignore 配置

# 敏感配置文件
.env
.env.*
*.env
secrets/

# 包含敏感信息的配置
docker-compose.override.yml
docker-compose.prod.yml

# 日志文件(可能含敏感信息)
logs/
*.log

环境变量模板文件

# .env.template(提交到版本库)
# 复制此文件为 .env 并填写实际值

# 数据库配置
POSTGRES_DB=
POSTGRES_USER=
POSTGRES_PASSWORD=

# Nacos 配置
NACOS_USERNAME=
NACOS_PASSWORD=

# MinIO 配置
MINIO_ROOT_USER=
MINIO_ROOT_PASSWORD=

# Redis 配置
REDIS_PASSWORD=

# 服务发现配置
SERVER_IP=
GATEWAY_PORT=

Nginx 安全请求头配置

基础安全头配置

server {
    listen 80;
    server_tokens off;  # 隐藏 Nginx 版本号
    absolute_redirect off;
    
    # 防止 MIME 类型嗅探
    add_header X-Content-Type-Options "nosniff" always;
    
    # XSS 防护
    add_header X-XSS-Protection "1; mode=block" always;
    
    # 防止点击劫持
    add_header X-Frame-Options "DENY" always;
    
    # 引用策略
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
    
    # 下载安全
    add_header X-Download-Options "noopen" always;
    
    # 跨域策略
    add_header X-Permitted-Cross-Domain-Policies "none" always;
    
    # 内容安全策略(根据实际需求调整)
    add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; connect-src 'self' http: https:; frame-ancestors 'none';" always;
    
    # HSTS(需配合 HTTPS 使用)
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    
    location / {
        root /usr/share/nginx/html;
        index index.html;
        try_files $uri $uri/ /index.html;
    }
    
    # 后端 API 代理(通过容器名称访问,不暴露端口)
    location /api/ {
        proxy_pass http://gateway:8080/;  # 使用容器名称
        proxy_buffering off;
        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;
    }
}

说明: Nginx 反向代理配置中使用的是容器名称(gateway),这是容器在网络中的标识符,确保请求能正确路由到目标容器。

安全请求头验证

# 验证安全头是否生效
curl -I http:///

# 预期输出应包含所有安全头
HTTP/1.1 200 OK
Server: nginx
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Referrer-Policy: strict-origin-when-cross-origin
X-Download-Options: noopen
X-Permitted-Cross-Domain-Policies: none
Content-Security-Policy: default-src 'self'; ...
Strict-Transport-Security: max-age=31536000; includeSubDomains

服务间通信配置

连接地址标准化

连接场景	❌ 错误配置	✅ 正确配置
Java 连接 Nacos	`:38848`	`nacos:8848`
Java 连接 PostgreSQL	`:35433`	`postgres:5432`
Java 连接 Redis	`:36379`	`redis:6379`
Nginx 转发请求	`http://:8080`	`http://gateway:8080`
服务注册地址	宿主机 IP	容器内部 IP(自动)

核心原则: 所有服务间通信使用容器名称作为主机名,Docker 内部 DNS 会自动解析为容器的内部 IP 地址。

配置示例

services:
  # API 网关
  gateway:
    image: /gateway:
    container_name: gateway
    networks:
      - apps
      - middleware
    environment:
      # 服务发现:使用容器名称
      SPRING_CLOUD_NACOS_CONFIG_SERVER_ADDR: nacos:8848
      SPRING_CLOUD_NACOS_DISCOVERY_SERVER_ADDR: nacos:8848
      # 数据库:使用容器名称
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/
      # 缓存:使用容器名称
      SPRING_REDIS_HOST: redis
      SPRING_REDIS_PORT: 6379

  # 业务服务
  app-service:
    image: /app-service:
    container_name: app-service
    networks:
      - apps
      - middleware
    environment:
      # 通过网关访问其他服务
      SERVICE_URL: http://gateway:8080
      # 直接访问中间件
      DATABASE_URL: postgres://postgres:5432/
      CACHE_URL: redis://redis:6379

  # 中间件
  postgres:
    image: /postgres:
    container_name: postgres
    networks:
      - middleware
    # 不映射端口,仅容器内访问
    
  redis:
    image: /redis:
    container_name: redis
    networks:
      - middleware
    # 不映射端口,仅容器内访问

  nacos:
    image: /nacos:
    container_name: nacos
    networks:
      - middleware
    # 不映射端口,仅容器内访问

安全审计检查清单

端口暴露检查

# 检查 Docker 端口映射
docker ps --format "table {{.Names}}\t{{.Ports}}" | grep -v "^NAMES"

# 仅应看到:
# nginx    0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp

# 检查宿主机监听端口
sudo netstat -tulnp | grep LISTEN

# 应仅看到: 22, 80, 443

网络隔离检查

# 查看容器网络
docker network ls

# 查看网络详情
docker network inspect apps
docker network inspect middleware

# 确认容器间可通过容器名称访问
docker exec -it  ping postgres
docker exec -it  ping redis
docker exec -it  ping nacos

防火墙规则检查

# 检查 UFW 状态
sudo ufw status verbose

# 应显示:
# Default: deny (incoming), allow (outgoing)
# 22/tcp ALLOW IN Anywhere
# 80/tcp ALLOW IN Anywhere
# 443/tcp ALLOW IN Anywhere

# 从外部扫描端口(应在其他机器上执行)
nmap -p 22,80,443,5432,6379,8848 

# 应仅看到 22, 80, 443 为 open

敏感信息检查

# 检查配置文件中的敏感信息
grep -r "password\|Password\|PASSWORD" docker-compose*.yml
grep -r "secret\|Secret\|SECRET" docker-compose*.yml
grep -r "[0-9]\{1,3\}\.[0-9]\{1,3\}\.[0-9]\{1,3\}\.[0-9]\{1,3\}" docker-compose*.yml

# 检查 .env 文件是否被忽略
git status | grep -i env

# 确认 .gitignore 包含敏感文件
cat .gitignore | grep -E "\.env|secret"

完整配置模板

docker-compose.yml 模板

version: '3.8'

# 网络配置
networks:
  frontend:
    driver: bridge
  apps:
    driver: bridge
  middleware:
    driver: bridge

# 通用配置
x-common-config: &common-config
  restart: unless-stopped
  networks:
    - apps
  logging:
    driver: "json-file"
    options:
      max-size: "10m"
      max-file: "3"

services:
  # ============ 前端层 ============
  nginx:
    image: /nginx:
    container_name: nginx
    ports:
      - "80:80"
      - "443:443"
    networks:
      - frontend
      - apps
    volumes:
      - ./conf/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./conf/web.conf:/etc/nginx/conf.d/default.conf:ro
      - ./data/certs:/etc/ssl/private:ro
      - ./data/html:/usr/share/nginx/html
    healthcheck:
      test: ["CMD", "nginx", "-t"]
      interval: 30s
      timeout: 10s
      retries: 3
    depends_on:
      - gateway

  # ============ 网关层 ============
  gateway:
    <<: *common-config
    image: /gateway:
    container_name: gateway
    networks:
      - apps
      - middleware
    environment:
      SPRING_CLOUD_NACOS_CONFIG_SERVER_ADDR: nacos:8848
      SPRING_CLOUD_NACOS_DISCOVERY_SERVER_ADDR: nacos:8848
    env_file:
      - .env.gateway
    depends_on:
      - nacos

  # ============ 应用层 ============
  app-service:
    <<: *common-config
    image: /app-service:
    container_name: app-service
    networks:
      - apps
      - middleware
    env_file:
      - .env.app

  # ============ 中间件层 ============
  postgres:
    image: /postgres:
    container_name: postgres
    networks:
      - middleware
    # 无端口映射
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "${POSTGRES_USER}"]
      interval: 30s
      timeout: 10s
      retries: 3

  redis:
    image: /redis:
    container_name: redis
    networks:
      - middleware
    # 无端口映射
    command: ["redis-server", "/usr/local/etc/redis/redis.conf"]
    volumes:
      - ./conf/redis.conf:/usr/local/etc/redis/redis.conf
      - ./data/redis:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3

  nacos:
    image: /nacos:
    container_name: nacos
    networks:
      - middleware
    # 无端口映射
    environment:
      MODE: standalone
      SPRING_DATASOURCE_PLATFORM: mysql
    env_file:
      - .env.nacos
    volumes:
      - ./data/nacos:/home/nacos/data
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8848/nacos/"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

环境变量文件模板

# .env.gateway
SPRING_CLOUD_NACOS_USERNAME=
SPRING_CLOUD_NACOS_PASSWORD=

# .env.app
DATABASE_URL=jdbc:postgresql://postgres:5432/
DATABASE_USER=
DATABASE_PASSWORD=
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=

# .env.nacos
MYSQL_SERVICE_HOST=
MYSQL_SERVICE_PORT=
MYSQL_SERVICE_USER=
MYSQL_SERVICE_PASSWORD=

故障排查诊断流程

网络隔离故障诊断

诊断流程图：

┌─────────────────────────────────────────────────────────────┐
│                    网络故障诊断流程                           │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
        ┌──────────────────────────────────┐
        │  1. 检查容器是否在同一网络        │
        │     docker network inspect  │
        └──────────────────────────────────┘
                           │
                  ┌────────┴────────┐
                  │                 │
              同一网络          不同网络
                  │                 │
                  ▼                 ▼
        ┌──────────────┐   ┌──────────────────┐
        │ 2. 测试连通性 │   │ 加入正确网络     │
        │ ping/dig     │   │ docker network   │
        │ curl         │   │ connect          │
        └──────────────┘   └──────────────────┘
                  │
                  ▼
        ┌──────────────────────────┐
        │  3. 检查端口映射配置      │
        │     docker ps --format   │
        └──────────────────────────┘
                  │
         ┌────────┴─────────┐
         │                  │
      端口未映射          端口已映射
      (预期状态)          (检查是否必要)
         │                  │
         ▼                  ▼
  ┌────────────┐    ┌──────────────────┐
  │ 服务正常    │    │ 评估安全风险     │
  └────────────┐    │ 考虑移除映射     │
                  └──────────────────┘

诊断命令链：

# ===== 第一阶段：网络连通性检查 =====

# 1. 查看所有网络
docker network ls

# 2. 检查特定网络中的容器
docker network inspect apps

# 3. 测试容器间连通性
docker exec -it gateway ping postgres
docker exec -it gateway ping redis
docker exec -it gateway ping nacos

# 4. 检查 DNS 解析
docker exec -it gateway dig postgres
docker exec -it gateway nslookup redis

# ===== 第二阶段：端口暴露检查 =====

# 5. 查看所有容器端口映射
docker ps --format "table {{.Names}}\t{{.Ports}}"

# 6. 检查宿主机监听端口
sudo netstat -tulnp | grep LISTEN
sudo ss -tulnp | grep LISTEN

# 7. 从外部扫描端口（在其他机器上执行）
nmap -p 22,80,443,5432,6379,8848 

# ===== 第三阶段：防火墙检查 =====

# 8. 检查 UFW 状态
sudo ufw status verbose

# 9. 检查 iptables 规则
sudo iptables -L -n -v

# 10. 检查 Docker iptables 规则
sudo iptables -t nat -L DOCKER -n -v

常见故障案例

案例 1：服务间无法通信

现象： Java 微服务无法连接 Nacos 或数据库

排查步骤：

# 1. 确认容器在同一网络
docker inspect gateway | grep -A 20 "Networks"
docker inspect nacos | grep -A 20 "Networks"

# 2. 检查容器名称
docker ps --format "{{.Names}}" | grep -E "gateway|nacos|postgres"

# 3. 测试 DNS 解析
docker exec -it gateway getent hosts nacos
# 如果返回空，说明 DNS 解析失败

# 4. 检查网络配置
docker network inspect apps --format '{{range .Containers}}{{.Name}}: {{.IPv4Address}}{{end}}'

# 5. 临时修复：手动添加 hosts
# 在 docker-compose.yml 中添加：
extra_hosts:
  - "nacos:"

根因分析：

容器不在同一网络（最常见）
容器名称不匹配（docker-compose.yml 中 container_name 配置错误）
Docker 内部 DNS 缓存问题（重启 Docker Daemon）

案例 2：外部无法访问服务

现象： 外部请求无法到达 Nginx 或返回 502

排查步骤：

# 1. 检查 Nginx 容器状态
docker ps | grep nginx
docker logs nginx --tail 100

# 2. 检查 Nginx 配置语法
docker exec nginx nginx -t

# 3. 测试 Nginx 到后端的连通性
docker exec nginx curl -v http://gateway:8080/
# 如果失败，说明 Nginx 无法访问后端

# 4. 检查端口映射
docker port nginx

# 5. 检查防火墙规则
sudo ufw status | grep -E "80|443"

# 6. 检查宿主机端口监听
sudo netstat -tulnp | grep -E ":80|:443"

根因分析：

Nginx 端口未正确映射到宿主机
防火墙规则阻止了外部访问
Nginx 配置中使用了错误的后端地址（IP而非容器名称）

案例 3：敏感信息泄露

现象： git status 显示 .env 文件或密码出现在日志中

排查步骤：

# 1. 检查 .gitignore 配置
cat .gitignore | grep -E "\.env|secret"

# 2. 检查是否有敏感文件被提交
git log --all --full-history -- "*.env"
git log --all --full-history -- "*password*"

# 3. 检查容器日志中的敏感信息
docker logs  | grep -i "password"
docker logs  | grep -E "[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+"

# 4. 检查 docker-compose.yml 硬编码密码
grep -r "password\|Password\|PASSWORD" docker-compose*.yml

# 5. 清理 Git 历史（如果已提交）
# 使用 BFG Repo-Cleaner 或 git filter-branch

修复方案：

# 1. 更新 .gitignore
cat >> .gitignore << EOF
.env
.env.*
*.env
secrets/
docker-compose.override.yml
EOF

# 2. 从 Git 中移除已提交的敏感文件
git rm --cached .env
git rm --cached docker-compose.override.yml

# 3. 使用环境变量替代硬编码密码
# 编辑 docker-compose.yml，改为：
environment:
  POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}

参考资源

官方文档

Docker 官方文档
Docker 安全最佳实践
Docker 网络配置指南
Docker Compose 官方文档
Nginx 官方文档
Nginx 安全配置指南

安全标准与最佳实践

CIS Docker Benchmark - Docker 安全配置基准
OWASP Docker 安全
Docker 安全扫描指南
容器安全检查清单

工具与扫描器

Trivy - 容器漏洞扫描器
Docker Bench for Security - Docker 安全审计脚本
Falco - 容器运行时安全
Clair - 镜像漏洞分析

网络与隔离

Docker 网络架构详解
Docker 内部网络 DNS
CNI 网络插件规范
Linux 网络 namespaces

社区资源

Docker GitHub 仓库
Docker 安全公告
Nginx 安全头配置
docker-microservice-security GitHub 讨论

进阶阅读

《Docker 安全最佳实践》电子书
云原生安全白皮书
容器隔离技术深度解析

总结

核心安全措施

端口最小化: 仅开放 80/443 (Web) 和 22 (SSH)
网络隔离: 所有服务通过 Docker 内部网络通信
配置脱敏: 使用环境变量和 secrets 管理敏感信息
安全请求头: Nginx 注入完整的安全响应头
防火墙双重防护: Docker 网络隔离 + 宿主机 UFW 防火墙
服务发现: 使用容器名称而非 IP 地址
定期审计: 执行安全检查脚本

安全收益

攻击面缩减 90%+: 数据库、缓存、后端服务端口完全隐藏
网络嗅探防护: 内部流量在容器网络内闭环
配置安全性: 敏感信息不入代码库
可维护性提升: 服务发现机制自动适应环境变化
符合最佳实践: 遵循云原生安全部署标准

通过本指南的实施,你可以构建一个安全、可靠的 Docker 微服务架构环境,有效降低安全风险,保护业务系统免受外部威胁。

Kubernetes 生产级部署完整指南（kubeadm）

2025-11-13T09:47:25.000Z

Kubernetes 是云原生应用编排的核心平台。本文档提供生产级 Kubernetes 集群部署方案，涵盖架构设计、环境准备、组件安装、网络配置、安全加固、性能优化和故障排查等全流程内容，适用于学习和生产环境。

适用版本与环境说明：

Kubernetes: 1.28.x - 1.33.x（本文以 v1.33.6 为示例）
Containerd: 1.7.x 及以上版本
Flannel: v0.27.x 及以上版本
操作系统: Debian 12 (Trixie)/Ubuntu 22.04+/CentOS 7.9+/Rocky Linux 9+
内核版本: 建议 5.4+ 以支持完整的容器网络特性
更新日期: 2025-11-13（建议关注 Kubernetes 官方版本更新公告）

Kubernetes 版本迭代较快，部署前请访问 Kubernetes Releases 查看最新稳定版本和版本兼容性矩阵。

Kubernetes 架构概述

Control Plane 组件

组件	功能	生产要求
kube-apiserver	集群 API 入口，认证授权	3+ 副本，负载均衡
etcd	分布式键值存储，保存集群状态	3+ 节点，定期备份
kube-scheduler	Pod 调度决策	多副本，Leader选举
kube-controller-manager	控制器管理（Deployment、Node等）	多副本，Leader选举
cloud-controller-manager	云平台集成控制器	可选，云环境必需

Worker Node 组件

组件	功能	配置要点
kubelet	节点代理，与 API Server 通信	配置资源预留
kube-proxy	服务代理，实现 Service	iptables/IPVS 模式
Container Runtime	容器运行时（containerd/Docker）	systemd cgroup 驱动

网络模型

Kubernetes 网络需满足四个要求：

所有 Pod 不使用 NAT 即可相互通信
所有 Node 不使用 NAT 即可与所有 Pod 通信
Pod 看到的自身 IP 与其他 Pod 看到的 IP 相同
Service 的 ClusterIP 可在集群内访问

部署架构

单控制平面架构（测试环境）

┌─────────────────────────────────────────┐
│  Control Plane (192.168.199.135)        │
│  ├─ kube-apiserver (6443)               │
│  ├─ etcd (2379-2380)                    │
│  ├─ kube-scheduler                      │
│  ├─ kube-controller-manager             │
│  └─ kubelet                             │
└─────────────────────────────────────────┘
           │
           │ Pod Network (10.244.0.0/16)
           │
┌─────────────────────────────────────────┐
│  Worker Node (192.168.199.136)          │
│  ├─ kubelet                             │
│  ├─ kube-proxy                          │
│  └─ Pods (业务应用)                      │
└─────────────────────────────────────────┘

高可用架构（生产环境）

┌────────────────────────────────────────────────────┐
│         Load Balancer (HAProxy/Nginx)              │
│                 VIP: 192.168.1.100                 │
└────────────────────────────────────────────────────┘
        │                    │                    │
        ▼                    ▼                    ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ Master 1     │  │ Master 2     │  │ Master 3     │
│ API Server   │  │ API Server   │  │ API Server   │
│ etcd         │  │ etcd         │  │ etcd         │
└──────────────┘  └──────────────┘  └──────────────┘
        │                    │                    │
        └────────────────────┴────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        ▼                  ▼                  ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ Worker 1     │  │ Worker 2     │  │ Worker 3     │
└──────────────┘  └──────────────┘  └──────────────┘

高可用要点：

etcd 集群：3 或 5 节点，奇数配置
API Server：多副本 + 负载均衡
控制器：内置 Leader 选举机制
网络：跨节点 Pod 通信，Service 负载均衡

前置要求

硬件资源配置

环境	CPU	内存	存储	说明
测试环境	2核	2GB	20GB	最小配置，仅用于学习
开发环境	4核	4GB	50GB	推荐配置，支持轻量应用
生产环境	8核+	16GB+	100GB+	SSD存储，独立etcd
大规模集群	16核+	32GB+	200GB+	高IO性能，专用磁盘

生产环境补充建议：

Master节点：CPU预留1核，内存预留2GB给系统进程
Worker节点：根据应用负载动态调整
etcd数据：独立SSD磁盘，避免IO竞争
网络带宽：至少1Gbps，生产推荐10Gbps

网络配置要求

必需开放的端口

Control Plane节点：

端口	协议	服务	说明
6443	TCP	API Server	Kubernetes API入口
2379-2380	TCP	etcd	etcd服务端口
10250	TCP	Kubelet	节点状态和日志
10251	TCP	Scheduler	调度器端口
10252	TCP	Controller	控制器端口
10257	TCP	kube-controller-manager	安全端口
10259	TCP	kube-scheduler	安全端口

Worker节点：

端口	协议	服务	说明
10250	TCP	Kubelet	节点通信
10256	TCP	kube-proxy	代理健康检查
30000-32767	TCP	NodePort	服务暴露端口

网络插件端口

网络插件	端口	说明
Flannel	8285/8472	VXLAN通信
Calico	179/4789	BGP/VXLAN
Cilium	4240/8472	健康检查/VXLAN

系统检查清单

执行以下检查确保系统就绪：

# 1. 验证 MAC 地址唯一性
ip link | grep link/ether

# 2. 验证 product_uuid 唯一性
cat /sys/class/dmi/id/product_uuid

# 3. 确认 Swap 已禁用
free | grep Swap

# 4. 验证时间同步
timedatectl status
systemctl status systemd-timesyncd

# 5. 检查内核版本（建议 5.4+）
uname -r

# 6. 检查系统资源
df -h
free -g
lscpu

安装步骤

配置 APT 源（两台 VM）

使用清华 TUNA 镜像加速软件包下载：

nano /etc/apt/sources.list

替换为以下内容：

deb https://mirrors.tuna.tsinghua.edu.cn/debian/ trixie main contrib non-free-firmware
deb-src https://mirrors.tuna.tsinghua.edu.cn/debian/ trixie main contrib non-free-firmware

deb https://mirrors.tuna.tsinghua.edu.cn/debian/ trixie-updates main contrib non-free-firmware
deb-src https://mirrors.tuna.tsinghua.edu.cn/debian/ trixie-updates main contrib non-free-firmware

deb https://mirrors.tuna.tsinghua.edu.cn/debian/ trixie-backports main contrib non-free-firmware
deb-src https://mirrors.tuna.tsinghua.edu.cn/debian/ trixie-backports main contrib non-free-firmware

deb https://mirrors.tuna.tsinghua.edu.cn/debian-security/ trixie-security main contrib non-free-firmware
deb-src https://mirrors.tuna.tsinghua.edu.cn/debian-security/ trixie-security main contrib non-free-firmware

禁用 Swap（两台 VM）

Kubelet 无法在启用 Swap 的系统上运行：

# 立即禁用
sudo swapoff -a

# 永久禁用（编辑 fstab 文件）
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

# 验证（应输出 0）
free | grep Swap | awk '{print $2}'

安装并配置容器运行时（两台 VM）

使用 Containerd 作为容器运行时（Kubernetes 1.24+ 推荐）：

# 1. 加载必需的内核模块
cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

sudo modprobe overlay
sudo modprobe br_netfilter

# 2. 配置内核参数（生产级调优）
cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
# Kubernetes 必需参数
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1

# 性能优化参数
net.core.somaxconn                  = 65535
net.ipv4.tcp_max_syn_backlog        = 8192
net.core.netdev_max_backlog         = 5000
vm.swappiness                       = 10
vm.max_map_count                    = 262144
fs.file-max                         = 655350
EOF

sudo sysctl --system

# 3. 安装 Containerd
sudo apt update
sudo apt install -y containerd

# 4. 创建生产级配置文件
sudo mkdir -p /etc/containerd
sudo containerd config default | sudo tee /etc/containerd/config.toml

# 5. 关键配置优化（生产必需）
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/g' /etc/containerd/config.toml

# 配置镜像加速（国内环境）
sudo sed -i 's|registry.k8s.io/pause:3\.[0-9]\+|registry.aliyuncs.com/google_containers/pause:3.10|g' /etc/containerd/config.toml

# 6. 启动并验证服务
sudo systemctl enable --now containerd
sudo systemctl status containerd
sudo ctr version

# 7. 验证配置
sudo ctr config dump | grep -A5 "plugins"

Containerd 生产级配置详解：

# /etc/containerd/config.toml 关键片段
[plugins."io.containerd.grpc.v1.cri"]
  enable_tls_streaming = false
  
  [plugins."io.containerd.grpc.v1.cri".containerd]
    snapshotter = "overlayfs"
    default_runtime_name = "runc"
    
    [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc]
      runtime_type = "io.containerd.runc.v2"
      
      [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options]
        SystemdCgroup = true  # Kubernetes 必需
        
  [plugins."io.containerd.grpc.v1.cri".registry]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
      [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
        endpoint = ["https://registry.aliyuncs.com"]

安装 Kubeadm、Kubelet、Kubectl（两台 VM）

添加 Kubernetes 官方仓库并安装 v1.33 版本：

# 1. 安装必需的工具
sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg

# 2. 添加 Kubernetes 官方 GPG 密钥
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.33/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

# 3. 添加 Kubernetes v1.33 APT 仓库
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.33/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list

# 4. 刷新缓存
sudo apt-get update

# 5. 安装指定版本
sudo apt-get install -y kubelet=1.33.* kubeadm=1.33.* kubectl=1.33.*

# 6. 防止自动升级
sudo apt-mark hold kubelet kubeadm kubectl

# 7. 验证安装
kubeadm version

初始化 Control Plane（仅 VM 1 - Master 节点）

前置条件： 记录 Master 节点的 IP 地址（本例为 192.168.199.135）

# 初始化集群
sudo kubeadm init \
  --apiserver-advertise-address=192.168.199.135 \
  --pod-network-cidr=10.244.0.0/16 \
  --kubernetes-version v1.33.6 \
  --image-repository registry.aliyuncs.com/google_containers

初始化完成后，终端会输出：

kubectl 配置命令
kubeadm join 命令（必须保存供 Worker 节点使用）

配置 Kubectl（仅 VM 1）

# 为当前用户配置 kubectl
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

# 验证 Control Plane（节点状态应为 NotReady，等待网络插件）
kubectl get nodes

Worker Node 加入集群（仅 VM 2）

在 VM 2 上执行步骤 5 中保存的 kubeadm join 命令：

sudo kubeadm join 192.168.199.135:6443 --token  \
  --discovery-token-ca-cert-hash sha256:

和来自步骤 5 的输出。

部署网络插件 - Flannel（VM 1 或任意有 kubectl 访问的节点）

Kubernetes 需要网络插件实现 Pod 间通信。我们使用 Flannel：

# 部署 Flannel CNI
kubectl apply -f https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml

# 等待 1-2 分钟，然后验证
kubectl get pods -n kube-system | grep flannel

# 验证所有系统 Pod 运行正常
kubectl get pods -n kube-system

预加载 Flannel 镜像（两台 VM - 可选但推荐）

如果网络不稳定或镜像下载缓慢，可提前在两台 VM 上加载 Flannel 镜像：

方案一：直接拉取镜像

# 1. 使用 ctr 直接拉取镜像到 containerd
sudo ctr image pull ghcr.io/flannel-io/flannel:v0.27.4
sudo ctr image pull ghcr.io/flannel-io/flannel-cni-plugin:v1.8.0-flannel1

方案二：本地打包后导入

如果镜像源不可达，可在能访问外网的机器上下载后导入：

# 在能访问外网的机器上执行
# 1. 拉取镜像
docker pull ghcr.io/flannel-io/flannel:v0.27.4
docker pull ghcr.io/flannel-io/flannel-cni-plugin:v1.8.0-flannel1

# 2. 打包成 tar 文件
docker save -o flannel_images.tar \
  ghcr.io/flannel-io/flannel:v0.27.4 \
  ghcr.io/flannel-io/flannel-cni-plugin:v1.8.0-flannel1

# 将 flannel_images.tar 文件复制到两台 VM，然后执行：

# 3. 在每台 VM 上导入镜像
# 导入到 k8s.io 命名空间
sudo ctr --namespace k8s.io image import flannel_images.tar

# 4. 验证镜像
sudo ctr images list | grep flannel
sudo ctr --namespace k8s.io images list | grep flannel

修复 CNI 插件路径（两台 VM）

如果 CoreDNS Pod 仍无法启动，执行以下修复：

# 1. 创建 CNI 标准目录
sudo mkdir -p /usr/lib/cni

# 2. 创建 Flannel 插件的符号链接
cd /usr/lib/cni/
for plugin in /opt/cni/bin/*; do
  sudo ln -sf "$plugin" "$(basename $plugin)"
done

# 3. 验证符号链接
ls -lh /usr/lib/cni/

# 4. 重启 Kubelet
sudo systemctl restart kubelet

# 5. 验证 Pod 状态
kubectl get pods -n kube-system

集群验证

最终验证（VM 1）

# 1. 检查所有节点状态（应全为 Ready）
kubectl get nodes

# 2. 检查所有系统 Pod（应全为 Running）
kubectl get pods -n kube-system

# 3. 查看集群信息
kubectl cluster-info

# 4. 运行测试 Pod
kubectl run test-pod --image=nginx --port=80
kubectl get pods
kubectl delete pod test-pod

常见验证命令

# 查看节点详细信息
kubectl describe node 

# 查看集群资源
kubectl top nodes

# 查看系统事件
kubectl get events -n kube-system

# 检查 API 服务器状态
kubectl get cs  # 已弃用，但可用于诊断

故障排除

故障诊断流程图

┌─────────────────────────────────────────────────────────────┐
│                 Kubernetes 集群故障诊断流程                   │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
        ┌──────────────────────────────────┐
        │  1. 检查节点状态                  │
        │     kubectl get nodes            │
        └──────────────────────────────────┘
                           │
                  ┌────────┴────────┐
                  │                 │
              Ready             NotReady
                  │                 │
                  ▼                 ▼
        ┌──────────────┐   ┌──────────────────┐
        │ 2. 检查Pod   │   │ 检查 kubelet     │
        │    状态      │   │ 日志和网络插件   │
        └──────────────┘   └──────────────────┘
                  │                 │
                  ▼                 ▼
        ┌──────────────────┐ ┌──────────────────┐
        │ 3. 检查系统组件   │ │ 重启 kubelet     │
        │    Pod 状态      │ │ 修复 CNI 配置    │
        └──────────────────┘ └──────────────────┘
                  │
         ┌────────┴─────────┐
         │                  │
       Running            Pending/CrashLoopBackOff
         │                  │
         ▼                  ▼
  ┌────────────┐    ┌──────────────────┐
  │ 集群正常    │    │ 检查 Pod 日志    │
  └────────────┐    │ 修复镜像/配置    │
                  └──────────────────┘

诊断命令链

# ===== 第一阶段：节点状态检查 =====

# 1. 查看所有节点状态
kubectl get nodes -o wide

# 2. 查看节点详细信息
kubectl describe node 

# 3. 检查节点资源使用
kubectl top nodes

# 4. 检查 kubelet 状态（在节点上执行）
sudo systemctl status kubelet
sudo journalctl -u kubelet -n 100 --no-pager

# ===== 第二阶段：系统 Pod 检查 =====

# 5. 查看所有系统 Pod
kubectl get pods -n kube-system -o wide

# 6. 查看特定 Pod 详情
kubectl describe pod  -n kube-system

# 7. 查看 Pod 日志
kubectl logs  -n kube-system
kubectl logs  -n kube-system --previous  # 查看上一个容器的日志

# 8. 检查组件状态
kubectl get componentstatuses

# ===== 第三阶段：网络检查 =====

# 9. 检查网络插件状态
kubectl get pods -n kube-system | grep -E "flannel|calico|cilium"

# 10. 检查 CNI 配置（在节点上执行）
ls -la /etc/cni/net.d/
cat /etc/cni/net.d/*.conf

# 11. 检查 Flannel 配置
kubectl logs -n kube-system 

# 12. 测试 Pod 间通信
kubectl run test-pod --image=busybox --restart=Never --rm -it -- ping

问题：节点处于 NotReady 状态

原因分析：

网络插件未部署或未就绪
kubelet 服务异常
CNI 配置错误
容器运行时异常

解决方案：

# 1. 检查 Flannel Pod 状态
kubectl get pods -n kube-system | grep flannel

# 2. 查看 Flannel Pod 日志
kubectl logs -n kube-system 
kubectl describe pod -n kube-system 

# 3. 检查 kubelet 日志（在 NotReady 节点上执行）
sudo journalctl -u kubelet -f

# 4. 检查 containerd 状态
sudo systemctl status containerd
sudo journalctl -u containerd -n 50

# 5. 重启 kubelet（在节点上执行）
sudo systemctl restart kubelet

# 6. 检查 CNI 插件路径
ls -la /opt/cni/bin/
ls -la /etc/cni/net.d/

# 7. 如果 CNI 插件缺失，重新部署
kubectl apply -f https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml

验证修复：

# 等待 1-2 分钟后检查
kubectl get nodes
# 应显示 Ready 状态

问题：CoreDNS Pod 处于 Pending 状态

原因分析：

CNI 插件路径配置不正确
网络插件未就绪
节点资源不足

解决方案： 执行步骤 9 的修复步骤

# 1. 创建 CNI 标准目录（在所有节点执行）
sudo mkdir -p /usr/lib/cni

# 2. 创建符号链接
cd /usr/lib/cni/
for plugin in /opt/cni/bin/*; do
  sudo ln -sf "$plugin" "$(basename $plugin)"
done

# 3. 验证符号链接
ls -lh /usr/lib/cni/

# 4. 重启 Kubelet（在所有节点执行）
sudo systemctl restart kubelet

# 5. 检查 CoreDNS Pod 状态
kubectl get pods -n kube-system | grep coredns

# 6. 如果仍处于 Pending，检查调度限制
kubectl describe pod -n kube-system

问题：kubeadm join 失败

原因分析：

Token 过期（默认 24 小时有效）
CA 证书哈希不匹配
Master 节点 API Server 不可达
端口 6443 被防火墙阻止

解决方案：

# 1. 在 Master 节点生成新 Token
kubeadm token create --print-join-command

# 2. 检查 Token 列表
kubeadm token list

# 3. 获取 CA 证书哈希（如果 Token 有效但哈希错误）
openssl x509 -pubkey -in /etc/kubernetes/pki/ca.crt | openssl rsa -pubin -outform der 2>/dev/null | openssl dgst -sha256 -hex | sed 's/^.* //'

# 4. 手动构建 join 命令
kubeadm join :6443 --token  --discovery-token-ca-cert-hash sha256:<hash>

# 5. 检查网络连通性（在 Worker 节点执行）
ping 
curl -k https://:6443/version

# 6. 检查防火墙规则（在 Master 节点执行）
sudo ufw status | grep 6443
sudo iptables -L -n | grep 6443

问题：Pod 无法启动（镜像拉取失败）

原因分析：

镜像仓库不可达
镜像不存在或版本错误
需要认证但未配置 Secret
网络策略阻止下载

解决方案：

# 1. 检查镜像拉取错误
kubectl describe pod  -n 
# 查看 Events 部分的错误信息

# 2. 手动拉取镜像测试（在节点上执行）
sudo ctr image pull 
# 或
docker pull 

# 3. 配置镜像加速（containerd）
# 编辑 /etc/containerd/config.toml
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
endpoint = ["https://registry.aliyuncs.com"]

# 4. 重启 containerd
sudo systemctl restart containerd

# 5. 配置私有仓库认证
kubectl create secret docker-registry regcred \
  --docker-server= \
  --docker-username= \
  --docker-password=

# 6. 在 Pod 或 Deployment 中引用 Secret
spec:
  imagePullSecrets:
  - name: regcred

获取调试日志

# 查看 Kubelet 日志
sudo journalctl -u kubelet -f

# 查看 containerd 日志
sudo journalctl -u containerd -f

# 查看 kube-apiserver 日志
kubectl logs -n kube-system kube-apiserver-

# 查看 kube-scheduler 日志
kubectl logs -n kube-system kube-scheduler-

# 查看 kube-controller-manager 日志
kubectl logs -n kube-system kube-controller-manager-

# 查看 etcd 日志
kubectl logs -n kube-system etcd-

# 查看所有容器日志（在节点上执行）
sudo crictl logs 

# 查看 Pod 事件
kubectl get events -n kube-system --sort-by='.lastTimestamp'

常用命令参考

# 集群管理
kubectl get nodes                          # 列出所有节点
kubectl get pods -A                        # 列出所有 Pod
kubectl get svc -A                         # 列出所有服务
kubectl get events -n kube-system         # 查看系统事件

# 节点管理
kubectl cordon                 # 禁止 Pod 调度到该节点
kubectl uncordon               # 允许 Pod 调度到该节点
kubectl drain                  # 驱逐节点上的所有 Pod

# 日志查看
kubectl logs -n kube-system    # 查看 Pod 日志
kubectl describe pod            # 查看 Pod 详细信息

# 集群信息
kubectl cluster-info                      # 查看集群信息
kubectl api-resources                     # 查看所有 API 资源

参考资源

官方文档

Kubernetes 官方文档
kubeadm 官方指南
kubeadm 配置参考
Kubernetes 版本支持政策
Kubernetes 发行说明
Flannel 官方文档
Containerd 官方文档
Containerd 配置指南

安全与加固

CIS Kubernetes Benchmark - Kubernetes 安全配置基准
Kubernetes 安全最佳实践
Pod Security Standards
Kubernetes 安全审计
RBAC 配置指南

网络与 CNI

Kubernetes 网络模型
CNI 插件规范
Flannel 网络配置
Calico 网络策略
Cilium 网络方案

高可用与运维

Kubernetes 高可用拓扑
etcd 运维指南
Kubernetes 备份与恢复
Kubernetes 监控架构
kubelet 配置参考

社区与工具

Kubernetes GitHub 仓库
kubeadm GitHub
Kubernetes Enhancement Proposals (KEP)
Kubernetes Slack 社区
Kubernetes Issue 跟踪

进阶阅读

《Kubernetes 权威指南》
云原生计算基金会 (CNCF)
Kubernetes 安全白皮书
生产级 Kubernetes 部署检查清单

生产环境优化配置

Kubelet 资源预留

编辑 /var/lib/kubelet/config.yaml（或通过 kubeadm 配置）：

apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
systemReserved:
  cpu: "500m"
  memory: "1Gi"
  ephemeral-storage: "10Gi"
kubeReserved:
  cpu: "500m"
  memory: "1Gi"
  ephemeral-storage: "10Gi"
evictionHard:
  memory.available: "500Mi"
  nodefs.available: "10%"
  nodefs.inodesFree: "5%"
  imagefs.available: "10%"
maxPods: 110
imageGCHighThresholdPercent: 85
imageGCLowThresholdPercent: 80

应用配置：

sudo systemctl restart kubelet
kubectl describe node | grep -A5 "Allocated resources"

API Server 性能调优

高并发场景配置（添加到 kubeadm init 参数）：

sudo kubeadm init \
  --apiserver-advertise-address=192.168.199.135 \
  --pod-network-cidr=10.244.0.0/16 \
  --kubernetes-version v1.33.6 \
  --image-repository registry.aliyuncs.com/google_containers \
  --apiserver-extra-args=--max-requests-inflight=800 \
  --apiserver-extra-args=--max-mutating-requests-inflight=400 \
  --apiserver-extra-args=--default-not-ready-toleration-seconds=300 \
  --apiserver-extra-args=--default-unreachable-toleration-seconds=300

etcd 性能优化

编辑 /etc/kubernetes/manifests/etcd.yaml：

spec:
  containers:
  - command:
    - etcd
    - --snapshot-count=10000  # 提高快照频率
    - --heartbeat-interval=200  # 心跳间隔（毫秒）
    - --election-timeout=2000  # 选举超时（毫秒）
    - --quota-backend-bytes=8589934592  # 8GB 存储限制
    - --auto-compaction-retention=1h  # 自动压缩

安全加固配置

RBAC 最小权限原则

创建命名空间管理员角色：

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: production
  name: namespace-admin
rules:
- apiGroups: ["", "apps", "extensions"]
  resources: ["*"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  namespace: production
  name: namespace-admin-binding
subjects:
- kind: User
  name: dev-user
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: namespace-admin
  apiGroup: rbac.authorization.k8s.io

Pod 安全策略（PSP）

使用 Pod Security Standards：

apiVersion: v1
kind: Namespace
metadata:
  name: production
  labels:
    pod-security.kubernetes.io/enforce: restricted
    pod-security.kubernetes.io/enforce-version: latest
    pod-security.kubernetes.io/audit: restricted
    pod-security.kubernetes.io/audit-version: latest
    pod-security.kubernetes.io/warn: restricted
    pod-security.kubernetes.io/warn-version: latest

网络策略（Network Policy）

限制命名空间间通信：

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny
  namespace: production
spec:
  podSelector: {}
  policyTypes:
  - Ingress
  - Egress
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-same-namespace
  namespace: production
spec:
  podSelector: {}
  ingress:
  - from:
    - podSelector: {}
  egress:
  - to:
    - podSelector: {}

集群证书轮换

证书有效期检查与更新：

# 检查证书有效期
kubeadm certs check-expiration

# 更新证书（自动续期1年）
kubeadm certs renew all

# 重启控制平面组件
sudo kill -s SIGHUP $(pidof kube-apiserver)
sudo kill -s SIGHUP $(pidof kube-controller-manager)
sudo kill -s SIGHUP $(pidof kube-scheduler)

# 更新客户端证书
cp /etc/kubernetes/admin.conf ~/.kube/config

监控与运维

集群健康检查脚本

cat << 'EOF' > k8s-health-check.sh
#!/bin/bash
echo "=== Kubernetes Cluster Health Check ==="
echo ""

echo "1. Node Status:"
kubectl get nodes -o wide
echo ""

echo "2. System Pods Status:"
kubectl get pods -n kube-system
echo ""

echo "3. Resource Usage:"
kubectl top nodes
kubectl top pods -A --sort-by=memory | head -n 10
echo ""

echo "4. Certificate Expiration:"
kubeadm certs check-expiration
echo ""

echo "5. Component Health:"
kubectl get componentstatuses
echo ""

echo "6. Recent Events:"
kubectl get events -A --sort-by='.lastTimestamp' | tail -n 20
echo ""

echo "7. Cluster Info:"
kubectl cluster-info
EOF
chmod +x k8s-health-check.sh
./k8s-health-check.sh

etcd 备份与恢复

备份脚本：

cat << 'EOF' > etcd-backup.sh
#!/bin/bash
BACKUP_DIR="/backup/etcd"
DATE=$(date +%Y%m%d-%H%M%S)

ETCDCTL_API=3 etcdctl snapshot save ${BACKUP_DIR}/etcd-snapshot-${DATE}.db \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/server.crt \
  --key=/etc/kubernetes/pki/etcd/server.key

# 保留最近7天的备份
find ${BACKUP_DIR} -name "*.db" -mtime +7 -delete
EOF
chmod +x etcd-backup.sh

恢复流程：

# 1. 停止所有控制平面组件
sudo systemctl stop kubelet
sudo crictl stopp $(sudo crictl pods -q)
sudo crictl rmp $(sudo crictl pods -q)

# 2. 恢复 etcd 数据
ETCDCTL_API=3 etcdctl snapshot restore /backup/etcd/etcd-snapshot.db \
  --data-dir=/var/lib/etcd-restore

# 3. 更新 etcd manifest
sudo mv /var/lib/etcd /var/lib/etcd-old
sudo mv /var/lib/etcd-restore/member /var/lib/etcd
sudo systemctl start kubelet

日志收集配置

配置 Fluent Bit：

apiVersion: v1
kind: ConfigMap
metadata:
  name: fluent-bit-config
  namespace: kube-system
data:
  fluent-bit.conf: |
    [SERVICE]
      Flush         1
      Log_Level     info
      Parsers_File  parsers.conf
    
    [INPUT]
      Name              tail
      Path              /var/log/containers/*.log
      Parser            cri
      Tag               kube.*
      Mem_Buf_Limit     10MB
    
    [FILTER]
      Name                kubernetes
      Match               kube.*
      Kube_URL            https://kubernetes.default.svc:443
      Kube_CA_File        /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
      Kube_Token_File     /var/run/secrets/kubernetes.io/serviceaccount/token
    
    [OUTPUT]
      Name            forward
      Match           *
      Host            fluentd-server
      Port            24224

最佳实践建议

镜像管理

使用私有仓库（Harbor、Nexus）
镜像扫描（Trivy、Clair）
版本锁定（避免使用 latest）
预加载关键镜像到节点

资源管理

设置合理的 requests/limits
使用 LimitRange 和 ResourceQuota
配置 Horizontal Pod Autoscaler (HPA)
启用 Vertical Pod Autoscaler (VPA)

网络配置

选择合适的 CNI 插件
配置网络策略隔离
使用 Service Mesh（Istio）进行流量管理
监控网络性能指标

存储管理

使用动态存储 provisioning
配置 StorageClass 多级别存储
定期备份 PVC 数据
监控存储使用情况

高可用配置

多 Master 节点（至少3个）
etcd 集群独立部署（大规模场景）
配置 Pod 反亲和性
使用 PodDisruptionBudget (PDB)

LVM 统一存储架构与数据迁移完整实践指南

2025-09-16T02:10:00.000Z

LVM（Logical Volume Manager）是企业级Linux存储管理的核心解决方案，提供灵活的存储池管理和动态扩展能力。本指南涵盖从传统分区到LVM的完整迁移实践、架构设计、性能优化和数据安全保障，适用于生产环境存储重构和容量规划。

LVM 存储架构设计

LVM 三层架构模型

应用层           文件系统 (ext4/xfs/btrfs)
                 ↓ 挂载点
逻辑层   ←       逻辑卷 (Logical Volume)
                 └─ 可动态调整大小
                 └─ 支持快照功能
                 └─ 提供条带化/镜像
组管理层 ←       卷组 (Volume Group)
                 └─ 存储池聚合管理
                 └─ PE分配单位
                 └─ 空间动态分配
物理层   ←       物理卷 (Physical Volume)
                 └─ 物理设备初始化
                 └─ LVM标签写入
                 └─ 元数据区域
硬件层           物理磁盘 (HDD/SSD/NVMe)
                 └─ 本地存储设备
                 └─ SAN存储设备

核心概念解析

概念	说明	生产应用
PV (Physical Volume)	物理卷，LVM的基础构建块	多磁盘整合
VG (Volume Group)	卷组，存储池聚合	统一管理
LV (Logical Volume)	逻辑卷，虚拟分区	动态扩展
PE (Physical Extent)	物理块，最小分配单位	默认4MB
LE (Logical Extent)	逻辑块，映射到PE	空间映射

LVM 生产优势

优势	传统分区	LVM方案	生产价值
动态扩展	不支持	完全支持	在线扩容
存储池化	独立分区	统一池化	资源优化
快照功能	无	完整支持	数据保护
条带化	不支持	IO性能提升	高性能
镜像	不支持	RAID1镜像	高可用

项目背景与需求分析

原始环境状况

我们的服务器配置如下：

系统盘：SDA 446.6GB（根分区、EFI分区）
数据盘1：NVMe0n1 3.5TB（已分区，挂载到 /data）
数据盘2：NVMe1n1 3.5TB（未使用）

NAME               MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
sda                  8:0    0 446.6G  0 disk
├─sda1               8:1    0     1G  0 part /boot/efi
├─sda2               8:2    0 445.6G  0 part /
└─sda3               8:3    0    65M  0 part
nvme0n1            259:0    0   3.5T  0 disk
└─nvme0n1p1        259:3    0 931.3G  0 part /data
nvme1n1            259:1    0   3.5T  0 disk

面临的问题

存储分散：数据分散在 /data 和 /home 等多个挂载点
扩展困难：传统分区无法动态调整大小
资源浪费：NVMe1n1 完全未使用
管理复杂：多个独立分区增加了管理复杂度

目标架构设计

设计一个统一的LVM存储架构：

将两块NVMe盘整合为单一卷组（Volume Group）
创建大容量逻辑卷，提供约7TB可用空间
通过软链接保持应用程序路径兼容性
实现存储的统一管理和动态扩展能力

LVM技术原理深度解析

LVM架构层次

LVM采用三层架构设计，从底层到上层分别是：

应用层          文件系统 (ext4/xfs)
逻辑层    ←     逻辑卷 (Logical Volume)
组管理层  ←     卷组 (Volume Group)  
物理层    ←     物理卷 (Physical Volume)
硬件层          物理磁盘 (/dev/nvme0n1, /dev/nvme1n1)

Physical Volume (PV)

物理卷是LVM的基础构建块，将物理存储设备（硬盘、分区）转换为LVM可管理的格式：

# PV创建过程中的关键操作
pvcreate /dev/nvme1n1
# 在磁盘开头写入LVM标签和元数据
# 划分PE (Physical Extent) 单位，默认4MB

Volume Group (VG)

卷组将多个物理卷聚合为统一的存储池：

vgcreate data_vg /dev/nvme1n1
# 创建卷组元数据
# 建立PE到VG的映射关系
# 提供统一的存储地址空间

Logical Volume (LV)

逻辑卷是用户实际使用的存储单元，具有以下特性：

动态扩展：可在线扩展容量
快照支持：支持一致性备份
条带化：支持多磁盘并行I/O

LVM vs 传统分区对比

特性	传统分区	LVM
大小调整	困难，通常需要重建	在线动态调整
跨磁盘	不支持	支持跨多个物理磁盘
快照	不支持	支持CoW快照
性能	单磁盘性能	支持条带化提升性能
管理复杂度	简单	中等，但功能强大

实施方案详细步骤

阶段一：LVM基础设施构建

1.1 创建物理卷

首先将NVMe1n1磁盘转换为LVM物理卷：

# 创建物理卷，写入LVM元数据
pvcreate /dev/nvme1n1

# 验证PV创建结果
pvdisplay /dev/nvme1n1

物理卷创建过程中，LVM会在磁盘开头写入以下信息：

LVM标签（LVM2_member）
物理卷UUID
卷组名称
PE大小和数量

1.2 创建卷组

# 创建卷组，将PV加入存储池
vgcreate data_vg /dev/nvme1n1

# 查看卷组信息
vgdisplay data_vg

卷组创建后的关键参数：

PE Size: 4.00 MiB（默认）
Total PE: 约915,707个PE
Allocatable: 是否可分配空间

1.3 创建逻辑卷

# 创建逻辑卷，使用所有可用空间
lvcreate -l 100%FREE -n data1_lv data_vg

# 验证逻辑卷状态
lvdisplay /dev/data_vg/data1_lv

关键参数说明：

-l 100%FREE: 使用所有可用的逻辑分区单元
-n data1_lv: 指定逻辑卷名称
data_vg: 目标卷组名称

1.4 文件系统创建

# 创建ext4文件系统
mkfs.ext4 /dev/data_vg/data1_lv

# 优化参数（可选）
mkfs.ext4 -b 4096 -E stride=32,stripe-width=64 /dev/data_vg/data1_lv

阶段二：数据迁移策略与实施

2.1 迁移准备工作

# 创建挂载点
mkdir /data1
mount /dev/data_vg/data1_lv /data1

# 创建目标目录结构
mkdir /data1/data_backup
mkdir /data1/home_backup

2.2 数据完整性迁移

使用rsync进行增量同步，保证数据一致性：

# 迁移/data数据，保持所有属性
nohup rsync -avxHAX --progress \
    --exclude='lost+found' \
    /data/ /data1/data_backup/ \
    > /data1/data_backup.log 2>&1 &

# 迁移/home数据（确保没有用户登陆，已登陆用户请踢出）
nohup rsync -avxHAX --progress \
    --exclude='lost+found' \
    /home/ /data1/home_backup/ \
    > /data1/home_backup.log 2>&1 &

rsync参数详解：

-a: 归档模式，保持权限、时间戳等
-v: 详细输出
-x: 不跨文件系统
-H: 保持硬链接
-A: 保持ACL
-X: 保持扩展属性
--progress: 显示进度

2.3 数据完整性验证

# 比较文件数量
find /data -type f | wc -l
find /data1/data_backup -type f | wc -l

# 比较总大小
du -sh /data
du -sh /data1/data_backup

# 使用校验和验证（可选，耗时较长）
find /data -type f -exec md5sum {} \; | sort > /tmp/original.md5
cd /data1/data_backup
find . -type f -exec md5sum {} \; | sort > /tmp/backup.md5
diff /tmp/original.md5 /tmp/backup.md5

阶段三：系统切换与进程处理

3.1 进程排查与处理

在卸载原分区前，必须确保没有进程占用：

# 查找占用/data的进程
lsof +D /data

# 示例输出分析
COMMAND       PID USER   FD   TYPE DEVICE   SIZE/OFF     NODE NAME
sftp-serv 1528862 root    3r   REG  259,3 8776906927 11273975 /data/opt/...

发现SFTP进程正在传输大文件，这解释了为什么”静态文件”会有进程占用。

3.2 优雅停止服务

# 停止相关服务
systemctl stop docker

# 强制终止占用进程（谨慎使用）
fuser -km /data

# 或者单独终止特定进程
kill -15 1528862  # 温和终止
kill -9 1528862   # 强制终止

3.3 安全卸载与切换

# 备份fstab
cp /etc/fstab /etc/fstab.backup

# 卸载原分区
umount /data
# 如果busy，使用懒卸载
umount -l /data

# 重命名原目录（保留备份）
mv /data /data.old
mv /home /home.old

# 创建软链接
ln -s /data1/data_backup /data
ln -s /data1/home_backup /home

阶段四：存储池扩展

4.1 第二块磁盘处理

NVMe0n1已有分区表，需要清理：

# 清除分区表和文件系统签名
wipefs -a /dev/nvme0n1

# 输出示例
/dev/nvme0n1: 8 bytes were erased at offset 0x00000200 (gpt): 45 46 49 20 50 41 52 54
/dev/nvme0n1: 8 bytes were erased at offset 0x37e3ee55e00 (gpt): 45 46 49 20 50 41 52 54
/dev/nvme0n1: 2 bytes were erased at offset 0x000001fe (PMBR): 55 aa

4.2 扩展LVM存储池

# 将新磁盘加入物理卷
pvcreate /dev/nvme0n1

# 扩展卷组
vgextend data_vg /dev/nvme0n1

# 扩展逻辑卷
lvextend -l +100%FREE /dev/data_vg/data1_lv

# 扩展文件系统
resize2fs /dev/data_vg/data1_lv

4.3 验证扩展结果

# 查看存储状态
pvdisplay
vgdisplay data_vg
lvdisplay /dev/data_vg/data1_lv
df -Th

阶段五：系统配置与验证

5.1 更新系统配置

# 更新fstab，添加新挂载项
echo "/dev/data_vg/data1_lv /data1 ext4 defaults 0 2" >> /etc/fstab

# 验证fstab语法
mount -a

Harbor 多架构镜像管理完整指南

2025-08-13T02:40:00.000Z

在现代容器化环境中，多架构支持变得越来越重要。随着 ARM64 架构在服务器和边缘设备中的普及，我们需要构建和管理支持多种 CPU 架构的容器镜像。本文将详细介绍如何在 Harbor 私有镜像仓库中管理多架构镜像，包括配置、推送和创建 manifest 列表的完整流程。

环境说明

Harbor 版本: 自建 Harbor 私有仓库
部署方式: HTTPS 模式，使用自签名证书，443 端口
Docker 版本: 支持 manifest 功能的版本
目标架构: AMD64 和 ARM64

问题背景

在实际项目中，我们遇到了以下挑战：

需要将单架构镜像转换为多架构镜像
Harbor 使用自签名 HTTPS 证书，需要正确配置 Docker 客户端
Docker manifest 功能需要特定的配置和操作流程
需要批量处理多个版本的镜像

解决方案

1. Harbor 证书配置

问题现象

Get "http://110.1.20.3/v2/": dial tcp 110.1.20.3:80: connect: connection refused

这个错误表明 Docker 客户端尝试使用 HTTP 协议连接 Harbor，但 Harbor 实际运行在 HTTPS 模式。

解决步骤

Step 1: 配置客户端证书

# 创建证书目录
mkdir -p /etc/docker/certs.d/110.1.20.3/

# 复制 Harbor CA 证书和服务器证书
\cp -rvf /data/opt/installharbor/certs/{ca.crt,harbor.crt} /etc/docker/certs.d/110.1.20.3/

# 设置正确的文件权限
cd /etc/docker/certs.d/110.1.20.3/
chmod 644 ca.crt harbor.crt

Step 2: 配置 Docker daemon

编辑 /etc/docker/daemon.json：

{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "http://docker.1panel.live",
    "https://docker.agsv.top",
    "https://docker.agsvpt.work",
    "https://dockerpull.com",
    "https://dockerproxy.cn"
  ],
  "debug": false,
  "insecure-registries": [
    "110.1.20.3"
  ],
  "ip-forward": true,
  "ipv6": false,
  "live-restore": true,
  "log-driver": "json-file",
  "log-level": "warn",
  "log-opts": {
    "max-size": "100m",
    "max-file": "2"
  },
  "selinux-enabled": false,
  "experimental": true,
  "storage-driver": "overlay2",
  "data-root": "/data/docker_dir",
  "default-ulimits": {
    "nofile": {
      "Name": "nofile",
      "Hard": 65536,
      "Soft": 65536
    }
  },
  "exec-opts": ["native.cgroupdriver=systemd"]
}

关键配置说明：

"experimental": true - 启用 manifest 功能
"insecure-registries": ["110.1.20.3"] - 信任自签名证书

Step 3: 重启服务

# 重启 Docker
systemctl daemon-reload 
systemctl restart docker

# 重启 Harbor（同台机器部署需要）
cd /data/opt/installharbor/
bash install.sh

2. 常见证书问题解决

问题1：证书文件扩展名错误

missing key ca.key for client certificate ca.cert. CA certificates must use the extension .crt

解决方法：

Docker 要求 CA 证书必须使用 .crt 扩展名
客户端证书目录不应包含私钥文件（.key 文件）

正确的证书目录结构：

/etc/docker/certs.d/110.1.20.3/
├── ca.crt          # CA 证书（必需）
└── harbor.crt      # Harbor 服务器证书（可选）

问题2：Docker daemon 配置错误

json: cannot unmarshal string into Go struct field Config.experimental of type bool

解决方法：

// 错误写法
"experimental": "enabled"

// 正确写法
"experimental": true

3. 多架构镜像管理脚本

创建自动化脚本 pushImages.sh 来批量处理镜像：

#!/bin/bash
# ===================================
# 批量处理：打 tag + 推送 + 创建多架构 manifest
# 支持 HTTPS Harbor 自签名证书
# ===================================
set -e

# Harbor 配置
HARBOR_HOST="110.1.20.3"
REPO_PREFIX="${HARBOR_HOST}/library"
VERSIONS=("3.11.3" "3.10.1" "3.9.2" "3.8.5")
ARCHES=("amd64" "arm64")

# 是否删除旧标签（可选）
DELETE_OLD_TAGS=false

echo "🚀 开始处理镜像标签与多架构清单..."
echo "📡 Harbor 地址: https://${HARBOR_HOST}"

# 检查登录状态
if ! docker login https://${HARBOR_HOST} 2>/dev/null; then
  echo "⚠️  Docker 未登录到 Harbor，请先登录："
  echo "   docker login https://${HARBOR_HOST}"
  exit 1
fi

# 1. 先为所有镜像打新标签并推送
for version in "${VERSIONS[@]}"; do
  for arch in "${ARCHES[@]}"; do
    OLD_TAG="${REPO_PREFIX}/java-gdal-local-${arch}:${version}"
    NEW_TAG="${REPO_PREFIX}/java-gdal-local:${version}-${arch}"
    
    if docker inspect "$OLD_TAG" &> /dev/null; then
      echo "🏷️  打标签: $OLD_TAG -> $NEW_TAG"
      docker tag "$OLD_TAG" "$NEW_TAG"
      
      echo "📤 推送: $NEW_TAG"
      docker push "$NEW_TAG"
      
      if [ "$DELETE_OLD_TAGS" = true ]; then
        echo "🗑️  删除旧标签: $OLD_TAG"
        docker rmi "$OLD_TAG" || true
      fi
    else
      echo "⚠️  镜像不存在，跳过: $OLD_TAG"
    fi
  done
done

# 2. 为每个版本创建多架构 manifest
echo ""
echo "🔧 开始创建多架构 manifest..."

for version in "${VERSIONS[@]}"; do
  MANIFEST_TAG="${REPO_PREFIX}/java-gdal-local:${version}"
  TAG_AMD64="${REPO_PREFIX}/java-gdal-local:${version}-amd64"
  TAG_ARM64="${REPO_PREFIX}/java-gdal-local:${version}-arm64"
  
  echo "📦 创建多架构镜像清单: $MANIFEST_TAG"
  
  # 删除可能存在的旧 manifest
  docker manifest rm "$MANIFEST_TAG" 2>/dev/null || true
  
  # 创建 manifest
  docker manifest create "$MANIFEST_TAG" \
    --amend "$TAG_AMD64" \
    --amend "$TAG_ARM64"
  
  # 添加平台信息（关键步骤）
  docker manifest annotate "$MANIFEST_TAG" "$TAG_AMD64" --os linux --arch amd64
  docker manifest annotate "$MANIFEST_TAG" "$TAG_ARM64" --os linux --arch arm64
  
  # 推送 manifest
  echo "📤 推送多架构镜像: $MANIFEST_TAG"
  docker manifest push "$MANIFEST_TAG"
  
  echo "✅ 完成: $MANIFEST_TAG"
done

echo ""
echo "🎉 所有操作完成！"
echo ""
echo "你现在可以通过以下方式拉取："
for version in "${VERSIONS[@]}"; do
  echo "   docker pull ${HARBOR_HOST}/library/java-gdal-local:${version}"
done

4. 手动操作流程

如果需要手动创建多架构镜像，可以按以下步骤：

Step 1: 登录 Harbor

docker login 110.1.20.3
# 或者
docker login -u admin -p Harbor12345@Gmail.com 110.1.20.3

Step 2: 推送单架构镜像

# 为现有镜像打新标签
docker tag 110.1.20.3/library/java-gdal-local-amd64:3.8.5 \
           110.1.20.3/library/java-gdal-local:3.8.5-amd64

docker tag 110.1.20.3/library/java-gdal-local-arm64:3.8.5 \
           110.1.20.3/library/java-gdal-local:3.8.5-arm64

# 推送镜像
docker push 110.1.20.3/library/java-gdal-local:3.8.5-amd64
docker push 110.1.20.3/library/java-gdal-local:3.8.5-arm64

Step 3: 创建多架构 manifest

# 创建 manifest
docker manifest create 110.1.20.3/library/java-gdal-local:3.8.5 \
  --amend 110.1.20.3/library/java-gdal-local:3.8.5-amd64 \
  --amend 110.1.20.3/library/java-gdal-local:3.8.5-arm64

# 添加平台信息（重要！）
docker manifest annotate 110.1.20.3/library/java-gdal-local:3.8.5 \
  110.1.20.3/library/java-gdal-local:3.8.5-amd64 --os linux --arch amd64

docker manifest annotate 110.1.20.3/library/java-gdal-local:3.8.5 \
  110.1.20.3/library/java-gdal-local:3.8.5-arm64 --os linux --arch arm64

# 推送 manifest（注意：使用 manifest push，不是普通 push）
docker manifest push 110.1.20.3/library/java-gdal-local:3.8.5

Step 4: 验证结果

# 查看 manifest 信息
docker manifest inspect 110.1.20.3/library/java-gdal-local:3.8.5

# 测试拉取（会根据当前平台自动选择架构）
docker pull 110.1.20.3/library/java-gdal-local:3.8.5

5. 故障排除

常见错误及解决方法

1. 证书相关错误

x509: certificate signed by unknown authority

解决： 确保正确配置了 CA 证书或使用 insecure-registries

2. Manifest 推送错误

tag does not exist: 110.1.20.3/library/java-gdal-local:3.8.5

解决： 使用 docker manifest push 而不是 docker push

3. 实验性功能未启用

docker manifest is only supported when experimental cli features are enabled

解决： 在 daemon.json 中设置 "experimental": true

检查清单

Docker daemon 配置了 "experimental": true
证书文件使用正确的扩展名（.crt）
证书目录不包含私钥文件
已正确登录 Harbor
单架构镜像已成功推送
使用 docker manifest push 推送 manifest

完整配置脚本

将所有配置步骤整合成一个脚本：

#!/bin/bash
# Harbor 多架构镜像配置脚本

echo "🔧 配置 Harbor 多架构镜像支持..."

# 1. 配置客户端证书
echo "📜 配置客户端证书..."
mkdir -p /etc/docker/certs.d/110.1.20.3/
\cp -rvf /data/opt/installharbor/certs/{ca.crt,harbor.crt} /etc/docker/certs.d/110.1.20.3/
cd /etc/docker/certs.d/110.1.20.3/
chmod 644 ca.crt harbor.crt

# 2. 重启 Docker
echo "🔄 重启 Docker 服务..."
systemctl daemon-reload 
systemctl restart docker

# 3. 重启 Harbor（同台机器上需要）
echo "🔄 重启 Harbor..."
cd /data/opt/installharbor/
bash install.sh

# 4. 等待服务启动
echo "⏳ 等待服务启动..."
sleep 30

# 5. 测试配置
echo "🧪 测试配置..."
docker login 110.1.20.3

# 6. 创建测试 manifest
echo "📦 创建测试 manifest..."
docker manifest create 110.1.20.3/library/java-gdal-local:3.8.5 \
  110.1.20.3/library/java-gdal-local:3.8.5-amd64 \
  110.1.20.3/library/java-gdal-local:3.8.5-arm64

docker manifest annotate 110.1.20.3/library/java-gdal-local:3.8.5 \
  110.1.20.3/library/java-gdal-local:3.8.5-amd64 --os linux --arch amd64

docker manifest annotate 110.1.20.3/library/java-gdal-local:3.8.5 \
  110.1.20.3/library/java-gdal-local:3.8.5-arm64 --os linux --arch arm64

docker manifest push 110.1.20.3/library/java-gdal-local:3.8.5

# 7. 验证结果
echo "✅ 验证结果..."
docker manifest inspect 110.1.20.3/library/java-gdal-local:3.8.5

echo "🎉 配置完成！"

总结

通过本文的配置和脚本，我们成功解决了在自建 Harbor 中管理多架构镜像的问题。关键要点包括：

正确配置 HTTPS 证书：使用正确的文件名和权限
启用实验性功能：Docker manifest 需要实验性功能支持
理解 manifest 操作：区分 docker push 和 docker manifest push
自动化流程：使用脚本批量处理多个版本和架构

这套方案可以帮助团队高效地管理多架构容器镜像，支持在不同 CPU 架构的环境中无缝部署应用。

参考资源

Docker Multi-platform images
Docker manifest command
Harbor Documentation

MinIO 站点复制部署与测试：同步与故障恢复

2025-05-13T08:38:00.000Z

MinIO 是一个高性能的分布式对象存储系统，其站点复制（Site Replication）功能支持跨集群的数据和元数据同步。本文记录了如何使用 Docker Compose 部署 MinIO 站点复制集群，配置两个 MinIO 实例，并进行同步测试和故障恢复测试。测试环境基于 20T 磁盘，适用于需要高可用性和灾难恢复的场景。

MinIO 站点复制简介

MinIO 的站点复制是一种集群级别的双向同步机制，可同步数据（桶、对象）和元数据（用户、策略、配置）。其主要特性包括：

最终一致性：对象数据近实时同步。
严格一致性：元数据保持完全一致。
高可用性：任一集群故障时，另一个集群可继续提供服务。

本文将部署两个 MinIO 实例（SITE1 和 SITE2），通过 minio-mc 容器配置站点复制，并测试同步和故障恢复。

环境与配置

硬件与网络

服务器：两台服务器（MinIO1: 192.168.199.145，MinIO2: 192.168.199.147）。
磁盘：每台服务器挂载 20T 磁盘。
网络：1Gbps 带宽，RTT < 20ms。
操作系统：Linux（支持 Docker）。

Docker Compose 配置

以下是 MinIO 和 minio-mc 服务的 Docker Compose 配置：

services:
  minio:
    image: "${MINIO_IMAGE}"
    deploy:
      resources:
        limits:
          memory: 4096M
    networks:
      - middleware 
    container_name: minio
    ports:
      - "${MINIO_PORT}:9000"
      - "${MINIO_CONSOLE_PORT}:9001"
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: "${MINIO_ROOT_USER}"
      MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD}"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./data/minio/data:/data
    restart: always

  minio-mc:
    image: minio/mc:latest
    container_name: minio-mc
    networks:
      - middleware 
    environment:
      SITE1_URL: "${SITE1_URL}"
      SITE2_URL: "${SITE2_URL}"
      MINIO_ROOT_USER: "${MINIO_ROOT_USER}"
      MINIO_ROOT_PASSWORD: "${MINIO_ROOT_PASSWORD}"
    volumes:
      - ./site-replication.sh:/site-replication.sh
    entrypoint: ["/bin/bash", "/site-replication.sh"]
    healthcheck:
      test: ["CMD-SHELL", "mc --version >/dev/null 2>&1"]
      interval: 30s
      timeout: 10s
      start_period: 10s
      retries: 3
    restart: always

networks:
  middleware:
    driver: bridge

环境变量

环境变量存储在 .env 文件中：

# MinIO
MINIO_PORT=9000
MINIO_CONSOLE_PORT=9001
MINIO_ROOT_USER="admin"
MINIO_ROOT_PASSWORD="Admin@123.com"
MINIO_IMAGE="minio/minio:RELEASE.2025-04-22T22-12-26Z"
SITE1_URL="http://192.168.145:9000"
SITE2_URL="http://192.168.147:9000"

站点复制脚本

site-replication.sh 用于配置站点复制：

#!/bin/bash

# 严格模式：错误、未定义变量、管道失败时退出
set -euo pipefail

# 颜色定义
RED='\033[0;31m'
GREEN='\033[0;32m'
CYAN='\033[1;36m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
MAGENTA='\033[0;35m'
RESET='\033[0m'

# 更丰富的图标集
ICON_INFO="🌐"
ICON_SUCCESS="✨"
ICON_WARNING="⚠️"
ICON_ERROR="💥"
ICON_DEBUG="🐞"
ICON_WAIT="⏳"
ICON_CLEAN="🧹"
ICON_CONFIG="⚙️"
ICON_NETWORK="📡"
ICON_START="🚀"
ICON_READY="✅"
ICON_FINISH="🎉"

# 增强版日志函数（优化颜色处理）
log() {
  local level=$1 message=$2
  local color icon timestamp
  timestamp=$(date -u '+%H:%M:%S')
  
  case $level in
    INFO)    color="$GREEN"  icon="$ICON_INFO" ;;
    SUCCESS) color="$GREEN"  icon="$ICON_SUCCESS" ;;
    WARN)    color="$YELLOW" icon="$ICON_WARNING" ;;
    ERROR)   color="$RED"    icon="$ICON_ERROR" ;;
    DEBUG)   color="$BLUE"   icon="$ICON_DEBUG" ;;
    WAIT)    color="$MAGENTA" icon="$ICON_WAIT" ;;
    *)       color="$CYAN"   icon="$ICON_INFO" ;;
  esac

  # 直接输出消息，避免嵌套格式化问题
  printf "${color}%s %-7s\t%s${RESET}
" "$timestamp $icon" "[$level]" "$message"
}

# 简洁标题样式（改为 === 标题 === 形式）
header() {
  if [ "$2" = "MinIO 站点复制初始化" ]; then
    printf "

${MAGENTA}███╗   ███╗██╗███╗   ██╗██╗ ██████╗     ███╗   ███╗ ██████╗
████╗ ████║██║████╗  ██║██║██╔═══██╗    ████╗ ████║██╔════╝
██╔████╔██║██║██╔██╗ ██║██║██║   ██║    ██╔████╔██║██║     
██║╚██╔╝██║██║██║╚██╗██║██║██║   ██║    ██║╚██╔╝██║██║     
██║ ╚═╝ ██║██║██║ ╚████║██║╚██████╔╝    ██║ ╚═╝ ██║╚██████╗
╚═╝     ╚═╝╚═╝╚═╝  ╚═══╝╚═╝ ╚═════╝     ╚═╝     ╚═╝ ╚═════╝

>> %s %s${RESET}
" "$1" "$2"
    printf "
"
  else
    printf "
${CYAN}[ TASK %d ] ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
>> %s %s${RESET}
" "$task_number" "$1" "$2"
    printf "
"
    task_number=$((task_number + 1))
  fi
}

# 初始化任务计数器
task_number=1

# 等待服务就绪（合并为一个任务）
wait_for_services() {
  local retries=15 delay=2 attempt=1
  local spinner=("⣾" "⣽" "⣻" "⢿" "⡿" "⣟" "⣯" "⣷")
  local all_ready=0

  header "$ICON_WAIT" "等待 MinIO 服务就绪"

  for site in "${!SITES[@]}"; do
    local alias="HEALTHCHECK_$site"
    local url="${SITES[$site]}"
    local attempt=1
    local all_ready=0



    log INFO "检查服务: $url"
    while [ $attempt -le $retries ]; do
      if /usr/bin/mc alias set "$alias" "$url" "$MINIO_ACCESS_KEY" "$MINIO_SECRET_KEY" >/dev/null 2>&1 && \
         /usr/bin/mc ls "$alias" >/dev/null 2>&1; then
        log SUCCESS "服务已就绪: $url"
        all_ready=1
        if [ "$site" = "SITE1" ]; then
          printf "${CYAN}%s${RESET}
" "$(for i in $(seq 1 61); do printf "-"; done)"
        fi
        break
      fi

      printf "\r%-80s" " "
      printf "\r${YELLOW}%s 尝试 %2d/%-2d 检查服务 %s 中...${RESET}" \
        "${spinner[$((attempt % ${#spinner[@]}))]}" \
        $attempt $retries "$url"
      sleep $delay
      ((attempt++))
      delay=$((delay * 2 > 8 ? 8 : delay * 2))
    done

    if [ $all_ready -eq 0 ]; then
      log ERROR "服务 $url 在 $retries 次尝试后仍未就绪"
      exit 1
    fi
  done
  echo ""
}

# 配置别名（优化颜色格式）
configure_aliases() {
  header "$ICON_CONFIG" "配置 MinIO 站点别名"
  for site in "${!SITES[@]}"; do
    local url="${SITES[$site]}"
    /usr/bin/mc alias remove "$site" 2>/dev/null || true
    if /usr/bin/mc alias set "$site" "$url" "$MINIO_ACCESS_KEY" "$MINIO_SECRET_KEY" >/dev/null 2>&1; then
      log SUCCESS "别名配置成功: ${site} → ${url}"
    else
      log ERROR "无法配置别名: $site → $url"
      return 1
    fi
  done
  echo ""
}

# 检查复制配置状态
check_replication_status() {
  /usr/bin/mc admin replicate info SITE1 2>&1 | grep -q "SiteReplication enabled"
}

# 清除原复制配置
cleanup_old_replication() {
  header "$ICON_CLEAN" "清理原有复制配置"
  for site in "${!SITES[@]}"; do
    log INFO "正在清理 $site 的复制配置..."
    if /usr/bin/mc admin replicate rm --all "$site" --force 2>/dev/null; then
      log SUCCESS "成功清理 $site 的配置"
    else
      log WARN "$site 无配置可清理或清理失败"
    fi
  done
  sleep 2
  if check_replication_status; then
    log ERROR "复制配置仍存在，请手动检查"
    return 1
  fi
  log SUCCESS "所有站点复制配置已清理完成"
  echo ""
}

# 可靠的bucket删除函数
delete_all_buckets() {
  local site=$1
  log WARN "即将清空 ${site} 的所有bucket..."
  local buckets
  buckets=$(/usr/bin/mc ls "$site" --json | jq -r .key | tr -d '/' | grep -v '^$')
  if [ -z "$buckets" ]; then
    log INFO "没有 bucket 需要删除"
    return 0
  fi
  echo "$buckets" | while read -r bucket; do
    log INFO "正在删除 ${site}/${bucket}..."
    if /usr/bin/mc rb --force "${site}/${bucket}" >/dev/null 2>&1; then
      log SUCCESS "删除成功: ${site}/${bucket}"
    else
      log ERROR "删除失败: ${site}/${bucket}"
      return 1
    fi
  done
  if /usr/bin/mc ls "$site" | grep -q .; then
    log ERROR "${site} 中仍有bucket存在"
    return 1
  fi
  log SUCCESS "${site} 已完全清空"
}

# 设置复制配置
setup_replication() {
  header "$ICON_NETWORK" "设置站点复制"
  local retries=5 delay=2 attempt=1
  local site_list=("${!SITES[@]}")
  while [ $attempt -le $retries ]; do
    log WAIT "尝试配置复制 (${attempt}/${retries})..."
    output=$(/usr/bin/mc admin replicate add "${site_list[@]}" 2>&1)
    if [ $? -eq 0 ]; then
      log SUCCESS "站点复制配置成功!"
      echo ""
      return 0
    fi
    if [[ $output == *"only one cluster may have data"* ]]; then
      log WARN "检测到 SITE2 中已有数据，违反复制要求"
      if ! delete_all_buckets "SITE2"; then
        log ERROR "清空 SITE2 失败，无法继续"
        return 1
      fi
      log INFO "等待 ${delay} 秒让系统完成清理..."
      sleep $delay
    else
      log ERROR "复制配置失败: $(echo "$output" | head -n1)"
      log DEBUG "完整错误: $output"
    fi
    ((attempt++))
    delay=$((delay * 2 > 8 ? 8 : delay * 2))
  done
  log ERROR "经过 ${retries} 次尝试后仍无法配置复制"
  return 1
}

# 优化状态验证表格
verify_status() {
  header "$ICON_NETWORK" "复制状态验证"
  for site in "${!SITES[@]}"; do
    printf "${GREEN}%s [SUCCESS]   查询成功: %s → %s${RESET}
" "$ICON_SUCCESS" "$site" "${SITES[$site]}"
    printf "${CYAN}%s${RESET}
" "$(for i in $(seq 1 160); do printf "-"; done)"
    status_output=$(/usr/bin/mc admin replicate info "$site" 2>&1)
    if echo "$status_output" | grep -q "SiteReplication enabled"; then
      printf "${GREEN}%s${RESET}
" "$status_output"
    else
      printf "${RED}%s${RESET}
" "$status_output"
    fi
    echo ""
  done
}

# 主流程控制
main() {
  : "${SITE1_URL:?需要 SITE1_URL 环境变量}"
  : "${SITE2_URL:?需要 SITE2_URL 环境变量}"
  : "${MINIO_ACCESS_KEY:?需要 MINIO_ACCESS_KEY 环境变量}"
  : "${MINIO_SECRET_KEY:?需要 MINIO_SECRET_KEY 环境变量}"
  declare -A SITES=(["SITE1"]="$SITE1_URL" ["SITE2"]="$SITE2_URL")
  header "$ICON_START" "MinIO 站点复制初始化"
  wait_for_services
  configure_aliases || exit 1
  cleanup_old_replication || exit 1
  setup_replication || exit 1
  verify_status
  header "$ICON_FINISH" "MinIO 站点复制已就绪"
  log SUCCESS "所有配置已完成，服务运行中..."
  log INFO "按 Ctrl+C 停止服务"
  exec tail -f /dev/null
}

trap 'log INFO "收到终止信号，正在关闭..."; exit 0' SIGTERM SIGINT
main

部署步骤

准备环境

创建目录：

mkdir -p /data/opt/installmiddleware/data/minio/data

设置磁盘权限：
确保 20T 磁盘挂载到 /data，并赋予权限：
chown -R 1000:1000 ./data/minio/data
保存配置：
- 保存 docker-compose.yml 和 .env 文件。
- 保存 site-replication.sh，设置可执行权限：
  chmod +x site-replication.sh

启动服务

在 MinIO1 和 MinIO2 服务器上分别部署 MinIO 实例：

cd /data/opt/installmiddleware
docker-compose up -d

配置站点复制

minio-mc 容器自动运行 site-replication.sh，配置站点复制。

检查日志：

docker logs --tail 100 minio-mc

预期输出：

Configuring aliases for SITE1 and SITE2...
Adding site replication between SITE1 and SITE2...
Site replication configured successfully!

同步测试

测试目标

验证 MinIO1 创建的桶和上传的对象是否自动同步到 MinIO2。

测试步骤

在 MinIO1 创建桶：

docker exec -it minio-mc bash
mc mb SITE1/test-bucket

上传测试文件：

创建文件：
echo "Hello, MinIO!" > test.txt
上传到 MinIO1：
mc cp test.txt SITE1/test-bucket

验证 MinIO2 同步：

检查桶：

mc ls SITE2

预期输出：

[2025-05-13 16:40:00 CST]     0B test-bucket/

检查文件：

mc ls SITE2/test-bucket

预期输出：

[2025-05-13 16:40:10 CST]    14B test.txt

访问 MinIO2 控制台：
- 打开 http://192.168.199.147:9000，登录（admin/Admin@123.com）。
- 确认 test-bucket 和 test.txt 存在。

测试结果

桶和文件成功同步，说明站点复制正常，同步延迟通常在毫秒级（RTT < 20ms）。

故障恢复测试

测试目标

模拟 MinIO1 故障，验证 MinIO2 的服务可用性，并测试 MinIO1 恢复后的同步。

测试步骤

停止 MinIO1：
docker-compose stop minio

检查站点复制状态：

在 minio-mc 容器中：

mc admin replicate status SITE2

预期输出（基于实际测试）：

Bucket replication status:
●  0/1 Buckets in sync
Bucket          | SITE1           | SITE2          
test            |                 | ✗  in-sync     
...
Object replication status:
Link:          ● offline 5 seconds (total downtime: 4 minutes 30 seconds)
Errors:        0 in last 1 minute; 1 in last 1hr

验证 MinIO2 服务：

上传新文件：

echo "MinIO2 test" > test2.txt
mc cp test2.txt SITE2/test-bucket

检查：

mc ls SITE2/test-bucket

预期输出：

[2025-05-13 16:45:00 CST]    14B test.txt
[2025-05-13 16:45:10 CST]    12B test2.txt

恢复 MinIO1：

启动：
docker-compose start minio

验证健康：

curl -f http://192.168.199.145:9000/minio/health/live

重新同步：

触发增量同步：

mc admin replicate resync start SITE2 SITE1

检查状态：

mc admin replicate status SITE2

预期输出：

Site Replication Status:
- Site: SITE1 (http://192.168.199.145:9000) - Online
- Site: SITE2 (http://192.168.199.147:9000) - Online
Replication Status: Active

验证 MinIO1 同步：

检查：

mc ls SITE1/test-bucket

预期输出：

[2025-05-13 16:45:00 CST]    14B test.txt
[2025-05-13 16:45:10 CST]    12B test2.txt

测试结果

MinIO1 故障期间，MinIO2 正常提供服务。
MinIO1 恢复后，增量数据（test2.txt）同步成功，站点复制恢复正常。

注意事项与优化建议

磁盘与虚拟化

20T 磁盘（虚拟化后 18T）可能受虚拟化影响，建议直通磁盘：
volumes:
- /dev/sdb:/data
定期检查磁盘健康：
smartctl -a /dev/sdb

网络

确保 RTT < 20ms，带宽 ≥ 1Gbps。

检查防火墙：

ufw allow from 192.168.199.0/24 to any port 9000

安全性

替换默认凭据（admin/Admin@123.com）。

启用 TLS：

environment:
  - MINIO_SERVER_URL=https://192.168.199.145:9000

监控

启用 Prometheus：

environment:
  - MINIO_PROMETHEUS_AUTH_TYPE=public

使用 Grafana 监控节点状态（minio_node_up）和复制延迟（minio_replication_last_hour_latency_millis）。

预算

站点复制需要两台服务器（约 14000-25000 元）。若预算有限，可考虑单向主从复制（约 7000-13000 元）。

总结

通过 Docker Compose 和 site-replication.sh，我们部署了 MinIO 站点复制集群，实现了 MinIO1 和 MinIO2 的数据和元数据同步。同步测试验证了桶和对象的自动同步，故障恢复测试确认了 MinIO2 的高可用性和 MinIO1 恢复后的增量同步。该方案结合 20T 磁盘的存储容量，适用于高可用性场景。

如需进一步优化（如 webhook 通知、Flask API 集成），请参考 MinIO 文档：Site Replication。

如何在 Docker 环境中部署 VLLM

2025-05-12T09:14:25.000Z

本指南将详细介绍如何在 Windows 和 Linux 系统上使用 Docker 部署 vLLM 大模型服务，并提供跨平台测试方案。

系统要求

硬件要求

NVIDIA GPU (建议 RTX 3060 或更高)
显存要求:
- Qwen/Qwen3-0.6B: 至少 8GB （本地测试）
- Qwen/QwQ-32B: 至少 64GB（生产使用）
内存: 16GB 或更高

软件要求

操作系统:
- Windows 10/11 (专业版/企业版)
- Linux (Ubuntu 20.04+/CentOS 7+)
Docker Engine 20.10+
NVIDIA 驱动 535+
NVIDIA Container Toolkit

准备工作

1. 安装必要组件

Windows 环境:

# 安装 WSL2 (Windows 子系统)
wsl --install

# 安装 Docker Desktop
# 从 https://www.docker.com/products/docker-desktop 下载安装

# 安装 NVIDIA 驱动和 CUDA
# 从 https://developer.nvidia.com/cuda-downloads 下载

Linux 环境:

# 安装 Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

# 安装 NVIDIA Container Toolkit
distribution=$(. /etc/os-release;echo $ID$VERSION_ID) \
   && curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add - \
   && curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update
sudo apt-get install -y nvidia-docker2
sudo systemctl restart docker

2. 验证环境

# 验证 Docker 安装
docker --version

# 验证 NVIDIA 支持
docker run --rm --gpus all nvidia/cuda:11.0.3-base-ubuntu20.04 nvidia-smi

Docker 部署

1. 创建 docker-compose.yml 文件

# version: '3.8'

services:
  vllm:
    image: vllm/vllm-openai:latest
    runtime: nvidia
    container_name: vllm
    restart: unless-stopped 
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              capabilities: [gpu]
              count: all
    volumes:
      - $HOME/.cache/huggingface:/root/.cache/huggingface
    ports:
      - "28000:8000"
    environment:
      - HF_HOME=/root/.cache/huggingface
      - PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
    command:
      - --model
      - Qwen/Qwen3-0.6B # 或 Qwen/QwQ-32B
      - --gpu-memory-utilization
      - "0.8"
      - --trust-remote-code
      - --max-num-seqs
      - "256"
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:8000/health || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

Windows 用户注意:

将 $HOME/.cache/huggingface 替换为 C:/Users/Devops/.cache/huggingface
确保路径使用正斜杠 / 而非反斜杠 \

2. 启动服务

# 下载 vLLM 镜像
docker pull vllm/vllm-openai:latest

# 启动服务
docker-compose up -d

3. 验证服务

# 检查容器状态
docker ps

# 查看日志
docker logs vllm

# 健康检查
curl http://localhost:28000/health

模型下载与管理

1. 手动下载模型 (可选)

# 安装 huggingface_hub
pip install huggingface_hub

# 下载模型 (可在宿主机执行)
huggingface-cli download Qwen/Qwen3-0.6B 

# 模型默认存放在用户家目录下，比如:
# C:/Users/Devops/.cache/huggingface/hub/models--Qwen--Qwen3-0.6B

2. 使用 vLLM 自动下载

vLLM 会在首次启动时自动下载模型，但建议提前下载以避免超时。

服务测试

1. 使用 curl 测试

curl http://localhost:28000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
      "model": "Qwen/Qwen3-0.6B",
      "prompt": "你好，介绍一下你自己",
      "max_tokens": 100
  }'

2. 使用 HTML 测试界面

创建 vllm-test.html 文件：

html>
<html>
<body>
  <h2>vLLM 测试界面h2>
  <textarea id="input" rows="4" cols="50" placeholder="输入提示词...">textarea><br>
  <button onclick="generate()">生成button>
  <pre id="output">pre>

  <script>
    async function generate() {
      const input = document.getElementById("input").value;
      try {
        const response = await fetch("http://localhost:28000/v1/completions", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({
            model: "Qwen/Qwen3-0.6B",
            prompt: input,
            max_tokens: 100
          })
        });
        const result = await response.json();
        document.getElementById("output").textContent = result.choices[0].text;
      } catch (error) {
        document.getElementById("output").textContent = "错误: " + error.message;
      }
    }
  script>
body>
html>

跨平台测试方案

Windows 环境测试

浏览器安全限制:
- Chrome/Firefox 默认阻止跨域请求
- 解决方案:
  - 使用 file:/// 协议直接打开 HTML 文件
  - 或使用以下命令启动 Chrome 禁用安全限制:
    chrome.exe --user-data-dir="C:/Temp" --disable-web-security

替代方案:

使用 Postman 或 Insomnia 测试 API

使用 Python 脚本测试:

from openai import OpenAI

client = OpenAI(base_url="http://localhost:28000/v1", api_key="token-abc123")

completion = client.completions.create(
    model="Qwen/Qwen3-0.6B",
    prompt="你好，介绍一下你自己",
    max_tokens=100
)
print(completion.choices[0].text)

Linux 环境测试

浏览器测试:
- 可直接使用 Firefox 打开 HTML 文件
- 或部署简单 HTTP 服务器:
  python3 -m http.server 8000
  然后访问 http://localhost:8000/vllm-test.html

命令行测试:

# 使用 httpie 工具
http POST http://localhost:28000/v1/completions \
  model="Qwen/Qwen3-0.6B" \
  prompt="你好" \
  max_tokens:=50

常见问题解决

1. 模型下载失败

症状: 容器日志显示下载超时或失败

解决方案:

设置 HTTP 代理:

environment:
  - HF_HUB_ENABLE_HF_TRANSFER=1
  - http_proxy=http://your-proxy:port
  - https_proxy=http://your-proxy:port

2. GPU 内存不足

症状: CUDA out of memory 错误

解决方案:

降低 --gpu-memory-utilization 值 (如 0.5)
使用更小模型 (如 Qwen3-0.6B 替代 QwQ-32B)
添加 --enforce-eager 参数减少内存占用

3. 跨域问题 (CORS)

症状: HTML 测试界面无法访问 API

解决方案:

启动 vLLM 时添加 CORS 参数:

command:
  - --model
  - Qwen/Qwen3-0.6B
  - --cors-allow-origins "*"

或使用 Nginx 反向代理配置 CORS

4. Windows 路径问题

症状: 卷挂载失败

解决方案:

使用绝对路径并确保 Docker Desktop 已启用 “Shared Drives”

示例:

volumes:
  - C:/Users/Devops/.cache/huggingface:/root/.cache/huggingface

性能优化建议

量化:

command:
  - --model
  - Qwen/Qwen3-0.6B
  - --quantization
  - awq  # 或 gptq

批处理优化:

command:
  - --max-num-batched-tokens
  - "4096"

并行推理:

command:
  - --tensor-parallel-size
  - "2"  # 使用2个GPU

使用 Cloudflare Tunnel 安全暴露本地服务到公网

2025-04-23T07:14:25.000Z

Cloudflare Tunnel 是一种强大的反向隧道服务，允许用户将本地服务器或内部网络资源安全暴露到公网，而无需开放防火墙端口或拥有公网 IP 地址。本文将详细介绍 Cloudflare Tunnel 的工作原理、功能特点、使用场景，并结合实际操作步骤，展示如何通过 Cloudflare Tunnel 将本地服务映射到公网域名。

什么是 Cloudflare Tunnel？

Cloudflare Tunnel 是 Cloudflare 提供的一项服务，通过运行轻量级客户端 cloudflared，在本地设备与 Cloudflare 全球网络之间建立安全的出站连接（outbound-only）。外部用户可以通过 Cloudflare 的网络访问你的本地服务，而无需直接暴露服务器的 IP 或端口。

工作原理

安装客户端：在本地服务器或设备上安装 cloudflared，这是 Cloudflare 提供的隧道守护进程。
创建隧道：使用 cloudflared 创建一个隧道，与 Cloudflare 边缘网络建立连接，无需公网 IP。
路由流量：在 Cloudflare 仪表盘中配置域名或子域名，外部请求通过 Cloudflare 转发到本地服务。
安全性保障：所有流量经过 Cloudflare 的加密，支持 HTTPS，并可结合 Cloudflare Access 添加身份验证。

主要特点

无需端口转发：无需配置路由器或开放防火墙端口，适合家庭网络或受限环境。
免费基础服务：基本功能（如创建隧道、绑定域名）免费，适合个人用户或小型项目。
安全性增强：提供 DDoS 防护、SSL/TLS 加密，流量通过 Cloudflare 全球网络。
灵活性：支持多种协议（如 HTTP、SSH、RDP），可暴露网页服务、远程桌面或游戏服务器。

使用场景

远程访问本地服务：如在家运行 NAS，想通过公网访问文件管理界面。
开发测试：快速将本地开发环境暴露到公网，测试 webhook 或第三方回调。
替代 VPN：相比传统 VPN，Cloudflare Tunnel 配置简单，适合快速部署。

对比 ngrok

与类似的反向隧道工具 ngrok 相比，Cloudflare Tunnel 有以下优势：

成本：ngrok 免费版有严格的时长（2小时断开）和连接限制，而 Cloudflare Tunnel 免费版更宽松。
域名：ngrok 免费版提供随机域名，Cloudflare 支持自定义域名。
安全性：Cloudflare 提供额外的 DDoS 防护和全球 CDN 加速。

实践：使用 Cloudflare Tunnel 暴露本地服务

下面，我们将通过实际操作，展示如何使用 Cloudflare Tunnel 将本地运行的网页服务（http://localhost:19000）映射到公网域名 share.freemankevin.uk。

准备工作

注册 Cloudflare 账号：登录 Cloudflare 仪表盘，添加你的域名并确保 DNS 托管在 Cloudflare。
安装 cloudflared：
- 在 Windows 上，下载 cloudflared.exe（官方下载地址）。
- 将 cloudflared.exe 放置在合适目录（如 C:\cloudflared\）。

安装 Cloudflare Tunnel 服务

运行以下命令以安装 cloudflared 服务并绑定 Cloudflare 账户：

cloudflared.exe service install eyJhIjoiMjc0YzhmYzViSa2kih1k3MzVhNjBjNWQ1MTkzOWQyMDEiLCJ0IjoiMDEwNDI5MmEtNzEwYS00NTBkLWI3OGYtOTNjZTExYjhmYTZlIiwicyI6Ik56Um1ZVGcyT0dRdE9XUm1OaTAwWkRJM0xUbGxZemN0TWpKbFlUWmhabiJzTlRRMiJ9

eyJh... 是 Cloudflare 提供的认证令牌，请替换为你自己的令牌（从 Cloudflare 仪表盘获取）。

成功后，cloudflared 将作为系统服务运行。

创建隧道

创建名为 share 的隧道：

cloudflared tunnel create share

输出类似以下内容：

Tunnel credentials written to C:\Users\Devops\.cloudflared\ab9d567c-00c0-46f3-83b7-680ei8b2f3f6.json. cloudflared chose this file based on where your origin certificate was found. Keep this file secret. To revoke these credentials, delete the tunnel.

Created tunnel share with id ab9d567c-00c0-46f3-83b7-680ei8b2f3f6

这会生成一个隧道 ID（ab9d567c-00c0-46f3-83b7-680ei8b2f3f6）和凭证文件（ab9d567c-00c0-46f3-83b7-680ei8b2f3f6.json）。请妥善保存凭证文件，避免泄露。

配置隧道

创建配置文件 config.yml，内容如下：

tunnel: share
credentials-file: C:\Users\Devops\.cloudflared\ab9d567c-00c0-46f3-83b7-680ei8b2f3f6.json
ingress:
  - hostname: share.freemankevin.uk
    service: http://localhost:19000
  - service: http_status:404

tunnel：指定隧道名称（share）。
credentials-file：指定凭证文件路径。
ingress：定义路由规则，将 share.freemankevin.uk 的请求转发到本地 http://localhost:19000，其他请求返回 404。

将 config.yml 保存到 C:\Users\Devops\.cloudflared\ 目录。

配置 DNS 记录

在 Cloudflare 仪表盘中，添加 CNAME 记录：

类型	名称	目标
CNAME	share	ab9d567c-00c0-46f3-83b7-680ei8b2f3f6.cfargotunnel.com

或者，使用以下命令自动配置 DNS：

cloudflared tunnel route dns share share.freemankevin.uk

运行隧道

运行以下命令启动隧道：

cloudflared tunnel --config C:\Users\Devops\.cloudflared\config.yml --origin-ca-pool C:\Users\Devops\.cloudflared\ca-certificates.pem --logfile C:\Users\Devops\.cloudflared\cloudflared.log run share

参数说明：

--config：指定配置文件路径。
--origin-ca-pool：指定 CA 证书路径（可选，通常用于企业环境）。
--logfile：指定日志文件路径，便于调试。

启动后，share.freemankevin.uk 将可通过公网访问，并指向本地 http://localhost:19000 的服务。

测试访问

在浏览器中访问 https://share.freemankevin.uk，确认是否能正常访问本地服务。如果无法访问，检查以下内容：

确保本地服务（http://localhost:19000）正在运行。
检查 Cloudflare 仪表盘中的 DNS 记录是否正确。
查看 cloudflared 日志（C:\Users\Devops\.cloudflared\cloudflared.log）以排查错误。

添加系统服务

为了方便启动和管理隧道，我们可以将上面的隧道共享服务添加到系统服务中：

添加服务

# 以管理员身份打开 PowerShell
# 创建系统服务
sc create CloudflaredTunnel binPath= "C:\Program Files (x86)\cloudflared\cloudflared.exe tunnel --config C:\Users\Devops\.cloudflared\config.yml run share" start= auto DisplayName= "Cloudflare Tunnel Service"

# 设置服务描述
sc description CloudflaredTunnel "Cloudflare Tunnel for secure remote access"

# 配置故障恢复（自动重启）
sc failure CloudflaredTunnel reset= 30 actions= restart/5000


# 启动服务
sc start CloudflaredTunnel

添加后，cloudflared 将作为系统服务运行，无需手动启动。

卸载服务

如果不再需要该服务，可以卸载：

sc delete CloudflaredTunnel

免费版限制

带宽：Cloudflare Tunnel 免费版没有明确的带宽限制，但可能对滥用行为进行限制。
功能：高级功能（如负载均衡、Zero Trust 策略）需要付费计划。
域名：需使用 Cloudflare 托管的域名（可免费注册或迁移现有域名）。

常见问题

隧道无法连接？

检查 cloudflared 是否正常运行，查看日志文件。
确保网络允许 cloudflared 的出站连接（端口 443）。

DNS 配置失败？

确认域名已正确托管在 Cloudflare。
检查 CNAME 记录是否指向正确的隧道地址。

如何停止隧道？

按 Ctrl+C 停止 cloudflared 进程。
或删除隧道：cloudflared tunnel delete share。

总结

Cloudflare Tunnel 是一个简单、安全且免费的工具，适合将本地服务暴露到公网。通过以上步骤，你可以轻松将本地网页服务映射到自定义域名，并享受 Cloudflare 提供的加密和 DDoS 防护。相比 ngrok，Cloudflare Tunnel 在成本、灵活性和安全性上更具优势，非常适合个人开发者、家庭用户或小型项目。

在 Docker 环境中部署 Nexus 仓库

2025-04-22T07:14:25.000Z

Nexus是一个功能强大的仓库管理工具，用于托管Maven工件、Docker镜像等。本文将详细介绍如何在Docker环境中部署Nexus仓库管理器，并集成PostgreSQL数据库、快照清理服务和数据库备份服务。

环境准备

目录结构创建

# 创建Nexus数据目录
mkdir -p ./nexus/sonatype-work
chmod -R 755 ./nexus/sonatype-work
chown -R 200:200 ./nexus/sonatype-work

# 创建Nexus密钥目录
mkdir -p ./nexus/secret
cat > ./nexus/secret/nexus-secrets.json <<EOF
{
  "active": "nexus-key",
  "keys": [
    {
      "id": "nexus-key",
      "key": "$(openssl rand -base64 32)"
    }
  ]
}
EOF

# 设置权限
chmod 600 ./nexus/secret/nexus-secrets.json
chown 200:200 ./nexus/secret/nexus-secrets.json

# 创建PostgreSQL目录
mkdir -p ./postgres/data ./postgres/dbbackups
chmod -R 755 ./postgres/data ./postgres/dbbackups
chown -R 101:103 ./postgres/data ./postgres/dbbackups

环境变量配置

创建.env文件：

# Nexus配置
NEXUS_PORT=8081
NEXUS_IMAGE=sonatype/nexus3:3.79.0
NEXUS_PASS=Admin@gmail.123.com
HEALTHCHECK_PORT=8000
NEXUS_URL=http://192.168.1.100:8081
NEXUS_USER=admin
REPOSITORY_NAME=maven-snapshots

# PostgreSQL配置
POSTGRES_PORT=5432
POSTGRES_USER=nexus
POSTGRES_PASS=Nexus@gmail.123.com
POSTGRES_DB=nexus
POSTGRES_IMAGE=kartoza/postgis:17-3.5
POSTGRES_BACKUP_IMAGE=kartoza/pg-backup:17-3.5

Docker Compose配置

创建docker-compose.yaml文件：

#version: '3'
services:
  nexus:
    image: "${NEXUS_IMAGE}"
    container_name: nexus
    deploy:
      resources:
        limits:
          memory: 8192M
    ports:
      - "${NEXUS_PORT}:8081"
    networks:
      - middleware
    environment:
      TZ: Asia/Shanghai
      INSTALL4J_ADD_VM_PARAMS: "-Xms2g -Xmx2g -XX:MaxDirectMemorySize=2g -Djava.util.prefs.userRoot=/opt/sonatype/sonatype-work -Dnexus.datastore.enabled=true -Dnexus.datastore.nexus.jdbcUrl=jdbc:postgresql://postgres:5432/nexus?gssEncMode=disable -Dnexus.datastore.nexus.username=nexus -Dnexus.datastore.nexus.password=Nexus@gmail.123.com -Dnexus.datastore.nexus.advanced=maximumPoolSize=50 -Dkaraf.data=/opt/sonatype/sonatype-work -Dkaraf.etc=/opt/sonatype/sonatype-work/etc"
      NEXUS_SECURITY_RANDOMPASSWORD: "false"
      NEXUS_SECRETS_KEY_FILE: /opt/sonatype/sonatype-work/etc/nexus-secrets.json
    restart: always
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8081/service/rest/v1/status"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 120s
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./nexus/secret/nexus-secrets.json:/opt/sonatype/sonatype-work/etc/nexus-secrets.json:ro
      - ./nexus/sonatype-work:/opt/sonatype/sonatype-work

  nexus-cleanup:
    image: ghcr.io/freemankevin/clean-snapshots/nexus-cleanup:sha-afbc846
    container_name: nexus-cleanup
    environment:
      NEXUS_URL: "${NEXUS_URL}"
      NEXUS_USER: "${NEXUS_USER:-admin}"
      NEXUS_PASS: "${NEXUS_PASS}"
      REPOSITORY_NAME: "${REPOSITORY_NAME:-maven-snapshots}"
      RETAIN_COUNT: "3"
      DRY_RUN: "false"
      LOG_LEVEL: "INFO"
      SCHEDULE_TIME: "03:00"
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./nexus/nexus-cleanup-logs:/var/log
    ports:
      - "${HEALTHCHECK_PORT}:8000"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    depends_on:
      nexus:
        condition: service_healthy


  postgres:
    image: "${POSTGRES_IMAGE}"
    container_name: postgres
    deploy:
      resources:
        limits:
          memory: 8192M  
    ports:
      - "${POSTGRES_PORT}:5432"
    networks:
      - middleware
    environment:
      TZ: Asia/Shanghai
      POSTGRES_DB: "${POSTGRES_DB}"
      POSTGRES_USER: "${POSTGRES_USER}"
      POSTGRES_PASS: "${POSTGRES_PASS}"
      POSTGRES_INITDB_ARGS: "--encoding=UTF8"
      ALLOW_IP_RANGE: "0.0.0.0/0"
      POSTGRES_MULTIPLE_EXTENSIONS: "postgis,hstore,postgis_topology,postgis_raster,pgrouting,pg_trgm"
      RUN_AS_ROOT: 'true'
    restart: always
    healthcheck:
      test: ["CMD-SHELL", "PGPASSWORD=${POSTGRES_PASS} pg_isready -h localhost -U ${POSTGRES_USER}"]
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./postgres/data:/var/lib/postgresql
      - ./postgres/dbbackups:/backups
      #- ./init-postgres.sql:/docker-entrypoint-initdb.d/init.sql

  postgres-backup:
    image: "${POSTGRES_BACKUP_IMAGE}"
    deploy:
      resources:
        limits:
          memory: 4096M
    container_name: postgres-backup
    hostname: postgres-backups
    networks:
      - middleware
    environment:
      TZ: Asia/Shanghai
      DUMPPREFIX: PG_db
      POSTGRES_USER: "${POSTGRES_USER}"
      POSTGRES_PASS: "${POSTGRES_PASS}"
      POSTGRES_PORT: "5432"
      POSTGRES_HOST: "postgres"
      CRON_SCHEDULE: "0 2 * * *"
      REMOVE_BEFORE: "15"
    restart: always
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./postgres/dbbackups:/backups
    depends_on:
      postgres:
        condition: service_healthy

networks:
  middleware:
    driver: bridge

服务部署

加载Docker镜像（离线环境）

docker load -i images/nexus_3.79.0_amd64.tar.gz
docker load -i images/nexus-cleanup.tar.gz
docker load -i images/pg-v17-3.5.tar.gz
docker load -i images/pg-backup-v17-3.5.tar.gz

启动服务

docker-compose up -d

验证服务状态：

docker-compose ps

密码重置

如果需要重置管理员密码：

进入PostgreSQL容器：

docker exec -it postgres bash

执行SQL：

--- 将默认admin 密码改为 admin123
UPDATE security_user 
SET password='$shiro1$SHA-512$1024$NE+wqQq/TmjZMvfI7ENh/g==$V4yPw8T64UQ6GfJfxYq2hLsVrBY8D1v+bktfOxGdt4b/9BthpWPNUy/CBk6V9iA0nHpzYzJFWO8v/tZFtES8CA==', 
status='active' 
WHERE id='admin';

重启服务：

docker-compose restart nexus

监控与验证

服务健康检查

Nexus: curl http://localhost:18080/service/rest/v1/status
Cleanup: curl http://localhost:8000/health
PostgreSQL: docker exec postgres pg_isready -U nexus

日志检查

docker logs nexus
tail -f ./nexus/nexus-cleanup-logs/cleanup.log

性能优化建议

JVM调优：

-Xms4g -Xmx4g -XX:MaxDirectMemorySize=4g

PostgreSQL配置：
max_connections = 200
work_mem = 16MB
清理策略：
RETAIN_COUNT: "5"
SCHEDULE_TIME: "02:00"

常见问题排查

问题	解决方案
Nexus启动失败	检查JVM内存设置
PostgreSQL连接错误	验证.env文件凭据
清理服务不工作	检查NEXUS_URL配置

结论

本文详细介绍了Nexus在Docker环境中的完整部署方案，包含数据库集成、自动清理和备份功能。该方案适合生产环境使用，可根据实际需求进行调整优化。

相关资源：

Nexus官方文档
PostgreSQL最佳实践

Vim 常用配置说明文档

2025-03-05T06:30:00.000Z

当前文档为 Vim 编辑器的常用配置说明，适用于 Linux 和 Mac 环境。配置项旨在提升代码编辑体验，包括语法高亮、文件类型检测、粘贴优化等功能。配置文件通常位于 ~/.vimrc（Linux/Mac），如果文件不存在，可通过 vim ~/.vimrc 创建。

配置内容

以下是推荐的 Vim 配置项及其说明：

" 启用语法高亮
syntax on

" 启用文件类型检测
filetype on

" 启用文件类型插件和自动缩进（基于文件类型）
filetype plugin indent on

" 设置默认颜色方案
colorscheme default

" 禁用自动缩进
set noautoindent

" 禁用智能缩进
set nosmartindent

" 禁用在插入注释时自动添加注释字符
set formatoptions-=r

" 禁用在按 'o' 或 'O' 时自动添加注释
set formatoptions-=o

" 禁用自动换行，保持原始行长
set textwidth=0

" 启用粘贴模式，防止自动格式化（建议临时使用）
set paste

配置项详细说明

syntax on
- 功能: 启用语法高亮，根据文件类型显示不同颜色。
- 适用场景: 提高代码可读性，适用于编程语言（如 Python、YAML）。
- 注意: 需终端支持颜色输出（Linux/Mac 通常支持）。
filetype on
- 功能: 启用文件类型检测，基于文件扩展名或内容自动识别类型。
- 适用场景: 确保 Vim 正确加载特定文件类型的设置。
- 注意: 与 filetype plugin indent on 配合使用。
filetype plugin indent on
- 功能: 启用文件类型插件和基于类型的自动缩进。
- 适用场景: 为不同语言提供定制化缩进规则（如 Python 使用 4 空格）。
- 注意: 如果禁用缩进（见下文），可能需调整此项。
colorscheme default
- 功能: 设置默认颜色方案，控制语法高亮的颜色。
- 适用场景: 提供基础视觉效果，可替换为其他方案（如 colorscheme desert）。
- 注意: 需安装对应颜色方案文件（通常默认已包含）。
set noautoindent
- 功能: 禁用自动缩进，防止新行继承上一行的缩进。
- 适用场景: 粘贴代码时保持原格式，避免意外缩进。
set nosmartindent
- 功能: 禁用智能缩进，防止根据语法自动调整缩进。
- 适用场景: 与 noautoindent 配合，适合粘贴大段文本。
set formatoptions-=r
- 功能: 禁用在插入模式下输入注释时自动添加注释字符。
- 适用场景: 防止在多行注释中意外添加多余 * 或 #。
set formatoptions-=o
- 功能: 禁用在按 o 或 O（新行）时自动添加注释。
- 适用场景: 保持手动控制注释格式。
set textwidth=0
- 功能: 禁用自动换行，保持原始行长。
- 适用场景: 粘贴长行代码或文档时避免截断。
set paste
- 功能: 启用粘贴模式，禁用自动格式化和缩进。
- 适用场景: 粘贴外部代码时保持原样。
- 注意: 建议临时启用（:set paste），粘贴后关闭（:set nopaste），否则可能影响正常编辑。

冲突分析

以下是配置项中可能发生的冲突及解决方法：

noautoindent、nosmartindent 与 filetype plugin indent on 的冲突
- 问题: filetype plugin indent on 启用基于文件类型的自动缩进，而 noautoindent 和 nosmartindent 试图禁用所有自动缩进，导致行为不一致。
- 影响: 可能导致缩进规则失效或混乱，尤其在打开新文件时。
- 解决: 如果目标是禁用缩进（例如为粘贴优化），建议移除 filetype plugin indent on 或仅保留 filetype on 和 syntax on。
set paste 的全局影响
- 问题: set paste 是一个全局设置，会禁用缩进、自动补全等插件功能，长期启用可能干扰正常编辑。
- 影响: 影响 filetype plugin indent on 的效果，甚至可能与自定义键盘映射冲突。
- 解决: 改为临时使用，添加快捷键切换：
  nnoremap :set paste!
  粘贴时按 F2 启用，粘贴后再次按 F2 关闭。
cindent（未包含但可能相关）的潜在冲突
- 问题: 如果添加 set cindent（启用 C 风格缩进），会与 noautoindent 和 nosmartindent 冲突，因为 cindent 尝试应用缩进规则。
- 影响: 缩进行为不可预测，可能导致代码格式混乱。
- 解决: 避免同时使用 cindent 和 noautoindent/nosmartindent。如果需要 C 风格缩进，移除前两者。

优化配置建议

根据上述分析，优化后的 ~/.vimrc 配置如下，兼顾语法高亮和粘贴优化：

" 启用语法高亮和文件类型检测
syntax on
filetype on
" 禁用基于文件类型的自动缩进插件（避免与粘贴冲突）
" filetype plugin indent on

" 设置默认颜色方案
colorscheme default

" 禁用自动缩进和智能缩进（适合粘贴）
set noautoindent
set nosmartindent

" 禁用自动注释格式
set formatoptions-=r
set formatoptions-=o

" 禁用自动换行
set textwidth=0

" 粘贴模式建议临时启用，添加快捷键切换
" set paste
nnoremap  :set paste!

使用说明

保存配置: 将上述内容写入 ~/.vimrc，运行 source ~/.vimrc 应用。
测试: 打开文件（vim test.yaml），按 F2 进入粘贴模式，粘贴内容，检查格式。
自定义: 根据需求调整颜色方案或添加其他插件。

兼容性注意

Linux/Mac: 配置适用于大多数终端（需支持 ANSI 颜色）。若无颜色，检查 TERM 变量（echo $TERM 应为 xterm 或 xterm-256color）。
插件: 若使用插件（如 NERDTree），可能需额外配置，避免与 paste 冲突。
更新: 定期更新 Vim（sudo apt update && sudo apt install vim 或 brew install vim）以获取最新功能。

总结

此配置优化了语法高亮和粘贴体验，消除了 noautoindent/nosmartindent 与 filetype plugin indent on 的冲突，并建议临时管理 paste 模式。安装后测试效果，若有特定需求（如支持特定语言），可进一步扩展配置。如需更多帮助，请提供使用反馈！

二进制方式部署Kubernetes 集群

2025-02-08T08:23:25.000Z

本文详细介绍如何使用二进制方式在 Debian 系统上搭建一个生产级别的高可用 Kubernetes 集群。

部署规划

服务器清单

角色	主机名	IP地址	配置	系统
LB-1	lb1.k8s.com	192.168.171.134	2C4G	Debian 12
LB-2	lb2.k8s.com	192.168.171.135	2C4G	Debian 12
VIP	-	192.168.171.133	-	-
ETCD-1	etcd1.k8s.com	192.168.171.136	4C8G	Debian 12
ETCD-2	etcd2.k8s.com	192.168.171.137	4C8G	Debian 12
ETCD-3	etcd3.k8s.com	192.168.171.138	4C8G	Debian 12
Master-1	master1.k8s.com	192.168.171.136	4C8G	Debian 12
Master-2	master2.k8s.com	192.168.171.137	4C8G	Debian 12
Master-3	master3.k8s.com	192.168.171.138	4C8G	Debian 12
Worker-1	worker1.k8s.com	192.168.171.139	8C16G	Debian 12
Harbor	harbor.k8s.com	192.168.171.50	4C8G	Debian 12
NFS	nfs.k8s.com	192.168.171.140	4C8G	Debian 12

网络规划

节点网段: 192.168.171.0/24
Pod 网段: 10.244.0.0/16
Service 网段: 10.96.0.0/12
DNS 服务: CoreDNS

组件版本

Kubernetes: v1.27.8
Etcd: v3.5.9
Docker: 24.0.7
Containerd: 1.7.6
Calico: v3.26.1
CoreDNS: v1.10.1
Harbor: v2.9.1

系统初始化

添加软件源

# 备份原始源文件
cp /etc/apt/sources.list /etc/apt/sources.list.bak

# 清理并配置新的软件源
# 删除注释行和空行
sed -i '/^#/d; /^$/d' /etc/apt/sources.list
# 注释掉原始行
sed -i 's/^deb cdrom:\[Debian GNU\/Linux.*$/#&/' /etc/apt/sources.list
# 删除旧的安全源
sed -i '/^deb http:\/\/security.debian.org\/debian-security/d' /etc/apt/sources.list
sed -i '/^deb-src http:\/\/security.debian.org\/debian-security/d' /etc/apt/sources.list

# 添加清华源
cat > /etc/apt/sources.list << EOF
deb http://mirrors.tuna.tsinghua.edu.cn/debian/ bullseye main contrib non-free
deb http://mirrors.tuna.tsinghua.edu.cn/debian/ bullseye-updates main contrib non-free
deb http://mirrors.tuna.tsinghua.edu.cn/debian/ bullseye-backports main contrib non-free
deb http://mirrors.tuna.tsinghua.edu.cn/debian-security bullseye-security main contrib non-free

# 源码镜像（可选）
# deb-src http://mirrors.tuna.tsinghua.edu.cn/debian/ bullseye main contrib non-free
# deb-src http://mirrors.tuna.tsinghua.edu.cn/debian/ bullseye-updates main contrib non-free
# deb-src http://mirrors.tuna.tsinghua.edu.cn/debian/ bullseye-backports main contrib non-free
# deb-src http://mirrors.tuna.tsinghua.edu.cn/debian-security bullseye-security main contrib non-free
EOF

系统更新

# 更新软件包索引
apt update 

# 升级所有已安装的软件包
apt upgrade -y 

# 安装重要的系统更新（如果有的话）
apt dist-upgrade -y

基础工具安装

# 安装基础工具包
apt update
apt install -y \
    # 系统工具
    apt-transport-https \
    ca-certificates \
    vim \
    net-tools \
    sudo \
    telnet \
    ufw \
    iotop \
    rsync \
    unzip \
    iputils-ping \
    gawk \
    sed \
    cron \
    gnupg \
    locales \
    curl \
    wget \
    tree \
    htop \
    nmon \
    lsof \
    # 网络工具
    nfs-common \
    sshpass \
    software-properties-common \
    # 系统监控
    sysstat \
    # 文本处理
    jq \
    # 版本控制
    git

# 清理不需要的包
apt autoremove -y

系统语言配置

# 生成英文语言环境
locale-gen en_US.UTF-8

# 配置系统默认语言
cat > /etc/default/locale << EOF
LC_ALL=en_US.utf8
LANG=en_US.utf8
LANGUAGE=en_US.utf8
EOF

# 配置语言生成
sed -i 's/^zh_CN.UTF-8 UTF-8/#zh_CN.UTF-8 UTF-8/' /etc/locale.gen
sed -i 's/#en_US.UTF-8 UTF-8/en_US.UTF-8 UTF-8/' /etc/locale.gen

# 重新生成语言文件
locale-gen

# 配置环境变量
echo "export LANG=en_US.utf8" >> /etc/profile
echo "export LANGUAGE=en_US.utf8" >> /etc/profile
source /etc/profile

SSH远程访问配置

# 配置SSH允许root登录
sed -ri 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config

# 加强SSH安全配置
cat >> /etc/ssh/sshd_config << EOF
# SSH认证配置
# 同时启用密码和密钥认证，便于初始化后的管理
PasswordAuthentication yes
PubkeyAuthentication yes

# 设置SSH协议版本
Protocol 2

# 限制最大认证尝试次数
MaxAuthTries 3

# 禁用空密码
PermitEmptyPasswords no

# 设置登录超时时间（秒）
LoginGraceTime 60

# 启用严格模式
StrictModes yes

# 安全加固建议（等系统完全配置好后可以考虑启用）：
# 1. 禁用密码认证，只使用密钥认证
# PasswordAuthentication no
# 2. 限制允许登录的用户
# AllowUsers your-user-name
# 3. 更改默认端口
# Port 2222
EOF

# 重启SSH服务
systemctl restart ssh

# 验证配置
egrep '^PermitRootLogin' /etc/ssh/sshd_config

Shell环境优化

# 配置.bashrc
cat >> ~/.bashrc << EOF
# 配置命令别名
alias ll='ls -l'
alias la='ls -A'
alias l='ls -CF'
alias vi='vim'
alias cls='clear'

# 配置命令历史记录
HISTSIZE=5000
HISTFILESIZE=10000
HISTTIMEFORMAT="%F %T "

# 配置PS1提示符
PS1='\[\033[01;32m\]\u@\h\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]\$ '

# 启用颜色支持
export LS_OPTIONS='--color=auto'
eval "$(dircolors)"
alias ls='ls $LS_OPTIONS'
EOF

# 应用新配置
source ~/.bashrc

网络配置（可选）

# 配置静态IP
cat > /etc/network/interfaces << EOF
# This file describes the network interfaces available on your system
# and how to activate them. For more information, see interfaces(5).

source /etc/network/interfaces.d/*

# The loopback network interface
auto lo
iface lo inet loopback

# The primary network interface
auto ens32
iface ens32 inet static
    address 192.168.171.136
    netmask 255.255.255.0
    gateway 192.168.171.2
    # DNS配置
    dns-nameservers 8.8.8.8 8.8.4.4
EOF

系统优化

# 关闭swap
swapoff -a
sed -i '/swap/d' /etc/fstab

# 配置系统限制
cat > /etc/security/limits.conf << EOF
* soft nofile 65535
* hard nofile 65535
* soft nproc 65535
* hard nproc 65535
EOF

# 优化内核参数
cat > /etc/sysctl.d/99-sysctl.conf << EOF
# 系统级别的最大文件句柄数
fs.file-max = 2097152

# TCP连接参数优化
net.ipv4.tcp_max_syn_backlog = 8192
net.core.somaxconn = 32768
net.ipv4.tcp_timestamps = 1
net.ipv4.tcp_fin_timeout = 30

# 内存参数优化
vm.swappiness = 0
vm.overcommit_memory = 1
EOF

# 应用内核参数
sysctl -p

系统服务优化

# 禁用不需要的服务
systemctl stop rpcbind
systemctl disable rpcbind
apt autoremove rpcbind -y

# 配置防火墙（UFW）
ufw default deny incoming
ufw default allow outgoing
ufw allow ssh
ufw allow 80/tcp
ufw allow 443/tcp
# 根据需要添加其他端口

# 启用防火墙
ufw --force enable

完成初始化

# 同步文件系统
sync

# 重启系统使所有更改生效
reboot

自动化部署

# 创建一个初始化脚本
cat > init-debian.sh << 'EOF'
#!/bin/bash
# Debian系统初始化脚本
# 使用方法: ./init-debian.sh

# 检查是否为root用户
if [ "$(id -u)" != "0" ]; then
   echo "此脚本必须以root权限运行" 
   exit 1
fi

# 这里放入上述所有配置步骤
# ...

echo "系统初始化完成，请重启服务器"
EOF

# 添加执行权限
chmod +x init-debian.sh

# 运行脚本
./init-debian.sh

注意事项

在执行初始化操作前，建议先备份重要数据
修改网络配置时需要特别小心，错误的配置可能导致无法远程访问
防火墙规则要根据实际需求配置
建议保存一份配置文件的备份
初始化完成后要及时修改root密码和SSH配置

故障排除

如果在初始化过程中遇到问题，可以检查以下几点：

查看系统日志：journalctl -xe
检查服务状态：systemctl status <服务名>
检查网络连接：ping -c 4 8.8.8.8
验证软件源可用性：apt update

高可用负载均衡部署

环境准备

# 更新系统并安装基础工具
apt-get update
apt-get install -y \
    psmisc \
    curl \
    wget \
    net-tools \
    ipvsadm \
    ipset

# 检查网络配置
ip a

Keepalived 部署

安装 Keepalived

# 在所有负载均衡节点上安装
apt install -y keepalived

配置健康检查脚本

# 创建健康检查脚本
cat > /etc/keepalived/check_apiserver.sh << EOF
#!/bin/bash

API_URL="https://192.168.171.133:6443/healthz"
TIMEOUT=3

# 检查API服务器健康状态
if curl -k -s --connect-timeout ${TIMEOUT} ${API_URL} | grep -q "ok"; then
    exit 0
else
    exit 1
fi
EOF

# 添加执行权限
chmod +x /etc/keepalived/check_apiserver.sh

主节点配置

# 配置主节点的keepalived
cat > /etc/keepalived/keepalived.conf << EOF
! Configuration File for keepalived
global_defs {
    router_id LVS_DEVEL
    script_user root
    enable_script_security
}

# HAProxy进程检查
vrrp_script check_haproxy {
    script "/usr/bin/killall -0 haproxy"
    interval 2
    weight 2
    fall 2
    rise 1
}

# API服务器健康检查
vrrp_script check_apiserver {
    script "/etc/keepalived/check_apiserver.sh"
    interval 3
    weight -2
    fall 10
    rise 2
}

vrrp_instance VI_1 {
    state MASTER
    interface ens192                # 根据实际网卡名修改
    virtual_router_id 51
    priority 101
    advert_int 1
    
    authentication {
        auth_type PASS
        auth_pass K8SHA_KA_AUTH    # 建议修改密码
    }
    
    virtual_ipaddress {
        192.168.171.133             # VIP地址
    }
    
    # 使用单播模式（推荐）
    unicast_src_ip 192.168.171.134  # 本机IP（LB-1）
    unicast_peer {
        192.168.171.135             # 对端IP（LB-2）
    }
    
    # 配置追踪脚本
    track_script {
        check_apiserver
        check_haproxy
    }
}
EOF

备节点配置

# 配置备节点的keepalived
cat > /etc/keepalived/keepalived.conf << EOF
! Configuration File for keepalived
global_defs {
    router_id LVS_DEVEL
    script_user root
    enable_script_security
}

vrrp_script check_haproxy {
    script "/usr/bin/killall -0 haproxy"
    interval 2
    weight 2
    fall 2
    rise 1
}

vrrp_script check_apiserver {
    script "/etc/keepalived/check_apiserver.sh"
    interval 3
    weight -2
    fall 10
    rise 2
}

vrrp_instance VI_1 {
    state BACKUP
    interface ens192                # 根据实际网卡名修改
    virtual_router_id 51
    priority 100
    advert_int 1
    
    authentication {
        auth_type PASS
        auth_pass K8SHA_KA_AUTH    # 与主节点保持一致
    }
    
    virtual_ipaddress {
        192.168.171.133             # VIP地址
    }
    
    unicast_src_ip 192.168.171.135  # 本机IP（LB-2）
    unicast_peer {
        192.168.171.134             # 对端IP（LB-1）
    }
    
    track_script {
        check_apiserver
        check_haproxy
    }
}
EOF

启动服务

# 检查配置文件语法
keepalived -t -f /etc/keepalived/keepalived.conf

# 启动并设置开机自启
systemctl start keepalived
systemctl enable keepalived

# 检查服务状态
systemctl status keepalived

HAProxy 部署

安装 HAProxy

# 在所有负载均衡节点上安装
apt install -y haproxy

配置 HAProxy

# 备份原配置
cp /etc/haproxy/haproxy.cfg /etc/haproxy/haproxy.cfg.bak

# 创建新配置
cat > /etc/haproxy/haproxy.cfg << EOF
#---------------------------------------------------------------------
# Global settings
#---------------------------------------------------------------------
global
    log /dev/log local0
    log /dev/log local1 notice
    daemon
    maxconn 100000
    user haproxy
    group haproxy
    stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners

#---------------------------------------------------------------------
# Default settings
#---------------------------------------------------------------------
defaults
    log     global
    mode    tcp
    option  dontlognull
    timeout connect 5000ms
    timeout client  50000ms
    timeout server  50000ms

#---------------------------------------------------------------------
# Statistics settings
#---------------------------------------------------------------------
listen stats
    bind *:9090
    mode http
    stats enable
    stats uri /stats
    stats refresh 30s
    stats auth admin:Admin@123.com    # 访问统计页面的用户名和密码

#---------------------------------------------------------------------
# Frontend configuration for API server
#---------------------------------------------------------------------
frontend k8s-apiserver
    bind *:6443
    mode tcp
    option tcplog
    default_backend k8s-apiserver

#---------------------------------------------------------------------
# Backend configuration for API server
#---------------------------------------------------------------------
backend k8s-apiserver
    mode tcp
    option tcp-check
    balance roundrobin
    default-server inter 10s downinter 5s rise 2 fall 2 slowstart 60s maxconn 250 maxqueue 256 weight 100
    server master1 192.168.171.136:6443 check
    server master2 192.168.171.137:6443 check
    server master3 192.168.171.138:6443 check
EOF

启动服务

# 检查配置文件语法
haproxy -f /etc/haproxy/haproxy.cfg -c

# 启动并设置开机自启
systemctl start haproxy
systemctl enable haproxy

# 检查服务状态
systemctl status haproxy

验证部署

# 检查VIP是否生效
ip a | grep 192.168.1.110

# 检查HAProxy统计页面
curl -u admin:Admin@123.com http://localhost:9090/stats

# 测试API服务器访问
curl -k https://192.168.171.133:6443/healthz

# 测试故障转移
# 1. 在主节点上停止HAProxy
systemctl stop haproxy

# 2. 观察VIP是否漂移到备节点
ip a

故障排除

Keepalived 故障排查：

# 检查日志
journalctl -u keepalived -f

# 检查配置
keepalived -t -f /etc/keepalived/keepalived.conf

# 检查网络接口
ip a

HAProxy 故障排查：

# 检查日志
journalctl -u haproxy -f

# 检查配置
haproxy -f /etc/haproxy/haproxy.cfg -c

# 检查端口监听
netstat -ntlp | grep haproxy

注意事项

网络配置：
- 确保防火墙允许VRRP协议（端口112）
- 允许HAProxy监听端口（6443, 9090）
- 检查网卡名称是否正确
安全建议：
- 修改Keepalived认证密码
- 更改HAProxy统计页面的访问凭据
- 限制HAProxy统计页面的访问IP
维护建议：
- 定期检查服务状态
- 监控日志信息
- 定期测试故障转移功能
性能优化：
- 根据实际负载调整HAProxy的连接数限制
- 适当调整超时时间
- 监控系统资源使用情况

ETCD 集群部署

环境准备

主机配置

# 修改主机名
# 在 etcd1 上执行
hostnamectl set-hostname etcd1

# 在 etcd2 上执行
hostnamectl set-hostname etcd2

# 在 etcd3 上执行
hostnamectl set-hostname etcd3

# 配置 hosts 解析
cat >> /etc/hosts << EOF
192.168.171.136 etcd1
192.168.171.137 etcd2
192.168.171.138 etcd3
EOF

配置免密登录

# 在 etcd1 上执行
# 生成密钥对
ssh-keygen -t rsa -b 2048 -N "" -f ~/.ssh/id_rsa

# 分发公钥
for host in etcd1 etcd2 etcd3; do
    sshpass -p 'your_password' ssh-copy-id -o StrictHostKeyChecking=no -i ~/.ssh/id_rsa.pub "root@$host"
done

配置环境变量

# 在所有节点上执行
cat >> /etc/profile << EOF
# ETCD API 版本
export ETCDCTL_API=3
EOF

source /etc/profile

组件安装

安装 CFSSL 工具

# 在所有节点上执行
# 安装 CFSSL（下载地址：https://github.com/cloudflare/cfssl/releases）
cp cfssl_1.6.3_linux_amd64 /usr/local/bin/cfssl
cp cfssljson_1.6.3_linux_amd64 /usr/local/bin/cfssljson

# 添加执行权限
chmod +x /usr/local/bin/cfssl /usr/local/bin/cfssljson

# 验证安装
cfssl version
cfssljson -version

安装 ETCD

# 在所有节点上执行
# 设置环境变量
export ETCD_VER=v3.5.9
export DOWNLOAD_URL="https://github.com/etcd-io/etcd/releases/download"
export INSTALL_DIR="/usr/local/bin"

# 下载 ETCD 二进制文件
wget ${DOWNLOAD_URL}/${ETCD_VER}/etcd-${ETCD_VER}-linux-amd64.tar.gz

# 验证下载文件完整性
wget ${DOWNLOAD_URL}/${ETCD_VER}/etcd-${ETCD_VER}-linux-amd64.tar.gz.asc
# 如果需要验证签名
# gpg --verify etcd-${ETCD_VER}-linux-amd64.tar.gz.asc

# 解压安装包
tar -xzf etcd-${ETCD_VER}-linux-amd64.tar.gz -C /tmp/

# 复制二进制文件到安装目录
cp /tmp/etcd-${ETCD_VER}-linux-amd64/etcd* ${INSTALL_DIR}/

# 清理临时文件
rm -rf /tmp/etcd-${ETCD_VER}-linux-amd64* etcd-${ETCD_VER}-linux-amd64.tar.gz*

# 创建数据目录
mkdir -p /data/etcd

# 验证安装
${INSTALL_DIR}/etcd --version
${INSTALL_DIR}/etcdctl version

配置 TLS 证书

创建证书配置

# 在 etcd1 上执行
mkdir -p /etc/etcd/ssl
cd /etc/etcd/ssl

# 创建 CA 配置文件
cat > ca-config.json << EOF
{
    "signing": {
        "default": {
            "expiry": "876000h"
        },
        "profiles": {
            "server": {
                "expiry": "876000h",
                "usages": [
                    "signing",
                    "key encipherment",
                    "server auth",
                    "client auth"
                ]
            },
            "client": {
                "expiry": "876000h",
                "usages": [
                    "signing",
                    "key encipherment",
                    "client auth"
                ]
            },
            "peer": {
                "expiry": "876000h",
                "usages": [
                    "signing",
                    "key encipherment",
                    "server auth",
                    "client auth"
                ]
            }
        }
    }
}
EOF

# 创建 CA 证书请求文件
cat > etcd-ca-csr.json << EOF
{
    "key": {
        "algo": "rsa",
        "size": 4096
    },
    "names": [
        {
            "C": "CN",
            "L": "Beijing",
            "ST": "Beijing",
            "O": "k8s",
            "OU": "System"
        }
    ]
}
EOF

# 创建客户端证书请求文件
cat > client-csr.json << EOF
{
    "CN": "client",
    "key": {
        "algo": "rsa",
        "size": 2048
    }
}
EOF

# 创建服务端证书请求文件
cat > etcd-server-csr.json << EOF
{
    "CN": "etcd-server",
    "hosts": [
        "192.168.171.136",
        "192.168.171.137",
        "192.168.171.138",
        "127.0.0.1"
    ],
    "key": {
        "algo": "rsa",
        "size": 2048
    },
    "names": [
        {
            "C": "CN",
            "L": "Beijing",
            "O": "etcd-cluster",
            "OU": "System",
            "ST": "Beijing"
        }
    ]
}
EOF

# 创建对等证书请求文件
cat > etcd-peer-csr.json << EOF
{
    "CN": "etcd-peer",
    "hosts": [
        "192.168.171.136",
        "192.168.171.137",
        "192.168.171.138",
        "127.0.0.1"
    ],
    "key": {
        "algo": "rsa",
        "size": 2048
    },
    "names": [
        {
            "C": "CN",
            "L": "Beijing",
            "O": "etcd-cluster",
            "OU": "System",
            "ST": "Beijing"
        }
    ]
}
EOF

生成证书

# 在 etcd1 上执行
cd /etc/etcd/ssl

# 生成 CA 证书
cfssl gencert -initca etcd-ca-csr.json | cfssljson -bare etcd-ca

# 生成客户端证书
cfssl gencert \
    -ca=etcd-ca.pem \
    -ca-key=etcd-ca-key.pem \
    -config=ca-config.json \
    -profile=client client-csr.json | cfssljson -bare client

# 生成服务端证书
cfssl gencert \
    -ca=etcd-ca.pem \
    -ca-key=etcd-ca-key.pem \
    -config=ca-config.json \
    -profile=server etcd-server-csr.json | cfssljson -bare etcd-server

# 生成对等证书
cfssl gencert \
    -ca=etcd-ca.pem \
    -ca-key=etcd-ca-key.pem \
    -config=ca-config.json \
    -profile=peer etcd-peer-csr.json | cfssljson -bare etcd-peer

# 分发证书到其他节点
for host in etcd2 etcd3; do
    ssh $host "mkdir -p /etc/etcd/ssl"
    scp /etc/etcd/ssl/* $host:/etc/etcd/ssl/
done

配置 ETCD 服务

创建服务配置文件

# 在 etcd1 上执行
cat > /lib/systemd/system/etcd.service << EOF
[Unit]
Description=Etcd Server
After=network.target
After=network-online.target
Wants=network-online.target
Before=kube-apiserver.service
Documentation=https://github.com/coreos

[Service]
Type=notify
WorkingDirectory=/data/etcd/
ExecStart=/usr/local/bin/etcd \\
  --name=etcd1 \\
  --cert-file=/etc/etcd/ssl/etcd-server.pem \\
  --key-file=/etc/etcd/ssl/etcd-server-key.pem \\
  --peer-cert-file=/etc/etcd/ssl/etcd-peer.pem \\
  --peer-key-file=/etc/etcd/ssl/etcd-peer-key.pem \\
  --trusted-ca-file=/etc/etcd/ssl/etcd-ca.pem \\
  --peer-trusted-ca-file=/etc/etcd/ssl/etcd-ca.pem \\
  --initial-advertise-peer-urls=https://192.168.171.136:2380 \\
  --listen-peer-urls=https://192.168.171.136:2380 \\
  --listen-client-urls=https://192.168.171.136:2379 \\
  --advertise-client-urls=https://192.168.171.136:2379 \\
  --initial-cluster-token=etcd-cluster-0 \\
  --initial-cluster=etcd1=https://192.168.171.136:2380,etcd2=https://192.168.171.137:2380,etcd3=https://192.168.171.138:2380 \\
  --initial-cluster-state=new \\
  --data-dir=/data/etcd \\
  --snapshot-count=50000 \\
  --auto-compaction-retention=1 \\
  --max-request-bytes=10485760 \\
  --quota-backend-bytes=8589934592
Restart=always
RestartSec=15
LimitNOFILE=65536
OOMScoreAdjust=-999

[Install]
WantedBy=multi-user.target
EOF

# 分发到其他节点并修改配置
for host in etcd2 etcd3; do
    scp /lib/systemd/system/etcd.service $host:/lib/systemd/system/
    ssh $host "sed -i 's/etcd1/$host/g; s/192.168.171.136/192.168.171.$(expr 136 + $(echo $host | cut -c5))/g' /lib/systemd/system/etcd.service"
done

启动服务

# 在所有节点上执行
# 创建数据目录
mkdir -p /data/etcd

# 重载服务配置
systemctl daemon-reload

# 启动并设置开机自启
systemctl enable --now etcd

# 查看服务状态
systemctl status etcd

集群验证

配置命令别名

# 在所有节点上执行
cat >> ~/.bashrc << EOF
# ETCD 集群操作别名
alias etcdctl='etcdctl \\
    --endpoints=192.168.171.136:2379,192.168.171.137:2379,192.168.171.138:2379 \\
    --cacert=/etc/etcd/ssl/etcd-ca.pem \\
    --cert=/etc/etcd/ssl/etcd-server.pem \\
    --key=/etc/etcd/ssl/etcd-server-key.pem'
EOF

source ~/.bashrc

检查集群状态

# 查看集群成员
etcdctl member list -w table

# 查看集群健康状态
etcdctl endpoint health -w table

# 写入测试数据
etcdctl put test "hello etcd"

# 读取测试数据
etcdctl get test

# 删除测试数据
etcdctl del test

集群备份

配置自动备份

# 创建备份目录
mkdir -p /data/etcd-backups

# 创建备份脚本
cat > /data/etcd-backups/etcd-backup.sh << EOF
#!/bin/bash

# 备份配置
BACKUP_DIR="/data/etcd-backups"
DATE=\$(date +%Y%m%d%H%M%S)
LOG_FILE="\${BACKUP_DIR}/backup-\${DATE}.log"

# 备份命令
/usr/local/bin/etcdctl \\
    --endpoints=192.168.171.136:2379 \\
    --cacert=/etc/etcd/ssl/etcd-ca.pem \\
    --cert=/etc/etcd/ssl/etcd-server.pem \\
    --key=/etc/etcd/ssl/etcd-server-key.pem \\
    snapshot save \${BACKUP_DIR}/backup-\${DATE}.db > \${LOG_FILE} 2>&1

# 清理旧备份
find \${BACKUP_DIR} -name "backup-*.db" -mtime +7 -delete
find \${BACKUP_DIR} -name "backup-*.log" -mtime +7 -delete
EOF

# 添加执行权限
chmod +x /data/etcd-backups/etcd-backup.sh

# 添加定时任务
echo "0 2 * * * /data/etcd-backups/etcd-backup.sh" >> /var/spool/cron/crontabs/root

故障排除

常见问题排查

证书问题：

# 检查证书有效期
openssl x509 -in /etc/etcd/ssl/etcd-server.pem -text -noout | grep -A2 Validity

# 检查证书权限
ls -l /etc/etcd/ssl/

网络问题：

# 检查端口监听
netstat -ntlp | grep etcd

# 检查端口连通性
for port in 2379 2380; do
    for host in 192.168.171.136 192.168.171.137 192.168.171.138; do
        echo "Testing $host:$port..."
        nc -zv $host $port
    done
done

日志排查：

# 查看实时日志
journalctl -u etcd -f

# 查看错误日志
journalctl -u etcd -p err

性能优化

系统参数优化：

# 调整系统限制
cat >> /etc/security/limits.conf << EOF
* soft nofile 65536
* hard nofile 65536
EOF

# 调整内核参数
cat >> /etc/sysctl.conf << EOF
net.ipv4.ip_local_port_range = 1024 65000
net.core.somaxconn = 32768
net.core.netdev_max_backlog = 16384
net.ipv4.tcp_max_syn_backlog = 8096
net.ipv4.tcp_tw_reuse = 1
EOF

sysctl -p

ETCD 参数优化：

适当调整 --snapshot-count
根据实际情况调整 --quota-backend-bytes
配置合适的 --auto-compaction-retention

注意事项

安全建议：
- 定期更新证书
- 限制访问权限
- 配置防火墙规则
维护建议：
- 定期备份数据
- 监控集群状态
- 及时清理历史数据
性能建议：
- 使用 SSD 存储
- 独立的磁盘空间
- 足够的内存配置
高可用建议：
- 节点跨机架部署
- 配置监控告警
- 定期进行故障演练

Harbor 私有镜像仓库部署

环境准备

DNS 配置

# 配置本地解析
cat >> /etc/hosts << EOF
192.168.171.50 harbor.k8s.com
EOF

# 修改主机名
hostnamectl set-hostname harbor.k8s.com

存储配置

# 安装 LVM 工具
apt-get update
apt-get install -y lvm2

# 创建物理卷
pvcreate /dev/sdb1

# 创建卷组
vgcreate data_vg /dev/sdb1

# 创建逻辑卷
lvcreate -l +100%FREE -n data_lv data_vg

# 格式化逻辑卷
mkfs.ext4 /dev/data_vg/data_lv

# 清理旧配置
#sed -i '/\/data/d' /etc/fstab

# 配置挂载
echo "/dev/data_vg/data_lv /data ext4 defaults 0 0" >> /etc/fstab
mkdir -p /data
mount -a

# 验证挂载
df -h /data

Docker 环境配置

安装 Docker

# 安装依赖包
apt-get update
apt-get install -y \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

# 添加 Docker 官方 GPG 密钥
curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 添加 Docker 软件源
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker
apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io

配置 Docker

# 创建 Docker 配置目录
mkdir -p /etc/docker

# 配置 Docker daemon
cat > /etc/docker/daemon.json << 'EOF'
{
  "registry-mirrors": ["https://ustc-edu-cn.mirror.aliyuncs.com"],
  "debug": false,
  "ip-forward": true,
  "ipv6": false,
  "live-restore": true,
  "log-driver": "json-file",
  "log-level": "warn",
  "log-opts": {
    "max-size": "100m",
    "max-file": "2"
  },
  "selinux-enabled": false,
  "experimental": true,
  "storage-driver": "overlay2",
  "metrics-addr": "0.0.0.0:9323",
  "data-root": "/data/docker",
  "default-ulimits": {
    "nofile": {
      "Name": "nofile",
      "Hard": 65536,
      "Soft": 65536
    }
  },
  "exec-opts": ["native.cgroupdriver=systemd"]
}
EOF

# 重启 Docker 服务
systemctl daemon-reload
systemctl restart docker
systemctl enable docker

安装 Docker Compose

# 下载 Docker Compose
COMPOSE_VERSION=$(curl -s https://api.github.com/repos/docker/compose/releases/latest | grep 'tag_name' | cut -d\" -f4)
curl -L "https://github.com/docker/compose/releases/download/${COMPOSE_VERSION}/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# 添加执行权限
chmod +x /usr/local/bin/docker-compose

# 验证安装
docker-compose version

Harbor 部署

下载 Harbor

# 设置 Harbor 版本
export HARBOR_VERSION="v2.9.1"

# 下载 Harbor 安装包
wget https://github.com/goharbor/harbor/releases/download/${HARBOR_VERSION}/harbor-offline-installer-${HARBOR_VERSION}.tgz

# 解压安装包
tar xzvf harbor-offline-installer-${HARBOR_VERSION}.tgz -C /data

配置 Harbor

# 创建配置文件
cp /data/harbor/harbor.yml.tmpl /data/harbor/harbor.yml

# 修改配置文件
cat > /data/harbor/harbor.yml << EOF
hostname: harbor.k8s.com
https:
  certificate: /data/harbor/ssl/harbor.k8s.com.crt
  private_key: /data/harbor/ssl/harbor.k8s.com.key
harbor_admin_password: Harbor@123.com
data_volume: /data/harbor/harbor-data
log:
  location: /data/harbor/harbor-logs
  level: info
  local:
    rotate_count: 50
    rotate_size: 200M
database:
  password: root123
  max_idle_conns: 100
  max_open_conns: 900
storage_service:
  ca_bundle: /etc/ssl/certs/ca-certificates.crt
  redirect:
    disabled: false
  cache:
    enabled: true
    expire_hours: 24
trivy:
  enabled: true
  ignore_unfixed: false
  skip_update: false
  offline_scan: false
EOF

配置 TLS 证书

# 创建证书目录
mkdir -p /data/harbor/ssl
cd /data/harbor/ssl

# 生成 CA 私钥和证书
openssl genrsa -out ca.key 4096
openssl req -x509 -new -nodes -sha512 -days 3650 \
    -subj "/C=CN/ST=Beijing/L=Beijing/O=example/OU=Personal/CN=harbor.k8s.com" \
    -key ca.key \
    -out ca.crt

# 生成服务器私钥
openssl genrsa -out harbor.k8s.com.key 4096

# 生成证书签名请求
openssl req -sha512 -new \
    -subj "/C=CN/ST=Beijing/L=Beijing/O=example/OU=Personal/CN=harbor.k8s.com" \
    -key harbor.k8s.com.key \
    -out harbor.k8s.com.csr

# 配置证书扩展信息
cat > v3.ext << EOF
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage=digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
extendedKeyUsage=serverAuth
subjectAltName=@alt_names

[alt_names]
DNS.1=harbor.k8s.com
DNS.2=harbor
IP.1=192.168.171.50
EOF

# 生成服务器证书
openssl x509 -req -sha512 -days 3650 \
    -extfile v3.ext \
    -CA ca.crt -CAkey ca.key -CAcreateserial \
    -in harbor.k8s.com.csr \
    -out harbor.k8s.com.crt

# 生成客户端证书
openssl x509 -inform PEM -in harbor.k8s.com.crt -out harbor.k8s.com.cert

# 配置 Docker 证书
mkdir -p /etc/docker/certs.d/harbor.k8s.com/
cp ca.crt /etc/docker/certs.d/harbor.k8s.com/
cp harbor.k8s.com.cert /etc/docker/certs.d/harbor.k8s.com/
cp harbor.k8s.com.key /etc/docker/certs.d/harbor.k8s.com/

安装 Harbor

cd /data/harbor

# 安装 Harbor
./prepare --with-trivy
./install.sh --with-trivy

# 验证安装
docker ps

# 测试登录
docker login -u admin -p 'Harbor@123.com' harbor.k8s.com

客户端配置

配置 Docker 客户端

# 复制证书到客户端
mkdir -p /etc/docker/certs.d/harbor.k8s.com/
scp harbor-server:/etc/docker/certs.d/harbor.k8s.com/* /etc/docker/certs.d/harbor.k8s.com/

# 重启 Docker 服务
systemctl restart docker

# 测试登录
docker login harbor.k8s.com

维护管理

备份配置

# 创建备份脚本
cat > /data/harbor/backup.sh << 'EOF'
#!/bin/bash

BACKUP_DIR="/data/harbor/backups"
DATE=$(date +%Y%m%d_%H%M%S)

# 创建备份目录
mkdir -p ${BACKUP_DIR}/${DATE}

# 停止服务
cd /data/harbor
docker-compose down

# 备份数据
tar czf ${BACKUP_DIR}/${DATE}/harbor_data.tar.gz /data/harbor/harbor-data
tar czf ${BACKUP_DIR}/${DATE}/harbor_config.tar.gz /data/harbor/harbor.yml /data/harbor/ssl

# 启动服务
docker-compose up -d

# 清理旧备份
find ${BACKUP_DIR} -type d -mtime +7 -exec rm -rf {} \;

# 记录备份日志
echo "Backup completed at $(date '+%Y-%m-%d %H:%M:%S')" >> /data/harbor/harbor-logs/backup.log
EOF

# 添加执行权限
chmod +x /data/harbor/backup.sh

# 创建日志目录
mkdir -p /data/harbor/harbor-logs

# 添加到 root 用户的定时任务
(crontab -l 2>/dev/null; echo "0 2 * * * /data/harbor/backup.sh > /dev/null 2>&1") | crontab -

# 验证定时任务
crontab -l

监控配置

# 创建监控脚本
cat > /data/harbor/monitor.sh << 'EOF'
#!/bin/bash

# 检查 Harbor 服务状态
check_harbor() {
    local containers=$(docker ps --format '{{.Names}}' | grep '^harbor-')
    if [ $(echo "$containers" | wc -l) -lt 7 ]; then
        echo "Warning: Some Harbor containers are not running"
        return 1
    fi
    return 0
}

# 检查存储空间
check_storage() {
    local usage=$(df -h /data | awk 'NR==2 {print $5}' | sed 's/%//')
    if [ $usage -gt 80 ]; then
        echo "Warning: Storage usage is above 80%"
        return 1
    fi
    return 0
}

# 主检查逻辑
main() {
    check_harbor || echo "Harbor service check failed"
    check_storage || echo "Storage check failed"
}

main
EOF

chmod +x /data/harbor/monitor.sh

# 添加到 crontab
echo "*/5 * * * * /data/harbor/monitor.sh >> /data/harbor/harbor-logs/monitor.log 2>&1" >> /var/spool/cron/crontabs/root

故障排除

常见问题

证书问题：

# 检查证书有效期
openssl x509 -in /data/harbor/ssl/harbor.k8s.com.crt -text -noout | grep -A2 Validity

# 检查证书配置
ls -l /etc/docker/certs.d/harbor.k8s.com/

存储问题：

# 检查存储空间
df -h /data

# 检查 Docker 存储
docker system df

服务问题：

# 检查服务状态
cd /data/harbor
docker-compose ps

# 查看服务日志
docker-compose logs

性能优化

系统优化：

# 调整系统限制
cat >> /etc/security/limits.conf << EOF
* soft nofile 65535
* hard nofile 65535
EOF

# 调整内核参数
cat >> /etc/sysctl.conf << EOF
net.ipv4.ip_local_port_range = 1024 65000
net.core.somaxconn = 32768
fs.file-max = 1000000
EOF

sysctl -p

Docker 优化：

配置合适的日志轮转策略
使用高性能存储
定期清理未使用的镜像和容器

注意事项

安全建议：
- 及时更新系统和组件
- 定期轮换密码和证书
- 限制访问权限
- 配置防火墙规则
维护建议：
- 定期备份数据
- 监控系统资源
- 及时清理垃圾数据
- 保持日志分析
高可用建议：
- 配置负载均衡
- 实现数据备份
- 监控告警配置
- 故障恢复演练

Kubernetes 集群环境部署

环境准备

主机配置

# 配置主机名
# Master 节点
hostnamectl set-hostname master1.k8s.com
hostnamectl set-hostname master2.k8s.com
hostnamectl set-hostname master3.k8s.com

# Worker 节点
hostnamectl set-hostname worker1.k8s.com

# 配置 DNS 解析
cat >> /etc/hosts << EOF
192.168.171.136 etcd1
192.168.171.50  harbor harbor.k8s.com
192.168.171.136 master1 master1.k8s.com
192.168.171.137 master2 master2.k8s.com
192.168.171.138 master3 master3.k8s.com
192.168.171.139 worker1 worker1.k8s.com
EOF

# 配置免密登录
ssh-keygen -t rsa -b 2048 -N "" -f ~/.ssh/id_rsa

# 分发公钥
for host in harbor etcd1 master{1..3} worker1; do
    sshpass -p 'your_password' ssh-copy-id -o StrictHostKeyChecking=no root@${host}
done

# 分发hosts文件
for host in master{2..3} worker1; do
    scp /etc/hosts ${host}:/etc/
done

系统配置

# 在所有节点上执行
# 关闭 swap
swapoff -a
sed -i '/swap/d' /etc/fstab

# 加载内核模块
cat > /etc/modules-load.d/k8s.conf << EOF
overlay
br_netfilter
ip_vs
ip_vs_rr
ip_vs_wrr
ip_vs_sh
nf_conntrack
EOF

# 加载模块
modprobe overlay
modprobe br_netfilter
modprobe ip_vs
modprobe ip_vs_rr
modprobe ip_vs_wrr
modprobe ip_vs_sh
modprobe nf_conntrack

# 更新内核设置
cat > /etc/sysctl.d/k8s.conf << EOF
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
vm.swappiness                       = 0
fs.file-max                         = 1000000
net.ipv4.ip_local_port_range       = 1024 65000
net.ipv4.tcp_tw_reuse              = 1
net.ipv4.tcp_fin_timeout           = 30
net.core.somaxconn                 = 32768
EOF

sysctl --system

组件安装

容器运行时

# 安装 containerd
export CONTAINERD_VERSION="1.7.6"
wget https://github.com/containerd/containerd/releases/download/v${CONTAINERD_VERSION}/containerd-${CONTAINERD_VERSION}-linux-amd64.tar.gz
tar Cxzvf /usr/local containerd-${CONTAINERD_VERSION}-linux-amd64.tar.gz

# 配置 containerd 服务
wget https://raw.githubusercontent.com/containerd/containerd/main/containerd.service -O /usr/local/lib/systemd/system/containerd.service

# 生成默认配置
mkdir -p /etc/containerd
containerd config default > /etc/containerd/config.toml

# 修改配置
sed -i 's|/var/lib/containerd|/data/containerd|g' /etc/containerd/config.toml
sed -i 's|k8s.gcr.io/pause:3.6|registry.aliyuncs.com/google_containers/pause:3.9|g' /etc/containerd/config.toml

# 添加镜像仓库配置
cat >> /etc/containerd/config.toml << EOF
      [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
        endpoint = ["https://docker.mirrors.ustc.edu.cn","http://hub-mirror.c.163.com"]
      [plugins."io.containerd.grpc.v1.cri".registry.mirrors."gcr.io"]
        endpoint = ["https://gcr.mirrors.ustc.edu.cn"]
      [plugins."io.containerd.grpc.v1.cri".registry.mirrors."k8s.gcr.io"]
        endpoint = ["https://gcr.mirrors.ustc.edu.cn/google-containers/"]
      [plugins."io.containerd.grpc.v1.cri".registry.mirrors."quay.io"]
        endpoint = ["https://quay.mirrors.ustc.edu.cn"]
      [plugins."io.containerd.grpc.v1.cri".registry.mirrors."harbor.k8s.com"]
        endpoint = ["https://harbor.k8s.com"]
EOF

# 启动服务
systemctl daemon-reload
systemctl enable --now containerd

安装 CNI 插件

# 下载并安装 CNI 插件
CNI_VERSION="v1.2.0"
wget https://github.com/containernetworking/plugins/releases/download/${CNI_VERSION}/cni-plugins-linux-amd64-${CNI_VERSION}.tgz
mkdir -p /opt/cni/bin
tar Cxzvf /opt/cni/bin cni-plugins-linux-amd64-${CNI_VERSION}.tgz

安装 nerdctl

# 下载并安装 nerdctl
NERDCTL_VERSION="1.6.2"
wget https://github.com/containerd/nerdctl/releases/download/v${NERDCTL_VERSION}/nerdctl-full-${NERDCTL_VERSION}-linux-amd64.tar.gz
tar Cxzvf /usr/local nerdctl-full-${NERDCTL_VERSION}-linux-amd64.tar.gz

# 配置别名
cat >> /etc/profile << EOF
alias docker='nerdctl --namespace k8s.io'
alias docker-compose='nerdctl compose'
alias crictl='crictl --runtime-endpoint unix:///var/run/containerd/containerd.sock'
EOF

source /etc/profile

# 配置 nerdctl
mkdir -p /etc/nerdctl
cat > /etc/nerdctl/nerdctl.toml << EOF
namespace = "k8s.io"
insecure_registry = true
cni_path = "/opt/cni/bin/"
EOF

安装 Kubernetes 组件

# 添加 Kubernetes 软件源
curl https://mirrors.aliyun.com/kubernetes/apt/doc/apt-key.gpg | apt-key add -
cat > /etc/apt/sources.list.d/kubernetes.list << EOF
deb https://mirrors.aliyun.com/kubernetes/apt/ kubernetes-xenial main
EOF

# 安装指定版本
export KUBE_VERSION="1.27.8"
apt update
apt install -y kubelet=${KUBE_VERSION}-00 kubeadm=${KUBE_VERSION}-00 kubectl=${KUBE_VERSION}-00

# 锁定版本
apt-mark hold kubelet kubeadm kubectl

# 启用自动补全
apt install -y bash-completion
echo 'source <(kubectl completion bash)' >> ~/.bashrc
source ~/.bashrc

# 预拉取镜像
kubeadm config images pull --kubernetes-version=v${KUBE_VERSION} \
    --image-repository='registry.aliyuncs.com/google_containers'

证书配置

# 创建证书目录
mkdir -p /etc/kubernetes/pki/etcd

# 复制 ETCD 证书
scp etcd1:/etc/etcd/ssl/etcd-ca.pem /etc/kubernetes/pki/etcd/
scp etcd1:/etc/etcd/ssl/client.pem /etc/kubernetes/pki/apiserver-etcd-client.pem
scp etcd1:/etc/etcd/ssl/client-key.pem /etc/kubernetes/pki/apiserver-etcd-client-key.pem

# 复制 Harbor 证书
mkdir -p /etc/tls/harbor/
scp -r harbor:/etc/docker/certs.d/harbor.k8s.com /etc/tls/harbor/

# 更新系统证书
cp /etc/tls/harbor/harbor.k8s.com/ca.crt /usr/local/share/ca-certificates/
cp /etc/tls/harbor/harbor.k8s.com/harbor.k8s.com.cert /usr/local/share/ca-certificates/
update-ca-certificates

系统优化

性能调优

# 调整系统限制
cat >> /etc/security/limits.conf << EOF
* soft nofile 65536
* hard nofile 65536
* soft nproc 65536
* hard nproc 65536
EOF

# 调整内核参数
cat >> /etc/sysctl.conf << EOF
net.ipv4.tcp_max_syn_backlog = 8192
net.core.somaxconn = 32768
net.ipv4.tcp_timestamps = 1
net.ipv4.tcp_fin_timeout = 30
EOF

sysctl -p

安全加固

# 禁用不必要的服务
systemctl stop apparmor
systemctl disable apparmor

# 配置防火墙规则
ufw allow 6443/tcp  # Kubernetes API
ufw allow 2379/tcp  # etcd client API
ufw allow 2380/tcp  # etcd peer API
ufw allow 10250/tcp # Kubelet API
ufw allow 10251/tcp # kube-scheduler
ufw allow 10252/tcp # kube-controller-manager

验证部署

# 验证模块加载
lsmod | grep -e br_netfilter -e overlay -e ip_vs

# 验证端口
netstat -ntlp | grep -e containerd -e kubelet

# 验证镜像
crictl images

# 验证 Kubernetes 组件
systemctl status kubelet
kubectl version --client
kubeadm version

注意事项

网络要求：
- 节点间网络互通
- 可访问外网（用于下载组件）
- 防火墙开放必要端口
安全建议：
- 及时更新系统和组件
- 使用最新的稳定版本
- 配置适当的安全策略
维护建议：
- 定期检查系统资源
- 监控关键组件状态
- 保持日志分析和审计

Kubernetes 集群部署

初始化配置

创建集群配置文件

# 在 master1 节点上执行
# 生成默认配置
kubeadm config print init-defaults > kubeadm-init.yaml

# 修改配置文件
cat > kubeadm-init.yaml << EOF
apiVersion: kubeadm.k8s.io/v1beta3
kind: InitConfiguration
localAPIEndpoint:
  advertiseAddress: 192.168.171.136
  bindPort: 6443
nodeRegistration:
  criSocket: unix:///var/run/containerd/containerd.sock
  taints:
    - effect: NoSchedule
      key: node-role.kubernetes.io/control-plane
---
apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
certificatesDir: /etc/kubernetes/pki
clusterName: kubernetes
controllerManager: {}
dns:
  type: CoreDNS
etcd:
  external:
    endpoints:
      - https://192.168.171.136:2379
      - https://192.168.171.137:2379
      - https://192.168.171.138:2379
    caFile: /etc/kubernetes/pki/etcd/etcd-ca.pem
    certFile: /etc/kubernetes/pki/apiserver-etcd-client.pem
    keyFile: /etc/kubernetes/pki/apiserver-etcd-client-key.pem
kubernetesVersion: 1.27.8
imageRepository: registry.aliyuncs.com/google_containers
networking:
  serviceSubnet: 10.96.0.0/12
  podSubnet: 10.244.0.0/16
---
apiVersion: kubeproxy.config.k8s.io/v1alpha1
kind: KubeProxyConfiguration
mode: ipvs
EOF

集群初始化

初始化主节点

# 在 master1 节点上执行
# 初始化集群
kubeadm init --config=kubeadm-init.yaml --upload-certs

# 配置 kubectl
mkdir -p $HOME/.kube
cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
chown $(id -u):$(id -g) $HOME/.kube/config

# 配置环境变量
echo "export KUBECONFIG=/etc/kubernetes/admin.conf" >> /etc/profile
source /etc/profile

添加节点

# 在其他 master 节点上执行
# 加入控制平面节点
kubeadm join 192.168.171.136:6443 --token  \
    --discovery-token-ca-cert-hash sha256: \
    --control-plane --certificate-key  \
    --cri-socket=unix:///var/run/containerd/containerd.sock

# 在 worker 节点上执行
# 加入工作节点
kubeadm join 192.168.171.136:6443 --token  \
    --discovery-token-ca-cert-hash sha256: \
    --cri-socket=unix:///var/run/containerd/containerd.sock

# 配置环境变量
echo "export KUBECONFIG=/etc/kubernetes/admin.conf" >> /etc/profile
source /etc/profile

节点标签管理

# 添加 worker 标签
kubectl label nodes worker1.k8s.com node-role.kubernetes.io/worker=

# 添加污点
kubectl taint nodes master1.k8s.com node-role.kubernetes.io/control-plane=:NoSchedule
kubectl taint nodes master2.k8s.com node-role.kubernetes.io/control-plane=:NoSchedule
kubectl taint nodes master3.k8s.com node-role.kubernetes.io/control-plane=:NoSchedule

网络配置

安装 Calico

# 添加 Helm 仓库
helm repo add projectcalico https://docs.tigera.io/calico/charts
helm repo update

# 创建配置文件
cat > calico-values.yaml << EOF
installation:
  cni:
    type: Calico
  ipPools:
  - cidr: 10.244.0.0/16
    encapsulation: IPIP
    natOutgoing: true
    nodeSelector: all()
  registry: docker.io
EOF

# 安装 Calico
helm install calico projectcalico/tigera-operator -f calico-values.yaml

CoreDNS 配置

# 配置 CoreDNS
kubectl -n kube-system get cm coredns -o yaml > coredns-cm.yaml

# 修改配置
cat > coredns-cm.yaml << EOF
apiVersion: v1
data:
  Corefile: |
    .:53 {
        errors
        health {
           lameduck 5s
        }
        hosts {
          192.168.171.50 harbor.k8s.com
          fallthrough
        }
        ready
        kubernetes cluster.local in-addr.arpa ip6.arpa {
           pods insecure
           fallthrough in-addr.arpa ip6.arpa
           ttl 30
        }
        prometheus :9153
        forward . /etc/resolv.conf {
           max_concurrent 1000
        }
        cache 30
        loop
        reload
        loadbalance
    }
EOF

# 应用配置
kubectl apply -f coredns-cm.yaml

# 重启 CoreDNS
kubectl -n kube-system delete pod -l k8s-app=kube-dns

组件配置

暴露组件端口

# 在所有 master 节点上执行
# 修改 kube-scheduler 配置
sed -i 's/- --bind-address=127.0.0.1/- --bind-address=0.0.0.0/' /etc/kubernetes/manifests/kube-scheduler.yaml

# 修改 kube-controller-manager 配置
sed -i 's/- --bind-address=127.0.0.1/- --bind-address=0.0.0.0/' /etc/kubernetes/manifests/kube-controller-manager.yaml

集群验证

# 验证集群状态
kubectl get nodes
kubectl get pods -A
kubectl cluster-info
kubectl get componentstatuses

# 验证网络
kubectl run test-nginx --image=nginx
kubectl expose pod test-nginx --port=80 --type=NodePort
curl http://:

维护操作

证书更新

# 查看证书过期时间
kubeadm certs check-expiration

# 更新证书
kubeadm certs renew all

集群升级

# 升级 kubeadm
apt-mark unhold kubeadm
apt-get update
apt-get install -y kubeadm=
apt-mark hold kubeadm

# 升级控制平面
kubeadm upgrade plan
kubeadm upgrade apply v

# 升级 kubelet 和 kubectl
apt-mark unhold kubelet kubectl
apt-get install -y kubelet= kubectl=
apt-mark hold kubelet kubectl
systemctl restart kubelet

故障处理

重置节点

# 清理节点
kubeadm reset
iptables -F && iptables -X
iptables -t nat -F && iptables -t nat -X
iptables -t mangle -F && iptables -t mangle -X
ipvsadm --clear
rm -rf /etc/kubernetes/ /var/lib/kubelet/ /var/lib/etcd/

常见问题排查

# 查看组件日志
journalctl -xeu kubelet
kubectl logs -n kube-system 

# 检查网络
kubectl exec -it  -- ping 
kubectl get endpoints

注意事项

高可用配置：
- 至少部署三个 master 节点
- 使用负载均衡器
- 配置外部 etcd 集群
安全建议：
- 及时更新组件版本
- 配置网络策略
- 使用 RBAC 控制访问
- 定期备份 etcd 数据
性能优化：
- 合理配置资源限制
- 优化网络配置
- 监控系统性能
运维建议：
- 实施监控告警
- 定期进行备份
- 制定故障恢复预案
- 保持文档更新

NFS StorageClass 部署

存储服务器配置

安装 NFS 服务

# 安装 NFS 服务器
apt-get update
apt-get install -y nfs-kernel-server

# 创建共享目录
mkdir -p /data/ifs/kubernetes
chown -R nobody:nogroup /data/ifs/kubernetes

# 配置共享权限
cat >> /etc/exports << EOF
/data/ifs/kubernetes 192.168.171.0/24(no_root_squash,rw,sync,no_subtree_check)
EOF

# 启动服务
systemctl enable --now nfs-kernel-server

# 验证配置
exportfs -av

配置防火墙

# 允许 NFS 相关端口
ufw allow 2049/tcp  # NFS
ufw allow 111/tcp   # portmapper
ufw allow 111/udp
ufw allow 32765:32768/tcp  # NFS 动态端口
ufw allow 32765:32768/udp

客户端配置

安装 NFS 客户端

# 在所有 Kubernetes 节点上执行
apt-get update
apt-get install -y nfs-common

# 配置 NFS 服务器解析
echo "192.168.171.140 nfs.k8s.com" >> /etc/hosts

# 验证 NFS 挂载
showmount -e nfs.k8s.com

StorageClass 部署

安装 NFS Provisioner

# 创建命名空间
kubectl create namespace nfs-provisioner

# 创建 ServiceAccount
cat > rbac.yaml << EOF
apiVersion: v1
kind: ServiceAccount
metadata:
  name: nfs-client-provisioner
  namespace: nfs-provisioner
---
kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: nfs-client-provisioner-runner
rules:
  - apiGroups: [""]
    resources: ["nodes"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["persistentvolumes"]
    verbs: ["get", "list", "watch", "create", "delete"]
  - apiGroups: [""]
    resources: ["persistentvolumeclaims"]
    verbs: ["get", "list", "watch", "update"]
  - apiGroups: ["storage.k8s.io"]
    resources: ["storageclasses"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["events"]
    verbs: ["create", "update", "patch"]
EOF

kubectl apply -f rbac.yaml

# 创建 Deployment
cat > deployment.yaml << EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nfs-client-provisioner
  namespace: nfs-provisioner
spec:
  replicas: 1
  strategy:
    type: Recreate
  selector:
    matchLabels:
      app: nfs-client-provisioner
  template:
    metadata:
      labels:
        app: nfs-client-provisioner
    spec:
      serviceAccountName: nfs-client-provisioner
      containers:
        - name: nfs-client-provisioner
          image: registry.aliyuncs.com/google_containers/sig-storage/nfs-subdir-external-provisioner:v4.0.2
          volumeMounts:
            - name: nfs-client-root
              mountPath: /persistentvolumes
          env:
            - name: PROVISIONER_NAME
              value: k8s-sigs.io/nfs-subdir-external-provisioner
            - name: NFS_SERVER
              value: nfs.k8s.com
            - name: NFS_PATH
              value: /data/ifs/kubernetes
      volumes:
        - name: nfs-client-root
          nfs:
            server: nfs.k8s.com
            path: /data/ifs/kubernetes
EOF

kubectl apply -f deployment.yaml

# 创建 StorageClass
cat > storageclass.yaml << EOF
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: nfs-client
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: k8s-sigs.io/nfs-subdir-external-provisioner
parameters:
  archiveOnDelete: "false"
EOF

kubectl apply -f storageclass.yaml

验证部署

# 创建测试 PVC
cat > test-claim.yaml << EOF
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: test-claim
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 1Mi
EOF

kubectl apply -f test-claim.yaml

# 创建测试 Pod
cat > test-pod.yaml << EOF
apiVersion: v1
kind: Pod
metadata:
  name: test-pod
spec:
  containers:
    - name: test-pod
      image: busybox
      command:
        - "/bin/sh"
      args:
        - "-c"
        - "touch /mnt/SUCCESS && exit 0 || exit 1"
      volumeMounts:
        - name: nfs-pvc
          mountPath: "/mnt"
  restartPolicy: "Never"
  volumes:
    - name: nfs-pvc
      persistentVolumeClaim:
        claimName: test-claim
EOF

kubectl apply -f test-pod.yaml

监控配置

# 创建监控脚本
cat > /usr/local/bin/monitor-nfs.sh << 'EOF'
#!/bin/bash

# 检查 NFS 服务状态
check_nfs_service() {
    if ! systemctl is-active --quiet nfs-kernel-server; then
        echo "NFS service is not running"
        return 1
    fi
    return 0
}

# 检查存储空间
check_storage() {
    local usage=$(df -h /data/ifs/kubernetes | awk 'NR==2 {print $5}' | sed 's/%//')
    if [ $usage -gt 80 ]; then
        echo "Storage usage is above 80%"
        return 1
    fi
    return 0
}

# 检查 NFS 挂载点
check_mounts() {
    if ! mountpoint -q /data/ifs/kubernetes; then
        echo "NFS directory is not mounted"
        return 1
    fi
    return 0
}

# 主检查逻辑
main() {
    check_nfs_service || echo "NFS service check failed"
    check_storage || echo "Storage check failed"
    check_mounts || echo "Mount check failed"
}

main
EOF

chmod +x /usr/local/bin/monitor-nfs.sh

# 添加到 crontab
(crontab -l 2>/dev/null; echo "*/5 * * * * /usr/local/bin/monitor-nfs.sh >> /var/log/nfs-monitor.log 2>&1") | crontab -

注意事项

性能优化：
- 使用 SSD 存储
- 调整 NFS 缓存参数
- 配置合适的网络带宽
安全建议：
- 限制 NFS 访问IP
- 配置防火墙规则
- 定期更新系统
维护建议：
- 定期备份数据
- 监控存储使用量
- 及时清理无用数据
高可用建议：
- 配置 NFS 服务器集群
- 使用网络存储备份
- 配置自动故障转移

Maven 私有仓库使用规范

2025-02-07T08:17:25.000Z

Maven私有仓库(Nexus)是企业进行依赖管理的重要基础设施。然而在实际使用中,团队常常因配置混乱导致跨团队协作困难,依赖问题频发。比如本地构建或打包时出现异常,公有云仓库与私有仓库混用导致缓存失效,这些都增加了不必要的沟通与排查成本。为此,我们需要统一规范配置,明确依赖管理流程,包括拉取依赖、上传私有包等标准操作方式。通过规范化管理,不仅可以方便项目交接和新人上手,还能充分发挥私有仓库的缓存加速作用,提升团队整体开发效率。本文将详细介绍Maven私有仓库的最佳实践,帮助团队建立起高效的依赖管理体系。

修改Maven配置

修改settings配置

私有仓库Nexus信息示例:

Nexus服务地址: http://nexus.your-company.com:8081/
开发者账号: developer/your-password
Maven公共仓库地址: http://nexus.your-company.com:8081/repository/maven-public/
Maven私有包-稳定版本-上传地址: http://nexus.your-company.com:8081/repository/maven-releases/
Maven私有包-开发版本-上传地址: http://nexus.your-company.com:8081/repository/maven-snapshots/

需要修改settings.xml配置文件,使其完全通过企业内网Nexus访问依赖,而不是直接访问公网仓库。这样可以:

首次使用时,Nexus会从公网拉取并缓存依赖
后续使用时直接从Nexus获取缓存的依赖,加快构建速度
统一管理团队使用的依赖版本

settings.xml示例配置:

<settings>
  <mirrors>
    <mirror>
      <id>nexusid>
      <mirrorOf>*mirrorOf>
      <url>http://nexus.your-company.com:8081/repository/maven-public/url>
    mirror>
  mirrors>

  <servers>
    <server>
      <id>maven-releasesid>
      <username>${NEXUS_USERNAME}username>
      <password>${NEXUS_PASSWORD}password>
    server>
    <server>
      <id>maven-snapshotsid>
      <username>${NEXUS_USERNAME}username>
      <password>${NEXUS_PASSWORD}password>
    server>
  servers>
settings>

公网包支持

如果在使用内网Maven公共仓库时无法拉取某些公网依赖包:

可以联系Nexus管理员添加所需的公网仓库源
默认应该已配置了主流公共仓库(如Maven中央仓库、阿里云Maven仓库等)
如需添加其他冷门仓库源,请提供仓库地址给管理员统一配置

内网私有包支持

如果无法拉取内网私有包:

优先联系包的开发团队,确认是否已上传到私有仓库
如未上传,请开发团队先完成上传

上传私有包到releases仓库:

通过Nexus Web UI上传
选择 hosted 类型的仓库才能上传成功

批量上传包到私库

对于需要批量上传的场景:

可以使用maven-deploy插件上传:

mvn deploy:deploy-file \
    -Durl=http://nexus.your-company.com:8081/repository/maven-snapshots \
    -DrepositoryId=snapshots \
    -Dfile=your-artifact.jar \
    -DgroupId=com.company \
    -DartifactId=project \
    -Dversion=1.0-SNAPSHOT \
    -Dpackaging=jar

也可以使用批量上传工具,如阿里云云效的 migrate-local-repo-tool.jar

修改父POM配置

在项目顶级pom.xml中配置仓库信息:

<project>
    <repositories>
        <repository>
            <id>maven-publicid>
            <name>maven-publicname>
            <url>http://nexus.your-company.com:8081/repository/maven-public/url>
            <releases>
                <enabled>trueenabled>
            releases>
            <snapshots>
                <enabled>trueenabled>
            snapshots>
        repository>
    repositories>

    <distributionManagement>
        <repository>
            <id>maven-releasesid>
            <name>maven-releasesname>
            <url>http://nexus.your-company.com:8081/repository/maven-releases/url>
        repository>
        <snapshotRepository>
            <id>maven-snapshotsid>
            <name>maven-snapshotsname>
            <url>http://nexus.your-company.com:8081/repository/maven-snapshots/url>
        snapshotRepository>
    distributionManagement>
project>

Nexus仓库说明

Nexus作为仓库管理工具的主要功能:

graph LR    A[用户] --> |mvn install / package| B[maven]    B --> C[nexus]    C --> |查找依赖| D{判断}    D -- 存在 --> E[直接返回给用户]    D -- 不存在 --> F[找公网]    F --> G[公共仓库]    G --> H[maven中央仓库]    G -.-> C    C -.-> A

Maven公共仓库

用途:存储公共依赖包
特点:自动从公网仓库同步和缓存
应用:主要用于依赖解析和下载

Maven Releases仓库

用途:存储稳定版本构件
特点:不可变性,版本唯一
应用:正式发布版本管理

Maven Snapshots仓库

用途:存储开发版本构件
特点:可覆盖更新,版本号带-SNAPSHOT后缀
应用:开发阶段使用

使用建议

严格遵循版本命名规范
合理配置权限管理
正确配置pom.xml和settings.xml
确保网络环境正常访问

GitLab 配置优化与 CICD 集成指南

2025-01-21T09:32:25.000Z

本文档旨在提供 GitLab 配置优化、集成最佳实践、安全加固、备份与恢复策略以及监控方法，帮助团队在使用 GitLab 进行源代码管理和持续集成/持续交付（CICD）时提升性能、安全性及稳定性。

GitLab 添加内网信任

目的

为 GitLab 配置内网信任，允许 GitLab 访问内网服务。

操作步骤

进入 GitLab 管理员界面。
进入设置页面，选择网络。
进入 出站请求，勾选以下选项：
- 允许来自 webhooks 和集成对本地网络的请求
- 允许系统钩子向本地网络发送请求
在空白框中粘贴需要调用的内网IP、域名。
登录 GitLab 服务器，编辑 /etc/hosts 文件，添加自定义域名映射。

192.168.x.x traefik.k8scluster.com
192.168.x.x harbor.dockerregistry.com
192.168.x.x argocd.k8scluster.com
192.168.x.x grpc.argocd.k8scluster.com

GitLab 集成 ArgoCD

目的

通过 GitLab 与 ArgoCD 集成，实现流水线中对 ArgoCD 应用的自动化操作，同时隐藏 ArgoCD 真实服务器信息。

操作步骤

进入项目组页面，选择设置 -> CI/CD -> 变量。
添加以下变量：
- ARGOCD_USERNAME: 自定义值，勾选 Masked
- ARGOCD_SERVER: 自定义值，勾选 Masked
- ARGOCD_PASSWORD: 自定义值，勾选 Masked

GitLab 集成 Minio

目的

将构建的制品存储到 Minio，减轻 GitLab 服务器的负担。

操作步骤

修改 GitLab 配置文件：

sudo vim /etc/gitlab/gitlab.rb
gitlab_rails['artifacts_enabled'] = true
gitlab_rails['artifacts_object_store_enabled'] = true
gitlab_rails['artifacts_object_store_remote_directory'] = 'gitlab-artifacts'
gitlab_rails['artifacts_object_store_connection'] = {
'provider' => 'AWS',
'region' => 'us-east-1',
'aws_access_key_id' => 'your_access_key',
'aws_secret_access_key' => 'your_secret_key',
'endpoint' => 'http://:9000',
'path_style' => true
}

重载配置：

sudo gitlab-ctl reconfigure

GitLab 集成 Harbor

目的

将构建的 Docker 镜像直接推送到 Harbor，无需重复配置。

操作步骤

进入 管理界面 或 项目组管理界面，选择设置 -> 集成。
添加 Harbor 集成，输入以下信息：
- 域名：Harbor 地址
- 项目名称：目标项目
- 用户：使用机器人名称
- 用户密码：Harbor 认证密码

GitLab 文件大小限制调整

目的

调整 GitLab 上传文件的大小限制，以适应大文件的上传需求。

操作步骤

进入 管理员界面 或 项目组页面，选择设置 -> CI/CD -> 流水线通用设置，调整 最大工件大小。

如果以上设置无效，修改 GitLab 服务器配置文件：

sudo vim /etc/gitlab/gitlab.rb
nginx['client_max_body_size'] = '200m'

重载配置：

sudo gitlab-ctl reconfigure

GitLab 集成 CICD

目的

配置 GitLab CI/CD，使机器人能够自动化更新代码。

操作步骤

进入项目页面，选择设置 -> 访问令牌，创建一个长期有效的开发者身份令牌。
进入 CI/CD -> 变量，添加以下变量：
- GITLAB_CI_TOKEN: 自定义值，勾选 Masked

GitLab 性能优化

目的

优化 GitLab 性能，提高并发处理能力，减少响应时间。

操作步骤

优化数据库：调整 PostgreSQL 配置，增加 shared_buffers 和 work_mem 设置：

sudo vim /etc/gitlab/postgresql.conf
shared_buffers = 1GB
work_mem = 64MB

启用 Redis 缓存：配置 GitLab 使用 Redis 缓存：

sudo vim /etc/gitlab/gitlab.rb
gitlab_rails['redis_host'] = 'localhost'
gitlab_rails['redis_port'] = 6379

使用 SSD 存储：为 GitLab 配置 SSD 存储，提高 I/O 性能。
优化 Nginx 配置：调整 Nginx 设置，提高吞吐量：

sudo vim /etc/gitlab/nginx/gitlab-http.conf
worker_processes auto;
worker_connections 4096;

分离 GitLab 服务：将 GitLab 服务分离到不同服务器，减轻单台服务器负担。

GitLab 安全加固

目的

加强 GitLab 的安全性，防止潜在的安全漏洞。

操作步骤

启用 HTTPS：为 GitLab 配置 SSL，确保数据传输加密：

sudo vim /etc/gitlab/gitlab.rb
external_url 'https://gitlab.example.com'
nginx['ssl_certificate'] = "/etc/ssl/certs/gitlab.crt"
nginx['ssl_certificate_key'] = "/etc/ssl/private/gitlab.key"

启用双因素认证（2FA）：在 GitLab 设置页面启用 2FA。
使用 LDAP 或 OAuth 实现企业认证：

sudo vim /etc/gitlab/gitlab.rb
gitlab_rails['ldap_enabled'] = true
gitlab_rails['ldap_servers'] = YAML.load <<-EOS
main:
  label: 'LDAP'
  host: '_your_ldap_server_'
  port: 389
  uid: 'sAMAccountName'
  bind_dn: 'CN=bind_user,CN=Users,DC=example,DC=com'
  password: '_your_password_'
EOS

GitLab 备份与恢复

目的

配置自动备份，以确保 GitLab 数据的安全性。

操作步骤

配置自动备份：

sudo vim /etc/gitlab/gitlab.rb
gitlab_rails['backup_path'] = '/var/opt/gitlab/backups'
gitlab_rails['backup_keep_time'] = 604800  # 保留7天备份

# 配置 crontab 定期备份
crontab -e
0 2 * * * gitlab-rake gitlab:backup:create

恢复备份：

sudo gitlab-rake gitlab:backup:restore BACKUP=timestamp_of_backup

备份恢复测试：定期进行恢复测试，确保备份数据可用。

GitLab 日志与监控

目的

通过日志管理和监控 GitLab 服务，及时发现和解决问题。

操作步骤

配置日志收集：使用 logrotate 管理 GitLab 日志文件：

sudo vim /etc/logrotate.d/gitlab
/var/log/gitlab/*.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
}

使用 Prometheus 和 Grafana 监控 GitLab：通过 Prometheus 集成监控 GitLab 性能，使用 Grafana 展示数据。
设置邮件通知：配置 GitLab 邮件通知，及时了解系统状态。

结语

本文档涵盖了 GitLab 的常见配置优化、集成 CICD、备份恢复、安全加固和监控等方面。通过这些操作，您可以有效提升 GitLab 的性能、安全性和可靠性。如果您有任何问题或进一步的需求，欢迎留言讨论。

如何在 Docker 环境中部署 GitLab Runner

2025-01-21T09:14:25.000Z

在本篇文章中，我们将介绍如何在 Docker 环境中部署 GitLab Runner，以便使用 GitLab CI/CD 实现自动化构建与部署。我们将通过 Docker Compose 配置并管理 GitLab Runner 容器，详细讲解配置文件和注册过程。

部署 GitLab Runner

GitLab Runner 是 GitLab CI/CD 的一个组成部分，用于执行 CI/CD 作业。本文将介绍如何在 Docker 环境中部署 GitLab Runner，并配置其与 GitLab 服务器的连接。我们将使用 Docker Compose 来管理 GitLab Runner 容器的启动和配置。

创建 Docker Compose 配置文件

首先，我们需要为 GitLab Runner 创建一个 docker-compose.yml 配置文件。在该文件中，我们定义了 GitLab Runner 容器的基本配置信息，包括使用的镜像、挂载的卷以及容器的特权模式。

version: '3'

services:
  gitlab-runner-npm:
    image: gitlab/gitlab-runner:latest  # 使用 GitLab Runner 的最新版本镜像
    container_name: gitlab-runner-npm  # 容器名称
    privileged: true  # 启用特权模式，允许容器执行 Docker 操作
    restart: always  # 容器崩溃时自动重启
    volumes:
      - ./gitlab-runner/:/etc/gitlab-runner  # 将本地的 GitLab Runner 配置文件挂载到容器中
      - ~/.docker:/root/.docker  # 将本地 Docker 配置挂载到容器中，确保 Runner 可以使用 Docker 客户端
      - /var/run/docker.sock:/var/run/docker.sock  # 共享 Docker 套接字，允许 Runner 执行 Docker 命令
      #- ./cache:/cache  # 可选的缓存挂载，用于加速构建过程

在这个 docker-compose.yml 文件中，我们挂载了几个目录和文件以确保容器能够正确工作：

./gitlab-runner/：用于存储 GitLab Runner 配置。
~/.docker：将主机上的 Docker 配置挂载到容器中。
/var/run/docker.sock：容器通过这个挂载与宿主机的 Docker 守护进程进行通信，允许 Runner 执行 Docker 命令。

注册 GitLab Runner

GitLab Runner 需要在注册后才能与 GitLab 服务进行通信。以下是注册 GitLab Runner 的脚本，它通过 Docker 执行 gitlab-runner register 命令。

#!/bin/bash

REGISTRATION_TOKEN="YOUR_REGISTRATION_TOKEN"  # GitLab 注册令牌，替换为实际值
RUNNER_NAME="gitlab-runner-npm-group"  # Runner 的名称

docker exec -it "${RUNNER_NAME}" gitlab-runner register \
  --non-interactive \
  --url "http://gitlab.example.com/" \  # GitLab 服务器地址，替换为实际地址
  --registration-token "${REGISTRATION_TOKEN}" \
  --executor "docker" \  # 使用 Docker 执行器
  --docker-image "docker:19.03.12" \  # Docker 镜像，选择适合的版本
  --description "Docker Runner" \  # Runner 描述
  --tag-list "docker-npm" \  # Runner 标签，帮助过滤任务
  --locked=true \  # 锁定 Runner，防止其他 GitLab 实例注册
  --docker-privileged=true \  # 启用 Docker 特权模式
  --run-untagged=false \  # 不运行未打标签的作业
  --docker-tlsverify=false \  # 禁用 Docker TLS 验证
  --docker-disable-entrypoint-overwrite=false \  # 不禁用容器入口点覆盖
  --docker-oom-kill-disable=false \  # 启用 OOM 杀死
  --docker-disable-cache=false \  # 启用 Docker 缓存
  --docker-shm-size=0 \  # 设置共享内存大小
  --cache-type="s3" \  # 配置 S3 缓存
  --cache-path="runner" \  # 缓存路径
  --cache-shared=true \  # 启用共享缓存
  --cache-s3-server-address="s3.example.com:9000" \  # S3 服务器地址，替换为实际值
  --cache-s3-access-key="YOUR_S3_ACCESS_KEY" \  # S3 访问密钥
  --cache-s3-secret-key="YOUR_S3_SECRET_KEY" \  # S3 秘密访问密钥
  --cache-s3-bucket-name="runner-cache" \  # S3 存储桶名称
  --cache-s3-insecure=true  # 启用不安全连接

GitLab Runner 配置

在容器中，我们可以编辑 GitLab Runner 的配置文件 config.toml，以设置并优化 Runner 的行为。以下是 config.toml 文件的示例，其中包含了多个重要的配置项：

concurrent = 1  # 限制同时运行的作业数
check_interval = 0  # 检查任务队列的间隔时间

[session_server]
  session_timeout = 1800  # 会话超时设置（单位：秒）

[[runners]]
  name = "Docker Runner"  # Runner 名称
  url = "http://gitlab.example.com/"  # GitLab 实例的 URL
  token = "YOUR_REGISTRATION_TOKEN"  # 注册令牌，替换为实际值
  executor = "docker"  # 使用 Docker 执行作业

  [runners.custom_build_dir]
  #[runners.cache]  # 缓存配置，通常用于加速构建过程
  #  Type = "local"
  #  Path = "/cache"
  #  Shared = true
  [runners.cache]
    Type = "s3"  # 使用 S3 作为缓存类型
    Path = "runner"  # 缓存路径
    Shared = true  # 启用共享缓存
    [runners.cache.s3]
      ServerAddress = "s3.example.com:9000"  # S3 服务器地址，替换为实际地址
      AccessKey = "YOUR_S3_ACCESS_KEY"  # S3 访问密钥
      SecretKey = "YOUR_S3_SECRET_KEY"  # S3 秘密访问密钥
      BucketName = "runner-cache"  # S3 存储桶名称
      Insecure = true  # 启用不安全连接

  [runners.docker]
    tls_verify = false  # 禁用 Docker TLS 验证
    image = "docker:19.03.12"  # Docker 镜像版本
    privileged = true  # 启用特权模式
    disable_entrypoint_overwrite = false  # 启用容器入口点覆盖
    oom_kill_disable = false  # 启用 OOM 杀死
    disable_cache = false  # 启用缓存
    volumes = ["/cache"]  # 挂载的目录
    shm_size = 536870912  # 设置共享内存大小
    memory = "24000m"  # 分配内存
    memory_swap = "26g"  # 设置交换内存
    cpus = "12"  # 分配 CPU 核数
    allowed_images = [  # 限制 Runner 使用的镜像列表
      "harbor.dockerregistry.com/kubernetes/maven:3.6.3-openjdk-8-slim",
      "harbor.dockerregistry.com/kubernetes/kaniko-project/executor:v1.14.0-debug",
      "harbor.dockerregistry.com/kubernetes/argocli-git:v2.7.14",
      "harbor.dockerregistry.com/kubernetes/nodejs:*"
    ]

重要配置说明：

privileged：启用特权模式，允许容器执行 Docker 操作。这是必需的，因为 GitLab Runner 需要能够在容器中执行构建任务。
executor：指定运行作业的执行器，通常为 docker，可以在容器中运行任务。
volumes：挂载卷，允许容器访问宿主机的文件系统。例如，挂载 Docker 套接字和共享缓存目录。
memory 和 cpus：为 Runner 分配内存和 CPU 资源，根据需要调整这些参数以优化构建性能。

启动 GitLab Runner

完成以上配置后，我们可以通过以下命令启动 GitLab Runner 容器：

docker-compose up -d  # 在后台启动服务

这将启动 GitLab Runner，并且它会自动与 GitLab 实例注册。您可以登录 GitLab 查看 Runner 是否成功注册并开始处理作业。

如何在Kubernetes 环境中安装 Grafana 部署指南

2025-01-21T08:53:25.000Z

本文介绍如何通过 Helm 部署 Grafana 并配置反向代理，以便在 Kubernetes 集群中使用 Grafana，支持 HTTPS 加密和基本认证。

下载 Helm Chart

首先创建目录并下载 Grafana 的 Helm Chart。

mkdir -p grafana 
cd grafana
helm repo add grafana https://grafana.github.io/helm-charts
helm repo update
helm search repo grafana/grafana -l
helm search repo grafana/grafana --versions

# 如果需要下载指定版本
# helm pull grafana/grafana --version 7.2.3 
tar xf grafana-7.2.3.tgz
cp -rvf grafana/values.yaml{,.bak}

创建自定义 `values.yaml`

Grafana 的 values.yaml 文件用于配置 Helm Chart 部署的参数。以下是常用的配置项：

image:
  registry: docker.io
  repository: grafana/grafana
  tag: "10.2.3"  # 修改为固定版本的镜像标签
  
ingress:
  enabled: true  # 启用 Ingress
  annotations:  # 添加注释
    kubernetes.io/ingress.class: "nginx"
    nginx.ingress.kubernetes.io/rewrite-target: /$1
    nginx.ingress.kubernetes.io/use-regex: "true"
  hosts:
    - grafana.k8scluster.com  # 使用域名访问 Grafana
  
persistence:
  type: pvc 
  enabled: true  # 启用 PVC 持久化存储
  storageClassName: default  # 使用默认存储类
  accessModes:
    - ReadWriteOnce
  size: 1Gi  # 设置 PVC 大小为 1Gi

extraVolumeMounts:  # 配置额外的挂载路径
  - name: grafana-data
    mountPath: /var/lib/grafana/plugins
    subPath: plugins
    readOnly: false
  - name: grafana-data
    mountPath: /var/lib/grafana/dashboards
    subPath: dashboards
    readOnly: false
  - name: grafana-data
    mountPath: /etc/grafana/provisioning
    subPath: provisioning
    readOnly: false

extraVolumes:
  - name: grafana-data
    persistentVolumeClaim:
      claimName: grafana-data-pvc  # 使用指定的 PVC

配置解释

镜像配置 (image)：选择正确的 Grafana 镜像版本。这里的 tag 参数设置为具体版本，如 10.2.3。
Ingress 配置 (ingress)：
- 启用 Ingress 以便通过域名访问 Grafana。
- nginx.ingress.kubernetes.io/rewrite-target：将请求路径重写为适合 Grafana 的路径。
- path 和 pathType 配置了访问路径，并使用正则匹配来灵活处理请求。
- hosts 配置为本地域名，确保 Grafana 可以通过指定域名访问。
持久化配置 (persistence)：
- 使用 PVC 进行持久化存储，以便在 Grafana Pod 重启时不会丢失数据。
- 配置存储大小为 1Gi，并选择合适的存储类 default。
额外的挂载配置 (extraVolumeMounts)：
- 将 Grafana 的插件、仪表盘和配置文件夹挂载到指定路径，确保 Grafana 启动时能够使用这些资源。

使用 Helm 安装 Grafana

使用以下命令来安装 Grafana 并指定自定义的 values.yaml 配置文件：

helm install grafana -f grafana/values.yaml ./grafana --namespace grafana --create-namespace

安装完成后输出

安装完成后，您可以通过以下命令获取 Grafana 的默认管理员密码：

kubectl get secret --namespace grafana grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo

Grafana 控制台可以通过以下 DNS 地址访问：

http://grafana.k8scluster.com

登录时，使用管理员账户 admin 和密码。

更新 Helm 部署

若需要对已部署的 Grafana 进行更新（例如修改配置），可以使用以下命令：

helm upgrade grafana -f grafana/values.yaml ./grafana --namespace grafana

更新后输出

更新后同样可以通过以下命令获取更新后的管理员密码：

kubectl get secret --namespace grafana grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo

登录 Grafana 控制台

Grafana 控制台可以通过浏览器访问以下地址：

http://grafana.k8scluster.com:30886/grafana

登录时，使用之前获取的管理员密码进行登录。

导出 Prometheus 和 Alertmanager

创建 Prometheus 和 Alertmanager 的 Ingress

为 Prometheus 和 Alertmanager 创建一个 Ingress 资源，使其通过域名访问。

kind: Ingress
apiVersion: networking.k8s.io/v1
metadata:
  name: prometheus-ingress
  namespace: kubesphere-monitoring-system
  annotations:
    nginx.ingress.kubernetes.io/auth-realm: Authentication Required
    nginx.ingress.kubernetes.io/auth-secret: prometheus-basic-auth
    nginx.ingress.kubernetes.io/auth-type: basic
    nginx.ingress.kubernetes.io/proxy-body-size: 2048m
    nginx.ingress.kubernetes.io/proxy-connect-timeout: '1800'
    nginx.ingress.kubernetes.io/proxy-read-timeout: '1800'
    nginx.ingress.kubernetes.io/proxy-send-timeout: '1800'
spec:
  ingressClassName: nginx
  rules:
    - host: prometheus.k8scluster.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: prometheus-k8s
                port:
                  name: web
    - host: alertmanager.k8scluster.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: alertmanager-main
                port:
                  name: web

创建 HTTP 基本认证

通过 htpasswd 创建一个基本认证文件，并将其作为 Secret 存储：

htpasswd -c auth admin  # 设置管理员密码

创建 Secret

创建 Kubernetes Secret，用于存储基本认证凭证：

kubectl create secret generic prometheus-basic-auth --from-file=auth -n monitoring

Kevin's Notes

Windows 容器开发环境搭建指南

方案对比：Docker Desktop / Podman / Rancher Desktop

Docker Desktop —— 好用但有授权风险

Podman on Windows —— 理想丰满，现实骨感

Rancher Desktop —— 看似全能，实则复杂

推荐方案：WSL2 + Docker Engine

架构原理

方案对比总结

完整配置步骤

Step 1：启用 WSL2

Step 2：WSL2 资源限制（可选但推荐）

Step 3：在 WSL2 里安装 Docker Engine

Step 4：配置代理（国内使用关键一步）

Step 5：配置镜像加速（代理 Fallback）

Step 6：配置 VSCode Remote WSL

可选：Portainer —— 需要 GUI 时的选择

最终工作流

写在最后

Nexus Repository Manager 启动失败排查全记录

背景

排查过程

第一步：定位真实安装路径

第二步：查看应用日志

第三步：前台运行，直接看报错

第四步：验证权限问题

根本原因分析

解决方案

修复一：恢复数据库文件权限

修复二：清理残留锁文件

修复三：重写为原生 systemd 服务

验证结果

遗留优化：SSL 证书问题

经验总结

Jenkins Slave 节点重建后 SSH 认证失败的排查与恢复

问题现象

根因分析

完整恢复步骤

Step 1 — 验证网络和 SSH 基础连通性

Step 2 — 切换为 SSH Key 认证（推荐，一劳永逸）

Step 3 — 更新 Jenkins Credential

Step 4 — 确认 slave 节点的 Java 环境

Step 5 — 重启 slave 节点连接

问题复盘

经验总结

参考资料

Podman CLI on Windows 安装与配置指南

Podman 架构概述

核心概念

与 Docker 的差异

安装 Podman

方式一：winget（推荐）

方式二：手动下载

初始化 Podman Machine

清理系统代理环境变量

配置 VM 内部代理

查找宿主机 WSL IP

开启代理软件局域网访问

写入 VM 代理配置

重启 Machine 使配置生效

配置私有 Harbor 仓库信任

配置开机自启动

验证完整环境

日常维护命令

故障排查指南

常见问题与解决方案

参考资源

官方文档

相关工具

Windows 小狼毫输入法（Rime）安装配置指南

安装步骤

方式一：官方下载

方式二：包管理器安装（推荐）

基础配置

配置文件位置

最小化配置

创建 default.custom.yaml

创建 weasel.custom.yaml

部署配置

快速上手

创建 `default.custom.yaml`

创建 `weasel.custom.yaml`