一、核心定位

本文作为GitOps环境搭建系列的第五篇，聚焦基础组件（数据库和缓存）的部署与配置。在GitOps环境中，数据库和缓存是支撑核心组件（Gitea、ArgoCD、Tekton、Harbor等）运行的关键基础设施。

基础组件包括：

PostgreSQL/MySQL：关系型数据库，用于存储Gitea、Harbor等组件的元数据
Redis：内存缓存，用于提升组件性能和会话管理

本文采用独立命名空间规划，将PostgreSQL部署在postgres命名空间，Redis部署在redis命名空间，MySQL作为备选方案部署在mysql命名空间。所有配置均适配K3s轻量级环境，使用local-path存储类保障数据持久化，并通过Traefik的IngressRouteTCP实现服务访问。

二、部署前置检查

部署前需验证K3s集群状态及存储配置：

# 1. 验证K3s集群状态
kubectl get nodes

# 2. 验证存储类配置
kubectl get storageclass
kubectl describe storageclass local-path

# 3. 验证Traefik运行状态
kubectl get pods -n kube-system -l app=traefik

# 4. 检查命名空间
kubectl get ns postgres redis mysql 2>/dev/null || echo "命名空间不存在，将自动创建"

# 5. 验证网络连通性
ping -c 3 8.8.8.8

前置条件检查清单：

K3s集群运行正常
local-path存储类可用
Traefik Pod处于Running状态
网络可访问外网（用于拉取镜像）
具备集群管理权限

三、创建独立命名空间

为实现数据库与缓存服务的资源隔离和精细化管理，分别创建专属命名空间：

# namespaces.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: postgres
---
apiVersion: v1
kind: Namespace
metadata:
  name: redis
---
apiVersion: v1
kind: Namespace
metadata:
  name: mysql

应用配置：

kubectl apply -f namespaces.yaml

# 验证命名空间创建
kubectl get namespaces | grep -E "postgres|redis|mysql"

四、部署PostgreSQL

4.1 配置PostgreSQL

# postgresql.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: postgres-config
  namespace: postgres
data:
  POSTGRES_DB: "gitea"
  POSTGRES_USER: "gitea"
  POSTGRES_PASSWORD: "gitea123"
  POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=C"
  PGDATA: "/var/lib/postgresql/data/pgdata"
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: postgres-pvc
  namespace: postgres
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: local-path
  resources:
    requests:
      storage: 20Gi
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres
  namespace: postgres
spec:
  serviceName: postgres
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
      - name: postgres
        image: postgres:15-alpine
        ports:
        - containerPort: 5432
        envFrom:
        - configMapRef:
            name: postgres-config
        volumeMounts:
        - name: postgres-data
          mountPath: /var/lib/postgresql/data
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
      volumes:
      - name: postgres-data
        persistentVolumeClaim:
          claimName: postgres-pvc
---
apiVersion: v1
kind: Service
metadata:
  name: postgres
  namespace: postgres
spec:
  selector:
    app: postgres
  ports:
  - port: 5432
    targetPort: 5432
  type: ClusterIP

4.2 配置IngressRouteTCP（可选）

如需通过Traefik外部访问PostgreSQL，配置IngressRouteTCP：

# postgres-ingressroute-tcp.yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRouteTCP
metadata:
  name: postgres-ingressroute-tcp
  namespace: postgres
spec:
  entryPoints:
    - postgres-tcp  # 需在Traefik中配置此TCP入口点
  routes:
  - match: HostSNI(`*`)
    services:
    - name: postgres
      port: 5432

4.3 应用PostgreSQL配置

# 部署PostgreSQL
kubectl apply -f postgresql.yaml

# 可选：部署IngressRouteTCP
kubectl apply -f postgres-ingressroute-tcp.yaml

# 验证部署状态
kubectl get pods -n postgres
kubectl get pvc -n postgres
kubectl get svc -n postgres

五、部署Redis

5.1 配置Redis

# redis.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: redis-config
  namespace: redis
data:
  redis.conf: |
    bind 0.0.0.0
    protected-mode no
    port 6379
    requirepass "redis123456"
    appendonly yes
    appendfsync everysec
    dir /data
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: redis
  namespace: redis
spec:
  serviceName: redis
  replicas: 1
  selector:
    matchLabels:
      app: redis
  template:
    metadata:
      labels:
        app: redis
    spec:
      containers:
      - name: redis
        image: redis:7-alpine
        command: ["redis-server", "/etc/redis/redis.conf"]
        ports:
        - containerPort: 6379
        volumeMounts:
        - name: redis-config
          mountPath: /etc/redis
        - name: redis-data
          mountPath: /data
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "256Mi"
            cpu: "200m"
  volumeClaimTemplates:
  - metadata:
      name: redis-data
    spec:
      accessModes: [ "ReadWriteOnce" ]
      storageClassName: "local-path"
      resources:
        requests:
          storage: 5Gi
---
apiVersion: v1
kind: Service
metadata:
  name: redis
  namespace: redis
spec:
  selector:
    app: redis
  ports:
  - port: 6379
    targetPort: 6379
  type: ClusterIP

5.2 配置IngressRouteTCP（可选）

# redis-ingressroute-tcp.yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRouteTCP
metadata:
  name: redis-ingressroute-tcp
  namespace: redis
spec:
  entryPoints:
    - redis-tcp  # 需在Traefik中配置此TCP入口点
  routes:
  - match: HostSNI(`*`)
    services:
    - name: redis
      port: 6379

5.3 应用Redis配置

# 部署Redis
kubectl apply -f redis.yaml

# 可选：部署IngressRouteTCP
kubectl apply -f redis-ingressroute-tcp.yaml

# 验证Redis运行状态
kubectl get pods -n redis
kubectl exec -it redis-0 -n redis -- redis-cli -a redis123456 ping

六、备选方案：部署MySQL

6.1 配置MySQL

# mysql.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: mysql-config
  namespace: mysql
data:
  my.cnf: |
    [mysqld]
    default_authentication_plugin=mysql_native_password
    character-set-server=utf8mb4
    collation-server=utf8mb4_unicode_ci
---
apiVersion: v1
kind: Secret
metadata:
  name: mysql-secret
  namespace: mysql
type: Opaque
data:
  mysql-root-password: cm9vdDEyMzQ1Ng==  # root123456 base64编码
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: mysql
  namespace: mysql
spec:
  serviceName: mysql
  replicas: 1
  selector:
    matchLabels:
      app: mysql
  template:
    metadata:
      labels:
        app: mysql
    spec:
      containers:
      - name: mysql
        image: mysql:8.0
        ports:
        - containerPort: 3306
        env:
        - name: MYSQL_ROOT_PASSWORD
          valueFrom:
            secretKeyRef:
              name: mysql-secret
              key: mysql-root-password
        volumeMounts:
        - name: mysql-data
          mountPath: /var/lib/mysql
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
  volumeClaimTemplates:
  - metadata:
      name: mysql-data
    spec:
      accessModes: [ "ReadWriteOnce" ]
      storageClassName: "local-path"
      resources:
        requests:
          storage: 20Gi
---
apiVersion: v1
kind: Service
metadata:
  name: mysql
  namespace: mysql
spec:
  selector:
    app: mysql
  ports:
  - port: 3306
    targetPort: 3306
  type: ClusterIP

6.2 配置IngressRouteTCP（可选）

# mysql-ingressroute-tcp.yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRouteTCP
metadata:
  name: mysql-ingressroute-tcp
  namespace: mysql
spec:
  entryPoints:
    - mysql-tcp  # 需在Traefik中配置此TCP入口点
  routes:
  - match: HostSNI(`*`)
    services:
    - name: mysql
      port: 3306

6.3 应用MySQL配置

# 部署MySQL（备选方案）
kubectl apply -f mysql.yaml

# 可选：部署IngressRouteTCP
kubectl apply -f mysql-ingressroute-tcp.yaml

# 验证MySQL运行状态
kubectl get pods -n mysql

七、验证部署结果

7.1 验证组件状态

# 查看所有基础组件状态
kubectl get pods -n postgres
kubectl get pods -n redis
kubectl get pods -n mysql 2>/dev/null || echo "MySQL未部署"

# 查看服务状态
kubectl get svc -n postgres
kubectl get svc -n redis
kubectl get svc -n mysql 2>/dev/null || echo "MySQL未部署"

# 查看持久化存储
kubectl get pvc -n postgres
kubectl get pvc -n redis
kubectl get pvc -n mysql 2>/dev/null || echo "MySQL未部署"

7.2 测试连接功能

# 测试PostgreSQL连接
kubectl run postgres-test --rm -it --image=postgres:15-alpine -n postgres -- \
  psql -h postgres.postgres.svc.cluster.local -U gitea -d gitea -c "SELECT 1;"

# 测试Redis连接
kubectl run redis-test --rm -it --image=redis:7-alpine -n redis -- \
  redis-cli -h redis.redis.svc.cluster.local -a redis123456 ping

# 测试MySQL连接（如部署）
kubectl run mysql-test --rm -it --image=mysql:8.0 -n mysql -- \
  mysql -h mysql.mysql.svc.cluster.local -uroot -proot123456 -e "SELECT 1;"

7.3 验证IngressRouteTCP（如配置）

# 查看IngressRouteTCP状态
kubectl get ingressroutetcps.traefik.containo.us -n postgres 2>/dev/null || echo "未配置"
kubectl get ingressroutetcps.traefik.containo.us -n redis 2>/dev/null || echo "未配置"
kubectl get ingressroutetcps.traefik.containo.us -n mysql 2>/dev/null || echo "未配置"

八、服务访问方式

8.1 集群内访问

PostgreSQL: postgres.postgres.svc.cluster.local:5432
Redis: redis.redis.svc.cluster.local:6379
MySQL: mysql.mysql.svc.cluster.local:3306

8.2 集群外访问（需配置IngressRouteTCP）

PostgreSQL: Traefik节点IP:5432（需Traefik配置postgres-tcp入口点）
Redis: Traefik节点IP:6379（需Traefik配置redis-tcp入口点）
MySQL: Traefik节点IP:3306（需Traefik配置mysql-tcp入口点）

九、日常运维命令

# 查看组件日志
kubectl logs -f postgres-0 -n postgres
kubectl logs -f redis-0 -n redis
kubectl logs -f mysql-0 -n mysql 2>/dev/null || echo "MySQL未部署"

# 重启组件
kubectl rollout restart statefulset postgres -n postgres
kubectl rollout restart statefulset redis -n redis
kubectl rollout restart statefulset mysql -n mysql 2>/dev/null || echo "MySQL未部署"

# 数据备份（PostgreSQL示例）
kubectl exec postgres-0 -n postgres -- pg_dump -U gitea gitea > gitea-backup-$(date +%Y%m%d).sql

# 进入容器调试
kubectl exec -it postgres-0 -n postgres -- /bin/bash
kubectl exec -it redis-0 -n redis -- /bin/sh
kubectl exec -it mysql-0 -n mysql -- /bin/bash 2>/dev/null || echo "MySQL未部署"

十、常见问题修复

问题现象	排查方向	修复方案
Pod一直Pending	存储类/资源不足	检查local-path存储类，确认节点有足够资源
数据库连接失败	服务发现/认证	检查Service selector，验证用户名密码
Redis认证失败	密码配置	确认redis.conf中的requirepass配置正确
数据持久化失败	PVC绑定问题	检查PVC状态：`kubectl describe pvc -n <namespace>`
IngressRouteTCP不生效	Traefik入口点配置	确认Traefik已配置对应TCP入口点

十一、配置参考

所有基础组件配置文件和部署脚本请参考：
https://gitee.com/Chemmy/kube-template/tree/master/devops

该目录包含：

PostgreSQL完整配置
Redis完整配置
MySQL完整配置
生产环境优化配置
备份和恢复脚本

总结

本文完成了GitOps环境基础组件（PostgreSQL、Redis、MySQL）的标准化部署，采用独立命名空间实现资源隔离，使用StatefulSet保障有状态服务的稳定性，通过local-path存储类实现数据持久化。

基础组件部署完成后，GitOps环境已具备完整的数据存储和缓存能力。下一篇文章将部署Gitea代码仓库，为GitOps环境提供代码托管服务。

一、核心定位

本文作为GitOps环境搭建系列的第九篇，聚焦容器镜像仓库Harbor的部署与配置。Harbor是由CNCF孵化而成的企业级开源Registry项目，提供完整的镜像存储、签名、扫描和分发能力。

在GitOps环境中，Harbor扮演”镜像存储中枢”角色，作为GitOps流程的镜像仓库环节，接收来自Tekton构建的镜像，并为ArgoCD提供可信的镜像源。Harbor与Gitea、Tekton、ArgoCD协同工作，形成完整的”代码→构建→镜像→部署”自动化流水线。

二、部署前置检查

部署前需验证K3s集群状态及前序组件运行情况：

# 1. 验证K3s集群状态
kubectl get nodes

# 2. 验证PostgreSQL运行状态
kubectl get pods -n postgres

# 3. 验证Redis运行状态
kubectl get pods -n redis

# 4. 验证Traefik运行状态
kubectl get pods -n kube-system -l app=traefik

# 5. 验证cert-manager运行状态
kubectl get pods -n cert-manager

# 6. 验证域名解析
nslookup harbor.example.io
nslookup notary.example.io

前置条件检查清单：

K3s集群运行正常
PostgreSQL数据库可用（用于存储Harbor元数据）
Redis缓存服务可用（用于Harbor会话缓存）
Traefik反向代理可用
cert-manager证书管理可用
域名harbor.example.io和notary.example.io已解析至K3s节点IP
已创建Harbor数据库和用户（如未创建，见下文步骤）

三、准备Harbor数据库

3.1 创建Harbor数据库

# 在PostgreSQL中创建Harbor数据库
kubectl exec -it postgres-0 -n postgres -- psql -U postgres -c "CREATE DATABASE harbor;"
kubectl exec -it postgres-0 -n postgres -- psql -U postgres -c "CREATE USER harbor WITH PASSWORD 'harbor123';"
kubectl exec -it postgres-0 -n postgres -- psql -U postgres -c "GRANT ALL PRIVILEGES ON DATABASE harbor TO harbor;"

3.2 创建Harbor命名空间

1 2	# 创建Harbor专属命名空间 kubectl create namespace harbor

四、配置Harbor证书

4.1 创建Harbor证书

# harbor-certificate.yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: harbor-cert
  namespace: harbor
spec:
  secretName: harbor-tls-secret
  issuerRef:
    name: selfsigned-cluster-issuer
    kind: ClusterIssuer
  commonName: harbor.example.io
  dnsNames:
  - harbor.example.io
  - notary.example.io
  duration: 2160h
  renewBefore: 360h
  privateKey:
    algorithm: RSA
    size: 2048
  usages:
  - server auth

4.2 应用证书配置

# 应用证书配置
kubectl apply -f harbor-certificate.yaml

