开源文档的构建、运营和贡献¶
本文介绍开源站点常用的构建方法，运营思路和吸引贡献者的经验。
DaoCloud 自主和捐献的开源站点¶
本节列出 DaoCloud 自主开源和捐献给社区的一些项目和站点。
自主产品¶
目前 DaoCloud 的主打产品为云原生操作系统 DCE 5.0 和算力运营管控平台 d.run。
| 网站 | 介绍 | 生成器 | 构建方式 | Repo 地址 |
|---|---|---|---|---|
| DCE 5.0 | 一款高性能、可扩展的云原生操作系统。其文档站的源代码完全开源 | mkdocs-material | cloudflare/wrangler-action@v3 | https://github.com/DaoCloud/DaoCloud-docs |
| d.run | AIGC 综合算力运维、大模型服务和运营平台。其文档站的源代码完全开源 | mkdocs-material | cloudflare/wrangler-action@v3 | https://github.com/d-run/drun-docs |
CNCF Sandbox¶
DaoCloud 捐献给 CNCF 并加入 Sandbox 的开源项目：
| 网站 | 介绍 | 生成器 | 构建方式 | Repo 地址 |
|---|---|---|---|---|
| Clusterpedia | 这个工具可以方便地检索容器化集群中的所有资源 | Hugo | gh-pages | https://github.com/clusterpedia-io/website |
| HAMi | 这是一个算力虚拟化的中间件，可以支持多种架构的 GPU | Docusaurus 3 | gh-pages | https://github.com/Project-HAMi/website |
| HwameiStor | 这是一个云原生化的本地存储方案 | Docusaurus | gh-pages | https://github.com/hwameistor/hwameistor |
| Kubean | 这是基于 Kubespray 构建的 Kubernetes 平台安装工具 | MkDocs | gh-pages | https://github.com/kubean-io/kubean |
| Merbridge | 使用 eBPF 加速网格的工具 | Hugo | gh-pages | https://github.com/merbridge/merbridge |
| Piraeus | 一个云原生数据仓库 | mkdocs-material | gh-pages | https://github.com/piraeusdatastore/piraeus |
| Spiderpool | 基于 Kubernetes 构建的 Underlay 和 RDMA 网络方案 | mkdocs-material | gh-pages | https://github.com/spidernet-io/spiderpool |
更多开源站点¶
经 DaoCloud 开源，仍在发展中的站点：
| 网站 | 介绍 | 生成器 | 构建方式 | Repo 地址 |
|---|---|---|---|---|
| CloudTTY | 这是一个网页版的命令行工具 | 未指定 | gh-pages | https://github.com/cloudtty/cloudtty |
| EgressGateway | 提供固定的 Egress IP 地址方案 | mkdocs-material | gh-pages | https://github.com/spidernet-io/egressgateway |
| kdoctor | 这是一个 Kubernetes 数据面的测试组件，主动探测集群的功能和性能 | mkdocs-material | gh-pages | https://github.com/kdoctor-io/kdoctor |
| KLTS | 对社区当前 4 个版本之外的 Kubernetes 提供长期维护支持 | Hugo | gh-pages | https://github.com/klts-io |
社区热门开源站点¶
| 网站 | 介绍 | 生成器 | 构建方式 | Repo 地址 |
|---|---|---|---|---|
| k/website | CNCF 社区的基石，云原生的起点 | Hugo | Netlify | https://github.com/kubernetes/website |
| istio.io | 目前最流行的服务网格 | Hugo | Netlify | https://github.com/istio/istio.io |
| opentelemetry.io | 收集和导出分布式系统可观测数据的开源工具集 | Hugo | Netlify | https://github.com/open-telemetry/opentelemetry.io |
| vLLM | 一个高效的开源库，用于加速大语言模型的推理性能 | Sphinx | Read the Docs | https://github.com/vllm-project/vllm |
| Pytorch | star 87k，一个开源的深度学习框架，广泛用于研究和生产环境中，以其动态计算图和易用性著称 | Hugo | 未指定 | https://github.com/pytorch/pytorch |
| huggingface | star 140k，汇总了全世界的大模型 | Docusaurus | .github/workflows | https://github.com/huggingface/transformers |
| KWOK | DaoCloud 捐献给 kubernetes-sigs 的模拟测试项目 | Hugo | Netlify | https://github.com/kubernetes-sigs/kwok |
| Kueue | DaoCloud 与 kubernetes-sigs 联合维护的 Kubernetes 原生的 Job 排队管理器 | Hugo | Netlify | https://github.com/kubernetes-sigs/kueue |
| LWS | DaoCloud 与 kubernetes-sigs 联合维护，无缝兼容 vLLM、SGLang 等主流架构，一键部署企业级 AI 服务 | 无 | Netlify | https://github.com/kubernetes-sigs/lws |
静态生成器对比¶
仅列出一些上文提及的静态生成器：
| 项目名称 | Star 数量 | 编写语言 | 开源时间 | 体量大小 | Repo 地址 |
|---|---|---|---|---|---|
| Hugo | 78.1k | Go | 2014 年 | 超轻量级，极快 | Hugo repo |
| MkDocs | 19.9k | Python | 2014 年 | 轻量级 | MkDocs repo |
| Docusaurus | 58.4k | React | 2017 年 | 中等，依赖 React | Docusaurus repo |
| Sphinx | 6.8k | Python | 2008 年 | 中等，功能强大 | Sphinx repo |
构建方式对比¶
| 构建方式 | 优点 | 缺点 |
|---|---|---|
| GitHub Pages | ✅ 免费托管，适合开源项目 ✅ 与 GitHub 仓库深度集成，自动部署 ✅ 支持 Jekyll，可直接渲染 Markdown 文件 |
❌ 仅支持静态网站，功能较单一 ❌ 自定义域名需手动配置 HTTPS ❌ CI/CD 能力有限，难以满足复杂部署需求 |
| Netlify | ✅ 支持自动化 CI/CD，构建、预览、部署一体化 ✅ 绑定 Git 仓库，支持多种静态站点生成器 ✅ 提供 Serverless Functions，可支持动态功能 |
❌ 免费额度有限，流量或构建超出需付费 ❌ 部署日志较简洁，调试复杂构建问题时可能不够直观 ❌ 需要额外配置 DNS 以充分利用 Edge Network |
| Cloudflare Pages | ✅ 全球 CDN 加速，特别适合国内用户 ✅ 内置 DDoS 防护，安全性高 ✅ 支持 Pages Functions，可结合 Workers 运行动态逻辑 |
❌ 免费版功能有限，部分高级功能需订阅付费方案 ❌ 部署过程较 Netlify 复杂，需手动配置构建和路由 ❌ 部分第三方插件或工具兼容性较差 |
开源站点常见 Bot¶
在 GitHub 上的开源项目（如 Kubernetes 和 Transformers）中，常见的机器人（bots）用于自动化 CI/CD、代码质量检查、发布管理等。以下是一些常见的 bot 及其用途：
| 分类 | Bot 名称 | 功能描述 |
|---|---|---|
| 代码质量 & Lint | GitHub Actions Bots | 运行 black、flake8、eslint、prettier 等 lint 任务，确保代码风格一致 |
| LGTM Bot | 分析代码质量，检测潜在的安全漏洞 | |
| Codecov Bot | 检查测试覆盖率，并在 PR 中提供覆盖率变化的报告 | |
| Prettier Bot | 自动格式化 JavaScript、Markdown 等文件，保持代码风格一致 | |
| PR & Issue 管理 | k8s-ci-robot（Prow） | Kubernetes 及 CNCF 生态常用，自动管理 PR、CI/CD 任务 |
| Stale Bot（probot-stale） | 自动关闭长期未活动的 Issue 和 PR，保持项目整洁 | |
| CLAassistant Bot | 检查贡献者是否签署了贡献者许可协议（CLA） | |
| welcome Bot（probot-welcome） | 对新贡献者的首个 PR 发送欢迎信息 | |
| 版本管理 & Release | Release Drafter | 自动生成 Release Notes，归类 PR 变更 |
| Semantic Release | 根据 commit 信息自动管理版本号，并发布新版本 | |
| Dependabot | 检测依赖项是否有更新，并自动创建 PR 进行升级 | |
| 安全 & 依赖管理 | Snyk Bot | 扫描项目的依赖项，检测安全漏洞 |
| GitHub Security Bot（Security Alerts） | 自动提醒安全漏洞，并建议修复方案 |
这些 Bot 大多基于 GitHub Actions 或 Prow，可用于提升项目的自动化程度、代码质量和安全性。
开源站点运营思考¶
吸引贡献者的一些举措：
- 构建 Mentor 体系，培训贡献者成长
- 为优秀贡献者提供 d.run 等试用的时间和权限
- 评选公司外部的年度贡献者，并给予 Badge 或试用奖励
- 定期组织线上线下开源会议，邀请贡献者参与，交流开源技术，拓展人脉资源
文档是拓展开源影响力的重要组成，参见 2024 中国开源年度报告和 2024 年度中国企业黑马 DaoCloud 的解读。
开源贡献¶
在开源社区，贡献不仅仅局限于代码，还包括文档、测试、用户反馈等多个方面。 以下是一些主要的贡献方式，以及如何有效地参与到开源项目中。
文档贡献¶
| 贡献类型 | 具体操作 |
|---|---|
| 新编文档 | 翻阅 Issue、Release notes，了解最近的文档需求 |
| 修复错误 | 发现文档中的错别字、格式问题或过时信息，直接提交 PR 进行修复 |
| 改进可读性 | - 通过增加示例、优化表述方式，使文档更加易读和易用 |
| - 采用 Markdown 等格式，提高排版质量 | |
| 本地化 | - 参与项目的 i18n（国际化）工作，贡献多语言版本的文档 |
| - 例如 Kubernetes、Istio 等项目都设有不同语言的 SIG（Special Interest Group） |
社区互动也是一种贡献¶
| 贡献类型 | 具体操作 |
|---|---|
| 回答问题 | - 在 GitHub Discussions、Slack、论坛、微信群等地方，帮助解答新手问题 |
| - 贡献 FAQ（常见问题解答），降低维护者的支持成本 | |
| 组织和参与活动 | - 参与线上或线下的开源会议，例如 KubeCon、Open Source Summit |
| - 组织 meetup、workshop，推广项目和分享经验 |
贡献奖励机制¶
为了激励贡献者，开源项目通常会设置奖励机制，如：
- 贡献者徽章（Badge）：如 CNCF 的贡献者认证
- T-shirt & 周边：许多开源项目会赠送纪念品给活跃贡献者
- Mentor 计划：为新手贡献者提供指导，加速成长
- 优先访问权限：如 d.run 等云服务可为活跃贡献者提供试用额度
如何开始？¶
| 步骤 | 描述 |
|---|---|
| 选择感兴趣的项目 | 关注 CNCF Landscape、GitHub Trending，找到与你的技术栈匹配的项目 |
| 阅读贡献指南 | 每个开源项目通常都有 CONTRIBUTING.md，阅读并遵循贡献流程 |
| 加入社区 | 订阅邮件列表、加入 Slack / Discord、参与定期会议 |
| 从小任务开始 | 先贡献文档、小 bug 修复，逐步熟悉项目 |
| 持续贡献 | 通过多次贡献建立信誉，成为项目的长期贡献者，甚至晋升为 Maintainer |
开源贡献不仅能提升技术能力，还能拓展人脉，为职业发展打开更多机会。希望更多开发者加入开源社区，共同推动技术进步！
写在最后，开源文档站不仅能扩大企业的影响范围，还能促进产品和文档的自我优化和演进。 在透明、开放的环境下，用户和开发者可以直接反馈问题，推动改进，甚至贡献内容，使文档更具时效性和实用性。 同时，一个活跃的开源文档站点也能帮助企业建立更紧密的社区联系，增强用户粘性，形成良性的技术生态。 唯有持续更新、紧跟行业动态，才能确保文档的生命力，使产品保持长期的竞争力和影响力。