MicroK8s中AdGuard Home容器重启后需重新配置的问题咨询

问题描述 #

在MicroK8s环境（搭配MetalLB与ZFS存储）部署AdGuard Home时，容器手动关闭或服务器重启后，每次启动都需要重新配置。相同部署方式的Plex可正常保留状态。

现有配置文件 #

Namespace #

---
apiVersion: v1
kind: Namespace
metadata:
  name: adguard

PV #

---
apiVersion: v1
kind: PersistentVolume
metadata:
  name: adguard-data-pv
  namespace: adguard
spec:
  capacity:
    storage: 1Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  hostPath:
    path: "/tank/apps/adguard/data"
---
apiVersion: v1
kind: PersistentVolume
metadata:
  name: adguard-conf-pv
  namespace: adguard
spec:
  capacity:
    storage: 1Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  hostPath:
    path: "/tank/apps/adguard/conf"

PVC #

---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: adguard-data-pvc
  namespace: adguard
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
  volumeName: adguard-data-pv
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: adguard-conf-pvc
  namespace: adguard
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
  volumeName: adguard-conf-pv

ConfigMap #

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: adguard-config
  namespace: adguard
data:
  AdGuardHome.yaml: |
    bind_host: 0.0.0.0
    bind_port: 3000
    auth_name: "admin"
    auth_pass: "[REDACTED]"
    language: "en"
    rlimit_nofile: 0
    rlimit_nproc: 0
    log_file: ""
    log_syslog: false
    log_syslog_srv: ""
    pid_file: ""
    verbose: false

Deployment #

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: adguard-deployment
  namespace: adguard
spec:
  replicas: 1
  selector:
    matchLabels:
      app: adguard
  template:
    metadata:
      labels:
        app: adguard
    spec:
      containers:
        - name: adguard-home
          image: adguard/adguardhome:latest
          resources:
            requests:
              memory: "128Mi"
              cpu: "250m"
            limits:
              memory: "512Mi"
              cpu: "1000m"
          env:
            - name: AGH_CONFIG
              valueFrom:
                configMapKeyRef:
                  name: adguard-config
                  key: AdGuardHome.yaml
          ports:
            - containerPort: 53
              name: dns-tcp
              protocol: TCP
            - containerPort: 53
              name: dns-udp
              protocol: UDP
            - containerPort: 67
              name: dhcp-one
              protocol: UDP
            - containerPort: 68
              name: dhcp-two
              protocol: TCP
            - containerPort: 68
              name: dhcp-three
              protocol: UDP
            - containerPort: 80
              name: http-tcp
              protocol: TCP
            - containerPort: 443
              name: doh-tcp
              protocol: TCP
            - containerPort: 443
              name: doh-udp
              protocol: UDP
            - containerPort: 3000
              name: http-initial
            - containerPort: 784
              name: doq-one
              protocol: UDP
            - containerPort: 853
              name: dot
              protocol: TCP
            - containerPort: 853
              name: doq-two
              protocol: UDP
            - containerPort: 5443
              name: dnscrypt-tcp
              protocol: TCP
            - containerPort: 5443
              name: dnscrypt-udp
              protocol: UDP
          volumeMounts:
            - name: adguard-data
              mountPath: /opt/adguardhome/work
            - name: adguard-conf
              mountPath: /opt/adguardhome/conf
      volumes:
        - name: adguard-data
          persistentVolumeClaim:
            claimName: adguard-data-pvc
        - name: adguard-conf
          persistentVolumeClaim:
            claimName: adguard-conf-pvc

Service #

---
apiVersion: v1
kind: Service
metadata:
  name: adguard-service
  namespace: adguard
spec:
  selector:
    app: adguard
  ports:
    - protocol: TCP
      port: 3000
      targetPort: 3000
      name: http-initial
    - protocol: TCP
      port: 80
      targetPort: 80
      name: http-tcp
    - protocol: UDP
      port: 53
      targetPort: 53
      name: dns-udp
    - protocol: TCP
      port: 53
      targetPort: 53
      name: dns-tcp
    - protocol: UDP
      port: 67
      targetPort: 67
      name: dhcp-one
    - protocol: TCP
      port: 68
      targetPort: 68
      name: dhcp-two
    - protocol: UDP
      port: 68
      targetPort: 68
      name: dhcp-three
    - protocol: TCP
      port: 443
      targetPort: 443
      name: doh-tcp
    - protocol: UDP
      port: 443
      targetPort: 443
      name: doh-udp
    - protocol: UDP
      port: 784
      targetPort: 784
      name: doq-one
    - protocol: TCP
      port: 853
      targetPort: 853
      name: dot
    - protocol: UDP
      port: 853
      targetPort: 853
      name: doq-two
    - protocol: TCP
      port: 5443
      targetPort: 5443
      name: dnscrypt-tcp
    - protocol: UDP
      port: 5443
      targetPort: 5443
      name: dnscrypt-udp
  type: LoadBalancer
  externalTrafficPolicy: Local