# 验证证书状态
kubectl get certificate -n harbor
kubectl describe certificate harbor-cert -n harbor

五、标准化部署Harbor

5.1 添加Helm仓库

1
2
3

# 添加Harbor官方Helm仓库
helm repo add harbor https://helm.goharbor.io --force-update
helm repo update

5.2 创建Harbor配置

# harbor-values.yaml
# 参考：https://gitee.com/Chemmy/kube-template/blob/master/devops/Harbor/harbor-values.yaml

# 全局配置
expose:
  type: ingress
  tls:
    enabled: true
    certSource: secret
    secret:
      secretName: "harbor-tls-secret"
      notarySecretName: "harbor-tls-secret"
  ingress:
    hosts:
      core: harbor.example.io
      notary: notary.example.io
    annotations:
      kubernetes.io/ingress.class: "traefik"
      traefik.ingress.kubernetes.io/router.tls: "true"
      traefik.ingress.kubernetes.io/router.entrypoints: websecure

externalURL: https://harbor.example.io

# 管理员密码
harborAdminPassword: "HarborAdmin123!"

# 持久化存储
persistence:
  enabled: true
  resourcePolicy: "keep"
  persistentVolumeClaim:
    registry:
      storageClass: "local-path"
      accessMode: ReadWriteOnce
      size: 100Gi
    chartmuseum:
      storageClass: "local-path"
      accessMode: ReadWriteOnce
      size: 5Gi
    jobservice:
      storageClass: "local-path"
      accessMode: ReadWriteOnce
      size: 5Gi
    trivy:
      storageClass: "local-path"
      accessMode: ReadWriteOnce
      size: 5Gi

# 外部数据库配置（使用前序部署的PostgreSQL）
database:
  type: external
  external:
    host: "postgres.postgres.svc.cluster.local"
    port: "5432"
    username: "harbor"
    password: "harbor123"
    coreDatabase: "harbor"
    clairDatabase: "harbor_clair"
    notaryServerDatabase: "harbor_notary_server"
    notarySignerDatabase: "harbor_notary_signer"

# 外部Redis配置
redis:
  type: external
  external:
    addr: "redis.redis.svc.cluster.local:6379"
    password: "redis123456"

# 启用ChartMuseum
chartmuseum:
  enabled: true
  resources:
    requests:
      memory: "256Mi"
      cpu: "250m"
    limits:
      memory: "512Mi"
      cpu: "500m"

# 启用Trivy漏洞扫描
trivy:
  enabled: true
  resources:
    requests:
      memory: "512Mi"
      cpu: "250m"
    limits:
      memory: "1Gi"
      cpu: "500m"

# 资源限制
nginx:
  resources:
    requests:
      memory: "128Mi"
      cpu: "100m"
    limits:
      memory: "256Mi"
      cpu: "200m"

portal:
  resources:
    requests:
      memory: "128Mi"
      cpu: "100m"
    limits:
      memory: "256Mi"
      cpu: "200m"

core:
  resources:
    requests:
      memory: "256Mi"
      cpu: "250m"
    limits:
      memory: "512Mi"
      cpu: "500m"

jobservice:
  resources:
    requests:
      memory: "256Mi"
      cpu: "250m"
    limits:
      memory: "512Mi"
      cpu: "500m"

registry:
  registry:
    resources:
      requests:
        memory: "256Mi"
        cpu: "250m"
      limits:
        memory: "512Mi"
        cpu: "500m"

notary:
  enabled: true
  server:
    resources:
      requests:
        memory: "128Mi"
        cpu: "100m"
      limits:
        memory: "256Mi"
      cpu: "200m"
  signer:
    resources:
      requests:
        memory: "128Mi"
        cpu: "100m"
      limits:
        memory: "256Mi"
        cpu: "200m"

5.3 部署Harbor

# 部署Harbor
helm install harbor harbor/harbor \
  --namespace harbor \
  --version 1.13.2 \
  -f harbor-values.yaml

# 或使用在线配置
helm install harbor harbor/harbor \
  --namespace harbor \
  --version 1.13.2 \
  --set expose.type=ingress \
  --set expose.tls.enabled=true \
  --set expose.tls.secret.secretName=harbor-tls-secret \
  --set expose.ingress.hosts.core=harbor.example.io \
  --set expose.ingress.hosts.notary=notary.example.io \
  --set externalURL=https://harbor.example.io \
  --set harborAdminPassword=HarborAdmin123! \
  --set persistence.enabled=true \
  --set persistence.persistentVolumeClaim.registry.storageClass=local-path \
  --set persistence.persistentVolumeClaim.registry.size=100Gi \
  --set database.type=external \
  --set database.external.host=postgres.postgres.svc.cluster.local \
  --set database.external.port=5432 \
  --set database.external.username=harbor \
  --set database.external.password=harbor123 \
  --set redis.type=external \
  --set redis.external.addr=redis.redis.svc.cluster.local:6379 \
  --set redis.external.password=redis123456 \
  --set chartmuseum.enabled=true \
  --set trivy.enabled=true \
  --set notary.enabled=true

六、验证部署结果

6.1 验证组件状态

# 查看Harbor Pod状态（首次启动需要2-3分钟）
kubectl get pods -n harbor -w

# 查看Service状态
kubectl get svc -n harbor

# 查看Ingress状态
kubectl get ingress -n harbor

# 查看证书状态
kubectl get certificate -n harbor

# 查看PVC状态
kubectl get pvc -n harbor

6.2 测试访问功能

# 等待Harbor完全启动
sleep 120

# 测试HTTPS访问
curl -k https://harbor.example.io

# 查看Harbor日志
kubectl logs -n harbor -l app=harbor --tail=50

# 测试Notary访问
curl -k https://notary.example.io

6.3 初始化Harbor

浏览器访问：https://harbor.example.io
用户名：admin
密码：HarborAdmin123!
首次登录后立即修改密码
创建项目（如gitops-demo）

七、配置容器运行时访问

7.1 Docker客户端配置

# 获取Harbor CA证书
kubectl get secret harbor-tls-secret -n harbor -o jsonpath='{.data.ca\.crt}' | base64 --decode > harbor-ca.crt

# 配置Docker信任Harbor证书
sudo mkdir -p /etc/docker/certs.d/harbor.example.io
sudo cp harbor-ca.crt /etc/docker/certs.d/harbor.example.io/ca.crt
sudo systemctl restart docker

# 登录Harbor
docker login harbor.example.io -u admin -p HarborAdmin123!

7.2 Containerd配置（K3s节点）

# 配置Containerd信任Harbor证书
sudo mkdir -p /etc/containerd/certs.d/harbor.example.io
sudo cp harbor-ca.crt /etc/containerd/certs.d/harbor.example.io/ca.crt
sudo systemctl restart containerd

7.3 测试镜像推送

# 拉取测试镜像
docker pull alpine:latest

# 打标签
docker tag alpine:latest harbor.example.io/gitops-demo/alpine:latest

# 推送镜像
docker push harbor.example.io/gitops-demo/alpine:latest

八、Harbor与GitOps全链路集成

完成Harbor部署后，GitOps环境搭建系列已具备完整的端到端交付能力。以下阐述Harbor与系列中其他核心组件的联动关系。

8.1 全链路组件矩阵

组件	职责	在GitOps链路中的角色
Gitea	代码托管与版本控制	开发者推送代码的单一可信数据源
Tekton	云原生CI/CD流水线引擎	监听代码变更，构建镜像并推送至Harbor
Harbor	容器镜像仓库与安全扫描	存储签名镜像，提供可信镜像分发
ArgoCD	GitOps持续部署控制平面	监听Harbor镜像Tag变化，自动同步至K3s

8.2 完整流水线联动流程

┌─────────────────────────────────────────────────────────────────┐
│                     GitOps 完整链路                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ① 开发者 ──push──▶ Gitea (Git仓库)                              │
│                                                                  │
│  ② Tekton Pipeline ──webhook触发──▶ 克隆代码                     │
│                                                                  │
│  ③ Tekton Pipeline ──构建──▶ Docker镜像                         │
│           │                                                        │
│           │ docker push                                           │
│           ▼                                                        │
│  ④ Harbor (镜像仓库) ◀── 推送镜像                                 │
│      │  • 存储镜像bits                                            │
│      │  • Trivy CVE扫描                                          │
│      │  • Notary镜像签名（可选）                                   │
│                                                                  │
│  ⑤ ArgoCD Application ──监听镜像Tag变化──▶ 检测到新镜像          │
│           │                                                        │
│           │ 更新Deployment镜像Tag                                  │
│           ▼                                                        │
│  ⑥ K3s集群 ──kubectl apply──▶ 新Pod以新镜像启动                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

8.3 Harbor与Gitea、Tekton、ArgoCD联动

Harbor + Gitea（认证集成）

Harbor与Gitea可共用外部认证源（如LDAP/OIDC），实现统一身份管理：

# Harbor配置外部认证
harbor-core:
  config:
    auth_mode: "oidc_auth"
    oidc_name: "Gitea OIDC"
    oidc_endpoint: "https://gitea.example.io/oauth"
    oidc_client_id: "harbor-client"
    oidc_secret: "harbor-oidc-secret"

Harbor + Tekton（镜像构建推送）

Tekton Pipeline执行构建并将镜像推送至Harbor：

# Tekton Task: 构建并推送镜像至Harbor
spec:
  steps:
    - name: git-clone
      image: alpine/git
      script: |
        git clone $(params.REPO_URL) $(params.REPO_DIR)

    - name: build-image
      image: docker:latest
      script: |
        docker build -t $(params.IMAGE):$(params.TAG) $(params.REPO_DIR)
        docker tag $(params.IMAGE):$(params.TAG) \
          harbor.example.io/gitops-demo/$(params.IMAGE):$(params.TAG)

    - name: push-image
      image: docker:latest
      script: |
        docker login harbor.example.io -u $(params.HARBOR_USER) -p $(params.HARBOR_PASS)
        docker push harbor.example.io/gitops-demo/$(params.IMAGE):$(params.TAG)

Harbor + ArgoCD（镜像驱动部署）

ArgoCD Image Updater自动轮询Harbor镜像仓库，发现新Tag后更新配置并触发同步：

# ArgoCD Application（Image Updater注解）
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: gitops-demo-app
  annotations:
    argocd-image-updater.argoproj.io/image-list: |
      demo=harbor.example.io/gitops-demo/demo-image
    argocd-image-updater.argoproj.io/demo.update-strategy: latest
    argocd-image-updater.argoproj.io/write-back-method: git
spec:
  source:
    repoURL: https://github.com/your-org/gitops-configs.git
    path: apps/demo-app
    targetRevision: main
  destination:
    server: https://kubernetes.default.svc
    namespace: gitops-demo

8.4 安全集成要点

镜像签名链路：Tekton构建 → Notary签名 → 推送Harbor → 部署时验签，全链路可信；
漏洞扫描卡点：Harbor Trivy扫描未通过的CVE镜像（Critical/High），可配置阻止推送；
认证打通：Harbor与Gitea共用OIDC认证，实现统一身份管理；
网络隔离：Harbor仅通过Traefik 443端口暴露，K3s节点通过内部网络拉取镜像。

九、服务访问方式

9.1 集群内访问

Web界面：harbor-core.harbor.svc.cluster.local
Registry API：harbor-registry.harbor.svc.cluster.local
ChartMuseum：harbor-chartmuseum.harbor.svc.cluster.local

9.2 集群外访问

Web界面：https://harbor.example.io
Registry：harbor.example.io（Docker push/pull）
Notary：https://notary.example.io

十、日常运维命令

# 查看Harbor状态
kubectl get all -n harbor

# 查看日志
kubectl logs -f deployment/harbor-core -n harbor
kubectl logs -f deployment/harbor-registry -n harbor
kubectl logs -f deployment/harbor-portal -n harbor

# 重启组件
kubectl rollout restart deployment -n harbor

# 备份Harbor数据
kubectl exec -n harbor $(kubectl get pod -n harbor -l component=registry -o jsonpath='{.items[0].metadata.name}') -- tar czf /tmp/registry-backup.tar.gz /storage
kubectl cp harbor/$(kubectl get pod -n harbor -l component=registry -o jsonpath='{.items[0].metadata.name}'):/tmp/registry-backup.tar.gz ./registry-backup-$(date +%Y%m%d).tar.gz

# 查看资源使用情况
kubectl top pods -n harbor

十一、常见问题修复

问题现象	排查方向	修复方案
Harbor无法启动	数据库连接失败	检查PostgreSQL连接，验证用户名密码
证书错误	证书配置/Secret	检查cert-manager状态，验证证书Secret
镜像推送失败	认证/网络	检查Docker登录状态，验证网络连通性
PVC无法绑定	存储类/磁盘空间	检查local-path存储类，确认节点有足够空间
Trivy扫描失败	网络/资源	检查Trivy网络连通性，增加资源限制
Notary服务异常	证书/配置	检查Notary证书配置，验证域名解析

十二、配置参考

所有Harbor配置文件和部署脚本请参考：
https://gitee.com/Chemmy/kube-template/tree/master/devops/Harbor

该目录包含：

Harbor Helm values配置
证书和路由配置
数据库初始化脚本
生产环境优化配置
集成配置示例

总结

本文完成了Harbor在K3s集群中的标准化部署，实现了镜像仓库的完整功能。Harbor作为GitOps环境的镜像存储中枢，为自动化构建和部署提供了可靠的镜像管理能力。

部署完成后，建议配置Tekton Pipeline实现自动镜像构建和推送，配置ArgoCD实现镜像更新自动同步。至此，GitOps环境的所有核心组件已部署完成，形成了完整的自动化流水线。

一、核心定位

本文作为GitOps环境搭建系列的第八篇，聚焦Tekton CI/CD流水线的部署与配置。Tekton是云原生CI/CD框架，专为Kubernetes环境设计，提供声明式的流水线定义和任务执行能力。

在GitOps环境中，Tekton扮演”持续集成引擎”角色，作为GitOps流程的构建和测试环节，实现从代码提交到镜像构建的自动化。Tekton与Gitea、Harbor、ArgoCD协同工作，形成完整的”代码→构建→镜像→部署”自动化流水线。

二、部署前置检查

部署前需验证K3s集群状态及前序组件运行情况：

# 1. 验证K3s集群状态
kubectl get nodes

# 2. 验证ArgoCD运行状态
kubectl get pods -n argocd

# 3. 验证cert-manager运行状态
kubectl get pods -n cert-manager

# 4. 验证Traefik运行状态
kubectl get pods -n kube-system -l app=traefik

# 5. 验证Gitea运行状态
kubectl get pods -n gitea

# 6. 验证域名解析
nslookup tekton.example.io

前置条件检查清单：

K3s集群运行正常
ArgoCD GitOps核心可用
cert-manager证书管理可用
Traefik反向代理可用
Gitea代码仓库可用
域名tekton.example.io已解析至K3s节点IP
Git仓库https://gitea.example.io/gitea_admin/devops-deploy.git已创建并包含Tekton配置

