@xingyanpo/deplix

🚀 Deplix

关于 Deplix

Deplix 是一个自托管的 CI/CD 工具，通过 Web 面板管理前端项目的自动化部署。采用步骤化流水线设计——将部署过程拆解为可独立配置的步骤，支持拖拽排序和自定义扩展。

核心特性

• 🧩 步骤化部署 — 11 个内置步骤类型，按需组合
• 🎯 预设模板 — 内置 Next.js / Vue-Vite / React-Vite / Nuxt / 静态站点
• 🔧 自定义步骤 — Web 面板编写 Shell 脚本，注册为可复用的步骤
• 🔗 Webhook 驱动 — GitHub + Gitee Push 自动触发部署
• 📊 实时日志 — SSE 流式推送，部署过程实时可见
• 🔒 账号认证 — 面板需登录访问，支持修改密码
• 🖥️ 守护进程 — Linux 下后台运行，关闭终端不中断（类似 pm2）
• ⚡ 运行时管理 — 自动下载/切换 Node.js 和 Bun 版本
• 🗄️ SQLite 数据库 — 零配置，数据存放于 deplix-data/ 目录

技术栈

快速开始

环境要求

Deplix 的运行时是 Bun，不是 Node.js。

说明：Deplix 通过 npm 发布（@xingyanpo/deplix），npm 仅作为包注册中心负责下载。实际运行依赖 Bun，因为代码使用了 Bun.spawn()、Bun.serve()、bun:sqlite 等 Bun 专属 API。

# 安装 Bun（≥ 1.1.0）
curl -fsSL https://bun.sh/install | bash    # macOS / Linux
powershell -c "irm bun.sh/install.ps1 | iex" # Windows

# 验证
bun --version

另外需要 Git 用于拉取部署项目的代码。

安装

npm install @xingyanpo/deplix -g

启动

# 基本启动（默认端口 5120，后台守护运行）
deplix start

# 指定端口 + 账号密码
deplix start -p 9090 -u admin -P mypassword

# 前台运行（调试用）
deplix start --foreground

# 自定义数据目录
deplix start -d /var/lib/deplix

启动后访问 http://<服务器IP>:<端口>，输入设置的账号密码登录。

# 查看状态
deplix status

# 停止服务
deplix stop

初始化项目配置

在你的前端项目根目录执行：

deplix init              # 自动检测项目类型
deplix init -t nextjs    # 指定类型：nextjs / vue-vite / react-vite / nuxt

生成 deplix.config.ts 文件，部署时自动读取。

CLI 命令参考

# 启动服务
deplix start                              # 默认 :5120，后台守护运行
deplix start -p 9090                      # 指定端口
deplix start -H 0.0.0.0                   # 绑定 IP
deplix start -u admin -P mypassword       # 设置登录账号密码
deplix start -d /var/lib/deplix           # 数据目录
deplix start --foreground                 # 前台运行（调试）

# 停止服务
deplix stop                               # 停止守护进程
deplix stop -d /path/to/data              # 指定数据目录

# 查看状态
deplix status                             # 检查默认端口
deplix status -p 9090                     # 检查指定端口

# 初始化项目
deplix init                               # 自动检测项目类型
deplix init -t nextjs                     # 指定项目类型

守护进程行为

• Linux：默认后台守护运行，关闭终端不中断。日志写入 <data-dir>/deplix.log
• Windows：默认前台运行（不支持守护进程）

认证系统

默认账号

首次启动时，系统使用以下默认凭据：

• 用户名：admin
• 密码：admin

⚠️ 安全建议：首次登录后立即修改密码！

自定义凭据

deplix start -u myuser -P Str0ngP@ss

修改密码

登录 Web 面板 → 「系统设置」→ 「修改密码」，输入当前密码和新密码即可。修改后需重新登录。

认证流程

1. 访问面板 → 显示登录页
2. 输入用户名密码 → 获取 Token
3. 后续请求自动携带 Authorization: Bearer <token>
4. Token 过期或无效 → 自动跳回登录页

使用指南

1. 创建部署

1. 登录 Web 面板 → 「部署管理」→ 「新建部署」
2. 填写部署名称和 Git 仓库地址（支持 GitHub / Gitee）
3. 选择预设模板，系统自动填充步骤列表
4. 拖拽调整步骤顺序，按需新增或删除步骤
5. 点击「创建部署」

2. 配置 Webhook（自动部署）

1. 进入「Webhook」页面，复制生成的 URL 和 Secret

2. 在 Git 平台配置：

   GitHub：Settings → Webhooks → Add webhook

   • Payload URL: http://<IP>:<端口>/api/webhooks/github
   • Content type: application/json
   • Secret: 粘贴面板中的密钥

   Gitee：管理 → WebHooks → 添加

   • URL: http://<IP>:<端口>/api/webhooks/gitee
   • 密码: 粘贴面板中的密钥

3. Push 代码即可自动触发部署

3. 手动触发

部署详情页 → 点击「部署」→ 实时查看日志输出。

4. 管理运行时版本

「系统设置」→「安装版本」→ 选择 Node.js 或 Bun → 下拉选择版本号（自动从官方 API 获取，包含 latest 最新版）。

5. 管理部署预设

「部署预设」→ 查看系统预设或创建自定义预设。自定义预设可自由组合步骤顺序，保存后在创建部署时直接选用。

6. 自定义步骤