问题修复步骤 #

1. 修正PV的Namespace配置 #

PV是集群级资源，不属于任何Namespace，原配置中metadata.namespace: adguard是错误的，会导致PVC绑定异常。修改后的PV配置：

---
apiVersion: v1
kind: PersistentVolume
metadata:
  name: adguard-data-pv
spec:
  capacity:
    storage: 1Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  hostPath:
    path: "/tank/apps/adguard/data"
---
apiVersion: v1
kind: PersistentVolume
metadata:
  name: adguard-conf-pv
spec:
  capacity:
    storage: 1Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  hostPath:
    path: "/tank/apps/adguard/conf"

2. 修正AGH_CONFIG环境变量用法 #

AGH_CONFIG是指定配置文件路径的环境变量，而非直接传入配置内容，原用法会导致容器无法识别配置，每次启动进入初始化流程。推荐使用以下两种方式之一：

方式一：挂载ConfigMap为自定义配置文件

修改Deployment的volumes和volumeMounts，将ConfigMap挂载到容器内自定义路径，再通过环境变量指向该文件：

# 更新Deployment的spec.template.spec部分
spec:
  containers:
    - name: adguard-home
      image: adguard/adguardhome:latest
      # 保留原有resources、ports配置
      env:
        - name: AGH_CONFIG
          value: /opt/adguardhome/custom/AdGuardHome.yaml
      volumeMounts:
        - name: adguard-data
          mountPath: /opt/adguardhome/work
        - name: adguard-conf
          mountPath: /opt/adguardhome/conf
        - name: adguard-custom-config
          mountPath: /opt/adguardhome/custom
  volumes:
    - name: adguard-data
      persistentVolumeClaim:
        claimName: adguard-data-pvc
    - name: adguard-conf
      persistentVolumeClaim:
        claimName: adguard-conf-pvc
    - name: adguard-custom-config
      configMap:
        name: adguard-config

方式二：直接覆盖默认配置文件路径

将ConfigMap中的配置文件直接挂载到AdGuard Home的默认配置路径（需使用subPath避免覆盖整个目录）：

# 更新Deployment的spec.template.spec部分
spec:
  containers:
    - name: adguard-home
      image: adguard/adguardhome:latest
      # 保留原有resources、ports配置
      volumeMounts:
        - name: adguard-data
          mountPath: /opt/adguardhome/work
        - name: adguard-conf
          mountPath: /opt/adguardhome/conf
        - name: adguard-config-file
          mountPath: /opt/adguardhome/conf/AdGuardHome.yaml
          subPath: AdGuardHome.yaml
  volumes:
    - name: adguard-data
      persistentVolumeClaim:
        claimName: adguard-data-pvc
    - name: adguard-conf
      persistentVolumeClaim:
        claimName: adguard-conf-pvc
    - name: adguard-config-file
      configMap:
        name: adguard-config

3. 检查持久化目录权限 #

确保ZFS路径的权限允许容器写入，AdGuard Home默认以root用户运行，执行以下命令：

sudo chown -R root:root /tank/apps/adguard
sudo chmod -R 755 /tank/apps/adguard

4. 验证PVC绑定状态 #

执行命令检查PVC是否正常绑定：

microk8s kubectl get pvc -n adguard

输出中STATUS应为Bound，若为Pending需检查PV路径是否存在、权限是否正确。

5. 重新部署应用 #

删除原有资源后重新部署：

microk8s kubectl delete -f namespace.yaml,pv.yaml,pvc.yaml,configmap.yaml,deployment.yaml,service.yaml
microk8s kubectl apply -f namespace.yaml,pv.yaml,pvc.yaml,configmap.yaml,deployment.yaml,service.yaml

为什么Plex正常？ #

Plex镜像会自动将配置写入挂载的持久化目录，无需额外环境变量指定配置路径，因此你的挂载方式可正常工作；而AdGuard Home对配置加载逻辑有明确要求，环境变量用法错误是配置无法持久化的核心原因。

内容的提问来源于stack exchange，提问作者telometto