三、基于ArgoCD部署Tekton

3.1 准备Git仓库配置

在Gitea仓库devops-deploy.git中创建Tekton配置目录：

# 克隆仓库
git clone https://gitea.example.io/gitea_admin/devops-deploy.git
cd devops-deploy

# 创建Tekton配置目录
mkdir -p tekton

3.2 创建ArgoCD应用配置

# tekton/argocd-application.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: tekton
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://gitea.example.io/gitea_admin/devops-deploy.git
    path: tekton
    targetRevision: HEAD
  destination:
    server: https://kubernetes.default.svc
    namespace: tekton-pipelines
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
    retry:
      limit: 5
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m

3.3 创建Tekton核心部署配置

# tekton/tekton-core.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: tekton-pipelines
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: tekton-dashboard
  namespace: tekton-pipelines
spec:
  replicas: 1
  selector:
    matchLabels:
      app: tekton-dashboard
  template:
    metadata:
      labels:
        app: tekton-dashboard
    spec:
      containers:
      - name: dashboard
        image: gcr.io/tekton-releases/github.com/tektoncd/dashboard/cmd/dashboard:v0.45.0
        ports:
        - containerPort: 9097
        env:
        - name: PORT
          value: "9097"
        - name: CLUSTER_NAME
          value: "k3s-gitops"
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "256Mi"
            cpu: "200m"
---
apiVersion: v1
kind: Service
metadata:
  name: tekton-dashboard
  namespace: tekton-pipelines
spec:
  selector:
    app: tekton-dashboard
  ports:
  - port: 9097
    targetPort: 9097
  type: ClusterIP

3.4 提交配置到Git仓库

# 添加配置文件
git add tekton/
git commit -m "feat: add Tekton deployment configuration"
git push origin main

四、配置HTTPS访问

4.1 创建Tekton证书

# tekton/tekton-certificate.yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: tekton-cert
  namespace: tekton-pipelines
spec:
  secretName: tekton-tls-secret
  issuerRef:
    name: selfsigned-cluster-issuer
    kind: ClusterIssuer
  commonName: tekton.example.io
  dnsNames:
  - tekton.example.io
  duration: 2160h
  renewBefore: 360h
  privateKey:
    algorithm: RSA
    size: 2048
  usages:
  - server auth

4.2 配置IngressRoute

# tekton/tekton-ingressroute.yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: tekton-websecure
  namespace: tekton-pipelines
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`tekton.example.io`) && PathPrefix(`/`)
      kind: Rule
      services:
        - name: tekton-dashboard
          passHostHeader: true
          port: 9097
  tls:
    secretName: tekton-tls-secret

4.3 应用ArgoCD配置

# 应用ArgoCD Application配置
kubectl apply -f tekton/argocd-application.yaml

# 或直接创建Application
cat <<EOF | kubectl apply -f -
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: tekton
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://gitea.example.io/gitea_admin/devops-deploy.git
    path: tekton
    targetRevision: HEAD
  destination:
    server: https://kubernetes.default.svc
    namespace: tekton-pipelines
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
EOF

五、验证部署结果

5.1 验证ArgoCD同步状态

# 查看ArgoCD应用状态
argocd app get tekton
argocd app sync tekton  # 手动触发同步

# 查看同步历史
argocd app history tekton

# 查看应用资源
argocd app resources tekton

5.2 验证Tekton组件状态

# 查看Tekton命名空间资源
kubectl get all -n tekton-pipelines

# 查看Dashboard Pod状态
kubectl get pods -n tekton-pipelines -l app=tekton-dashboard

# 查看Service状态
kubectl get svc -n tekton-pipelines tekton-dashboard

# 查看证书状态
kubectl get certificate -n tekton-pipelines
kubectl describe certificate tekton-cert -n tekton-pipelines

# 查看IngressRoute状态
kubectl get ingressroute -n tekton-pipelines

5.3 测试访问功能

# 测试HTTPS访问
curl -k https://tekton.example.io

# 查看Dashboard日志
kubectl logs -n tekton-pipelines -l app=tekton-dashboard --tail=50

# 进入容器检查状态
kubectl exec -it $(kubectl get pod -n tekton-pipelines -l app=tekton-dashboard -o jsonpath='{.items[0].metadata.name}') -n tekton-pipelines -- /bin/sh

六、配置示例流水线

6.1 创建Tekton Pipeline资源

# tekton/example-pipeline.yaml
apiVersion: tekton.dev/v1beta1
kind: Pipeline
metadata:
  name: build-and-deploy
  namespace: tekton-pipelines
spec:
  params:
  - name: git-url
    type: string
    description: Git repository URL
  - name: image-name
    type: string
    description: Docker image name
  tasks:
  - name: fetch-source
    taskRef:
      name: git-clone
    params:
    - name: url
      value: $(params.git-url)
    - name: revision
      value: main
    workspaces:
    - name: output
      workspace: source
      
  - name: build-image
    runAfter: [fetch-source]
    taskRef:
      name: kaniko
    params:
    - name: IMAGE
      value: $(params.image-name)
    workspaces:
    - name: source
      workspace: source
    - name: dockerconfig
      workspace: docker-config

6.2 创建Tekton Task资源

# tekton/tasks.yaml
apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: git-clone
  namespace: tekton-pipelines
spec:
  workspaces:
  - name: output
    description: Git repository will be cloned here
  params:
  - name: url
    description: Git repository URL
    type: string
  - name: revision
    description: Git revision to clone
    type: string
    default: main
  steps:
  - name: clone
    image: alpine/git
    script: |
      git clone $(params.url) $(workspaces.output.path)
      cd $(workspaces.output.path)
      git checkout $(params.revision)
---
apiVersion: tekton.dev/v1beta1
kind: Task
metadata:
  name: kaniko
  namespace: tekton-pipelines
spec:
  workspaces:
  - name: source
    description: Source code workspace
  - name: dockerconfig
    description: Docker config.json workspace
  params:
  - name: IMAGE
    description: Docker image name
    type: string
  steps:
  - name: build-and-push
    image: gcr.io/kaniko-project/executor:v1.9.0
    env:
    - name: DOCKER_CONFIG
      value: /workspace/dockerconfig
    command:
    - /kaniko/executor
    args:
    - --dockerfile=$(workspaces.source.path)/Dockerfile
    - --destination=$(params.IMAGE)
    - --context=$(workspaces.source.path)

七、服务访问方式

7.1 集群内访问

Dashboard Web界面：tekton-dashboard.tekton-pipelines.svc.cluster.local:9097
API访问：通过Service直接访问Tekton组件

7.2 集群外访问

Dashboard Web界面：https://tekton.example.io
Git Webhook配置：https://tekton.example.io（用于接收Gitea webhook）

八、日常运维命令

# 查看Tekton资源
kubectl get pipelines.tekton.dev -n tekton-pipelines
kubectl get tasks.tekton.dev -n tekton-pipelines
kubectl get pipelineruns.tekton.dev -n tekton-pipelines
kubectl get taskruns.tekton.dev -n tekton-pipelines

# 查看Dashboard日志
kubectl logs -f deployment/tekton-dashboard -n tekton-pipelines

# 重启Dashboard
kubectl rollout restart deployment tekton-dashboard -n tekton-pipelines

# 查看资源使用情况
kubectl top pods -n tekton-pipelines

# 清理完成的PipelineRun
kubectl delete pipelineruns.tekton.dev --all -n tekton-pipelines --field-selector=status.conditions[0].status=True

九、常见问题修复

问题现象	排查方向	修复方案
ArgoCD同步失败	Git仓库访问权限	检查ArgoCD Repository配置，添加访问凭证
Dashboard无法访问	IngressRoute/证书	检查IngressRoute配置，验证证书Secret是否存在
Pipeline执行失败	任务配置/资源权限	检查Task定义，验证ServiceAccount权限
镜像构建失败	Docker配置/网络	检查kaniko配置，验证网络连通性
Webhook不触发	Webhook配置/网络	检查Gitea webhook配置，验证网络可达性
资源占用过高	资源限制/并发数	调整资源限制，限制并发PipelineRun数量

十、配置参考

所有Tekton配置文件和部署脚本请参考：
https://gitee.com/Chemmy/kube-template/tree/master/devops/Tekton

该目录包含：

Tekton核心部署配置
示例Pipeline和Task定义
Webhook集成配置
生产环境优化配置
监控和日志配置

总结

本文完成了Tekton在K3s集群中的标准化部署，基于ArgoCD实现了GitOps方式的CI/CD流水线管理。Tekton作为GitOps环境的持续集成引擎，为自动化构建和测试提供了强大的能力。

部署完成后，建议创建示例流水线验证构建功能，配置Gitea webhook实现自动触发，并设置适当的资源限制。下一篇文章将部署Harbor镜像仓库，为GitOps环境提供镜像存储和分发能力。

一、核心定位

本文作为GitOps环境搭建系列的第七篇，聚焦核心组件ArgoCD的部署与配置。ArgoCD是Argo Project开源的声明式GitOps持续部署工具，专为Kubernetes应用部署与生命周期管理设计。

在GitOps环境中，ArgoCD扮演”部署自动化中枢”角色，作为GitOps流程的核心执行引擎，实现”Git为单一可信数据源”的理念。ArgoCD自动对比Git仓库中的期望状态与K3s集群中的实际状态，完成配置同步与部署，实现从代码到部署的完整自动化。

二、部署前置检查

部署前需验证K3s集群状态及前序组件运行情况：

# 1. 验证K3s集群状态
kubectl get nodes

# 2. 验证Traefik运行状态
kubectl get pods -n kube-system -l app=traefik

# 3. 验证cert-manager运行状态
kubectl get pods -n cert-manager

# 4. 验证Gitea运行状态
kubectl get pods -n gitea

# 5. 验证Helm可用性
helm version --short

# 6. 验证域名解析
nslookup argocd.example.io

前置条件检查清单：

K3s集群运行正常
Traefik反向代理可用
cert-manager证书管理可用
Gitea代码仓库可用（可选，用于测试）
域名argocd.example.io已解析至K3s节点IP
Helm工具可用

三、标准化部署ArgoCD

3.1 环境准备

3.1.1 添加ArgoCD Helm仓库

1
2
3

# 添加ArgoCD官方Helm仓库
helm repo add argo https://argoproj.github.io/argo-helm --force-update
helm repo update

3.1.2 创建命名空间

1 2	# 创建ArgoCD专属命名空间 kubectl create namespace argocd

3.2 编写配置文件

创建argocd-values.yaml配置文件：

# argocd-values.yaml
# 参考：https://gitee.com/Chemmy/kube-template/blob/master/devops/ArgoCD/argocd-values.yaml

## 全局配置
global:
  # 设置访问域名为 argocd.example.io
  domain: argocd.example.io

## Argo CD 核心配置
configs:
  cm:
    # 启用本地 admin 用户
    admin.enabled: true

  params:
    # 禁用 Argo CD Server 的 HTTPS，让 Traefik 处理 TLS
    server.insecure: "true"

## Server 配置
server:
  # 启用 Ingress，由 Traefik 接管
  ingress:
    enabled: true
    # 指定 IngressClass 为 traefik（K3s 默认）
    annotations:
      traefik.ingress.kubernetes.io/router.tls: "true"
      traefik.ingress.kubernetes.io/router.entrypoints: websecure
    ingressClassName: "traefik"
    hosts:
      - argocd.example.io

  service:
    # 使用 ClusterIP，Traefik 通过 Service 发现后端
    type: ClusterIP

## Redis（Argo CD 必需，保持启用）
redis:
  enabled: true

## 关闭通知模块节省资源
notifications:
  enabled: false

## Dex（如无需 SSO 登录，可关闭以节省资源）
dex:
  enabled: false

## 其他组件保持默认
crds:
  install: true
  keep: true

3.3 一键部署ArgoCD

# 部署ArgoCD
helm install argocd argo/argo-cd \
  --namespace argocd \
  --version 9.4.1 \
  -f argocd-values.yaml

# 或使用在线配置
helm install argocd argo/argo-cd \
  --namespace argocd \
  --version 9.4.1 \
  --set global.domain=argocd.example.io \
  --set server.ingress.enabled=true \
  --set server.ingress.ingressClassName=traefik \
  --set server.ingress.hosts[0]=argocd.example.io \
  --set server.insecure=true \
  --set notifications.enabled=false \
  --set dex.enabled=false

3.4 验证部署状态

# 查看ArgoCD Pod状态
kubectl get pods -n argocd -w

# 查看Ingress资源
kubectl get ingress -n argocd

# 查看ArgoCD服务状态
kubectl get svc -n argocd

# 查看部署完成状态
kubectl wait --for=condition=Ready pods -l app.kubernetes.io/name=argocd-server -n argocd --timeout=300s

四、配置HTTPS访问

4.1 创建ArgoCD证书

# argocd-certificate.yaml
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: argocd-cert
  namespace: argocd
spec:
  secretName: argocd-tls-secret
  issuerRef:
    name: selfsigned-cluster-issuer
    kind: ClusterIssuer
  commonName: argocd.example.io
  dnsNames:
  - argocd.example.io
  duration: 2160h
  renewBefore: 360h
  privateKey:
    algorithm: RSA
    size: 2048
  usages:
  - server auth

4.2 配置IngressRoute

# argocd-ingressroute.yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: argocd-websecure
  namespace: argocd
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`argocd.example.io`) && PathPrefix(`/`)
      kind: Rule
      services:
        - name: argocd-server
          passHostHeader: true
          port: 80
  tls:
    secretName: argocd-tls-secret

4.3 应用HTTPS配置

# 应用证书和路由配置
kubectl apply -f argocd-certificate.yaml
kubectl apply -f argocd-ingressroute.yaml

# 验证证书状态
kubectl get certificate -n argocd
kubectl describe certificate argocd-cert -n argocd

五、访问与初始化ArgoCD

5.1 获取初始密码

# 获取初始管理员密码
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d && echo

# 或使用更安全的方式
ARGOCD_PASSWORD=$(kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d)
echo "ArgoCD初始密码: $ARGOCD_PASSWORD"

5.2 访问ArgoCD Web UI

浏览器访问：https://argocd.example.io
用户名：admin
密码：使用上述获取的初始密码
首次登录后立即修改密码（User Info → Update Password）

5.3 CLI工具安装与配置（可选）

# Linux系统安装ArgoCD CLI
curl -sSL -o argocd-linux-amd64 https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
sudo install -m 755 argocd-linux-amd64 /usr/local/bin/argocd
rm -f argocd-linux-amd64

# 验证安装
argocd version --client

# 登录ArgoCD
argocd login argocd.example.io --grpc-web --username admin --password $ARGOCD_PASSWORD

# 或使用token登录（更安全）
argocd account generate-token --account admin

