企业官网建设流程全解析

• 测试
• 云原生
• 质量保障

本篇技术文章基于examples/quickstarts/README.md展开，系统讲解 OpenShift Origin 中 QuickStart 模板的定位、12 个预置应用骨架的组成结构（Service、Route、BuildConfig、DeploymentConfig 等对象）、完整参数体系，以及这些模板如何通过hack/update-external-examples.sh自动从上游仓库拉取同步、并被扩展测试套件用于集群加载器压测。读完后，你将能够读懂并复用 QuickStart 模板、理解其参数化机制，并掌握维护该目录的正确方式。

一、QuickStart 是什么：应用的基本骨架

根据 README 的定义，QuickStarts 提供的是一个应用的基本骨架（basic skeleton）。具体来说：

• 每个 QuickStart 模板引用一个包含非常简单的源代码的外部仓库，这些代码用某个特定框架实现了一个"平凡"（trivial）应用；
• 模板同时定义了应用运行所需的全部配套组件，包括Build 配置（BuildConfig）以及支撑性服务（如数据库）等；
• 目录内现有 12 个模板文件，覆盖 PHP（CakePHP）、Perl（Dancer）、Python（Django）、Ruby（Rails）、Node.js、Apache HTTPD、Nginx 七类框架/服务。

1.1 两种使用方式

README 明确指出 QuickStart 模板有两条使用路径：

1. 原样实例化（instantiate as is）：直接以模板默认的源仓库 URL 实例化，得到一个可运行的参考应用；
2. Fork 源仓库：fork 模板所引用的源码仓库，将你的 fork 地址作为SOURCE_REPOSITORY_URL（即原文所称的 source-repository）传入后再实例化模板，从而在保留整套构建/部署骨架的前提下，替换为自己的业务代码。

这正是 OpenShift "源到镜像（Source-to-Image）"开发模式的典型入口：你只提供代码，构建策略、触发器、探针、路由全部由模板代劳。

1.2 12 个 QuickStart 模板全表

examples/quickstarts/目录下的实际模板文件与 README 清单一一对应：

需要注意的两点约束（README 原文强调）：

• persistent 变体要求集群中有可用的持久卷（persistent volumes），否则实例化后数据库容器无法正常挂载数据卷；
• 带数据库的应用中，ephemeral 变体的数据在 Pod 销毁后会丢失，模板元数据中也带有 "WARNING: Any data stored will be lost upon pod destruction. Only use this template for testing." 的告警。

二、模板结构解剖：以 httpd.json 为例

所有 QuickStart 都是kind: Template（apiVersion: template.openshift.io/v1）对象。以静态内容最简单的 httpd.json 为例，它由 5 个objects组成，构成完整的"构建—部署—暴露"链路：

2.1 BuildConfig：S2I 构建与触发器

BuildConfig 的核心配置（httpd.json）：

"strategy": { "sourceStrategy": { "from": { "kind": "ImageStreamTag", "name": "httpd:2.4-el8", "namespace": "${NAMESPACE}" } }, "type": "Source" }

• 采用Source 策略，从${NAMESPACE}（默认openshift）命名空间下的httpd:2.4-el8ImageStreamTag 拉取基础镜像，把 Git 源码注入其中完成构建；
• 构建产物写入${NAME}:latest这个 ImageStreamTag；
• 源码来自${SOURCE_REPOSITORY_URL}（默认指向上游示例仓库），可通过${SOURCE_REPOSITORY_REF}指定分支/标签、${CONTEXT_DIR}指定仓库内子目录；
• 配置了 4 种构建触发器：ImageChange（基础镜像变更时重新构建）、ConfigChange（配置变更时重新构建）、GitHub Webhook（带${GITHUB_WEBHOOK_SECRET}校验）、Generic Webhook（带${GENERIC_WEBHOOK_SECRET}校验）。

2.2 DeploymentConfig：自动滚动更新与健康探针

