企业官网建设流程全解析

Osclass 是一款基于 PHP 的开源免费分类信息（classifieds）建站脚本，可快速搭建二手交易、房产、招聘等分类广告站点。本文以stable/osclassHelm Chart 为核心，系统讲解如何在 Kubernetes 集群上通过 Helm 完成 Osclass 的部署、数据库接入、网络暴露、持久化与监控配置，并深入剖析 Chart 各模板的底层实现，帮助读者掌握一套可直接落地复制的部署方案。

一、Chart 概览：一个"应用 + 依赖数据库"的完整部署单元

本仓库中的 Osclass Chart 位于 stable/osclass，本质上是将 Bitnami 官方 Osclass 容器镜像 作为数据库依赖。从 Chart.yaml 可以看到该 Chart 的核心元数据：

• 版本7.0.10，应用版本appVersion: 3.7.4（对应 Osclass 3.7.4）
• deprecated: true：受 Helmstable仓库整体弃用时间线影响，该 Chart 已停止维护
• 关键字：osclass、classifieds、http、web、php

Chart 的目录结构反映了其完整的资源组织方式：

从依赖声明可以看出，数据库接入存在两条路径：默认由 Chart 内嵌的 MariaDB 提供，或通过mariadb.enabled=false+externalDatabase.*接入外部已有数据库，两条路径在模板中都有完整的实现支撑。

二、弃用说明与迁移指引

按照 Helm 官方stable仓库的弃用时间线，Bitnami 维护的 Osclass Chart 已迁移至bitnami/charts仓库。本仓库 Chart 的 Chart.yaml 与 NOTES.txt 均明确标注了该状态。迁移到 Bitnami 仓库的安装命令与原命令几乎一致，仅需将仓库名从stable换成bitnami：

$ helm repo add bitnami https://charts.bitnami.com/bitnami $ helm install my-release bitnami/<chart> # Helm 3 $ helm install --name my-release bitnami/<chart> # Helm 2

对已在stable仓库部署的存量实例，可通过如下命令完成 Chart 源切换升级：

$ helm repo add bitnami https://charts.bitnami.com/bitnami $ helm upgrade my-release bitnami/<chart>

提示：涉及 Chart 本身的 Issue 与 PR 均会导向bitnami/charts仓库；迁移相关问题可查阅原文档中指向的讨论 Issue（helm/charts#20969）获取统一答复。本篇文章仍以当前仓库中的stable/osclassChart 结构为事实依据展开。

三、前置条件

在开始部署前，需要确认集群环境满足以下要求：

• Kubernetes 1.12+（Chart 在apps/v1与extensions/v1beta1之间按集群版本自动选择 Deployment apiVersion，见下文"升级指南"）
• Helm 2.11+ 或 Helm 3.0-beta3+（模板注释中明确说明 Helm 2.11 才支持跨作用域变量赋值，见 _helpers.tpl 的兼容性说明）
• 底层基础设施提供 PV（Persistent Volume）供给能力，用于持久化 Osclass 数据与数据库数据
• 若需扩缩副本，需要 ReadWriteMany 类型的卷支持

四、安装与卸载

4.1 安装

使用默认配置安装，release 名称为my-release：

$ helm install my-release stable/osclass

该命令会以默认参数在集群中部署 Osclass 及其依赖的 MariaDB。默认配置对应的清单可查看 values.yaml。安装后可用helm list查看已安装的 release。

安装完成后，根据 NOTES.txt 的输出指引获取访问地址与凭据：

# 获取 Service 对外地址（LoadBalancer 类型） export APP_HOST=$(kubectl get svc --namespace NAMESPACE my-release-osclass \ --template "{{ range (index .status.loadBalancer.ingress 0) }}{{ . }}{{ end }}") # 获取随机生成的 Osclass 管理员密码 export APP_PASSWORD=$(kubectl get secret --namespace NAMESPACE my-release-osclass \ -o jsonpath="{.data.osclass-password}" | base64 --decode)

若使用ClusterIP类型 Service，则可通过端口转发访问：

kubectl port-forward --namespace NAMESPACE svc/my-release-osclass 8080:80 echo URL : http://127.0.0.1:8080/ echo Admin URL : http://127.0.0.1:8080/oc-admin/