六、验证部署结果

6.1 验证组件状态

# 查看所有ArgoCD组件状态
kubectl get all -n argocd

# 查看证书和路由状态
kubectl get certificate,ingressroute -n argocd

# 查看ArgoCD日志
kubectl logs -n argocd -l app.kubernetes.io/name=argocd-server --tail=50

# 测试HTTPS访问
curl -k https://argocd.example.io

6.2 测试GitOps功能

# 创建测试应用（使用Gitea仓库）
cat > test-application.yaml << EOF
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: test-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://gitea.example.io/gitea_admin/test-repo.git
    targetRevision: HEAD
    path: k8s/
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
EOF

# 应用测试配置
kubectl apply -f test-application.yaml

# 查看应用状态
kubectl get application -n argocd
argocd app get test-app

6.3 清理测试资源

1 2	# 清理测试应用 kubectl delete -f test-application.yaml

七、生产环境配置建议

7.1 安全加固

# 在argocd-values.yaml中添加安全配置
server:
  extraArgs:
    - --insecure
    - --disable-auth
    - --rootpath=/argocd
  ingress:
    annotations:
      traefik.ingress.kubernetes.io/whitelist-source-range: "192.168.0.0/16,10.0.0.0/8"
      traefik.ingress.kubernetes.io/rate-limit: "10"

7.2 资源优化

# 调整资源限制
controller:
  resources:
    requests:
      memory: "256Mi"
      cpu: "250m"
    limits:
      memory: "512Mi"
      cpu: "500m"

server:
  resources:
    requests:
      memory: "256Mi"
      cpu: "250m"
    limits:
      memory: "512Mi"
      cpu: "500m"

repoServer:
  resources:
    requests:
      memory: "256Mi"
      cpu: "250m"
    limits:
      memory: "512Mi"
      cpu: "500m"

7.3 监控配置

# 启用监控
controller:
  metrics:
    enabled: true
    serviceMonitor:
      enabled: true

server:
  metrics:
    enabled: true

八、日常运维命令

# 查看ArgoCD状态
argocd version
argocd cluster list

# 管理应用
argocd app list
argocd app get <app-name>
argocd app sync <app-name>
argocd app history <app-name>
argocd app rollback <app-name> --id <revision-id>

# 管理项目
argocd proj list
argocd proj get <project-name>

# 查看日志
kubectl logs -f deployment/argocd-server -n argocd
kubectl logs -f deployment/argocd-repo-server -n argocd
kubectl logs -f deployment/argocd-application-controller -n argocd

# 重启组件
kubectl rollout restart deployment argocd-server -n argocd
kubectl rollout restart deployment argocd-repo-server -n argocd
kubectl rollout restart deployment argocd-application-controller -n argocd

九、常见问题修复

问题现象	排查方向	修复方案
无法访问Web UI	域名解析/IngressRoute	检查域名解析，验证IngressRoute配置，查看Traefik日志
证书警告或错误	证书签发/Secret	检查cert-manager状态，验证证书Secret是否存在
无法同步Git仓库	网络/认证	检查网络连通性，配置SSH密钥或访问令牌
资源同步失败	权限/资源配置	检查ServiceAccount权限，验证资源配置格式
CLI登录失败	网络/认证	检查网络代理，验证用户名密码，使用–grpc-web参数
内存占用过高	资源限制/应用数量	调整资源限制，减少监控的应用数量

十、配置参考

所有ArgoCD配置文件和部署脚本请参考：
https://gitee.com/Chemmy/kube-template/tree/master/devops/ArgoCD

该目录包含：

ArgoCD Helm values配置
证书和路由配置
生产环境优化配置
示例应用配置
监控和备份脚本

总结

本文完成了ArgoCD在K3s集群中的标准化部署，实现了GitOps核心组件的完整功能。ArgoCD作为GitOps环境的核心执行引擎，为自动化部署提供了强大的能力。

部署完成后，建议创建测试应用验证同步功能，配置自动同步策略，并设置适当的资源限制。下一篇文章将部署Tekton CI流水线，为GitOps环境提供持续集成能力。

麒麟V10系统配置NVIDIA显卡驱动及DockerGPU支持

发表于 2026-03-25 更新于 2026-04-28

本文档基于一篇关于在 Kylin V10 上安装 NVIDIA 驱动、CUDA 和 Docker 的实践笔记整理，旨在为使用 NVIDIA GeForce RTX 3060 Ti 显卡的用户提供清晰的离线安装与配置步骤。

1. 系统环境确认

首先，确认您的操作系统版本。

1	cat /etc/kylin-release

预期输出应类似 Kylin Linux Advanced Server release V10 (Sword)。

2. 安装 NVIDIA 显卡驱动

步骤 1：禁用系统自带的开源驱动 (nouveau)

编辑黑名单配置文件：

1	sudo vi /usr/lib/modprobe.d/dist-blacklist.conf

找到 blacklist nvidiafb 一行，在行首添加 # 将其注释掉。

在文件末尾添加以下两行内容：

1 2	blacklist nouveau options nouveau modeset=0

保存并退出编辑器。

步骤 2：卸载开源驱动模块并重启

1 2	sudo rmmod nouveau sudo reboot

步骤 3：安装驱动编译依赖
重启后，安装编译 NVIDIA 驱动所需的内核开发包和工具。

1	sudo dnf install gcc kernel-devel-$(uname -r) kernel-headers-$(uname -r) make elfutils-libelf-devel tar bzip2 dkms acpid wget -y

步骤 4：下载并安装官方驱动

下载驱动：访问 NVIDIA 官方驱动下载页面。选择产品类型为 GeForce RTX 3060 Ti，操作系统选择 Linux 64-bit，点击“搜索”并下载推荐的驱动版本（例如 550 或 575 系列）。将下载的 .run 文件（如 NVIDIA-Linux-x86_64-550.90.07.run）上传到服务器。

安装驱动：

# 赋予安装脚本执行权限
chmod +x NVIDIA-Linux-x86_64-*.run
# 运行安装程序，按照提示操作（通常选择默认选项即可）
sudo ./NVIDIA-Linux-x86_64-*.run

验证安装：安装完成后，运行以下命令检查显卡是否被正确识别。
1
nvidia-smi
如果看到显卡型号、驱动版本和 GPU 状态信息，则表示驱动安装成功。

3. 安装 CUDA 工具包

CUDA 是进行 GPU 计算的基础平台。

下载 CUDA：访问 NVIDIA CUDA 下载页面。选择操作系统为 Linux -> x86_64 -> Kylin -> 10 -> rpm (local)。页面会生成安装命令。

执行安装命令：复制页面提供的命令在终端中执行，例如：

wget https://developer.download.nvidia.com/compute/cuda/repos/kylin10/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update
sudo apt-get -y install cuda

注意：实际命令请以官网生成的最新命令为准。

配置环境变量：

1
2
3

echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

验证安装：
1
nvcc -V
此命令应输出已安装的 CUDA 版本号。

4. 离线安装 Docker 并配置 GPU 支持

步骤 1：离线安装 Docker
请参考笔记麒麟V10离线安装Docker 中详细的分架构（x86_64）离线安装步骤。该指南提供了从外网准备 RPM 包到内网服务器安装、启动和验证的完整流程。请确保按照该指南完成 Docker 的离线安装，并成功运行 docker --version 和 docker ps 命令进行验证。

步骤 2：安装 NVIDIA Container Toolkit (为 Docker 添加 GPU 支持)
这是让 Docker 容器能够使用宿主 GPU 的关键步骤。

配置仓库并安装：

distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit

配置 Docker 使用 NVIDIA 作为默认运行时：

1 2	sudo nvidia-ctk runtime configure --runtime=docker sudo systemctl restart docker

验证 Docker GPU 支持：
运行一个测试容器，检查容器内是否能识别到 GPU。
1
sudo docker run --rm --gpus all nvidia/cuda:12.1.1-base-ubuntu22.04 nvidia-smi
如果此命令在容器内成功输出了与宿主机 nvidia-smi 类似的 GPU 信息，则表明 Docker 已成功配置 GPU 支持，您的 RTX 3060 Ti 现在可以在容器中用于加速计算任务（如 AI 训练、图形渲染等）。

总结

整个过程可以概括为：禁用开源驱动 -> 安装 NVIDIA 官方驱动 -> 安装 CUDA 计算平台 -> 参考专用指南离线安装 Docker 引擎 -> 为 Docker 安装 NVIDIA 容器工具包。完成这些步骤后，您的麒麟 V10 系统就具备了完整的 NVIDIA GPU 计算与容器化支持环境。

Nexus与Harbor镜像仓库文件服务功能解析与深度对比

发表于 2026-03-17 更新于 2026-04-28

在容器化与微服务架构日益普及的今天，镜像仓库作为DevOps流程中的关键环节，承担着镜像存储、分发与管理的重任。Nexus Repository Manager（Nexus）与Harbor作为两款主流的镜像仓库解决方案，各自拥有独特的文件服务能力。本文将从功能特性、应用场景、性能优化及实践建议四个维度，深度剖析这两款工具的镜像仓库文件服务。

一、Nexus镜像仓库文件服务解析

1.1 多格式支持与存储管理

Nexus Repository Manager以其强大的多格式支持能力著称，不仅支持Docker镜像，还兼容Maven、npm、PyPI等多种包管理格式。这种多格式兼容性使得Nexus成为跨技术栈团队的首选。

在文件服务层面，Nexus通过智能存储引擎，实现了镜像与包文件的高效存储与检索。其支持分层存储，可根据文件类型、访问频率等维度自动优化存储策略，提升I/O性能。Nexus的存储架构支持多种后端存储，包括本地文件系统、S3兼容对象存储等，提供了灵活的存储选择。

1.2 安全与权限控制

安全是镜像仓库的核心考量。Nexus提供了细粒度的权限控制机制，支持基于角色（RBAC）的访问控制，可精确到仓库、组、项目等层级。管理员可以创建自定义角色，为不同团队或项目分配适当的访问权限。

同时，Nexus集成了LDAP/Active Directory等身份认证服务，便于与企业现有安全体系集成。在文件传输层面，Nexus支持HTTPS加密传输，确保镜像数据在传输过程中的安全性。此外，Nexus还支持内容验证，确保上传文件的完整性。

1.3 自动化与集成能力

Nexus通过REST API与CI/CD工具链深度集成，支持自动化镜像上传、下载与版本控制。例如，在Jenkins流水线中，可通过Nexus插件直接推送构建完成的镜像至Nexus仓库，实现构建-测试-部署的全自动化。

此外，Nexus还支持Webhook机制，可在镜像状态变更时触发自定义操作，如通知、备份等。其丰富的插件生态系统进一步扩展了功能边界，支持与各种开发工具和平台的集成。

二、Harbor镜像仓库文件服务解析

2.1 专为容器设计的文件服务

Harbor作为一款专为容器镜像设计的仓库解决方案，其文件服务紧密围绕容器生态构建。Harbor支持Docker镜像的存储、分发与签名验证，确保镜像的完整性与来源可信。

其独特的”项目”机制，允许用户按业务线、团队等维度组织镜像，提升管理效率。每个项目可以独立配置权限、存储配额和复制策略，实现了精细化的资源管理。

2.2 高级安全特性

Harbor在安全方面表现尤为突出，除了基本的权限控制与HTTPS加密外，还支持镜像签名与漏洞扫描。通过集成Clair等漏洞扫描工具，Harbor可在镜像上传时自动检测安全漏洞，阻止不安全镜像的入库。

Harbor支持内容信任（Content Trust）机制，确保只有经过签名的镜像才能被拉取和部署。此外，Harbor还支持镜像复制与同步，便于跨地域、跨云环境的镜像分发，同时保持安全策略的一致性。

2.3 性能优化与扩展性

Harbor通过分布式架构设计，实现了水平扩展能力。其支持多节点部署，可通过增加节点提升存储与处理能力。在文件服务层面，Harbor采用了缓存机制与负载均衡策略，有效降低了镜像拉取的延迟。

Harbor支持与Kubernetes等容器编排平台的深度集成，实现镜像的自动拉取与部署。其资源配额管理功能可以防止单个项目占用过多存储空间，确保资源的合理分配。

三、Nexus与Harbor的对比与选择建议

3.1 功能对比

特性维度	Nexus Repository Manager	Harbor
多格式支持	支持Docker、Maven、npm、PyPI等多种格式	专注于Docker镜像
安全特性	RBAC权限控制、LDAP集成、HTTPS加密	镜像签名、漏洞扫描、内容信任
存储管理	分层存储、多后端支持	项目级存储配额、镜像复制
集成能力	丰富的REST API、插件生态系统	深度容器生态集成、Kubernetes原生支持
部署架构	单节点或集群部署	分布式架构、水平扩展
社区生态	成熟的企业级解决方案	CNCF毕业项目、活跃的社区支持

3.2 选择建议

选择Nexus的场景：

团队涉及多种技术栈，需要统一管理Docker镜像、Java包、Node.js模块等多种类型的包文件
企业已有Nexus作为制品仓库，希望扩展容器镜像管理功能
需要与现有的Maven、npm等构建工具链深度集成
对多格式包管理的统一性和一致性有较高要求

选择Harbor的场景：

团队专注于容器化应用开发，对镜像安全有严格要求
需要漏洞扫描、镜像签名等高级安全功能
计划在Kubernetes环境中大规模部署容器应用
需要跨地域、跨云的镜像复制和同步能力
重视CNCF生态系统的兼容性和社区支持

混合部署方案：
对于大型企业，可以考虑Nexus与Harbor的混合部署方案。使用Nexus管理多格式的制品包，同时使用Harbor专门管理容器镜像，充分发挥两者的优势。

四、实践建议与优化策略

4.1 存储优化

定期清理策略：

建立镜像生命周期管理策略，定期清理不再使用的镜像与包文件
设置保留策略，如保留最近N个版本，自动删除旧版本
使用标签策略管理镜像版本，避免存储空间浪费

存储配置优化：

根据文件类型与访问频率，合理配置存储策略
对于频繁访问的镜像，考虑使用SSD存储提升I/O性能
配置适当的缓存策略，减少网络传输开销

4.2 安全加固

访问控制强化：

启用多因素认证，提升账户安全性
定期审计权限配置，确保最小权限原则
实施网络访问控制，限制仓库的访问来源

安全扫描集成：

配置自动漏洞扫描，确保所有镜像在上传时都经过安全检查
建立安全策略，阻止高风险镜像的部署
定期更新漏洞数据库，保持扫描的准确性

4.3 性能监控与高可用

监控体系建设：

利用Prometheus、Grafana等监控工具，实时监控镜像仓库的性能指标
设置关键指标告警，如存储空间使用率、请求延迟、错误率等
定期分析日志文件，识别潜在的性能瓶颈与安全风险

高可用部署：

对于生产环境，建议采用集群部署确保高可用性
配置负载均衡，分散请求压力
实施定期备份策略，确保数据安全

