Pipewright

Pipewright 文档

v2.4.3

安装自托管实例、运行第一条流水线,再按场景配置部署与权限。

快速开始

用 Compose 体验控制台

准备 Docker 和 Compose。将以下两个配置文件保存到同一个空目录,把 .env.example 复制为 .env。设置自己的管理员密码、填入 openssl rand -base64 32 生成的主密钥,并将 PIPEWRIGHT_VERSION 设为 2.4.3。保存主密钥和持久化卷,后续恢复凭据需要它们。

docker compose up -d
docker compose ps

在浏览器打开 http://localhost:8080,用户名是 admin,密码使用刚刚设置的值。当 docker compose ps 显示服务正在运行,且能进入控制台,启动验证即完成。想验证实际脚本输出,请走下方 Linux 路径。

在 Linux 上启动真实构建

准备带 Bash、curl、OpenSSL 和 Docker 的 Linux 主机,并确认运行 Pipewright 的账号能执行 docker info。下列命令在 Bash 中运行,PIPEWRIGHT_BUILDER=real 会在缺少容器 CLI 时报告错误。

curl -fsSLo install-pipewright.sh \
  https://raw.githubusercontent.com/huangchengsir/pipewright/v2.4.3/install.sh
VERSION=v2.4.3 INSTALL_DIR="$HOME/.local/bin" sh ./install-pipewright.sh

umask 077
mkdir -p .pipewright
test -s .pipewright/master.key || openssl rand -base64 32 > .pipewright/master.key
read -rsp '首次登录密码: ' PIPEWRIGHT_ADMIN_PASSWORD
printf '\n'
PIPEWRIGHT_ADMIN_PASSWORD="$PIPEWRIGHT_ADMIN_PASSWORD" \
PIPEWRIGHT_MASTER_KEY_FILE="$PWD/.pipewright/master.key" \
PIPEWRIGHT_ADDR=127.0.0.1:8080 \
PIPEWRIGHT_BUILDER=real \
  "$HOME/.local/bin/pipewright"

启动后访问 http://127.0.0.1:8080,用 admin 和刚输入的密码登录,然后运行示例流水线。已有实例占用 8080 时,可为新实例选择另一个端口。后续启动继续使用同一工作目录和主密钥。

运行第一条流水线

  1. 准备一个自己可访问的测试 Git 仓库,把 示例 YAML 保存成仓库根目录的 .pipewright.yml 并提交。
  2. 在 Pipewright 新建项目,填仓库地址和分支。私有仓库先在凭据保险库添加并绑定仓库凭据。
  3. 进入项目的流水线页,启用「流水线即代码」,保存后手动运行。
  4. 在运行详情打开脚本节点日志,确认出现 Hello from Pipewright。如实际脚本未执行,先核对运行日志中的构建器以及选中的分支。

流水线 YAML

项目启用流水线即代码后,读取本次构建分支仓库根目录中的 .pipewright.yml。文件缺失或无法解析时,使用项目已保存的画布配置。以下示例使用 Alpine 脚本镜像。

version: 1
stages:
  - id: checkout
    name: 拉取代码
    kind: source
    jobs:
      - name: Git 源
        type: git_source
  - id: verify
    name: 验证
    kind: build
    needs: [checkout]
    jobs:
      - name: 运行脚本
        type: script
        script:
          image: alpine:3
          commands:
            - echo 'Hello from Pipewright'
字段用途
version配置格式版本,此处使用 1。
stages[].id / needs阶段标识与依赖。needs 引用阶段 ID。
kind / jobs[].type阶段类别与任务类型。示例使用 source、build、git_source 和 script。
script.image / commands脚本容器镜像与要运行的命令,可选 workdir 和 env。
gate / when.branches阶段审批开关与分支过滤,完整写法见 README。

触发规则、项目变量和缓存、环境与凭据仍在项目设置里管理。敏感值在平台中配置,提交的 YAML 使用引用或占位符。

完整版 YAML 与流水线上下文

查看流水线变更历史

打开项目的「流水线配置 → 变更历史」,选中一条保存记录,可查看操作者、保存时间和节点差异。命令、变量值及受保护配置只显示修改提示。

在运行详情中选择「查看画布版本」,可以回到当次运行采用的画布记录。来自仓库的流水线继续显示 YAML 来源。

选择可载入的旧版本,点击「从此版本创建草稿」。在画布核对内容后点击「保存配置」才会应用。没有可用快照或包含无法安全还原的配置时,可参照差异在画布中修改。

部署方式

SSH 部署

在凭据保险库保存 SSH 凭据,在「服务器」登记并检查目标机连接。给项目配置目标环境和服务器,再把 SSH 部署节点接在构建节点之后。首次发布建议选测试环境并打开节点日志核对实际目标。