DeploymentConfig 通过imageChangeParams（automatic: true，监听${NAME}:latest）实现"构建出新镜像 → 自动触发滚动部署"的闭环。容器层面（httpd.json）：

• livenessProbe：httpGet检查/路径、8080 端口，initialDelaySeconds: 30，timeoutSeconds: 3；
• readinessProbe：同样的检查，initialDelaySeconds: 3，保证 Pod 就绪前不接收流量；
• 内存上限由参数${MEMORY_LIMIT}控制（默认 512Mi）。

2.3 通用参数体系

httpd 与 nginx 等模板的parameters部分定义了全部可覆写变量：

nginx.json 在此基础上多出一个版本参数NGINX_VERSION（默认1.20-el8），用于选择nginxImageStream 的标签；其 Route 还额外带template.openshift.io/expose-uri: http://{.spec.host}{.spec.path}注解，便于实例化后直接展示访问地址。

三、带数据库的模板：Django + PostgreSQL 深度剖析

django-postgresql.json（模板名django-psql-example，显示名 "Django + PostgreSQL (Ephemeral)"）代表了 QuickStart 中最完整的一类：应用 + 数据库 + 密钥管理。它比静态模板多出以下机制：

3.1 Secret 与敏感信息

模板首先创建一个Secret，其中包含三项内容：database-password、database-user以及 Django 特有的django-secret-key。DATABASE_PASSWORD按[a-zA-Z0-9]{16}表达式自动生成，DJANGO_SECRET_KEY按[\\w]{50}表达式自动生成。应用容器与 PostgreSQL 容器都通过secretKeyRef从该 Secret 读取凭证，实现应用侧与数据库侧凭证共享。

3.2 构建与部署差异

• 构建阶段：Source 策略基于python:${PYTHON_VERSION}镜像（默认3.9-ubi8），支持PIP_INDEX_URL参数指定自定义 PyPI 源；并配置了postCommit脚本./manage.py test，构建完成后自动运行 Django 测试套件；
• 部署策略：应用与数据库 DeploymentConfig 均为Recreate而非 Rolling（数据库是单副本有状态服务，不适合并行滚动）；
• 健康检查：应用改用 Django 提供的/health端点；PostgreSQL 容器则用 SCL 镜像内置的/usr/libexec/check-container命令做 exec 探针（liveness--live参数，initialDelaySeconds: 120）。

3.3 数据卷：Ephemeral 与 Persistent 的分水岭

两种变体的唯一结构性差异就在数据卷。ephemeral 版（django-postgresql.json）：

"volumes": [ { "emptyDir": {}, "name": "data" } ]

persistent 版（django-postgresql-persistent.json）：

"volumes": [ { "name": "${DATABASE_SERVICE_NAME}-data", "persistentVolumeClaim": { "claimName": "${DATABASE_SERVICE_NAME}" } } ]

这正是 README 中 "Note: requires available persistent volumes" 的技术含义——persistent 变体依赖一个名为${DATABASE_SERVICE_NAME}的 PVC 真实存在，而 ephemeral 版的数据随 Pod 生命周期消失，因此仅适用于测试用途。

3.4 数据库模板的完整参数

Django 模板在通用参数之外还定义了：PYTHON_VERSION（3.6-ubi8 / 3.8-ubi8 / 3.9-ubi8 / latest）、POSTGRESQL_VERSION（10-el8 / 12-el8 / latest，默认12-el8）、MEMORY_POSTGRESQL_LIMIT、DATABASE_SERVICE_NAME（默认postgresql）、DATABASE_ENGINE（默认postgresql）、DATABASE_NAME（默认default）、DATABASE_USER（默认django）、APP_CONFIG（可选的 Gunicorn 配置文件路径），且SOURCE_REPOSITORY_REF默认锁定到4.2.x分支。

四、目录的自动同步机制：不要手工修改文件

README 末尾有一段关键的运维约束：

This file is processed byhack/update-external-examples.sh. New examples must follow the exact syntax of the existing entries. Files in this directory are automatically pulled down, do not modify/add files to this directory.