4.4 最佳实践总结

规划先行：在部署前明确需求，选择合适的解决方案
安全第一：始终将安全作为首要考虑因素
持续优化：定期评估和优化存储、性能和安全配置
团队培训：确保团队成员了解工具的使用方法和最佳实践
文档完善：建立完善的运维文档和应急响应流程

五、未来发展趋势

随着云原生技术的不断发展，镜像仓库技术也在持续演进。未来的发展趋势可能包括：

智能化管理：利用AI技术优化镜像存储和分发策略
边缘计算支持：更好地支持边缘场景下的镜像分发
安全增强：集成更多的安全扫描工具和策略
生态融合：与更多的云原生工具链深度集成
性能优化：针对大规模集群的进一步性能优化

结论

Nexus与Harbor作为两款主流的镜像仓库解决方案，各自拥有独特的文件服务能力。Nexus以其多格式支持和成熟的生态系统适合需要统一管理多种类型制品的团队，而Harbor则以其专注于容器镜像的安全特性和云原生集成能力在容器生态中表现出色。

开发者及企业用户应根据自身的技术栈、安全要求和运维能力，选择最适合的镜像仓库工具。通过合理的存储优化、安全加固与性能监控，可进一步提升镜像仓库的效率与可靠性，为DevOps流程提供坚实支撑。在实际应用中，也可以考虑两者的混合部署方案，充分发挥各自的优势，构建更加完善的企业级制品管理体系。

一、引言：机器学习工程师与数据科学家的角色

在机器学习项目中，团队通常由不同角色组成，其中两个核心角色是：

角色	核心职责	工作重点
机器学习工程师	构建、开发和维护可投入生产的机器学习系统。	工程实现、系统可靠性、性能和规模化部署。
数据科学家	通过研究分析形成项目思路，评估模型对业务指标的影响。	理论研究、算法探索、数据分析和业务洞察。

选择合适的框架是项目成功的关键。本文将系统介绍当前主流的机器学习框架，帮助您根据需求做出明智选择。

二、深度学习与通用框架

1. TensorFlow（谷歌）

特点：使用数据流图进行数值计算的开源库，支持分布式训练和部署。

核心概念：张量（Tensors）在计算图中流动（Flow）。
语言支持：Python（主要）、C++、Java等。
部署：支持移动端（TensorFlow Lite）和浏览器（TensorFlow.js）。
生态系统：拥有庞大的社区和丰富的预训练模型（TensorFlow Hub）。
官网：https://www.tensorflow.org/

2. PyTorch（Meta）

特点：以动态计算图和灵活性著称，深受研究人员喜爱。

核心优势：直观的Pythonic API，调试方便，动态图便于实验。
语言：Python（主要），底层为C++。
应用：计算机视觉（TorchVision）、自然语言处理（Hugging Face Transformers）等。
社区：拥有活跃的学术和工业界社区。
官网：https://pytorch.org/

3. Caffe（伯克利视觉与学习中心）

特点：早期专注于计算机视觉的高效深度学习框架。

设计理念：表达、效率和模块化。
性能：完全用C++编写，支持CUDA GPU加速，单GPU日处理超6000万张图像。
模型：支持CNN、RNN等，提供大量预训练模型。
现状：Caffe2已并入PyTorch，但原Caffe仍在特定领域使用。

4. Apache Singa

特点：用于大规模数据集训练的通用分布式深度学习平台。

设计：基于分层抽象的简单开发模型。
支持模型：CNN、RNN、RBM等。
部署：支持跨机器集群训练，易于通过Zookeeper管理集群。
状态：Apache孵化器项目。

5. Theano

特点：早期的数值计算库，启发了许多现代框架（如TensorFlow）。

语言：Python。
功能：可定义、优化和数值计算，支持高效机器学习算法。
现状：已停止主要开发，但其思想影响深远。
官网：http://deeplearning.net/software/theano/

6. Torch（基于Lua）

特点：科学计算框架，以GPU优先和灵活性著称。

语言：LuaJIT脚本语言，底层为C/CUDA。
生态系统：拥有庞大的社区库（机器学习、视觉、信号处理等）。
衍生：PyTorch受其启发，但使用Python接口。

三、云平台与自动化机器学习框架

7. Amazon Machine Learning (AML)

特点：AWS提供的托管服务，降低机器学习使用门槛。

用户：面向各级开发者，无需深入算法细节。
功能：提供可视化工具和向导，构建预测模型。
集成：与AWS数据服务（S3、Redshift、RDS）无缝连接。
限制：模型和数据存储以AWS为中心。

8. Microsoft Azure Machine Learning Studio

特点：Azure的拖放式可视化机器学习环境。

使用方式：通过浏览器创建、训练模型，并发布为API。
资源：提供大量微软和第三方算法。
免费体验：支持匿名试用长达8小时。
官网：https://studio.azureml.net/

9. Google Cloud AI Platform / Vertex AI

特点：谷歌云的全托管机器学习平台。

功能：涵盖数据准备、训练、调优、部署和监控全流程。
集成：与TensorFlow、PyTorch、Scikit-learn等框架深度集成。
自动化：提供AutoML功能，自动构建和优化模型。

四、传统机器学习与数据科学框架

10. Scikit-learn

特点：Python机器学习的事实标准，专注于传统算法。

基础：基于NumPy、SciPy和Matplotlib。
算法：提供完整的分类、回归、聚类、降维等工具。
特点：API设计一致，文档优秀，社区活跃。
适用：中小规模数据、快速原型、教学和生产。
官网：http://scikit-learn.org/

11. MLlib (Apache Spark)

特点：Spark的机器学习库，专为大规模数据处理设计。

优势：可扩展性，能在内存中高速处理海量数据。
算法：涵盖常见学习算法和工具（分类、回归、聚类、协同过滤）。
语言：Scala（原生）、Java、Python、R。
官网：http://spark.apache.org/mllib/

12. H2O.ai

特点：开源分布式机器学习平台，注重易用性和企业部署。

界面：提供Web UI（Flow）和多种语言API（Python、R、Java）。
功能：支持自动机器学习（AutoML）、深度学习、模型解释。
集成：可与Hadoop、Spark等大数据生态系统协作。

13. Shogun

特点：历史悠久的通用机器学习工具箱（1999年创建）。

语言：核心为C++，通过SWIG支持Java、Python、R、Julia等10多种语言。
重点：统一的大规模学习，支持分类、回归、数据分析等。
官网：http://www.shogun-toolbox.org/

14. mlpack

特点：基于C++的高性能机器学习库。

设计理念：可扩展性、高效性和易用性。
使用方式：命令行“黑盒”操作或C++ API。
现状：mlpack 3.x持续更新，性能优异，但主要面向C++生态。
官网：http://mlpack.org/

五、其他特色框架

15. Pattern（Python Web挖掘组件）

特点：Python的Web挖掘和自然语言处理工具包。

功能：数据挖掘（网络爬虫、API）、NLP（情感分析、WordNet）、机器学习（聚类、SVM）、可视化。
适用：快速构建网络数据分析和挖掘应用。

16. Massive Online Analysis (MOA)

特点：流行的数据流挖掘开源框架。

场景：处理持续到达的大规模数据流。
算法：分类、回归、聚类、概念漂移检测、推荐系统。
语言：Java，扩展性好。
官网：https://moa.cms.waikato.ac.nz/

17. Veles（三星）

特点：用C++开发的分布式深度学习平台，使用Python进行协调。

流程：数据自动标准化分析后馈入集群，REST API支持生产部署。
拓扑：支持全卷积神经网络、CNN、RNN等。
官网：https://velesnet.ml/

18. Microsoft分布式机器学习工具包 (DMTK)

特点：专为跨集群分布式机器学习任务设计。

目标：高效利用资源有限的集群，减少节点间通信。
扩展性：框架设计便于未来添加新算法。

19. Microsoft计算网络工具包 (CNTK)

特点：微软的深度学习框架，强调速度和跨CPU/GPU扩展。

性能：据称在语音识别等任务上训练速度极快。
功能：通过有向图构建神经网络，支持多种网络类型。

20. Neon（Nervana）

特点：Nervana公司开发的深度学习框架，后其技术融入Intel产品。

设计：Python编写，部分组件用C++，支持可插拔硬件后端（CPU、GPU、专用硬件）。
现状：已由Intel优化并整合至其AI套件。

21. Marvin（普林斯顿视觉小组）

特点：轻量级神经网络框架，“生来就是为了被改动的”。

依赖：仅少量C++/CUDA文件，便于理解和修改。
资源：提供预训练模型，鼓励社区贡献。

22. Brainstorm（IDSIA）

特点：旨在让深度神经网络“快速、灵活而有趣”。

功能：支持LSTM等递归神经网络，提供Python接口。
后端：支持Numpy（CPU）和CUDA（GPU）。

六、框架选型指南

需求场景	推荐框架	关键理由
研究与快速原型	PyTorch	动态图、调试友好、社区活跃。
生产部署与移动端	TensorFlow	生态系统完整、部署工具链成熟。
传统机器学习	Scikit-learn	API统一、文档优秀、覆盖全面。
大数据环境	MLlib (Spark)	与Spark生态无缝集成，处理海量数据。
自动化与低代码	H2O AutoML 或云平台（Azure ML, GCP Vertex AI）	降低技术门槛，快速构建模型。
计算机视觉传统项目	Caffe	历史悠久，大量预训练视觉模型。
分布式深度学习研究	Apache Singa 或 Horovod	专为分布式训练设计。

选择原则：

项目阶段：研究阶段重灵活性（PyTorch），生产阶段重稳定性和工具链（TensorFlow）。
团队技能：优先选择团队最熟悉的语言和框架。
问题领域：计算机视觉、NLP、推荐系统等领域有特定的优选框架和预训练模型库。
基础设施：考虑与现有大数据平台（Spark、Hadoop）、云服务或硬件的集成。
社区与支持：活跃的社区意味着更多的教程、解决方案和持续更新。

七、总结

机器学习框架生态丰富多样，从专注于深度学习的TensorFlow、PyTorch，到面向传统机器学习的Scikit-learn，再到降低门槛的云平台和自动化工具，各有其定位和优势。

核心建议：

初学者：从 Scikit-learn 开始理解机器学习基础，然后学习 PyTorch 或 TensorFlow 进入深度学习。
团队：评估长期技术栈，在灵活性和工程化之间取得平衡。
企业：考虑云平台和AutoML工具来提升效率，同时培养团队掌握核心框架以应对复杂需求。

在麒麟V10桌面操作系统的日常运维与开发工作中，SSH（Secure Shell）作为远程开发、虚拟机管理及内网服务器连接的核心工具，其运行稳定性直接影响运维效率与开发进度。当出现“Connection refused”“Connection timed out”等连接异常提示时，运维人员与开发人员常面临排查无头绪的困境——此类故障可能源于服务运行状态、配置参数设置、网络通路连通性、防火墙规则配置或用户权限管控等多个环节，需通过分层拆解实现根源定位。

在团队内部麒麟V10开发桌面部署过程中，曾出现一起由旧版配置残留导致的SSH连接异常，排查耗时较长。该案例表明，掌握系统性的故障诊断方法论，相较于记忆零散操作命令更具实践价值。本文基于实战经验，梳理形成从现象到根源、从通用场景到特殊场景的分层排查体系，覆盖五大常见故障类型，深入解析故障产生的技术原理，补充安全实用的配置方案，提供可直接复用的操作命令与排查技巧，为相关人员解决SSH连接故障提供技术支撑。

一、基础排查：SSH守护进程（sshd）运行状态校验

SSH连接建立的前提是目标主机的sshd服务正常运行，该环节作为基础排查要点，易被忽视。在系统新安装、重启或配置变更后，需优先对sshd服务状态进行校验。

1.1 服务状态查询与异常分析

麒麟V10系统中，OpenSSH服务通常由systemd进行管理，最常用的服务状态查询命令为sudo systemctl status ssh。查看命令输出时，需重点关注核心信息，不可仅依据“active (running)”的表面状态判断服务正常。

1	sudo systemctl status ssh

健康的sshd服务输出需包含以下三项关键信息，缺一不可：

Loaded行：显示为enabled，表示服务已配置开机自启；若显示为disabled，则系统重启后服务无法自动运行，需手动启动。
Active行：active (running)为服务正常运行的理想状态；若显示为active (exited)，表明服务启动后异常退出，需进一步排查启动失败原因。
日志片段：若输出中出现Failed to listen on port 22或Address already in use，则可直接判定为端口冲突问题，需优先处理端口占用异常。

若sshd服务未处于运行状态，不可盲目启动服务，应先通过日志排查启动失败根源，避免操作不当加剧故障：

1	sudo journalctl -u ssh --since "5 minutes ago" --no-pager

说明：journalctl为systemd系统的日志查看工具，-u ssh参数用于指定查看sshd服务相关日志，--since参数用于过滤最近5分钟的日志内容。通过查看启动失败的详细错误信息，可快速定位服务启动类故障的核心原因，为后续修复提供依据。

1.2 服务安装、启动与自启配置

若经排查确认sshd服务未安装（如最小化安装的麒麟V10系统），需先安装openssh-server组件，确保服务运行所需组件完整：

1 2	sudo apt update sudo apt install openssh-server -y

组件安装完成后，需启动sshd服务并配置开机自启，最后再次校验服务状态，确保服务正常运行：

1
2
3

sudo systemctl start ssh      # 立即启动sshd服务
sudo systemctl enable ssh     # 配置服务开机自启
sudo systemctl status ssh     # 校验服务运行状态

进阶排查要点：部分场景下，服务状态虽显示为“active (running)”，但实际未监听目标端口，需通过ss或netstat命令进行交叉验证，排除服务“假运行”情况：

1
2
3

sudo ss -tlnp | grep :22
# 或使用netstat（部分系统默认未预装，需提前安装）
sudo netstat -tlnp | grep :22

正常情况下，命令输出应显示sshd进程监听0.0.0.0:22（IPv4所有网络接口）和[::]:22（IPv6所有网络接口）；若无相关输出，说明sshd进程可能绑定至特定IP地址，或未成功监听目标端口，需进一步排查配置文件。

二、核心配置：sshd_config参数解析及推荐配置

若sshd服务运行正常且端口监听正常，但SSH连接仍存在异常，故障大概率源于核心配置文件/etc/ssh/sshd_config。该文件用于控制sshd守护进程的运行规则，参数配置错误是导致SSH连接失败的高频原因，同时合理的配置可有效提升SSH连接的安全性。

2.1 必查核心配置项（故障排查重点）

修改配置文件前，需先进行备份操作，避免配置错误导致sshd服务无法启动，备份命令如下：sudo cp /etc/ssh/sshd_config /etc/ssh/sshd_config.bak。备份完成后，可通过vi或nano编辑器对配置文件进行修改。以下为导致SSH连接失败的高频配置项，需重点排查：


