Harness 教程 01：平台介绍与环境搭建（国内网络环境落地版）

如果你正在做 DevOps 或平台工程，大概率已经听说过 Harness。

简单来说，Harness 是一个面向云原生时代的端到端交付平台，涵盖 CI、CD、Feature Flags、混沌工程、Cloud Cost Management、安全合规（SSCA）、内部开发者门户（IDP）等能力。

它的想法很有意思：用 AI 和智能化的方式，把过去需要手动配置的部署变成可审计、可治理、可重复的流程。

但问题也很现实——Harness 的中文资料非常少，官方文档虽然齐全，但信息分散，缺乏一条清晰的学习路径。对于刚接触的团队来说，从哪开始、重点在哪、如何落地，都让人头疼。

所以，我花了些时间，整理了这么一套教程。

这套教程是给谁的

如果你符合以下任一角色，这套教程应该对你有用：

• DevOps 工程师

  ：你需要设计 CI/CD 流水线，管理多环境部署，让发布更稳更快

• SRE

  ：可观测性、自动化恢复、回滚策略、混沌工程是你日常关注的

• 平台工程师

  ：你在搭建内部开发者平台，让开发团队能自助式交付

• 技术管理者

  ：你关心标准化、治理合规、成本控制、团队协作效率

如果你是刚接触 Harness 的新手，按顺序从第一篇读下去就行。如果你已经在使用，可以直接跳到感兴趣的专题。

一、为什么国内环境不能直接照搬国外教程？

很多 Harness 官方或海外教程默认使用：

• GitHub

• DockerHub

• npm 官方源

• 公网 Kubernetes

• 公网制品仓库

但在国内企业落地时，这些链路经常会遇到访问慢、连接失败、镜像拉取失败、构建超时、企业防火墙限制、内网 Git 无法被 SaaS 直接访问等问题。

所以本文采用国内落地基线：

国外默认

国内替代方案

GitHub

GitLab / Gitee / 内网代码仓库

DockerHub

Harbor / 阿里云 ACR / 腾讯云 TCR / 华为云 SWR

npm 官方源

npmmirror

公网部署

国内 K8s / 企业内网 K8s

明文密码

Harness Secret

直接访问内网

Harness Delegate 代理访问

Harness 的关键组件是 Delegate。官方文档中，Harness Delegate 被定义为运行在本地网络或 VPC 中的服务，用来把制品、基础设施、协作工具、验证工具和其他第三方系统连接到 Harness Manager，Delegate 会执行部署和集成等操作。

二、本文最终架构

国内环境推荐采用下面这种架构：

code

复制

开发人员  │  ├── GitLab / Gitee  │  ├── Harbor / 国内云镜像仓库  │  └── Kubernetes 集群        │        └── Harness Delegate              │ 出站 HTTPS/WSS              ▼        Harness SaaS

重点是：

• Harness SaaS

  负责编排、可视化、审计、流水线配置

• Delegate

  负责访问企业内网 Git、Harbor、Kubernetes、云厂商 API

官方文档说明，Delegate 与 Harness Manager 之间通过出站 HTTPS/WSS 连接通信；同时 Harness 建议把 Delegate 安装在防火墙之后，并确保它能访问制品服务器、部署环境和云平台等目标资源。

三、核心概念快速入门

1. Harness SaaS

Harness SaaS 是你登录的 Web 控制台，主要负责：

• 创建项目

• 创建流水线

• 管理环境

• 管理连接器

• 管理密钥

• 查看执行日志

• 审批发布

• 审计发布记录

国内企业如果允许访问 SaaS，可以直接使用 Harness SaaS。如果是政务、强内网、完全离线环境，则需要评估 Harness Self-Managed 或离线部署方案。Harness Delegate Helm 安装文档中也提到，Self-Managed Enterprise Edition 的 air-gapped 环境需要额外处理证书和离线安装要求。

2. Delegate

Delegate 是部署在你自己网络里的执行代理。

它的职责是：

• 访问内网 GitLab

• 访问 Harbor

• 访问 Kubernetes API Server

• 执行 kubectl / helm / shell

• 拉取 Manifest

• 执行部署

• 回传执行状态

在国内环境中，Delegate 非常重要，因为 Harness SaaS 通常不能直接访问企业内网的 GitLab、Harbor 和 Kubernetes。

3. Connector

