企业官网建设流程全解析

最近帮团队搭了一套基于GitPuk和Arbess的自动化部署流水线，从最初的手动上线搞得焦头烂额，到现在代码合并后十几分钟全自动走完构建、测试和部署。这两天刚好有同事问起这套东西怎么从零开始搭，干脆把整个过程中的设计思路、核心配置、踩过的坑整理成一篇入门指南，方便后面新同学照着上手，也给自己留个备忘。

先说清楚这套组合是干什么的：GitPuk负责托管代码和管理CI任务，Arbess负责接替传统部署脚本完成镜像拉取、环境编排和滚动更新。说白了就是代码推上去之后，剩下的构建产物、环境一致性、服务发布全部自动处理，你在后台盯着日志看进度就行。这套方案比较适合中小团队，不想自己折腾一套复杂的发布平台，又希望流程规范、可追溯的场景。

全篇会按照“架构思路 -> 环境准备 -> 流水线实现 -> 问题排查”的顺序来写，每一块都会带上我实际用到的配置片段和执行命令，尽量做到拿过去就能用。

1. 整体架构与方案选型

1.1 为什么选GitPuk + Arbess而不是其他方案

团队之前的上线方式是典型的“人肉运维”：开发本地打包，传到服务器，手动停服务、替换文件、再启动。听起来简单，实际跑起来全是坑——环境不一致、漏了配置文件、回滚要翻聊天记录找上一个包在哪。更难受的是，每次发版都占用一个人半小时到一小时，遇上紧急修复一天能打断好几次。

在选择自动化方案时，我们重点对比了几个方向：

• 传统CI工具 + 远程执行脚本：配置简单，但发布逻辑散落在脚本里，回滚还是要手动介入。
• 容器化 + 编排平台：能力强，但对小团队来说学习成本和维护成本偏高。
• CI工具 + GitOps工具：CI负责构建镜像和更新配置，部署交给专门的GitOps组件，流程清晰，回滚自然。

最终敲定GitPuk加Arbess的原因也简单：GitPuk本身自带CI能力，不需要额外搭一套Jenkins之类的服务；Arbess以应用为中心，配置都在Git仓库里，天然具备版本管理和审计能力。整体只有两个核心组件，维护成本可控，部署逻辑全声明式，对团队的认知负担比较友好。

1.2 部署链路的核心设计

这套流水线跑起来之后，完整的链路是这样走的：

开发者推送代码 -> GitPuk触发流水线 -> 单元测试与构建 -> 推送镜像到制品库 -> 更新部署配置 -> Arbess同步新配置 -> 滚动更新线上服务

设计这张链路时有三个关键决策：

第一，构建和部署分离。GitPuk只管产出可信的镜像和配置文件，线上环境长什么样由Arbess决定。这样开发和运维的职责边界非常清晰，谁出了问题都不会互相污染。

第二，环境差异用配置目录隔离。我们在仓库里为测试环境和生产环境各建了一个目录，里面是各自环境的部署清单。流水线构建好镜像后，只需要用脚本更新对应目录里的镜像标签，剩下的交给Arbess自动识别差异并执行更新。

第三，一切变更留痕。无论是代码变更、镜像更新还是部署描述文件变更，全部通过Git提交完成。出问题的时候直接查提交历史，谁改的、改了什么、为什么改一目了然，不再需要“你记不记得刚才改了哪个配置”这种对话。

这套设计我们跑了两个多月，最大的感受是安心。以前发版前要反复确认服务器状态，现在只需要看流水线有没有全绿，以及Arbess那边是不是已经把新版本Pod拉起来了。

2. 环境准备与Runner接入配置

2.1 代码仓库与组织骨架初始化

第一步是把代码仓库的结构整理好。GitPuk支持标准Git工作流，直接创建项目仓库就行。但建议从一开始就按“代码、配置、基础设施描述”三层分开管理，避免后期配置和代码挤在一起出问题。

我们仓库最终长这样：

my-project/ ├── src/ # 项目源码 ├── deploy/ │ ├── base/ # 公共配置模板 │ ├── test/ # 测试环境覆盖配置 │ └── prod/ # 生产环境覆盖配置 └── .gitpuk-ci.yaml # CI流水线定义

源码和部署配置放同一个仓库，好处是版本天然同步——某次代码提交对应的部署方式就在同一个commit里，回溯问题的时候方便得多。后面如果团队长大、权限需要拆分，再考虑拆独立仓库也不迟。

2.2 流水线执行器的接入

GitPuk的CI任务跑在独立的执行器上。执行器可以理解成一个跑流水线任务的打工机器人，它从GitPuk领取任务、执行脚本、把结果上报回去。