其中/oc-admin/是 Osclass 管理后台路径，由 NOTES.txt 明确给出。

4.2 卸载

$ helm delete my-release

该命令会移除与该 release 关联的所有 Kubernetes 组件并删除 release 记录。需要注意，按 Kubernetes 的语义，由 Chart 创建的 PVC 不会随helm delete自动删除，如需彻底清理存储需另行处理。

五、参数总览（完整配置清单）

以下表格完整收录原文档的 Parameters 一节，并结合 values.yaml 与实际模板实现补充了默认值与取值说明。

5.1 全局与镜像参数

镜像地址的解析逻辑实现在 _helpers.tpl 的osclass.image模板函数中：当配置了global.imageRegistry时以全局仓库地址拼接，否则使用image.registry/repository:tag的常规拼接方式。

5.2 命名与访问地址

osclassHost是让 Osclass 正常运行的关键参数：从 deployment.yaml 可以看到，模板会将osclass.host拼入OSCLASS_HOST环境变量，若 Service 端口非 80 还会自动追加:port。而osclass.host的取值优先级定义在 _helpers.tpl：优先使用osclassHost，未设置时回退到 Service IP（serviceIP，ClusterIP 类型下固定为127.0.0.1）。因此若不显式提供osclassHost，站点 URL 将不完整，需要后续通过helm upgrade补齐。

osclassLoadBalancerIP用于为 LoadBalancer 类型 Service 指定保留 IP，该能力仅在部分云厂商（如 GKE）可用。以 GKE 为例，先保留公网 IP：

$ gcloud compute addresses create osclass-public-ip

安装时将该保留 IP 作为参数传入：

$ helm install my-release --set osclassLoadBalancerIP=IP_ADDRESS stable/osclass

5.3 应用账户与站点参数

这些参数在 deployment.yaml 中逐一映射为容器环境变量（OSCLASS_USERNAME、OSCLASS_PASSWORD、OSCLASS_EMAIL、OSCLASS_WEB_TITLE、OSCLASS_PING_ENGINES、OSCLASS_SAVE_STATS）。其中osclassPassword与smtpPassword不直接写入环境变量明文，而是通过 secrets.yaml 生成 Secret：未显式设置密码时，模板使用randAlphaNum 10生成 10 位随机密码并 base64 编码存入 Secret，再由 Deployment 通过secretKeyRef引用——这一实现细节保证了默认安装也具备基础安全强度。

5.4 SMTP 邮件参数

SMTP 参数在 deployment.yaml 映射为SMTP_HOST、SMTP_PORT、SMTP_USER、SMTP_PASSWORD、SMTP_PROTOCOL环境变量。所有 SMTP 参数默认均为空，即未配置邮件发送能力；密码部分同样走 Secret 注入。

5.5 Service 与资源参数

svc.yaml 展示了 Service 的完整实现：同时暴露 HTTP（默认 80）与 HTTPS（默认 443）两个端口，NodePort 类型下可通过nodePorts.http/https显式指定节点端口（需在 30000-32767 范围内），LoadBalancer 类型下支持loadBalancerIP与externalTrafficPolicy（默认Cluster，即不保留客户端源 IP，values.yaml 中有详细注释）。对于 minikube 等本地环境，建议将serviceType改为NodePort。

5.6 持久化参数

注：原文档参数表中的persistence.moodle.*为历史遗留拼写，实际生效路径为 values.yaml 中的persistence.osclass.*，本表以源码实际实现为准。

5.7 数据库参数（内置 MariaDB / 外部数据库）

5.8 Ingress 参数

ingress.yaml 中：启用certManager时会自动附加kubernetes.io/tls-acme: "true"注解；tls=true时按tlsHosts（或回退到 host 名）声明 hosts 并以tlsSecret指定证书 Secret；若希望自行在 Chart 外管理证书，可通过ingress.secrets[].{name,certificate,key}传入证书内容，密钥材料需要以-----BEGIN CERTIFICATE-----、-----BEGIN RSA PRIVATE KEY-----格式提供。

5.9 Pod 与监控参数

以上参数均映射为 bitnami/osclass 容器镜像支持的环境变量，各参数的取值语义、环境变量名与镜像文档一一对应。

六、安装配置实战：命令行与 values 文件两种方式