Connector 是 Harness 连接外部系统的配置，例如：

• GitLab Connector

• Gitee Connector

• Harbor Connector

• Kubernetes Cluster Connector

• 阿里云 Connector

• 腾讯云 Connector

• Prometheus Connector

国内落地时，Connector 要尽量选择：

• Execute on Delegate: true
• Delegate Selector: cn-k8s-dev

意思是让 Delegate 去访问内网资源，而不是让 Harness SaaS 直接访问。

4. Secret

Secret 用来保存密码、Token、AccessKey、Harbor 机器人账号 Token 等敏感信息。

不要把密码写进 Pipeline YAML 或 Git 仓库。

Harness Connector YAML 示例中，Docker Registry Connector 就是通过 passwordRef 引用 Secret，而不是直接写密码。

5. Pipeline、Stage、Step

Harness 的流水线层级可以这样理解：

code

复制

Pipeline：完整流水线  └── Stage：阶段，例如构建、部署、审批        └── Step：具体动作，例如执行脚本、部署 K8s、运行测试

Harness 官方 YAML 文档说明，Pipeline 顶层包含 pipeline，下面包含 name、identifier、projectIdentifier、orgIdentifier、stages 等字段；stages 用来定义多个阶段。

四、环境准备

本文建议准备下面这些环境。

1. 基础组件

• Harness SaaS 账号

• Kubernetes 集群

• kubectl

• Helm 3

• GitLab / Gitee

• Harbor / 国内云镜像仓库

• Node.js 示例项目

2. 国内推荐选型

类型

推荐方案

代码仓库

GitLab CE、GitLab 企业版、Gitee 企业版

镜像仓库

Harbor、阿里云 ACR、腾讯云 TCR、华为云 SWR

Kubernetes

自建 K8s、ACK、TKE、CCE、Rancher 管理集群

npm 源

npmmirror

CI/CD 平台

Harness SaaS + Delegate

生产环境访问方式

Delegate + 企业代理 / 专线 / VPC 内访问

Harbor 官方文档说明，Harbor 文档覆盖安装配置、管理员运维和项目管理等内容，适合作为企业容器镜像仓库使用。

npmmirror 官方说明它是 npmjs 的完整镜像，可以代替官方版本使用，并提供了 npm config set registry https://registry.npmmirror.com 的配置方式。

五、推荐仓库结构

本教程先准备一个最小可用项目，后续 30 篇教程都可以基于这个结构继续扩展。

code

复制

harness-demo-app/├── README.md├── .npmrc├── app/│   ├── package.json│   └── server.js├── docker/│   └── Dockerfile├── k8s/│   ├── namespace.yaml│   ├── deployment.yaml│   └── service.yaml├── harness/│   ├── pipeline-empty-cn.yaml│   └── connectors/│       ├── gitlab-connector.yaml│       └── harbor-connector.yaml└── scripts/    ├── check-network-cn.sh    ├── sync-base-images.sh    └── install-delegate-cn.sh

六、准备 Node.js 示例服务

1. .npmrc

项目根目录创建 .npmrc：

ini

复制

registry=https://registry.npmmirror.comfetch-retries=5fetch-retry-mintimeout=20000fetch-retry-maxtimeout=120000

作用：

• 让 npm install 使用国内 npm 镜像

• 降低构建阶段网络超时概率

• 提高后续 CI 流水线稳定性

2. app/package.json

json

复制

{"name":"harness-demo-app","version":"1.0.0","description":"Harness 国内网络环境示例服务","main":"server.js","scripts":{"start":"node server.js","test":"node -e \"console.log('unit test passed')\""},"dependencies":{"express":"^4.18.3"}}

3. app/server.js

js

复制

const express = require("express");const app = express();const port = process.env.PORT || 3000;app.get("/", (req, res) => {  res.json({app: "harness-demo-app",env: process.env.APP_ENV || "dev",version: process.env.APP_VERSION || "v1",message: "Hello Harness China Network"  });});app.get("/health", (req, res) => {  res.status(200).json({status: "UP"  });});app.listen(port, () => {console.log(`server started on port ${port}`);});

七、准备国内版 Dockerfile

docker/Dockerfile

dockerfile

复制

FROM harbor.company.com/library/node:20-alpineWORKDIR /appCOPY .npmrc ./COPY app/package*.json ./RUN npm install --omit=devCOPY app/server.js ./ENV PORT=3000ENV APP_ENV=devEXPOSE3000CMD ["node", "server.js"]