我这边直接在服务器上用一条命令注册了一个执行器：

gitpuk-runner register --url http://git.example.com --token xxxx --name build-runner --executor docker --tag-list build,test

几个参数的说明：

• --url：GitPuk服务地址。
• --token：在GitPuk项目的设置里生成，用于执行器注册。
• --executor docker：让每个CI任务跑在干净的Docker容器里，避免服务器上依赖互相污染。
• --tag-list：给执行器打标签，后面写流水线时可以指定任务跑在哪类执行器上。

注册好了之后，去GitPuk的项目设置里能看到这个执行器在线。我在Executor数量上给了两个节点，一个打上build标签用来跑构建和测试，另一个打上deploy标签专门处理部署任务。隔离的好处是，就算构建任务把资源吃满了，部署操作也不至于被卡住。

2.3 Arbess安装与应用配置

Arbess安装方式比较多，考虑到团队用容器比较顺，我们在服务器上直接以容器方式运行。兼容Kubernetes环境时，官方推荐用Operator方式安装，创建几个自定义资源就能完成部署。

安装完成后，第一件事是把代码仓库里的部署配置目录和Arbess关联起来。需要在Arbess中创建一个应用，指定仓库地址、目标集群和目标目录。第一次接入时建议先用测试环境目录做验证，跑通之后再接入生产目录。

这里有一个重要的安全设置：Arbess默认以轮询方式从仓库拉取新配置，所以需要给它配置访问仓库的凭证。我们在GitPuk里生成了一对只读访问令牌，只授权拉取代码和读取配置，不给任何写权限，这样即使令牌泄露，最坏情况也只是被看到代码，不会被篡改。

配置完成后，Arbess会自动读取仓库里已有的部署描述，并显示当前环境实际状态。确认状态一致后，基础接入就算完成了。

3. 流水线实现与核心阶段参数解析

3.1 触发策略与任务编排

流水线用GitPuk的自定义YAML格式来描述，根文件叫.gitpuk-ci.yaml，放在仓库根目录。我们为不同分支配置了不同的策略：