通过 SSH 只执行命令

如果镜像已经推送到仓库,目标机也已经准备好 Compose 文件,可以用 YAML 配置 deploy_ssh,把节点的 config.artifactType 设为 command,在 config.restartCommand 写入要在目标机运行的命令。通过节点选择服务器,或在运行时选择已绑定服务器的环境。

- name: 更新目标机服务
  type: deploy_ssh
  config:
    artifactType: command
    restartCommand: |
      set -e
      cd /opt/myapp
      docker compose pull
      docker compose up -d

这是部署阶段 jobs 下的节点片段。command 模式不上传产物,命令退出码非零时该目标会失败。应用仍需确认镜像仓库权限和部署后的健康状态。v2.4.3 的画布下拉框暂未提供这一模式,请用「从 YAML 导入」或仓库中的 .pipewright.yml 配置。

Docker 镜像部署

在有真实容器执行器的环境中构建镜像,并配置镜像仓库和推送节点。由目标机拉取待部署的镜像。优先使用本次构建的明确版本标识,便于从运行详情追溯实际部署内容。

把构建生成的镜像交给部署节点

使用「构建镜像 → 推送镜像 → SSH 部署」,让部署依赖推送所在阶段,部署产物类型设为「镜像」。推送节点将本次推送结果登记为镜像产物,部署可以直接使用该镜像引用。如果有多个镜像,在「产物来源」指定对应节点和产物。

同一阶段内,脚本可把 KEY=VALUE 追加到 $PIPEWRIGHT_ENV,供下游脚本读取。这个变量机制不能直接把脚本动态算出的 tag 交给另一个阶段的 SSH 部署配置。若要自己写部署命令,且 tag 在触发时已知,可以定义运行参数 IMAGE_TAG,在「重启 / 切换命令」中引用 {{IMAGE_TAG}}。

Kubernetes 部署

配置 Kubernetes 凭据和连接,核对命名空间、执行位置以及项目的部署授权。部署节点按场景选择更新现有工作负载镜像或使用发布套件,并用运行回执查看结果。

Kubernetes 发布套件 · 发布护航

环境变量

变量作用默认或取值
PIPEWRIGHT_ADDRHTTP 监听地址:8080
PIPEWRIGHT_ADMIN_PASSWORD首次启动管理员密码首次启动时设置
PIPEWRIGHT_MASTER_KEY
PIPEWRIGHT_MASTER_KEY_FILE
凭据保险库主密钥或密钥文件32 字节密钥,以 Base64 保存
PIPEWRIGHT_BUILDER容器构建方式auto 自动发现,real 要求可用 CLI,stub 使用模拟构建
PIPEWRIGHT_PUBLIC_URL反代后的外部访问地址,用于 webhook 和 OAuth 回调等按实例填写
PIPEWRIGHT_DB_DRIVER数据库驱动sqlite,也可选 mysql、postgres、sqlserver 或选配的 dm
PIPEWRIGHT_DB
PIPEWRIGHT_DB_DSN
SQLite 数据库文件路径或其他数据库连接串pipewright.db 或按引擎填写 DSN
PIPEWRIGHT_MULTI_TENANT启用团队与权限首次安装默认关闭,设 true 启用
PIPEWRIGHT_OPS_CHAT_MODELSAI 运维助手可选择的额外模型用逗号分隔,最多 31 个。同一 AI 连接,重启后生效。默认只使用已配置的模型。
PIPEWRIGHT_PAC_RUNTIME为所有项目强制使用流水线即代码默认关闭,设 1 开启

使用 Compose 时,应用环境变量需要由 Compose 的 environment 或 env_file 传入容器。变更部署参数后,按部署方式重启服务或重新创建容器。

完整配置说明 · 数据库连接与迁移

更多专题

Dockerfile 构建

将 Dockerfile 提交到仓库,用真实容器执行器运行镜像构建节点。构建上下文和 Dockerfile 路径都应匹配本次检出的代码。

查看镜像部署 · 查看构建缓存说明

配置通知

在设置中创建通知渠道并绑定事件,或在流水线添加通知节点。首次配置可以用测试运行确认失败或成功消息能送达。

查看渠道和通知节点说明

AI 运维助手与模型选择

在容器或服务器的运维助手中选择排查对象,再输入问题。设置中配置的模型会作为默认选项,额外模型由 PIPEWRIGHT_OPS_CHAT_MODELS 启用,并使用同一 AI 连接和凭据。切换模型只影响下一次请求,历史回答保留当时的模型名称。

回滚部署

在对应环境的部署历史中核对当前版本,从可回滚的成功发布记录发起回滚,再查看运行和环境中的版本状态。

查看发布护航报告说明