需要替换：

code

复制

harbor.company.com/library/node:20-alpine

改成你自己的 Harbor 地址，例如：

code

复制

harbor.xxx.com/library/node:20-alpineregistry.cn-hangzhou.aliyuncs.com/company/node:20-alpine

国内落地建议：不要让 Dockerfile 直接使用 node:20-alpine，而是先同步到企业镜像仓库。

八、准备 Kubernetes 配置

1. k8s/namespace.yaml

yaml

复制

apiVersion:v1kind:Namespacemetadata:name:dev

2. k8s/deployment.yaml

yaml

复制

apiVersion:apps/v1kind:Deploymentmetadata:name:harness-demo-appnamespace:devlabels:app:harness-demo-appspec:replicas:1selector:matchLabels:app:harness-demo-apptemplate:metadata:labels:app:harness-demo-appspec:imagePullSecrets:-name:harbor-pull-secretcontainers:-name:harness-demo-appimage:harbor.company.com/devops/harness-demo-app:latestimagePullPolicy:Alwaysports:-containerPort:3000env:-name:APP_ENVvalue:"dev"-name:APP_VERSIONvalue:"v1"readinessProbe:httpGet:path:/healthport:3000initialDelaySeconds:5periodSeconds:10livenessProbe:httpGet:path:/healthport:3000initialDelaySeconds:15periodSeconds:20

需要替换：

code

复制

harbor.company.com/devops/harness-demo-app:latest

改成你的真实镜像仓库地址。

3. k8s/service.yaml

yaml

复制

apiVersion:v1kind:Servicemetadata:name:harness-demo-appnamespace:devspec:selector:app:harness-demo-appports:-name:httpport:80targetPort:3000type:ClusterIP

九、国内网络预检查脚本

scripts/check-network-cn.sh

bash

复制

#!/usr/bin/env bashset -eecho"==== 1. 检查 Harness SaaS ===="curl -I --connect-timeout 10 https://app.harness.io || trueecho"==== 2. 检查 GitLab / Gitee ===="curl -k -I --connect-timeout 10 https://gitlab.company.com || trueecho"==== 3. 检查 Harbor ===="curl -k -I --connect-timeout 10 https://harbor.company.com/v2/ || trueecho"==== 4. 检查 npm 国内镜像 ===="curl -I --connect-timeout 10 https://registry.npmmirror.com || trueecho"==== 5. 检查 Kubernetes 集群 ===="kubectl get nodeskubectl get nsecho"==== 检查完成 ===="

执行：

bash

复制

chmod +x scripts/check-network-cn.sh./scripts/check-network-cn.sh

你需要把下面两个地址替换成自己的地址：

• https://gitlab.company.com
• https://harbor.company.com

十、同步基础镜像到 Harbor

scripts/sync-base-images.sh

bash

复制

#!/usr/bin/env bashset -eHARBOR_HOST="harbor.company.com"HARBOR_LIBRARY_PROJECT="library"HARBOR_PLATFORM_PROJECT="platform"NODE_IMAGE="node:20-alpine"DELEGATE_IMAGE="harness/delegate:25.01.x"echo"==== 登录 Harbor ===="docker login ${HARBOR_HOST}echo"==== 同步 Node 基础镜像 ===="docker pull ${NODE_IMAGE}docker tag ${NODE_IMAGE}${HARBOR_HOST}/${HARBOR_LIBRARY_PROJECT}/node:20-alpinedocker push ${HARBOR_HOST}/${HARBOR_LIBRARY_PROJECT}/node:20-alpineecho"==== 同步 Harness Delegate 镜像 ===="docker pull ${DELEGATE_IMAGE}docker tag ${DELEGATE_IMAGE}${HARBOR_HOST}/${HARBOR_PLATFORM_PROJECT}/harness-delegate:25.01.xdocker push ${HARBOR_HOST}/${HARBOR_PLATFORM_PROJECT}/harness-delegate:25.01.xecho"==== 基础镜像同步完成 ===="

需要替换：

• harbor.company.com
• harness/delegate:25.01.x

Delegate 版本不要随便猜，建议从 Harness 控制台安装 Delegate 页面复制。

十一、安装 Harness Delegate