配置项	默认值/常见值	作用与影响	排查建议值
Port	22	指定SSH服务监听的端口号，默认22端口易遭受扫描攻击，可根据实际需求自定义修改	确认端口配置与预期一致（如默认22端口），若已修改端口，客户端连接时需通过`-p`参数指定端口
ListenAddress	0.0.0.0	指定sshd进程监听的IP地址，0.0.0.0表示监听所有IPv4网络接口	若配置为127.0.0.1或特定IP地址，仅该IP地址可建立SSH连接，排查时需确认是否存在误配置
PermitRootLogin	prohibit-password	控制是否允许root用户直接通过SSH登录，直接允许root用户登录存在安全风险	故障调试阶段可临时设置为yes，生产环境建议配置为no或prohibit-password，提升系统安全性
PasswordAuthentication	yes	控制是否允许通过密码认证方式登录SSH，密码认证易遭受暴力破解攻击	密码连接失败时，需确认该参数配置为yes；生产环境建议关闭密码认证，仅启用公钥认证
PubkeyAuthentication	yes	控制是否允许通过公钥认证方式登录SSH，公钥认证为更安全的登录方式	公钥连接失败时，需确认该参数配置为yes，且公钥相关配置正确无误
AllowUsers	未设置	配置允许通过SSH登录的用户白名单，设置后仅白名单内用户可建立连接	若已配置该参数，需确认登录用户名已纳入白名单，否则无法建立SSH连接
DenyUsers	未设置	配置禁止通过SSH登录的用户黑名单，设置后黑名单内用户无法建立连接	排查时需确认登录用户名未被纳入黑名单，避免因误配置导致连接失败

2.2 推荐配置（安全与稳定兼顾，可直接复用）

结合麒麟V10桌面版系统特性，梳理以下sshd_config推荐配置，兼顾安全性与实用性，可直接添加至配置文件末尾（需根据实际应用场景调整），配置完成后需重启sshd服务使配置生效：

# 自定义SSH端口（避免默认22端口遭受扫描，建议选择10000-65535区间的端口）
Port 2222

# 禁止root用户直接登录，提升系统安全性
PermitRootLogin no

# 关闭密码认证，仅启用公钥认证（需提前完成公钥配置）
PasswordAuthentication no

# 启用公钥认证（默认启用，明确配置可提升配置可靠性）
PubkeyAuthentication yes

# 指定公钥文件路径（默认路径，无需修改，需确保文件权限正确）
AuthorizedKeysFile .ssh/authorized_keys

# 限制连接超时时间，避免空闲连接占用系统资源
ClientAliveInterval 60
ClientAliveCountMax 3

# 禁止空密码登录（默认禁止，明确配置可规范配置标准）
PermitEmptyPasswords no

# 限制并发连接数，可根据服务器性能灵活调整
MaxSessions 10
MaxStartups 10:30:60

注意：修改Port端口配置后，客户端建立SSH连接时需使用ssh -p 2222 user@hostname命令（将2222替换为自定义端口）；关闭密码认证前，需确认公钥认证已配置完成，避免出现无法登录的情况。

任何配置修改完成后，需重启sshd服务使配置生效；部分无需重启服务即可生效的参数，可通过重载配置实现更新：

1
2
3

sudo systemctl restart ssh
# 或重载配置（适用于AllowUsers、DenyUsers等部分参数）
sudo systemctl reload ssh

2.3 配置文件语法排错技巧

SSH配置文件对语法规范性要求严格，轻微语法错误即可导致sshd服务无法启动，以下为常见语法错误及排查技巧：

多余空格：如PermitRootLogin yes（两个空格分隔）可能导致参数识别异常，PermitRootLogin = yes（添加等号）属于语法错误，正确格式为PermitRootLogin yes（单个空格分隔）。
注释符干扰：以#开头的行为注释行，需确保待修改行未被注释（行首无#）；若需启用注释行中的配置，删除行首#即可。
Include指令影响：配置文件可能通过Include指令引入其他配置片段，若核心配置排查无异常，需检查引入的配置文件是否存在冲突。

可通过sshd测试模式快速检查配置文件语法有效性，该模式仅解析配置文件并报告错误，不实际重启服务，可避免因配置错误导致服务中断：

1	sudo sshd -t

若命令无输出，表明配置文件语法正确；若存在错误提示，可根据提示定位并修改对应参数。

三、通路排查：网络连通性与防火墙规则解析

当sshd服务运行正常且配置无误时，SSH连接异常通常源于网络通路问题，主要包括网络不可达与防火墙拦截两类情况。需从网络连通性与防火墙规则两个核心维度进行排查，确保连接通路畅通。

3.1 基础网络连通性测试（快速定位底层故障）

在客户端主机上，可通过ping命令测试目标服务器IP地址的连通性（假设服务器IP为192.168.1.100），初步排除底层网络故障：

1	ping -c 4 192.168.1.100

排查说明：

若ping命令执行失败，表明存在底层网络故障，如网线松动、IP地址配置错误、路由器拦截、网段隔离等，需先解决网络连通性问题，再排查SSH服务本身。
若ping命令执行成功但SSH连接失败，表明网络可达，故障集中于SSH端口未开放或防火墙拦截，需进一步检查目标端口开放状态。

可通过telnet命令测试SSH端口（默认22端口，自定义端口需对应替换）的开放情况：

1	telnet 192.168.1.100 22

若连接成功，将显示类似SSH-2.0-OpenSSH_8.9p1的横幅信息；若连接被拒绝或超时，表明目标端口未开放或被防火墙拦截。

说明：麒麟V10桌面版默认可能未安装telnet客户端，可使用nc（netcat）工具替代，该工具命令更简洁、输出更清晰，具体命令为：nc -zv 192.168.1.100 22，其中-z参数用于端口扫描，-v参数用于输出详细信息，可快速判断端口开放状态。

3.2 防火墙规则深度排查（重点解决拦截问题）

麒麟V10桌面版通常采用firewalld或ufw作为防火墙前端工具，底层依赖iptables/nftables实现规则管控。需逐层检查防火墙规则，避免SSH端口被拦截，具体排查方法如下：

1. 检查ufw防火墙（若启用）

ufw为麒麟V10桌面版常用的简易防火墙管理工具，可通过以下命令查看当前防火墙状态及规则：

1	sudo ufw status verbose

排查重点：确认SSH端口（默认22端口，自定义端口需对应）的规则为ALLOW IN；若规则为DENY，需执行以下命令开放端口：

1 2	sudo ufw allow 22/tcp # 开放22端口（SSH默认使用TCP协议） sudo ufw reload # 重载防火墙规则，使配置生效

2. 检查firewalld防火墙（若启用）

部分麒麟V10系统可能启用firewalld防火墙，可通过以下命令查看当前防火墙规则：

1	sudo firewall-cmd --list-all

排查重点：确认services:列表中包含ssh服务，或ports:列表中包含22/tcp端口；若未包含，需添加对应规则并重载：

# 方法1：添加ssh服务（自动对应22端口）
sudo firewall-cmd --permanent --add-service=ssh
# 方法2：添加指定端口（自定义端口时使用，如2222）
# sudo firewall-cmd --permanent --add-port=2222/tcp
sudo firewall-cmd --reload  # 重载防火墙规则

3. 直接检查iptables规则（终极排查手段）

ufw与firewalld的配置最终均会同步至iptables/nftables，直接查看iptables规则可避免前端工具配置的误导，快速定位拦截故障：

1	sudo iptables -L -n --line-numbers

排查重点：查看INPUT链（入站规则），确认存在针对tcp dpt:22（22替换为自定义端口）的允许规则，典型允许规则如下：

1	ACCEPT tcp -- 0.0.0.0/0 0.0.0.0/0 tcp dpt:22 ctstate NEW,ESTABLISHED

注意：若INPUT链前端存在DROP或REJECT所有流量的规则，且允许SSH连接的规则未优先生效，将导致SSH连接被拦截，需调整规则顺序或修改拦截规则。

四、认证排查：密码与公钥认证故障精准修复

若能正常连接sshd服务，但在登录阶段出现失败，属于认证类故障。SSH协议主要支持密码认证与公钥认证两种方式，需结合登录提示信息，针对性排查，解决认证不匹配问题。

4.1 密码认证失败排查（简易流程）

确认服务端PasswordAuthentication参数已配置为yes，但密码登录仍失败时，可按以下顺序排查，高效定位故障原因：

用户名有效性：SSH连接所使用的用户名为麒麟V10系统的操作系统用户，安装系统时创建的普通用户与root用户为不同账户。使用ssh user@hostname命令连接时，需确认user为系统已存在的用户（可通过cat /etc/passwd命令查看系统用户列表）。
密码正确性：SSH登录密码区分大小写，需检查键盘布局是否正常（如CapsLock键是否误触发）。可先在服务端本地终端使用该用户登录，验证密码有效性，排除密码输入错误。
用户账户状态：检查用户账户是否处于锁定或过期状态，执行以下命令查看账户状态： sudo passwd -S <用户名> # 替换<用户名>为实际登录用户 若状态显示为L（锁定）或NP（无密码），需执行解锁命令（sudo passwd -u <用户名>）或重置密码（sudo passwd <用户名>）。
PAM模块限制：/etc/pam.d/目录下的配置文件（如sshd）可能存在额外登录限制，如终端限制、登录时间限制等。若未手动修改过相关配置，此类限制通常不是故障根源，可暂不排查。

4.2 公钥认证失败排查（实战重点，高安全性）

公钥认证失败的排查过程相对复杂，涉及客户端与服务端的多文件匹配及权限配置，需分别对两端进行检查，具体排查清单如下：

服务端检查清单（核心重点）

公钥文件权限检查（最常见故障点）：sshd服务对文件权限要求严格，~/.ssh/authorized_keys文件及其父目录权限过松，会导致sshd服务出于安全考虑拒绝使用该文件，需配置正确权限： chmod 700 ~/.ssh # 仅当前用户拥有读写执行权限 chmod 600 ~/.ssh/authorized_keys # 仅当前用户拥有读写权限 chown -R $USER:$USER ~/.ssh # 确保文件归属当前用户
公钥内容检查：确保authorized_keys文件中粘贴的公钥为完整单行内容，无换行、多余空格或特殊字符。建议使用ssh-copy-id命令重新推送公钥，该命令可自动处理公钥格式与文件权限：# 在客户端执行，替换用户与服务器IP地址 ssh-copy-id user@192.168.1.100
sshd配置确认：再次检查sshd_config文件，确保PubkeyAuthentication参数配置为yes，且AuthorizedKeysFile参数指向正确（默认路径为.ssh/authorized_keys，无需修改）。

客户端检查清单

私钥权限检查：客户端私钥文件（默认路径为~/.ssh/id_rsa）需配置严格权限，否则会被客户端SSH工具拒绝使用，具体权限配置命令： chmod 600 ~/.ssh/id_rsa
指定密钥文件：若使用非默认私钥（如自定义密钥文件名或路径），建立连接时需通过-i参数指定私钥路径： ssh -i /path/to/your/private_key user@hostname
启用详细调试（终极排查手段）：建立连接时添加-vvv参数，可输出详细的认证过程，清晰呈现每一步的执行情况及失败原因，重点关注Offering public key、Authentication succeeded/failed等关键日志行：ssh -vvv user@hostname

五、进阶排查：隐性故障与特殊场景处理

若经上述四层排查后，SSH连接仍存在异常，故障可能源于系统安全模块、资源限制或客户端缓存等隐性因素，需进一步深入排查，覆盖各类特殊场景。

5.1 SELinux/AppArmor强制访问控制的影响

麒麟V10系统可能搭载强制访问控制模块，其中桌面版默认通常不强制启用SELinux，但AppArmor模块可能处于活跃状态。该模块的严格访问控制规则可能阻止sshd进程访问必要资源（如authorized_keys文件、私钥文件等），导致SSH连接失败。

通过以下命令检查AppArmor状态，确认sshd服务是否被管控：

1	sudo aa-status \| grep sshd

排查与处理方案：

若sshd服务处于enforce模式（强制管控），且系统日志（/var/log/auth.log或/var/log/audit/audit.log）中存在“拒绝访问”相关记录，表明AppArmor模块拦截了sshd进程的操作。
临时调试方案：将sshd服务的AppArmor模式调整为complain（仅输出警告，不执行拦截），测试SSH连接是否恢复正常，命令如下： sudo aa-complain /usr/sbin/sshd

重要提示：临时调试完成后，需根据实际安全需求制定合理的AppArmor策略，或恢复为enforce模式，避免降低系统安全防护等级。

5.2 系统资源与连接限制排查

系统资源不足或连接数限制也可能导致SSH连接失败，重点排查以下三项内容：

最大连接数限制：sshd_config文件中的MaxSessions（最大并发会话数）与MaxStartups（未完成认证的最大连接数）参数，若当前连接数达到限制，新的连接尝试会被拒绝，可根据服务器性能适当调大参数值。
PAM资源限制：通过ulimit命令或PAM模块设置的用户进程数、文件描述符数等资源限制，可能影响sshd进程创建子进程处理连接。可通过ulimit -a命令查看当前资源限制，必要时进行调整。
TCP Wrappers限制：/etc/hosts.allow与/etc/hosts.deny文件为古老的访问控制配置文件，可能存在针对sshd服务的拒绝规则。需检查该文件，若存在相关拒绝规则，需删除或修改。

5.3 客户端侧配置与缓存故障排查

排查过程中不可仅关注服务端，客户端的配置错误或缓存问题也可能导致SSH连接失败，重点排查以下三项内容：

客户端配置文件干扰：客户端~/.ssh/config文件的配置优先级较高，若该文件中为目标主机配置了错误参数（如错误端口、用户名、密钥文件路径、代理设置等），会导致连接失败，需检查并修改该文件。
known_hosts文件缓存问题：若服务器重装系统或更换SSH密钥，客户端会因主机密钥不匹配拒绝建立连接，提示“Host key verification failed”。需删除客户端~/.ssh/known_hosts文件中对应主机的条目，或通过以下命令快速删除：ssh-keygen -R hostname # 替换hostname为服务器IP地址或主机名
网络代理干扰：客户端shell环境中的http_proxy、all_proxy等环境变量，若配置了网络代理，可能干扰SSH直接连接。需通过echo $http_proxy命令检查代理配置，必要时通过unset http_proxy all_proxy命令临时关闭代理后重试。

总结：SSH连接故障排查核心逻辑

麒麟V10桌面版SSH连接失败的排查工作，本质是一套分层诊断流程：从基础的sshd服务运行状态校验，到核心的sshd_config配置参数排查，再到网络连通性与防火墙规则解析，随后进行认证凭据匹配排查，最后处理系统级隐性故障。通过层层递进的方式，逐步缩小排查范围，可实现故障的高效定位与修复。