6.1 使用--set指定参数

所有参数均可通过helm install的--set key=value[,key=value]语法指定。例如设置 Osclass 管理员为admin、密码为password，并同时指定 MariaDB root 密码：

$ helm install my-release \ --set osclassUsername=admin,osclassPassword=password,mariadb.mariadbRootPassword=secretpassword \ stable/osclass

6.2 使用 values 文件

对于参数较多、需要版本化管理或团队复用的场景，推荐将配置写入 YAML 文件后以-f参数加载：

$ helm install my-release -f values.yaml stable/osclass

可直接以 values.yaml 为模板进行修改，该文件对每个参数都附有详尽注释与示例，例如取消注释global.imageRegistry即可让主应用与 MariaDB 依赖统一走私有镜像仓库。

6.3 常见生产配置示例

以下是一份综合了私有镜像、外部数据库、Ingress 与固定密码的完整 values 片段（仅供参考，请按实际环境调整）：

osclassHost: osclass.example.com osclassUsername: admin osclassPassword: changeme osclassEmail: admin@example.com osclassWebTitle: "My Classifieds Site" service: type: ClusterIP ingress: enabled: true certManager: true annotations: kubernetes.io/ingress.class: nginx hosts: - name: osclass.example.com path: / tls: true tlsHosts: - osclass.example.com tlsSecret: osclass-tls mariadb: enabled: false externalDatabase: host: my-db.example.com port: 3306 user: bn_osclass password: dbpassword database: bitnami_osclass persistence: enabled: true osclass: storageClass: "-" accessMode: ReadWriteOnce size: 8Gi

七、数据库架构：内嵌 MariaDB 与外部数据库双路径

Chart 的数据库逻辑在 deployment.yaml 中通过条件分支实现，两条路径注入的数据库环境变量一致（MARIADB_HOST、MARIADB_PORT_NUMBER、OSCLASS_DATABASE_NAME、OSCLASS_DATABASE_USER、OSCLASS_DATABASE_PASSWORD），差异在于取值来源：

路径一：内嵌 MariaDB（默认）

mariadb.enabled=true时，依赖的 MariaDB Chart 会一并部署，Osclass 的数据库连接参数取自mariadb.db.*，密码通过secretKeyRef从 MariaDB 生成的 Secret（key 为mariadb-password）动态注入。

路径二：外部数据库

mariadb.enabled=false时，连接参数改用externalDatabase.*，密码则从 externaldb-secrets.yaml 生成的<release>-externaldbSecret（key 为db-password）注入。该 Secret 仅在mariadb.enabled=false时渲染，避免与内嵌 MariaDB 路径冲突。

从部署逻辑看，两种路径共用同一套容器环境变量命名，因此在外部数据库与内置数据库之间切换时，应用侧配置无需改动，仅需调整 values 并重新升级 release。

八、健康检查与资源限制：源码级实现细节

deployment.yaml 为 Osclass 容器定义了完整的存活与就绪探针：

• livenessProbe：HTTP GET/index.php（携带Host头为osclass.host），initialDelaySeconds: 120、timeoutSeconds: 120、failureThreshold: 6。较长的延迟与超时设置符合 PHP 应用首次启动需要执行安装初始化、且偶发慢请求的实际情况。
• readinessProbe：同样探测/index.php，initialDelaySeconds: 30、periodSeconds: 5、timeoutSeconds: 120。

值得注意的细节：Deployment 模板为 Pod 注入了hostAliases，将status.localhost指向127.0.0.1（deployment.yaml），这是为 Metrics exporter 抓取 Apacheserver-status端点准备的内部主机名映射。

资源限制默认值为 Memory512Mi、CPU300m（requests），可通过resources参数整体覆盖。

九、持久化：数据如何跨 Pod 存活

Bitnami Osclass 镜像将站点数据与配置存储在容器内的/bitnami/osclass路径。Chart 通过 osclass-pvc.yaml 声明一个名为<fullname>-osclass的 PVC，并在 Deployment 中挂载到该路径（deployment.yaml）：

• persistence.enabled=true（默认）：挂载 PVC，数据跨 Pod 重建与 release 升级存活；
• persistence.enabled=false：改用emptyDir，Pod 重建即丢失数据，仅适合评估测试场景。