1. 获取 Delegate Token

在 Harness 控制台中进入：

Account Settings → Account Resources → Delegates → Tokens → New Token

创建：

Token Name: first-delegate-token

复制生成的 Token。

官方文档说明，Delegate Token 会作为安装参数提供给 Delegate，用于认证 Harness Platform。

2. 获取 Account ID

Harness Account ID 可以在 Harness URL 中找到。

例如：

code

复制

https://app.harness.io/ng/#/account/6_vVHzo9Qeu9fXvj-AcQCb/settings/overview

其中 6_vVHzo9Qeu9fXvj-AcQCb 就是 Account ID。官方文档也说明，accountId 会出现在每个 Harness URL 中，并且安装 Delegate 时需要提供。

3. 使用 Helm 安装 Delegate

官方安装文档给出的 Helm 方式是先添加 harness-delegate Helm 仓库，然后使用 harness-delegate/harness-delegate-ng Chart 安装 Delegate；安装参数包括 delegateName、accountId、delegateToken、managerEndpoint、delegateDockerImage 等。

国内环境建议写成脚本。

scripts/install-delegate-cn.sh

bash

复制

#!/usr/bin/env bashset -eDELEGATE_NAME="firstk8sdel"NAMESPACE="harness-delegate-ng"HARNESS_ACCOUNT_ID="替换成你的 Harness Account ID"HARNESS_DELEGATE_TOKEN="替换成你的 Harness Delegate Token"HARNESS_MANAGER_ENDPOINT="https://app.harness.io"DELEGATE_IMAGE="harbor.company.com/platform/harness-delegate:25.01.x"echo"==== 添加 Harness Delegate Helm 仓库 ===="helm repo add harness-delegate https://app.harness.io/storage/harness-download/delegate-helm-chart/ || truehelm repo updateecho"==== 安装 / 更新 Harness Delegate ===="helm upgrade -i ${DELEGATE_NAME} \  --namespace ${NAMESPACE} \  --create-namespace \  harness-delegate/harness-delegate-ng \  --set delegateName=${DELEGATE_NAME} \  --set accountId=${HARNESS_ACCOUNT_ID} \  --set delegateToken=${HARNESS_DELEGATE_TOKEN} \  --set managerEndpoint=${HARNESS_MANAGER_ENDPOINT} \  --set delegateDockerImage=${DELEGATE_IMAGE} \  --set replicas=1 \  --set upgrader.enabled=trueecho"==== 国内网络常见配置：关闭 Stackdriver 远程日志 ===="kubectl setenv deployment/${DELEGATE_NAME} \  -n ${NAMESPACE} \  STACK_DRIVER_LOGGING_ENABLED=falseecho"==== 等待 Delegate 启动 ===="kubectl rollout status deployment/${DELEGATE_NAME} -n ${NAMESPACE}kubectl get pods -n ${NAMESPACE}

执行：

bash

复制

chmod +x scripts/install-delegate-cn.sh./scripts/install-delegate-cn.sh

国内企业网络如果阻断 Google Stackdriver Logging API，可以把 Delegate 的 STACK_DRIVER_LOGGING_ENABLED 设置为 false，官方文档也说明该变量可用于禁用远程日志并避免连接问题。

4. 如果企业必须走代理

如果服务器不能直接访问 Harness SaaS，需要在 Delegate 上增加代理环境变量。

bash

复制

kubectl setenv deployment/firstk8sdel \  -n harness-delegate-ng \  HTTP_PROXY=http://proxy.company.com:3128 \  HTTPS_PROXY=http://proxy.company.com:3128 \  NO_PROXY=localhost,127.0.0.1,.svc,.cluster.local,gitlab.company.com,harbor.company.com,kubernetes.default.svc

NO_PROXY 一定要包含内网服务，否则 Delegate 访问 GitLab、Harbor、Kubernetes API Server 时可能被错误转发到代理。

5. 验证 Delegate

bash

复制

kubectl get pods -n harness-delegate-ngkubectl logs -f deployment/firstk8sdel -n harness-delegate-ng

然后回到 Harness 控制台：

Account Settings → Account Resources → Delegates

看到状态为 Connected / Available，说明 Delegate 安装成功。

十二、创建 Harbor 拉取密钥

在 Kubernetes 中创建镜像拉取密钥：

bash

复制

