screwdrivercd/guide

Screwdriver 文档指南

Screwdriver CD服务的文档

Screwdriver是一个自包含、可插件化的服务，帮助使用最新容器化技术构建、测试和持续交付软件。其文档（Screwdriver Guide）由Jekyll驱动，支持通过Docker或本地安装两种方式运行Jekyll以预览和编辑文档。

核心功能与特性

• 基于Jekyll构建，支持Screwdriver CD服务文档的渲染与预览
• 容器化运行方式，无需本地配置Ruby、Jekyll等依赖环境
• 支持文档实时预览，方便编辑与调试
• 支持多语言文档查看（如日语等）
• 提供便捷的文档贡献流程，支持添加新文档和更新目录结构

使用场景

• Screwdriver CD服务文档的本地开发与预览
• 文档贡献者编辑、测试和预览文档变更
• 开发团队查阅Screwdriver的配置指南、API文档和使用教程

使用方法

前提条件

• 安装Docker Desktop（适用于Docker运行方式）

使用Docker运行Jekyll

1. 安装Docker Desktop
   若尚未安装，从Docker官网下载并安装Docker Desktop。

2. 验证Docker运行状态
   执行docker info命令检查Docker是否正常运行。若未运行，在macOS上可通过命令行启动：

   bash
   open -a /Applications/Docker.app/
   

   命令行启动可导出$SSH_AUTH_SOCK，确保ssh-agent正常工作（如需使用SSH相关功能）。

3. 运行Jekyll Docker镜像
   通过以下命令启动容器，挂载当前目录并映射端口，以运行文档服务：

   bash
   docker run -v $PWD:/srv/jekyll:rw -p 4080:4000 -it jekyll/jekyll jekyll serve --source docs --destination _site
   

   • 参数说明：
     • -v $PWD:/srv/jekyll:rw：将当前目录（$PWD）挂载到容器内的/srv/jekyll目录，支持读写
     • -p 4080:4000：将容器的4000端口映射到本地4080端口，用于访问文档服务
     • -it：交互式终端模式，支持通过Ctrl+C终止服务
     • jekyll serve --source docs --destination _site：启动Jekyll服务，指定文档源目录（docs）和输出目录（_site）

本地查看文档

启动Jekyll服务后，通过浏览器访问以下地址预览文档：

• 默认语言文档：[***]
• 多语言文档：访问http://127.0.0.1:4080/:lang/，例如日语文档：[***]

优化Docker运行效率（频繁构建场景）

若需频繁重建文档，可通过以下步骤缓存依赖，加速后续构建：

1. 首次运行时不使用--rm参数，保留容器：

   bash
   docker run -v $PWD:/srv/jekyll:rw -p 4080:4000 -it jekyll/jekyll jekyll serve --source docs --destination _site
   

2. 提交容器为镜像，保存已安装的依赖：

   bash
   docker commit $(docker ps -q -a | head -n 1) cached-jekyll
   

3. 使用缓存镜像运行（依赖已预安装，启动更快）：

   bash
   docker run --rm -v $PWD:/srv/jekyll:rw -p 4080:4000 -it cached-jekyll jekyll serve --source docs --destination _site
   

本地查看文档

启动服务后，通过浏览器访问以下地址预览文档：

• 英文文档：[***]
• 多语言文档：访问http://127.0.0.1:4080/:lang/，例如日语文档：[***]

添加文档

1. 在docs目录的文件夹结构中添加新的Markdown文档
2. 在docs/_data/menu.yaml的目录树中添加对应条目

文档结构

• 首页
  • 各部分说明
• 集群管理（面向Screwdriver管理员）
  • 整体架构
  • 配置API
    • SCM插件
    • 数据存储插件
  • 配置UI
  • 配置存储
    • 日志插件
  • 配置队列服务
  • 本地运行
  • 配置构建
  • 示例
    • Kubernetes设置
  • 调试
• 用户指南
  • 快速入门
  • API
  • 认证与授权
  • 配置
    • 整体YAML
    • 元数据
    • 密钥
  • 模板
  • 常见问题
• 关于
  • 什么是Screwdriver？
  • 附录
    • 领域模型
    • 执行引擎
  • 贡献指南
  • 支持