• 推送到main分支：触发完整流水线（测试、构建镜像、更新配置、触发部署）。
• 推送到dev/*分支：只执行单元测试和镜像构建，不触发部署，方便开发阶段快速反馈。
• 打tag：触发生产环境部署，并且要求人工确认后才真正执行发布动作。

写出来的配置核心结构如下：

stages: - test - build - deploy test-job: stage: test tags: - build script: - npm run test build-image: stage: build tags: - build script: - docker build -t registry.internal/my-app:${CI_COMMIT_SHA} . - docker push registry.internal/my-app:${CI_COMMIT_SHA} update-config: stage: deploy tags: - deploy script: - sed -i "s|image: my-app:.*|image: registry.internal/my-app:${CI_COMMIT_SHA}|" deploy/test/deployment.yaml - git commit -am "Update image tag to ${CI_COMMIT_SHA}" - git push origin main only: - main

重点说明一下update-config这一步做了什么：它不是直接去操作服务器，而是把部署文件里的镜像标签替换成这次构建出来的版本，然后提交回仓库。Arbess检测到仓库有变化后，自动将配置同步到集群并滚动更新服务。这是GitOps的核心思路——仓库是唯一事实来源，所有变更先入库，再被自动化工具应用。

3.2 构建参数与镜像版本策略

镜像标签策略直接决定了后续排查问题的速度。很多团队习惯用latest当标签，看起来方便，实际上出问题之后根本不知道线上跑的是哪次提交构建出来的。我们从第一天起就强制要求：镜像标签必须与代码提交哈希一一对应。

用${CI_COMMIT_SHA}作为标签，包含完整提交哈希和短哈希两种格式。完整哈希用于精确定位，短哈希用于Arbess界面上快速查看，建议统一用完整哈希，稍显长但查询时不会产生歧义。流水线里引入Commit哈希之后，任何一个运行中的容器都可以反向追溯到触发它的那次代码提交。

镜像构建的几个参数也值得讲一下：

• --pull参数：强制每次构建前拉取基础镜像的最新版本，避免本地缓存导致镜像带着过期补丁。
• 多阶段构建：我们的后端服务采用多阶段构建，第一阶段装编译工具链并完成编译，第二阶段只拷贝编译产物到轻量运行镜像，这样最终镜像体积能减少百分之六十以上。
• 构建缓存：合理利用GitPuk执行器挂载的Docker缓存目录，避免每次全量下载依赖，能节省大量时间。

3.3 环境差异化配置处理

测试环境和生产环境不可能完全一样，比如数据库地址、日志级别、资源配置。我们的方案是Arbess的原生能力支持应用同一套基础配置，再按环境覆盖差异化部分。

实现上，仓库里的deploy/目录利用一个叫做Patch定义的机制：base/放公共部分，test/和prod/分别放各自环境的增量修改。举个例子，测试环境只需要一个副本，生产环境至少三个副本并且要求滚动更新策略：

# deploy/base/deployment.yaml apiVersion: apps/v1 kind: Deployment metadata: name: my-app spec: replicas: 1 template: spec: containers: - name: app image: registry.internal/my-app:latest

# deploy/prod/patch-replica.yaml spec: replicas: 3 strategy: type: RollingUpdate rollingUpdate: maxUnavailable: 0 maxSurge: 1

Arbess会把base配置和对应环境的patch合并成最终部署内容。这样的好处是：公共部分的修改只需要动base/目录，所有环境自动生效；环境专属策略独立维护，互不干扰。

3.4 部署阶段的权限设计与确认机制

部署阶段是整个流水线里权限最敏感的一环。我们的做法是：让流水线执行器拥有Git推送到配置仓库的权限，但不让它直接操作线上环境；真正的环境变更由Arbess完成。换句话说，CI阶段的权限边界最多到提交配置，Arbess才是唯一有权限改环境的组件。

生产环境的发布流程我们在流水线里加了一道人工确认关卡：

prod-deploy: stage: deploy when: manual script: - ./scripts/update-prod-image.sh

加了when: manual之后，流水线执行到生产部署前会停住，需要具备相应权限的人在GitPuk后台点一下“允许”按钮，才会继续往下走。测试环境全自动，生产环境半自动，这个折中方案兼顾了效率与安全。

实际操作中发现，人工确认还有一个隐藏好处：节点稳定。上线这件事从“顺手推一下”变成了一个有仪式感的明确动作，操作人心里会过一遍影响面，错误率明显下降。

4. 常用命令与本地验证手段

4.1 本地模拟流水线执行

很多问题在写配置阶段就能暴露，不用等推到远程才触发CI。GitPuk官方提供了一个本地执行工具，能直接读取项目里的流水线定义并在本地运行，这个工具我强烈建议配置阶段就用上：

gitpuk-ci-local exec --job test-job

本地跑的时候有几个注意点：

• 确保本地Docker可用，因为默认执行器就是Docker模式。
• 第一次跑会拉取基础镜像，耐心等一会儿，后续就会走缓存。
• 本地环境变量跟远程不完全一样，某些依赖远程预置变量的脚本需要在本地额外指定。

我习惯每次改完流水线文件先本地跑一遍测试阶段的命令，确认语法人机校验都通过再推送到远程。这套流程帮我们至少省了四五次“推到远程才发现YAML对齐错了”的尴尬局面。

4.2 Arbess命令行查看同步状态

Arbess安装完成后自带一套命令行工具，日常排查问题离不开它。最常用的查看命令：

arbess app list arbess app get my-app

app get返回的信息比较全，包括当前应用的同步状态、上次同步时间、目标版本和当前运行版本。如果出现OutOfSync状态，说明实际部署和仓库配置不一致，这个时候看看差异内容再决定是重新同步还是回滚配置。工具还支持直接查看差异汇总，不用打开界面一步步点：

arbess app diff my-app

这条命令比对的是仓库配置与实际部署的差异，输出中会标注哪些字段不一致。定位问题速度比看界面快得多，我几乎每天都会用几次。

4.3 回滚操作的两种路径

线上出问题后，回滚是必须支持的能力。因为一切配置都在Git仓库，回滚本质上就是“把配置改回去”。

我实际会用到两种路径：

第一种，单文件回滚。线上环境出问题，但代码本身没问题，只是配置改坏了。直接用Git回退到上一个提交，或者手动修改配置修复问题，推送到仓库后Arbess会自动同步：

git revert HEAD --no-edit git push origin main

第二种，整体镜像回滚。代码本身有严重Bug，需要把镜像标签指向上一个稳定版本。这种情况下直接改部署文件里的镜像版本：

git checkout HEAD~1 -- deploy/prod/deployment.yaml git commit -am "Rollback to previous stable version" git push origin main

Arbess检测到镜像标签变化后，会根据Deployment的滚动更新策略逐个替换实例。由于我们在生产配置里设置了maxUnavailable: 0，旧版本会保持运行直到新版本实例通过健康检查，所以回滚过程中服务不会中断。这个策略配置很值，建议所有生产服务都带上。

5. 实操问题排查与避坑清单

5.1 执行器异常与任务卡死

第一个最容易踩的坑是执行器掉线。GitPuk显示任务一直在排队，检查发现是执行器所在服务器磁盘满了。执行器跑构建任务会频繁拉镜像、写缓存，磁盘说满就满。

处理建议：执行器节点单独挂一块大容量数据盘，镜像和构建缓存目录指向这块盘。同时加一个定时清理任务，只保留最近几天的镜像缓存：

docker image prune -a --filter "until=168h" -f

每周清理一次，执行器基本稳定。

5.2 镜像推送认证失效

第二个高频问题是构建阶段报镜像推送权限错误。原因是执行器节点上的Docker登录凭证过期。由于执行器使用Docker容器运行任务，推送镜像时依赖节点上配置的认证信息。定期手动执行一下登录命令刷新凭证：

docker login registry.internal --username xxx --password xxx

一个更省事的办法是：在流水线脚本里通过环境变量执行动态登录，这样凭证可以放在GitPuk的CI变量配置里统一管理，刷新或轮换都不需要登录服务器手动操作。我们后来改成这种方式，推送认证问题基本绝迹。

5.3 Arbess同步状态长时间卡在Progressing

Arbess显示Progressing状态长时间不变，先别急着怀疑Arbess出了问题。多数情况是新的Deployment实例没有通过健康检查。Arbess的同步状态和实际Pod状态有延迟，需要进一步排查：

kubectl get pods -n my-namespace kubectl logs -f <pod-name>

多半是启动参数传错了、数据库连不上或者资源配额不够。我遇到最多的是测试环境资源限制太小，新版本镜像启动时内存超限被反复杀掉，Arbess持续重试，看起来就像卡死一样。查看一下事件日志：

kubectl describe pod <pod-name>

里面会直接写明是资源限制还是镜像拉取失败，定位速度非常快。

5.4 流水线长尾阶段占用资源拖慢整体构建

团队提交频繁之后，构建任务越来越多，执行器资源被单个大任务占满导致其他任务排队。我们在流水线配置里为不同任务设置了资源限制，并且拆分构建和测试用的执行器。线上全量测试和快速单测分配不同标签，优先保证核心任务能及时跑起来。这个优化做完之后，开发分支的流水线反馈时间从半小时降到了十分钟以内。

5.5 常见问题速查

6. 进阶技巧与长期维护建议

6.1 配置漂移检测

Arbess有一个比较实用的功能：定期对比仓库配置和实际环境状态，发现漂移自动修正。换句话说，有人跑到服务器上手动改了Pod副本数等配置，过不了多久就会被Arbess“纠正”回来。这让环境状态非常稳定，人为误操作影响面明显缩小。

我建议把这个功能开着，同时保留审计日志。既保证状态收敛，又能留下操作记录方便追溯。一开始团队有人不适应“不能直接在服务器上改配置”，习惯了之后反而觉得安全，毕竟多了一层保护。

6.2 流水线配置复用

多个项目之间有很多流水线逻辑是重复的，比如测试、构建镜像、更新配置。GitPuk支持定义复用模板，把公共逻辑抽出来后，项目里的流水线文件可以精简很多。我们内部把测试和构建流程做成了模板，新项目接入只需要写两三行核心差异，维护成本大幅降低。

模板还有一个好处：统一的规范不会因为不同人写的流水线各搞一套而漂移。项目负责人不同，写法习惯自然不同，但模板兜底了主流程的一致性。

6.3 团队权限分级

权限划分建议按最小化原则：

• 普通开发者：能推送代码、查看流水线日志，不能触发生产部署确认、不能修改部署配置路径。
• 项目负责人：额外拥有生产环境部署确认权限。
• 平台管理员：管理Arbess配置、执行器注册、仓库权限等平台级操作。

生产环境的人工确认权限目前只放给项目负责人和平台管理员，其他人看到流水线停在确认节点会知道需要找谁推进，边界清晰不混乱。

6.4 长期维护动作清单

• 每周检查一次构建缓存清理情况。
• 每月轮换一次CI变量中的镜像仓库凭证。
• 每季度审计一次Arbess管理的应用和权限配置。
• 出新版本工具时，先在测试环境验证实验性配置，稳定后再推广到生产。

这套东西搭起来到稳定运行，最耗时间的其实不是怎么安装配置，而是怎么让整个团队接受“以后不要直接登服务器改东西”这件事。工具层面的流程逻辑理顺之后，剩下的主要是配合节奏的调整。

最后再分享一个细节：Arbess管理界面默认只显示最近几次同步的操作记录，时间久了你可能想查更早的发布历史。在仓库侧我们可以通过git log deploy/prod/deployment.yaml快速还原每一次线上发布对应的镜像版本和配置变更。这个习惯建议从第一天就坚持——所有变更走Git，历史就是完整的时间线，随时能翻。