kubectl apply -f k8s/namespace.yamlkubectl create secret docker-registry harbor-pull-secret \  --docker-server=harbor.company.com \  --docker-username='robot$harness-demo' \  --docker-password='替换成 Harbor 机器人账号 Token' \  --docker-email=devops@company.com \  -n dev

建议生产环境使用 Harbor 机器人账号，不要使用个人账号。

十三、创建 GitLab Connector

在 Harness 控制台中进入：

Project → Project Settings → Connectors → New Connector → Code Repositories → GitLab

填写建议：

• Name

  : gitlab-company

• Identifier

  : gitlab_company

• URL Type

  : Repository

• Connection Type

  : HTTPS

• Repository URL

  : https://gitlab.company.com/devops/harness-demo-app.git

• Authentication

  : Token

• Username

  : harness-bot

• Token

  : 使用 Harness Secret

• Execute on Delegate

  : ✅ true

• Delegate Selector

  : cn-k8s-dev

注意：国内内网 GitLab 必须让 Delegate 访问，不要让 Harness SaaS 直接访问内网 GitLab。

GitLab Token 推荐权限：

• read_repository
• read_api

后续如果要自动打 Tag、写提交状态，再增加：

• write_repository
• api

十四、创建 Harbor Connector

进入：

Project → Project Settings → Connectors → New Connector → Artifact Repositories → Docker Registry

填写建议：

• Name

  : harbor-company

• Identifier

  : harbor_company

• Docker Registry URL

  : https://harbor.company.com

• Provider Type

  : Other

• Authentication

  : Username and Password

• Username

  : robot$harness-demo

• Password

  : 使用 Harness Secret

• Execute on Delegate

  : ✅ true

• Delegate Selector

  : cn-k8s-dev

对应 YAML 参考：

yaml

复制

connector:name:harbor-companyidentifier:harbor_companydescription:国内企业Harbor镜像仓库orgIdentifier:devops_labprojectIdentifier:harness_demotype:DockerRegistryspec:dockerRegistryUrl:https://harbor.company.comproviderType:Otherauth:type:UsernamePasswordspec:username:robot$harness-demopasswordRef:harbor_robot_tokenexecuteOnDelegate:truedelegateSelectors:-cn-k8s-dev

十五、创建 Kubernetes Cluster Connector

进入：

Project → Project Settings → Connectors → New Connector → Cloud Providers → Kubernetes Cluster

推荐选择：

Use the credentials of a specific Harness Delegate

也就是让 Delegate 使用它所在集群的 ServiceAccount 权限访问 Kubernetes。

填写建议：

• Name

  : k8s-dev-cluster

• Identifier

  : k8s_dev_cluster

• Delegate Selector

  : cn-k8s-dev

• Namespace

  : dev

生产建议：

• dev/test 使用一个 Delegate

• pre/prod 使用独立 Delegate

• 不同环境使用不同 Delegate Selector

• 不同环境使用不同 Kubernetes RBAC 权限

十六、创建第一个空 Pipeline

进入：

Project → Pipelines → New Pipeline

填写：

• Name

  : first-empty-pipeline-cn

• Identifier

  : first_empty_pipeline_cn

• Description

  : 国内网络环境下第一个 Harness Pipeline

十七、使用 Visual Editor 创建第一个 Custom Stage

1. 添加 Stage

在 Pipeline Studio 中点击：

Add Stage → Custom Stage

填写：

• Stage Name

  : Init

• Stage Identifier

  : init

2. 添加 Shell Script Step

在 Init Stage 中点击：

Add Step → Shell Script

填写：

• Name

  : Check Domestic Network

• Identifier

  : check_domestic_network

• Shell

  : Bash

脚本内容：

bash

复制

echo"==== Harness 国内网络环境检查 ===="echo"Pipeline: <+pipeline.name>"echo"Stage: <+stage.name>"echo"Execution ID: <+pipeline.executionId>"echo"==== 检查 GitLab ===="curl -k -I --connect-timeout 10 https://gitlab.company.com || trueecho"==== 检查 Harbor ===="curl -k -I --connect-timeout 10 https://harbor.company.com/v2/ || trueecho"==== 检查 npm mirror ===="curl -I --connect-timeout 10 https://registry.npmmirror.com || trueecho"==== 检查 Kubernetes ===="kubectl get ns || true

这个 Stage 的目的不是部署，而是先确认：