即examples/quickstarts/下的 JSON 文件全部是从上游 openshift/library 仓库自动拉取的副本，目录内文件不可手工修改或新增；新增示例必须严格沿用既有的 Markdown 条目语法。

hack/update-external-examples.sh 中 quickstarts 部分的处理逻辑非常精确：

1. 进入examples/quickstarts目录，删除所有*.json / *.yaml / *.yml；
2. 用grep -E '\(https://raw.githubusercontent.com.*\)'从 README.md 中找出所有含 raw 文件地址的行，再用sed提取括号内的 URL；
3. 用curl批量下载这些模板 JSON；
4. 用rename -- '-example' ''去掉文件名中的-example后缀（上游 openshift/library 的文件名带-example后缀）；
5. 对命名不一致的模板做重命名映射：django-psql-persistent.json → django-postgresql-persistent.json、django-psql.json → django-postgresql.json、rails-pgsql-persistent.json → rails-postgresql-persistent.json（脚本注释说明：openshift/library 按模板的template.name字段命名文件，直接改名会破坏兼容性，故在本地统一命名）。

这解释了 README 条目语法为什么是强约束：每一条名称形式的 Markdown 链接就是同步脚本的数据源，格式稍有偏差（例如括号内 URL 位置不对）就会导致sed提取失败、文件缺失。同一脚本还以相同方式维护examples/image-streams、examples/db-templates与examples/jenkins目录。

五、QuickStart 模板在测试套件中的消费方式

这个 OpenShift 符合性/扩展测试仓库并非把 QuickStart 仅当作示例存放——它们被实际用于扩展测试的**集群加载器（cluster loader）**场景：

• test/extended/cluster/cm.go 中的newTemplate函数直接把模板路径拼为./examples/quickstarts/{template}.json，作为 ClusterLoader 配置中的模板对象写入集群加载配置（ClusterLoaderObjectType），用于在测试集群中批量实例化这些骨架应用、施加负载并观察集群状态；
• test/extended/cluster/cl.go 将cakephp-mysql、dancer-mysql、django-postgresql、nodejs-postgresql、rails-postgresql五个模板声明为测试 fixture（exutil.FixturePath("testdata", "cluster", "quickstarts", ...)）；
• 模板文件同时被 test/extended/testdata/bindata.go 以 bindata 形式内嵌到测试二进制中，保证测试运行时无需依赖工作区文件布局。

此外，仓库顶层的 examples/examples_test.go 提供了walkJSONFiles工具函数与TestExampleObjectSchemas，对examples/sample-app、examples/jenkins、examples/image-streams、examples/db-templates等目录中的 JSON/YAML 做 OpenShift API 类型（templatev1.Template等）解码校验，是 examples 目录下示例文件保持 API 兼容性的质量网。

六、实践要点总结

1. 复用骨架：要快速搭起一个 Django/CakePHP/NodeJS 应用骨架，直接实例化对应 quickstart 模板；要接入自己的代码，fork 上游示例仓库后覆写SOURCE_REPOSITORY_URL（可配合SOURCE_REPOSITORY_REF、CONTEXT_DIR）。
2. 选型纪律：临时验证用 ephemeral 变体（数据随 Pod 消失，模板元数据中带有明确的测试用途 WARNING）；需要数据存活必须用 persistent 变体，并确保集群有可用的 PVC/PV。
3. 参数覆写：实例化时按需覆写MEMORY_LIMIT、*_VERSION（如PYTHON_VERSION、POSTGRESQL_VERSION、NGINX_VERSION）、APPLICATION_DOMAIN等；webhook 密钥与数据库密码类参数由平台按generate表达式自动生成，无需手工填写。
4. 维护纪律：examples/quickstarts/下的 JSON 是上游自动同步产物——不要手工编辑；新增 QuickStart 的正规做法是在 examples/quickstarts/README.md 中按既有语法追加条目，再运行 hack/update-external-examples.sh 完成拉取与重命名。

• 测试
• 云原生
• 质量保障