portainer 容器管家部署指南

🌱 创建: 2026/04/12 ⏱️ 更新: 2026/05/22

如果说 Headlamp 是我们堡垒里华丽的“全息监控大屏”，那么 Portainer 就是你腰间挂着的那串“万能钥匙”。它不仅能看，更能打 —— 尤其是在处理容器日志、直接进入控制台、查看镜像层级时，它的操作逻辑更符合我们从 Docker 时代过来的习惯。

💡 认识工程组件

1. 什么是 Portainer？

Portainer 是全球最流行的容器管理面板。在 K8s 架构中，它由两个核心部件组成：

Portainer Server：中央大脑，负责 UI 展示和数据存储。
Portainer Agent：分身，部署在每个节点上，负责替大脑打杂（收集数据、执行指令）。

2. 存储警告：关于“搬家”的风险与终极解法

Portainer 需要存储你的用户设置和配置数据。在我们目前的 K3s 集群中，默认使用的是 local-path（本地路径）存储类。

⚠️ 风险点：如果你不指定节点，Portainer 的数据会存在某一台随机分配的 Master 的物理磁盘里。万一哪天 K8s 把 Portainer 调度到了另一台机器，它会发现“家没了”，导致你辛苦设置的密码和配置全部重置，一夜回到解放前。
🩹 临时解法 (本章方案)：为了眼前不出岔子，我们将在部署时使用 nodeSelector，把 Portainer 死死地“焊”在 k3s-master-01 上，禁止它瞎跑。
🚀 终极方案 (后续预告)：把应用绑死在单台机器上显然违背了 K8s 高可用的初衷。后面包工头会带你部署企业级分布式块存储 —— Longhorn。届时，数据会在所有节点间实时多副本同步，无论 Pod 漂移到哪台机器，它的“家”都在那里！

📜 官方蓝图 (Official Resources)

🚢 Portainer 官方文档
- 📘 K8s 裸机安装指南：Official Docs
- 🐙 Helm Chart 仓库：https://github.com/portainer/k8s

🏗️ 核心施工：Portainer 规范化部署

我们继续采用 Helm + 配置文件 的工业级标准，拒绝盲目敲入一长串命令行参数。

编写 Helm 施工图纸 portainer-values.yaml

在执行安装前，我们先定好规矩。请注意 nodeSelector 部分，确保它运行在你的 k3s-master-01 上。

# 强制开启 TLS，保证安全
tls:
  force: true

# 核心配置：将 Pod 锁定在 Master 01，防止数据随漂移丢失 请将k3s-master-01修改为你实际的节点名
nodeSelector:
  kubernetes.io/hostname: k3s-master-01

# 存储配置
persistence:
  enabled: true
  size: 300M
  # K3s 默认存储类名
  storageClass: "local-path"

照图施工：执行安装

# 添加仓库并更新
helm repo add portainer https://portainer.github.io/k8s/
helm repo update

# 一键拉起管家
helm upgrade --install -n portainer --create-namespace \
  portainer portainer/portainer \
  -f portainer-values.yaml

检查发牌进度

由于 Portainer 默认的 Chart 会自带一个 NodePort 类型的 Service，我们可以看看 Cilium 是否已经给它发了牌照：
Terminal window
```
kubectl get svc -n portainer
```
期望结果：看到 portainer 服务已经30779端口。

🧪 Service 维度压测：打通“管家”通道

Portainer 默认监听两个端口：9000 (HTTP) 和 9443 (HTTPS)。为了验证我们的网络底座，我们同样手写一张多维度的接入图纸 portainer-access.yaml。

---
# 维度一：榨干发牌员 (LoadBalancer)
# 我们手动定义一个，强制要求 Cilium 分配我们的 10.0.10.x 段 IP
apiVersion: v1
kind: Service
metadata:
  name: portainer-lb-manual
  namespace: portainer
  annotations:
    # 🎯 赛博发牌员的“后门指令”：强制要求分配 10.0.10.55
    io.cilium/lb-ipam-ips: "10.0.10.55"
spec:
  type: LoadBalancer
  selector:
    app.kubernetes.io/instance: portainer
    app.kubernetes.io/name: portainer
  ports:
    - name: http
      port: 9000
      targetPort: 9000
    - name: https
      port: 9443
      targetPort: 9443

执行应用：kubectl apply -f portainer-access.yaml。

🧭 接入点验收

方式 A (LoadBalancer)：直接访问 Cilium 分配的 IP，例如 https://10.0.10.55:9443。
方式 B (NodePort)：访问任意节点的物理 IP，例如 https://10.0.10.10:30779。

🎉 登堂入室 (Access)

初始化管理员：第一次打开页面，你会看到初始化界面。请在 12 分钟内完成密码设置，否则 Portainer 会为了安全自动关闭（重启 Pod 即可重置计时）。
选择环境：由于 Portainer 跑在集群内部且我们给了它权限，它会自动发现 Local 集群。
开始巡检：点击进入环境后，你会看到久违的 Dashboard。在这里，你可以像在单机 Docker 环境里一样，轻松地：
- 查看所有容器的资源占用。
- 快速进入 Shell（比 kubectl exec 爽多了）。
- 直接查看 Pod 的实时滚动日志。

❓ 常见问题与解答 (Q & A)

[Q] 为什么我登录时提示“Timeout”，无法设置密码？

[A]: 这是一个安全机制。如果安装后 12 分钟内没人设置管理员，它会罢工。只需执行 kubectl rollout restart deployment portainer -n portainer 重启一下即可。

[Q] 以后我加了 Worker 节点，Portainer 能管到吗？

[A]: 只要你在新节点也加入了集群，Portainer 会通过 Agent（它会自动以 DaemonSet 形式布在每个节点）自动接管新节点的容器。

[Q] 为什么我的 Portainer 重启后，之前的容器列表变了？

[A]: 检查你的 values.yaml。如果没有设置 persistence.enabled: true，或者没有指定 nodeSelector 导致 Pod 漂移到了没有数据的节点，配置就会重置。