• Pipeline 能运行

• Delegate 能执行脚本

• Delegate 能访问 GitLab

• Delegate 能访问 Harbor

• Delegate 能访问 npm 国内镜像

• Delegate 能访问 Kubernetes

• 日志可以回传到 Harness

3. 运行 Pipeline

点击 Save → Run → Run Pipeline。

预期日志：

code

复制

Harness 国内网络环境检查Pipeline: first-empty-pipeline-cnStage: InitExecution ID: xxxx检查 GitLab检查 Harbor检查 npm mirror检查 Kubernetes

十八、切换到 YAML 查看 Pipeline 配置

在 Pipeline Studio 中可以切换到 YAML 编辑器。官方文档说明，在 Pipeline Studio 中选择 YAML 即可切换到 YAML editor，并且可以使用自动补全。

参考 YAML：

yaml

复制

pipeline:name:first-empty-pipeline-cnidentifier:first_empty_pipeline_cnprojectIdentifier:harness_demoorgIdentifier:devops_labtags:network:chinatutorial:harness-01stages:-stage:name:Initidentifier:inittype:Customspec:execution:steps:-step:name:CheckDomesticNetworkidentifier:check_domestic_networktype:ShellScripttimeout:10mspec:shell:Bashsource:type:Inlinespec:script:|                          echo "==== Harness 国内网络环境检查 ===="                          echo "Pipeline: <+pipeline.name>"                          echo "Stage: <+stage.name>"                          echo "Execution ID: <+pipeline.executionId>"echo"==== 检查 GitLab ===="curl-k-I--connect-timeout10https://gitlab.company.com||trueecho"==== 检查 Harbor ===="curl-k-I--connect-timeout10https://harbor.company.com/v2/||trueecho"==== 检查 npm mirror ===="curl-I--connect-timeout10https://registry.npmmirror.com||trueecho"==== 检查 Kubernetes ===="kubectlgetns||true

十九、使用 Visual Editor 创建简单部署阶段

现在创建一个最小 Deployment Stage。

1. 添加 Deploy Stage

点击：

Add Stage → Deploy

填写：

• Stage Name

  : Deploy Dev

• Stage Identifier

  : deploy_dev

• Deployment Type

  : Kubernetes

2. 配置 Service

Service 表示要部署的应用。

填写：

• Service Name

  : harness-demo-app

• Service Identifier

  : harness_demo_app

• Service Definition

  : Kubernetes

Manifest 选择：

• Manifest Source

  : Git Repository

• Git Connector

  : gitlab_company

• Repository

  : devops/harness-demo-app

• Branch

  : main

• Manifest Path

  : k8s

这里使用 GitLab Connector 读取 k8s/ 目录下的 Kubernetes YAML。

3. 配置 Environment

Environment 表示环境，例如 dev、test、pre、prod。

创建：

• Environment Name

  : dev

• Environment Identifier

  : dev

• Environment Type

  : Pre-Production

4. 配置 Infrastructure

Infrastructure 表示部署到哪里。

填写：

• Infrastructure Name

  : dev-k8s

• Infrastructure Identifier

  : dev_k8s

• Cluster Connector

  : k8s_dev_cluster

• Namespace

  : dev

• Release Name

  : harness-demo-app

5. 执行部署

点击 Save → Run → Run Pipeline。

部署完成后，在本地或运维机上验证：

bash

复制

kubectl get pods -n devkubectl get deploy -n devkubectl get svc -n dev

端口转发验证：

bash

复制

kubectl port-forward svc/harness-demo-app 8080:80 -n dev

访问 http://localhost:8080，预期返回：

json

复制

{"app":"harness-demo-app","env":"dev","version":"v1","message":"Hello Harness China Network"}

二十、国内环境常见问题排查

问题 1：Delegate 一直 Not Connected

排查命令：

bash

复制

kubectl get pods -n harness-delegate-ngkubectl describe pod -n harness-delegate-ngkubectl logs -f deployment/firstk8sdel -n harness-delegate-ng

重点检查：

• Harness Account ID 是否正确

• Delegate Token 是否正确

• managerEndpoint 是否正确

• Delegate 镜像是否能拉取

• 是否需要 HTTP_PROXY / HTTPS_PROXY

• 企业防火墙是否允许出站 443

• 是否阻断 WSS

问题 2：GitLab Connector 测试失败