「步骤管理」→「新建自定义步骤」→ 编写 Shell 脚本 → 保存后在部署步骤中选用。

脚本可用环境变量：

示例 — 清理缓存：

#!/bin/bash
rm -rf $DEPLIX_DEPLOY_DIR/node_modules/.cache
rm -rf $DEPLIX_DEPLOY_DIR/.next/cache
echo "缓存清理完成!"

项目配置

在项目根目录的 deplix.config.ts 中覆盖默认行为：

import { defineDeplixConfig } from '@xingyanpo/deplix'

export default defineDeplixConfig({
  // 运行时
  runtime: 'node',          // 部署目标: 'node' | 'bun'
  nodeVersion: '20.11.0',   // 自动下载指定 Node 版本
  bunVersion: '1.1.0',      // 自动下载指定 Bun 版本

  // 包管理
  packageManager: 'pnpm',   // 'npm' | 'pnpm' | 'yarn' | 'bun'
  installCommand: 'pnpm install',
  buildCommand: 'pnpm build',
  outputDir: '.next',

  // 端口
  port: 3000,

  // PM2
  pm2: {
    name: 'my-app',
    instances: 1,
    maxMemory: '512M',
  },

  // Systemd
  systemd: {
    serviceName: 'my-app',
    description: 'My Application',
  },

  // 钩子
  hooks: {
    beforeInstall: 'echo "开始安装..."',
    afterBuild: 'echo "构建完成"',
    afterDeploy: 'echo "部署成功!"',
  },

  // 环境变量
  env: {
    NODE_ENV: 'production',
  },
})

部署流水线

内置步骤

系统预设

API 参考

公共接口

业务接口（需认证）

认证方式

所有业务接口需携带 Header：Authorization: Bearer <token>

开发指南

面向希望参与 Deplix 开发的贡献者。

环境准备

bun --version   # ≥ 1.1.0
pnpm --version  # ≥ 11.0

git clone https://gitee.com/may-the-world-wu/deplix.git
cd Deplix
pnpm install

常用命令

pnpm dev              # 启动前端 + 后端（均热更新）
pnpm build            # 构建全部 5 个包
pnpm lint             # ESLint 检查
pnpm lint:fix         # ESLint 自动修复
pnpm clean            # 清理构建产物

# 单独启动
pnpm --filter @deplix/server dev   # 后端 :5120
pnpm --filter @deplix/web dev      # 前端 :5173（API 代理到 :5120）

项目结构

Deplix/
├── packages/
│   ├── shared/        # @deplix/shared — 类型、Zod Schema、常量
│   ├── core/          # @deplix/core   — 流水线引擎、步骤、预设
│   ├── server/        # @deplix/server — Hono API、SQLite、SSE
│   ├── web/           # @deplix/web    — React 面板（shadcn/ui）
│   └── cli/           # @xingyanpo/deplix — CLI + npm 发布入口
├── pnpm-workspace.yaml
├── tsconfig.base.json
├── eslint.config.js
└── README.md

发布

pnpm publish:dry      # 预览
pnpm publish:patch    # 补丁版本 (1.0.0 → 1.0.1)
pnpm publish:minor    # 功能版本 (1.0.0 → 1.1.0)
pnpm publish:major    # 大版本   (1.0.0 → 2.0.0)

发布前确保已登录 npm 并设置了 Automation Token：

npm login
npm set //registry.npmjs.org/:_authToken=npm_xxx

架构

 ┌─────────────────────────────────────────┐
 │             Web 面板 (React)              │
 │         shadcn/ui + TailwindCSS          │
 └────────────────┬────────────────────────┘
                  │ REST / SSE
 ┌────────────────▼────────────────────────┐
 │           Hono API Server                │
 │   路由 · Auth · Webhook · SSE · 中间件   │
 └────────────────┬────────────────────────┘
                  │
 ┌────────────────▼────────────────────────┐
 │         Pipeline Engine (Core)           │
 │   Pipeline → Executor → 11 Steps        │
 └────────────────┬────────────────────────┘
                  │
     ┌────────────┼────────────┐
     ▼            ▼            ▼
 ┌──────┐  ┌──────────┐  ┌────────┐
 │ Git   │  │Bun.spawn │  │ SQLite │
 │Clone  │  │ (子进程)  │  │  (DB)  │
 └──────┘  └──────────┘  └────────┘

常见问题

Q: 为什么需要 Bun？

Deplix 使用了 Bun.spawn()、Bun.serve()、bun:sqlite 等 Bun 专属 API，无法在 Node.js 上运行。npm 只负责下载安装。

Q: 如何查看运行日志？

守护进程模式下日志写入 <data-dir>/deplix.log，前台模式下直接输出到终端。

Q: 部署失败如何排查？

1. 进入部署详情页 →「部署日志」查看各步骤输出
2. 检查服务器是否安装了 Git、Node/Bun、PM2/Nginx 等必要工具
3. 确认 deplix.config.ts 中的构建命令与项目实际一致

Q: 如何修改已创建的部署？

部署详情页可编辑步骤配置。如需更换 Git 仓库或预设，建议删除后重新创建。

Q: Webhook 没触发怎么办？

1. deplix status -p <端口> 确认服务在运行
2. 确认 Git 平台的 Webhook 配置中 URL 和 Secret 正确
3. 查看 GitHub/Gitee 的 Webhook 投递记录是否有错误

License

MIT © xingyanpo