核心排查技巧：结合日志与调试输出进行分析——服务端/var/log/auth.log（或/var/log/secure）日志可提供sshd服务运行状态及认证失败原因，客户端ssh -vvv命令可输出详细的连接与认证过程，二者结合可快速定位故障根源。

养成“故障排查先查日志、先基础后复杂”的习惯，可大幅降低盲目操作的概率，提升排查效率。实际上，绝大多数SSH连接失败故障均可通过本文梳理的五个层次实现解决，掌握该套排查体系，可有效提升SSH连接故障的处理能力，保障远程运维与开发工作的顺利开展。

麒麟V10离线安装Docker

发表于 2026-03-15 更新于 2026-04-28

在国产化替代加速推进的当下，越来越多政企单位开始部署搭载麒麟V10操作系统的服务器，涵盖arm64、x86_64两种主流架构。这类服务器常应用于涉密项目、内部研发等无外网访问权限的场景，如何在完全隔离的内网环境中，快速、稳定地部署Docker及验证环境（本文以Redis为例），成为很多运维人员面临的难题。

常规外网环境中，docker pull redis 即可轻松获取镜像并部署，但不同架构的麒麟V10服务器无法直接拉取非对应架构的默认镜像，且内网环境无法在线下载依赖和镜像，导致部署过程坑点重重。本文将从Docker离线安装入手，兼顾arm64、x86_64两种架构，手把手带你完成麒麟V10环境下Docker离线部署、Redis镜像离线获取与加载、容器启动与环境验证的全流程，兼顾实用性与安全性，确保新手也能跟着操作落地，Redis仅作为Docker环境部署完成后的验证工具，无需复杂配置。

一、前置说明：环境与核心思路

1.1 环境确认

本次操作针对 麒麟V10操作系统（含arm64/x86_64两种架构，arm64即aarch64，x86_64即x86），目标服务器为无外网访问权限的内网服务器。操作前需准备两台机器，且中转站机器架构建议与目标服务器一致（避免镜像架构不兼容）：

目标服务器：内网麒麟V10（arm64或x86_64），用于最终部署Docker和Redis（环境验证）；
中转站机器：能访问外网的Linux机器（优先与目标服务器同架构，arm64可选麒麟V10、华为云鲲鹏实例，x86_64可选普通Linux服务器、虚拟机；若架构不同，需额外注意镜像架构指定）。

1.2 核心思路

离线部署的核心是“外网准备、内网部署、环境验证”，整体流程可概括为3步，兼顾两种架构适配：

外网中转站：根据目标服务器架构，下载对应版本的Docker离线安装包、Redis Docker镜像，并打包保存；
内网传输：将离线安装包、镜像包通过U盘、内部文件服务器等介质，传输到麒麟V10目标服务器；
内网部署：依次完成Docker离线安装、Redis镜像加载、容器启动，通过简单命令验证Docker与Redis环境正常运行。

二、第一步：外网准备——下载Docker离线包与Redis镜像（分架构）

此步骤在能访问外网的中转站机器上操作，核心是根据目标服务器架构（arm64/x86_64），获取适配麒麟V10的Docker安装包和Redis镜像，避免架构不兼容问题。Redis仅作为环境验证，选择官方稳定版（本文以Redis 6.2.6为例，适配两种架构）。

2.1 下载麒麟V10（分架构）Docker离线安装包

麒麟V10系统基于CentOS/RHEL架构，Docker离线安装需依赖rpm包，优先选择适配对应架构的官方稳定版本（本文以Docker 20.10.24为例，分arm64、x86_64两个版本）。

操作步骤（分架构执行）：

根据目标服务器架构，访问对应Docker官方rpm仓库，下载以下3个核心rpm包（后缀对应架构）：
1. arm64架构：访问 https://download.docker.com/linux/centos/8/aarch64/stable/Packages/，下载 aarch64 后缀的包：
  - containerd.io-xxx.aarch64.rpm（容器运行时依赖）；
  - docker-ce-xxx.aarch64.rpm（Docker核心包）；
  - docker-ce-cli-xxx.aarch64.rpm（Docker命令行工具）。
2. x86_64架构：访问 https://download.docker.com/linux/centos/8/x86_64/stable/Packages/，下载 x86_64 后缀的包：
  - containerd.io-xxx.x86_64.rpm（容器运行时依赖）；
  - docker-ce-xxx.x86_64.rpm（Docker核心包）；
  - docker-ce-cli-xxx.x86_64.rpm（Docker命令行工具）。