常见原因：

• Harness SaaS 无法访问企业内网 GitLab

• Connector 没有选择 Execute on Delegate

• Delegate 所在网络无法访问 GitLab

• GitLab Token 权限不足

• GitLab 使用自签证书

处理建议：

• Connector 必须选择 Execute on Delegate

• Delegate Selector 选择 cn-k8s-dev

• 先在 Delegate Pod 内 curl GitLab 地址

• 确认 Token 有 read_repository 权限

问题 3：Harbor Connector 失败

排查：

bash

复制

kubectl exec -it deploy/firstk8sdel -n harness-delegate-ng -- shcurl -k -I https://harbor.company.com/v2/

常见原因：

• Harbor 地址写错

• Harbor 使用自签证书

• 机器人账号 Token 错误

• Delegate 无法访问 Harbor

• Secret Identifier 写错

问题 4：Kubernetes 拉不到镜像

排查：

bash

复制

kubectl describe pod -n devkubectl get secret harbor-pull-secret -n dev

常见原因：

• image 地址还是 docker.io

• 没有配置 imagePullSecrets

• Harbor 账号没有 pull 权限

• containerd 没信任 Harbor 证书

• Harbor 项目名写错

问题 5：npm install 很慢

检查 .npmrc：

bash

复制

cat .npmrc

应包含：

ini

复制

registry=https://registry.npmmirror.com

Dockerfile 中也要复制 .npmrc：

dockerfile

复制

COPY .npmrc ./

二十一、企业落地建议

第 1 篇只是入门，但从一开始就建议按企业规范来做。

1. 命名规范

• Org: devops-lab

• Project: harness-demo

• Pipeline: demo-api-dev-deploy

• Connector: gitlab-company / harbor-company / k8s-dev-cluster

• Secret: harbor-robot-token

• Delegate: cn-k8s-dev

2. Delegate 标签规范

建议给 Delegate 添加标签：cn、k8s、dev、gitlab、harbor。

后续 Connector 和 Pipeline Step 通过 Selector 使用指定 Delegate。

官方文档说明，可以给 Delegate 添加 tag，并在命令和连接器中引用这些 tag，以确保使用指定 Delegate。

3. 多环境规划

从第一天就按多环境设计：

• dev

  ：开发环境

• test

  ：测试环境

• pre

  ：准生产环境

• prod

  ：生产环境

建议：

• dev/test 使用普通 Delegate

• pre/prod 使用独立 Delegate

• prod Connector 独立创建

• prod Secret 独立管理

• prod Pipeline 增加人工审批

4. 安全规范

• 不要把密码写进 YAML

• 不要把 Token 提交到 Git

• Harbor 使用机器人账号

• GitLab 使用 Project Access Token

• 生产环境最小权限

• 不同环境使用不同 Secret

二十二、本篇验收标准

完成本篇后，应该达到下面结果：

• ✅ 已理解 Harness SaaS + Delegate 架构

• ✅ 已创建 Harness Org / Project

• ✅ 已准备 GitLab / Harbor / Kubernetes

• ✅ 已配置 npm 国内镜像

• ✅ 已同步 Node 基础镜像到 Harbor

• ✅ 已同步 Delegate 镜像到 Harbor

• ✅ 已安装 Harness Delegate

• ✅ Delegate 状态为 Connected / Available

• ✅ 已创建 GitLab Connector

• ✅ 已创建 Harbor Connector

• ✅ 已创建 Kubernetes Cluster Connector

• ✅ 已创建第一个空 Pipeline

• ✅ Custom Stage 可以执行国内网络检查

• ✅ 可以使用 Visual Editor 创建简单部署阶段

• ✅ 应用可以部署到 dev namespace

二十三、本篇总结

本文完成了 Harness 国内网络环境下的第一步落地。

你需要重点记住：

• Harness SaaS 负责管理和编排

• Delegate 负责在企业内网执行任务

• 国内环境不要默认依赖 GitHub / DockerHub / npm 官方源

• Git 仓库建议使用 GitLab / Gitee

• 镜像仓库建议使用 Harbor / 国内云镜像仓库

• npm 构建建议使用 npmmirror

• 内网资源访问必须通过 Delegate

• Secret 不要明文写入 YAML

• Pipeline 可以先用 Visual Editor 入门，再逐步切换 YAML 工程化