存储类解析逻辑在 _helpers.tpl 的osclass.storageClass函数中：global.storageClass优先；未设置时回退到persistence.osclass.storageClass；若设置为字符串"-"则渲染为空的storageClassName以禁用动态供给。PVC 的默认访问模式为ReadWriteOnce、容量8Gi。文档注明该持久化方案已在 GCE、AWS 与 minikube 上验证可用。

同样地，依赖的 MariaDB 数据卷默认也启用持久化（mariadb.persistence.enabled=true，ReadWriteOnce、8Gi）。

十、监控指标：Apache Exporter 边车

启用metrics.enabled=true后，Chart 会在同一 Pod 内追加一个 bitnami/apache-exporter 边车容器（deployment.yaml）：

command: [ '/bin/apache_exporter', '-scrape_uri', 'http://status.localhost:80/server-status/?auto']

exporter 通过上节提到的status.localhost主机别名抓取 Apache 的server-status指标，暴露在容器端口9117，并配有独立的存活/就绪探针。默认的 Pod 注解prometheus.io/scrape: "true"与prometheus.io/port: "9117"（见 values.yaml）使 Prometheus 可自动发现该指标端点。exporter 自身的资源限制通过metrics.resources配置。

十一、升级指南：两个重要的大版本变更

11.1 升级到 7.0.0：Deployment GVK 变更

在 helm/charts#17303 中，本 Chart 的 DeploymentapiVersion由extensions/v1beta1更新为apps/v1，以配合 Kubernetes API 的废弃节奏。Kubernetes 将对象按 group（apps）、version（v1）、kind（Deployment）即 GVK 进行识别，GVK 变更被视为兼容性破坏，因此无法原地升级旧对象。早期 Helm 3 版本曾存在查找逻辑缺陷（现已按规范修复），这正是该大版本号的意义所在。

当前模板对 apiVersion 的处理是自适应的——_helpers.tpl 中的osclass.deployment.apiVersion会依据集群版本（<1.14-0用extensions/v1beta1，否则用apps/v1）动态选择。

11.2 升级到 3.0.0：标签兼容性处理

从 3.0.0 之前的版本升级时，不修改 Deployment 标签则无法保证向后兼容。以下为官方提供的变通方案（假设 release 名为osclass）：

$ kubectl patch deployment osclass-osclass --type=json -p='[{"op": "remove", "path": "/spec/selector/matchLabels/chart"}]' $ kubectl delete statefulset osclass-mariadb --cascade=false

第一条命令移除旧 Deployment selector 中的chart标签（selector 在创建后不可变更，因此需先摘除该标签）；第二条命令以非级联方式删除旧的 MariaDB StatefulSet，为后续以新模板重新创建做准备。执行后即可按新版 Chart 重新部署，实现标签结构的平滑过渡。

十二、部署要点总结

• 必须设置osclassHost：推荐使用 FQDN（或公网 IP），否则 Osclass 应用生成的站点 URL 不完整，需要安装后通过helm upgrade --set osclassHost=...补齐（NOTES.txt 会在安装结束时给出明确的补齐命令）。
• 密码安全默认：osclassPassword、数据库密码、SMTP 密码均通过 Secret 注入，未指定时由模板随机生成（randAlphaNum 10），安装后从 Secret 中以 base64 解码获取。
• 生产环境使用不可变镜像标签：建议固定image.tag（如3.7.4-debian-10-r24），避免滚动标签（rolling tag）导致镜像在无感知的情况下被更新；NOTES.txt 也会对以-r<数字>结尾之外的 tag 发出滚动标签警告。
• 数据库路径二选一：默认内嵌 MariaDB 开箱即用；已有数据库时设置mariadb.enabled=false并填写externalDatabase.*即可，两种模式共用同一组环境变量注入机制。
• 网络暴露三选一：LoadBalancer（云环境默认）、NodePort（minikube/裸机）、Ingress（ingress.enabled=true，可与 cert-manager 集成自动签发 TLS 证书）。
• 持久化默认开启：Osclass 数据与 MariaDB 数据各占一个 8Gi PVC，关闭持久化（persistence.enabled=false）仅适合临时评估。

本文档对应的完整默认配置见 values.yaml，资源模板实现见 templates 目录，读者可对照源码逐项验证上文所述行为。