将下载的3个rpm包放在同一目录（如 /home/docker_offline），并打包为tar压缩包（标注架构，方便后续区分），方便后续传输：
1. arm64架构：tar -czvf docker_arm64_20.10.24.tar.gz /home/docker_offline/*.rpm
2. x86_64架构：tar -czvf docker_x86_64_20.10.24.tar.gz /home/docker_offline/*.rpm

注意：务必确认rpm包后缀与目标服务器架构一致（arm64对应aarch64，x86_64对应x86_64），否则无法在麒麟V10上安装。

2.2 下载并打包Redis对应架构Docker镜像

Redis官方镜像包含多个架构版本，需根据目标服务器架构（arm64/x86_64），精准获取对应版本，避免下载错误架构导致无法运行。本文以Redis 6.2.6（长期支持版，稳定可靠，适配两种架构）为例，仅作为Docker环境验证工具，无需复杂配置。

操作步骤（分架构执行）：

拉取正确架构的Redis镜像：
1. 若中转站机器与目标服务器同架构（arm64/x86_64），直接拉取，Docker会自动匹配架构：docker pull redis:6.2.6
2. 若中转站机器与目标服务器架构不同，必须指定对应平台，否则会拉取错误架构版本：
  - 目标服务器为arm64：docker pull --platform linux/arm64 redis:6.2.6
  - 目标服务器为x86_64：docker pull --platform linux/amd64 redis:6.2.6
验证镜像架构（确保与目标服务器一致）： docker inspect redis:6.2.6 | grep Architecture输出结果：arm64架构对应 “Architecture”: “aarch64”，x86_64架构对应 “Architecture”: “amd64”，确认镜像正确。
打包镜像为tar文件（标注架构），便于内网传输：
1. arm64架构： # 查看镜像ID（假设为 abcdef123456） docker images | grep redis # 打包镜像 docker save abcdef123456 -o /home/redis_arm64_6.2.6.tar
2. x86_64架构： # 查看镜像ID（假设为 abcdef123456） docker images | grep redis # 打包镜像 docker save abcdef123456 -o /home/redis_x86_64_6.2.6.tar
（可选）校验文件完整性：计算tar包的哈希值，后续传输到内网后核对，避免文件损坏：
1. arm64架构：sha256sum /home/redis_arm64_6.2.6.tar > redis_sha256.txt
2. x86_64架构：sha256sum /home/redis_x86_64_6.2.6.tar > redis_sha256.txt

至此，外网准备工作完成。根据目标服务器架构，将对应的Docker离线包、Redis镜像包（及redis_sha256.txt）通过安全介质，传输到内网麒麟V10目标服务器的 /home 目录下。

三、第二步：内网部署——麒麟V10安装Docker（分架构）

目标服务器为无外网权限的麒麟V10（arm64/x86_64），需根据架构，通过对应离线rpm包安装Docker，步骤如下（分架构执行）：

3.1 解压Docker离线包（分架构）

cd /home
# 分架构解压，释放rpm文件
# arm64架构
tar -xzvf docker_arm64_20.10.24.tar.gz
# x86_64架构
tar -xzvf docker_x86_64_20.10.24.tar.gz

3.2 离线安装Docker依赖与核心包（分架构）

进入解压后的rpm包目录，执行安装命令（需root权限，若提示依赖缺失，需提前准备对应离线依赖包，依赖包架构需与目标服务器一致）：

cd /home/docker_offline
# 安装3个rpm包（顺序无关，--nodeps可忽略依赖检查，若有依赖需提前安装）
# arm64架构
rpm -ivh --nodeps containerd.io-xxx.aarch64.rpm docker-ce-cli-xxx.aarch64.rpm docker-ce-xxx.aarch64.rpm
# x86_64架构
rpm -ivh --nodeps containerd.io-xxx.x86_64.rpm docker-ce-cli-xxx.x86_64.rpm docker-ce-xxx.x86_64.rpm

3.3 启动Docker并设置开机自启

# 启动Docker服务
systemctl start docker
# 设置开机自启（关键，避免服务器重启后Docker失效）
systemctl enable docker
# 验证Docker安装成功
docker --version
# 查看Docker运行状态（Active: active (running) 即为正常）
systemctl status docker | grep Active

若启动失败，大概率是依赖缺失或rpm包架构错误。可执行 systemctl status docker 查看错误日志，补充对应依赖或重新下载正确架构的rpm包。

第三步：内网部署——Docker加载并运行Redis（环境验证，分架构）

Docker安装完成后，即可加载提前传输的对应架构Redis镜像，启动容器并完成简单验证，确认Docker环境正常可用（Redis仅作为验证工具，无需复杂配置）。

3.1 导入Redis镜像（分架构）

将传输到 /home 目录的对应架构Redis镜像包导入Docker本地仓库：

cd /home
# 分架构导入镜像
# arm64架构
docker load -i redis_arm64_6.2.6.tar
# x86_64架构
docker load -i redis_x86_64_6.2.6.tar
# （可选）核对文件完整性，确保传输未损坏
sha256sum -c redis_sha256.txt

导入成功后，执行 docker images 会看到一个无标签（REPOSITORY和TAG为）的镜像，需为其打上易识别的标签（标注架构），方便后续管理：

# 查看镜像ID（假设为 1234567890ab）
docker images
# 分架构打标签（格式：镜像名:版本-架构）
# arm64架构
docker tag 1234567890ab redis:6.2.6-arm64
# x86_64架构
docker tag 1234567890ab redis:6.2.6-x86_64
# 验证标签
docker images | grep redis

3.2 配置Redis数据持久化（可选，验证环境可省略）

若仅作为环境验证，可省略数据持久化；若需简单留存数据，可将Redis数据目录挂载到宿主机（生产环境建议配置，验证环境可跳过）：

# 创建宿主机数据目录（验证环境可省略）
sudo mkdir -p /data/redis/data
# 赋予目录读写权限
sudo chmod 755 /data/redis
# 进阶：修改目录所属用户（匹配容器内默认用户，避免权限报错）
sudo chown -R 999:999 /data/redis/data

3.3 启动Redis容器（环境验证版，分架构）

使用 docker run 命令启动容器，配置端口映射、自启等基础参数，确保容器正常运行，用于验证Docker环境可用（无需复杂配置，仅开启基础服务）：

# 分架构启动容器，验证环境无需复杂配置
# arm64架构
docker run -d \
  --name redis-server \ # 容器名称，便于管理
  --restart=always \ # 容器随Docker自启，保障可用性
  -p 6379:6379 \ # 端口映射：宿主机6379端口映射到容器6379端口（Redis默认端口）
  # 验证环境可省略数据挂载，如需挂载添加以下一行
  # -v /data/redis/data:/data \
  redis:6.2.6-arm64 \ # 镜像标签（arm64架构）
  --requirepass "RedisTest123!" # 简单设置密码，避免未授权访问（验证环境可选）

# x86_64架构
docker run -d \
  --name redis-server \ # 容器名称，便于管理
  --restart=always \ # 容器随Docker自启，保障可用性
  -p 6379:6379 \ # 端口映射：宿主机6379端口映射到容器6379端口（Redis默认端口）
  # 验证环境可省略数据挂载，如需挂载添加以下一行
  # -v /data/redis/data:/data \
  redis:6.2.6-x86_64 \ # 镜像标签（x86_64架构）
  --requirepass "RedisTest123!" # 简单设置密码，避免未授权访问（验证环境可选）

参数说明（验证环境重点）：

-d：后台运行容器，不占用终端；
–restart=always：服务器重启、Docker重启后，容器自动启动，便于长期验证；
-p 6379:6379：Redis默认端口映射，便于后续连接验证；
–requirepass：简单设置密码，避免内网未授权访问（验证环境可选，提升安全性）。

启动后，验证容器状态（确认Docker环境正常）：

1	docker ps \| grep redis-server

若 STATUS 为 Up，说明Redis容器已成功运行，Docker环境部署正常，达到环境验证目的。

四、第四步：环境验证——Redis连接测试（核心，确认环境可用）

Redis容器启动后，通过简单的连接命令，验证Docker容器运行正常、Redis服务可用，完成整个环境验证流程。

4.1 容器内连接Redis测试

# 进入Redis容器内部
docker exec -it redis-server /bin/bash
# 连接Redis（若设置了密码，需输入密码）
redis-cli
# 输入密码（若设置了--requirepass参数）
auth RedisTest123!
# 执行简单命令，验证服务可用
ping

若输出 PONG，说明Redis服务正常运行，Docker容器部署无误，环境验证通过。

4.2 宿主机连接Redis测试（可选）

# 宿主机直接连接Redis（需确保宿主机安装了redis-cli，或使用Docker命令间接连接）
# 方法1：使用Docker命令间接连接
docker exec -it redis-server redis-cli -a RedisTest123! ping
# 方法2：宿主机安装redis-cli后直接连接
redis-cli -h 127.0.0.1 -p 6379 -a RedisTest123! ping

若输出 PONG，说明宿主机与容器通信正常，整个Docker+Redis环境验证完成。

4.3 常见验证失败排查

容器启动失败：检查镜像架构是否与目标服务器一致，执行 docker logs redis-server 查看错误日志；
ping命令无响应：检查容器是否正常运行（docker ps），密码是否输入正确，防火墙是否开放6379端口；
防火墙开放端口（若无法连接）：sudo firewall-cmd --zone=public --add-port=6379/tcp --permanent sudo firewall-cmd --reload

五、安全加固与环境清理（验证环境可选）

若仅作为临时环境验证，使用完成后可清理容器和镜像，释放服务器资源；若需长期保留，可进行简单安全加固。

5.1 环境清理（临时验证用）

# 停止Redis容器
docker stop redis-server
# 删除Redis容器
docker rm redis-server
# 删除Redis镜像（按需执行）
# arm64架构：docker rmi redis:6.2.6-arm64
# x86_64架构：docker rmi redis:6.2.6-x86_64

5.2 简单安全加固（长期保留用）

端口限制：通过防火墙限制仅允许内部指定IP访问6379端口，避免内网未授权访问；
密码加固：设置复杂密码，避免简单密码泄露；
容器资源限制：若长期保留，可限制容器内存和CPU使用，避免占用过多服务器资源： # 启动容器时添加资源限制参数（以arm64为例，x86_64替换镜像标签即可） docker run -d \ --name redis-server \ --restart=always \ -p 6379:6379 \ --memory="1g" \ # 限制容器最大使用1GB内存 --cpus="1.0" \ # 限制容器最大使用1个CPU核心 redis:6.2.6-arm64 --requirepass "RedisTest123!"

六、总结

本文完整覆盖了麒麟V10（arm64/x86_64两种架构）内网环境下，Docker离线安装、Redis（环境验证版）离线部署与测试的全流程，核心要点是“架构匹配”和“环境验证”——确保Docker安装包、Redis镜像均与目标服务器架构一致，提前在外网完成资源准备，内网仅需执行安装、加载、启动和简单测试，即可完成Docker环境验证。

整个流程避开了源码编译、依赖冲突等坑点，通过Docker容器化方式，保证了环境一致性和部署便捷性，适用于政企单位、涉密项目等无外网场景的Docker环境验证。Redis仅作为验证工具，配置简单、操作便捷，能快速确认Docker环境部署成功；若需部署其他Docker应用，可参考本文“外网准备-内网部署”的思路，替换对应镜像即可。

若实际操作中遇到问题，优先查看容器日志和系统日志，大部分错误均可通过日志定位并解决；两种架构的核心操作一致，仅需注意安装包和镜像的架构区分，新手也能轻松落地。

基于Docker部署Label Studio私有标注平台

发表于 2026-03-14 更新于 2026-04-28

Label Studio是一款开源、多模态的数据标注工具，支持图像、文本、视频、音频等多种数据类型的标注任务，广泛应用于机器学习数据预处理场景。本文基于Docker容器化技术，详细讲解Label Studio的私有部署流程，整合Nginx反向代理、外部Redis缓存、外部PostgreSQL数据库配置，实现安全、高效、可协作的私有标注平台搭建，适配企业内网多人协作、敏感数据私有化存储的核心需求。

一、部署背景与核心需求

在实际企业应用中，数据标注往往涉及敏感信息（如隐私图片、内部文档），因此私有化部署是必然选择。本次部署需满足以下核心需求：

私有化部署：所有标注数据、配置信息存储在内网，杜绝数据外流；
多人协作：支持多角色用户（管理员、标注员、审核员）权限管理，实现数据集隔离；
安全访问：隐藏Label Studio核心服务端口，通过Nginx反向代理对外暴露访问入口；
稳定可靠：复用宿主机外部Redis（缓存）和PostgreSQL（数据库），提升服务稳定性和可维护性；
易用性：简化访问方式，用户无需记忆复杂端口，通过固定端口即可访问。

二、前置条件准备

部署前需确保服务器满足以下环境要求，避免因依赖缺失导致部署失败：

2.1 环境版本要求

环境/工具	版本要求	检查与安装命令
操作系统	Linux（Ubuntu 20.04+/CentOS 7+）	无（推荐Ubuntu，兼容性更好）
Docker	20.10+	检查：`docker -v`；安装：`curl -fsSL https://get.docker.com \| sh`
Docker Compose	V2+	检查：`docker compose version`；安装：`apt install docker-compose-plugin`（Ubuntu）
Nginx	1.18+	检查：`nginx -v`；安装：`apt install nginx`（Ubuntu）/ `yum install nginx`（CentOS）
PostgreSQL	13+/14+	部署在宿主机，检查：`systemctl status postgresql`
Redis	6+/7+	部署在宿主机，检查：`systemctl status redis`
端口	8081（Nginx对外）、9000（Label Studio本机）、5432（PG）、6379（Redis）	检查端口占用：`netstat -tulpn \| grep 端口号`

2.2 核心前置配置（关键！）

本次部署使用宿主机已有的Redis和PostgreSQL（无自定义Docker Network），需提前配置两者允许容器访问，否则会出现连接失败问题。

2.2.1 宿主机PostgreSQL配置

登录PostgreSQL，创建Label Studio专属数据库和用户（用于容器连接）： -- 创建数据库 CREATE DATABASE label_studio; -- 创建用户（替换your_pg_pass为自定义密码） CREATE USER label_studio WITH PASSWORD 'your_pg_pass'; -- 赋予用户数据库全权限 GRANT ALL PRIVILEGES ON DATABASE label_studio TO label_studio;
修改PostgreSQL配置文件，允许容器访问：
1. 编辑postgresql.conf（路径通常为/etc/postgresql/版本/main/postgresql.conf）： listen_addresses = '*' # 允许所有IP访问（内网环境安全）
2. 编辑pg_hba.conf（同上述路径），添加容器网段和宿主机授权： # 允许Docker容器网段（默认172.17.0.0/16）访问 host label_studio label_studio 172.17.0.0/16 md5 # 允许宿主机本地访问 host label_studio label_studio 127.0.0.1/32 md5
重启PostgreSQL服务：systemctl restart postgresql

2.2.2 宿主机Redis配置

编辑Redis配置文件redis.conf（路径通常为/etc/redis/redis.conf）： bind 0.0.0.0 # 允许所有IP访问（内网环境） protected-mode no # 关闭保护模式，允许容器访问 requirepass your_redis_pass # 配置密码（可选，推荐，替换为自定义密码）
重启Redis服务：systemctl restart redis

三、分步部署Label Studio（Docker+Nginx）

本次部署采用Docker Compose管理容器，整合Label Studio和Nginx两个核心服务，Label Studio仅绑定本机端口，通过Nginx反向代理对外暴露8081端口，确保服务安全。

3.1 创建部署目录（统一管理文件）

为避免配置文件混乱，创建统一的部署目录，所有数据、配置文件均存储在此目录下：

# 创建核心部署目录
mkdir -p /opt/label-studio/{data,conf,nginx}
# 进入部署目录
cd /opt/label-studio

目录说明：

data：存储Label Studio标注数据、日志等（持久化）；
conf：存储Label Studio配置文件；
nginx：存储Nginx反向代理配置文件和缓存文件。

3.2 编写Docker Compose配置文件

在/opt/label-studio目录下创建docker-compose.yml文件，核心配置如下（已整合所有需求，可直接复制使用，需替换自定义密码和宿主机IP）：

version: '3.8'

services:
  # Label Studio 核心服务（仅本机可访问，绑定9000端口）
  label-studio:
    image: heartexlabs/label-studio:latest
    container_name: label-studio
    restart: always
    environment:
      # 连接宿主机PostgreSQL配置
      - LABEL_STUDIO_DB=postgres
      - LABEL_STUDIO_DB_HOST=192.168.1.100  # 替换为宿主机内网IP
      - LABEL_STUDIO_DB_PORT=5432
      - LABEL_STUDIO_DB_USER=label_studio
      - LABEL_STUDIO_DB_PASSWORD=your_pg_pass  # 替换为之前创建的PG密码
      - LABEL_STUDIO_DB_NAME=label_studio
      # 连接宿主机Redis配置
      - REDIS_HOST=192.168.1.100  # 替换为宿主机内网IP
      - REDIS_PORT=6379
      - REDIS_PASSWORD=your_redis_pass  # 替换为Redis密码，无则删除该行
      - REDIS_DB=0
      # 基础配置
      - ALLOWED_HOSTS=*
      - LABEL_STUDIO_DATA_DIR=/label-studio/data
    volumes:
      - ./data:/label-studio/data
      - ./conf:/label-studio/conf
    # 核心：仅绑定本机127.0.0.1:9000，外部无法直接访问
    ports:
      - 127.0.0.1:9000:8080
    # Linux系统兼容host.docker.internal（可选，用于容器访问宿主机）
    extra_hosts:
      - "host.docker.internal:host-gateway"
    networks:
      - label-studio-net

  # Nginx 反向代理服务（对外暴露8081端口）
  nginx:
    image: nginx:1.23-alpine
    container_name: label-studio-nginx
    restart: always
    ports:
      - "8081:80"  # 宿主机8081端口映射到容器80端口（对外访问入口）
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ./nginx/cache:/var/cache/nginx
    depends_on:
      - label-studio  # 确保Label Studio启动后再启动Nginx
    extra_hosts:
      - "host.docker.internal:host-gateway"
    networks:
      - label-studio-net

# 容器内部网络（仅用于Label Studio和Nginx通信）
networks:
  label-studio-net:
    driver: bridge

3.3 编写Nginx反向代理配置

在/opt/label-studio/nginx目录下创建nginx.conf文件，核心作用是将外部8081端口的请求，代理到本机9000端口的Label Studio服务，同时优化访问性能和大文件上传体验：

server {
    listen 80;  # 容器内部监听80端口，与Docker映射对应
    server_name _;  # 匹配所有IP，无需配置域名

    # 支持大文件上传（标注视频/图片常用，可根据需求调整大小）
    client_max_body_size 10G;

    # 传递真实访问IP和请求信息，便于日志排查
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # 超时配置，避免大文件上传超时
    proxy_connect_timeout 300s;
    proxy_send_timeout 300s;
    proxy_read_timeout 300s;

    # 核心反向代理逻辑：将请求转发到本机9000端口（Label Studio）
    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_redirect off;
    }

    # 静态文件缓存（CSS/JS/图片等），提升访问速度
    location /static/ {
        proxy_pass http://127.0.0.1:9000/static/;
        expires 30d;  # 缓存30天
        add_header Cache-Control "public, max-age=2592000";
    }
}

3.4 启动服务并验证

启动容器服务（后台运行）： docker compose up -d
检查服务运行状态（确保所有容器均为Up状态）： docker compose ps若出现Exited状态，可通过日志排查问题：docker compose logs -f label-studio
访问验证：
1. 本机测试：curl http://127.0.0.1:9000，应返回Label Studio登录页面HTML内容；
2. 外部/内网测试：浏览器打开http://宿主机IP:8081（如http://192.168.1.100:8081），进入Label Studio登录页面，说明部署成功；
3. 安全验证：外部机器访问http://宿主机IP:9000，应无法访问（符合预期，确保Label Studio不对外暴露）。
首次登录配置：首次访问http://宿主机IP:8081，会引导创建超级管理员账号（用户名、密码、邮箱），记住该账号，用于后续用户管理和项目配置。

四、关键配置说明与优化

4.1 端口安全设计（核心亮点）

本次部署采用“Label Studio本机隐藏+Nginx反向代理”的安全架构，核心设计如下：

Label Studio端口映射为127.0.0.1:9000:8080，仅宿主机本机可直接访问，外部无法直接发起请求，避免核心服务被恶意攻击；
Nginx对外仅暴露8081端口，所有用户通过该端口访问，由Nginx统一转发请求，相当于给Label Studio加了一层“防护屏障”；
防火墙仅需放行8081端口，无需放行9000、5432、6379端口，进一步提升内网安全性。

4.2 外部Redis/PG连接说明

本次部署未使用Docker内置的Redis和PostgreSQL，而是复用宿主机已有的实例，优势如下：

统一管理：企业内网通常已有数据库/缓存集群，复用现有实例可减少资源浪费，便于统一运维和数据备份；
数据安全：数据库和缓存数据存储在宿主机，而非Docker容器，避免容器删除导致数据丢失；
灵活扩展：后续可根据需求，将Redis/PG替换为集群架构，无需修改Label Studio配置。

注意：配置中LABEL_STUDIO_DB_HOST和REDIS_HOST必须填写宿主机内网IP，不可使用localhost（容器内localhost指向自身，而非宿主机）。

4.3 性能优化配置

大文件上传：Nginx配置client_max_body_size 10G，支持GB级视频、图片上传，避免上传超时；
静态文件缓存：Nginx对Label Studio的静态资源（CSS/JS/图片）进行30天缓存，减少重复请求，提升页面加载速度；
超时配置：延长代理超时时间至300s，适配标注过程中长时间连接的场景。

五、多人权限管理与数据集导入

5.1 多角色用户管理

登录超级管理员账号后，可创建多角色用户，实现多人协作和数据集隔离：

点击顶部导航栏「Settings」→「Users」；
点击「Create User」，填写用户名、密码，选择角色：
1. Annotator（标注员）：仅能标注分配的任务，无审核和管理权限；
2. Reviewer（审核员）：可标注并审核标注结果，确保标注质量；
3. Admin（管理员）：全权限，可管理用户、项目和配置（谨慎分配）。
为用户分配项目权限：进入目标项目→「Settings」→「Access」，添加用户并分配View（仅查看）、Edit（可标注）、Owner（项目所有者）权限。

5.2 数据集导入（私有化存储）

Label Studio支持多种数据集导入方式，适配不同规模的标注需求，所有数据均存储在宿主机/opt/label-studio/data目录，确保私有化：

小数据集：进入项目→「Import」→「Upload Files」，批量上传本地文件（图片、文本、视频等）；
大数据集（推荐）：将内网数据集文件夹挂载到容器，避免直接上传耗时： # 1. 创建内网数据集目录 mkdir -p /data/label-dataset # 2. 修改docker-compose.yml，添加卷挂载（在volumes下新增） volumes: - ./data:/label-studio/data - ./conf:/label-studio/conf - /data/label-dataset:/label-studio/dataset # 3. 重启服务 docker compose down && docker compose up -d导入时选择「Local Storage」，找到/label-studio/dataset目录即可批量导入。

六、常用运维命令与故障排查

6.1 常用运维命令

操作需求	命令
启动服务	`docker compose up -d`
停止服务	`docker compose down`
重启服务	`docker compose restart`
查看Label Studio日志	`docker compose logs -f label-studio`
查看Nginx日志	`docker compose logs -f nginx`
备份数据（核心）	`cp -r /opt/label-studio/data /backup/label-studio-$(date +%Y%m%d)`
重置管理员密码	`docker exec -it label-studio python manage.py changepassword 用户名`

6.2 常见故障排查

问题1：Label Studio启动失败，日志提示“could not connect to postgres/redis” 排查：① 确认宿主机Redis/PG服务正在运行；② 检查配置文件中IP、端口、密码是否正确；③ 确认宿主机防火墙放行5432、6379端口；④ 检查PG/Redis配置是否允许外部访问。
问题2：访问http://宿主机IP:8081无法打开页面排查：① 检查Nginx和Label Studio容器是否正常运行；② 确认宿主机防火墙放行8081端口；③ 查看Nginx日志，确认反向代理配置是否正确。
问题3：大文件上传失败，提示超时排查：修改Nginx配置中的client_max_body_size、proxy_read_timeout参数，增大数值后重启Nginx。

七、总结

本文基于Docker容器化技术，完成了Label Studio私有标注平台的完整部署，整合了Nginx反向代理、外部Redis缓存、外部PostgreSQL数据库，实现了以下核心目标：

私有化安全：所有数据存储在内网，Label Studio仅本机可访问，通过Nginx反向代理对外暴露，杜绝数据外流和恶意攻击；
多人协作：支持多角色用户管理和数据集隔离，适配企业团队标注场景；
稳定高效：复用宿主机现有Redis/PG，优化大文件上传和页面加载性能，适合长期使用；
易用易维护：通过Docker Compose统一管理容器，运维命令简洁，故障排查便捷。

本部署方案适用于企业内网、敏感数据标注场景，可根据实际需求扩展功能（如配置HTTPS加密、集成MinIO私有存储、批量导入/导出标注数据），进一步提升平台的安全性和实用性。