基于Docker + K3S + Jenkins + Harbor的云原生自动化部署实践

1. 为什么你需要这套自动化部署方案？

如果你和我一样，带过几个中小规模的研发团队，肯定对下面这些场景深有体会：每次发版，开发、测试、运维几个兄弟得凑在一起，手动打包、传文件、登录服务器、执行一堆命令，一搞就是大半天。万一哪个步骤手滑了，还得回滚重来，整个下午就搭进去了。更头疼的是，测试环境、预发环境、生产环境配置还不一样，每次部署都像在走钢丝。

后来我接触了云原生这套东西，发现用 Docker + K3S + Jenkins + Harbor 组合拳，能把上面这些痛点一次性解决掉。简单来说，它能把“代码提交”到“服务上线”这个漫长、易错的手工过程，变成一条全自动的流水线。你只需要点一下按钮，或者干脆代码一推，剩下的构建、测试、打包、部署，全部由机器搞定。

这套方案特别适合中小团队，原因有三：

1. 轻量且够用：K3S 是 Kubernetes 的轻量级发行版，去掉了很多企业级复杂功能，但核心的容器编排能力一点不差，对资源消耗很小，几台虚拟机甚至一台好点的机器就能跑起来。
2. 成本可控：全部采用开源方案，Harbor 提供企业级的私有镜像仓库，安全又免费；Jenkins 的流水线能力经过无数项目验证，非常稳定。
3. 上手不难：虽然听起来技术栈不少，但每个环节的配置都有“套路”。一旦搭好，后续就是复制粘贴微调，新人也能快速接手维护。

我去年给一个不到10人的产品团队落地了这套方案，部署效率提升了70%以上，半夜因为部署问题被叫起来救火的次数直接降为零。下面，我就把从零开始搭建的完整过程，以及我踩过的坑和最佳实践，毫无保留地分享给你。

2. 环境准备与基础组件安装

万事开头难，我们先得把“舞台”搭好。这里假设你有2-3台 Linux 服务器（可以是虚拟机），一台作为构建和仓库服务器（Jenkins + Harbor），另一台或多台作为 K3S 集群节点。如果资源紧张，所有组件也可以装在一台机器上，只是生产环境不建议这么做。

2.1 安装 Docker 环境

Docker 是这一切的基石，我们的应用最终都会被打包成容器。安装过程以 CentOS 7/8 为例，其他系统也大同小异。

# 1. 卸载旧版本（如果有）
sudo yum remove docker docker-client docker-client-latest docker-common docker-latest docker-latest-logrotate docker-logrotate docker-engine

# 2. 安装必要的依赖包
sudo yum install -y yum-utils device-mapper-persistent-data lvm2

# 3. 设置稳定的 Docker CE 仓库
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 4. 安装 Docker CE 及命令行工具
sudo yum install -y docker-ce docker-ce-cli containerd.io

# 5. 启动 Docker 并设置开机自启
sudo systemctl start docker
sudo systemctl enable docker

# 6. 验证安装
sudo docker run hello-world

如果能看到“Hello from Docker!”的输出，说明 Docker 安装成功了。接下来有个非常重要的配置：国内访问 Docker Hub 拉取镜像很慢，我们需要配置镜像加速器。同时，因为我们后续要用到自建的 Harbor 私有仓库（默认是 HTTP），也需要把它加到“信任名单”里。

# 编辑 Docker 守护进程配置文件
sudo vi /etc/docker/daemon.json

将以下内容写入文件（请将 your-harbor-ip 替换为你实际的 Harbor 服务器 IP）：

{
  "registry-mirrors": [
    "https://registry.docker-cn.com",
    "https://mirror.baidubce.com"
  ],
  "insecure-registries": [
    "your-harbor-ip:80"
  ],
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  }
}

保存后，重启 Docker 使配置生效：

sudo systemctl daemon-reload
sudo systemctl restart docker

这个 insecure-registries 配置是关键，它告诉 Docker 客户端可以信任这个 HTTP 协议的仓库地址，否则 push/pull 镜像时会报安全错误。

2.2 部署轻量级 K3S 集群

K3S 是 Rancher 公司推出的轻量级 K8S，安装简单到令人发指。对于学习和中小规模生产，单节点集群就足够了。如果你想体验多节点，后续再加也很方便。

在主节点上执行（假设你的服务器 IP 是 192.168.1.100）：

# 使用国内镜像加速安装，一行命令搞定
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn sh -

# 安装完成后，检查状态
sudo systemctl status k3s

# 获取 kubeconfig 文件，用于后续 kubectl 操作
sudo cat /etc/rancher/k3s/k3s.yaml

你会看到一段 YAML 配置，把它保存到你的本地 ~/.kube/config，或者 Jenkins 服务器上的某个路径。注意：配置文件里的 server: https://127.0.0.1:6443 需要改成 K3S 主节点的实际 IP，比如 server: https://192.168.1.100:6443，这样其他机器（如 Jenkins）才能远程访问。

验证集群：

# 默认 k3s 将 kubectl 链接到了 /usr/local/bin/kubectl
sudo kubectl get nodes
sudo kubectl get pods -A

如果能看到节点状态是 Ready，并且一堆系统 Pod 都在运行，那么你的迷你 K8S 集群就 ready 了。

2.3 搭建私有镜像仓库 Harbor

为什么不用 Docker Hub 的公共仓库？因为速度、安全和隐私。Harbor 提供了图形化界面、权限管理、漏洞扫描等企业级功能，是私有化部署的必备。

首先，确保你的机器上已经安装了 Docker 和 Docker Compose。然后去 Harbor GitHub Release 页面下载离线安装包（比如 harbor-offline-installer-v2.10.0.tgz）。

# 1. 解压安装包
tar xzf harbor-offline-installer-v2.10.0.tgz
cd harbor

# 2. 复制配置文件模板并编辑
cp harbor.yml.tmpl harbor.yml
vi harbor.yml

你需要修改 harbor.yml 中的几个关键配置：

# 主机名或IP，用于访问 Harbor UI
hostname: your-harbor-ip  # 例如 192.168.1.100

# HTTP 配置（如果不用 HTTPS，就只用这个）
http:
  port: 80

# 初始管理员密码，务必修改！
harbor_admin_password: YourStrongPassword123

# 数据持久化目录
data_volume: /data/harbor

如果你是在内网测试，可以暂时不配置 HTTPS（注释掉 https 部分）。在生产环境，强烈建议配置 HTTPS。

# 3. 执行安装脚本
sudo ./install.sh

安装完成后，用浏览器打开 http://your-harbor-ip，用 admin 和你设置的密码登录。第一件事就是创建一个新项目（比如叫 myapp），后续我们的镜像就推送到这个项目下。

2.4 安装与配置 Jenkins

Jenkins 是我们的自动化引擎。这里我们用 Docker 方式来安装，方便管理。

#