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 时,可为新实例选择另一个端口。后续启动继续使用同一工作目录和主密钥。
运行第一条流水线
- 准备一个自己可访问的测试 Git 仓库,把 示例 YAML 保存成仓库根目录的
.pipewright.yml并提交。 - 在 Pipewright 新建项目,填仓库地址和分支。私有仓库先在凭据保险库添加并绑定仓库凭据。
- 进入项目的流水线页,启用「流水线即代码」,保存后手动运行。
- 在运行详情打开脚本节点日志,确认出现
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 来源。
选择可载入的旧版本,点击「从此版本创建草稿」。在画布核对内容后点击「保存配置」才会应用。没有可用快照或包含无法安全还原的配置时,可参照差异在画布中修改。
部署方式
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 凭据和连接,核对命名空间、执行位置以及项目的部署授权。部署节点按场景选择更新现有工作负载镜像或使用发布套件,并用运行回执查看结果。
环境变量
| 变量 | 作用 | 默认或取值 |
|---|---|---|
PIPEWRIGHT_ADDR | HTTP 监听地址 | :8080 |
PIPEWRIGHT_ADMIN_PASSWORD | 首次启动管理员密码 | 首次启动时设置 |
PIPEWRIGHT_MASTER_KEYPIPEWRIGHT_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_DBPIPEWRIGHT_DB_DSN | SQLite 数据库文件路径或其他数据库连接串 | pipewright.db 或按引擎填写 DSN |
PIPEWRIGHT_MULTI_TENANT | 启用团队与权限 | 首次安装默认关闭,设 true 启用 |
PIPEWRIGHT_OPS_CHAT_MODELS | AI 运维助手可选择的额外模型 | 用逗号分隔,最多 31 个。同一 AI 连接,重启后生效。默认只使用已配置的模型。 |
PIPEWRIGHT_PAC_RUNTIME | 为所有项目强制使用流水线即代码 | 默认关闭,设 1 开启 |
使用 Compose 时,应用环境变量需要由 Compose 的 environment 或 env_file 传入容器。变更部署参数后,按部署方式重启服务或重新创建容器。
更多专题
Dockerfile 构建
将 Dockerfile 提交到仓库,用真实容器执行器运行镜像构建节点。构建上下文和 Dockerfile 路径都应匹配本次检出的代码。
配置通知
在设置中创建通知渠道并绑定事件,或在流水线添加通知节点。首次配置可以用测试运行确认失败或成功消息能送达。
AI 运维助手与模型选择
在容器或服务器的运维助手中选择排查对象,再输入问题。设置中配置的模型会作为默认选项,额外模型由 PIPEWRIGHT_OPS_CHAT_MODELS 启用,并使用同一 AI 连接和凭据。切换模型只影响下一次请求,历史回答保留当时的模型名称。
回滚部署
在对应环境的部署历史中核对当前版本,从可回滚的成功发布记录发起回滚,再查看运行和环境中的版本状态。
- 团队与权限,包括部署开关、员工、角色与第三方登录。
- 构建缓存,介绍多种语言的依赖缓存配置。
- MCP 接入,介绍连接、令牌和权限。
- English README · v2.4.3 发行说明